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