Wed Feb 25 16:56:33 PST 2004
Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

(cygwin-users-guide)
The packages required to build the Cygwin user's guide are unfortunately
not yet part of the Cygwin distribution. For a time, there were testing
packages available for DocBook on Cygwin, but they are no longer available.

If you have a working DocBook installation, you can use the files in
this directory to create your own formats. Note that the originals are
in CVS, however, so if you want to improve the Cygwin documentation I
recommend downloading the Cygwin CVS and following the instructions
below to get a working documentation build system.

To create the one-HTML-file, try this:

jade -d cygwin.dsl -t sgml -i html -V nochunks cygwin-ug-net.sgml >cygwin-ug-net-nochunks.html

For PDF creation, you can use pdfjadetex on an machine with it. You need
to run it several times to get the Table of Contents correct:

jade -t tex -d cygwin.dsl cygwin-ug-net.sgml
pdfjadetex cygwin-ug-net.tex 
pdfjadetex cygwin-ug-net.tex 
pdfjadetex cygwin-ug-net.tex 

---Getting a working documentation build system---

To build the documentation from Cygwin CVS, you need to have all the
normal build tools (gcc,make,etc) and a couple you might not--
libxml2 and rpm. Before the letters "R" "P" "M" scare people, let
me digress. Up until now the Cygwin documentation has been built
either on Linux or with custom Cygwin packages. (Note to you and
to future list readers, this hopefully will change very soon--maybe 
as soon as we get Nicholas' openjade patches and can get it and the
various DTD and stylesheets in the distribution.)

The problem with installing custom packages is that you can get them
confused with real ones and create a dependency mess as you attempt
to move from custom to official packages. Right now on Cygwin all we
have is custom packages for SGML docbook (which is what the Users' Guide 
and API Reference are written in).  Just to be clear here, RPM is not
becoming an official Cygwin installation method, and most RPMs you find
on the Web will *NOT* work in Cygwin.

That said, I've put up my hacked-together RPMs at:

<http://ns1.iocc.com/~joshua/cygwin/RPMS/>

Note that RPM has many features such as dependency management that I've
deliberately ripped out of these, so don't get too excited. 
Note also that there is an openjade-1.3.1-1.tar.bz2 there. This was 
packaged about two years ago before there was trouble building openjade, 
so it's quite old, but works for our purposes:

--------------------------snip---------------------------------------
# 1. Get the files
cd /tmp 
wget -m -np -nH --cut-dirs=3 http://ns1.iocc.com/~joshua/cygwin/RPMS/

# 2. Never do this again--it's a very bad idea
cd /
tar jxvf /tmp/openjade-1.3-1.1.tar.bz2

# 3. Install the hacked-together "dependencies" rpms
rpm -Uhv /tmp/*rpm

# 4. Install the actual docbook packages
rpm -Uhv /tmp/docbook/*rpm

# 5. Remove everything you've installed with rpm with one easy step
#    onces we've got Cygwin packages together--no mess!
rpm -e $(rpm -qa)
--------------------------snip---------------------------------------

Once you've got that, all you should need to do it type "make" in the
winsup/doc folder of your Cygwin build tree. There are a couple of other
things you might want to do:

-comment out (with -- before and after) the "DTDDECL" statement in 
/usr/share/sgml/docbook/dsssl-stylesheets/catalog
This version of jade just hates the DTDDECL and complains loudly. 

-Change /usr/bin/db2html's shebang to "#!/bin/bash" since it uses 
bash-specific artithmetic syntax.
