Merge pull request #4764 from mwichmann/doc/uguide-tags

Add remaining links to User Guide sections

Author: bdbaddog

CHANGES.txt

@@ -183,6 +183,11 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       and unchanged target and source lists are accounted for to resolve.
       Fixes #3029.
     - Improve documentation of builder methods and builder objects.
+    - Add tags to the remaining section headers in the User Guide. This is
+      visible only in two ways: it's possible to link to any section now,
+      and the generated html will no longer have obscure links
+      (e.g. https://scons.org/doc/production/HTML/scons-user.html#id1514)
+      that may change over time.
 
 
 RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700

RELEASE.txt

@@ -156,6 +156,10 @@ DOCUMENTATION
 
 - Improve documentation of builder methods and builder objects.
 
+- All the User Guide sections now have textual anchors, meaning there
+  no longer be build-generated numeric tags like
+  https://scons.org/doc/production/HTML/scons-user.html#id1514
+
 DEVELOPMENT
 -----------
 

doc/user/actions.xml

@@ -29,7 +29,9 @@ This file is processed by the bin/SConsDoc.py module.
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 <title>&SCons; Actions</title>
 
-<!--
+<!-- TOOD: placeholder file, not currently included in build -->
+
+<!-- cons reference documentation:
 
 =head1 Build actions
 
@@ -272,10 +274,10 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </para>
 
-  <section>
+  <section id="sect-cmdstr-actions">
   <title>Command Strings as Actions</title>
 
-    <section>
+    <section id="sect-suppress-cmdline">
     <title>Suppressing Command-Line Printing</title>
 
     <para>
@@ -286,7 +288,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
     </section>
 
-    <section>
+    <section id="sect-ignore-exit-status">
     <title>Ignoring Exit Status</title>
 
     <para>
@@ -299,7 +301,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-arglist-actions">
   <title>Argument Lists as Actions</title>
 
   <para>
@@ -310,7 +312,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-python-func-actions">
   <title>Python Functions as Actions</title>
 
   <para>
@@ -321,10 +323,10 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-modify-printing">
   <title>Modifying How an Action is Printed</title>
 
-    <section>
+    <section id="sect-strfunc-cmdstr">
     <title>XXX:  the &strfunction; keyword argument</title>
 
     <para>
@@ -335,7 +337,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
     </section>
 
-    <section>
+    <section id="sect-cmdstr-cmdstr">
     <title>XXX:  the &cmdstr; keyword argument</title>
 
     <para>
@@ -348,7 +350,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-varlist">
   <title>Making an Action Depend on Variable Contents:  the &varlist; keyword argument</title>
 
   <para>
@@ -359,7 +361,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-chdir">
   <title>chdir=1</title>
 
   <para>
@@ -370,7 +372,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-batch-key">
   <title>Batch Building of Multiple Targets from Separate Sources:  the &batch_key; keyword argument</title>
 
   <para>
@@ -381,7 +383,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   </section>
 
-  <section>
+  <section id="sect-exitstatfunc">
   <title>Manipulating the Exit Status of an Action:  the &exitstatfunc; keyword argument</title>
 
   <para>
@@ -396,7 +398,7 @@ b = Builder(action = Action('build &lt; $SOURCE &gt; $TARGET'))
 
   ???
 
-  <section>
+  <section id="sect-presub">
   <title>presub=</title>
 
   <para>

doc/user/ant.xml

@@ -29,13 +29,15 @@ This file is processed by the bin/SConsDoc.py module.
           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 <title>Converting From Ant</title>
 
+<!-- TOOD: placeholder file, not currently included in build -->
+
  <para>
 
    XXX
 
  </para>
 
- <section>
+ <section id="sect-ant-diff">
  <title>Differences Between &Ant; and &SCons;</title>
 
    <para>
@@ -46,7 +48,7 @@ This file is processed by the bin/SConsDoc.py module.
 
  </section>
 
- <section>
+ <section id="sect-ant-adv">
  <title>Advantages of &SCons; Over &Ant;</title>
 
    <para>

doc/user/build-install.xml

@@ -366,7 +366,7 @@ $ <emphasis>activate a virtualenv and run 'scons' to use that version</emphasis>
 
   <!--
 
-  <section>
+  <section id="sect-python-basics">
   <title>Python Basics</title>
 
     <para>