Merge pull request #3524 from mwichmann/doc-comstr-shcomstr

docs: refer *COM* and SH*COM* to each other  [ci skip]

10 files changed, 125 insertions, 66 deletions

diff --git a/src/engine/SCons/Tool/DCommon.xml b/src/engine/SCons/Tool/DCommon.xml
index 7cc47da..6d907c6 100644
--- a/src/engine/SCons/Tool/DCommon.xml
+++ b/src/engine/SCons/Tool/DCommon.xml
@@ -27,6 +27,7 @@ See its __doc__ string for a discussion of the format.
 <summary>
 <para>
 The D compiler to use.
+See also &cv-link-SHDC; for compiling to shared objects.
 </para>
 </summary>
 </cvar>
@@ -37,6 +38,18 @@ The D compiler to use.
 The command line used to compile a D file to an object file.
 Any options specified in the &cv-link-DFLAGS; construction variable
 is included on this command line.
+See also &cv-link-SHDCOM; for compiling to shared objects.
+</para>
+</summary>
+</cvar>
+
+<cvar name="DCOMSTR">
+<summary>
+<para>
+If set, the string displayed when a D source file
+is compiled to a (static) object file.
+If not set, then &cv-link-DCOM; (the command line) is displayed.
+See also &cv-link-SHDCOMSTR; for compiling to shared objects.
 </para>
 </summary>
 </cvar>
@@ -181,6 +194,7 @@ DLIBLINKSUFFIX.
 <summary>
 <para>
 Name of the linker to use for linking systems including D sources.
+See also &cv-link-SHDLINK; for linking shared objects.
 </para>
 </summary>
 </cvar>
@@ -189,6 +203,7 @@ Name of the linker to use for linking systems including D sources.
 <summary>
 <para>
 The command line to use when linking systems including D sources.
+See also &cv-link-SHDLINKCOM; for linking shared objects.
 </para>
 </summary>
 </cvar>
@@ -197,6 +212,7 @@ The command line to use when linking systems including D sources.
 <summary>
 <para>
 List of linker flags.
+See also &cv-link-SHDLINKFLAGS; for linking shared objects.
 </para>
 </summary>
 </cvar>
@@ -278,6 +294,7 @@ DVERSUFFIX.
 <para>
 The name of the compiler to use when compiling D source
 destined to be in a shared objects.
+See also &cv-link-DC; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -286,6 +303,18 @@ destined to be in a shared objects.
 <summary>
 <para>
 The command line to use when compiling code to be part of shared objects.
+See also &cv-link-DCOM; for compiling to static objects.
+</para>
+</summary>
+</cvar>
+
+<cvar name="SHDCOMSTR">
+<summary>
+<para>
+If set, the string displayed when a D source file
+is compiled to a (shared) object file.
+If not set, then &cv-link-SHDCOM; (the command line) is displayed.
+See also &cv-link-DCOMSTR; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -311,6 +340,7 @@ SHDLIBVERSIONFLAGS.
 <para>
 The linker to use when creating shared objects for code bases
 include D sources.
+See also &cv-link-DLINK; for linking static objects.
 </para>
 </summary>
 </cvar>
@@ -319,6 +349,7 @@ include D sources.
 <summary>
 <para>
 The command line to use when generating shared objects.
+See also &cv-link-DLINKCOM; for linking static objects.
 </para>
 </summary>
 </cvar>
@@ -327,6 +358,7 @@ The command line to use when generating shared objects.
 <summary>
 <para>
 The list of flags to use when generating a shared object.
+See also &cv-link-DLINKFLAGS; for linking static objects.
 </para>
 </summary>
 </cvar>
diff --git a/src/engine/SCons/Tool/c++.xml b/src/engine/SCons/Tool/c++.xml
index b59816b..019821c 100644
--- a/src/engine/SCons/Tool/c++.xml
+++ b/src/engine/SCons/Tool/c++.xml
@@ -47,6 +47,7 @@ Sets construction variables for generic POSIX C++ compilers.
 </sets>
 <uses>
 <item>CXXCOMSTR</item>
+<item>SHCXXCOMSTR</item>
 </uses>
 </tool>
 
@@ -54,6 +55,7 @@ Sets construction variables for generic POSIX C++ compilers.
 <summary>
 <para>
 The C++ compiler.
+See also &cv-link-SHCXX; for compiling to shared objects..
 </para>
 </summary>
 </cvar>
@@ -65,6 +67,7 @@ The command line used to compile a C++ source file to an object file.
 Any options specified in the &cv-link-CXXFLAGS; and
 &cv-link-CPPFLAGS; construction variables
 are included on this command line.
+See also &cv-link-SHCXXCOM; for compiling to shared objects..
 </para>
 </summary>
 </cvar>
@@ -72,9 +75,10 @@ are included on this command line.
 <cvar name="CXXCOMSTR">
 <summary>
 <para>
-The string displayed when a C++ source file
+If set, the string displayed when a C++ source file
 is compiled to a (static) object file.
-If this is not set, then &cv-link-CXXCOM; (the command line) is displayed.
+If not set, then &cv-link-CXXCOM; (the command line) is displayed.
+See also &cv-link-SHCXXCOMSTR; for compiling to shared objects..
 </para>
 
 <example_commands>
@@ -91,6 +95,7 @@ By default, this includes the value of &cv-link-CCFLAGS;,
 so that setting &cv-CCFLAGS; affects both C and C++ compilation.
 If you want to add C++-specific flags,
 you must set or override the value of &cv-link-CXXFLAGS;.
+See also &cv-link-SHCXXFLAGS; for compiling to shared objects..
 </para>
 </summary>
 </cvar>
@@ -99,6 +104,7 @@ you must set or override the value of &cv-link-CXXFLAGS;.
 <summary>
 <para>
 The C++ compiler used for generating shared-library objects.
+See also &cv-link-CXX; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -111,6 +117,7 @@ to a shared-library object file.
 Any options specified in the &cv-link-SHCXXFLAGS; and
 &cv-link-CPPFLAGS; construction variables
 are included on this command line.
+See also &cv-link-CXXCOM; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -118,9 +125,10 @@ are included on this command line.
 <cvar name="SHCXXCOMSTR">
 <summary>
 <para>
-The string displayed when a C++ source file
+If set, the string displayed when a C++ source file
 is compiled to a shared object file.
-If this is not set, then &cv-link-SHCXXCOM; (the command line) is displayed.
+If not set, then &cv-link-SHCXXCOM; (the command line) is displayed.
+See also &cv-link-CXXCOMSTR; for compiling to static objects.
 </para>
 
 <example_commands>
@@ -134,6 +142,7 @@ env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
 <para>
 Options that are passed to the C++ compiler
 to generate shared-library objects.
+See also &cv-link-CXXFLAGS; for compiling to static objects.
 </para>
 </summary>
 </cvar>
diff --git a/src/engine/SCons/Tool/cc.xml b/src/engine/SCons/Tool/cc.xml
index 06e73ff..e47cf2d 100644
--- a/src/engine/SCons/Tool/cc.xml
+++ b/src/engine/SCons/Tool/cc.xml
@@ -51,6 +51,8 @@ Sets construction variables for generic POSIX C compilers.
 </sets>
 <uses>
 <item>PLATFORM</item>
+<item>CCCOMSTR</item>
+<item>SHCCCOMSTR</item>
 </uses>
 </tool>
 
@@ -67,8 +69,8 @@ The C compiler.
 <para>
 The command line used to compile a C source file to a (static) object
 file.  Any options specified in the &cv-link-CFLAGS;, &cv-link-CCFLAGS; and
-&cv-link-CPPFLAGS; construction variables are included on this command
-line.
+&cv-link-CPPFLAGS; construction variables are included on this command line.
+See also &cv-link-SHCCCOM; for compiling to shared objects.
 </para>
 </summary>
 </cvar>
@@ -76,9 +78,10 @@ line.
 <cvar name="CCCOMSTR">
 <summary>
 <para>
-The string displayed when a C source file
+If set, the string displayed when a C source file
 is compiled to a (static) object file.
-If this is not set, then &cv-link-CCCOM; (the command line) is displayed.
+If not set, then &cv-link-CCCOM; (the command line) is displayed.
+See also &cv-link-SHCCCOMSTR; for compiling to shared objects.
 </para>
 
 <example_commands>
@@ -91,6 +94,7 @@ env = Environment(CCCOMSTR = "Compiling static object $TARGET")
 <summary>
 <para>
 General options that are passed to the C and C++ compilers.
+See also &cv-link-SHCCFLAGS; for compiling to shared objects.
 </para>
 </summary>
 </cvar>
@@ -99,6 +103,7 @@ General options that are passed to the C and C++ compilers.
 <summary>
 <para>
 General options that are passed to the C compiler (C only; not C++).
+See also &cv-link-SHCFLAGS; for compiling to shared objects.
 </para>
 </summary>
 </cvar>
@@ -156,6 +161,7 @@ The default list is:
 <summary>
 <para>
 The C compiler used for generating shared-library objects.
+See also &cv-link-CC; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -169,6 +175,7 @@ Any options specified in the &cv-link-SHCFLAGS;,
 &cv-link-SHCCFLAGS; and
 &cv-link-CPPFLAGS; construction variables
 are included on this command line.
+See also &cv-link-CCCOM; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -176,9 +183,10 @@ are included on this command line.
 <cvar name="SHCCCOMSTR">
 <summary>
 <para>
-The string displayed when a C source file
+If set, the string displayed when a C source file
 is compiled to a shared object file.
-If this is not set, then &cv-link-SHCCCOM; (the command line) is displayed.
+If not set, then &cv-link-SHCCCOM; (the command line) is displayed.
+See also &cv-link-CCCOMSTR; for compiling to static objects.
 </para>
 
 <example_commands>
@@ -192,6 +200,7 @@ env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
 <para>
 Options that are passed to the C and C++ compilers
 to generate shared-library objects.
+See also &cv-link-CCFLAGS; for compiling to static objects.
 </para>
 </summary>
 </cvar>
@@ -201,6 +210,7 @@ to generate shared-library objects.
 <para>
 Options that are passed to the C compiler (only; not C++)
 to generate shared-library objects.
+See also &cv-link-CFLAGS; for compiling to static objects.
 </para>
 </summary>
 </cvar>
diff --git a/src/engine/SCons/Tool/f03.xml b/src/engine/SCons/Tool/f03.xml
index c020b81..61c02ef 100644
--- a/src/engine/SCons/Tool/f03.xml
+++ b/src/engine/SCons/Tool/f03.xml
@@ -77,9 +77,9 @@ for all Fortran versions.
 <cvar name="F03COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 03 source file
+If set, the string displayed when a Fortran 03 source file
 is compiled to an object file.
-If this is not set, then &cv-link-F03COM; or &cv-link-FORTRANCOM;
+If not set, then &cv-link-F03COM; or &cv-link-FORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -217,10 +217,10 @@ for all Fortran versions.
 <cvar name="F03PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 03 source file
+If set, the string displayed when a Fortran 03 source file
 is compiled to an object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-F03PPCOM; or &cv-link-FORTRANPPCOM;
+If not set, then &cv-link-F03PPCOM; or &cv-link-FORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -256,9 +256,9 @@ for all Fortran versions.
 <cvar name="SHF03COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 03 source file
+If set, the string displayed when a Fortran 03 source file
 is compiled to a shared-library object file.
-If this is not set, then &cv-link-SHF03COM; or &cv-link-SHFORTRANCOM;
+If not set, then &cv-link-SHF03COM; or &cv-link-SHFORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -299,10 +299,10 @@ for all Fortran versions.
 <cvar name="SHF03PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 03 source file
+If set, the string displayed when a Fortran 03 source file
 is compiled to a shared-library object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-SHF03PPCOM; or &cv-link-SHFORTRANPPCOM;
+If not set, then &cv-link-SHF03PPCOM; or &cv-link-SHFORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
diff --git a/src/engine/SCons/Tool/f08.xml b/src/engine/SCons/Tool/f08.xml
index 802e4cc..a56d60b 100644
--- a/src/engine/SCons/Tool/f08.xml
+++ b/src/engine/SCons/Tool/f08.xml
@@ -77,9 +77,9 @@ for all Fortran versions.
 <cvar name="F08COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 08 source file
+If set, the string displayed when a Fortran 08 source file
 is compiled to an object file.
-If this is not set, then &cv-link-F08COM; or &cv-link-FORTRANCOM;
+If not set, then &cv-link-F08COM; or &cv-link-FORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -217,10 +217,10 @@ for all Fortran versions.
 <cvar name="F08PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 08 source file
+If set, the string displayed when a Fortran 08 source file
 is compiled to an object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-F08PPCOM; or &cv-link-FORTRANPPCOM;
+If not set, then &cv-link-F08PPCOM; or &cv-link-FORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -256,9 +256,9 @@ for all Fortran versions.
 <cvar name="SHF08COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 08 source file
+If set, the string displayed when a Fortran 08 source file
 is compiled to a shared-library object file.
-If this is not set, then &cv-link-SHF08COM; or &cv-link-SHFORTRANCOM;
+If not set, then &cv-link-SHF08COM; or &cv-link-SHFORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -299,10 +299,10 @@ for all Fortran versions.
 <cvar name="SHF08PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 08 source file
+If set, the string displayed when a Fortran 08 source file
 is compiled to a shared-library object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-SHF08PPCOM; or &cv-link-SHFORTRANPPCOM;
+If not set, then &cv-link-SHF08PPCOM; or &cv-link-SHFORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
diff --git a/src/engine/SCons/Tool/f77.xml b/src/engine/SCons/Tool/f77.xml
index abfc4a2..70ec721 100644
--- a/src/engine/SCons/Tool/f77.xml
+++ b/src/engine/SCons/Tool/f77.xml
@@ -108,9 +108,9 @@ F77 dialect will be used. By default, this is empty
 <cvar name="F77COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 77 source file
+If set, the string displayed when a Fortran 77 source file
 is compiled to an object file.
-If this is not set, then &cv-link-F77COM; or &cv-link-FORTRANCOM;
+If not set, then &cv-link-F77COM; or &cv-link-FORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -230,10 +230,10 @@ for all Fortran versions.
 <cvar name="F77PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 77 source file
+If set, the string displayed when a Fortran 77 source file
 is compiled to an object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-F77PPCOM; or &cv-link-FORTRANPPCOM;
+If not set, then &cv-link-F77PPCOM; or &cv-link-FORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -269,9 +269,9 @@ for all Fortran versions.
 <cvar name="SHF77COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 77 source file
+If set, the string displayed when a Fortran 77 source file
 is compiled to a shared-library object file.
-If this is not set, then &cv-link-SHF77COM; or &cv-link-SHFORTRANCOM;
+If not set, then &cv-link-SHF77COM; or &cv-link-SHFORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -312,10 +312,10 @@ for all Fortran versions.
 <cvar name="SHF77PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 77 source file
+If set, the string displayed when a Fortran 77 source file
 is compiled to a shared-library object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-SHF77PPCOM; or &cv-link-SHFORTRANPPCOM;
+If not set, then &cv-link-SHF77PPCOM; or &cv-link-SHFORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
diff --git a/src/engine/SCons/Tool/f90.xml b/src/engine/SCons/Tool/f90.xml
index 94249a3..64dc6e1 100644
--- a/src/engine/SCons/Tool/f90.xml
+++ b/src/engine/SCons/Tool/f90.xml
@@ -77,9 +77,9 @@ for all Fortran versions.
 <cvar name="F90COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 90 source file
+If set, the string displayed when a Fortran 90 source file
 is compiled to an object file.
-If this is not set, then &cv-link-F90COM; or &cv-link-FORTRANCOM;
+If not set, then &cv-link-F90COM; or &cv-link-FORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -217,9 +217,9 @@ for all Fortran versions.
 <cvar name="F90PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 90 source file
+If set, the string displayed when a Fortran 90 source file
 is compiled after first running the file through the C preprocessor.
-If this is not set, then &cv-link-F90PPCOM; or &cv-link-FORTRANPPCOM;
+If not set, then &cv-link-F90PPCOM; or &cv-link-FORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -255,9 +255,9 @@ for all Fortran versions.
 <cvar name="SHF90COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 90 source file
+If set, the string displayed when a Fortran 90 source file
 is compiled to a shared-library object file.
-If this is not set, then &cv-link-SHF90COM; or &cv-link-SHFORTRANCOM;
+If not set, then &cv-link-SHF90COM; or &cv-link-SHFORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -298,10 +298,10 @@ for all Fortran versions.
 <cvar name="SHF90PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 90 source file
+If set, the string displayed when a Fortran 90 source file
 is compiled to a shared-library object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-SHF90PPCOM; or &cv-link-SHFORTRANPPCOM;
+If not set, then &cv-link-SHF90PPCOM; or &cv-link-SHFORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
diff --git a/src/engine/SCons/Tool/f95.xml b/src/engine/SCons/Tool/f95.xml
index 4a4db46..4bda653 100644
--- a/src/engine/SCons/Tool/f95.xml
+++ b/src/engine/SCons/Tool/f95.xml
@@ -77,9 +77,9 @@ for all Fortran versions.
 <cvar name="F95COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 95 source file
+If set, the string displayed when a Fortran 95 source file
 is compiled to an object file.
-If this is not set, then &cv-link-F95COM; or &cv-link-FORTRANCOM;
+If not set, then &cv-link-F95COM; or &cv-link-FORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -217,10 +217,10 @@ for all Fortran versions.
 <cvar name="F95PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 95 source file
+If set, the string displayed when a Fortran 95 source file
 is compiled to an object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-F95PPCOM; or &cv-link-FORTRANPPCOM;
+If not set, then &cv-link-F95PPCOM; or &cv-link-FORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -256,9 +256,9 @@ for all Fortran versions.
 <cvar name="SHF95COMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 95 source file
+If set, the string displayed when a Fortran 95 source file
 is compiled to a shared-library object file.
-If this is not set, then &cv-link-SHF95COM; or &cv-link-SHFORTRANCOM;
+If not set, then &cv-link-SHF95COM; or &cv-link-SHFORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -299,10 +299,10 @@ for all Fortran versions.
 <cvar name="SHF95PPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran 95 source file
+If set, the string displayed when a Fortran 95 source file
 is compiled to a shared-library object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-SHF95PPCOM; or &cv-link-SHFORTRANPPCOM;
+If not set, then &cv-link-SHF95PPCOM; or &cv-link-SHFORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
diff --git a/src/engine/SCons/Tool/fortran.xml b/src/engine/SCons/Tool/fortran.xml
index 53bcfb1..7b3c51f 100644
--- a/src/engine/SCons/Tool/fortran.xml
+++ b/src/engine/SCons/Tool/fortran.xml
@@ -73,9 +73,9 @@ are included on this command line.
 <cvar name="FORTRANCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran source file
+If set, the string displayed when a Fortran source file
 is compiled to an object file.
-If this is not set, then &cv-link-FORTRANCOM;
+If not set, then &cv-link-FORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -285,10 +285,10 @@ construction variables are included on this command line.
 <cvar name="FORTRANPPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran source file
+If set, the string displayed when a Fortran source file
 is compiled to an object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-FORTRANPPCOM;
+If not set, then &cv-link-FORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -330,9 +330,9 @@ to a shared-library object file.
 <cvar name="SHFORTRANCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran source file
+If set, the string displayed when a Fortran source file
 is compiled to a shared-library object file.
-If this is not set, then &cv-link-SHFORTRANCOM;
+If not set, then &cv-link-SHFORTRANCOM;
 (the command line) is displayed.
 </para>
 </summary>
@@ -364,10 +364,10 @@ are included on this command line.
 <cvar name="SHFORTRANPPCOMSTR">
 <summary>
 <para>
-The string displayed when a Fortran source file
+If set, the string displayed when a Fortran source file
 is compiled to a shared-library object file
 after first running the file through the C preprocessor.
-If this is not set, then &cv-link-SHFORTRANPPCOM;
+If not set, then &cv-link-SHFORTRANPPCOM;
 (the command line) is displayed.
 </para>
 </summary>
diff --git a/src/engine/SCons/Tool/link.xml b/src/engine/SCons/Tool/link.xml
index 654dafc..281e147 100644
--- a/src/engine/SCons/Tool/link.xml
+++ b/src/engine/SCons/Tool/link.xml
@@ -32,9 +32,6 @@ based on the types of source files.
 </para>
 </summary>
 <sets>
-<item>SHLINK</item>
-<item>SHLINKFLAGS</item>
-<item>SHLINKCOM</item>
 <item>LINK</item>
 <item>LINKFLAGS</item>
 <item>LINKCOM</item>
@@ -42,6 +39,9 @@ based on the types of source files.
 <item>LIBDIRSUFFIX</item>
 <item>LIBLINKPREFIX</item>
 <item>LIBLINKSUFFIX</item>
+<item>SHLINK</item>
+<item>SHLINKFLAGS</item>
+<item>SHLINKCOM</item>
 <item>SHLIBSUFFIX</item>
 <item>__SHLIBVERSIONFLAGS</item>
 <item>LDMODULE</item>
@@ -55,8 +55,8 @@ based on the types of source files.
 <item>__LDMODULEVERSIONFLAGS</item>
 </sets>
 <uses>
-<item>SHLINKCOMSTR</item>
 <item>LINKCOMSTR</item>
+<item>SHLINKCOMSTR</item>
 <item>LDMODULECOMSTR</item>
 </uses>
 </tool>
@@ -184,8 +184,8 @@ On other systems, this is the same as &cv-link-SHLINK;.
 <cvar name="LDMODULECOMSTR">
 <summary>
 <para>
-The string displayed when building loadable modules.
-If this is not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
+If set, the string displayed when building loadable modules.
+If not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
 </para>
 </summary>
 </cvar>
@@ -243,6 +243,7 @@ set.
 <summary>
 <para>
 The linker.
+See also &cv-link-SHLINK; for linking shared objects.
 </para>
 </summary>
 </cvar>
@@ -251,6 +252,7 @@ The linker.
 <summary>
 <para>
 The command line used to link object files into an executable.
+See also &cv-link-SHLINKCOM; for linking shared objects.
 </para>
 </summary>
 </cvar>
@@ -258,9 +260,10 @@ The command line used to link object files into an executable.
 <cvar name="LINKCOMSTR">
 <summary>
 <para>
-The string displayed when object files
+If set, the string displayed when object files
 are linked into an executable.
-If this is not set, then &cv-link-LINKCOM; (the command line) is displayed.
+If not set, then &cv-link-LINKCOM; (the command line) is displayed.
+See also &cv-link-SHLINKCOMSTR;.  for linking shared objects.
 </para>
 
 <example_commands>
@@ -290,6 +293,7 @@ and
 &cv-link-_LIBDIRFLAGS;
 above,
 for the variable that expands to library search path options.
+See also &cv-link-SHLINKFLAGS;.  for linking shared objects.
 </para>
 </summary>
 </cvar>
@@ -317,6 +321,7 @@ set.
 <summary>
 <para>
 The linker for programs that use shared libraries.
+See also &cv-link-LINK; for linking static objects.
 </para>
 </summary>
 </cvar>
@@ -325,6 +330,7 @@ The linker for programs that use shared libraries.
 <summary>
 <para>
 The command line used to link programs using shared libraries.
+See also &cv-link-LINKCOM; for linking static objects.
 </para>
 </summary>
 </cvar>
@@ -334,6 +340,7 @@ The command line used to link programs using shared libraries.
 <para>
 The string displayed when programs using shared libraries are linked.
 If this is not set, then &cv-link-SHLINKCOM; (the command line) is displayed.
+See also &cv-link-LINKCOMSTR;  for linking static objects.
 </para>
 
 <example_commands>
@@ -363,6 +370,7 @@ and
 &cv-link-_LIBDIRFLAGS;
 above,
 for the variable that expands to library search path options.
+See also &cv-link-LINKFLAGS;  for linking static objects.
 </para>
 </summary>
 </cvar>