annotate README @ 730:f7d674e6e736

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