hgbook
annotate README.BUILD @ 1114:527b86d55d4a
inotify: update installation information
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author | Nicolas Dumazet <nicdumz.commits@gmail.com> |
---|---|
date | Sun Dec 13 16:35:56 2009 +0900 (2009-12-13) |
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/ |