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