On 07/11/2011 08:38 PM, Goffredo Baroncelli wrote:
> 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 <path>
> * create a new subvolume
> *
> * The command [b]btrfs subvolume create[b] is used.....
> *
> ***/
>
> void do_create_subvolume(int argc, char **argv)
> {
> [...]
Reminds me of java, but nevertheless, I like the general idea.
> A script extracts from the comment in the source both:
> - the text for the man page
> - the text for the detailed help.
Does anybody have such a script around? I suppose we're not the first
ones writing help texts and man pages.
> 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
Only, we still will need like short and long help. E.g. the full text in
the man page may be inappropriate as a --help message. Also, we do need
a clever idea to get indentation right in the man pages. I fiddled a lot
on the man pages for scrub parameter indentation (to get the second line
describing a command line option indented correctly to start below the
text of the first line, that was).
-Jan
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
