Update README

README.md

@@ -41,6 +41,9 @@ See the [subdirectory](usage/) for examples.
 
 The grammar is based on [compleat](https://github.com/mbrubeck/compleat/blob/master/README.markdown#syntax)'s one.
 
+A grammar is a series of line terminated by a semicolon (;). Each line (roughly) represents a single variant of
+invoking the command.
+
  * `a b` matches `a` followed by `b`.
  * `a b | c` matches either `a b` or `c`.
  * `[a]` matches zero or one occurrences of `a`.
@@ -66,17 +69,21 @@ Use parentheses to group patterns:
 
 # Roadmap
 
- * Generate grammars automatically from man pages similarly to [how Fish shell is does it](https://github.com/fish-shell/fish-shell/blob/946ecf235c002cff596fbbb2c03f9693c30744da/share/tools/create_manpage_completions.py).
-
- * Show completion hints in ZSH and Fish (Bash does not support them).
+ * Printing of undefined variables as a gentle warning.
 
  * `name ::= expression;` defines a new production that can be referred to from other productions via `<name>`
  syntax. Referring to a production recursively won't be supported as that would take us outside of regular languages.
 
+ * Produce [railroad diagrams](https://github.com/lukaslueg/railroad) to ease grammar development.
+
+ * Automatic completion of standard objects, e.g. <FILE>, <PATH>, etc.
+
+ * Generate grammars automatically from man pages similarly to [how Fish shell is does it](https://github.com/fish-shell/fish-shell/blob/946ecf235c002cff596fbbb2c03f9693c30744da/share/tools/create_manpage_completions.py).
+
+ * Show completion hints in ZSH and Fish (Bash does not support them).
+
  * `name = { shell-command... }` defines a variable that uses a shell command to generate suggested
  completions. The shell command should print one suggested completion per line. The `$COMP_LINE` and
  `$COMP_CWORD` environment will contain the input line and the current word being completed.
 
- * If no value is defined for `name`, then the pattern `<name>` will match any word.
-
  * End-to-end tests that excercise the generation completion scripts and check that they behave properly.

usage/cargo.usage

@@ -1,4 +1,6 @@
-cargo [+toolchain] [<OPTIONS>] [<COMMAND>];
+cargo [+<toolchain>] [<OPTIONS>] [<COMMAND>];
+
+<toolchain> ::= { rustup toolchain list | cut -d' ' -f1 };
 <OPTIONS> ::= [-V | --version] [--list] [--explain <CODE>] [-v | --verbose...] [-q | --quiet] [--color <WHEN>] [--frozen] [--locked] [--offline] [--config <KEY_VALUE>] [-Z <FLAG>] [-h | --help];
 <COMMAND> ::= (build | b) | (check | c) | clean | (doc | d) | new | init | add | remove | (run | r) | (test | t) <TEST_OPTIONS> <TESTNAME> | bench | update | search | publish | install | uninstall;
 <TEST_OPTIONS> ::= [-q | --quiet] [--lib] [--bin [<NAME>]] [--bins] [-v | --verbose]... [--example [<NAME>]] [--color <WHEN>] [--examples] [--frozen] [--test [<NAME>]] [--locked] [--tests] [--bench [<NAME>]] [--offline] [--benches] [--config <KEY=VALUE>] [--all-targets] [-Z <FLAG>] [--doc] [--no-run] [--no-fail-fast] [-p | --package [<SPEC>]] [--workspace] [--exclude <SPEC>] [--all] [-j | --jobs <N>] [--keep-going] [-r | --release] [--profile <PROFILE-NAME>] [-F | --features <FEATURES>] [--all-features] [--no-default-features] [--target <TRIPLE>] [--target-dir <DIRECTORY>] [--manifest-path <PATH>] [--ignore-rust-version] [--message-format <FMT>] [--unit-graph] [--future-incompat-report] [--timings [<FMTS>]] [-h | --help];

usage/darcs.usage

@@ -1,4 +1,4 @@
-darcs help ( ( --debug | --debug-verbose | --debug-http | ( -v | --verbose ) | ( -q | --quiet ) | --standard-verbosity ) | --timings | ( --posthook <COMMAND> | --no-posthook ) | ( --prompt-posthook | --run-posthook ) | ( --prehook <COMMAND> | --no-prehook ) | ( --prompt-prehook | --run-prehook ) ) ... [<DARCS_COMMAND> [DARCS_SUBCOMMAND]] ;
+darcs help ( ( --debug | --debug-verbose | --debug-http | ( -v | --verbose ) | ( -q | --quiet ) | --standard-verbosity ) | --timings | ( --posthook <COMMAND> | --no-posthook ) | ( --prompt-posthook | --run-posthook ) | ( --prehook <COMMAND> | --no-prehook ) | ( --prompt-prehook | --run-prehook ) ) ... [<DARCS_COMMAND> [<DARCS_SUBCOMMAND>]] ;
 darcs add ( --boring | ( --case-ok | --reserved-ok ) | ( ( -r | --recursive ) | --not-recursive ) | ( --date-trick | --no-date-trick ) | --repodir <DIRECTORY> | --dry-run | --umask <UMASK> | ( --debug | --debug-verbose | --debug-http | ( -v | --verbose ) | ( -q | --quiet ) | --standard-verbosity ) | --timings | ( --posthook <COMMAND> | --no-posthook ) | ( --prompt-posthook | --run-posthook ) | ( --prehook <COMMAND> | --no-prehook ) | ( --prompt-prehook | --run-prehook ) ) ... ( <FILE> | <DIRECTORY> )...;
 darcs remove ( --repodir <DIRECTORY> | --umask <UMASK> | ( --debug | --debug-verbose | --debug-http | ( -v | --verbose ) | ( -q | --quiet ) | --standard-verbosity ) | --timings | ( --posthook <COMMAND> | --no-posthook ) | ( --prompt-posthook | --run-posthook ) | ( --prehook <COMMAND> | --no-prehook ) | ( --prompt-prehook | --run-prehook ) ) ... ( <FILE> | <DIRECTORY> )...;
 darcs move ( ( --case-ok | --reserved-ok ) | --repodir <DIRECTORY> | --umask <UMASK> | ( --debug | --debug-verbose | --debug-http | ( -v | --verbose ) | ( -q | --quiet ) | --standard-verbosity ) | --timings | ( --posthook <COMMAND> | --no-posthook ) | ( --prompt-posthook | --run-posthook ) | ( --prehook <COMMAND> | --no-prehook ) | ( --prompt-prehook | --run-prehook ) ) ... <SOURCE> ... <DESTINATION>;