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. 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 :man-sec: 2 :author: John Sample :address: john.sample@xxxxxxxxxxx Name ==== VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output Return ====== ... <SNAP> ----------------------------------- The man-name and man-sec is used to build the filename "videoc_audout.2" and is also inserted in the .TH (title line), e.g: <SNIP> ----------------------------------- .TH "VIDIOC_AUDOUT" "2" "July 06, 2016" "Linux" "Linux Programmer's Manual" <SNAP> ----------------------------------- The date in the .TH will be the build date and the last two fields are always "Linux" and "Linux Programmer's Manual" (see man-page7) My first question is, do we really need author and address and when we need it, how should we handle these items? The man-pages7 says: Use of an AUTHORS section is strongly discouraged ... if you write or significantly amend a page, add a copyright notice as a comment in the source file ... If you are the author of a device driver and want to include an address for reporting bugs, place this under the BUGS section. 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. I have many other thoughts about man pages and I will remark them when the discussion running, but at first I want to now from you all: What are your suggestions about man page generation? Thanks for any remark ... -- Markus -- References: * linux man pages: https://www.kernel.org/doc/man-pages/ * man-page(7): http://man7.org/linux/man-pages/man7/man-pages.7.html -- 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
