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

[Corinna Vinschen <corinna-cygwin@cygwin.com>]

[-- Attachment #1: Type: text/plain, Size: 3031 bytes --]

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.

So...

> >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'

> * 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.
> 
> * 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.

> * Assuming I can finish the first 3 items on that list before the next
> cygwin release, move the newlib manpages to a new package
> (man-pages-newlib?) and make that a dependency of cygwin-doc.

As I wrote, no stress.


Thanks,
Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat

[-- Attachment #2: Type: application/pgp-signature, Size: 819 bytes --]