hgbook
annotate it/README @ 1114:527b86d55d4a
inotify: update installation information
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author | Nicolas Dumazet <nicdumz.commits@gmail.com> |
---|---|
date | Sun Dec 13 16:35:56 2009 +0900 (2009-12-13) |
parents | |
children |
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 |