annotate README.BUILD @ 814:e9154b3daa94

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