This is the mail archive of the
newlib@sourceware.org
mailing list for the newlib project.
Re: [RFC][PATCH] Make manpages via DocBook XML
- From: Jeff Johnston <jjohnstn at redhat dot com>
- To: Jon TURNEY <jon dot turney at dronecode dot org dot uk>
- Cc: newlib at sourceware dot org
- Date: Wed, 22 Jul 2015 16:36:06 -0400 (EDT)
- Subject: Re: [RFC][PATCH] Make manpages via DocBook XML
- Authentication-results: sourceware.org; auth=none
- References: <55AE3D08 dot 7070009 at dronecode dot org dot uk> <20150721184718 dot GD3864 at calimero dot vinschen dot de> <25070555 dot 3192375 dot 1437506682457 dot JavaMail dot zimbra at redhat dot com> <55AFF8D9 dot 1020805 at dronecode dot org dot uk>
----- Original Message -----
> 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?
>
> No.
>
> 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
> DocBook XML.
>
> 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.
> >>> A
> >>> few functions (e.g. sccanf, ssprintf) use nested tables in a way which
> >>> can't
> >>> be represented by troff markup (see [1]). 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.
> (see
> http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Adding-Output-Formats)
>
> The texinfo documentation for glibc is organized in a different manner
> to man pages (e.g for sscanf, see
> http://www.gnu.org/software/libc/manual/html_node/Formatted-Input-Functions.html
> 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
> http://git.kernel.org/cgit/docs/man-pages/man-pages.git/tree/man3/scanf.3)
>
> >>> * 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
> > it.
>
> I'm not sure in what sense 'should' is used here.
>
The clause is in a Red Hat license which means it would be reasonable to assume
that Corinna or myself, representing Red Hat, would have the ability to modify it but IANAL.