valgrind/docs/README - nest-cam/4320010/valgrind - Git at Google



            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

	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