l4/pkg/valgrind/src/valgrind-3.6.0-svn/docs/README

   1
   2 Valgrind Documentation
   3 ----------------------
   4 This text assumes the following directory structure:
   5
   6 Distribution text files (eg. AUTHORS, NEWS, ...):
   7   valgrind/
   8
   9 Main /docs/ dir:
  10   valgrind/docs/
  11
  12 Top-level XML files:
  13   valgrind/docs/xml/
  14
  15 Tool specific XML docs:
  16   valgrind/<toolname>/docs/
  17
  18 All images used in the docs:
  19   valgrind/docs/images/
  20
  21 Stylesheets, catalogs, parsing/formatting scripts:
  22   valgrind/docs/lib/
  23
  24 Some files of note:
  25   docs/xml/index.xml:        Top-level book-set wrapper
  26   docs/xml/FAQ.xml:          The FAQ
  27   docs/valgrind-manpage.xml  The valgrind manpage
  28   docs/xml/vg-entities.xml:  Various strings, dates etc. used all over
  29   docs/xml/xml_help.txt:     Basic guide to common XML tags.
  30
  31 The docs/internals directory contains some useful high-level stuff about
  32 Valgrind's internals.  It's not relevant for the rest of this discussion.
  33
  34
  35 Overview
  36 ---------
  37 The Documentation Set contains all books, articles, manpages,
  38 etc. pertaining to Valgrind, and is designed to be built as:
  39 - chunked html files
  40 - PDF file
  41 - PS file
  42 - manpage
  43
  44 The whole thing is a "book set", made up of multiple books (the user
  45 manual, the FAQ, the tech-docs, the licenses).  Each book could be
  46 made individually, but the build system doesn't do that.
  47
  48 CSS: the style-sheet used by the docs is the same as that used by the
  49 website (consistency is king).  It might be worth doing a pre-build diff
  50 to check whether the website stylesheet has changed.
  51
  52
  53 The build process
  54 -----------------
  55 It's not obvious exactly when things get built, and so on.  Here's an
  56 overview:
  57
  58 - The HTML docs can be built manually by running 'make html-docs' in
  59   valgrind/docs/.  (Don't use 'make html'; that is a valid built-in
  60   automake target, but does nothing.)  Likewise for PDF/PS with 'make
  61   print-docs'.
  62
  63 - 'make dist' (nb: at the top level, not in docs/) puts the XML files
  64   into the tarball.  It also builds the HTML docs and puts them in too,
  65   in valgrind/docs/html/ (including style sheets, images, etc).
  66
  67 - 'make install' installs the HTML docs in
  68   $(install)/share/doc/valgrind/html/, if they are present.  (They will
  69   be present if you are installing from the result of a 'make dist'.
  70   They might not be present if you are developing in a Subversion
  71   workspace and have not built them.)  It doesn't install the XML docs,
  72   as they're not useful installed.
  73
  74 If the XML processing tools ever mature enough to become standard, we
  75 could just build the docs from XML when doing 'make install', which
  76 would be simpler.
  77
  78
  79 The XML Toolchain
  80 ------------------
  81 I spent some time on the docbook-apps list in order to ascertain
  82 the most-useful / widely-available / least-fragile / advanced
  83 toolchain.  Basically, everything has problems of one sort or
  84 another, so I ended up going with what I felt was the
  85 least-problematical of the various options.
  86
  87 The maintainer is responsible for ensure the following tools are
  88 present on his system:
  89 - xmllint:    using libxml version 20620
  90 - xsltproc:   Using libxml 20620, libxslt 10114 and libexslt 812
  91                 (Nb:be sure to use a version based on libxml2
  92                 version 2.6.11 or later.  There was a bug in
  93                       xml:base processing in versions before that.)
  94 - pdfxmltex:  pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4)
  95 - pdftops:    version 3.00
  96 - DocBook:    version 4.2
  97 - bzip2
  98
  99 A big problem is latency.  Norman Walsh is constantly updating
 100 DocBook, but the tools tend to lag behind somewhat.  It is
 101 important that the versions get on with each other.  If you
 102 decide to upgrade something, then it is your responsibility to
 103 ascertain whether things still work nicely - this *cannot* be
 104 assumed.
 105
 106 Print output: if make expires with an error, cat output.
 107 If you see something like this:
 108   ! TeX capacity exceeded, sorry [pool size=436070]
 109
 110 then look at this:
 111   http://lists.debian.org/debian-doc/2003/12/msg00020.html
 112 and modify your texmf files accordingly.
 113
 114
 115
 116 Catalog/Stylesheet Location
 117 ---------------------------
 118 /etc/xml/ seems to have become the standard place for catalogs
 119 in recent distros.
 120
 121
 122 Notes [May 2009]
 123 -----------------
 124 For Ubuntu 9.04, to build HTML docs I had to:
 125
 126   sudo apt-get install docbook docbook-xsl
 127
 128 Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl'
 129 definitely is.
 130
 131 To build the man pages I also changed the Makefile.am to try this
 132 stylesheet:
 133
 134     /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
 135
 136 if it can't find this one:
 137
 138     /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
 139
 140 I haven't succeeded in building the print docs.
 141
 142 Notes [Mar. 2007]
 143 -----------------
 144 For SuSE 10.1, I have to install the following packages to get a
 145 working toolchain.  Non-indented ones I asked YaST to install;
 146 indented ones are extras it added on:
 147
 148 docbook_4
 149   iso_ent
 150   xmlcharent
 151 docbook-dsssl-stylesheets
 152   docbook_3
 153 docbook-xsl-stylesheets
 154 xmltex
 155   gd
 156   latex-ucs
 157   te_latex
 158   tetex
 159   xaw3d
 160 passivetex
 161 xpdf
 162   xpdf-tools
 163
 164 pdfxmltex still bombs when building the print docs.  On SuSE 10.1 I
 165 edited /etc/texmf/web2c/texmf.cnf and changed
 166   pool_size.pdfxmltex = 500000
 167 to
 168   pool_size.pdfxmltex = 1500000
 169 and that fixes it.
 170
 171 It is also reported that the print docs build OK on Fedora Core 5.
 172
 173
 174 Notes [Nov. 2005]
 175 -----------------
 176 After upgrading to Suse 10, found a (known) bug in PassiveTex which
 177 broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
 178 Bug-fix related links:
 179 http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
 180 http://www.dpawson.co.uk/docbook/tools.html#d850e300
 181 http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
 182
 183
 184 Notes [July 2005]
 185 -----------------
 186 jrs had to install zillions of packages on SuSE 9.2 in order to
 187 build the print docs (make print-docs), including
 188    passivetex
 189    xpdf (for pdftops, which does the nicest job)
 190
 191 Even then, pdfxmltex eventually dies with "TeX capacity exceeded,
 192 sorry [pool size = 67555]" or some such.  To fix this, he edited
 193 /etc/texmf/texmf.cnf and changed
 194    pool_size.pdfxmltex = 500000
 195 to
 196    pool_size.pdfxmltex = 1500000
 197 and that fixed it.
 198
 199
 200 Notes [Nov. 2004]:
 201 -----------------
 202 - the end of file.xml must have only ONE newline after the last tag:
 203   </book>
 204 - pdfxmltex barfs if given a filename with an underscore in it
 205
 206
 207 References:
 208 ----------
 209 - samba have got all the stuff
 210 http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1
 211
 212 excellent on-line howto reference:
 213 - http://www.cogent.ca/
 214
 215 using automake with docbook:
 216 - http://www.movement.uklinux.net/docs/docbook-autotools/index.html
 217
 218 Debugging catalog processing:
 219 - http://xmlsoft.org/catalog.html#Declaring
 220   xmlcatalog -v <catalog-file>
 221
 222 shell script to generate xml catalogs for docbook 4.1.2:
 223 - http://xmlsoft.org/XSLT/docbook.html
 224
 225 configure.in re pdfxmltex
 226 - http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325
 227
 228 some useful xls stylesheets in cvs:
 229 - http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/
 230
 231
 232 TODO LESS CRUCIAL:
 233 ------------------
 234 - concat titlepage + subtitle page in fo output
 235 - try and get the QuickStart and FAQ titlepage+toc+content onto one page