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//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: - 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 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