njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1 | |
sewardj | 49fbe60 | 2005-07-25 17:58:48 +0000 | [diff] [blame] | 2 | Valgrind Documentation |
| 3 | ---------------------- |
| 4 | This text assumes the following directory structure: |
| 5 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 6 | Distribution text files (eg. AUTHORS, NEWS, ...): |
sewardj | 49fbe60 | 2005-07-25 17:58:48 +0000 | [diff] [blame] | 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 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 21 | Stylesheets, catalogs, parsing/formatting scripts: |
| 22 | valgrind/docs/lib/ |
| 23 | |
| 24 | Some files of note: |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 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. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 30 | |
njn | f7c00b1 | 2005-07-19 21:46:19 +0000 | [diff] [blame] | 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. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 33 | |
de | 91baf95 | 2005-11-29 17:42:50 +0000 | [diff] [blame] | 34 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 35 | Overview |
| 36 | --------- |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 37 | The Documentation Set contains all books, articles, manpages, |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 38 | etc. pertaining to Valgrind, and is designed to be built as: |
| 39 | - chunked html files |
| 40 | - PDF file |
| 41 | - PS file |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 42 | - manpage |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 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 | |
sewardj | 8bc09dc | 2005-07-25 17:54:06 +0000 | [diff] [blame] | 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). |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 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 | |
florian | ee470b8 | 2015-03-16 22:42:13 +0000 | [diff] [blame] | 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. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 83 | |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 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 | |
sewardj | 372d7b9 | 2015-09-08 12:53:49 +0000 | [diff] [blame] | 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 |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 118 | |
florian | ee470b8 | 2015-03-16 22:42:13 +0000 | [diff] [blame] | 119 | Notes [Mar 2015] |
| 120 | ---------------- |
| 121 | On Ubuntu 14.04.2 LTS the following is known to work: |
de | 91baf95 | 2005-11-29 17:42:50 +0000 | [diff] [blame] | 122 | |
florian | ee470b8 | 2015-03-16 22:42:13 +0000 | [diff] [blame] | 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. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 163 | |
| 164 | |
njn | ff0c452 | 2009-05-18 23:11:49 +0000 | [diff] [blame] | 165 | Notes [May 2009] |
| 166 | ----------------- |
njn | 40ad266 | 2009-08-06 01:26:14 +0000 | [diff] [blame] | 167 | For Ubuntu 9.04, to build HTML docs I had to: |
njn | ff0c452 | 2009-05-18 23:11:49 +0000 | [diff] [blame] | 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 | |
njn | abe8b8c | 2009-08-07 06:54:44 +0000 | [diff] [blame] | 174 | To build the man pages I also changed the Makefile.am to try this |
| 175 | stylesheet: |
njn | ff0c452 | 2009-05-18 23:11:49 +0000 | [diff] [blame] | 176 | |
| 177 | /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl |
| 178 | |
njn | abe8b8c | 2009-08-07 06:54:44 +0000 | [diff] [blame] | 179 | if it can't find this one: |
njn | ff0c452 | 2009-05-18 23:11:49 +0000 | [diff] [blame] | 180 | |
| 181 | /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl |
| 182 | |
njn | 40ad266 | 2009-08-06 01:26:14 +0000 | [diff] [blame] | 183 | I haven't succeeded in building the print docs. |
| 184 | |
sewardj | a5629a2 | 2012-08-05 14:25:35 +0000 | [diff] [blame] | 185 | |
sewardj | 429d539 | 2007-03-08 19:56:58 +0000 | [diff] [blame] | 186 | Notes [Mar. 2007] |
sewardj | 429eb99 | 2006-12-10 02:58:27 +0000 | [diff] [blame] | 187 | ----------------- |
sewardj | 429d539 | 2007-03-08 19:56:58 +0000 | [diff] [blame] | 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 |
sewardj | eb0d332 | 2007-11-07 01:10:42 +0000 | [diff] [blame] | 205 | xpdf |
| 206 | xpdf-tools |
sewardj | 429d539 | 2007-03-08 19:56:58 +0000 | [diff] [blame] | 207 | |
sewardj | 429eb99 | 2006-12-10 02:58:27 +0000 | [diff] [blame] | 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 | |
sewardj | e01c505 | 2007-11-25 00:56:51 +0000 | [diff] [blame] | 215 | It is also reported that the print docs build OK on Fedora Core 5. |
| 216 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 217 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 218 | Notes [Nov. 2005] |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 219 | ----------------- |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 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 |
de | 91baf95 | 2005-11-29 17:42:50 +0000 | [diff] [blame] | 226 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 227 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 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 |
de | 91baf95 | 2005-11-29 17:42:50 +0000 | [diff] [blame] | 239 | to |
| 240 | pool_size.pdfxmltex = 1500000 |
| 241 | and that fixed it. |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 242 | |
| 243 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 244 | Notes [Nov. 2004]: |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 245 | ----------------- |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 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 |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame] | 249 | |
| 250 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 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 | |
njn | 0ce9da2 | 2004-11-30 14:08:24 +0000 | [diff] [blame] | 276 | TODO LESS CRUCIAL: |
| 277 | ------------------ |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 278 | - concat titlepage + subtitle page in fo output |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 279 | - try and get the QuickStart and FAQ titlepage+toc+content onto one page |