continue working on docs (#92)

* prevent horrible colors on terminal.app
* more browser doc tweaks
* remove version from global options
* even out description punctuation

.milpa/commands/itself/command-tree.yaml

@@ -1,6 +1,6 @@
 summary: Prints a tree of known commands
 description: |
-  Prints out command names and descriptions, or optionally all properties as `json` or `yaml`.
+  Prints out command names and descriptions, or optionally a nested representation of all properties of commands, serialized as `json` or `yaml`. Custom textual representations of commands can be obtained by using the `--template` option and specifying a [go-template](https://pkg.go.dev/text/template#hdr-Actions) to be applied to every command. See [chinampa/pkg.Command](https://pkg.go.dev/git.rob.mx/nidito/[email protected]/pkg/command#Command) and [milpa/internal/command.Meta](https://pkg.go.dev/github.com/unrob/[email protected]/internal/command#Meta) for references on the structs available during template rendering.
 
   ## Examples
 
@@ -11,14 +11,14 @@ description: |
   # print a tree of milpa itself sub-commands
   milpa itself command-tree itself
 
-  # print out all commands, skipping groups
-  milpa itself command-tree --template '{{ if (not (eq .Meta.Kind "virtual")) }}{{ .FullName }}'$'\n''{{ end }}'
-
   # get all commands as a json tree
   milpa itself command-tree --output json
 
   # same, but as the yaml representation of this command itself
   milpa itself command-tree --output json itself command-tree
+
+  # print out all commands, skipping groups
+  milpa itself command-tree --template '{{ if (not (eq .Command.Meta.Kind "virtual")) }}{{ .Command.FullName }}'$'\n''{{ end }}'
   ```
 arguments:
   - name: prefix

.milpa/commands/itself/create.yaml

@@ -21,10 +21,10 @@ options:
     description: Open the script file in your current $EDITOR after creation
   executable:
     type: bool
-    description: Create an empty, executable command. Useful when you'd like using something other than bash.
+    description: Create an empty, executable command. Useful when you'd like using something other than bash
   repo:
     type: string
-    description: a path to the milpa repo to create this command in. By default, the nearest .milpa directory from `pwd` and up.
+    description: a path to the milpa repo to create this command in. By default, the nearest .milpa directory from `pwd` and up
     values:
       suggest-only: true
       script: find . -type d -maxdepth 1 && milpa itself repo list --paths-only

.milpa/commands/itself/repo/install.yaml

@@ -11,8 +11,8 @@ description: |
   ### Examples
 
   - `github.com/unRob/milpa` would download the `.milpa` folder from the `unRob/milpa` github repo, using **https**, and prompting for credentials for private repos.
-  - `git::ssh://[email protected]/unRob/milpa.git//internal` would download the `internal/.milpa` folder from the `unRob/milpa` github repo using **ssh credentials**, useful for skipping credential prompts for private repos
-  - `~/.dotfiles` would symlink `$HOME/.dotfiles/.milpa` to the target. An alternative to this is to set `MILPA_PATH` to `$HOME/.dotfiles` (see [`milpa help docs milpa environment`](/.milpa/docs/milpa/environment.md))
+  - `git::ssh://[email protected]/unRob/milpa.git//internal` would download the `internal/.milpa` folder from the `unRob/milpa` github repo using **ssh credentials**, useful for skipping credential prompts for private repos.
+  - `~/.dotfiles` would symlink `$HOME/.dotfiles/.milpa` to the target. An alternative to this is to set `MILPA_PATH` to `$HOME/.dotfiles` (see [`milpa help docs milpa environment`](/.milpa/docs/milpa/environment.md)).
 
 arguments:
   - name: source

.milpa/commands/itself/repo/list.yaml

@@ -1,11 +1,11 @@
 summary: Lists installed repos
 description: |
-  Milpa can install repositories from remote locations at two different locations, depending on how it was instaled.
+  `milpa` installs repositories from remote locations at two different locations:
 
-    - In the `$MILPA_ROOT` (by default, /usr/local/lib/milpa)
-    - In `$XDG_DATA_HOME/milpa` folder
+    - machine-wide repositories are installed to `$MILPA_ROOT`, usually at `/usr/local/lib/milpa`,
+    - user-specific repositories are installed to `$XDG_DATA_HOME/milpa` folder, usually `$HOME/.local/share/milpa/`
 
-  For more information on installing packages, see [`milpa itself repo install --help`](/.milpa/commands/itself/repo/install.md)
+  For more information on installing packages, see [`milpa itself repo install --help`](/.milpa/commands/itself/repo/install.md).
 options:
   paths-only:
     description: Only output the paths to repos with no decoration

.milpa/commands/itself/repo/uninstall.yaml

@@ -1,6 +1,6 @@
 summary: Removes an installed milpa repo
 description: |
-  Uninstalls a milpa repo by PATH. See [`milpa itself repo list --help`](/.milpa/commands/itself/repo/list.md) for a list of available repos
+  Uninstalls a milpa repo by PATH. See [`milpa itself repo list --help`](/.milpa/commands/itself/repo/list.md) for a list of available repos.
 arguments:
   - name: path
     description: The repo path to uninstall

.milpa/docs/milpa/command/index.md

@@ -5,12 +5,12 @@ weight: 15
 description: Commands overview
 ---
 
-`milpa` has two modes for running your scripts:
+`milpa` runs your scripts or executables, by matching passed arguments to files in `.milpa/commands` directories. It looks at a few of these, starting with the one where `milpa` was called from. Check out `MILPA_PATH` of [`milpa help docs milpa environment`](/.milpa/docs/environment.md#MILPA_PATH) to understand where `milpa` looks for **commands**. A collection of commands under a single `.milpa` folder is called a **repo**, and you can learn more reading [`milpa help docs milpa repo`](/.milpa/docs/milpa/repo/index.md)
 
-0. bash scripts, with an `.sh` extension, or
-1. executable files without an extension, written in whatever language you want.
+Your **script** or executable plus its corresponding **spec** is what we call a `milpa` **command**. Scripts can be:
 
-Your **script** or executable plus its corresponding **spec** is what we call a `milpa` **command**. If your command does not have an extension, remember to set the executable bit on (`chmod +x .milpa/commands/your-command`)!
+0. bash scripts, with an `.sh` extension, or
+1. executable files without an extension, written in whatever language you want. If your command does not have an extension, remember to set on the executable bit (`chmod +x .milpa/commands/your-command`)!
 
 ## Spec
 
@@ -55,24 +55,26 @@ echo "$MILPA_OPT_GREETING $(title_case "$name")"
 
 ## Arguments, Options and Environment
 
-The **arguments** and **options** passed in the command line will be parsed and validated according to your spec. If valid, your script will receive numbered arguments as usual (`$1` and so on), without known options. Valid arguments and options will be available to your script as **environment variables** as well.
+The **arguments** and **options** passed in the command line will be parsed and validated according to your spec. If valid, your script will receive numbered arguments as usual (`$1` and so on), excluding any supplied options (i.e. without `--option=value` "arguments"). Valid arguments and options will be available to your script as **environment variables** as well.
+
+> ⚠️ Unknown arguments and options will cause an error before your script executes!
 
 The environment available to a **script** is composed of four groups:
 
-- `MILPA_COMMAND_*` variables have information about the **command** called by the user,
-- `MILPA_ARG_*` variables hold values for every **argument** of the spec,
-- `MILPA_OPT_*` variables hold values for every **option** defined, and
-- [global environment variables](/.milpa/docs/milpa/environment.md) that affect `milpa`'s overall behavior.
+0. `MILPA_COMMAND_*` variables have information about the **command** called by the user,
+1. `MILPA_ARG_*` variables hold values for every **argument** of the spec,
+2. `MILPA_OPT_*` variables hold values for every **option** defined, and
+3. [global environment variables](/.milpa/docs/milpa/environment.md) that affect `milpa`'s overall behavior.
 
 
-### Command: `MILPA_COMMAND_*`
+### Command metadata: `MILPA_COMMAND_*`
 
 Your script has access to the following variables set by `milpa` after parsing arguments and running validations:
 
 - `MILPA_COMMAND_NAME`: the space delimited name of your command, i.e. `db connect`;
 - `MILPA_COMMAND_KIND`: either `source` for `.sh` scripts, or `exec` for executables;
 - `MILPA_COMMAND_REPO`: the path to the repo containing this command, i.e. `/home/you/project/.milpa`; and
-- `MILPA_COMMAND_PATH`: the full path to the executable being called
+- `MILPA_COMMAND_PATH`: the full path to the executable being called.
 
 ### Arguments: `MILPA_ARG_*`
 
@@ -93,7 +95,7 @@ milpa greet elmer homero
 
 ### Options: `MILPA_OPT_*`
 
-**Options** show up on the environment with the `MILPA_OPT_` prefix followed by the name in your spec. Names will be all uppercase, and dashes will be turned into underscores. In the [command spec](/.milpa/docs/milpa/command/spec.md) you'll find more details on how to set **options**.
+**Options** show up on the environment with the `MILPA_OPT_` prefix followed by the name in your spec. Names will be all uppercase, and dashes will be turned into underscores. In the [command spec](/.milpa/docs/milpa/command/spec.md) you'll find more details on how to define **options**.
 
 ```sh
 # when ran like this:
@@ -122,7 +124,7 @@ options:
 if [[ "$MILPA_OPT_SHOUT" ]]; then
   echo "$MILPA_OPT_GREETING $(title_case "$name")!" | awk '{print toupper($0)}'
 else
-  echo "$MILPA_ARG_GREETING $(title_case "${MILPA_ARG_FULL_NAME[*]}")"
+  echo "$MILPA_OPT_GREETING $(title_case "$name")"
 fi
 ```
 

.milpa/docs/milpa/command/spec.md

@@ -85,7 +85,7 @@ arguments:
     # a default may be specified, it'll be passed to your command if none is provided
     default: patch
     # if marked as required, the command won't run unless this argument is provided
-    # An error will result if the argument is bothr required and has a default set
+    # An error will result if the argument is both required and has a default set
     required: true
     # arguments may be variadic, that is, all remaining arguments starting at this position
     # in this case, since there's only one argument, it would mean all arguments after
@@ -106,11 +106,12 @@ The `options` map describes the named options that may be passed to a command. O
 ```yaml
 # options, also known as flags, are specified as a map
 options:
-  # this sets the --scheme option
+  # this creates the --scheme option
   # it will be available to your script as the $MILPA_OPT_SCHEME environment variable
   # and may be specified on the command line as either `--scheme "semver"` or `--scheme=semver`.
   scheme:
-    # options require a description, this will show during completions and on the command's help page
+    # options require a description, this will show during completions
+    # and on the command's help page
     description: Determines the format of the tags for this repo.
     # Sometimes, very commonly used flags might benefit from setting a short name
     # in this case, users would be able to use `-s calver`
@@ -169,3 +170,23 @@ A `values` property may be specified for both arguments and options; `milpa` wil
       # if enabled, will not add a space after suggestions during autocomplete
       suggest-raw: false
 ```
+
+### Value completion script interpolation
+
+[go-template](https://pkg.go.dev/text/template#hdr-Actions) tags may be used within `milpa` and `script` value completions to interpolate already supplied values. The following tags are available:
+
+- `{{ Arg "name" }}`: the value (or default) for the named argument. A map of argument names to their string values is also available at `{{ index Args "name" }}`.
+- `{{ Opt "name" }}`: the value (or default) for the named option. A map of argument names to their string values is also available at `{{ index Opts "name" }}`.
+- `{{ Current }}`: the value currently being auto-completed. On a command line like `milpa song play joão⇥`, `{{ Current }}` would return `joão`.
+
+Additionally, the following Go functions are available:
+
+- `{{ contains "team" "ea" }}`: [`strings.Contains`](https://pkg.go.dev/strings#Contains)
+- `{{ hasSuffix "content" "ent" }}`: [`strings.HasSuffix`](https://pkg.go.dev/strings#HasSuffix)
+- `{{ hasPrefix "content" "con" }}`: [`strings.HasPrefix`](https://pkg.go.dev/strings#HasPrefix)
+- `{{ replace "file.yaml" ".yaml" ".sh" }}`: [`strings.ReplaceAll`](https://pkg.go.dev/strings#ReplaceAll)
+- `{{ toUpper "shout" }}`: [`strings.ToUpper`](https://pkg.go.dev/strings#ToUpper)
+- `{{ toLower "whisper" }}`: [`strings.ToLower`](https://pkg.go.dev/strings#ToLower)
+- `{{ trim " padded " }}`: [`strings.Trim`](https://pkg.go.dev/strings#Trim)
+- `{{ trimSuffix "content" "con" }}`: [`strings.TrimSuffix`](https://pkg.go.dev/strings#TrimSuffix)
+- `{{ trimPrefix "content" "ent" }}`: [`strings.TrimPrefix`](https://pkg.go.dev/strings#TrimPrefix)

.milpa/docs/milpa/environment.md

@@ -57,11 +57,11 @@ By default, when stdout is a TTY, `milpa` will output color escape characters. I
 
 If either `--no-color` or `--color` options are provided, these will override both `COLOR` and `NO_COLOR` environment variables.
 
-### `MILPA_HELP_STYLE` / `MILPA_PLAIN_HELP`
+If `COLORTERM` is set to `truecolor`, 24-bit colors will be used instead of the default 256-color palette.
 
-`MILPA_HELP_STYLE` can be one of `auto`, `dark`, and `light` and specifies the theme to use when rendering help pages. This option has no effect if `--no-color` or `NO_COLOR=1` is specified.
+### `MILPA_HELP_STYLE`
 
-`MILPA_PLAIN_HELP` will not colorize help output at all, formatting help as plain markdown text instead.
+`MILPA_HELP_STYLE` controls the theme to use when rendering help pages, and must be one of `auto`, `dark`, `light`, and `markdown`.
 
 ---