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 Notes on building PDF / PS documents 80 ------------------------------------ 81 Below are random notes and recollections about how to build PDF / PS 82 documents from the XML source at various times on various Linux distros. 83 84 Notes [Sept 2015] 85 ----------------- 86 Fedora 21 and 22: Had mucho trouble with building the print docs on 87 F21/22 even with the [Mar 2015] package set (or something similarish) 88 installed. Eventually installed "passivetex" and that fixes the 89 failures. 90 91 Installing the packages below on Fedora _might_ get you a working setup. 92 Also you need the epstopdf-base.sty hack detailed below. 93 94 texlive-xmltex texlive-xmltex-bin texlive-xmltex-doc texlive dblatex 95 texlive-xmltex docbook-style-xsl docbook-dtds docbook-style-xsl.noarch 96 docbook-simple.noarch docbook-simple.noarch docbook-slides.noarch 97 docbook-style-dsssl.noarch docbook-utils.noarch 98 docbook-utils-pdf.noarch docbook5-schemas.noarch 99 docbook5-style-xsl.noarch passivetex 100 101 Notes [Mar 2015] 102 ---------------- 103 On Ubuntu 14.04.2 LTS the following is known to work: 104 105 Required packages: 106 texlive 107 dblatex 108 xsltproc 109 xmltex 110 docbook-xml 111 docbook-xsl 112 113 Additional the following lines need to be changed in 114 /usr/share/texlive/texmf-dist/tex/latex/oberdiek/epstopdf-base.sty 115 around line 450 from 116 117 118 \ifETE@prepend 119 \expandafter\PrependGraphicsExtensions 120 \else 121 \expandafter\AppendGraphicsExtensions 122 \fi 123 {.eps} 124 125 126 to 127 128 129 %% \ifETE@prepend 130 %% \expandafter\PrependGraphicsExtensions 131 %% \else 132 %% \expandafter\AppendGraphicsExtensions 133 %% \fi 134 %% {.eps} 135 136 This hack was devised by Mark Wielaard. 137 138 139 Notes [Aug. 2012] 140 ----------------- 141 On Ubuntu 10.04 there was a new capacity-related failure whilst 142 building the print docs in the run up to the 3.8.0 release. This was 143 fixed by editing /etc/texmf/texmf.cnf and changing pool_size to 144 2000000. 145 146 147 Notes [May 2009] 148 ----------------- 149 For Ubuntu 9.04, to build HTML docs I had to: 150 151 sudo apt-get install docbook docbook-xsl 152 153 Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl' 154 definitely is. 155 156 To build the man pages I also changed the Makefile.am to try this 157 stylesheet: 158 159 /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl 160 161 if it can't find this one: 162 163 /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl 164 165 I haven't succeeded in building the print docs. 166 167 168 Notes [Mar. 2007] 169 ----------------- 170 For SuSE 10.1, I have to install the following packages to get a 171 working toolchain. Non-indented ones I asked YaST to install; 172 indented ones are extras it added on: 173 174 docbook_4 175 iso_ent 176 xmlcharent 177 docbook-dsssl-stylesheets 178 docbook_3 179 docbook-xsl-stylesheets 180 xmltex 181 gd 182 latex-ucs 183 te_latex 184 tetex 185 xaw3d 186 passivetex 187 xpdf 188 xpdf-tools 189 190 pdfxmltex still bombs when building the print docs. On SuSE 10.1 I 191 edited /etc/texmf/web2c/texmf.cnf and changed 192 pool_size.pdfxmltex = 500000 193 to 194 pool_size.pdfxmltex = 1500000 195 and that fixes it. 196 197 It is also reported that the print docs build OK on Fedora Core 5. 198 199 200 Notes [Nov. 2005] 201 ----------------- 202 After upgrading to Suse 10, found a (known) bug in PassiveTex which 203 broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'. 204 Bug-fix related links: 205 http://lists.oasis-open.org/archives/docbook/200509/msg00032.html 206 http://www.dpawson.co.uk/docbook/tools.html#d850e300 207 http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt 208 209 210 Notes [July 2005] 211 ----------------- 212 jrs had to install zillions of packages on SuSE 9.2 in order to 213 build the print docs (make print-docs), including 214 passivetex 215 xpdf (for pdftops, which does the nicest job) 216 217 Even then, pdfxmltex eventually dies with "TeX capacity exceeded, 218 sorry [pool size = 67555]" or some such. To fix this, he edited 219 /etc/texmf/texmf.cnf and changed 220 pool_size.pdfxmltex = 500000 221 to 222 pool_size.pdfxmltex = 1500000 223 and that fixed it. 224 225 226 Notes [Nov. 2004]: 227 ----------------- 228 - the end of file.xml must have only ONE newline after the last tag: 229 </book> 230 - pdfxmltex barfs if given a filename with an underscore in it 231 232 233 References: 234 ---------- 235 - samba have got all the stuff 236 http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1 237 238 excellent on-line howto reference: 239 - http://www.cogent.ca/ 240 241 using automake with docbook: 242 - http://www.movement.uklinux.net/docs/docbook-autotools/index.html 243 244 Debugging catalog processing: 245 - http://xmlsoft.org/catalog.html#Declaring 246 xmlcatalog -v <catalog-file> 247 248 shell script to generate xml catalogs for docbook 4.1.2: 249 - http://xmlsoft.org/XSLT/docbook.html 250 251 configure.in re pdfxmltex 252 - http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325 253 254 some useful xls stylesheets in cvs: 255 - http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/ 256 257 258 TODO LESS CRUCIAL: 259 ------------------ 260 - concat titlepage + subtitle page in fo output 261 - try and get the QuickStart and FAQ titlepage+toc+content onto one page 262
