Mercurial > hgbook
annotate README.BUILD @ 818:75ccc1e89aef
Add paragraph IDS
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun, 26 Apr 2009 23:22:28 -0700 |
parents | d8c85d831fb4 |
children |
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 | 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 | 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 | 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 | 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/ |