On 07/11/2011 09:11 PM, Jan Schmidt wrote:
> 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.
>
I am trying to write a my own (yes I know, I suffer of the NIH syndrome
:-) ).
>> 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).
I agree for the short and long help. I think that we need to use some
tags for the bold, italic, Empty line...
>
> -Jan
> --
> To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at http://vger.kernel.org/majordomo-info.html
> .
>
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
