songdongsheng@666: HOW-TO: Compiling the Mercurial Book songdongsheng@666: ====================================== bos@605: songdongsheng@666: This Mercurial Book is written in DocBook 4.5. bos@605: songdongsheng@666: The goal of this document is to give simple instructions to anyone who songdongsheng@666: wants to compile this book into a useful format, like HTML or PDF. It songdongsheng@666: should state *exactly* which tools to use, and how to invoke them, in songdongsheng@666: simplest terms. bos@605: songdongsheng@666: Table of Contents: bos@605: songdongsheng@666: I. PRIMER songdongsheng@666: II. COMPILING THE DOCS songdongsheng@666: III. HACKING ON THE DOCS songdongsheng@666: songdongsheng@666: I. PRIMER songdongsheng@666: dongsheng@879: DocBook has a tortured, confusing history. Before you do anything, dongsheng@879: take a look at: songdongsheng@666: dongsheng@879: http://wiki.docbook.org/topic/DocBookTutorials songdongsheng@666: songdongsheng@666: II. COMPILING THE DOCS songdongsheng@666: songdongsheng@666: 1. Install XML DTD and XSL stylesheets for DocBook songdongsheng@666: songdongsheng@666: % sudo apt-get install docbook-xml docbook-xsl songdongsheng@666: songdongsheng@666: 2. Install libxml2-utils songdongsheng@666: songdongsheng@666: % sudo apt-get install libxml2-utils songdongsheng@666: dongsheng@884: 3. Install graph drawing and patches tools songdongsheng@666: dongsheng@884: % sudo apt-get install graphviz inkscape patchutils songdongsheng@666: songdongsheng@666: 4. Install pdf support songdongsheng@666: songdongsheng@666: % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop songdongsheng@666: dongsheng@873: The Makefile will actually invoke $FOP_HOME/fop.sh, you should do songdongsheng@666: some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar . songdongsheng@666: dongsheng@877: 5. Configure XML Catalogs dongsheng@879: For non pdf output, we use xsltproc for XSLT process, xsltproc use system dongsheng@877: catalog files automatically, usually /etc/xml/catalog. Users do not need to dongsheng@877: care about it. dongsheng@877: dongsheng@877: For pdf output, we need use the xsl extensions (docbook-xsl-saxon), so we must dongsheng@877: create file $JAVA_LIB/CatalogManager.properties like this: dongsheng@877: dongsheng@877: catalogs=/etc/xml/catalog dongsheng@877: relative-catalogs=true dongsheng@877: static-catalog=yes dongsheng@877: catalog-class-name=org.apache.xml.resolver.Resolver dongsheng@877: verbosity=1 dongsheng@877: dongsheng@877: 6. Create Makefile.vars dongsheng@877: Please create your Makefile.vars from Makefile.vars.tmpl . dongsheng@877: dongsheng@877: 7. Make songdongsheng@666: Run 'make' for more details, for example: songdongsheng@666: dongsheng@878: * make all document(pdf, epub, html and html-single for all languages) songdongsheng@666: % make all songdongsheng@666: dongsheng@878: * make english document(pdf, epub, html and html-single for all languages) songdongsheng@666: % make LINGUA=en all songdongsheng@666: dongsheng@878: * make Chinese document(pdf, epub, html and html-single for all languages) songdongsheng@666: % make LINGUA=zh all songdongsheng@666: songdongsheng@666: * make Chinese pdf document songdongsheng@666: % make LINGUA=zh pdf songdongsheng@666: songdongsheng@666: III. HACKING ON THE DOCS songdongsheng@666: songdongsheng@666: In addition to everything in section II: songdongsheng@666: dongsheng@879: 1. Get a nice editing environment for XML songdongsheng@666: songdongsheng@666: This isn't strictly required, but it's nice when your editor songdongsheng@666: colorizes things, understands the DTD, tells you what tags you can songdongsheng@666: insert, etc. songdongsheng@666: dongsheng@879: If you use emacs, we recommend the nxml-mode. Most free songdongsheng@666: operating systems package it, or its home page is here: songdongsheng@666: dongsheng@879: http://www.emacswiki.org/emacs/NxmlMode songdongsheng@666: songdongsheng@666: If you use vim, you might check out xmledit, at: songdongsheng@666: songdongsheng@666: http://www.vim.org/scripts/script.php?script_id=301 songdongsheng@666: dongsheng@879: 2. Get a validating parser songdongsheng@666: songdongsheng@666: Actually, if you have what you need to compile the documentation, songdongsheng@666: then you almost certainly have an XML validator installed already - songdongsheng@666: it is called xmllint, and comes as part of libxml2. songdongsheng@666: songdongsheng@666: The makefile is preconfigured with a suitable invocation of it, songdongsheng@666: so simply run: songdongsheng@666: songdongsheng@666: $ make validate songdongsheng@666: dongsheng@879: 3. Read about DocBook songdongsheng@666: songdongsheng@666: You'll want to get real intimate with a DocBook reference, such as songdongsheng@666: can be found at: http://www.docbook.org/tdg/en/html/