> Am 27.09.2017 um 13:19 schrieb Jesper Dangaard Brouer <brouer@xxxxxxxxxx>: [...] >>> I would prefer adding a README.rst file, in RST-format, as the rest of >>> the kernel documentation is moving in that direction[1] (your github >>> version is in README.md format). A man page will always be >>> out-of-sync, and even out-of-sync on different distros. >>> >>> See[1]: https://www.kernel.org/doc/html/latest/ >>> >>> And then I would find some place in Documentation/admin-guide/ and >>> include the README.rst file, so it shows up at [1]. >>> >>> RST have an include method like: >>> >>> .. include:: ../../tools/bpf/bpftool/README.rst >> >> Can the docs in new format be rendered into a man page? Call me old >> fashioned but I think we should provide some form of a man page.. :) > > Yes, simply create the man page like: > > rst2man README.rst README.man > You can add this to your local makefile. Hm ... this will work only for simple reST files. FYI: Sphinx is build up on top of docutils extending the reST markup. Tools like rst2man are from docutils and do not cover the markup extensions from Sphinx. Since Sphinx has its own builder for man pages, generating man pages is not the problem ... > The standard sphinx build can also generate man-pages, but it have been > removed from the kernel makefile targets: > > Documentation targets: > Linux kernel internal documentation in different formats from ReST: > htmldocs - HTML > latexdocs - LaTeX > pdfdocs - PDF > epubdocs - EPUB > xmldocs - XML > linkcheckdocs - check for broken external links (will connect to external hosts) > cleandocs - clean all generated files The reason why we have no man page target is, that we have not yet evaluated a concept, how we can manage the 'build man pages' task in the kernel build. Beside what you find in the kernel-source tree I'am working on such a concept (adapted man page builder for the Kernel) [1]. IMO: Even if we merge the builder from [1] or implement something different, we have to touch the current kernel-doc parser. I guess that and the absence of a handy concept is the reason why we are dangling with a 'man' target. Anyway, these are my estimations, it might be better if we hear what Jon think about a man page builder (concept). [1] https://return42.github.io/linuxdoc/linuxdoc-howto/man-pages.html -- 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
