gpiancastelli@861: This is the Italian translation of "Mercurial: The Definitive Guide". The gpiancastelli@861: original book has been written by Bryan O'Sullivan and published by O'Reilly gpiancastelli@861: Media in 2009. The book has been translated into Italian by Giulio Piancastelli gpiancastelli@861: and currently is available in electronic form only. gpiancastelli@861: gpiancastelli@861: This book is written in DocBook and uses a variety of tools to produce a gpiancastelli@861: bunch of HTML pages to be published on a web site. Transformations towards a gpiancastelli@861: single HTML page or a PDF document are also possible, but are currently not gpiancastelli@861: directly supported. gpiancastelli@861: gpiancastelli@861: The tools needed to build the book are: gpiancastelli@861: gpiancastelli@861: * DocBook XML DTD, version 4.5 (untested with a different version) gpiancastelli@861: * DocBook XSL stylesheets, version >1.75.2 (see later) gpiancastelli@861: * libxml2-utils, containing xmllint (used to validate the XML chapters against gpiancastelli@861: the DocBook DTD) and xmlproc (used to transform XML to HTML) gpiancastelli@861: * Graphviz, to transform DOT files (textual representations of graphs, yay) gpiancastelli@861: into SVG images gpiancastelli@861: * Inkscape, to transform SVG images into PNG images gpiancastelli@861: * Python 3 (ah, yes, I'm sorry, see later), to generate a proper TOC gpiancastelli@861: gpiancastelli@861: (Apparently, if you want also to generate a PDF document out of the DocBook gpiancastelli@861: sources, the suggested tools are Java, Saxon, and FOP. You're still on your gpiancastelli@861: own here.) gpiancastelli@861: gpiancastelli@861: Once you have your tools properly installed, just type gpiancastelli@861: gpiancastelli@861: $ make html gpiancastelli@861: gpiancastelli@861: and you should be set. First, the book is validated; then, XML is transformed gpiancastelli@861: into HTML; using the Mercurial repository, a Python 3 script generates a proper gpiancastelli@861: table of contents for the book; finally, images are transformed, and voilà, you gpiancastelli@861: have your own multi-page HTML version of the book. No other moving parts here. gpiancastelli@861: gpiancastelli@861: Now, let me briefly explain the two esoteric requirements about DocBook XSL and gpiancastelli@861: Python 3. First, the XSL stylesheets. As of today (23th August, 2009) the gpiancastelli@861: latest release of the DocBook XSL stylesheets is 1.75.2. So why I ask you to gpiancastelli@861: grab a release that doesn't even exist yet? Because the latest development gpiancastelli@861: snapshot includes a patch that allows an Italian writer to use complex gpiancastelli@861: prepositions in front of xrefs to sections. Without that patch, you will end up gpiancastelli@861: with text like "come abbiamo visto nella la sezione ...", which gpiancastelli@861: is frankly unreadable. And you do want to read your newly generated version of gpiancastelli@861: the book, don't you? So, grab a DocBook XSL stylesheet development snapshot gpiancastelli@861: while waiting for 1.75.3 to be released, and have a go with it. gpiancastelli@861: gpiancastelli@861: Well, and what about Python 3? I'm sorry. I like it, I just happen to be a fan, gpiancastelli@861: so I'm using it everywhere I can, including this book. You can use it, too. gpiancastelli@861: The only Python script in the build system is it/web/genindex.py; anyway, it gpiancastelli@861: should not be that difficult to edit in order to let it run on Python 2, if you gpiancastelli@861: can't or don't want to use Python 3. Actually, my genindex.py is the result of gpiancastelli@861: converting Bryan's genindex.py to Python 3... but you can't use that script gpiancastelli@861: directly, because it contains some HTML text that I translated into Italian, gpiancastelli@861: and is not capable to make the References appear into the main TOC. gpiancastelli@861: gpiancastelli@861: WINDOWS USERS BEWARE! gpiancastelli@861: gpiancastelli@861: If you are building the book on a Windows system, good luck. I have written gpiancastelli@861: the entire translation on a Windows 2000 box (uh, yes, it's 2009 and they still gpiancastelli@861: exist) so I know how much the process can hurt. Thus, some words of advice gpiancastelli@861: follow. gpiancastelli@861: gpiancastelli@861: First, the silent assumption of the build script is that you are on a Linux (or gpiancastelli@861: probably just Unix-like) system. The build script is a Makefile, and uses gpiancastelli@861: typical *nix tools such as cat and sed. On Windows, you really need to have gpiancastelli@861: Cygwin installed. Look at the Makefile to know exactly which commands are used. gpiancastelli@861: gpiancastelli@861: Then, XSL transformations work on the basis of a symlink. ln -s. Yes. I know. gpiancastelli@861: How the fuck are you supposed to do that on Windows? (Well, at least Windows gpiancastelli@861: 2000 and XP... I heard that newer versions should finally have that kind of gpiancastelli@861: feature built-in.) Two words: junction points. Oh, and an acronym: NTFS. gpiancastelli@861: Junction points are the equivalent of *nix symbolic links for directories gpiancastelli@861: under Windows, but they only work on NTFS. If you have a FAT32 file system, gpiancastelli@861: I believe you are screwed. gpiancastelli@861: gpiancastelli@861: More informations on junction points are available here: gpiancastelli@861: gpiancastelli@861: http://technet.microsoft.com/en-us/sysinternals/bb896768.aspx gpiancastelli@861: gpiancastelli@861: Finally, Inkscape on the Windows command line has some limitations. You might gpiancastelli@861: be forced to pass absolute pathnames to images, use the program from its gpiancastelli@861: installation directory, or perform other esoteric contortions in order to have gpiancastelli@861: it run properly. gpiancastelli@861: gpiancastelli@861: PLEASE SEND FEEDBACK. I'm willing to update build informations and do (or just gpiancastelli@861: merge) some changes to the Makefile in order to improve the build process or gpiancastelli@861: expand it (e.g. to generate also a PDF output). I can be reached by email: gpiancastelli@861: gpiancastelli@861: Giulio Piancastelli gpiancastelli@861: