hgbook

view README.BUILD @ 1101:5b6b0d5fc1b8

find changesets by author, revision, files, or words in the commit message
2.7.3 zh translated
author Zhaoping Sun <zhaopingsun@gmail.com>
date Wed Nov 25 08:08:20 2009 -0500 (2009-11-25)
parents 4688f8ac941d
children
line source
1 HOW-TO: Compiling the Mercurial Book
2 ======================================
3
4 This Mercurial Book is written in DocBook 4.5.
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.
10
11 Table of Contents:
12
13 I. PRIMER
14 II. COMPILING THE DOCS
15 III. HACKING ON THE DOCS
16
17 I. PRIMER
18
19 DocBook has a tortured, confusing history. Before you do anything,
20 take a look at:
21
22 http://wiki.docbook.org/topic/DocBookTutorials
23
24 II. COMPILING THE DOCS
25
26 1. Install XML DTD and XSL stylesheets for DocBook
27
28 % sudo apt-get install docbook-xml docbook-xsl
29
30 2. Install libxml2-utils
31
32 % sudo apt-get install libxml2-utils
33
34 3. Install graph drawing and patches tools
35
36 % sudo apt-get install graphviz inkscape patchutils
37
38 4. Install pdf support
39
40 % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
41
42 The Makefile will actually invoke $FOP_HOME/fop.sh, you should do
43 some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
44
45 5. Configure XML Catalogs
46 For non pdf output, we use xsltproc for XSLT process, xsltproc use system
47 catalog files automatically, usually /etc/xml/catalog. Users do not need to
48 care about it.
49
50 For pdf output, we need use the xsl extensions (docbook-xsl-saxon), so we must
51 create file $JAVA_LIB/CatalogManager.properties like this:
52
53 catalogs=/etc/xml/catalog
54 relative-catalogs=true
55 static-catalog=yes
56 catalog-class-name=org.apache.xml.resolver.Resolver
57 verbosity=1
58
59 6. Create Makefile.vars
60 Please create your Makefile.vars from Makefile.vars.tmpl .
61
62 7. Make
63 Run 'make' for more details, for example:
64
65 * make all document(pdf, epub, html and html-single for all languages)
66 % make all
67
68 * make english document(pdf, epub, html and html-single for all languages)
69 % make LINGUA=en all
70
71 * make Chinese document(pdf, epub, html and html-single for all languages)
72 % make LINGUA=zh all
73
74 * make Chinese pdf document
75 % make LINGUA=zh pdf
76
77 III. HACKING ON THE DOCS
78
79 In addition to everything in section II:
80
81 1. Get a nice editing environment for XML
82
83 This isn't strictly required, but it's nice when your editor
84 colorizes things, understands the DTD, tells you what tags you can
85 insert, etc.
86
87 If you use emacs, we recommend the nxml-mode. Most free
88 operating systems package it, or its home page is here:
89
90 http://www.emacswiki.org/emacs/NxmlMode
91
92 If you use vim, you might check out xmledit, at:
93
94 http://www.vim.org/scripts/script.php?script_id=301
95
96 2. Get a validating parser
97
98 Actually, if you have what you need to compile the documentation,
99 then you almost certainly have an XML validator installed already -
100 it is called xmllint, and comes as part of libxml2.
101
102 The makefile is preconfigured with a suitable invocation of it,
103 so simply run:
104
105 $ make validate
106
107 3. Read about DocBook
108
109 You'll want to get real intimate with a DocBook reference, such as
110 can be found at: http://www.docbook.org/tdg/en/html/