hgbook

annotate README.BUILD @ 1049:e7ce6a9f50c7

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