1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/it/README	Sun Aug 23 02:21:44 2009 +0200
     1.3 @@ -0,0 +1,89 @@
     1.4 +This is the Italian translation of "Mercurial: The Definitive Guide". The
     1.5 +original book has been written by Bryan O'Sullivan and published by O'Reilly
     1.6 +Media in 2009. The book has been translated into Italian by Giulio Piancastelli
     1.7 +and currently is available in electronic form only.
     1.8 +
     1.9 +This book is written in DocBook and uses a variety of tools to produce a
    1.10 +bunch of HTML pages to be published on a web site. Transformations towards a
    1.11 +single HTML page or a PDF document are also possible, but are currently not
    1.12 +directly supported.
    1.13 +
    1.14 +The tools needed to build the book are:
    1.15 +
    1.16 + * DocBook XML DTD, version 4.5 (untested with a different version)
    1.17 + * DocBook XSL stylesheets, version >1.75.2 (see later)
    1.18 + * libxml2-utils, containing xmllint (used to validate the XML chapters against
    1.19 +   the DocBook DTD) and xmlproc (used to transform XML to HTML)
    1.20 + * Graphviz, to transform DOT files (textual representations of graphs, yay)
    1.21 +   into SVG images
    1.22 + * Inkscape, to transform SVG images into PNG images
    1.23 + * Python 3 (ah, yes, I'm sorry, see later), to generate a proper TOC
    1.24 +
    1.25 +(Apparently, if you want also to generate a PDF document out of the DocBook
    1.26 +sources, the suggested tools are Java, Saxon, and FOP. You're still on your
    1.27 +own here.)
    1.28 +
    1.29 +Once you have your tools properly installed, just type
    1.30 +
    1.31 +  $ make html
    1.32 +
    1.33 +and you should be set. First, the book is validated; then, XML is transformed
    1.34 +into HTML; using the Mercurial repository, a Python 3 script generates a proper
    1.35 +table of contents for the book; finally, images are transformed, and voilà, you
    1.36 +have your own multi-page HTML version of the book. No other moving parts here.
    1.37 +
    1.38 +Now, let me briefly explain the two esoteric requirements about DocBook XSL and
    1.39 +Python 3. First, the XSL stylesheets. As of today (23th August, 2009) the
    1.40 +latest release of the DocBook XSL stylesheets is 1.75.2. So why I ask you to
    1.41 +grab a release that doesn't even exist yet? Because the latest development
    1.42 +snapshot includes a patch that allows an Italian writer to use complex
    1.43 +prepositions in front of xrefs to sections. Without that patch, you will end up
    1.44 +with text like "come abbiamo visto nella <a href=...>la sezione ...</a>", which
    1.45 +is frankly unreadable. And you do want to read your newly generated version of
    1.46 +the book, don't you? So, grab a DocBook XSL stylesheet development snapshot
    1.47 +while waiting for 1.75.3 to be released, and have a go with it.
    1.48 +
    1.49 +Well, and what about Python 3? I'm sorry. I like it, I just happen to be a fan,
    1.50 +so I'm using it everywhere I can, including this book. You can use it, too.
    1.51 +The only Python script in the build system is it/web/genindex.py; anyway, it
    1.52 +should not be that difficult to edit in order to let it run on Python 2, if you
    1.53 +can't or don't want to use Python 3. Actually, my genindex.py is the result of
    1.54 +converting Bryan's genindex.py to Python 3... but you can't use that script
    1.55 +directly, because it contains some HTML text that I translated into Italian,
    1.56 +and is not capable to make the References appear into the main TOC.
    1.57 +
    1.58 +WINDOWS USERS BEWARE!
    1.59 +
    1.60 +If you are building the book on a Windows system, good luck. I have written
    1.61 +the entire translation on a Windows 2000 box (uh, yes, it's 2009 and they still
    1.62 +exist) so I know how much the process can hurt. Thus, some words of advice
    1.63 +follow.
    1.64 +
    1.65 +First, the silent assumption of the build script is that you are on a Linux (or
    1.66 +probably just Unix-like) system. The build script is a Makefile, and uses
    1.67 +typical *nix tools such as cat and sed. On Windows, you really need to have
    1.68 +Cygwin installed. Look at the Makefile to know exactly which commands are used.
    1.69 +
    1.70 +Then, XSL transformations work on the basis of a symlink. ln -s. Yes. I know.
    1.71 +How the fuck are you supposed to do that on Windows? (Well, at least Windows
    1.72 +2000 and XP... I heard that newer versions should finally have that kind of
    1.73 +feature built-in.) Two words: junction points. Oh, and an acronym: NTFS.
    1.74 +Junction points are the equivalent of *nix symbolic links for directories
    1.75 +under Windows, but they only work on NTFS. If you have a FAT32 file system,
    1.76 +I believe you are screwed.
    1.77 +
    1.78 +More informations on junction points are available here:
    1.79 +
    1.80 +  http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx
    1.81 +
    1.82 +Finally, Inkscape on the Windows command line has some limitations. You might
    1.83 +be forced to pass absolute pathnames to images, use the program from its
    1.84 +installation directory, or perform other esoteric contortions in order to have
    1.85 +it run properly.
    1.86 +
    1.87 +PLEASE SEND FEEDBACK. I'm willing to update build informations and do (or just
    1.88 +merge) some changes to the Makefile in order to improve the build process or
    1.89 +expand it (e.g. to generate also a PDF output). I can be reached by email:
    1.90 +
    1.91 +  Giulio Piancastelli <giulio.piancastelli@gmail.com>
    1.92 +