mirror of
https://github.com/ioacademy-jikim/debugging
synced 2025-06-07 16:06:09 +00:00
262 lines
7.2 KiB
Plaintext
262 lines
7.2 KiB
Plaintext
|
|
Valgrind Documentation
|
|
----------------------
|
|
This text assumes the following directory structure:
|
|
|
|
Distribution text files (eg. AUTHORS, NEWS, ...):
|
|
valgrind/
|
|
|
|
Main /docs/ dir:
|
|
valgrind/docs/
|
|
|
|
Top-level XML files:
|
|
valgrind/docs/xml/
|
|
|
|
Tool specific XML docs:
|
|
valgrind/<toolname>/docs/
|
|
|
|
All images used in the docs:
|
|
valgrind/docs/images/
|
|
|
|
Stylesheets, catalogs, parsing/formatting scripts:
|
|
valgrind/docs/lib/
|
|
|
|
Some files of note:
|
|
docs/xml/index.xml: Top-level book-set wrapper
|
|
docs/xml/FAQ.xml: The FAQ
|
|
docs/valgrind-manpage.xml The valgrind manpage
|
|
docs/xml/vg-entities.xml: Various strings, dates etc. used all over
|
|
docs/xml/xml_help.txt: Basic guide to common XML tags.
|
|
|
|
The docs/internals directory contains some useful high-level stuff about
|
|
Valgrind's internals. It's not relevant for the rest of this discussion.
|
|
|
|
|
|
Overview
|
|
---------
|
|
The Documentation Set contains all books, articles, manpages,
|
|
etc. pertaining to Valgrind, and is designed to be built as:
|
|
- chunked html files
|
|
- PDF file
|
|
- PS file
|
|
- manpage
|
|
|
|
The whole thing is a "book set", made up of multiple books (the user
|
|
manual, the FAQ, the tech-docs, the licenses). Each book could be
|
|
made individually, but the build system doesn't do that.
|
|
|
|
CSS: the style-sheet used by the docs is the same as that used by the
|
|
website (consistency is king). It might be worth doing a pre-build diff
|
|
to check whether the website stylesheet has changed.
|
|
|
|
|
|
The build process
|
|
-----------------
|
|
It's not obvious exactly when things get built, and so on. Here's an
|
|
overview:
|
|
|
|
- The HTML docs can be built manually by running 'make html-docs' in
|
|
valgrind/docs/. (Don't use 'make html'; that is a valid built-in
|
|
automake target, but does nothing.) Likewise for PDF/PS with 'make
|
|
print-docs'.
|
|
|
|
- 'make dist' (nb: at the top level, not in docs/) puts the XML files
|
|
into the tarball. It also builds the HTML docs and puts them in too,
|
|
in valgrind/docs/html/ (including style sheets, images, etc).
|
|
|
|
- 'make install' installs the HTML docs in
|
|
$(install)/share/doc/valgrind/html/, if they are present. (They will
|
|
be present if you are installing from the result of a 'make dist'.
|
|
They might not be present if you are developing in a Subversion
|
|
workspace and have not built them.) It doesn't install the XML docs,
|
|
as they're not useful installed.
|
|
|
|
If the XML processing tools ever mature enough to become standard, we
|
|
could just build the docs from XML when doing 'make install', which
|
|
would be simpler.
|
|
|
|
|
|
Notes on building PDF / PS documents
|
|
------------------------------------
|
|
Below are random notes and recollections about how to build PDF / PS
|
|
documents from the XML source at various times on various Linux distros.
|
|
|
|
Notes [Sept 2015]
|
|
-----------------
|
|
Fedora 21 and 22: Had mucho trouble with building the print docs on
|
|
F21/22 even with the [Mar 2015] package set (or something similarish)
|
|
installed. Eventually installed "passivetex" and that fixes the
|
|
failures.
|
|
|
|
Installing the packages below on Fedora _might_ get you a working setup.
|
|
Also you need the epstopdf-base.sty hack detailed below.
|
|
|
|
texlive-xmltex texlive-xmltex-bin texlive-xmltex-doc texlive dblatex
|
|
texlive-xmltex docbook-style-xsl docbook-dtds docbook-style-xsl.noarch
|
|
docbook-simple.noarch docbook-simple.noarch docbook-slides.noarch
|
|
docbook-style-dsssl.noarch docbook-utils.noarch
|
|
docbook-utils-pdf.noarch docbook5-schemas.noarch
|
|
docbook5-style-xsl.noarch passivetex
|
|
|
|
Notes [Mar 2015]
|
|
----------------
|
|
On Ubuntu 14.04.2 LTS the following is known to work:
|
|
|
|
Required packages:
|
|
texlive
|
|
dblatex
|
|
xsltproc
|
|
xmltex
|
|
docbook-xml
|
|
docbook-xsl
|
|
|
|
Additional the following lines need to be changed in
|
|
/usr/share/texlive/texmf-dist/tex/latex/oberdiek/epstopdf-base.sty
|
|
around line 450 from
|
|
|
|
|
|
\ifETE@prepend
|
|
\expandafter\PrependGraphicsExtensions
|
|
\else
|
|
\expandafter\AppendGraphicsExtensions
|
|
\fi
|
|
{.eps}
|
|
|
|
|
|
to
|
|
|
|
|
|
%% \ifETE@prepend
|
|
%% \expandafter\PrependGraphicsExtensions
|
|
%% \else
|
|
%% \expandafter\AppendGraphicsExtensions
|
|
%% \fi
|
|
%% {.eps}
|
|
|
|
This hack was devised by Mark Wielaard.
|
|
|
|
|
|
Notes [Aug. 2012]
|
|
-----------------
|
|
On Ubuntu 10.04 there was a new capacity-related failure whilst
|
|
building the print docs in the run up to the 3.8.0 release. This was
|
|
fixed by editing /etc/texmf/texmf.cnf and changing pool_size to
|
|
2000000.
|
|
|
|
|
|
Notes [May 2009]
|
|
-----------------
|
|
For Ubuntu 9.04, to build HTML docs I had to:
|
|
|
|
sudo apt-get install docbook docbook-xsl
|
|
|
|
Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl'
|
|
definitely is.
|
|
|
|
To build the man pages I also changed the Makefile.am to try this
|
|
stylesheet:
|
|
|
|
/usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
|
|
|
|
if it can't find this one:
|
|
|
|
/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
|
|
|
|
I haven't succeeded in building the print docs.
|
|
|
|
|
|
Notes [Mar. 2007]
|
|
-----------------
|
|
For SuSE 10.1, I have to install the following packages to get a
|
|
working toolchain. Non-indented ones I asked YaST to install;
|
|
indented ones are extras it added on:
|
|
|
|
docbook_4
|
|
iso_ent
|
|
xmlcharent
|
|
docbook-dsssl-stylesheets
|
|
docbook_3
|
|
docbook-xsl-stylesheets
|
|
xmltex
|
|
gd
|
|
latex-ucs
|
|
te_latex
|
|
tetex
|
|
xaw3d
|
|
passivetex
|
|
xpdf
|
|
xpdf-tools
|
|
|
|
pdfxmltex still bombs when building the print docs. On SuSE 10.1 I
|
|
edited /etc/texmf/web2c/texmf.cnf and changed
|
|
pool_size.pdfxmltex = 500000
|
|
to
|
|
pool_size.pdfxmltex = 1500000
|
|
and that fixes it.
|
|
|
|
It is also reported that the print docs build OK on Fedora Core 5.
|
|
|
|
|
|
Notes [Nov. 2005]
|
|
-----------------
|
|
After upgrading to Suse 10, found a (known) bug in PassiveTex which
|
|
broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
|
|
Bug-fix related links:
|
|
http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
|
|
http://www.dpawson.co.uk/docbook/tools.html#d850e300
|
|
http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
|
|
|
|
|
|
Notes [July 2005]
|
|
-----------------
|
|
jrs had to install zillions of packages on SuSE 9.2 in order to
|
|
build the print docs (make print-docs), including
|
|
passivetex
|
|
xpdf (for pdftops, which does the nicest job)
|
|
|
|
Even then, pdfxmltex eventually dies with "TeX capacity exceeded,
|
|
sorry [pool size = 67555]" or some such. To fix this, he edited
|
|
/etc/texmf/texmf.cnf and changed
|
|
pool_size.pdfxmltex = 500000
|
|
to
|
|
pool_size.pdfxmltex = 1500000
|
|
and that fixed it.
|
|
|
|
|
|
Notes [Nov. 2004]:
|
|
-----------------
|
|
- the end of file.xml must have only ONE newline after the last tag:
|
|
</book>
|
|
- pdfxmltex barfs if given a filename with an underscore in it
|
|
|
|
|
|
References:
|
|
----------
|
|
- samba have got all the stuff
|
|
http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1
|
|
|
|
excellent on-line howto reference:
|
|
- http://www.cogent.ca/
|
|
|
|
using automake with docbook:
|
|
- http://www.movement.uklinux.net/docs/docbook-autotools/index.html
|
|
|
|
Debugging catalog processing:
|
|
- http://xmlsoft.org/catalog.html#Declaring
|
|
xmlcatalog -v <catalog-file>
|
|
|
|
shell script to generate xml catalogs for docbook 4.1.2:
|
|
- http://xmlsoft.org/XSLT/docbook.html
|
|
|
|
configure.in re pdfxmltex
|
|
- http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325
|
|
|
|
some useful xls stylesheets in cvs:
|
|
- http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/
|
|
|
|
|
|
TODO LESS CRUCIAL:
|
|
------------------
|
|
- concat titlepage + subtitle page in fo output
|
|
- try and get the QuickStart and FAQ titlepage+toc+content onto one page
|