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