From: Mark Wielaard <mark@klomp.org>
Date: Tue, 9 Jun 2020 09:23:46 +0000 (+0200)
Subject: docs: Make sure all elements that need it have an id tag.
X-Git-Tag: VALGRIND_3_17_0~180
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a489f40f78cee5559c230699befe11ff52388c28;p=thirdparty%2Fvalgrind.git

docs: Make sure all elements that need it have an id tag.

When generating HTML it is useful if every element that can be referenced
has a stable id. If it doesn't a random one is generated which makes it
harder to link to parts of the manual on the website. It also generates
spurious diffs. Explicitly add an id tag for the sect2 and sect3 elements
in dh-manual, a unique id for each legalnotice element and for each
FAQ question and answer.
---

diff --git a/dhat/docs/dh-manual.xml b/dhat/docs/dh-manual.xml
index f52cca204d..6b9f1cb3f9 100644
--- a/dhat/docs/dh-manual.xml
+++ b/dhat/docs/dh-manual.xml
@@ -153,7 +153,7 @@ smaller <option>--num-callers</option> value to reduce the stack depths,
 because this can significantly reduce the size of DHAT's output files.</para>
 
 
-<sect2><title>The Output Header</title>
+<sect2 id="dh-output-header"><title>The Output Header</title>
 
 <para>The first part of the output shows the program command and process ID.
 For example:</para>
@@ -179,13 +179,13 @@ Times {
 </sect2>
 
 
-<sect2><title>The AP Tree</title>
+<sect2 id="dh-ap-tree"><title>The AP Tree</title>
 
 <para>The third part of the output is the largest and most interesting part,
 showing the allocation point (AP) tree.</para>
 
 
-<sect3><title>Structure</title>
+<sect3 id="dh-structure"><title>Structure</title>
 
 <para>The following image shows a screenshot of part of an AP
 tree. The font is very small because this screenshot is intended to
@@ -223,7 +223,7 @@ email, bug report, etc.</para>
 </sect3>
 
 
-<sect3><title>The Root Node</title>
+<sect3 id="dh-root-node"><title>The Root Node</title>
 
 <para>The root node looks like this:</para>
 
@@ -248,7 +248,7 @@ next example will explain these in more detail.</para>
 </sect3>
 
 
-<sect3><title>Interior Nodes</title>
+<sect3 id="dh-interior-nodes"><title>Interior Nodes</title>
 
 <para>AP nodes further down the tree show information about a subset of
 allocations. For example:</para>
@@ -331,7 +331,7 @@ vectors and hash tables, and isn't always fixable. </para>
 </sect3>
 
 
-<sect3><title>Leaf Nodes</title>
+<sect3 id="dh-leaf-nodes"><title>Leaf Nodes</title>
 
 <para>This is a leaf node:</para>
 
@@ -381,7 +381,7 @@ This also means that each node makes complete sense on its own.</para>
 </sect3>
 
 
-<sect3><title>Access Counts</title>
+<sect3 id="dh-access-counts"><title>Access Counts</title>
 
 <para>If all blocks covered by an AP node have the same size, an additional
 <computeroutput>Accesses</computeroutput> field will be present. It indicates
@@ -423,7 +423,7 @@ layout inefficiencies.</para>
 </sect3>
 
 
-<sect3><title>Aggregate Nodes</title>
+<sect3 id="aggregate-nodes"><title>Aggregate Nodes</title>
 
 <para>The AP tree is very large and many nodes represent tiny numbers of blocks
 and bytes. Therefore, DHAT's viewer aggregates insignificant nodes like
@@ -447,7 +447,7 @@ case).</para>
 </sect2>
 
 
-<sect2><title>The Output Footer</title>
+<sect2 id="dh-output-footer"><title>The Output Footer</title>
 
 <para>Below the AP tree is a line like this:</para>
 
@@ -466,7 +466,7 @@ terms, abbreviations and symbols used in the output.</para>
 </sect2>
 
 
-<sect2><title>Sort Metrics</title>
+<sect2 id="dh-sort-metrics"><title>Sort Metrics</title>
 
 <para>The order in which sub-trees are sorted can be changed via the "Sort
 metric" drop-down menu at the top of DHAT's viewer. Different sort metrics can
diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
index 845f5bb96c..414ac1364b 100644
--- a/docs/xml/FAQ.xml
+++ b/docs/xml/FAQ.xml
@@ -13,7 +13,7 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-devs-url;">Valgrind Developers</ulink></holder>
   </copyright>
-  <legalnotice>
+  <legalnotice id="faq-legal">
     <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
   </legalnotice>
 </bookinfo>
@@ -96,14 +96,14 @@
 </qandaentry>
 
 <qandaentry id="faq.glibc_devel">
- <question>
+ <question id="q-glibc_devel">
   <para>When building Valgrind, 'make' fails with this:</para>
 <screen>
 /usr/bin/ld: cannot find -lc
 collect2: ld returned 1 exit status
 </screen>
  </question>
- <answer>
+ <answer id="a-glibc_devel">
   <para>You need to install the glibc-static-devel package.</para>
  </answer>
 </qandaentry>
@@ -629,7 +629,7 @@ is built standalone as FAQ.txt.  That's why we link to, for example, the
 online copy of the manual. -->
 
 <qandaentry id="e-help">
-  <question><para>Where can I get more help?</para></question>
+  <question id="q-help"><para>Where can I get more help?</para></question>
   <answer id="a-help">
   <para>Read the appropriate section(s) of the 
   <ulink url="&vg-docs-url;">Valgrind Documentation</ulink>.</para>
diff --git a/docs/xml/dist-docs.xml b/docs/xml/dist-docs.xml
index 9bf4d100ae..b1b5598fb0 100644
--- a/docs/xml/dist-docs.xml
+++ b/docs/xml/dist-docs.xml
@@ -13,7 +13,7 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-devs-url;">Valgrind Developers</ulink></holder>
   </copyright>
-  <legalnotice>
+  <legalnotice id="dist-legal">
     <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
   </legalnotice>
 </bookinfo>
diff --git a/docs/xml/index.xml b/docs/xml/index.xml
index 3bdb38aa12..4166239ef5 100644
--- a/docs/xml/index.xml
+++ b/docs/xml/index.xml
@@ -16,7 +16,7 @@
       </holder>
     </copyright>
 
-    <legalnotice>
+    <legalnotice id="legal">
       <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
diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml
index e71a9cf750..518be2964e 100644
--- a/docs/xml/manual.xml
+++ b/docs/xml/manual.xml
@@ -13,7 +13,7 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-devs-url;">Valgrind Developers</ulink></holder>
    </copyright>
-   <legalnotice>
+   <legalnotice id="manual-legal">
      <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
    </legalnotice>
 </bookinfo>
diff --git a/docs/xml/quick-start-guide.xml b/docs/xml/quick-start-guide.xml
index a61f5f095a..0f5e0a5f8a 100644
--- a/docs/xml/quick-start-guide.xml
+++ b/docs/xml/quick-start-guide.xml
@@ -12,7 +12,7 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-devs-url;">Valgrind Developers</ulink></holder>
   </copyright>
-  <legalnotice>
+  <legalnotice id="quickstart-legal">
     <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
   </legalnotice>
 </bookinfo>
diff --git a/docs/xml/tech-docs.xml b/docs/xml/tech-docs.xml
index 28070f970c..2e077fc1d3 100644
--- a/docs/xml/tech-docs.xml
+++ b/docs/xml/tech-docs.xml
@@ -12,7 +12,7 @@
     <year>&vg-lifespan;</year>
     <holder><ulink url="&vg-devs-url;">Valgrind Developers</ulink></holder>
   </copyright>
-  <legalnotice>
+  <legalnotice id="tech-legal">
     <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
   </legalnotice>
 </bookinfo>