hgbook

annotate README.BUILD @ 877:3d6f290fe822

find changesets by author, revision, files, or words in the commit message
Update README.BUILD
author Dongsheng Song <dongsheng.song@gmail.com>
date Wed Oct 21 11:57:11 2009 +0800 (2009-10-21)
parents fb9eed54548a
children 7037e4bcb90c
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
dongsheng@873 46 The Makefile will actually invoke $FOP_HOME/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
dongsheng@877 49 5. Configure XML Catalogs
dongsheng@877 50 For non pdf output, we use xsltproc for XSLT process, which use system
dongsheng@877 51 catalog files automatically, usually /etc/xml/catalog. Users do not need to
dongsheng@877 52 care about it.
dongsheng@877 53
dongsheng@877 54 For pdf output, we need use the xsl extensions (docbook-xsl-saxon), so we must
dongsheng@877 55 create file $JAVA_LIB/CatalogManager.properties like this:
dongsheng@877 56
dongsheng@877 57 catalogs=/etc/xml/catalog
dongsheng@877 58 relative-catalogs=true
dongsheng@877 59 static-catalog=yes
dongsheng@877 60 catalog-class-name=org.apache.xml.resolver.Resolver
dongsheng@877 61 verbosity=1
dongsheng@877 62
dongsheng@877 63 6. Create Makefile.vars
dongsheng@877 64 Please create your Makefile.vars from Makefile.vars.tmpl .
dongsheng@877 65
dongsheng@877 66 7. Make
songdongsheng@666 67 Run 'make' for more details, for example:
songdongsheng@666 68
songdongsheng@666 69 * make all document(pdf, html and html-single for all languages)
songdongsheng@666 70 % make all
songdongsheng@666 71
songdongsheng@666 72 * make english document(pdf, html and html-single for all languages)
songdongsheng@666 73 % make LINGUA=en all
songdongsheng@666 74
songdongsheng@666 75 * make Chinese document(pdf, html and html-single for all languages)
songdongsheng@666 76 % make LINGUA=zh all
songdongsheng@666 77
songdongsheng@666 78 * make Chinese pdf document
songdongsheng@666 79 % make LINGUA=zh pdf
songdongsheng@666 80
songdongsheng@666 81 III. HACKING ON THE DOCS
songdongsheng@666 82
songdongsheng@666 83 In addition to everything in section II:
songdongsheng@666 84
songdongsheng@666 85
songdongsheng@666 86 1. Get a nice editing environment for SGML/XML.
songdongsheng@666 87
songdongsheng@666 88 This isn't strictly required, but it's nice when your editor
songdongsheng@666 89 colorizes things, understands the DTD, tells you what tags you can
songdongsheng@666 90 insert, etc.
songdongsheng@666 91
songdongsheng@666 92 If you use emacs, we recommend the PSGML major-mode. Most free
songdongsheng@666 93 operating systems package it, or its home page is here:
songdongsheng@666 94
songdongsheng@666 95 http://www.lysator.liu.se/projects/about_psgml.html
songdongsheng@666 96
songdongsheng@666 97 If you use vim, you might check out xmledit, at:
songdongsheng@666 98
songdongsheng@666 99 http://www.vim.org/scripts/script.php?script_id=301
songdongsheng@666 100
songdongsheng@666 101
songdongsheng@666 102 2. Get a validating parser.
songdongsheng@666 103
songdongsheng@666 104 Actually, if you have what you need to compile the documentation,
songdongsheng@666 105 then you almost certainly have an XML validator installed already -
songdongsheng@666 106 it is called xmllint, and comes as part of libxml2.
songdongsheng@666 107
songdongsheng@666 108 The makefile is preconfigured with a suitable invocation of it,
songdongsheng@666 109 so simply run:
songdongsheng@666 110
songdongsheng@666 111 $ make validate
songdongsheng@666 112
songdongsheng@666 113 3. Read about DocBook.
songdongsheng@666 114
songdongsheng@666 115 You'll want to get real intimate with a DocBook reference, such as
songdongsheng@666 116 can be found at: http://www.docbook.org/tdg/en/html/