doc/readme.txt

   1 HowTo build the docs\r
   2 ====================\r
   3 \r
   4 Since you are already reading this, I assume that you have succeeded in checking \r
   5 out the TortoiseGit.\r
   6 \r
   7 Tools needed:\r
   8 =============\r
   9 \r
  10 There are some tools for processing the XML input that you need to build the docs.\r
  11 Scripts and dtd are included, but the executables (formatting processor, microsoft\r
  12 help compiler, translation tools) have to be installed separately.\r
  13 You will also need to have a Java Runtime Environment version 1.3.x or above.\r
  14 \r
  15 tools\fop\              - the fop processor\r
  16 tools\xsl\              - the docbook xsl files from sourceforge\r
  17 tools\                  - xsl processor, hhc.exe, ...\r
  18 \r
  19 you can download all the required tools as a zip package from our website:\r
  20 http://code.google.com/p/tortoisesvn/downloads/list\r
  21 tools-*.7z. Use 7-zip extract to \TortotiseGit\Tools\r
  22 \r
  23 \r
  24 Please note that having spaces in your directory path will (for the time being)\r
  25 cause the documentation build process to fail.\r
  26 \r
  27 To build only the english docs, that's all you need. If you want to build translated\r
  28 docs as well, you need:\r
  29 - A Python runtime environment\r
  30   (http://www.python.org)\r
  31 - The Python libxml2 bindings\r
  32   (http://users.skynet.be/sbi/libxml-python/)\r
  33 - Aspell (optional) for spell checking translations\r
  34   (ftp://ftp.gnu.org/gnu/aspell/w32/)\r
  35 \r
  36 For Chm docs you need:\r
  37 - Microsofts makehm.exe, Part of visual studio, sources available on msdn\r
  38 - Microsofts html workshop, Binaries available on msdn\r
  39 \r
  40 \r
  41 Structure:\r
  42 ==========\r
  43 The most important directories for you are:\r
  44 source\en - contains the english XML text source.\r
  45 images\en - contains the base (english) images for the docs. If you don't localize \r
  46             your screenshots, these will be used instead.\r
  47 images\*  - contains the localized screenshots for other languages.\r
  48 po\*      - contains the translations for each language. Best edited with poEdit.\r
  49 xsl\      - contains the stylesheets for the doc creation\r
  50 dtd\      - contains the tools and the dtd to validate and build the docs.\r
  51             You might want to place your tools directory somewhere else on your \r
  52             harddisk, if you want to use it to build other docs too. This will \r
  53             however require tweaking the build scripts.\r
  54             I'd recommend to leave dtd in place, so the source stays \r
  55             compatible between TSVN doc developers.\r
  56             \r
  57 Building the docs:\r
  58 ==================\r
  59 \r
  60 NAnt Build:\r
  61 -----------\r
  62 \r
  63 VS->Tools->Vistual Studio 2008 command line\r
  64 cd doc\r
  65 ..\tools\nant-0.86-beta1\bin\nant.exe\r
  66 \r
  67 A NAnt build script has been provided to build the docs. When doc.build is run for\r
  68 the first time, the template doc.build.include.template is copied to doc.build.include.\r
  69 \r
  70 For local customisations, copy the doc.build.user.tmpl file to doc.build.user and\r
  71 modify that copy to point to the location of the tools on your system.\r
  72 \r
  73 If you want to build the Japanese docs, you have to copy xsl\ja\userconfig.template.xml\r
  74 to xsl\ja\userconfig.xml and adjust the path settings to the japanese fonts.\r
  75 \r
  76 Currently nant supports three targets "all", "clean" and "potfile".\r
  77 - "all" builds all the docs that are out of date. Runs the target "potfile" too.\r
  78 - "clean" cleans only the output directory\r
  79 - "potfile" updates the po template from the source document.\r
  80 \r
  81 All other parameters are defined in doc.build.include. You can override all settings\r
  82 in doc.build.user or via the NAnt command line.\r
  83 \r
  84 Translate:\r
  85 ==========\r
  86 If you want to translate the docs into a new language (assume french), just go ahead\r
  87 and copy po\doc.pot to po\fr.po. Start to translate phrases and test your translation\r
  88 with "TranslateDoc fr" and "makedoc tortoisesvn fr".\r
  89 \r
  90 Place localized screenshots in images\fr. The file "screenshots.txt" contains some \r
  91 instructions on how/where the images have been captured. \r
  92 \r
  93 Now go ahead and translate the rest.\r