From: Jon TURNEY <jon.turney@dronecode.org.uk>
To: cygwin-patches@cygwin.com
Subject: Re: [PATCH 0/5] Generate cygwin-api manpages
Date: Thu, 18 Jun 2015 10:46:00 -0000 [thread overview]
Message-ID: <5582A170.9010305@dronecode.org.uk> (raw)
In-Reply-To: <20150617162753.GN31537@calimero.vinschen.de>
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.
next prev parent reply other threads:[~2015-06-18 10:46 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-06-17 12:37 Jon TURNEY
2015-06-17 12:37 ` [PATCH 3/5] winsup/doc: Convert cygwin-api function documentation to refentry elements Jon TURNEY
2015-06-17 12:37 ` [PATCH 1/5] winsup/doc: Rename cygwin.xsl as html.xsl Jon TURNEY
2015-06-17 12:37 ` [PATCH 2/5] winsup/doc: Generate ANSI rather than K&R style function prototypes Jon TURNEY
2015-06-17 12:37 ` [PATCH 4/5] winsup/doc: Make and install cygwin-api function manpages Jon TURNEY
2015-06-19 14:05 ` Jon TURNEY
2015-06-17 12:37 ` [PATCH 5/5] winsup/doc: Add man.xsl customization stylesheet Jon TURNEY
2015-06-17 13:49 ` [PATCH 0/5] Generate cygwin-api manpages Corinna Vinschen
2015-06-17 15:59 ` Jon TURNEY
2015-06-17 16:28 ` Corinna Vinschen
2015-06-18 10:46 ` Jon TURNEY [this message]
2015-06-18 20:05 ` Corinna Vinschen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5582A170.9010305@dronecode.org.uk \
--to=jon.turney@dronecode.org.uk \
--cc=cygwin-patches@cygwin.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).