hgbook

annotate README @ 629:bae6d1503482

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