• Home
Name
Date
Size
#Lines
LOC

..--

html/03-May-2024-25,68625,539

images/03-May-2024-

internals/03-May-2024-10,1697,586

lib/03-May-2024-1,5401,209

xml/03-May-2024-8,0966,720

Makefile.amD03-May-20249.9 KiB305235

Makefile.inD03-May-202423.3 KiB775661

READMED03-May-20247.8 KiB280207

callgrind_annotate.1D03-May-20243 KiB10580

callgrind_control.1D03-May-20244.2 KiB10984

cg_annotate.1D03-May-20243.8 KiB10075

cg_diff.1D03-May-20242.4 KiB7045

cg_merge.1D03-May-20241.8 KiB5631

index.pdfD03-May-20241 MiB

ms_print.1D03-May-20242.1 KiB7651

valgrind-listener.1D03-May-20242.4 KiB7146

valgrind.1D03-May-2024116.9 KiB2,5892,564

vgdb.1D03-May-20246.7 KiB210184

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