Re: [PATCH 0/3] Improve Kernel documentation guide

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 19.11.2016 um 19:22 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

>> What are the chances of just making the rst doc be the definitive one
>> and putting a pointer into pod2rst?
> 
> Not sure what exactly you want. IMO, it is useful to be able to
> run the script with --man or --help, and this comes almost for free
> in perl, when de documentation is in POD format. I usually look first
> at the command line help pages than seeking for an application
> documentation elsewhere. 
> 
> That's why I decided to write the documentation using POD. With that,
> you can always get a quick summary of the options with:
> 
> 	$ ./Documentation/sphinx/parse-headers.pl --help
> 	Usage:
> 	    parse_headers.pl [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
> 
> 	    Where <options> can be: --debug, --help or --man.
> 
> 	Options:
> 	    --debug Put the script in verbose mode, useful for debugging.
> 
> 	    --help  Prints a brief help message and exits.
> 
> 	    --man   Prints the manual page and exits.
> 
> And, a more detailed description using --man. Right now --man
> displays an identical content of the part below that comment
> in the rst file, because I used pad2rst for the conversion.

Sorry, IMO this is conceptual wrong.

reST is the base format from which we create other output formats.
Even if we have no man page generation from reST yet, we should not
promote toolchains using language specific markups (POD) as base
format.

So it might be time to investigate some efforts in a 'man'-page 
target. Ask me if I can help.


--Markus--

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux