Merge pull request #4849 from mwichmann/doc/linking-and-entities

Minor doc fixes for linking

Author: bdbaddog

CHANGES.txt

@@ -83,6 +83,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       and tweak wording a bit.
     - zip tool now uses zipfile module's "from_file" method to populate
       ZipInfo records, rather than doing manually.
+    - Update documentation for linking-related construction variables.
+      Add a few more live links.
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700

RELEASE.txt

@@ -121,6 +121,9 @@ DOCUMENTATION
 - Clarify VariantDir behavior when switching to not duplicate sources
   and tweak wording a bit.
 
+- Update documentation for linking-related construction variables.
+  Add a few more live links.
+
 DEVELOPMENT
 -----------
 

SCons/Environment.xml

@@ -2783,7 +2783,7 @@ and added to the following &consvars;:
 Any other strings not associated with options
 are assumed to be the names of libraries
 and added to the
-&cv-LIBS; &consvar;.
+&cv-link-LIBS; &consvar;.
 </para>
 
 <para>

SCons/Script/Main.xml

@@ -82,7 +82,7 @@ as long as they can be unambiguously resolved.
 For example, if
 <function>add_option</function> is called to
 define a <option>--devicename</option> option,
-it will recognize <option>--device</option>,
+it will also recognize <option>--device</option>,
 <option>--dev</option>
 and so forth as long as there is no other option
 which could also match to the same abbreviation.
@@ -200,9 +200,11 @@ Future versions of &SCons; will likely forbid such usage.
 </arguments>
 <summary>
 <para>
-Allows setting options for SCons debug options. Currently, the only supported value is
-  <emphasis>json</emphasis> which sets the path to the JSON file created when
-  <literal>--debug=json</literal> is set.
+Allows setting values for SCons debug options.
+Currently, the only supported value is
+<emphasis>json</emphasis> which sets the path to the JSON file created when the
+<link linkend="opt-debug"><option>--debug=json</option></link>
+argument is given.
 </para>
   <example_commands>
 DebugOptions(json='#/build/output/scons_stats.json')
@@ -436,7 +438,7 @@ processed prior to the &f-GetOption; call in the &SConscript; files.
 </row>
 <row>
   <entry><varname>config</varname></entry>
-  <entry><option>--config</option></entry>
+  <entry><link linkend="opt-config"><option>--config</option></link></entry>
 </row>
 <row>
   <entry><varname>debug</varname></entry>
@@ -1171,13 +1173,13 @@ SetOption('max_drift', 0)
       </para>
 
       <screen>
-$ <userinput>scons --compilers=mingw</userinput>  # the correct flag is --compiler
+$ <userinput>scons --complier=mingw</userinput>  # the correct flag is --compiler
       </screen>
 
       <para>
-        Here &SCons; could go off and run a bunch of configure steps with
-        the default value of <literal>--compiler</literal>, since the
-        incorrect command line did not actually supply a value to it,
+        Here &SCons; could go off and run a bunch of configure steps using
+        the default value of <option>--compiler</option>, since the
+        misspelled option causes it not to be supplied the intended value,
         costing developer time to track down why the configure logic
         made the "wrong" choices.  This example shows catching this:
       </para>

SCons/Script/SConscript.xml

@@ -278,7 +278,7 @@ file is found.
 <para>
 Adds <parameter>text</parameter> to the help message shown when
 &scons; is called with the
-<option>-h</option> or <option>--help</option>
+<link linkend="opt-help"><option>-h</option> or <option>--help</option></link>
 argument.
 </para>
 <para>

SCons/Tool/Tool.xml

@@ -523,11 +523,11 @@ general information on specifying emitters.
 <summary>
 <para>
 When this &consvar; is defined, a versioned loadable module
-is created by &b-link-LoadableModule; builder. This activates the
+is created by the &b-link-LoadableModule; builder. This activates the
 &cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as
 required, adds the version number to the library name, and creates the symlinks
-that are needed. &cv-link-LDMODULEVERSION; versions should exist in the same
-format as &cv-link-SHLIBVERSION;.
+that are needed. &cv-link-LDMODULEVERSION; versions should be
+specified in the same format as &cv-link-SHLIBVERSION;.
 </para>
 </summary>
 </cvar>
@@ -572,9 +572,12 @@ When this &consvar; is defined, a versioned shared library
 is created by the &b-link-SharedLibrary; builder. This activates the
 &cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as
 required, adds the version number to the library name, and creates the symlinks
-that are needed.  &cv-link-SHLIBVERSION; versions should exist as alphanumeric,
-decimal-delimited values as defined by the regular expression "\w+[\.\w+]*".
-Example &cv-link-SHLIBVERSION; values include '1', '1.2.3', and '1.2.gitaa412c8b'.
+that are needed.  &cv-link-SHLIBVERSION; versions are specified
+as alphanumeric, decimal-delimited values which can be
+recognized by the regular expression
+<literal>"\w+[\.\w+]*"</literal>
+Example valid &cv-SHLIBVERSION; values include
+'1', '1.2.3', and '1.2.gitaa412c8b'.
 </para>
 </summary>
 </cvar>

SCons/Tool/install.xml

@@ -69,7 +69,8 @@ in this case.
 </para>
 
 <para>
-If the <option>--install-sandbox</option> command line
+If the
+<link linkend="opt-install-sandbox"><option>--install-sandbox</option></link>
 option is given, the target directory will be prefixed
 by the directory path specified.
 This is useful to test installation behavior without installing to

SCons/Tool/lex.xml

@@ -123,7 +123,9 @@ command-line option. Use this in preference to including
 <cvar name="LEXUNISTD">
 <summary>
 <para>
-Used only in Windows environments to set a lex flag to prevent 'unistd.h' from being included. The default value is '--nounistd'.
+Used only in Windows environments to set a lex flag to prevent
+<literal>unistd.h</literal> from being included.
+The default value is <option>--nounistd</option>.
 </para>
 </summary>
 </cvar>

SCons/Tool/link.xml

@@ -83,8 +83,10 @@ if &cv-link-SHLIBVERSION; is set. Otherwise, it evaluates to an empty string.
 <cvar name="_LDMODULESONAME">
 <summary>
 <para>
-A macro that automatically generates loadable module's SONAME based on $TARGET,
-$LDMODULEVERSION and $LDMODULESUFFIX. Used by &b-link-LoadableModule; builder
+A macro that automatically generates a loadable module's &cv-link-SONAME;
+based on <literal>$TARGET</literal>,
+&cv-link-LDMODULEVERSION; and &cv-link-LDMODULESUFFIX;.
+Used by the &b-link-LoadableModule; builder
 when the linker tool supports SONAME (e.g. &t-link-gnulink;).
 </para>
 </summary>
@@ -94,11 +96,12 @@ when the linker tool supports SONAME (e.g. &t-link-gnulink;).
 <summary>
 <para>
 This macro automatically introduces extra flags to &cv-link-LDMODULECOM; when
-building versioned &b-link-LoadableModule; (that is when
-&cv-link-LDMODULEVERSION; is set). <literal>_LDMODULEVERSIONFLAGS</literal>
+building a versioned &b-link-LoadableModule;
+(that is, when &cv-link-LDMODULEVERSION; is set).
+&cv-_LDMODULEVERSIONFLAGS;
 usually adds &cv-link-SHLIBVERSIONFLAGS; and some extra dynamically generated
-options (such as <literal>-Wl,-soname=$_LDMODULESONAME</literal>).  It is unused
-by plain (unversioned) loadable modules.
+options (such as <literal>-Wl,-soname=$_LDMODULESONAME</literal>).
+It is unused by plain (unversioned) loadable modules.
 </para>
 </summary>
 </cvar>
@@ -107,20 +110,23 @@ by plain (unversioned) loadable modules.
 <summary>
 <para>
 This macro automatically introduces extra flags to &cv-link-SHLINKCOM; when
-building versioned &b-link-SharedLibrary; (that is when &cv-link-SHLIBVERSION;
-is set). <literal>_SHLIBVERSIONFLAGS</literal> usually adds &cv-link-SHLIBVERSIONFLAGS;
-and some extra dynamically generated options (such as
-<literal>-Wl,-soname=$_SHLIBSONAME</literal>. It is unused by "plain"
-(unversioned) shared libraries.
+building a versioned &b-link-SharedLibrary;
+(that is, when &cv-link-SHLIBVERSION; is set).
+&cv-_SHLIBVERSIONFLAGS; usually adds &cv-link-SHLIBVERSIONFLAGS;
+and some extra dynamically generated options
+(such as <literal>-Wl,-soname=$_SHLIBSONAME</literal>).
+It is unused by "plain" (unversioned) shared libraries.
 </para>
 </summary>
 </cvar>
 
 <cvar name="_SHLIBSONAME">
 <summary>
 <para>
-A macro that automatically generates shared library's SONAME based on $TARGET,
-$SHLIBVERSION and $SHLIBSUFFIX. Used by &b-link-SharedLibrary; builder when
+A macro that automatically generates a shared library's &cv-link-SONAME;
+based on <literal>$TARGET</literal>,
+&cv-link-SHLIBVERSION; and &cv-link-SHLIBSUFFIX;.
+Used by the &b-link-SharedLibrary; builder when
 the linker tool supports SONAME (e.g. &t-link-gnulink;).
 </para>
 </summary>
@@ -202,8 +208,9 @@ General user options passed to the linker for building loadable modules.
 <cvar name="LDMODULENOVERSIONSYMLINKS">
 <summary>
 <para>
-Instructs the &b-link-LoadableModule; builder to not automatically create symlinks
-for versioned modules. Defaults to <literal>$SHLIBNOVERSIONSYMLINKS</literal>
+Instructs the &b-link-LoadableModule; builder
+not to automatically create symlinks for versioned modules.
+Defaults to &cv-link-SHLIBNOVERSIONSYMLINKS;.
 </para>
 </summary>
 </cvar>
@@ -234,8 +241,8 @@ the same as $SHLIBSUFFIX.
 <summary>
 <para>
 Extra flags added to &cv-link-LDMODULECOM; when building versioned
-&b-link-LoadableModule;. These flags are only used when &cv-link-LDMODULEVERSION; is
-set.
+&b-link-LoadableModule;.
+These flags are only used when &cv-link-LDMODULEVERSION; is set.
 </para>
 </summary>
 </cvar>
@@ -399,29 +406,37 @@ See also &cv-link-LINKFLAGS;  for linking static objects.
 <cvar name="SONAME">
 <summary>
 <para>
-Variable used to hard-code SONAME for versioned shared library/loadable module.
+The name of a versioned shared library/loadable module.
+If specified, it is an explicit statement of the name;
+if unspecified, the value is generated.
+&cv-SONAME; and &cv-link-SOVERSION; may not both be specified
+in the same &consenv; or override.
 <example_commands>
+# Will cause libtest.so.2 to exist and be a symlink to libtest.so.0.1.2
 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
 </example_commands>
-The variable is used, for example, by &t-link-gnulink; linker tool.
+</para>
+<para>
+This variable is used by toolchains that support versioned shared objects.
 </para>
 </summary>
 </cvar>
 
 <cvar name="SOVERSION">
 <summary>
 <para>
-This will construct the <varname>SONAME</varname> using on the base library name
-(<parameter>test</parameter> in the example below) and use specified <varname>SOVERSION</varname>
-to create <varname>SONAME</varname>.
+Version string used in construction of &cv-link-SONAME;.
+The version is added to the base library name
+(<parameter>test</parameter> in the example below).
+&cv-SONAME; and &cv-SOVERSION; may not both be specified
+in the same &consenv; or override.
 <example_commands>
+# SONAME will be libtest.so.2, and will be a symlink to libtest.so.0.1.2
 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
 </example_commands>
-The variable is used, for example, by &t-link-gnulink; linker tool.
 </para>
 <para>
-In the example above <varname>SONAME</varname> would be <filename>libtest.so.2</filename>
-which would be a symlink and point to <filename>libtest.so.0.1.2</filename>
+This variable is used by toolchains that support versioned shared objects.
 </para>
 </summary>
 </cvar>

SCons/Tool/packaging/packaging.xml

@@ -28,8 +28,9 @@ This file is processed by the bin/SConsDoc.py module
 <summary>
 <para>
 Sets construction variables for the &b-link-Package; Builder.
-If this tool is enabled, the <option>--package-type</option>
-command-line option is also enabled.
+If this tool is enabled, the
+<link linkend="opt-package-type"><option>--package-type</option></link>
+command-line option is made available.
 </para>
 </summary>
 <sets>
@@ -56,7 +57,9 @@ env = Environment(tools=['default', 'packaging'])
 &SCons; can build packages in a number of well known packaging formats.
 The target package type may be selected with the
 &cv-link-PACKAGETYPE; construction variable
-or the <option>--package-type</option> command line option.
+or the
+<link linkend="opt-package-type"><option>--package-type</option></link>
+command line option.
 The package type may be a list, in which case &SCons; will attempt
 to build packages for each type in the list. Example:
 </para>