Em Mon, 21 Nov 2016 08:48:00 +0100 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > 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. Sorry but I don't agree with you here ;) IMHO, *all* Executable files should have an usage and a help argument that would at least explain the arguments to such script. Even sphinx-build script has it, despite the fact that the more detailed documentation for it is in ReST format. In the case of Perl, the simplest way to do it is to use POD. POD supports two levels of help: a quick summary and a comprehensive one. Both are created from the POD markups inside it, by calling pod2usage($verbose). if $verbose is 1, it provides a quick summary; if $verbose is 2, it provides the complete help, on a format similar to a man page. Making perl read the documentation from a RST file will be an ugly hack, IMHO. > > So it might be time to investigate some efforts in a 'man'-page > target. Ask me if I can help. Generating man pages is something that we need to do anyway. It would be great if you could restart such work. Thanks, Mauro -- 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
