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