On Thu, 14 Jul 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx> wrote: > Em Thu, 14 Jul 2016 13:45:00 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > >> Hi Jonathan, hi all, >> >> I want to contribute a modified version of my man-page builder, >> but before we should elaborate what we need in more detail. >> We have two use-cases from which we want to create man page. >> >> * create man-pages from kernel-doc comments and >> * create man-pages from "handwritten" reST documents >> >> For the "handwritten", sphinx-doc brings the "man" builder described in [1]. >> >> [1] http://www.sphinx-doc.org/en/stable/config.html#confval-man_pages >> >> Mauro and I figured out, that [1] has some drawbacks: >> >> 1. you need a separate file for each man-page (see "startdocname" [1]) >> 2. you need to touch the conf.py every time you mark a content >> as man-page. > > This will never scale. At media, we have already hundreds of > stuff that would be better fit as a man page. conf.py is python. It can include other files or infer the man pages programmatically. >> 3. The "NAME" section is created by the builder and could not >> be a part of your reST document (see "name" [1]) >> >> Thats why we recommend a simple markup (a directive) to mark reST >> content as content from which a man-page should be build. E.g: >> >> <SNIP> ----------------------------------- >> ************************************** >> ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT >> ************************************** >> >> .. kernel-man: >> :man-name: videoc_audout I am not sure how this would scale better than using conf.py. I don't have the time right now to propose a proper solution, but please also don't lock in to the thought that you'd have to list everything in the conf file or tag everything in the rst files. >> I think there are many other question, we have to answer, e.g. >> how this is married with the kernel-doc comments, but at first >> it might be the best, we focus on "handwritten" man-pages. >> Later, we can discuss how this markup will be produced by >> the kernel-doc parser. > > Agreed. Once we have an extension capable of generating man pages > based on a tag inside the rst file, it shouldn't be hard to automate > kernel-doc to use it. One thing is a "handwritten" man page including kernel-doc comments using the extension. This shouldn't require any changes. Just a regular kernel-doc directive. The other thing is generating man pages from kernel-doc comments on the fly. I don't think we should use any special kernel-doc markup or indeed change anything in kernel-doc the script or extension for this. The rst output should be generic this way. Instead, I am thinking we could perhaps come up with a single template rst file, perhaps generated, that would include the bits indicated on the make command line somehow. Needs thought. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
