This is the mail archive of the cygwin mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Cygwin manpages clobbered


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]