You need to download and install the Cygwin tools. Just go to http://www.cygwin.com/ and select the "Install now !" link and download the file "setup.exe" (usually right click, "Save as..". in your web browser) to an empty directory. This directory will later hold all the archives that the installer downloads. Therefore you should not use a temporary directory for this purpose, but one that you keep in place, e.g. "C :\cygwin-install".

Start setup

Log in as an administrator, connect to the internet, and run "setup.exe". Select the "Install from Internet" option.

Download and install the packages

The setup dialog will ask you for the "install root directory". All Cygwin files will be installed in a hierarchy below this directory. Use something like "c :\Programs\cygwin".
Important : change the "Default text file type" to DOS.

To avoid problems, if your sandbox use "DOS" files, install Cygwin with DOS type text file, and if your sandbox uses UNIX files, install Cygwin with UNIX type text files.

If you are not behind a firewall, click on direct connection, then click Next

Select the main mirror

Next, you will be presented with a listbox of available mirrors. Select one close to your home for main cygwin packages. If you have problems connecting, try a different mirror.

Select specific mirror for docbook tools

Within the same screen, type in the bottom box : http://t.bothorel.free.fr/cygwin then click Add. Notice that you have now 2 selected mirrors , scroll the window to make sure they are selected. You can select multiple mirrors by holding down CTRL and clicking on each one. If this url does not work, please add a comment at the bottom of this page. You can try this other mirror also http://drewish.com/projects/cygwin/. It seems previous mirrors are not working any more ( http://www.thierrybo.freesurf.fr/cygwin or http://ns1.iocc.com/ joshua/cygwin/… ).

Package selection

Finally, you will get a listbox with available packages. They are organized in groups that can be opened by clicking their names. You definitely want the base package (leave default choices).
Next, you have to select 6 additional packages :
- 4 in Text category : docbook-dssl, docbook-sgml, openjade, sgml-base, and
- 2 in Devel category : autoconf and make

Click on "Text" to open the category.

Browse to the line "docbook-dssl : DSSL style sheets …".

Click on "Skip". This should replace "skip" with "1.76-1" (or newer) and the first check-box should be checked. You are done. For Text category, just select this one, and all three other packages should be automatically selected. Browse the category to verify that docbook-sgml, sgml-base and openjade packages are selected.

When I wrote the first draft of this document, "openjade" package was missing, or if one was available, it was the same version as the one I provide on http://t.bothorel.free.fr/cygwin. However at the time I updated this HOW-TO, Cygwin installer found a newer "openjade" package that seems available. You should see the version number "1.3.3-1" (or newer) on the "openjade" line. I was NOT able to successfully build PEAR manual with this version, all output goes to the screen. Instead click on "1.3.3-1" and this should switch to "1.3.1-1".

Then click Next button on each page. Don’t worry if you see packages downloads you have not selected. Package dependancies are automatically selected.

If you don’t have your snapshot yet, execute your CVS tool to checkout your peardoc sandbox.

Again, I make the assumption you still want to use Wincvs or TortoiseCVS and don’t want to use command line CVS from within Cygwin.

Run Cygwin

Run "Cygwin Bash Shell" command from the Programs menu (it will be added here by the previous step). From now, it is just like the unix way. You get a command line which behaves same as bash on Unix boxes. If you never worked with bash or Unix before, note that there are slashes (/) instead of backslashes (\) in paths. If you want to access the foo directory on drive c : write it as c :/foo instead of c :\foo.

Do NOT use symlinks with Cygwin, it’s buggy. (the shell doesn’t handle them very well either)

Running "Cygwin Bash Shell" will open a shell in your HOME directory. On Windows XP, this directory maps on the directory specified in §13. On Windows 2000, this is C :\Documents and Settings\<your_windows_user_name>\. Please change your peardoc directory in §13 if you use W2000. If for whatever reason you set an environment variable named HOME, Cygwin bash shell will open within the directory specified in your HOME variable.

Change to the directory where your peardoc snapshot is (or where you want to have it). Use, just like in Windows, the cd command. In Cygwin, the dir command is also supported : cd peardoc

Type

$ autoconf
$ ./configure [—with-lang=your_language_code]
$ make [html|bightml|test]

Substitute your_language_code with a language code you checked out the files of, and would like to work on. The —with-lang parameter is optional. If you don’t specify it, the default is en (English).

’Make html’ (or ’make’) will produce a bunch of html files, whereas ’make bightml’ will produce only one html file named pear_manual_your_language_code.html.

If you didn’t get any errors, you’re ready to rock&roll. Otherwise, you could check out the installation appendix of "DocBook : The Definitive Guide". if you think that the problem is in the build system, ask on the mailing list.

Open the file
C :\Programs\Cygwin\home\<your_windows_user_name>\peardoc\html\index.html with your favorite web browser and see the result !

Install DocBook XML OASIS Standard DTD

Go to the The DocBook Document Type expressed in XML page at http://www.oasis-open.org/docbook/xml/ and follow the link to the latest DocBook XML DTD (ie. V4.2). Then download the zip archive and unzip in C :\Programs\Docbook.

Install Jade DSSSL engine

Go to http://www.jclark.com/jade/#getting page and download the current binary distribution. Then unzip in C :\Programs\Jade .

Install DocBook DSSSL stylesheets

Follow the link http://sourceforge.net/project/showfiles.php?group_id=21935 and download the current docbook-dsssl package (ie. docbook-dsssl-1.78.zip). Then unzip in C :\Programs\Stylesheets\Docbook-dsssl.

Install the Linux Documentation Project customized version of the DocBook DSSSL Style Sheet

You can find the latest copy of the file at http://www.tldp.org/authors/tools/ldp.dsl. Once you have the file ldp.dsl, edit the following line (#6) to the file by bringing it up under your favorite text editor :

< !ENTITY docbook.dsl PUBLIC
 "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"
         CDATA dsssl>
]]>
< !ENTITY % print "INCLUDE">
< ![%print ;[
< !ENTITY docbook.dsl PUBLIC
 "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
 CDATA dsssl>

to

< !ENTITY docbook.dsl SYSTEM 
         "docbook.dsl" 
         CDATA dsssl>
]]>
< !ENTITY % print "INCLUDE">
< ![%print ;[
< !ENTITY docbook.dsl SYSTEM 
         "docbook.dsl" 
         CDATA dsssl>

Adjust PATH

Change the PATH system environment variable to include the Jade directory. This is done via the system settings. Select the "Environment" tab in the System dialog, click on the PATH entry in the upper pane (System variables), and append the path, e.g. C :\Programs\Jade, to the semicolon-separated list. Click Set and close the dialog box.

Create SGML_CATALOG_FILES

Create a SGML_CATALOG_FILES system environment variable. These catalog files are used to resolve public identifiers to local filenames. In the Environment tab of the system dialog enter SGML_CATALOG_FILES as a new variable name in the upper pane. The value of this variable is a semicolon-separated list of catalog files. Be aware that this variable is not a list of directories that contains catalog files, but rather a list of the paths of individual catalog files. Set the value of the environment variable as follows :

C :\Programs\Jade\catalog ;C :\Programs\Docbook\docbook.cat ; _
  C :\Programs\Stylesheets\Docbook-dsssl\catalog

Create a docbook2html.bat file

Create a batch file named docbook2html.bat file in your system PATH, ie.

C :\Programs\Jade\. Then enter theses lines :

@echo off
echo Build HTML …
jade -t sgml -d C :\Programs\Stylesheets\docbook-dsssl\html\ldp.dsl#html %1%.xml
echo Done

All done ! (don’t forget to boot your system so that system knows your new environment variables)

How to use

First open a NT command-line window. Change into the directory which contains your xml files and type the following command (without .xml extension) :

c :\yourfolder> docbook2html xml_file_name

Jade should create several files in the current directory. Open index.html to see the result.

Don’t worry about general entity and reference to identity errors. Peardoc xml files are not designed to be built individually, then <link/> are not shown and <ulink/> have empty urls, but at least you got the overall look and feel of your files, and you can test your xml tags.