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
	=
Mailing-List: contact cygwin-help@cygwin.com; run by ezmlm
Sender: cygwin-owner@cygwin.com
Mail-Followup-To: cygwin@cygwin.com
Message-ID: <518CC275.2060207@etr-usa.com>
Date: Fri, 10 May 2013 03:48:37 -0600
From: Warren Young <warren@etr-usa.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@cygwin.com
Subject: Re: Cygwin manpages clobbered
References: <5F8AAC04F9616747BC4CC0E803D5907D0AF787B3@MLBXv04.nih.gov> <518C55BD.7020807@etr-usa.com> <20130510041245.GA3019@ednor.casa.cgf.cx>
In-Reply-To: <20130510041245.GA3019@ednor.casa.cgf.cx>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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