Am 14.07.2016 um 16:19 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>: > 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. OK, should not be hard to implement. >> :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 May I misunderstood you: how should this work? ... I mean, the reST file is somewhere under Documentation/ ... this might work for kernel-doc generated man pages, where the source file is parsed. >> 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. About portability, the tbl man page says: The output generated by GNU tbl cannot be processed with Unix troff; it must be processed with GNU troff. About reST tables: The output of tables is independent from the reST markup you used to describe the table ... ASCII art tables and flat-tables result in the same (internal) node-tree. So it does not matter if you define a cell spanning with ASCII art or with the flat-table directive. The problem is, that the underlying man page translator does not support row or cell spanning: https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/manpage.py#L615 I think I could extend the Translator to support row and cell spanning, but as far as I can estimate from here, this this will need some efforts. -- Markus -- >> >> 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
