Em Sat, 19 Nov 2016 10:35:07 -0700 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Thu, 17 Nov 2016 08:32:32 -0200 > Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > > > The Kernel documentation guide is currently a single file at the top of > > Documentation/ dir. Sphinx works best if the documentation is > > inside a subdirectory, as otherwise there's no way to have a PDF book > > with its contents, without including everything else. > > > > The first patch on this series address this, by splitting the > > kernel-documentation.rst file into the Documentation/doc-guide dir. > > > > The next two patches add the missing documentation for the > > parse-headers.pl script, responsible to generate cross-references > > between uAPI header files and the Kernel documentation. > > OK, I've applied this series (and merged the result with Daniel's > change). But there's one thing... > > > +.. NOTE: the man pages below were generated using pod2rst tool: > > +.. http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst > > +.. If you need to change anything below this point, please do the changes > > +.. at parse-headers.pl directly, re-run the script and paste the output of > > +.. the script here. > > Here we've just added another generated file to the tree, and, to top it > off, the results are, um, not as pretty as one might like. Yeah, I see your point. > 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. Nothing really prevents us to maintain the contents in separate, but that would make it harder to maintain, as, if we change something, we'll have two files to touch. Yet, I suspect that we won't be doing too much changes there. So, updating any changes on two places won't be hard. We could also add pad2rst to convert it in runtime, but that would require one extra package to be installed for documentation. Assuming that we won't do many changes at the POD content, this sounds overkill to me. Another alternative would be to make the rst content different, for example, running away from the man-pages style and adding more information at the .rst file. What do you prefer? 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
