Yeah, the --help docs. But I can always chime in with some code for it -- don't feel pressured to write up and commit all features in one go. Just trying out the looks of how pike -x rsif would shape up here:
class Parser { // The name for now. inherit Arg.OptionsSupreme;
string help_pre = #"pike -x rsif [options] <from> <to> <files>
rsif ("replace string in file") replaces all occurrences of the string <from> with the string <to> in listed files. The name of the files that were changed are written to stdout. Directories may be given instead of files, in which case all the files in that directory will be processed. Available options:";
Arg backups = NoArg("-b")|NoArg("--backups"); string help_backups = "Saves the unaltered file in <filename>~";
Arg recurse = NoArg("-r")|NoArg("--recursive"); string help_recurse = "Processes directories recusively";
Arg verbose = NoArg("-v")|NoArg("--verbose"); string help_verbose = "Writes more junk to stderr.";
Arg quiet = NoArg("-q")|NoArg("--quiet"); string help_quiet = "Writes no output at all.";
Arg version = NoArg("-V")|NoArg("--version"); string help_version = "Writes the version number of rsif.";
Arg help = NoArg("-h")|NoArg("--help"); string help_help = "Shows this help message."; }
for the output:
pike -x rsif [options] <from> <to> <files>
rsif ("replace string in file") replaces all occurrences of the string <from> with the string <to> in listed files. The name of the files that were changed are written to stdout. Directories may be given instead of files, in which case all the files in that directory will be processed. Available options:
-b, --backups Saves the unaltered file in <filename>~ -r, --recursive Processes directories recusively -v, --verbose Writes more junk to stderr. -q, --quiet Writes no output at all. -V, --version Writes the version number of rsif. -h, --help Shows this help message.
I like it. It's a huge gain in readability (and maintainability) from the former code. We could add error() out featuritis for colliding flag names and likely other similar helpful housekeeping too.
Maybe it would make sense letting the *Arg constructors conveniently take an optional docstring argument, instead of the help_* variables:
Arg verbose = NoArg("-v", "Writes more junk to stderr.") | NoArg("--verbose");