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/