1
2Valgrind Documentation
3----------------------
4This text assumes the following directory structure:
5
6Distribution text files (eg. AUTHORS, NEWS, ...):
7  valgrind/
8
9Main /docs/ dir:
10  valgrind/docs/
11
12Top-level XML files:
13  valgrind/docs/xml/
14
15Tool specific XML docs:
16  valgrind/<toolname>/docs/
17
18All images used in the docs:
19  valgrind/docs/images/
20
21Stylesheets, catalogs, parsing/formatting scripts:
22  valgrind/docs/lib/
23
24Some 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
31The docs/internals directory contains some useful high-level stuff about
32Valgrind's internals.  It's not relevant for the rest of this discussion.
33
34
35Overview
36---------
37The Documentation Set contains all books, articles, manpages,
38etc. pertaining to Valgrind, and is designed to be built as:
39- chunked html files
40- PDF file
41- PS file
42- manpage
43
44The whole thing is a "book set", made up of multiple books (the user
45manual, the FAQ, the tech-docs, the licenses).  Each book could be
46made individually, but the build system doesn't do that.
47
48CSS: the style-sheet used by the docs is the same as that used by the
49website (consistency is king).  It might be worth doing a pre-build diff
50to check whether the website stylesheet has changed.
51
52
53The build process
54-----------------
55It's not obvious exactly when things get built, and so on.  Here's an
56overview:
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
74If the XML processing tools ever mature enough to become standard, we
75could just build the docs from XML when doing 'make install', which
76would be simpler.
77
78
79Notes on building PDF / PS documents
80------------------------------------
81Below are random notes and recollections about how to build PDF / PS
82documents from the XML source at various times on various Linux distros.
83
84Notes [Sept 2015]
85-----------------
86Fedora 21 and 22: Had mucho trouble with building the print docs on
87F21/22 even with the [Mar 2015] package set (or something similarish)
88installed.  Eventually installed "passivetex" and that fixes the
89failures.
90
91Installing the packages below on Fedora _might_ get you a working setup.
92Also 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
101Notes [Mar 2015]
102----------------
103On Ubuntu 14.04.2 LTS the following is known to work:
104
105Required packages:
106texlive
107dblatex
108xsltproc
109xmltex
110docbook-xml
111docbook-xsl
112
113Additional the following lines need to be changed in
114/usr/share/texlive/texmf-dist/tex/latex/oberdiek/epstopdf-base.sty
115around line 450  from
116
117
118\ifETE@prepend
119  \expandafter\PrependGraphicsExtensions
120\else
121  \expandafter\AppendGraphicsExtensions
122\fi
123{.eps}
124
125
126to
127
128
129%% \ifETE@prepend
130%%   \expandafter\PrependGraphicsExtensions
131%% \else
132%%   \expandafter\AppendGraphicsExtensions
133%% \fi
134%% {.eps}
135
136This hack was devised by Mark Wielaard.
137
138
139Notes [Aug. 2012]
140-----------------
141On Ubuntu 10.04 there was a new capacity-related failure whilst
142building the print docs in the run up to the 3.8.0 release.  This was
143fixed by editing /etc/texmf/texmf.cnf and changing pool_size to
1442000000.
145
146
147Notes [May 2009]
148-----------------
149For Ubuntu 9.04, to build HTML docs I had to:
150
151  sudo apt-get install docbook docbook-xsl
152
153Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl'
154definitely is.
155
156To build the man pages I also changed the Makefile.am to try this
157stylesheet:
158
159    /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
160
161if it can't find this one:
162
163    /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
164
165I haven't succeeded in building the print docs.
166
167
168Notes [Mar. 2007]
169-----------------
170For SuSE 10.1, I have to install the following packages to get a
171working toolchain.  Non-indented ones I asked YaST to install;
172indented ones are extras it added on:
173
174docbook_4
175  iso_ent
176  xmlcharent
177docbook-dsssl-stylesheets
178  docbook_3
179docbook-xsl-stylesheets
180xmltex
181  gd
182  latex-ucs
183  te_latex
184  tetex
185  xaw3d
186passivetex
187xpdf
188  xpdf-tools
189
190pdfxmltex still bombs when building the print docs.  On SuSE 10.1 I
191edited /etc/texmf/web2c/texmf.cnf and changed
192  pool_size.pdfxmltex = 500000
193to
194  pool_size.pdfxmltex = 1500000
195and that fixes it.
196
197It is also reported that the print docs build OK on Fedora Core 5.
198
199
200Notes [Nov. 2005]
201-----------------
202After upgrading to Suse 10, found a (known) bug in PassiveTex which
203broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
204Bug-fix related links:
205http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
206http://www.dpawson.co.uk/docbook/tools.html#d850e300
207http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
208
209
210Notes [July 2005]
211-----------------
212jrs had to install zillions of packages on SuSE 9.2 in order to
213build the print docs (make print-docs), including
214   passivetex
215   xpdf (for pdftops, which does the nicest job)
216
217Even then, pdfxmltex eventually dies with "TeX capacity exceeded,
218sorry [pool size = 67555]" or some such.  To fix this, he edited
219/etc/texmf/texmf.cnf and changed
220   pool_size.pdfxmltex = 500000
221to
222   pool_size.pdfxmltex = 1500000
223and that fixed it.
224
225
226Notes [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
233References:
234----------
235- samba have got all the stuff
236http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1
237
238excellent on-line howto reference:
239- http://www.cogent.ca/
240
241using automake with docbook:
242- http://www.movement.uklinux.net/docs/docbook-autotools/index.html
243
244Debugging catalog processing:
245- http://xmlsoft.org/catalog.html#Declaring
246  xmlcatalog -v <catalog-file>
247
248shell script to generate xml catalogs for docbook 4.1.2:
249- http://xmlsoft.org/XSLT/docbook.html
250
251configure.in re pdfxmltex
252- http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325
253
254some useful xls stylesheets in cvs:
255- http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/
256
257
258TODO 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
262