docs/README - platform/external/valgrind - Gitiles


 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.


 The XML Toolchain
 ------------------
 I spent some time on the docbook-apps list in order to ascertain
 the most-useful / widely-available / least-fragile / advanced
 toolchain.  Basically, everything has problems of one sort or
 another, so I ended up going with what I felt was the
 least-problematical of the various options.

 The maintainer is responsible for ensure the following tools are
 present on his system:
 - xmllint:    using libxml version 20620
 - xsltproc:   Using libxml 20620, libxslt 10114 and libexslt 812
                 (Nb:be sure to use a version based on libxml2
                 version 2.6.11 or later.  There was a bug in
 	              xml:base processing in versions before that.)
 - pdfxmltex:  pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4)
 - pdftops:    version 3.00
 - DocBook:    version 4.2
 - bzip2

 A big problem is latency.  Norman Walsh is constantly updating
 DocBook, but the tools tend to lag behind somewhat.  It is
 important that the versions get on with each other.  If you
 decide to upgrade something, then it is your responsibility to
 ascertain whether things still work nicely - this *cannot* be
 assumed.

 Print output: if make expires with an error, cat output.
 If you see something like this:
   ! TeX capacity exceeded, sorry [pool size=436070]

 then look at this:
   http://lists.debian.org/debian-doc/2003/12/msg00020.html
 and modify your texmf files accordingly.


 Catalog/Stylesheet Location
 ---------------------------
 /etc/xml/ seems to have become the standard place for catalogs
 in recent distros.


 Notes [May 2009]
 -----------------
 For Ubuntu 9.04, to do non-print-docs builds (ie. with BUILD_ALL_DOCS
 commented out) 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.

 Then I had to change the value of XSL_MAN_STYLE from this:

     /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl

 to this:

     /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl

 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.


	The XML Toolchain
	------------------
	I spent some time on the docbook-apps list in order to ascertain
	the most-useful / widely-available / least-fragile / advanced
	toolchain. Basically, everything has problems of one sort or
	another, so I ended up going with what I felt was the
	least-problematical of the various options.

	The maintainer is responsible for ensure the following tools are
	present on his system:
	- xmllint: using libxml version 20620
	- xsltproc: Using libxml 20620, libxslt 10114 and libexslt 812
	(Nb:be sure to use a version based on libxml2
	version 2.6.11 or later. There was a bug in
	xml:base processing in versions before that.)
	- pdfxmltex: pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4)
	- pdftops: version 3.00
	- DocBook: version 4.2
	- bzip2

	A big problem is latency. Norman Walsh is constantly updating
	DocBook, but the tools tend to lag behind somewhat. It is
	important that the versions get on with each other. If you
	decide to upgrade something, then it is your responsibility to
	ascertain whether things still work nicely - this cannot be
	assumed.

	Print output: if make expires with an error, cat output.
	If you see something like this:
	! TeX capacity exceeded, sorry [pool size=436070]

	then look at this:
	http://lists.debian.org/debian-doc/2003/12/msg00020.html
	and modify your texmf files accordingly.



	Catalog/Stylesheet Location
	---------------------------
	/etc/xml/ seems to have become the standard place for catalogs
	in recent distros.


	Notes [May 2009]
	-----------------
	For Ubuntu 9.04, to do non-print-docs builds (ie. with BUILD_ALL_DOCS
	commented out) 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.

	Then I had to change the value of XSL_MAN_STYLE from this:

	/usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl

	to this:

	/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl

	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