X-Recipient:	archive-cygwin AT delorie DOT com
DomainKey-Signature:	a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id
	:list-unsubscribe:list-subscribe:list-archive:list-post
	:list-help:sender:message-id:date:from:mime-version:to:subject
	:references:in-reply-to:content-type:content-transfer-encoding;
	q=dns; s=default; b=TJGisuS/+/OaeVIe0lStq/QIQkC27TDhhNjYtNSuw5v
	6l/OBvcLo/qn5Jan0VcsMQ9e8vAobALtCf6NeplzcYZ5R4IlsROrRP7IYtgp51nv
	1w+FGYPQ48fJ1zyixdGSpgm/g3jwF9IxMeR1TxthofYr2Q8xi/zXXIA7QfhmNAME
	=
DKIM-Signature:	v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id
	:list-unsubscribe:list-subscribe:list-archive:list-post
	:list-help:sender:message-id:date:from:mime-version:to:subject
	:references:in-reply-to:content-type:content-transfer-encoding;
	s=default; bh=3qLpc8ZTuAk2sY5CleHSUfYu8MM=; b=ZwVCQhow6KJl3R+S+
	7tLV0Z5J8b07KBu3YE/pxDw4ourButp0/gtLt+NB/hXx+NjdbnKEqxI20SgPI3eE
	/UyKZO6XLty3LswaQI3HsC+xB1z6bj9nmqmiHXUIipE98D31wyiV2MbbmE8zUPw0
	RIDcjuSQnkHq+l3O1kiISXbNkI=
Mailing-List:	contact cygwin-help AT cygwin DOT com; run by ezmlm
List-Id:	<cygwin.cygwin.com>
List-Subscribe:	<mailto:cygwin-subscribe AT cygwin DOT com>
List-Archive:	<http://sourceware.org/ml/cygwin/>
List-Post:	<mailto:cygwin AT cygwin DOT com>
List-Help:	<mailto:cygwin-help AT cygwin DOT com>, <http://sourceware.org/ml/#faqs>
Sender:	cygwin-owner AT cygwin DOT com
Mail-Followup-To:	cygwin AT cygwin DOT com
Delivered-To:	mailing list cygwin AT cygwin DOT com
X-Spam-SWARE-Status:	No, score=-3.2 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RP_MATCHES_RCVD autolearn=ham version=3.3.1
Message-ID:	<518CC275.2060207@etr-usa.com>
Date:	Fri, 10 May 2013 03:48:37 -0600
From:	Warren Young <warren AT etr-usa DOT com>
User-Agent:	Mozilla/5.0 (Windows NT 6.2; WOW64; rv:17.0) Gecko/20130328 Thunderbird/17.0.5
MIME-Version:	1.0
To:	cygwin AT cygwin DOT com
Subject:	Re: Cygwin manpages clobbered
References:	<5F8AAC04F9616747BC4CC0E803D5907D0AF787B3 AT MLBXv04 DOT nih DOT gov> <518C55BD DOT 7020807 AT etr-usa DOT com> <20130510041245 DOT GA3019 AT ednor DOT casa DOT cgf DOT cx>
In-Reply-To:	<20130510041245.GA3019@ednor.casa.cgf.cx>

On 5/9/2013 22:12, Christopher Faylor wrote:
>
> Warren, if you want to take over the cygwin-doc package you're welcome
> to it.

Pending our discussion with Corinna when she gets back, sure.

I haven't tried digging further to figure out how these man pages were 
generated for the cygwin-doc package yet, but I did figure out how to do 
the conversion myself.  That, and a fair bit of hacking on the original 
SGML gives these results:

     http://etr-usa.com/cygwin/doc/test/api.xml
     http://etr-usa.com/cygwin/doc/test/ccp.xml
     http://etr-usa.com/cygwin/doc/test/ccp.html
     http://etr-usa.com/cygwin/doc/test/ccp.3
     http://etr-usa.com/cygwin/doc/test/ccp.pdf

Stylesheets to drive the conversions:

     http://etr-usa.com/cygwin/doc/test/fo.xsl
     http://etr-usa.com/cygwin/doc/test/html.xsl
     http://etr-usa.com/cygwin/doc/test/manpage.xsl

api.xml is a cut-down stand-in for winsup/doc/cygwin-api.xml.  You need 
the DocBook <book> container to get an accurate picture of how the man 
page will format in HTML and PDF outputs.

I think these outputs look pretty good, myself.  The HTML is the least 
impressive, and it can be fixed with some CSS.  (Code snippets should be 
indented, for example.)

Conversion commands, to save anyone who cares some digging:

ccp.xml to manpage:

     $ xsltproc --nonet manpage.xsl ccp.xml

man page test:

     $ man ./cygwin_conv_path.3

(Did you know man(1) could be arm-twisted into testing a man page 
without having to install it first?  The trick is the "./".)

HTML and PDF output:

     $ xmlto html api.xml
     $ xmlto pdf api.xml

(Notice that there is no --skip-validation, as with the current Cygwin 
docs.  That is to say, my files *do* validate. :) )

Doxygen can do all of this, too, with less verbose markup.

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

- Raw text -