hgbook
changeset 626:83a687a996b2
Basically completed Docbook xml make environment
author | Dongsheng Song <dongsheng.song@gmail.com> |
---|---|
date | Thu Mar 12 15:52:36 2009 +0800 (2009-03-12) |
parents | cfdb601a3c8b |
children | 8271c8891b0e |
files | Makefile README |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/Makefile Thu Mar 12 15:52:36 2009 +0800 1.3 @@ -0,0 +1,194 @@ 1.4 +# 1.5 +# Makefile for the hgbook, top-level 1.6 +# 1.7 + 1.8 +FORMATS=html html-single pdf 1.9 + 1.10 +PO_LANGUAGES := zh 1.11 +DBK_LANGUAGES := en 1.12 +LANGUAGES := $(DBK_LANGUAGES) $(PO_LANGUAGES) 1.13 + 1.14 +UPDATEPO = PERLLIB=../tools/po4a/lib/ ../tools/po4a/po4a-updatepo -M UTF-8 \ 1.15 + -f docbook -o doctype='docbook' -o includeexternal \ 1.16 + -o nodefault='<programlisting> <screen>' \ 1.17 + -o untranslated='<programlisting> <screen>' 1.18 +TRANSLATE = PERLLIB=tools/po4a/lib/ tools/po4a/po4a-translate -M UTF-8 \ 1.19 + -f docbook -o doctype='docbook' \ 1.20 + -k 0 1.21 + 1.22 +#rev_id = $(shell hg parents --template '{node|short} ({date|isodate})') 1.23 +rev_id = $(shell hg parents --template '{node|short} ({date|shortdate})') 1.24 + 1.25 +images := \ 1.26 + en/images/feature-branches.png \ 1.27 + en/images/filelog.png \ 1.28 + en/images/metadata.png \ 1.29 + en/images/mq-stack.png \ 1.30 + en/images/revlog.png \ 1.31 + en/images/snapshot.png \ 1.32 + en/images/tour-history.png \ 1.33 + en/images/tour-merge-conflict.png \ 1.34 + en/images/tour-merge-merge.png \ 1.35 + en/images/tour-merge-pull.png \ 1.36 + en/images/tour-merge-sep-repos.png \ 1.37 + en/images/undo-manual-merge.png \ 1.38 + en/images/undo-manual.png \ 1.39 + en/images/undo-non-tip.png \ 1.40 + en/images/undo-simple.png \ 1.41 + en/images/wdir-after-commit.png \ 1.42 + en/images/wdir-branch.png \ 1.43 + en/images/wdir-merge.png \ 1.44 + en/images/wdir.png \ 1.45 + en/images/wdir-pre-branch.png 1.46 + 1.47 +help: 1.48 + @echo " make html [LINGUA=en|zh|...]" 1.49 + @echo " make html-single [LINGUA=en|zh|...]" 1.50 + @echo " make pdf [LINGUA=en|zh|...]" 1.51 + @echo " make validate [LINGUA=en|zh|...] # always before commit!" 1.52 + @echo " make tidypo [LINGUA=zh|...] # always before commit!" 1.53 + @echo " make updatepo [LINGUA=zh|...] # update po files." 1.54 + @echo " make all [LINGUA=en|zh|...]" 1.55 + @echo " make stat # print statistics about po files." 1.56 + @echo " make clean # Remove the build files." 1.57 + 1.58 +clean: 1.59 + @rm -fr build po/*.mo 1.60 + 1.61 +all: 1.62 +ifdef LINGUA 1.63 + for f in $(FORMATS); do \ 1.64 + $(MAKE) LINGUA=$(LINGUA) $$f; \ 1.65 + done 1.66 +else 1.67 + for l in $(LANGUAGES); do \ 1.68 + for f in $(FORMATS); do \ 1.69 + $(MAKE) LINGUA=$$l $$f; \ 1.70 + done; \ 1.71 + done 1.72 +endif 1.73 + 1.74 +stat: 1.75 + @( \ 1.76 + LANG=C; export LANG; cd po; \ 1.77 + for f in *.po; do \ 1.78 + printf "%s\t" $$f; \ 1.79 + msgfmt --statistics -c $$f; \ 1.80 + done; \ 1.81 + ) 1.82 + 1.83 +tidypo: 1.84 +ifdef LINGUA 1.85 + msgcat --sort-by-file --width=80 po/$(LINGUA).po > po/$(LINGUA).tmp && \ 1.86 + mv po/$(LINGUA).tmp po/$(LINGUA).po; 1.87 +else 1.88 + for po in $(wildcard po/*.po); do \ 1.89 + msgcat --sort-by-file --width=80 $$po > $$po.tmp && mv $$po.tmp $$po; \ 1.90 + done 1.91 +endif 1.92 + 1.93 +ifndef LINGUA 1.94 +updatepo: 1.95 + for l in $(PO_LANGUAGES); do \ 1.96 + $(MAKE) $@ LINGUA=$$l; \ 1.97 + done 1.98 +else 1.99 +updatepo: 1.100 +ifneq "$(findstring $(LINGUA),$(PO_LANGUAGES))" "" 1.101 + (cd po && $(UPDATEPO) -m ../en/00book.xml -p $(LINGUA).po) 1.102 + $(MAKE) tidypo LINGUA=$(LINGUA) 1.103 +endif 1.104 +endif 1.105 + 1.106 +ifndef LINGUA 1.107 +validate: 1.108 + for l in $(LANGUAGES); do \ 1.109 + $(MAKE) $@ LINGUA=$$l; \ 1.110 + done 1.111 +else 1.112 +validate: build/$(LINGUA)/source/hgbook.xml 1.113 + xmllint --nonet --noout --postvalid --xinclude $< 1.114 + 1.115 +ifneq "$(findstring $(LINGUA),$(DBK_LANGUAGES))" "" 1.116 +build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images) 1.117 + mkdir -p build/$(LINGUA)/source 1.118 + cp -r $(LINGUA)/* build/$(LINGUA)/source 1.119 + xmllint --nonet --noent --xinclude --postvalid --output $@.tmp $(LINGUA)/00book.xml 1.120 + cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@ 1.121 +else 1.122 +build/$(LINGUA)/source/hgbook.xml: $(wildcard en/*.xml) po/$(LINGUA).po $(images) 1.123 + mkdir -p build/$(LINGUA)/source 1.124 + cp -r en/images build/$(LINGUA)/source 1.125 + cp -r en/examples build/$(LINGUA)/source 1.126 + cp en/book-shortcuts.xml build/$(LINGUA)/source 1.127 + for f in en/*.xml; do \ 1.128 + if [ $$f != "en/book-shortcuts.xml" ]; then \ 1.129 + $(TRANSLATE) -m $$f -p po/$(LINGUA).po -l build/$(LINGUA)/source/`basename $$f`; \ 1.130 + fi \ 1.131 + done 1.132 + xmllint --nonet --noent --xinclude --postvalid --output $@.tmp build/$(LINGUA)/source/00book.xml 1.133 + cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@ 1.134 +endif 1.135 + 1.136 +endif 1.137 + 1.138 +ifndef LINGUA 1.139 +html: 1.140 + for l in $(LANGUAGES); do \ 1.141 + $(MAKE) $@ LINGUA=$$l; \ 1.142 + done 1.143 +else 1.144 +html: build/$(LINGUA)/html/index.html 1.145 + 1.146 +build/$(LINGUA)/html/index.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html.xsl stylesheets/$(LINGUA)/html.xsl 1.147 + mkdir -p build/$(LINGUA)/html/images 1.148 + cp en/images/*.png build/$(LINGUA)/html/images 1.149 + cp stylesheets/hgbook.css build/$(LINGUA)/html 1.150 + xsltproc --output build/$(LINGUA)/html/ \ 1.151 + stylesheets/$(LINGUA)/html.xsl build/$(LINGUA)/source/hgbook.xml 1.152 +endif 1.153 + 1.154 +ifndef LINGUA 1.155 +html-single: 1.156 + for l in $(LANGUAGES); do \ 1.157 + $(MAKE) $@ LINGUA=$$l; \ 1.158 + done 1.159 +else 1.160 +html-single: build/$(LINGUA)/html-single/hgbook.html 1.161 + 1.162 +build/$(LINGUA)/html-single/hgbook.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html-single.xsl stylesheets/$(LINGUA)/html-single.xsl 1.163 + mkdir -p build/$(LINGUA)/html-single/images 1.164 + cp en/images/*.png build/$(LINGUA)/html-single/images 1.165 + cp stylesheets/hgbook.css build/$(LINGUA)/html-single 1.166 + xsltproc --output build/$(LINGUA)/html-single/hgbook.html \ 1.167 + stylesheets/$(LINGUA)/html-single.xsl build/$(LINGUA)/source/hgbook.xml 1.168 +endif 1.169 + 1.170 +ifndef LINGUA 1.171 +pdf: 1.172 + for l in $(LANGUAGES); do \ 1.173 + $(MAKE) $@ LINGUA=$$l; \ 1.174 + done 1.175 +else 1.176 +pdf: build/$(LINGUA)/pdf/hgbook.pdf 1.177 + 1.178 +build/$(LINGUA)/pdf/hgbook.pdf: build/$(LINGUA)/source/hgbook.xml stylesheets/fo.xsl stylesheets/$(LINGUA)/fo.xsl 1.179 + mkdir -p build/$(LINGUA)/pdf 1.180 + java -classpath tools/fop/lib/saxon65.jar:tools/fop/lib/saxon65-dbxsl.jar:tools/fop/lib/xml-commons-resolver-1.2.jar:tools/fop/conf \ 1.181 + com.icl.saxon.StyleSheet \ 1.182 + -x org.apache.xml.resolver.tools.ResolvingXMLReader \ 1.183 + -y org.apache.xml.resolver.tools.ResolvingXMLReader \ 1.184 + -r org.apache.xml.resolver.tools.CatalogResolver \ 1.185 + -o build/$(LINGUA)/source/hgbook.fo \ 1.186 + build/$(LINGUA)/source/hgbook.xml \ 1.187 + stylesheets/$(LINGUA)/fo.xsl \ 1.188 + fop1.extensions=1 1.189 + 1.190 + (cd build/$(LINGUA)/source && ../../../tools/fop/fop.sh hgbook.fo ../pdf/hgbook.pdf) 1.191 +endif 1.192 + 1.193 +en/images/%.png: en/images/%.svg 1.194 + inkscape -D -d 120 -e $@ $< 1.195 + 1.196 +en/images/%.svg: en/images/%.dot 1.197 + dot -Tsvg -o $@ $<
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 2.2 +++ b/README Thu Mar 12 15:52:36 2009 +0800 2.3 @@ -0,0 +1,99 @@ 2.4 +HOW-TO: Compiling the Mercurial Book 2.5 +====================================== 2.6 + 2.7 +This Mercurial Book is written in DocBook 4.5. 2.8 + 2.9 +The goal of this document is to give simple instructions to anyone who 2.10 +wants to compile this book into a useful format, like HTML or PDF. It 2.11 +should state *exactly* which tools to use, and how to invoke them, in 2.12 +simplest terms. 2.13 + 2.14 +Table of Contents: 2.15 + 2.16 + I. PRIMER 2.17 + II. COMPILING THE DOCS 2.18 +III. HACKING ON THE DOCS 2.19 + 2.20 +I. PRIMER 2.21 + 2.22 + DocBook has a tortured, confusing history. Before you do anything, 2.23 + take a look at Eric Raymond's excellent "DocBook Demystification HOWTO": 2.24 + 2.25 + http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/ 2.26 + 2.27 + It's very short and clears up many things. 2.28 + 2.29 + 2.30 +II. COMPILING THE DOCS 2.31 + 2.32 + 2.33 +1. Install XML DTD and XSL stylesheets for DocBook 2.34 + 2.35 + % sudo apt-get install docbook-xml docbook-xsl 2.36 + 2.37 +2. Install libxml2-utils 2.38 + 2.39 + % sudo apt-get install libxml2-utils 2.40 + 2.41 +3. Install graph drawing tools 2.42 + 2.43 + % sudo apt-get install graphviz inkscape 2.44 + 2.45 +4. Install pdf support 2.46 + 2.47 + % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop 2.48 + 2.49 + The Makefile will actually invoke tools/fop/fop.sh, you should do 2.50 + some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar . 2.51 + 2.52 +5. Make 2.53 + Run 'make' for more details, for example: 2.54 + 2.55 + * make all document(pdf, html and html-single for all languages) 2.56 + % make all 2.57 + 2.58 + * make english document(pdf, html and html-single for all languages) 2.59 + % make LINGUA=en all 2.60 + 2.61 + * make Chinese document(pdf, html and html-single for all languages) 2.62 + % make LINGUA=zh all 2.63 + 2.64 + * make Chinese pdf document 2.65 + % make LINGUA=zh pdf 2.66 + 2.67 +III. HACKING ON THE DOCS 2.68 + 2.69 +In addition to everything in section II: 2.70 + 2.71 + 2.72 +1. Get a nice editing environment for SGML/XML. 2.73 + 2.74 + This isn't strictly required, but it's nice when your editor 2.75 + colorizes things, understands the DTD, tells you what tags you can 2.76 + insert, etc. 2.77 + 2.78 + If you use emacs, we recommend the PSGML major-mode. Most free 2.79 + operating systems package it, or its home page is here: 2.80 + 2.81 + http://www.lysator.liu.se/projects/about_psgml.html 2.82 + 2.83 + If you use vim, you might check out xmledit, at: 2.84 + 2.85 + http://www.vim.org/scripts/script.php?script_id=301 2.86 + 2.87 + 2.88 +2. Get a validating parser. 2.89 + 2.90 + Actually, if you have what you need to compile the documentation, 2.91 + then you almost certainly have an XML validator installed already - 2.92 + it is called xmllint, and comes as part of libxml2. 2.93 + 2.94 + The makefile is preconfigured with a suitable invocation of it, 2.95 + so simply run: 2.96 + 2.97 + $ make validate 2.98 + 2.99 +3. Read about DocBook. 2.100 + 2.101 + You'll want to get real intimate with a DocBook reference, such as 2.102 + can be found at: http://www.docbook.org/tdg/en/html/