[RFC][PATCH] Make manpages via DocBook XML
Wed Jul 22 20:36:00 GMT 2015
On 21/07/2015 20:24, Jeff Johnston wrote:
>> On Jul 21 13:37, Jon TURNEY wrote:
>>> * This only converts to DocBook the minimum necessary to generate manpages.
>>> Converting the full content of libc.texinfo, libm.texinfo, sys.tex,
>>> reent.tex, iconv.tex, etc. is hard to do automatically, so would need to be
>>> done by hand.
>>> Since maintaining the documentation in two formats seems unlikely to be a
>>> good idea, this would mean fully converting to DocBook, removing all the
>>> current texinfo source and .info generation and generating the .info from
>>> DocBook instead.
>> Do I understand you correctly? Do you suggest to convert the
>> documentation in the C files to DocBook XML format?
Firstly, you might consider this a non-issue, and be happy with the
approach of adding a mechanism for generating manpages, while leaving
generating .info documentation as currently, as this patch does.
Secondly, that's not what I'm suggesting.
My aim was to make the minimum amount of change, so I wrote makedocbook
(which processes makedoc markup and a very limited subset of texinfo
markup into DocBook XML) avoid having to alter the existing
documentation in C files.
As stated in the "Documentation" section of HOWTO, the current situation
is that documentation in C files uses makedoc markup, and can also use
any texinfo commands directly.
Additionally there are some handwritten .texinfo files.
I guess I am noting that it would be possible to change that so that
documentation in the C files can use makedoc markup, the very limited
subset of texinfo markup which is currently used, (and perhaps) DocBook
markup (it's not clear this is necessary or a good idea)
Additionally, the handwritten .texinfo files would be converted to
If you have suggestions as to how to achieve my goal of making manpages
while making even less changes, I would very much like to hear them.
>>> * This fails to fully achieve the objective of generating good manpages.
>>> few functions (e.g. sccanf, ssprintf) use nested tables in a way which
>>> be represented by troff markup (see ). So the markup of the
>>> documentation for these functions would need to be improved, presumably by
>>> writing it directly in DocBook.
I should probably have written 'simplified or improved...', and also
discussed the possibility of simplifying the markup used in the
documentation for those functions to something which allows good
manpages to be generated.
On reflection, and after looking at the linux man-pages for sscanf,
ssprintf (which do not use tables at all), that seems the better approach.
> Again, not sure why this means everything has to be rewritten and not just
> a few functions modified. Glibc uses texinfo documentation for stdio functions
> and presumably the man pages are generated from them so we should be able to
> do something similar.
This is a good question, but I don't think the presumption is correct.
By design, texinfo does not lend itself well to generating manpages.
The texinfo documentation for glibc is organized in a different manner
to man pages (e.g for sscanf, see
and the surrounding sections)
There are also manpages, but those come from the linux man-pages
project, and seem to be handwritten troff. (e.g. compare
>>> * The documentation license contains a clause specifically permitting
>>> printing after processing with Tex. Presumably the copyright holder, Red
>>> Hat, would need to approve a change permitting printing after processing
>>> with other tools.
>> The copyright holder is not Red Hat. Many files have different
>> copyrights and copyright holders. But I don't think that's a problem.
>> I assume that the general idea was to make sure that it's allowed to
>> print the docs in the first place.
Ok, I didn't know that newlib didn't require a copyright assignment.
>> Jeff, any input to this?
> The clause is in libc.texinfo and libm.texinfo and we should have the power to modify
I'm not sure in what sense 'should' is used here.
More information about the Newlib