Post-release changes:
- removed a reference to cachegrind dot org from mc-tech-docs.xml
- in an effort to simplify future borked links, replaced all valgrind 
  website urls with entities so now we just have to change one string.
- new stylesheet to create the docs to 'fit' into the website
- added build rules 'make website-docs' + make download-docs
  to /docs/Makefile.am




git-svn-id: svn://svn.valgrind.org/valgrind/trunk@5239 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/Makefile.am b/docs/Makefile.am
index f9608d4..2018097 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -31,6 +31,11 @@
 myhtmldir  = $(top_builddir)/docs/html
 myprintdir = $(top_builddir)/docs/print
 
+websitedir   = $(top_builddir)/docs/website
+valkyriedir  = $(top_builddir)/docs/vg-html
+downloadsdir = $(top_builddir)/docs/downloads
+vgdir        = $(top_builddir)/docs/valgrind
+
 XML_CATALOG_FILES = /etc/xml/catalog
 
 # file to log print output to
@@ -50,6 +55,7 @@
 XSL_HTML_CHUNK_STYLE  = $(mylibdir)/vg-html-chunk.xsl
 XSL_FO_STYLE          = $(mylibdir)/vg-fo.xsl
 XSL_TEXT_STYLE        = $(mylibdir)/vg-faq2txt.xsl
+XSL_WEBSITE_STYLE     = $(mylibdir)/vg-html-website.xsl
 
 all-docs: FAQ.txt html-docs print-docs
 
@@ -115,7 +121,6 @@
 	fi
  endif
 
-
 # This is done at 'make dist' time.  It builds the html and print docs
 # and copies them into the docs/ directory in the tarball.
  ifeq ($(BUILD_ALL_DOCS),yes)
@@ -133,3 +138,63 @@
 distclean-local:
 	rm -rf html print
 	rm -f $(top_builddir)/FAQ.txt
+
+
+
+# Note: the following three rules are nothing to do with the normal build tree.
+
+# chunked html with no html/body tags, css, or top nav, to fit into the website
+website-docs:
+	@echo "Generating website html files ..."
+	export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
+	/bin/rm -fr $(websitedir)
+	mkdir -p $(websitedir)
+	$(XSLTPROC) $(XSLTPROC_FLAGS) -o $(websitedir)/ $(XSL_WEBSITE_STYLE) $(myxmldir)/index.xml
+
+# valkyrie carries around her own copy of the valgrind manual
+valkyrie-docs:
+	@echo "Generating a set of valgrind docs for valkyrie..."
+	export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
+	/bin/rm -fr $(valkyriedir)
+	mkdir -p $(valkyriedir)
+	mkdir -p $(valkyriedir)/images
+	cp $(mylibdir)/vg_basic.css $(valkyriedir)/
+	cp $(myimgdir)/*.png $(valkyriedir)/images/
+	$(XSLTPROC) $(XSLTPROC_FLAGS) -o $(valkyriedir)/ $(XSL_HTML_CHUNK_STYLE) $(myxmldir)/index.xml
+
+# html.tar.bz2, .pdf, .ps.bz2 files for downloading from the website
+download-docs:
+	export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
+	/bin/rm -fr $(downloadsdir)
+	mkdir -p $(downloadsdir)
+	@echo ""
+	@echo "Generating valgrind_manual.html.tar.bz2 ..."
+	export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
+	/bin/rm -fr $(vgdir)
+	mkdir -p $(vgdir)
+	mkdir -p $(vgdir)/html
+	mkdir -p $(vgdir)/html/images
+	cp $(mylibdir)/vg_basic.css $(vgdir)/html/
+	cp $(myimgdir)/*.png $(vgdir)/html/images/
+	$(XSLTPROC) $(XSLTPROC_FLAGS) -o $(vgdir)/html/ $(XSL_HTML_CHUNK_STYLE) $(myxmldir)/index.xml
+	(cd $(top_builddir)/docs/ && \
+		(tar cfj $(downloadsdir)/valgrind_manual.html.tar.bz2 ./valgrind/html/ ) )
+	/bin/rm -fr $(vgdir)/html/
+	@echo ""
+	@echo "Generating valgrind_manual.pdf ..."
+	mkdir -p $(vgdir)/print
+	mkdir -p $(vgdir)/print/images
+	cp $(myimgdir)/massif-graph-sm.png $(vgdir)/print/images/
+	$(XSLTPROC) $(XSLTPROC_FLAGS) -o $(vgdir)/print/manual.fo $(XSL_FO_STYLE) $(myxmldir)/index.xml
+	(cd $(vgdir)/print/ && \
+		( pdfxmltex manual.fo && \
+		  pdfxmltex manual.fo && \
+		  pdfxmltex manual.fo ) &> $(LOGFILE) < /dev/null )
+	@echo ""
+	@echo "Generating valgrind_manual.ps.bz2 ..."
+	(cd $(vgdir)/print/ && \
+		( pdftops manual.pdf ) )
+	mv $(vgdir)/print/manual.pdf $(downloadsdir)/valgrind_manual.pdf
+	mv $(vgdir)/print/manual.ps $(downloadsdir)/valgrind_manual.ps
+	bzip2 $(downloadsdir)/valgrind_manual.ps
+	/bin/rm -fr $(vgdir)
diff --git a/docs/lib/Makefile.am b/docs/lib/Makefile.am
index 44acd8f..4775bda 100644
--- a/docs/lib/Makefile.am
+++ b/docs/lib/Makefile.am
@@ -1,6 +1,7 @@
-EXTRA_DIST =        \
-	vg-fo.xsl         \
-	vg-html-chunk.xsl \
-	vg-faq2txt.xsl    \
-	line-wrap.xsl     \
-	vg_basic.css
+EXTRA_DIST =          \
+	vg-fo.xsl           \
+	vg-html-chunk.xsl   \
+	vg-faq2txt.xsl      \
+	line-wrap.xsl       \
+	vg_basic.css        \
+	vg-html-website.xsl
diff --git a/docs/lib/vg-fo.xsl b/docs/lib/vg-fo.xsl
index ae4af84..30ffa4c 100644
--- a/docs/lib/vg-fo.xsl
+++ b/docs/lib/vg-fo.xsl
@@ -41,10 +41,12 @@
 qandaset  toc
 </xsl:param>
 
-<!-- properties common to html + fo -->
+<!-- properties common to html + fo ................................... -->
+
 <!-- we like '1.2 Title' -->
 <xsl:param name="section.autolabel" select="'1'"/> 
 <xsl:param name="section.label.includes.component.label" select="'1'"/>
+
 <!-- Do not put 'Chapter' at the start of eg 'Chapter 1. Doing This' -->
 <xsl:param name="local.l10n.xml" select="document('')"/> 
 <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"> 
@@ -55,6 +57,15 @@
   </l:l10n>
 </l:i18n>
 
+<!-- per Bob Stayton: turn off xml:base processing pro tem -->
+<!-- should hopefully be fixed in next docbook stylesheets release (1.70) -->
+<!-- ensures correct source paths, eg. images/my_img.png -->
+<xsl:template match="@fileref">
+  <xsl:value-of select="."/>
+</xsl:template>
+
+<!-- end properties common to html + fo ............................... -->
+
 
 <!-- Bug-fix for Suse 10 PassiveTex version -->
 <!-- Precompute attribute values 'cos PassiveTex is too stupid: -->
@@ -74,13 +85,6 @@
   <xsl:attribute name="hyphenate">false</xsl:attribute>
 </xsl:attribute-set>
 
-<!-- per Bob Stayton: turn off xml:base processing pro tem -->
-<!-- should hopefully be fixed in next docbook stylesheets release (1.70) -->
-<!-- ensures correct source paths, eg. images/my_img.png -->
-<xsl:template match="@fileref">
-  <xsl:value-of select="."/>
-</xsl:template>
-
 <!-- show links in color -->
 <xsl:attribute-set name="xref.properties">
   <xsl:attribute name="color">blue</xsl:attribute>
diff --git a/docs/lib/vg-html-chunk.xsl b/docs/lib/vg-html-chunk.xsl
index f9e943f..8241dde 100644
--- a/docs/lib/vg-html-chunk.xsl
+++ b/docs/lib/vg-html-chunk.xsl
@@ -38,7 +38,8 @@
 </xsl:param>
 
 
-<!-- properties common to html + fo -->
+<!-- properties common to html + fo ................................... -->
+
 <!-- we like '1.2 Title' -->
 <xsl:param name="section.autolabel" select="'1'"/> 
 <xsl:param name="section.label.includes.component.label" select="'1'"/>
@@ -59,6 +60,8 @@
   <xsl:value-of select="."/>
 </xsl:template>
 
+<!-- end properties common to html + fo ............................... -->
+
 
 <!-- center everything at the top of a titlepage -->
 <xsl:attribute-set name="set.titlepage.recto.style">
@@ -66,7 +69,33 @@
 </xsl:attribute-set>
 
 
-<!-- use our custom header -->
+<!-- don`t put an expanded set-level TOC, only book titles -->
+<xsl:template match="book" mode="toc">
+  <xsl:param name="toc-context" select="."/>
+  <xsl:choose>
+    <xsl:when test="local-name($toc-context) = 'set'">
+      <xsl:call-template name="subtoc">
+        <xsl:with-param name="toc-context" select="$toc-context"/>
+        <xsl:with-param name="nodes" select="foo"/>
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:call-template name="subtoc">
+        <xsl:with-param name="toc-context" select="$toc-context"/>
+        <xsl:with-param name="nodes" select="part|reference
+                                         |preface|chapter|appendix
+                                         |article
+                                         |bibliography|glossary|index
+                                         |refentry
+                                         |bridgehead[$bridgehead.in.toc !=
+0]"/>
+      </xsl:call-template>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+
+<!-- custom header for html docs -->
 <xsl:template name="header.navigation">
   <xsl:param name="prev" select="/foo"/>
   <xsl:param name="next" select="/foo"/>
@@ -148,16 +177,6 @@
      <!-- chapter|section heading -->
      <th align="center" valign="middle">
        <xsl:apply-templates select="$up" mode="object.title.markup"/>
-<!--
-      <xsl:choose>
-       <xsl:when test="count($up) > 0 and generate-id($up) != generate-id($home)">
-        <xsl:apply-templates select="$up" mode="object.title.markup"/>
-       </xsl:when>
-       <xsl:otherwise>
-        <xsl:text>Valgrind User`s Manual</xsl:text>
-       </xsl:otherwise>
-      </xsl:choose>
--->
      </th>
      <!-- next -->
       <td width="22px" align="center" valign="middle">
@@ -187,7 +206,7 @@
 </xsl:template>
 
 
-<!-- our custom footer -->
+<!-- custom footer -->
 <xsl:template name="footer.navigation">
   <xsl:param name="prev" select="/foo"/>
   <xsl:param name="next" select="/foo"/>
@@ -299,52 +318,8 @@
  </div>
 </xsl:template>
 
-<!-- We don`t like tables with borders -->
-<xsl:template match="revhistory" mode="titlepage.mode">
-  <xsl:variable name="numcols">
-    <xsl:choose>
-      <xsl:when test="//authorinitials">3</xsl:when>
-      <xsl:otherwise>2</xsl:otherwise>
-    </xsl:choose>
-  </xsl:variable>
-  <table width="100%" border="0" summary="Revision history">
-    <tr>
-      <th align="left" colspan="{$numcols}">
-        <h3>Revision History</h3>
-      </th>
-    </tr>
-    <xsl:apply-templates mode="titlepage.mode">
-      <xsl:with-param name="numcols" select="$numcols"/>
-    </xsl:apply-templates>
-  </table>
-</xsl:template>
 
-<!-- don`t put an expanded set-level TOC, only book titles -->
-<xsl:template match="book" mode="toc">
-  <xsl:param name="toc-context" select="."/>
-  <xsl:choose>
-    <xsl:when test="local-name($toc-context) = 'set'">
-      <xsl:call-template name="subtoc">
-        <xsl:with-param name="toc-context" select="$toc-context"/>
-        <xsl:with-param name="nodes" select="foo"/>
-      </xsl:call-template>
-    </xsl:when>
-    <xsl:otherwise>
-      <xsl:call-template name="subtoc">
-        <xsl:with-param name="toc-context" select="$toc-context"/>
-        <xsl:with-param name="nodes" select="part|reference
-                                         |preface|chapter|appendix
-                                         |article
-                                         |bibliography|glossary|index
-                                         |refentry
-                                         |bridgehead[$bridgehead.in.toc !=
-0]"/>
-      </xsl:call-template>
-    </xsl:otherwise>
-  </xsl:choose>
-</xsl:template>
-
-<!-- question and answer set mods -->
+<!-- faq styles -->
 <xsl:template match="answer">
   <xsl:variable name="deflabel">
     <xsl:choose>
diff --git a/docs/lib/vg-html-website.xsl b/docs/lib/vg-html-website.xsl
new file mode 100644
index 0000000..989dd7b
--- /dev/null
+++ b/docs/lib/vg-html-website.xsl
@@ -0,0 +1,433 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-common.xsl"/>
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/manifest.xsl"/>
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-code.xsl"/>
+
+<!-- special stylesheet to generate the docs to fit into the website    -->
+<!-- the only differences between this and vg-html-chunk.xsl should be: -->
+<!-- (a) no css stylesheet is used;        -->
+<!-- (b) no navigation header is used;     -->
+<!-- (c) no html start/end tags are output -->
+
+
+<!-- use 8859-1 encoding -->
+<xsl:output method="html" encoding="ISO-8859-1" indent="yes"/>
+
+<!-- set various parameters -->
+<xsl:param name="use.id.as.filename" select="'1'"/> 
+<xsl:param name="chunker.output.indent" select="'yes'"/>
+<!-- set chunking at the chapter level only -->
+<xsl:param name="chunk.section.depth" select="'0'"/> 
+<!-- do not generate sub-tocs for qanda sets -->
+<xsl:param name="generate.toc">
+set       toc,title
+book      toc,title,figure,table,example,equation
+chapter   toc,title
+section   toc
+sect1     toc
+sect2     toc
+sect3     toc
+sect4     nop
+sect5     nop
+qandaset  toc
+qandadiv  toc
+appendix  toc,title
+article/appendix  nop
+article   nop
+preface   toc,title
+reference toc,title
+</xsl:param>
+
+<!-- properties common to html + fo ................................... -->
+
+<!-- we like '1.2 Title' -->
+<xsl:param name="section.autolabel" select="'1'"/> 
+<xsl:param name="section.label.includes.component.label" select="'1'"/>
+
+<!-- Do not put 'Chapter' at the start of eg 'Chapter 1. Doing This' -->
+<xsl:param name="local.l10n.xml" select="document('')"/> 
+<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"> 
+  <l:l10n language="en"> 
+    <l:context name="title-numbered">
+      <l:template name="chapter" text="%n.&#160;%t"/>
+    </l:context> 
+  </l:l10n>
+</l:i18n>
+
+<!-- per Bob Stayton: turn off xml:base processing pro tem -->
+<!-- should hopefully be fixed in next docbook stylesheets release (1.70) -->
+<xsl:template match="@fileref">
+  <xsl:value-of select="."/>
+</xsl:template>
+
+<!-- end properties common to html + fo ............................... -->
+
+
+<!-- center everything at the top of a titlepage -->
+<xsl:attribute-set name="set.titlepage.recto.style">
+  <xsl:attribute name="align">center</xsl:attribute>
+</xsl:attribute-set>
+
+
+<!-- don`t put an expanded set-level TOC, only book titles -->
+<xsl:template match="book" mode="toc">
+  <xsl:param name="toc-context" select="."/>
+  <xsl:choose>
+    <xsl:when test="local-name($toc-context) = 'set'">
+      <xsl:call-template name="subtoc">
+        <xsl:with-param name="toc-context" select="$toc-context"/>
+        <xsl:with-param name="nodes" select="foo"/>
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:call-template name="subtoc">
+        <xsl:with-param name="toc-context" select="$toc-context"/>
+        <xsl:with-param name="nodes" 
+                        select="part|reference|preface|chapter|appendix
+                                |article|bibliography|glossary|index
+                                |refentry|bridgehead[$bridgehead.in.toc != 0]"/>
+      </xsl:call-template>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+
+<!-- custom header for website: no 'html' / 'body' etc. tags -->
+<xsl:template name="chunk-element-content">
+  <xsl:param name="prev"/>
+  <xsl:param name="next"/>
+  <xsl:param name="nav.context"/>
+  <xsl:param name="content">
+    <xsl:apply-imports/>
+  </xsl:param>
+  <xsl:copy-of select="$content"/>
+  <xsl:call-template name="footer.navigation">
+	  <xsl:with-param name="prev" select="$prev"/>
+	  <xsl:with-param name="next" select="$next"/>
+	  <xsl:with-param name="nav.context" select="$nav.context"/>
+  </xsl:call-template>
+</xsl:template>
+
+
+<!-- custom footer -->
+<xsl:template name="footer.navigation">
+  <xsl:param name="prev" select="/foo"/>
+  <xsl:param name="next" select="/foo"/>
+  <xsl:param name="nav.context"/>
+
+  <xsl:variable name="home" select="/*[1]"/>
+  <xsl:variable name="up" select="parent::*"/>
+
+  <xsl:variable name="row1" select="count($prev) &gt; 0
+                                    or count($up) &gt; 0
+                                    or count($next) &gt; 0"/>
+
+  <xsl:variable name="row2" select="($prev != 0)
+             or (generate-id($home) != generate-id(.) or $nav.context = 'toc')
+             or ($chunk.tocs.and.lots != 0 and $nav.context != 'toc')
+             or ($next != 0)"/>
+  <div>
+  <xsl:if test="$row1 or $row2">
+   <br />
+   <table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
+    <xsl:if test="$row1">
+     <tr>
+      <td rowspan="2" width="40%" align="left">
+       <xsl:if test="count($prev)>0">
+        <a accesskey="p">
+         <xsl:attribute name="href">
+          <xsl:call-template name="href.target">
+           <xsl:with-param name="object" select="$prev"/>
+          </xsl:call-template>
+         </xsl:attribute>
+         <xsl:text>&#060;&#060;&#160;</xsl:text>
+         <xsl:apply-templates select="$prev" mode="object.title.markup"/>
+        </a>
+       </xsl:if>
+       <xsl:text>&#160;</xsl:text>
+      </td>
+      <td width="20%" align="center">
+       <xsl:choose>
+        <xsl:when test="count($up)>0">
+         <a accesskey="u">
+          <xsl:attribute name="href">
+           <xsl:call-template name="href.target">
+            <xsl:with-param name="object" select="$up"/>
+           </xsl:call-template>
+          </xsl:attribute>
+          <xsl:call-template name="navig.content">
+           <xsl:with-param name="direction" select="'up'"/>
+          </xsl:call-template>
+         </a>
+        </xsl:when>
+        <xsl:otherwise>&#160;</xsl:otherwise>
+       </xsl:choose>
+      </td>
+      <td rowspan="2" width="40%" align="right">
+       <xsl:text>&#160;</xsl:text>
+       <xsl:if test="count($next)>0">
+        <a accesskey="n">
+         <xsl:attribute name="href">
+          <xsl:call-template name="href.target">
+           <xsl:with-param name="object" select="$next"/>
+          </xsl:call-template>
+         </xsl:attribute>
+         <xsl:apply-templates select="$next" mode="object.title.markup"/>
+         <xsl:text>&#160;&#062;&#062;</xsl:text>
+        </a>
+       </xsl:if>
+      </td>
+     </tr>
+    </xsl:if>
+    <xsl:if test="$row2">
+     <tr>
+      <td width="20%" align="center">
+       <xsl:choose>
+       <xsl:when test="$home != . or $nav.context = 'toc'">
+        <a accesskey="h">
+         <xsl:attribute name="href">
+          <xsl:call-template name="href.target">
+           <xsl:with-param name="object" select="$home"/>
+          </xsl:call-template>
+         </xsl:attribute>
+         <xsl:call-template name="navig.content">
+          <xsl:with-param name="direction" select="'home'"/>
+         </xsl:call-template>
+        </a>
+        <xsl:if test="$chunk.tocs.and.lots != 0 and $nav.context != 'toc'">
+         <xsl:text>&#160;|&#160;</xsl:text>
+        </xsl:if>
+       </xsl:when>
+       <xsl:otherwise>&#160;</xsl:otherwise>
+       </xsl:choose>
+       <xsl:if test="$chunk.tocs.and.lots != 0 and $nav.context != 'toc'">
+        <a accesskey="t">
+         <xsl:attribute name="href">
+          <xsl:apply-templates select="/*[1]" mode="recursive-chunk-filename"/>
+          <xsl:text>-toc</xsl:text>
+          <xsl:value-of select="$html.ext"/>
+         </xsl:attribute>
+         <xsl:call-template name="gentext">
+          <xsl:with-param name="key" select="'nav-toc'"/>
+         </xsl:call-template>
+        </a>
+       </xsl:if>
+      </td>
+     </tr>
+    </xsl:if>
+   </table>
+  </xsl:if>
+ </div>
+</xsl:template>
+
+
+<!-- qandaset styles -->
+<!-- these templates have been carefully tweaked to correct the horrible -->
+<!-- mess that docbook makes of dl/dt/dd tags. Edit with care.           -->
+<xsl:template match="qandaset">
+  <xsl:variable name="title" select="(blockinfo/title|title)[1]"/>
+  <xsl:variable name="toc">
+    <xsl:call-template name="dbhtml-attribute">
+      <xsl:with-param name="pis" select="processing-instruction('dbhtml')"/>
+      <xsl:with-param name="attribute" select="'toc'"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:variable name="toc.params">
+    <xsl:call-template name="find.path.params">
+      <xsl:with-param name="table" select="normalize-space($generate.toc)"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <div class="{name(.)}">
+    <xsl:apply-templates select="$title"/>
+    <xsl:if test="(contains($toc.params, 'toc') and $toc != '0') or $toc = '1'">
+      <xsl:call-template name="process.qanda.toc"/>
+    </xsl:if>
+    <xsl:apply-templates select="qandaentry|qandadiv"/>
+  </div>
+</xsl:template>
+
+
+<xsl:template match="qandadiv">
+<!--
+  <hr/>
+-->
+  <br/>
+  <table width="100%" summary="Q and A Div" cellpadding="2" cellspacing="2" border="0">
+  <xsl:if test="blockinfo/title|title">
+    <tr class="qandadiv">
+      <td align="left" valign="top" colspan="2">
+        <xsl:call-template name="anchor">
+          <xsl:with-param name="conditional" select="0"/>
+        </xsl:call-template>
+        <xsl:apply-templates select="(blockinfo/title|title)[1]"/>
+      </td>
+    </tr>
+  </xsl:if>
+
+  <xsl:variable name="toc">
+    <xsl:call-template name="dbhtml-attribute">
+      <xsl:with-param name="pis"
+                      select="processing-instruction('dbhtml')"/>
+      <xsl:with-param name="attribute" select="'toc'"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:variable name="toc.params">
+    <xsl:call-template name="find.path.params">
+      <xsl:with-param name="table" select="normalize-space($generate.toc)"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:if test="(contains($toc.params, 'toc') and $toc != '0') or $toc = '1'">
+    <tr class="toc" colspan="2">
+      <td align="left" valign="top" colspan="2">
+        <xsl:call-template name="process.myqanda.toc"/>
+      </td>
+    </tr>
+  </xsl:if>
+  <xsl:apply-templates select="qandadiv|qandaentry"/>
+  </table>
+</xsl:template>
+
+
+<!-- put questions in bold -->
+<xsl:template match="question/para">
+  <b><xsl:apply-templates/></b>
+</xsl:template>
+
+<xsl:template match="question">
+  <xsl:variable name="deflabel">
+    <xsl:choose>
+      <xsl:when test="ancestor-or-self::*[@defaultlabel]">
+        <xsl:value-of select="(ancestor-or-self::*[@defaultlabel])[last()]
+                              /@defaultlabel"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$qanda.defaultlabel"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+  <tr><td colspan="2"><xsl:text>&#160;</xsl:text></td></tr>
+  <tr class="{name(.)}">
+    <td align="left" valign="top">
+      <xsl:call-template name="anchor">
+        <xsl:with-param name="node" select=".."/>
+        <xsl:with-param name="conditional" select="0"/>
+      </xsl:call-template>
+      <xsl:call-template name="anchor">
+        <xsl:with-param name="conditional" select="0"/>
+      </xsl:call-template>
+      <b>
+        <xsl:apply-templates select="." mode="label.markup"/>
+        <xsl:if test="$deflabel = 'number' and not(label)">
+          <xsl:apply-templates select="." mode="intralabel.punctuation"/>
+	      </xsl:if>
+      </b>
+    </td>
+    <td align="left" valign="top">
+      <xsl:choose>
+        <xsl:when test="$deflabel = 'none' and not(label)">
+          <b><xsl:apply-templates select="*[name(.) != 'label']"/></b>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:apply-templates select="*[name(.) != 'label']"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </td>
+  </tr>
+</xsl:template>
+
+
+<xsl:template name="process.myqanda.toc">
+  <xsl:apply-templates select="qandadiv" mode="qandatoc.mode"/>
+  <xsl:apply-templates select="qandaentry" mode="myqandatoc.mode"/>
+</xsl:template>
+
+
+<xsl:template name="process.qanda.toc">
+  <xsl:apply-templates select="qandadiv" mode="qandatoc.mode"/>
+  <xsl:apply-templates select="qandaentry" mode="qandatoc.mode"/>
+</xsl:template>
+
+
+<xsl:template match="qandadiv" mode="qandatoc.mode">
+<dl>
+  <dt><xsl:apply-templates select="title" mode="qandatoc.mode"/></dt>
+  <xsl:call-template name="process.qanda.toc"/>
+</dl>
+</xsl:template>
+
+
+<!-- this one is used at the top of the page -->
+<xsl:template match="question" mode="qandatoc.mode">
+  <xsl:variable name="firstch" select="(*[name(.)!='label'])[1]"/>
+  <xsl:variable name="deflabel">
+    <xsl:choose>
+      <xsl:when test="ancestor-or-self::*[@defaultlabel]">
+        <xsl:value-of select="(ancestor-or-self::*[@defaultlabel])[last()]
+                              /@defaultlabel"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$qanda.defaultlabel"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+  <dd>
+    <xsl:apply-templates select="." mode="label.markup"/>
+    <xsl:if test="$deflabel = 'number' and not(label)">
+      <xsl:apply-templates select="." mode="intralabel.punctuation"/>
+    </xsl:if>
+    <xsl:text> </xsl:text>
+    <a>
+      <xsl:attribute name="href">
+        <xsl:call-template name="href.target">
+          <xsl:with-param name="object" select=".."/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:value-of select="$firstch"/>
+    </a>
+  </dd>
+</xsl:template>
+
+
+<!-- this one is used within table cells -->
+<xsl:template match="qandaentry" mode="myqandatoc.mode">
+  <xsl:apply-templates select="question" mode="myqandatoc.mode"/>
+</xsl:template>
+
+<xsl:template match="question" mode="myqandatoc.mode">
+  <xsl:variable name="firstch" select="(*[name(.)!='label'])[1]"/>
+  <xsl:variable name="deflabel">
+    <xsl:choose>
+      <xsl:when test="ancestor-or-self::*[@defaultlabel]">
+        <xsl:value-of select="(ancestor-or-self::*[@defaultlabel])[last()]
+                              /@defaultlabel"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$qanda.defaultlabel"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+    <xsl:apply-templates select="." mode="label.markup"/>
+    <xsl:if test="$deflabel = 'number' and not(label)">
+      <xsl:apply-templates select="." mode="intralabel.punctuation"/>
+    </xsl:if>
+    <xsl:text> </xsl:text>
+    <a>
+      <xsl:attribute name="href">
+        <xsl:call-template name="href.target">
+          <xsl:with-param name="object" select=".."/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:value-of select="$firstch"/>
+    </a>
+  <br />
+</xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
index dd486a6..7c275ea 100644
--- a/docs/xml/FAQ.xml
+++ b/docs/xml/FAQ.xml
@@ -3,6 +3,7 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
+
 <book id="FAQ" xreflabel="Valgrind FAQ">
 
 <bookinfo>
@@ -18,7 +19,7 @@
 </bookinfo>
 
 
-<article>
+<article id="faq">
 <title>Valgrind Frequently Asked Questions</title>
 
 
@@ -523,11 +524,9 @@
   <para>If you think an answer is incomplete or inaccurate, please
   e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
 
-  <para>Read the appropriate section(s) of the 
-  <ulink url="http://www.valgrind.org/docs/manual.html">Valgrind 
-  Documentation</ulink>.</para>
+  <para>Read the appropriate section(s) of the <xref linkend="set-index"/>.</para>
 
-  <para>Read the <ulink url="http://www.valgrind.org/docs/dist.html">Distribution Documents</ulink>.</para>
+  <para>Read the <xref linkend="dist"/>.</para>
 
   <para><ulink url="http://search.gmane.org">Search</ulink> the 
   <ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name 
diff --git a/docs/xml/dist-docs.xml b/docs/xml/dist-docs.xml
index 3e99c39..85302a8 100644
--- a/docs/xml/dist-docs.xml
+++ b/docs/xml/dist-docs.xml
@@ -3,6 +3,7 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
+
 <book id="dist" xreflabel="Distribution Documents">
 
   <bookinfo>
@@ -17,8 +18,8 @@
   </author>
   </bookinfo>
 
-  <!-- Nb: because these are all text files, we have to wrap them in suitable
-       XML.  Hence the chapter/title stuff -->
+  <!-- Nb: because these are all text files, we have to wrap -->
+  <!-- them in suitable XML.  Hence the chapter/title stuff  -->
 
   <chapter id="dist.acknowledge" xreflabel="Acknowledgements">
     <title>ACKNOWLEDGEMENTS</title>
diff --git a/docs/xml/index.xml b/docs/xml/index.xml
index 1a240df..0feec65 100644
--- a/docs/xml/index.xml
+++ b/docs/xml/index.xml
@@ -1,12 +1,10 @@
 <?xml version="1.0"?> <!-- -*- sgml -*- -->
 <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[
- <!-- various strings, dates etc. common to all docs -->
- <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities;
-]>
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
-<set id="index" lang="en">
+
+<set lang="en" id="set-index" xreflabel="Valgrind Documentation">
 
   <setinfo>
     <title>Valgrind Documentation</title>
@@ -19,13 +17,12 @@
     </copyright>
 
     <legalnotice>
-      <para>Permission is granted to copy, distribute and/or
-      modify this document under the terms of the GNU Free
-      Documentation License, Version 1.2 or any later version
-      published by the Free Software Foundation; with no
-      Invariant Sections, with no Front-Cover Texts, and with no
-      Back-Cover Texts.  A copy of the license is included in the
-      section entitled <xref linkend="license.gfdl"/>.</para>
+      <para>Permission is granted to copy, distribute and/or 
+      modify this document under the terms of the GNU Free Documentation License,
+      Version 1.2 or any later version published by the Free Software Foundation; 
+      with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+      Texts.  A copy of the license is included in the section entitled 
+      <xref linkend="license.gfdl"/>.</para>
     </legalnotice>
 
   </setinfo>
diff --git a/docs/xml/licenses.xml b/docs/xml/licenses.xml
index 2b31e9a..e9c4ef6 100644
--- a/docs/xml/licenses.xml
+++ b/docs/xml/licenses.xml
@@ -11,8 +11,7 @@
   <chapter id="license.gpl" xreflabel=" The GNU General Public License">
     <title>The GNU General Public License</title>
       <literallayout>
-      <xi:include href="../../COPYING" 
-          parse="text"  
+      <xi:include href="../../COPYING" parse="text"  
           xmlns:xi="http://www.w3.org/2001/XInclude" />
       </literallayout>
   </chapter>
@@ -20,8 +19,7 @@
   <chapter id="license.gfdl" xreflabel="The GNU Free Documentation License">
     <title>The GNU Free Documentation License</title>
       <literallayout>
-      <xi:include href="../../COPYING.DOCS" 
-          parse="text"  
+      <xi:include href="../../COPYING.DOCS" parse="text"  
           xmlns:xi="http://www.w3.org/2001/XInclude" />
       </literallayout>
   </chapter>
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
index 64d28f7..4585812 100644
--- a/docs/xml/manual-core.xml
+++ b/docs/xml/manual-core.xml
@@ -1,6 +1,8 @@
 <?xml version="1.0"?> <!-- -*- sgml -*- -->
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
+
 
 <chapter id="manual-core" xreflabel="Valgrind's core">
 <title>Using and understanding the Valgrind core</title>
@@ -1558,7 +1560,7 @@
 <sect1 id="manual-core.problems" xreflabel="If You Have Problems">
 <title>If You Have Problems</title>
 
-<para>Contact us at <ulink url="http://www.valgrind.org">http://www.valgrind.org</ulink>.</para>
+<para>Contact us at <ulink url="&vg-url;">&vg-url;</ulink>.</para>
 
 <para>See <xref linkend="manual-core.limits"/> for the known
 limitations of Valgrind, and for a list of programs which are
@@ -1577,9 +1579,8 @@
 effect before dying in this way.  This is a known problem which
 we should fix.</para>
 
-<para>Read the 
-<ulink url="http://www.valgrind.org/docs/FAQ/">FAQ</ulink> for
-more advice about common problems, crashes, etc.</para>
+<para>Read the <xref linkend="FAQ"/> for more advice about common problems, 
+crashes, etc.</para>
 
 </sect1>
 
diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml
index e7c716c..c7080d0 100644
--- a/docs/xml/manual-intro.xml
+++ b/docs/xml/manual-intro.xml
@@ -114,7 +114,7 @@
 
     <para>Cachegrind is nicely complemented by Josef
     Weidendorfer's amazing KCacheGrind visualisation tool 
-    (<ulink url="http://kcachegrind.sourceforge.net">http://kcachegrind.sourceforge.net</ulink>),
+    (<ulink url="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindIndex">http://kcachegrind.sourceforge.net</ulink>),
     a KDE application which presents these profiling results in a
     graphical and easier-to-understand form.</para>
    </listitem>
diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml
index 39fc83c..aa2f8c1 100644
--- a/docs/xml/manual.xml
+++ b/docs/xml/manual.xml
@@ -29,7 +29,7 @@
   <xi:include href="../../cachegrind/docs/cg-manual.xml" parse="xml"  
       xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="../../massif/docs/ms-manual.xml" parse="xml"  
-       xmlns:xi="http://www.w3.org/2001/XInclude" />
+      xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="../../helgrind/docs/hg-manual.xml" parse="xml"  
       xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="../../none/docs/nl-manual.xml" parse="xml"  
diff --git a/docs/xml/quick-start-guide.xml b/docs/xml/quick-start-guide.xml
index 6616cd0..d4daf27 100644
--- a/docs/xml/quick-start-guide.xml
+++ b/docs/xml/quick-start-guide.xml
@@ -3,7 +3,7 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
-<book id="quick-start" xreflabel="Valgrind Quick Start Guide">
+<book id="QuickStart" xreflabel="Valgrind Quick Start Guide">
 
 <bookinfo>
   <title>The Valgrind Quick Start Guide</title>
@@ -18,7 +18,7 @@
 </bookinfo>
 
 
-<article>
+<article id="quick-start">
 <title>The Valgrind Quick Start Guide</title>
 
 
diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml
index d072a46..8448053 100644
--- a/docs/xml/vg-entities.xml
+++ b/docs/xml/vg-entities.xml
@@ -1,13 +1,18 @@
 <!-- misc. strings -->
-<!ENTITY vg-url      "http://www.valgrind.org">
-<!ENTITY vg-jemail   "julian@valgrind.org">
-<!ENTITY vg-vemail   "valgrind@valgrind.org">
-<!ENTITY vg-lifespan "2000-2005">
+<!ENTITY vg-url        "http://www.valgrind.org/">
+<!ENTITY vg-jemail     "julian@valgrind.org">
+<!ENTITY vg-vemail     "valgrind@valgrind.org">
+<!ENTITY vg-lifespan   "2000-2005">
 <!ENTITY vg-users-list "http://lists.sourceforge.net/lists/listinfo/valgrind-users">
 <!ENTITY vg-developers "http://www.valgrind.org/info/developers.html">
+<!ENTITY vg-svn-repo   "http://www.valgrind.org/downloads/repository.html">
+
 
 <!-- valgrind release + version stuff -->
 <!ENTITY rel-type    "Release">
 <!ENTITY rel-version "3.1.0">
 <!ENTITY rel-date    "November 25 2005">
 
+<!-- valgrind website links used in lots of places in the docs  -->
+<!-- kept in here 'cos everytime the website gets changed, it`s -->
+<!-- a real pain tracking the links down in the docs            -->
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
index ee6d335..22318d9 100644
--- a/docs/xml/writing-tools.xml
+++ b/docs/xml/writing-tools.xml
@@ -1,8 +1,7 @@
 <?xml version="1.0"?> <!-- -*- sgml -*- -->
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
-<!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities;
-]>
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
 
 <chapter id="writing-tools" xreflabel="Writing a New Valgrind Tool">
 <title>Writing a New Valgrind Tool</title>
@@ -302,9 +301,8 @@
 <para>To write your own tool, you'll need the Valgrind source code.
 A normal source distribution should do, although you might want to
 check out the latest code from the Subversion repository.  See the
-information about how to do so at
-<ulink url="http://www.valgrind.org/downloads/repository.html">the
-Valgrind website</ulink>.</para>
+information about how to do so at 
+<ulink url="&vg-svn-repo;">the Valgrind website</ulink>.</para>
 
 </sect2>
 
@@ -761,7 +759,7 @@
 <para>If you aren't confident using XML, or you have problems
 with the toolchain, then write your documentation in text format,
 email it to
-<computeroutput>valgrind@valgrind.org</computeroutput>, and
+<computeroutput>&vg-vemail;</computeroutput>, and
 someone will convert it to XML for you.  Otherwise, follow these
 steps (using <computeroutput>foobar</computeroutput> as the
 example tool name again):</para>
@@ -862,7 +860,7 @@
 ]]></programlisting>
 
   <para>Send a patch for this to
-  <computeroutput>valgrind@valgrind.org</computeroutput>.</para>
+  <computeroutput>&vg-vemail;</computeroutput>.</para>
 
   <para>To achieve true anality, try for a full doc-set build:</para>
 <screen><![CDATA[