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