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