Do not claim Win32 module-def file is created [skip travis] [skip appveyor]

Change doc wording to indicate WINDOWS_INSERT_DEF adds a linker
cmdline reference to the module-definition file, it does not *create*
that file.  Also polished up some other mslink wording.

Fixes #3968

Signed-off-by: Mats Wichmann <mats@linux.com>

1 files changed, 52 insertions, 25 deletions

diff --git a/SCons/Tool/mslink.xml b/SCons/Tool/mslink.xml
index 8683e0519..52aa0f24a 100644
--- a/SCons/Tool/mslink.xml
+++ b/SCons/Tool/mslink.xml
@@ -72,11 +72,11 @@ Sets construction variables for the Microsoft linker.
 <para>
 When set to non-zero,
 suppresses creation of a corresponding Windows static import lib by the
-<literal>SharedLibrary</literal>
+&b-link-SharedLibrary;
 builder when used with
 MinGW, Microsoft Visual Studio or Metrowerks.
 This also suppresses creation
-of an export (.exp) file
+of an export (<filename>.exp</filename>) file
 when using Microsoft Visual Studio.
 </para>
 </summary>
@@ -120,11 +120,13 @@ see the entry for that variable for specific examples.
 <cvar name="WINDOWS_EMBED_MANIFEST">
 <summary>
 <para>
-Set this variable to True or 1 to embed the compiler-generated manifest
+Set to <constant>True</constant> to embed the
+compiler-generated manifest
 (normally <literal>${TARGET}.manifest</literal>)
-into all Windows exes and DLLs built with this environment,
+into all Windows executables and DLLs built with this environment,
 as a resource during their link step.
 This is done using &cv-link-MT; and &cv-link-MTEXECOM; and &cv-link-MTSHLIBCOM;.
+See also &cv-link-WINDOWS_INSERT_MANIFEST;.
 </para>
 </summary>
 </cvar>
@@ -169,8 +171,8 @@ See also &cv-link-MTEXECOM;.
 <para>
 The program used on Windows systems
 to register a newly-built DLL library
-whenever the &b-SharedLibrary; builder
-is passed a keyword argument of <literal>register=1</literal>.
+whenever the &b-link-SharedLibrary; builder
+is passed a keyword argument of <literal>register=True</literal>.
 </para>
 </summary>
 </cvar>
@@ -180,8 +182,8 @@ is passed a keyword argument of <literal>register=1</literal>.
 <para>
 The command line used on Windows systems
 to register a newly-built DLL library
-whenever the &b-SharedLibrary; builder
-is passed a keyword argument of <literal>register=1</literal>.
+whenever the &b-link-SharedLibrary; builder
+is passed a keyword argument of <literal>register=True</literal>.
 </para>
 </summary>
 </cvar>
@@ -211,14 +213,21 @@ and requiring user attention.
 <cvar name="WINDOWS_INSERT_DEF">
 <summary>
 <para>
-When this is set to true,
+If set to true,
 a library build of a Windows shared library
 (<filename>.dll</filename> file)
-will also build a corresponding <filename>.def</filename> file
-at the same time,
-if a <filename>.def</filename> file
+will include a reference to the corresponding
+module-definition file at the same time,
+if a module-definition file
 is not already listed as a build target.
-The default is 0 (do not build a <filename>.def</filename> file).
+The name of the module-definition file will
+be constructed from the base name of the library
+and the &consvars;
+&cv-link-WINDOWSDEFSUFFIX; and
+&cv-link-WINDOWSDEFPREFIX;.
+The default is to not add a module-definition file.
+The module-definition file is not created by this directive,
+and must be supplied by the developer.
 </para>
 </summary>
 </cvar>
@@ -226,11 +235,21 @@ The default is 0 (do not build a <filename>.def</filename> file).
 <cvar name="WINDOWS_INSERT_MANIFEST">
 <summary>
 <para>
-When this is set to true,
+If set to true,
 &scons;
-will be aware of the
-<filename>.manifest</filename>
-files generated by Microsoft Visua C/C++ 8.
+will add the manifest file
+generated by Microsoft Visual C++ 8.0 and later
+to the target list so &SCons; will be aware they
+were generated.
+In the case of an executable, the manifest file name
+is constructed using
+&cv-link-WINDOWSPROGMANIFESTSUFFIX; and
+&cv-link-WINDOWSPROGMANIFESTPREFIX;.
+In the case of a shared library, the manifest file name
+is constructed using
+&cv-link-WINDOWSSHLIBMANIFESTSUFFIX; and
+&cv-link-WINDOWSSHLIBMANIFESTPREFIX;.
+See also &cv-link-WINDOWS_EMBED_MANIFEST;.
 </para>
 </summary>
 </cvar>
@@ -238,7 +257,8 @@ files generated by Microsoft Visua C/C++ 8.
 <cvar name="WINDOWSDEFPREFIX">
 <summary>
 <para>
-The prefix used for Windows <filename>.def</filename> file names.
+The prefix used for a Windows linker module-definition file name.
+Defaults to empty.
 </para>
 </summary>
 </cvar>
@@ -246,7 +266,8 @@ The prefix used for Windows <filename>.def</filename> file names.
 <cvar name="WINDOWSDEFSUFFIX">
 <summary>
 <para>
-The suffix used for Windows <filename>.def</filename> file names.
+The suffix used for a Windows linker module-definition file name.
+Defaults to <filename>.def</filename>.
 </para>
 </summary>
 </cvar>
@@ -254,7 +275,8 @@ The suffix used for Windows <filename>.def</filename> file names.
 <cvar name="WINDOWSEXPPREFIX">
 <summary>
 <para>
-The prefix used for Windows <filename>.exp</filename> file names.
+The prefix used for Windows linker exports file names.
+Defaults to empty.
 </para>
 </summary>
 </cvar>
@@ -262,7 +284,8 @@ The prefix used for Windows <filename>.exp</filename> file names.
 <cvar name="WINDOWSEXPSUFFIX">
 <summary>
 <para>
-The suffix used for Windows <filename>.exp</filename> file names.
+The suffix used for Windows linker exports file names.
+Defaults to <filename>.exp</filename>.
 </para>
 </summary>
 </cvar>
@@ -270,8 +293,9 @@ The suffix used for Windows <filename>.exp</filename> file names.
 <cvar name="WINDOWSPROGMANIFESTPREFIX">
 <summary>
 <para>
-The prefix used for executable program <filename>.manifest</filename> files
+The prefix used for executable program manifest files
 generated by Microsoft Visual C/C++.
+Defaults to empty.
 </para>
 </summary>
 </cvar>
@@ -279,8 +303,9 @@ generated by Microsoft Visual C/C++.
 <cvar name="WINDOWSPROGMANIFESTSUFFIX">
 <summary>
 <para>
-The suffix used for executable program <filename>.manifest</filename> files
+The suffix used for executable program manifest files
 generated by Microsoft Visual C/C++.
+Defaults to <filename>.manifest</filename>.
 </para>
 </summary>
 </cvar>
@@ -288,8 +313,9 @@ generated by Microsoft Visual C/C++.
 <cvar name="WINDOWSSHLIBMANIFESTPREFIX">
 <summary>
 <para>
-The prefix used for shared library <filename>.manifest</filename> files
+The prefix used for shared library manifest files
 generated by Microsoft Visual C/C++.
+Defaults to empty.
 </para>
 </summary>
 </cvar>
@@ -297,8 +323,9 @@ generated by Microsoft Visual C/C++.
 <cvar name="WINDOWSSHLIBMANIFESTSUFFIX">
 <summary>
 <para>
-The suffix used for shared library <filename>.manifest</filename> files
+The suffix used for shared library manifest files
 generated by Microsoft Visual C/C++.
+Defaults to <filename>.manifest</filename>.
 </para>
 </summary>
 </cvar>