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

[Jon TURNEY <jon.turney@dronecode.org.uk>]

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" ?

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

* 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

* 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

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