For OCaml tools this does essentially nothing useful because the --help output is automatically generated from the options, and so cannot be wrong. However for C tools this is a useful check. It would be nice to generate C tools --help output, but there isn't enough information in the getopt data to do that. This commit also includes fixes to the --help output for a few tools. --- align/scan.c | 1 + df/main.c | 4 ++-- edit/edit.c | 26 +++++++++++++------------- fish/fish.c | 1 + make-fs/make-fs.c | 20 ++++++++++---------- p2v/main.c | 2 +- podcheck.pl | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 7 files changed, 74 insertions(+), 27 deletions(-) diff --git a/align/scan.c b/align/scan.c index 5f1d98a..e7327ea 100644 --- a/align/scan.c +++ b/align/scan.c @@ -87,6 +87,7 @@ usage (int status) " --help Display brief help\n" " -P nr_threads Use at most nr_threads\n" " -q|--quiet No output, just exit code\n" + " --uuid Print UUIDs instead of names\n" " -v|--verbose Verbose messages\n" " -V|--version Display version and exit\n" " -x Trace libguestfs API calls\n" diff --git a/df/main.c b/df/main.c index e04b14e..23cdaee 100644 --- a/df/main.c +++ b/df/main.c @@ -78,12 +78,12 @@ usage (int status) " --csv Output as Comma-Separated Values\n" " -d|--domain guest Add disks from libvirt guest\n" " --format[=raw|..] Force disk format for -a option\n" - " -h|--human-readable Human-readable sizes in --long output\n" + " -h|--human-readable Print sizes in human-readable format\n" " --help Display brief help\n" " -i|--inodes Display inodes\n" " --one-per-guest Separate appliance per guest\n" " -P nr_threads Use at most nr_threads\n" - " --uuid Add UUIDs to --long output\n" + " --uuid Print UUIDs instead of names\n" " -v|--verbose Verbose messages\n" " -V|--version Display version and exit\n" " -x Trace libguestfs API calls\n" diff --git a/edit/edit.c b/edit/edit.c index 2d3ccc6..eb9dfbd 100644 --- a/edit/edit.c +++ b/edit/edit.c @@ -70,20 +70,20 @@ usage (int status) " %s [--options] -d domname file [file ...]\n" " %s [--options] -a disk.img [-a disk.img ...] file [file ...]\n" "Options:\n" - " -a|--add image Add image\n" - " -b|--backup .ext Backup original as original.ext\n" - " -c|--connect uri Specify libvirt URI for -d option\n" - " -d|--domain guest Add disks from libvirt guest\n" - " --echo-keys Don't turn off echo for passphrases\n" - " -e|--expr expr Non-interactive editing using Perl expr\n" - " --format[=raw|..] Force disk format for -a option\n" - " --help Display brief help\n" - " --keys-from-stdin Read passphrases from stdin\n" + " -a|--add image Add image\n" + " -b|--backup .ext Backup original as original.ext\n" + " -c|--connect uri Specify libvirt URI for -d option\n" + " -d|--domain guest Add disks from libvirt guest\n" + " --echo-keys Don't turn off echo for passphrases\n" + " -e|--edit|--expr expr Non-interactive editing using Perl expr\n" + " --format[=raw|..] Force disk format for -a option\n" + " --help Display brief help\n" + " --keys-from-stdin Read passphrases from stdin\n" " -m|--mount dev[:mnt[:opts[:fstype]]]\n" - " Mount dev on mnt (if omitted, /)\n" - " -v|--verbose Verbose messages\n" - " -V|--version Display version and exit\n" - " -x Trace libguestfs API calls\n" + " Mount dev on mnt (if omitted, /)\n" + " -v|--verbose Verbose messages\n" + " -V|--version Display version and exit\n" + " -x Trace libguestfs API calls\n" "For more information, see the manpage %s(1).\n"), guestfs_int_program_name, guestfs_int_program_name, guestfs_int_program_name, guestfs_int_program_name); diff --git a/fish/fish.c b/fish/fish.c index e639d3d..d2cf359 100644 --- a/fish/fish.c +++ b/fish/fish.c @@ -126,6 +126,7 @@ usage (int status) " --echo-keys Don't turn off echo for passphrases\n" " -f|--file file Read commands from file\n" " --format[=raw|..] Force disk format for -a option\n" + " --help Display brief help\n" " -i|--inspector Automatically mount filesystems\n" " --keys-from-stdin Read passphrases from stdin\n" " --listen Listen for remote commands\n" diff --git a/make-fs/make-fs.c b/make-fs/make-fs.c index 42e7e82..8ece991 100644 --- a/make-fs/make-fs.c +++ b/make-fs/make-fs.c @@ -82,16 +82,16 @@ usage (int status) " %s [--options] input.tar.gz output.img\n" " %s [--options] directory output.img\n" "Options:\n" - " --floppy Make a virtual floppy disk\n" - " --format=raw|qcow2|.. Set output format\n" - " --help Display brief help\n" - " --label=label Filesystem label\n" - " --partition=mbr|gpt|.. Set partition type\n" - " --size=size|+size Set size of output disk\n" - " --type=ext4|.. Set filesystem type\n" - " -v|--verbose Verbose messages\n" - " -V|--version Display version and exit\n" - " -x Trace libguestfs API calls\n" + " --floppy Make a virtual floppy disk\n" + " -F|--format=raw|qcow2|.. Set output format\n" + " --help Display brief help\n" + " --label=label Filesystem label\n" + " --partition=mbr|gpt|.. Set partition type\n" + " -s|--size=size|+size Set size of output disk\n" + " -t|--type=ext4|.. Set filesystem type\n" + " -v|--verbose Verbose messages\n" + " -V|--version Display version and exit\n" + " -x Trace libguestfs API calls\n" "For more information, see the manpage %s(1).\n"), guestfs_int_program_name, guestfs_int_program_name, guestfs_int_program_name, guestfs_int_program_name, diff --git a/p2v/main.c b/p2v/main.c index 6d6f555..35f0b59 100644 --- a/p2v/main.c +++ b/p2v/main.c @@ -86,7 +86,7 @@ usage (int status) "Options:\n" " --help Display brief help\n" " --cmdline=CMDLINE Used to debug command line parsing\n" - " --colours Use ANSI colour sequences even if not tty\n" + " --colors|--colours Use ANSI colour sequences even if not tty\n" " --iso Running in the ISO environment\n" " --test-disk=DISK.IMG For testing, use disk as /dev/sda\n" " -v|--verbose Verbose messages\n" diff --git a/podcheck.pl b/podcheck.pl index fca91fb..527a2e4 100755 --- a/podcheck.pl +++ b/podcheck.pl @@ -153,6 +153,17 @@ delete $tool_option_exists{"--color"}; delete $tool_option_exists{"--colour"}; delete $tool_option_exists{"--debug-gc"}; +# Run the tool with --help. +my $help_content; +open PIPE, "LANG=C $tool --help |" + or die "$progname: $tool --help: $!"; +{ + local $/ = undef; + $help_content = <PIPE>; +} +close PIPE; + +# Do the tests. my $errors = 0; # Check each option exists in the manual. @@ -184,9 +195,43 @@ foreach (sort keys %pod_options) { } } +# Check the tool's --help output mentions all the options. (For OCaml +# tools this is a waste of time since the --help output is generated, +# but for C tools it is a genuine test). +my $help_options_checked = 0; + +my %help_options = (); +$help_options{$_} = 1 foreach ( $help_content =~ /(?<!\w)(-[-\w]+)/g ); + +# There are some help options which we automatically ignore. +delete $help_options{"--color"}; +delete $help_options{"--colour"}; +# "[--options]" is used as a placeholder for options in the synopsis +# text, so ignore it. +delete $help_options{"--options"}; + +foreach (sort keys %tool_option_exists) { + unless ($ignore{$_}) { + unless (exists $help_options{$_}) { + $errors++; + warn "$progname: $tool: option $_ does not appear in --help output\n" + } + } +} + +foreach (sort keys %help_options) { + unless ($ignore{$_}) { + $help_options_checked++; + unless (exists $tool_option_exists{$_}) { + $errors++; + warn "$progname: $tool: unknown option $_ appears in --help output\n" + } + } +} + exit 1 if $errors > 0; -printf "$progname: $tool: checked $tool_options_checked tool options against $pod_options_checked documented options\n"; +printf "$progname: $tool: checked $tool_options_checked tool options, $pod_options_checked documented options, $help_options_checked help options\n"; exit 0; -- 2.7.4