docs/README

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