How to translate "The Definitive Guide".
This memo describes how to translate "The Definitive Guide"
to each native language, but English. Our bible is written
as XML documents to generate many kind of other documents easily,
e.g. a large HTML file, many chunked HTML files, PDF document,
and so on.
Doing such tasks auto-magically, Subversion uses "DocBook"
documentation framework, but the system is fairly complex
to many newbies just like me. Using this framework, you
should translate *.xml files first, then generate HTML
files from them.
You may take another strategy, that is, translate some
generated files directly. For example, a large HTML file named
"book.html" itself.
but it's not practical. You'll be ruined, I promise.
The Guide has not been finished yet. It continues to grow up
as well as source code itself.
If you translate some output files rather than original XML sources,
sooner or later you won't be able to catch up with the
original changes.
So I took below steps. Using this way, I managed to translate The
Guide to Japanese and generate HTML files successfully.
I hope this memo will be useful for anyone who is trying to
translate to his/her own language.
=====================================================================
1. Get a subversion's original document.
First of all, You have to get the original document with
its auto generation system of Subversion. You can get tarball,
or use "svn co" to get more fresh revision. For our purpose,
It's enough to get only /doc/book directory.
If you use "svn co", you can type following:
------------------------------------------------------------------
[tez@tezzy booklabo]$ svn co http://svn.collab.net/repos/svn/trunk/doc/book book
A book/HACKING
A book/Makefile
... ( snip ) ...
A book/book/images/ch02dia1.png
A book/book/images/DirectoryModels.ppt
Checked out revision 5431.
[tez@tezzy booklabo]$ cd book
[tez@tezzy book]$ ls
HACKING Makefile README book misc-docs outline.txt tools
[tez@tezzy book]$
------------------------------------------------------------------
You can also get a tarball, such as "subversion-0.19.1.tar.gz", and
extract /doc/book part. It's up to you.
It's very important for us to save the revision. This case, it's
5431. Without the revision, It's very hard to track the original XML document
after it'll be changed.
2. Get docbook-xsl.
As stated in "HACKING" file, you can download "docbook-xsl" from somewhere.
I used "docbook-xsl-1.60.1.tar.gz". Un-tar it, and mv.
------------------------------------------------------------------
[tez@tezzy tools]$ tar zxvf /tmp/docbook-xsl-1.60.1.tar.gz
docbook-xsl-1.60.1/
docbook-xsl-1.60.1/BUGS
... ( snip ) ...
docbook-xsl-1.60.1/xhtml/ChangeLog
docbook-xsl-1.60.1/xhtml/chunkfast.xsl
[tez@tezzy tools]$ ls
bin docbook-xsl-1.60.1 dtd fo-stylesheet.xsl readme-dblite.html svnbook.el
[tez@tezzy tools]$ mv docbook-xsl-1.60.1 xsl
[tez@tezzy tools]$ ls
bin dtd fo-stylesheet.xsl readme-dblite.html svnbook.el xsl
[tez@tezzy tools]$
------------------------------------------------------------------
3. Edit some files.
I found that we have to modify the following files for each language.
3.1. tools/xsl/html/docbook.xsl:
You can see the following lines in it.
--------------------------------------------
--------------------------------------------
If you want to use another charset in the output HTML files,
change the "encoding=" part. As for me, I modified by
--------------------------------------------
--------------------------------------------
"Shift-JIS" is one of the most popular charset in Japan.
3.2. book/book.xml:
You can see the following line in it.
-----
-----
I modified the line as:
-----
-----
There are many xx.html files in tools/xsl/common directory,
where 'xx' represents each country code. I guess they
correspond to the above lang parameter. Because I want
to use Japanese environment, I set 'ja'.
3.3. tools/xsl/html/chunker.xsl:
--------------------------------------------
--------------------------------------------
I modified the line as:
--------------------------------------------
--------------------------------------------
4. Edit the book/*.xml files.
Burnout ? :)
OK, Let's roll. It's your turn.
4.1. Insert tag at the top of *.xml.
Each book/*.xml file doesn't have such line
at the beginning. But under my language environment,
the following line was inevitable.
--------------------------------------------
--------------------------------------------
As I've already said, "Shift_JIS" is my charset.
( Do not ask me about the difference between "Shift-JIS"
and "Shift_JIS". It's a very long story... )
4.2. Translate the contents, by your own hand.
Hang in there !!!!
5. Generate HTML files.
Finished ?
Before generating HTML files, book/book.html must be deleted, or
you can not update it. I don't know why.
"make all-html" in our top directory.
This makes both a large HTML file and a collection of many
HTML chunk files in the "book" directory.
---------------------------------------------------------------
[tez@tezzy book]$ ls
HACKING Makefile README book misc-docs outline.txt tools
[tez@tezzy book]$ cd book
[tez@tezzy book]$ ls
appa.xml appd.xml book.html ch01.xml ch04.xml ch07.xml copyright.xml images
appb.xml appe.xml book.xml ch02.xml ch05.xml ch08.xml glossary.xml styles.css
appc.xml appf.xml ch00.xml ch03.xml ch06.xml colo.xml html-chunk
[tez@tezzy book]$ rm -f book.html
[tez@tezzy book]$ cd ..
[tez@tezzy book]$ ls
HACKING Makefile README book misc-docs outline.txt tools
[tez@tezzy book]$ make all-html
xsltproc --stringparam html.stylesheet styles.css \
--output ./book/book.html ./tools/xsl/html/docbook.xsl ./book/book.xml
mkdir -p ./book/html-chunk
xsltproc --stringparam html.stylesheet styles.css \
--output ./book/html-chunk/ \
./tools/xsl/html/chunk.xsl ./book/book.xml
Writing pr01s02.html for sect1(svn-ch-0-sect-2)
Writing pr01s03.html for sect1(svn-ch-0-sect-3)
... ( snip ) ...
cp ./book/styles.css ./book/html-chunk
cp ./book/images/*.png ./book/html-chunk
[tez@tezzy book]$
---------------------------------------------------------------
Check the new book/book.html file by your favoriate browser.
Do you see it ?
6. Tracking.
Anytime, you can find what part of the original documents
are modified since you translated.
For example, if you want the diffs between Rev.5431 and Rev.5600,
---------------------------------------------------------------
[tez@tezzy booklabo]$ svn diff \
http://svn.collab.net/repos/svn/trunk/doc/book/book@5431 \
http://svn.collab.net/repos/svn/trunk/doc/book/book@5600
---------------------------------------------------------------
Seeing this output, you can add the new changes to your
local translated *.xml files.
Again, do not forget to save the last translated revision.
THIS IS YOUR LIFELINE.
Good luck!
- Tez Kamihira (tez@kamihira.com)
# arch-tag: 472598a3-16fa-47f5-9e42-170f15034236