Re: [PATCH 0/5] Generate cygwin-api manpages

[Jon TURNEY <jon dot turney at dronecode dot org dot uk>]

On 17/06/2015 17:27, Corinna Vinschen wrote:
> On Jun 17 16:59, Jon TURNEY wrote:
> > On 17/06/2015 14:49, Corinna Vinschen wrote:
> > > On Jun 17 13:37, Jon TURNEY wrote:
> > > > This patch set changes the DocBook source XML for the Cygwin API reference to
> > > > use refentry elements, and also generates man pages from that.
> > > >
> > > > Again, note that after this, the chunked html now has a page for each function,
> > > > rather than one containing all functions.
> > >
> > > Patchset approved, basically, except...
> > >
> > > The next cygwin.cygport file will explicitly exclude the man pages
> > > section 1.  But it won't exclude section 3, and I'm rather not hot
> > > on excluding each newly generated API file explicitly.
> >
> > Yes, I hadn't noticed that regex.3 manpage, which makes things a bit of a
> > pain.
> >
> > But maybe you write in cygwin_devel_CONTENTS something like
> > "--exclude=usr/share/man/ usr/share/man/man3/regex.3.gz
> > usr/share/man/man7/regex.7.gz" ?
>
> exclude?  This would require to move both files to cygwin-doc
> as you outlined below.  It would essentially remove all man pages
> from the cygwin core packages and then we exclude usr/share/man,
> as you outlined below as well.

Hmm?  I thought perhaps this would exclude everything under 
usr/share/man, then include regex.3 and regex.7

But I don't think tar processes it's options left-to-right like that, so 
never mind.

> > > Do you have an idea how far away we are from including the cygwin-doc
> > > package into the cygwin package set?  I'm not planning a new release
> > > very soon, so we can coordinate that without pressure.
> >
> > After this patch set, the remaining things are:
> >
> > * newlib libc and libm .info documentation
> >
> > I think this just needs 'make info' adding to the .cygport, as newlib
> > doesn't build this on 'make all'
>
>    libc.info and libm.info are built by default, but they are not
>    installed with `make install'

That seems a little odd.

> > * intro.1 and intro.3 man pages for Cygwin, handwritten
> >
> > If these are worth keeping, this is straightforward
> >
> > * Cygwin User's Guide and API reference texinfo, generated from the DocBook
> > XML
> >
> > as is this
>
>    Isn't the HTML documentation sufficient?  I'm not opposed to
>    keeping the texinfo's, just wondering.

It's there currently and it's really not much work to keep it.

> > * man pages for newlib functions
> >
> > But this is a substantial piece of work.  Currently, I'm not even sure how
> > this can be done in an upstreamable way.
> >
> > I am experimenting with building an alternative to the makedoc tool, which
> > generates DocBook XML rather than .texinfo, which can then be processed into
> > manpages and other formats, but this is far from complete.
> >
> >
> > If the suggestion above doesn't work, I guess possible approaches to
> > coordination are:
> >
> > * Move regex.[37] from cygwin-devel to cygwin-doc, and exclude
> > /usr/share/man
>
> ... this sounds good to me.

Let's do things that way, then.