hgbook
view README.BUILD @ 878:7037e4bcb90c
Minor fix
| author | Dongsheng Song <dongsheng.song@gmail.com> |
|---|---|
| date | Wed Oct 21 14:26:58 2009 +0800 (2009-10-21) |
| parents | 3d6f290fe822 |
| children | 4688f8ac941d |
line source
1 HOW-TO: Compiling the Mercurial Book
2 ======================================
4 This Mercurial Book is written in DocBook 4.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.
11 Table of Contents:
13 I. PRIMER
14 II. COMPILING THE DOCS
15 III. HACKING ON THE DOCS
17 I. PRIMER
19 DocBook has a tortured, confusing history. Before you do anything,
20 take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
22 http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
24 It's very short and clears up many things.
27 II. COMPILING THE DOCS
30 1. Install XML DTD and XSL stylesheets for DocBook
32 % sudo apt-get install docbook-xml docbook-xsl
34 2. Install libxml2-utils
36 % sudo apt-get install libxml2-utils
38 3. Install graph drawing tools
40 % sudo apt-get install graphviz inkscape
42 4. Install pdf support
44 % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
46 The Makefile will actually invoke $FOP_HOME/fop.sh, you should do
47 some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
49 5. Configure XML Catalogs
50 For non pdf output, we use xsltproc for XSLT process, which use system
51 catalog files automatically, usually /etc/xml/catalog. Users do not need to
52 care about it.
54 For pdf output, we need use the xsl extensions (docbook-xsl-saxon), so we must
55 create file $JAVA_LIB/CatalogManager.properties like this:
57 catalogs=/etc/xml/catalog
58 relative-catalogs=true
59 static-catalog=yes
60 catalog-class-name=org.apache.xml.resolver.Resolver
61 verbosity=1
63 6. Create Makefile.vars
64 Please create your Makefile.vars from Makefile.vars.tmpl .
66 7. Make
67 Run 'make' for more details, for example:
69 * make all document(pdf, epub, html and html-single for all languages)
70 % make all
72 * make english document(pdf, epub, html and html-single for all languages)
73 % make LINGUA=en all
75 * make Chinese document(pdf, epub, html and html-single for all languages)
76 % make LINGUA=zh all
78 * make Chinese pdf document
79 % make LINGUA=zh pdf
81 III. HACKING ON THE DOCS
83 In addition to everything in section II:
86 1. Get a nice editing environment for SGML/XML.
88 This isn't strictly required, but it's nice when your editor
89 colorizes things, understands the DTD, tells you what tags you can
90 insert, etc.
92 If you use emacs, we recommend the PSGML major-mode. Most free
93 operating systems package it, or its home page is here:
95 http://www.lysator.liu.se/projects/about_psgml.html
97 If you use vim, you might check out xmledit, at:
99 http://www.vim.org/scripts/script.php?script_id=301
102 2. Get a validating parser.
104 Actually, if you have what you need to compile the documentation,
105 then you almost certainly have an XML validator installed already -
106 it is called xmllint, and comes as part of libxml2.
108 The makefile is preconfigured with a suitable invocation of it,
109 so simply run:
111 $ make validate
113 3. Read about DocBook.
115 You'll want to get real intimate with a DocBook reference, such as
116 can be found at: http://www.docbook.org/tdg/en/html/