hgbook
view it/README @ 1022:ac4f835c6beb
French: typo and better translation in ch00
| author | André Sintzoff <andre.sintzoff@gmail.com> |
|---|---|
| date | Wed Dec 02 18:28:49 2009 +0100 (2009-12-02) |
| parents | |
| children |
line source
1 This is the Italian translation of "Mercurial: The Definitive Guide". The
2 original book has been written by Bryan O'Sullivan and published by O'Reilly
3 Media in 2009. The book has been translated into Italian by Giulio Piancastelli
4 and currently is available in electronic form only.
6 This book is written in DocBook and uses a variety of tools to produce a
7 bunch of HTML pages to be published on a web site. Transformations towards a
8 single HTML page or a PDF document are also possible, but are currently not
9 directly supported.
11 The tools needed to build the book are:
13 * DocBook XML DTD, version 4.5 (untested with a different version)
14 * DocBook XSL stylesheets, version >1.75.2 (see later)
15 * libxml2-utils, containing xmllint (used to validate the XML chapters against
16 the DocBook DTD) and xmlproc (used to transform XML to HTML)
17 * Graphviz, to transform DOT files (textual representations of graphs, yay)
18 into SVG images
19 * Inkscape, to transform SVG images into PNG images
20 * Python 3 (ah, yes, I'm sorry, see later), to generate a proper TOC
22 (Apparently, if you want also to generate a PDF document out of the DocBook
23 sources, the suggested tools are Java, Saxon, and FOP. You're still on your
24 own here.)
26 Once you have your tools properly installed, just type
28 $ make html
30 and you should be set. First, the book is validated; then, XML is transformed
31 into HTML; using the Mercurial repository, a Python 3 script generates a proper
32 table of contents for the book; finally, images are transformed, and voilà, you
33 have your own multi-page HTML version of the book. No other moving parts here.
35 Now, let me briefly explain the two esoteric requirements about DocBook XSL and
36 Python 3. First, the XSL stylesheets. As of today (23th August, 2009) the
37 latest release of the DocBook XSL stylesheets is 1.75.2. So why I ask you to
38 grab a release that doesn't even exist yet? Because the latest development
39 snapshot includes a patch that allows an Italian writer to use complex
40 prepositions in front of xrefs to sections. Without that patch, you will end up
41 with text like "come abbiamo visto nella <a href=...>la sezione ...</a>", which
42 is frankly unreadable. And you do want to read your newly generated version of
43 the book, don't you? So, grab a DocBook XSL stylesheet development snapshot
44 while waiting for 1.75.3 to be released, and have a go with it.
46 Well, and what about Python 3? I'm sorry. I like it, I just happen to be a fan,
47 so I'm using it everywhere I can, including this book. You can use it, too.
48 The only Python script in the build system is it/web/genindex.py; anyway, it
49 should not be that difficult to edit in order to let it run on Python 2, if you
50 can't or don't want to use Python 3. Actually, my genindex.py is the result of
51 converting Bryan's genindex.py to Python 3... but you can't use that script
52 directly, because it contains some HTML text that I translated into Italian,
53 and is not capable to make the References appear into the main TOC.
55 WINDOWS USERS BEWARE!
57 If you are building the book on a Windows system, good luck. I have written
58 the entire translation on a Windows 2000 box (uh, yes, it's 2009 and they still
59 exist) so I know how much the process can hurt. Thus, some words of advice
60 follow.
62 First, the silent assumption of the build script is that you are on a Linux (or
63 probably just Unix-like) system. The build script is a Makefile, and uses
64 typical *nix tools such as cat and sed. On Windows, you really need to have
65 Cygwin installed. Look at the Makefile to know exactly which commands are used.
67 Then, XSL transformations work on the basis of a symlink. ln -s. Yes. I know.
68 How the fuck are you supposed to do that on Windows? (Well, at least Windows
69 2000 and XP... I heard that newer versions should finally have that kind of
70 feature built-in.) Two words: junction points. Oh, and an acronym: NTFS.
71 Junction points are the equivalent of *nix symbolic links for directories
72 under Windows, but they only work on NTFS. If you have a FAT32 file system,
73 I believe you are screwed.
75 More informations on junction points are available here:
77 http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
79 Finally, Inkscape on the Windows command line has some limitations. You might
80 be forced to pass absolute pathnames to images, use the program from its
81 installation directory, or perform other esoteric contortions in order to have
82 it run properly.
84 PLEASE SEND FEEDBACK. I'm willing to update build informations and do (or just
85 merge) some changes to the Makefile in order to improve the build process or
86 expand it (e.g. to generate also a PDF output). I can be reached by email:
88 Giulio Piancastelli <giulio.piancastelli@gmail.com>