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. > 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 guess it would be interesting to allow specifying multiple man pages. In this specific example, two ioctls are documented the same way. I guess it would make sense to produce two man pages, so, if the user asks for: $ man vidioc_g_audout or $ man vidioc_s_audout it will see the contents of this man page. > :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. For the media stuff (both the uAPI and kernel-docs), I don't think it is needed, at least for the things we have there right now. Currently, we document only the kAPI and uAPI stuff (e. g. the subsystem core), with has multiple authors. So, if one wants to check the copyrights, he would need to go to the Kernel's tree. If we're willing to document single drivers (I'm now talking only about kernel-docs), then having an AUTHOR could be interesting. Yet, IMHO, the best would be, instead, to look into the MAINTAINERS file and get the emails of the ones responsible for maintaining the driver (usually a mailing list), using a logic similar to: ./scripts/get_maintainers.pl > 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. > > 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? One thing that it needs to address is that the flat-tables should also be converted somehow to groff format. Groff has a table preprocessor (tbl). With that, outputting some thing like: .TS tab(;) allbox; l l l ld r ^ l rd. 0000;foobar T{ 1111 .br 2222 T};foo r; T{ 3333 .br 4444 T};bar \^;\^ .TE (example copied from tbl man page) will produce this table with: $ man ./foo ┌─────┬────────┐ │0000 │ foobar │ ├─────┼────────┤ │1111 │ │ │2222 │ │ ├─────┤ │ │ r │ foo │ ├─────┼────────┤ │3333 │ │ │4444 │ bar │ └─────┴────────┘ Yet, I'm not sure how portable is to use such preprocessor. > > 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 -- 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
