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