HV Command Reference
generation of the reference
Since the commands share a very similar format, it was decided to use a common
small DSL (domain-specific language) to simplify the input of each command's details.
A command's documentation is described in a .cd file (located in refs.in/),
we then pass it through build.py which will generate a corresponding .md
file (in refs/). This .md file is then included into a larger document.
Syntax of .cd (command doc) files
The order must be respected:
- parameters (if any)
- description
- example(s)
parameters
A parameter represents either an option (e.g. "-a") or an argument (e.g. "//cat.i64") a parameter is split into two parts, the name - which will be used for the synopsis and the text - which will be used for the parameter description
each parameter entry must begin with .
.SITENAME
a parameter can be optional
.[WORKLIST_ID]
the name of a parameter can be composed of multiple tokens
.[-u USERNAME]
The syntax is the following:
regular parameter
.<SINGLE_TOKEN> <description>
."<MULTIPLE TOKENS>" <description>
optional parameter
.[SINGLE_TOKEN] <description>
.[MULTIPLE TOKEN] <description>
Substitutions
Some parameters are heavily shared among commands. Macros were created to enhance their descriptions.
PATH macros
a parameter with $NCAT_VAULT_PATH:<name> <description> will
create a <name> synopsis parameter with an xref to the vault path anchor
and a parameter entry <name>:: <description>
*VAULT_PATH* macros will create an xref to the "paths-vaultpath" anchor
*LOCAL_PATH* macros will create an xref to the "paths-localpath" anchor
VAULT_PATH_WITH_REV will append the [=REVISION] specifier to the name
macros ending in ... will add an ellipsis to the name to indicate that the parameter can be repeated
Description
The description begins with an answer to: "What does the command do?" Following that, it can give more detail on the behaviour of the command.
The description begins right after a line beginning with >
Examples
Examples are meant to display how the command can be used.
Examples start after a line beginning with '!'
A line beginning with $ will be made interpreted as a listing and the $ will be replaced by a prompt string
Conventions
- Parameter descriptions begin with a capital letter and end with a period.