hgbook

annotate README.BUILD @ 666:d8c85d831fb4

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