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.
