Am 19.11.2016 um 19:22 schrieb Mauro Carvalho Chehab <mche...@s-opensource.com>:
>> 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
