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