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