Home | History | Annotate | only in /external/valgrind/main/docs
Up to higher level directory
NameDateSize
images/23-Apr-2015
internals/23-Apr-2015
lib/23-Apr-2015
Makefile.am23-Apr-20159.6K
Makefile.in23-Apr-201519.5K
README23-Apr-20157.2K
xml/23-Apr-2015

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 
    143 Notes [Aug. 2012]
    144 -----------------
    145 On Ubuntu 10.04 there was a new capacity-related failure whilst
    146 building the print docs in the run up to the 3.8.0 release.  This was
    147 fixed by editing /etc/texmf/texmf.cnf and changing pool_size to
    148 2000000.
    149 
    150 
    151 Notes [Mar. 2007]
    152 -----------------
    153 For SuSE 10.1, I have to install the following packages to get a
    154 working toolchain.  Non-indented ones I asked YaST to install;
    155 indented ones are extras it added on:
    156 
    157 docbook_4
    158   iso_ent
    159   xmlcharent
    160 docbook-dsssl-stylesheets
    161   docbook_3
    162 docbook-xsl-stylesheets
    163 xmltex
    164   gd
    165   latex-ucs
    166   te_latex
    167   tetex
    168   xaw3d
    169 passivetex
    170 xpdf
    171   xpdf-tools
    172 
    173 pdfxmltex still bombs when building the print docs.  On SuSE 10.1 I
    174 edited /etc/texmf/web2c/texmf.cnf and changed
    175   pool_size.pdfxmltex = 500000
    176 to
    177   pool_size.pdfxmltex = 1500000
    178 and that fixes it.
    179 
    180 It is also reported that the print docs build OK on Fedora Core 5.
    181 
    182 
    183 Notes [Nov. 2005]
    184 -----------------
    185 After upgrading to Suse 10, found a (known) bug in PassiveTex which 
    186 broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
    187 Bug-fix related links:
    188 http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
    189 http://www.dpawson.co.uk/docbook/tools.html#d850e300
    190 http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
    191 
    192 
    193 Notes [July 2005]
    194 -----------------
    195 jrs had to install zillions of packages on SuSE 9.2 in order to
    196 build the print docs (make print-docs), including
    197    passivetex
    198    xpdf (for pdftops, which does the nicest job)
    199 
    200 Even then, pdfxmltex eventually dies with "TeX capacity exceeded,
    201 sorry [pool size = 67555]" or some such.  To fix this, he edited
    202 /etc/texmf/texmf.cnf and changed
    203    pool_size.pdfxmltex = 500000
    204 to 
    205    pool_size.pdfxmltex = 1500000 
    206 and that fixed it.
    207 
    208 
    209 Notes [Nov. 2004]:
    210 -----------------
    211 - the end of file.xml must have only ONE newline after the last tag:
    212   </book>
    213 - pdfxmltex barfs if given a filename with an underscore in it
    214 
    215 
    216 References:
    217 ----------
    218 - samba have got all the stuff
    219 http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1
    220 
    221 excellent on-line howto reference:
    222 - http://www.cogent.ca/
    223 
    224 using automake with docbook:
    225 - http://www.movement.uklinux.net/docs/docbook-autotools/index.html
    226 
    227 Debugging catalog processing:
    228 - http://xmlsoft.org/catalog.html#Declaring
    229   xmlcatalog -v <catalog-file>
    230 
    231 shell script to generate xml catalogs for docbook 4.1.2:
    232 - http://xmlsoft.org/XSLT/docbook.html
    233 
    234 configure.in re pdfxmltex
    235 - http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325
    236 
    237 some useful xls stylesheets in cvs:
    238 - http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/
    239 
    240 
    241 TODO LESS CRUCIAL:
    242 ------------------
    243 - concat titlepage + subtitle page in fo output
    244 - try and get the QuickStart and FAQ titlepage+toc+content onto one page
    245