Document %workspace% and other token expansions

The `%workspace%` token is mentioned in the user manual under the `--package_path` flag. It would be way easier to find if expansion tokens were documented in a separate section.

It would also be useful to document
- where the expansion tokens are expanded (i.e. which files and flags they are valid in)
- whether there are an other expansion tokens

The description of `%workspace%` is confusing, since it refers to a "Bazel directory", which seems to mean a directory literally named "bazel". I can't find a precise definition of this term, an it is not mentioned in the concepts page. IIUC a workspace would be a directory containing a "WORKSPACE" file, but that doesn't seem to be what this expansion variable means.

Start with the user manual entry for the --package_path flag and the concepts page, then search the repository for %workspace% and other expansion-token handling. Done means adding a discoverable section that lists the tokens, explains where each is valid and expanded, and precisely defines the meaning of %workspace%.

Written by the indexing model from the issue text.