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
