From mboxrd@z Thu Jan 1 00:00:00 1970 From: Goffredo Baroncelli Subject: Re: [PATCH 2/2] add detailed help messages to btrfs command Date: Mon, 11 Jul 2011 20:38:04 +0200 Message-ID: <4E1B430C.3020008@libero.it> References: <201101231339.36599.kario@wit.edu.pl> <201101231342.43637.kario@wit.edu.pl> <4E1B1309.2080408@jan-o-sch.net> Reply-To: kreijack@inwind.it Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Cc: Hubert Kario , linux-btrfs@vger.kernel.org, Hugo Mills To: Jan Schmidt Return-path: In-Reply-To: <4E1B1309.2080408@jan-o-sch.net> List-ID: Hi, all. what about generating the man page on the basis of the btrfs help detailed messages ? My idea is the following: before the function source associated to the command we can put a comment with a detailed help. The comment may be: [...] /*** man:btrfs subvolume create * * btrfs subvolume create * create a new subvolume * * The command [b]btrfs subvolume create[b] is used..... * ***/ void do_create_subvolume(int argc, char **argv) { [...] A script extracts from the comment in the source both: - the text for the man page - the text for the detailed help. So we can reach the following goals: - the help is linked to the code - is less likely to forget to update the message - the man page, the helps are always aligned BR G.Baroncelli On 07/11/2011 05:13 PM, Jan Schmidt wrote: > Hi Hubert, > > I have to admit I did not recognize this patch but now Hugo is forcing > me to use the "detailed help messages" and I've got an improvement to > suggest: > > On 23.01.2011 13:42, Hubert Kario wrote: >> extend the >> >> btrfs --help >> >> command to print detailed help message if available but fallback to >> basic help message if detailed is unavailable >> >> add detailed help message for 'filesystem defragment' command >> >> little tweaks in comments >> >> Signed-off-by: Hubert Kario >> --- >> btrfs.c | 101 ++++++++++++++++++++++++++++++++++++++++++-------------------- >> 1 files changed, 68 insertions(+), 33 deletions(-) >> >> diff --git a/btrfs.c b/btrfs.c >> index b84607a..bd6f6f8 100644 >> --- a/btrfs.c >> +++ b/btrfs.c >> @@ -23,6 +23,9 @@ >> #include "btrfs_cmds.h" >> #include "version.h" >> >> +#define BASIC_HELP 0 >> +#define ADVANCED_HELP 1 >> + >> typedef int (*CommandFunction)(int argc, char **argv); >> >> struct Command { >> @@ -31,8 +34,10 @@ struct Command { >> if >= 0, number of arguments, >> if < 0, _minimum_ number of arguments */ >> char *verb; /* verb */ >> - char *help; /* help lines; form the 2nd onward they are >> - indented */ >> + char *help; /* help lines; from the 2nd line onward they >> + are automatically indented */ >> + char *adv_help; /* advanced help message; from the 2nd line >> + onward they are automatically indented */ >> /* the following fields are run-time filled by the program */ >> char **cmds; /* array of subcommands */ >> @@ -47,73 +52,96 @@ static struct Command commands[] = { >> { do_clone, 2, >> "subvolume snapshot", " [/]\n" >> "Create a writable snapshot of the subvolume with\n" >> - "the name in the directory." >> + "the name in the directory.", >> + NULL >> }, >> { do_delete_subvolume, 1, >> "subvolume delete", "\n" >> - "Delete the subvolume ." >> + "Delete the subvolume .", >> + NULL >> }, >> { do_create_subvol, 1, >> "subvolume create", "[/]\n" >> "Create a subvolume in (or the current directory if\n" >> - "not passed)." >> + "not passed).", >> + NULL >> }, >> { do_subvol_list, 1, "subvolume list", "\n" >> - "List the snapshot/subvolume of a filesystem." >> + "List the snapshot/subvolume of a filesystem.", >> + NULL >> }, >> { do_find_newer, 2, "subvolume find-new", " \n" >> - "List the recently modified files in a filesystem." >> + "List the recently modified files in a filesystem.", >> + NULL >> }, >> { do_defrag, -1, >> "filesystem defragment", "[-vcf] [-s start] [-l len] [-t size] | [|...]\n" >> - "Defragment a file or a directory." >> + "Defragment a file or a directory.", >> + "[-vcf] [-s start] [-l len] [-t size] | [|...]\n" >> + "Defragment file data or directory metadata.\n" >> + "-v be verbose\n" >> + "-c compress the file while defragmenting\n" >> + "-f flush data to disk immediately after defragmenting\n" >> + "-s start defragment only from byte onward\n" >> + "-l len defragment only up to len bytes\n" >> + "-t size minimal size of file to be considered for defragmenting\n" > > Lots of too long lines. > > I don't like to repeat the synopsis passage. How about adding the > general ->help when printing ->adv_help as well? This reduces the need > of duplication. > > To prove my point, looking at the current version in Hugo's integration > branch, your two synopsis lines already got inconsistent regarding the > -c option :-) > >> }, >> { do_set_default_subvol, 2, >> "subvolume set-default", " \n" >> "Set the subvolume of the filesystem which will be mounted\n" >> - "as default." >> + "as default.", >> + NULL >> }, >> { do_fssync, 1, >> "filesystem sync", "\n" >> - "Force a sync on the filesystem ." >> + "Force a sync on the filesystem .", >> + NULL >> }, >> { do_resize, 2, >> "filesystem resize", "[+/-][gkm]|max \n" >> "Resize the file system. If 'max' is passed, the filesystem\n" >> - "will occupe all available space on the device." >> + "will occupe all available space on the device.", >> + NULL >> }, >> { do_show_filesystem, 999, >> "filesystem show", "[|