songdongsheng@666: HOW-TO:  Compiling the Mercurial Book
songdongsheng@666: ======================================
bos@605: 
songdongsheng@666: This Mercurial Book is written in DocBook 4.5.
bos@605: 
songdongsheng@666: The goal of this document is to give simple instructions to anyone who
songdongsheng@666: wants to compile this book into a useful format, like HTML or PDF.  It
songdongsheng@666: should state *exactly* which tools to use, and how to invoke them, in
songdongsheng@666: simplest terms.
bos@605: 
songdongsheng@666: Table of Contents:
bos@605: 
songdongsheng@666:   I. PRIMER
songdongsheng@666:  II. COMPILING THE DOCS
songdongsheng@666: III. HACKING ON THE DOCS
songdongsheng@666: 
songdongsheng@666: I. PRIMER
songdongsheng@666: 
dongsheng@879:   DocBook has a tortured, confusing history. Before you do anything,
dongsheng@879:   take a look at:
songdongsheng@666: 
dongsheng@879:       http://wiki.docbook.org/topic/DocBookTutorials
songdongsheng@666: 
songdongsheng@666: II. COMPILING THE DOCS
songdongsheng@666: 
songdongsheng@666: 1. Install XML DTD and XSL stylesheets for DocBook
songdongsheng@666: 
songdongsheng@666:       % sudo apt-get install docbook-xml docbook-xsl
songdongsheng@666: 
songdongsheng@666: 2. Install libxml2-utils
songdongsheng@666: 
songdongsheng@666:       % sudo apt-get install libxml2-utils
songdongsheng@666: 
dongsheng@884: 3. Install graph drawing and patches tools
songdongsheng@666: 
dongsheng@884:       % sudo apt-get install graphviz inkscape patchutils
songdongsheng@666: 
songdongsheng@666: 4. Install pdf support
songdongsheng@666: 
songdongsheng@666:       % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
songdongsheng@666: 
dongsheng@873:   The Makefile will actually invoke $FOP_HOME/fop.sh, you should do
songdongsheng@666:   some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
songdongsheng@666: 
dongsheng@877: 5. Configure XML Catalogs
dongsheng@879:   For non pdf output, we use xsltproc for XSLT process, xsltproc use system
dongsheng@877:   catalog files automatically, usually /etc/xml/catalog. Users do not need to
dongsheng@877:   care about it.
dongsheng@877: 
dongsheng@877:   For pdf output, we need use the xsl extensions (docbook-xsl-saxon), so we must
dongsheng@877:   create file $JAVA_LIB/CatalogManager.properties like this:
dongsheng@877: 
dongsheng@877:       catalogs=/etc/xml/catalog
dongsheng@877:       relative-catalogs=true
dongsheng@877:       static-catalog=yes
dongsheng@877:       catalog-class-name=org.apache.xml.resolver.Resolver
dongsheng@877:       verbosity=1
dongsheng@877: 
dongsheng@877: 6. Create Makefile.vars
dongsheng@877:   Please create your Makefile.vars from Makefile.vars.tmpl .
dongsheng@877: 
dongsheng@877: 7. Make
songdongsheng@666:   Run 'make' for more details, for example:
songdongsheng@666: 
dongsheng@878:   * make all document(pdf, epub, html and html-single for all languages)
songdongsheng@666:       % make all
songdongsheng@666: 
dongsheng@878:   * make english document(pdf, epub, html and html-single for all languages)
songdongsheng@666:       % make LINGUA=en all
songdongsheng@666: 
dongsheng@878:   * make Chinese document(pdf, epub, html and html-single for all languages)
songdongsheng@666:       % make LINGUA=zh all
songdongsheng@666: 
songdongsheng@666:   * make Chinese pdf document
songdongsheng@666:       % make LINGUA=zh pdf
songdongsheng@666: 
songdongsheng@666: III. HACKING ON THE DOCS
songdongsheng@666: 
songdongsheng@666: In addition to everything in section II:
songdongsheng@666: 
dongsheng@879: 1. Get a nice editing environment for XML
songdongsheng@666: 
songdongsheng@666:   This isn't strictly required, but it's nice when your editor
songdongsheng@666:   colorizes things, understands the DTD, tells you what tags you can
songdongsheng@666:   insert, etc.
songdongsheng@666: 
dongsheng@879:   If you use emacs, we recommend the nxml-mode. Most free
songdongsheng@666:   operating systems package it, or its home page is here:
songdongsheng@666: 
dongsheng@879:       http://www.emacswiki.org/emacs/NxmlMode
songdongsheng@666: 
songdongsheng@666:   If you use vim, you might check out xmledit, at:
songdongsheng@666: 
songdongsheng@666:       http://www.vim.org/scripts/script.php?script_id=301
songdongsheng@666: 
dongsheng@879: 2. Get a validating parser
songdongsheng@666: 
songdongsheng@666:   Actually, if you have what you need to compile the documentation,
songdongsheng@666:   then you almost certainly have an XML validator installed already -
songdongsheng@666:   it is called xmllint, and comes as part of libxml2.
songdongsheng@666: 
songdongsheng@666:   The makefile is preconfigured with a suitable invocation of it,
songdongsheng@666:   so simply run:
songdongsheng@666: 
songdongsheng@666:       $ make validate
songdongsheng@666: 
dongsheng@879: 3. Read about DocBook
songdongsheng@666: 
songdongsheng@666:   You'll want to get real intimate with a DocBook reference, such as
songdongsheng@666:   can be found at:  http://www.docbook.org/tdg/en/html/