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