hgbook
view README.BUILD @ 814:99c201b30491
Minor changes and translation of code snippets for Ch.13.
| author | Giulio@puck |
|---|---|
| date | Sat Aug 15 18:03:50 2009 +0200 (2009-08-15) |
| parents | a21668c4af50 |
| children | fb9eed54548a |
line source
1 HOW-TO: Compiling the Mercurial Book
2 ======================================
4 This Mercurial Book is written in DocBook 4.5.
6 The goal of this document is to give simple instructions to anyone who
7 wants to compile this book into a useful format, like HTML or PDF. It
8 should state *exactly* which tools to use, and how to invoke them, in
9 simplest terms.
11 Table of Contents:
13 I. PRIMER
14 II. COMPILING THE DOCS
15 III. HACKING ON THE DOCS
17 I. PRIMER
19 DocBook has a tortured, confusing history. Before you do anything,
20 take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
22 http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
24 It's very short and clears up many things.
27 II. COMPILING THE DOCS
30 1. Install XML DTD and XSL stylesheets for DocBook
32 % sudo apt-get install docbook-xml docbook-xsl
34 2. Install libxml2-utils
36 % sudo apt-get install libxml2-utils
38 3. Install graph drawing tools
40 % sudo apt-get install graphviz inkscape
42 4. Install pdf support
44 % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
46 The Makefile will actually invoke tools/fop/fop.sh, you should do
47 some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
49 5. Make
50 Run 'make' for more details, for example:
52 * make all document(pdf, html and html-single for all languages)
53 % make all
55 * make english document(pdf, html and html-single for all languages)
56 % make LINGUA=en all
58 * make Chinese document(pdf, html and html-single for all languages)
59 % make LINGUA=zh all
61 * make Chinese pdf document
62 % make LINGUA=zh pdf
64 III. HACKING ON THE DOCS
66 In addition to everything in section II:
69 1. Get a nice editing environment for SGML/XML.
71 This isn't strictly required, but it's nice when your editor
72 colorizes things, understands the DTD, tells you what tags you can
73 insert, etc.
75 If you use emacs, we recommend the PSGML major-mode. Most free
76 operating systems package it, or its home page is here:
78 http://www.lysator.liu.se/projects/about_psgml.html
80 If you use vim, you might check out xmledit, at:
82 http://www.vim.org/scripts/script.php?script_id=301
85 2. Get a validating parser.
87 Actually, if you have what you need to compile the documentation,
88 then you almost certainly have an XML validator installed already -
89 it is called xmllint, and comes as part of libxml2.
91 The makefile is preconfigured with a suitable invocation of it,
92 so simply run:
94 $ make validate
96 3. Read about DocBook.
98 You'll want to get real intimate with a DocBook reference, such as
99 can be found at: http://www.docbook.org/tdg/en/html/