dongsheng@626: HOW-TO:  Compiling the Mercurial Book
dongsheng@626: ======================================
dongsheng@626: 
dongsheng@626: This Mercurial Book is written in DocBook 4.5.
dongsheng@626: 
dongsheng@626: The goal of this document is to give simple instructions to anyone who
dongsheng@626: wants to compile this book into a useful format, like HTML or PDF.  It
dongsheng@626: should state *exactly* which tools to use, and how to invoke them, in
dongsheng@626: simplest terms.
dongsheng@626: 
dongsheng@626: Table of Contents:
dongsheng@626: 
dongsheng@626:   I. PRIMER
dongsheng@626:  II. COMPILING THE DOCS
dongsheng@626: III. HACKING ON THE DOCS
dongsheng@626: 
dongsheng@626: I. PRIMER
dongsheng@626: 
dongsheng@626:   DocBook has a tortured, confusing history.  Before you do anything,
dongsheng@626:   take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
dongsheng@626: 
dongsheng@626:       http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
dongsheng@626: 
dongsheng@626:   It's very short and clears up many things.
dongsheng@626: 
dongsheng@626: 
dongsheng@626: II. COMPILING THE DOCS
dongsheng@626: 
dongsheng@626: 
dongsheng@626: 1. Install XML DTD and XSL stylesheets for DocBook
dongsheng@626: 
dongsheng@626:       % sudo apt-get install docbook-xml docbook-xsl
dongsheng@626: 
dongsheng@626: 2. Install libxml2-utils
dongsheng@626: 
dongsheng@626:       % sudo apt-get install libxml2-utils
dongsheng@626: 
dongsheng@626: 3. Install graph drawing tools
dongsheng@626: 
dongsheng@626:       % sudo apt-get install graphviz inkscape
dongsheng@626: 
dongsheng@626: 4. Install pdf support
dongsheng@626: 
dongsheng@626:       % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
dongsheng@626: 
dongsheng@626:   The Makefile will actually invoke tools/fop/fop.sh, you should do
dongsheng@626:   some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
dongsheng@626: 
dongsheng@626: 5. Make
dongsheng@626:   Run 'make' for more details, for example:
dongsheng@626: 
dongsheng@626:   * make all document(pdf, html and html-single for all languages)
dongsheng@626:       % make all
dongsheng@626: 
dongsheng@626:   * make english document(pdf, html and html-single for all languages)
dongsheng@626:       % make LINGUA=en all
dongsheng@626: 
dongsheng@626:   * make Chinese document(pdf, html and html-single for all languages)
dongsheng@626:       % make LINGUA=zh all
dongsheng@626: 
dongsheng@626:   * make Chinese pdf document
dongsheng@626:       % make LINGUA=zh pdf
dongsheng@626: 
dongsheng@626: III. HACKING ON THE DOCS
dongsheng@626: 
dongsheng@626: In addition to everything in section II:
dongsheng@626: 
dongsheng@626: 
dongsheng@626: 1. Get a nice editing environment for SGML/XML.
dongsheng@626: 
dongsheng@626:   This isn't strictly required, but it's nice when your editor
dongsheng@626:   colorizes things, understands the DTD, tells you what tags you can
dongsheng@626:   insert, etc.
dongsheng@626: 
dongsheng@626:   If you use emacs, we recommend the PSGML major-mode.  Most free
dongsheng@626:   operating systems package it, or its home page is here:
dongsheng@626: 
dongsheng@626:       http://www.lysator.liu.se/projects/about_psgml.html
dongsheng@626: 
dongsheng@626:   If you use vim, you might check out xmledit, at:
dongsheng@626: 
dongsheng@626:       http://www.vim.org/scripts/script.php?script_id=301
dongsheng@626: 
dongsheng@626: 
dongsheng@626: 2. Get a validating parser.
dongsheng@626: 
dongsheng@626:   Actually, if you have what you need to compile the documentation,
dongsheng@626:   then you almost certainly have an XML validator installed already -
dongsheng@626:   it is called xmllint, and comes as part of libxml2.
dongsheng@626: 
dongsheng@626:   The makefile is preconfigured with a suitable invocation of it,
dongsheng@626:   so simply run:
dongsheng@626: 
dongsheng@626:       $ make validate
dongsheng@626: 
dongsheng@626: 3. Read about DocBook.
dongsheng@626: 
dongsheng@626:   You'll want to get real intimate with a DocBook reference, such as
dongsheng@626:   can be found at:  http://www.docbook.org/tdg/en/html/