CLI tools usage in documentation is out of sync
Summary
CLI tools usage in documentation is out of sync. See examples below.
BIND version used
current main, commit 9a7d2000
Steps to reproduce
Compare named-compilezone with content of bin/check/named-checkzone.rst.
What is the current bug behavior?
- named-compilezone
Tool prints:
named-compilezone [-djqvD] [-c class] [-f inputformat] [-F outputformat] [-J filename] [-s (full|relative)] [-t directory] [-w directory] [-k (ignore|warn|fail)] [-m (ignore|warn|fail)] [-n (ignore|warn|fail)] [-r (ignore|warn|fail)] [-i (full|full-sibling|local|local-sibling|none)] [-M (ignore|warn|fail)] [-S (ignore|warn|fail)] [-W (ignore|warn)] -o filename zonename [ (filename|-) ]
Man page says:
named-compilezone [-d] [-j] [-q] [-v] [-c class] [-C mode] [-f format] [-F format] [-J filename] [-i mode] [-k mode] [-m mode] [-n mode] [-l ttl] [-L serial] [-r mode] [-s style] [-t directory] [-T mode] [-w directory] [-D] [-W mode] {-o filename} {zonename} {filename}
E.g. -C
is not printed by the tool, and it errors out when specified:
named-compilezone: invalid argument -C
- Another example is
tsig-keygen
:
Tool prints:
tsig-keygen [-a alg] [keyname]
Man page says:
tsig-keygen [-a algorithm] [-h] [-r randomfile] [name]
What is the expected correct behavior?
Well, manpages should be correct :troll:
Possible fixes
I think we could have mechanism to automatically check if usage in man page and in *.rst matches. I imagine it would run all tools in mode which prints usage, grep usage line, and compare it with (somehow tagged) usage line in *.rst
Obvious problems:
- Tools would have to have common way to print usage with options.
- Normalizing formatting from RST to plain text.