README
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
79The XML Toolchain
80------------------
81I spent some time on the docbook-apps list in order to ascertain
82the most-useful / widely-available / least-fragile / advanced
83toolchain. Basically, everything has problems of one sort or
84another, so I ended up going with what I felt was the
85least-problematical of the various options.
86
87The maintainer is responsible for ensure the following tools are
88present on his system:
89- xmllint: using libxml version 20620
90- xsltproc: Using libxml 20620, libxslt 10114 and libexslt 812
91 (Nb:be sure to use a version based on libxml2
92 version 2.6.11 or later. There was a bug in
93 xml:base processing in versions before that.)
94- pdfxmltex: pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4)
95- pdftops: version 3.00
96- DocBook: version 4.2
97- bzip2
98
99A big problem is latency. Norman Walsh is constantly updating
100DocBook, but the tools tend to lag behind somewhat. It is
101important that the versions get on with each other. If you
102decide to upgrade something, then it is your responsibility to
103ascertain whether things still work nicely - this *cannot* be
104assumed.
105
106Print output: if make expires with an error, cat output.
107If you see something like this:
108 ! TeX capacity exceeded, sorry [pool size=436070]
109
110then look at this:
111 http://lists.debian.org/debian-doc/2003/12/msg00020.html
112and modify your texmf files accordingly.
113
114
115
116Catalog/Stylesheet Location
117---------------------------
118/etc/xml/ seems to have become the standard place for catalogs
119in recent distros.
120
121
122Notes [May 2009]
123-----------------
124For Ubuntu 9.04, to build HTML docs I had to:
125
126 sudo apt-get install docbook docbook-xsl
127
128Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl'
129definitely is.
130
131To build the man pages I also changed the Makefile.am to try this
132stylesheet:
133
134 /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
135
136if it can't find this one:
137
138 /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
139
140I haven't succeeded in building the print docs.
141
142
143Notes [Aug. 2012]
144-----------------
145On Ubuntu 10.04 there was a new capacity-related failure whilst
146building the print docs in the run up to the 3.8.0 release. This was
147fixed by editing /etc/texmf/texmf.cnf and changing pool_size to
1482000000.
149
150
151Notes [Mar. 2007]
152-----------------
153For SuSE 10.1, I have to install the following packages to get a
154working toolchain. Non-indented ones I asked YaST to install;
155indented ones are extras it added on:
156
157docbook_4
158 iso_ent
159 xmlcharent
160docbook-dsssl-stylesheets
161 docbook_3
162docbook-xsl-stylesheets
163xmltex
164 gd
165 latex-ucs
166 te_latex
167 tetex
168 xaw3d
169passivetex
170xpdf
171 xpdf-tools
172
173pdfxmltex still bombs when building the print docs. On SuSE 10.1 I
174edited /etc/texmf/web2c/texmf.cnf and changed
175 pool_size.pdfxmltex = 500000
176to
177 pool_size.pdfxmltex = 1500000
178and that fixes it.
179
180It is also reported that the print docs build OK on Fedora Core 5.
181
182
183Notes [Nov. 2005]
184-----------------
185After upgrading to Suse 10, found a (known) bug in PassiveTex which
186broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
187Bug-fix related links:
188http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
189http://www.dpawson.co.uk/docbook/tools.html#d850e300
190http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
191
192
193Notes [July 2005]
194-----------------
195jrs had to install zillions of packages on SuSE 9.2 in order to
196build the print docs (make print-docs), including
197 passivetex
198 xpdf (for pdftops, which does the nicest job)
199
200Even then, pdfxmltex eventually dies with "TeX capacity exceeded,
201sorry [pool size = 67555]" or some such. To fix this, he edited
202/etc/texmf/texmf.cnf and changed
203 pool_size.pdfxmltex = 500000
204to
205 pool_size.pdfxmltex = 1500000
206and that fixed it.
207
208
209Notes [Nov. 2004]:
210-----------------
211- the end of file.xml must have only ONE newline after the last tag:
212 </book>
213- pdfxmltex barfs if given a filename with an underscore in it
214
215
216References:
217----------
218- samba have got all the stuff
219http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1
220
221excellent on-line howto reference:
222- http://www.cogent.ca/
223
224using automake with docbook:
225- http://www.movement.uklinux.net/docs/docbook-autotools/index.html
226
227Debugging catalog processing:
228- http://xmlsoft.org/catalog.html#Declaring
229 xmlcatalog -v <catalog-file>
230
231shell script to generate xml catalogs for docbook 4.1.2:
232- http://xmlsoft.org/XSLT/docbook.html
233
234configure.in re pdfxmltex
235- http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325
236
237some useful xls stylesheets in cvs:
238- http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/
239
240
241TODO LESS CRUCIAL:
242------------------
243- concat titlepage + subtitle page in fo output
244- try and get the QuickStart and FAQ titlepage+toc+content onto one page
245