Mercurial > hgbook

changeset 725:83a687a996b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Basically completed Docbook xml make environment
author Dongsheng Song <dongsheng.song@gmail.com>
date Thu, 12 Mar 2009 15:52:36 +0800
parents cfdb601a3c8b
children 8271c8891b0e
files Makefile README
diffstat 2 files changed, 293 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Makefile	Thu Mar 12 15:52:36 2009 +0800
@@ -0,0 +1,194 @@
+#
+# Makefile for the hgbook, top-level
+#
+
+FORMATS=html html-single pdf
+
+PO_LANGUAGES := zh
+DBK_LANGUAGES := en
+LANGUAGES := $(DBK_LANGUAGES) $(PO_LANGUAGES)
+
+UPDATEPO = PERLLIB=../tools/po4a/lib/ ../tools/po4a/po4a-updatepo -M UTF-8 \
+	   -f docbook -o doctype='docbook' -o includeexternal \
+	   -o nodefault='<programlisting> <screen>' \
+	   -o untranslated='<programlisting> <screen>'
+TRANSLATE = PERLLIB=tools/po4a/lib/ tools/po4a/po4a-translate -M UTF-8 \
+	   -f docbook -o doctype='docbook' \
+	   -k 0
+
+#rev_id = $(shell hg parents --template '{node|short} ({date|isodate})')
+rev_id = $(shell hg parents --template '{node|short} ({date|shortdate})')
+
+images := \
+	en/images/feature-branches.png \
+	en/images/filelog.png \
+	en/images/metadata.png \
+	en/images/mq-stack.png \
+	en/images/revlog.png \
+	en/images/snapshot.png \
+	en/images/tour-history.png \
+	en/images/tour-merge-conflict.png \
+	en/images/tour-merge-merge.png \
+	en/images/tour-merge-pull.png \
+	en/images/tour-merge-sep-repos.png \
+	en/images/undo-manual-merge.png \
+	en/images/undo-manual.png \
+	en/images/undo-non-tip.png \
+	en/images/undo-simple.png \
+	en/images/wdir-after-commit.png \
+	en/images/wdir-branch.png \
+	en/images/wdir-merge.png \
+	en/images/wdir.png \
+	en/images/wdir-pre-branch.png
+
+help:
+	@echo "  make html         [LINGUA=en|zh|...]"
+	@echo "  make html-single  [LINGUA=en|zh|...]"
+	@echo "  make pdf          [LINGUA=en|zh|...]"
+	@echo "  make validate     [LINGUA=en|zh|...] # always before commit!"
+	@echo "  make tidypo       [LINGUA=zh|...]    # always before commit!"
+	@echo "  make updatepo     [LINGUA=zh|...]    # update po files."
+	@echo "  make all          [LINGUA=en|zh|...]"
+	@echo "  make stat         # print statistics about po files."
+	@echo "  make clean        # Remove the build files."
+
+clean:
+	@rm -fr build po/*.mo
+
+all:
+ifdef LINGUA
+	for f in $(FORMATS); do \
+	  $(MAKE) LINGUA=$(LINGUA) $$f; \
+	done
+else
+	for l in $(LANGUAGES); do \
+	    for f in $(FORMATS); do \
+		$(MAKE) LINGUA=$$l $$f; \
+	    done; \
+	done
+endif
+
+stat:
+	@( \
+	LANG=C; export LANG; cd po; \
+	for f in *.po; do \
+	    printf "%s\t" $$f; \
+	    msgfmt --statistics -c $$f; \
+	done; \
+	)
+
+tidypo:
+ifdef LINGUA
+	msgcat --sort-by-file --width=80 po/$(LINGUA).po > po/$(LINGUA).tmp && \
+	    mv po/$(LINGUA).tmp po/$(LINGUA).po;
+else
+	for po in $(wildcard po/*.po); do \
+	    msgcat --sort-by-file --width=80 $$po > $$po.tmp && mv $$po.tmp $$po; \
+	done
+endif
+
+ifndef LINGUA
+updatepo:
+	for l in $(PO_LANGUAGES); do \
+	    $(MAKE) $@ LINGUA=$$l; \
+	done
+else
+updatepo:
+ifneq "$(findstring $(LINGUA),$(PO_LANGUAGES))" ""
+	(cd po && $(UPDATEPO) -m ../en/00book.xml -p $(LINGUA).po)
+	$(MAKE) tidypo LINGUA=$(LINGUA)
+endif
+endif
+
+ifndef LINGUA
+validate:
+	for l in $(LANGUAGES); do \
+	    $(MAKE) $@ LINGUA=$$l; \
+	done
+else
+validate: build/$(LINGUA)/source/hgbook.xml
+	xmllint --nonet --noout --postvalid --xinclude $<
+
+ifneq "$(findstring $(LINGUA),$(DBK_LANGUAGES))" ""
+build/$(LINGUA)/source/hgbook.xml: $(wildcard $(LINGUA)/*.xml) $(images)
+	mkdir -p build/$(LINGUA)/source
+	cp -r $(LINGUA)/* build/$(LINGUA)/source
+	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp $(LINGUA)/00book.xml
+	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
+else
+build/$(LINGUA)/source/hgbook.xml: $(wildcard en/*.xml) po/$(LINGUA).po $(images)
+	mkdir -p build/$(LINGUA)/source
+	cp -r en/images build/$(LINGUA)/source
+	cp -r en/examples build/$(LINGUA)/source
+	cp en/book-shortcuts.xml build/$(LINGUA)/source
+	for f in en/*.xml; do \
+	  if [ $$f != "en/book-shortcuts.xml" ]; then \
+	    $(TRANSLATE) -m $$f -p po/$(LINGUA).po -l build/$(LINGUA)/source/`basename $$f`; \
+	  fi \
+	done
+	xmllint --nonet --noent --xinclude --postvalid --output $@.tmp build/$(LINGUA)/source/00book.xml
+	cat $@.tmp | sed 's/\$$rev_id\$$/${rev_id}/' > $@
+endif
+
+endif
+
+ifndef LINGUA
+html:
+	for l in $(LANGUAGES); do \
+	    $(MAKE) $@ LINGUA=$$l; \
+	done
+else
+html: build/$(LINGUA)/html/index.html
+
+build/$(LINGUA)/html/index.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html.xsl stylesheets/$(LINGUA)/html.xsl
+	mkdir -p build/$(LINGUA)/html/images
+	cp en/images/*.png build/$(LINGUA)/html/images
+	cp stylesheets/hgbook.css build/$(LINGUA)/html
+	xsltproc --output build/$(LINGUA)/html/ \
+	    stylesheets/$(LINGUA)/html.xsl build/$(LINGUA)/source/hgbook.xml
+endif
+
+ifndef LINGUA
+html-single:
+	for l in $(LANGUAGES); do \
+	    $(MAKE) $@ LINGUA=$$l; \
+	done
+else
+html-single: build/$(LINGUA)/html-single/hgbook.html
+
+build/$(LINGUA)/html-single/hgbook.html: build/$(LINGUA)/source/hgbook.xml stylesheets/html-single.xsl stylesheets/$(LINGUA)/html-single.xsl
+	mkdir -p build/$(LINGUA)/html-single/images
+	cp en/images/*.png build/$(LINGUA)/html-single/images
+	cp stylesheets/hgbook.css build/$(LINGUA)/html-single
+	xsltproc --output build/$(LINGUA)/html-single/hgbook.html \
+	    stylesheets/$(LINGUA)/html-single.xsl build/$(LINGUA)/source/hgbook.xml
+endif
+
+ifndef LINGUA
+pdf:
+	for l in $(LANGUAGES); do \
+	    $(MAKE) $@ LINGUA=$$l; \
+	done
+else
+pdf: build/$(LINGUA)/pdf/hgbook.pdf
+
+build/$(LINGUA)/pdf/hgbook.pdf: build/$(LINGUA)/source/hgbook.xml stylesheets/fo.xsl stylesheets/$(LINGUA)/fo.xsl
+	mkdir -p build/$(LINGUA)/pdf
+	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 \
+	    com.icl.saxon.StyleSheet \
+	    -x org.apache.xml.resolver.tools.ResolvingXMLReader \
+	    -y org.apache.xml.resolver.tools.ResolvingXMLReader \
+	    -r org.apache.xml.resolver.tools.CatalogResolver \
+	    -o build/$(LINGUA)/source/hgbook.fo \
+	    build/$(LINGUA)/source/hgbook.xml \
+	    stylesheets/$(LINGUA)/fo.xsl \
+	    fop1.extensions=1
+
+	(cd build/$(LINGUA)/source && ../../../tools/fop/fop.sh hgbook.fo ../pdf/hgbook.pdf)
+endif
+
+en/images/%.png: en/images/%.svg
+	inkscape -D -d 120 -e $@ $<
+
+en/images/%.svg: en/images/%.dot
+	dot -Tsvg -o $@ $<
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Thu Mar 12 15:52:36 2009 +0800
@@ -0,0 +1,99 @@
+HOW-TO:  Compiling the Mercurial Book
+======================================
+
+This Mercurial Book is written in DocBook 4.5.
+
+The goal of this document is to give simple instructions to anyone who
+wants to compile this book into a useful format, like HTML or PDF.  It
+should state *exactly* which tools to use, and how to invoke them, in
+simplest terms.
+
+Table of Contents:
+
+  I. PRIMER
+ II. COMPILING THE DOCS
+III. HACKING ON THE DOCS
+
+I. PRIMER
+
+  DocBook has a tortured, confusing history.  Before you do anything,
+  take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
+
+      http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
+
+  It's very short and clears up many things.
+
+
+II. COMPILING THE DOCS
+
+
+1. Install XML DTD and XSL stylesheets for DocBook
+
+      % sudo apt-get install docbook-xml docbook-xsl
+
+2. Install libxml2-utils
+
+      % sudo apt-get install libxml2-utils
+
+3. Install graph drawing tools
+
+      % sudo apt-get install graphviz inkscape
+
+4. Install pdf support
+
+      % sudo apt-get install openjdk-6-jdk docbook-xsl-saxon libsaxon-java fop
+
+  The Makefile will actually invoke tools/fop/fop.sh, you should do
+  some trick, let fop's CLASSPATH include saxon.jar and docbook-xsl-saxon.jar .
+
+5. Make
+  Run 'make' for more details, for example:
+
+  * make all document(pdf, html and html-single for all languages)
+      % make all
+
+  * make english document(pdf, html and html-single for all languages)
+      % make LINGUA=en all
+
+  * make Chinese document(pdf, html and html-single for all languages)
+      % make LINGUA=zh all
+
+  * make Chinese pdf document
+      % make LINGUA=zh pdf
+
+III. HACKING ON THE DOCS
+
+In addition to everything in section II:
+
+
+1. Get a nice editing environment for SGML/XML.
+
+  This isn't strictly required, but it's nice when your editor
+  colorizes things, understands the DTD, tells you what tags you can
+  insert, etc.
+
+  If you use emacs, we recommend the PSGML major-mode.  Most free
+  operating systems package it, or its home page is here:
+
+      http://www.lysator.liu.se/projects/about_psgml.html
+
+  If you use vim, you might check out xmledit, at:
+
+      http://www.vim.org/scripts/script.php?script_id=301
+
+
+2. Get a validating parser.
+
+  Actually, if you have what you need to compile the documentation,
+  then you almost certainly have an XML validator installed already -
+  it is called xmllint, and comes as part of libxml2.
+
+  The makefile is preconfigured with a suitable invocation of it,
+  so simply run:
+
+      $ make validate
+
+3. Read about DocBook.
+
+  You'll want to get real intimate with a DocBook reference, such as
+  can be found at:  http://www.docbook.org/tdg/en/html/