Description
Some command syntaxes are extremely long on the website, for example CLIENT KILL:
CLIENT KILL 〈 old-format | 〈 [ ID client-id ] | [ TYPE normal | master | primary | slave | replica | pubsub ] | [ USER username ] | [ ADDR addr ] | [ LADDR laddr ] | [ SKIPME yes | no ] | [ MAXAGE maxage ] 〉 [ 〈 [ ID client-id ] | [ TYPE normal | master | primary | slave | replica | pubsub ] | [ USER username ] | [ ADDR addr ] | [ LADDR laddr ] | [ SKIPME yes | no ] | [ MAXAGE maxage ] 〉 ... ] 〉
It's a bit hard to read it.
Describe the solution you'd like
In the man pages, there is another rendering, equivalent but shorter:
CLIENT KILL ip:port
CLIENT KILL [<ID client-id | TYPE <NORMAL | MASTER | PRIMARY | SLAVE | REPLICA | PUBSUB> | USER username | ADDR ip:port | LADDR ip:port | SKIPME <YES | NO> | MAXAGE maxage>...]
Differences:
-
When everything after the command and subcommand name is a single "oneof" argument, the syntax can be split into multiple lines, so
COMMAND SUBCOMMAND <old-format | new-format>
becomesCOMMAND SUBCOMMAND old-format
and on a separate lineCOMMAND SUBCOMMAND new-format
. This multiline display is often used on man pages and--help
output of commands, for example this one:SYNOPSIS git diff [<options>] [<commit>] [--] [<path>...] git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...] git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...] git diff [<options>] <commit>...<commit> [--] [<path>...] git diff [<options>] <blob> <blob> git diff [<options>] --no-index [--] <path> <path>
-
ip:port
instead ofold-format
. Just use the"display"
field in the JSON defintion, if it's available. This argument has a JSON definition like this:{ "name": "old-format", "display": "ip:port", "type": "string", "deprecated_since": "2.8.12" },
-
Rewrite to simplify. When an argument has
"type": "oneof"
and not optional, but all of its arguments have"optional": true
, then we can move the optional property to the outer "oneof" argument.< [a] | [b] | [c] > ...
becomes
[ <a | b | c> ... ]
In the CLIENT KILL example, the argument that starts with
〈 [ ID client-id ] | ... 〉
can benefit from this rewrite. -
When a "oneof" that is not optional, it is rendered as
<a | b>
. If this thing also has the"multiple": true
propery, then it's currently rendered as<a | b> [ <a | b> ... ]
, i.e. the whole oneof thing is repeated. This combination often becomes too long to be readable.When I experimented with combinations of "oneof", "multiple", "optional" and "block", I realized that it's good to consider combinations of these and define a syntax for each combinatio. I ended up with the following style, which is what's applied in the suggestion above.
simple foo optional [foo] multiple foo [foo...] multiple + optional [foo...] oneof <foo | bar> oneof + optional [foo | bar] oneof + multiple <foo | bar> [<foo | bar>...] oneof + multiple + optional [<foo | bar>...] block foo bar block + optional [foo bar] block + multiple foo bar [foo bar ...] block + multiple + optional [foo bar [foo bar ...]]
Additional context
-
There's an implementation of all of the above ideas in the Python script
utils/command_syntax.py
in the doc repo. It can be used for inspiration and probably be translated to Zola. -
Redis webpage isn't much better. It renders this command as:
CLIENT KILL <ip:port | <[ID client-id] | [TYPE <NORMAL | MASTER |
SLAVE | REPLICA | PUBSUB>] | [USER username] | [ADDR ip:port] |
[LADDR ip:port] | [SKIPME <YES | NO>] | [MAXAGE maxage]
[[ID client-id] | [TYPE <NORMAL | MASTER | SLAVE | REPLICA |
PUBSUB>] | [USER username] | [ADDR ip:port] | [LADDR ip:port] |
[SKIPME <YES | NO>] | [MAXAGE maxage] ...]>>`.