1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/README.BUILD	Tue Aug 11 23:01:30 2009 +0200
     1.3 @@ -0,0 +1,99 @@
     1.4 +HOW-TO:  Compiling the Mercurial Book
     1.5 +======================================
     1.6 +
     1.7 +This Mercurial Book is written in DocBook 4.5.
     1.8 +
     1.9 +The goal of this document is to give simple instructions to anyone who
    1.10 +wants to compile this book into a useful format, like HTML or PDF.  It
    1.11 +should state *exactly* which tools to use, and how to invoke them, in
    1.12 +simplest terms.
    1.13 +
    1.14 +Table of Contents:
    1.15 +
    1.16 +  I. PRIMER
    1.17 + II. COMPILING THE DOCS
    1.18 +III. HACKING ON THE DOCS
    1.19 +
    1.20 +I. PRIMER
    1.21 +
    1.22 +  DocBook has a tortured, confusing history.  Before you do anything,
    1.23 +  take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
    1.24 +
    1.25 +      http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
    1.26 +
    1.27 +  It's very short and clears up many things.
    1.28 +
    1.29 +
    1.30 +II. COMPILING THE DOCS
    1.31 +
    1.32 +
    1.33 +1. Install XML DTD and XSL stylesheets for DocBook
    1.34 +
    1.35 +      % sudo apt-get install docbook-xml docbook-xsl
    1.36 +
    1.37 +2. Install libxml2-utils
    1.38 +
    1.39 +      % sudo apt-get install libxml2-utils
    1.40 +
    1.41 +3. Install graph drawing tools
    1.42 +
    1.43 +      % sudo apt-get install graphviz inkscape
    1.44 +
    1.45 +4. Install pdf support
    1.46 +
    1.47 +      % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
    1.48 +
    1.49 +  The Makefile will actually invoke tools/fop/fop.sh, you should do
    1.50 +  some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
    1.51 +
    1.52 +5. Make
    1.53 +  Run 'make' for more details, for example:
    1.54 +
    1.55 +  * make all document(pdf, html and html-single for all languages)
    1.56 +      % make all
    1.57 +
    1.58 +  * make english document(pdf, html and html-single for all languages)
    1.59 +      % make LINGUA=en all
    1.60 +
    1.61 +  * make Chinese document(pdf, html and html-single for all languages)
    1.62 +      % make LINGUA=zh all
    1.63 +
    1.64 +  * make Chinese pdf document
    1.65 +      % make LINGUA=zh pdf
    1.66 +
    1.67 +III. HACKING ON THE DOCS
    1.68 +
    1.69 +In addition to everything in section II:
    1.70 +
    1.71 +
    1.72 +1. Get a nice editing environment for SGML/XML.
    1.73 +
    1.74 +  This isn't strictly required, but it's nice when your editor
    1.75 +  colorizes things, understands the DTD, tells you what tags you can
    1.76 +  insert, etc.
    1.77 +
    1.78 +  If you use emacs, we recommend the PSGML major-mode.  Most free
    1.79 +  operating systems package it, or its home page is here:
    1.80 +
    1.81 +      http://www.lysator.liu.se/projects/about_psgml.html
    1.82 +
    1.83 +  If you use vim, you might check out xmledit, at:
    1.84 +
    1.85 +      http://www.vim.org/scripts/script.php?script_id=301
    1.86 +
    1.87 +
    1.88 +2. Get a validating parser.
    1.89 +
    1.90 +  Actually, if you have what you need to compile the documentation,
    1.91 +  then you almost certainly have an XML validator installed already -
    1.92 +  it is called xmllint, and comes as part of libxml2.
    1.93 +
    1.94 +  The makefile is preconfigured with a suitable invocation of it,
    1.95 +  so simply run:
    1.96 +
    1.97 +      $ make validate
    1.98 +
    1.99 +3. Read about DocBook.
   1.100 +
   1.101 +  You'll want to get real intimate with a DocBook reference, such as
   1.102 +  can be found at:  http://www.docbook.org/tdg/en/html/