Merge pull request #3425 from mwichmann/tool-docs

manpage: clarify that tools=[list] overrides [ci skip]

4 files changed, 89 insertions, 6 deletions

diff --git a/src/engine/SCons/Tool/cc.xml b/src/engine/SCons/Tool/cc.xml
index 9330436..7ce8b36 100644
--- a/src/engine/SCons/Tool/cc.xml
+++ b/src/engine/SCons/Tool/cc.xml
@@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format.
 <tool name="cc">
 <summary>
 <para>
-Sets construction variables for generic POSIX C copmilers.
+Sets construction variables for generic POSIX C compilers.
 </para>
 </summary>
 <sets>
diff --git a/src/engine/SCons/Tool/default.xml b/src/engine/SCons/Tool/default.xml
index 38eb122..4b862fb 100644
--- a/src/engine/SCons/Tool/default.xml
+++ b/src/engine/SCons/Tool/default.xml
@@ -26,10 +26,91 @@ See its __doc__ string for a discussion of the format.
 <tool name="default">
 <summary>
 <para>
-Sets variables by calling a default list of Tool modules
-for the platform on which SCons is running.
+Sets &consvars; for a default list of Tool modules.
+Use <emphasis role="bold">default</emphasis>
+in the tools list to retain the original defaults,
+since the <parameter>tools</parameter> parameter
+is treated as a literal statement of the tools
+to be made available in that &consenv;, not an addition.
 </para>
+
+<para>
+The list of tools selected by default is not static,
+but is dependent both on
+the platform and on the software installed on the platform.
+Some tools will not initialize if an underlying command is
+not found, and some tools are selected from a list of choices
+on a first-found basis. The finished tool list can be
+examined by inspecting the <envar>TOOLS</envar> &consvar;
+in the &consenv;.
+</para>
+
+<para>
+On all platforms, all tools from the following list
+are selected whose respective conditions are met:
+filesystem, wix, lex, yacc, rpcgen, swig,
+jar, javac, javah, rmic, dvipdf, dvips, gs,
+tex, latex, pdflatex, pdftex, tar, zip, textfile.
+</para>
+
+<para>
+On Linux systems, the default tools list selects
+(first-found): a C compiler from
+gcc, intelc, icc, cc;
+a C++ compiler from
+g++, intelc, icc, cxx;
+an assembler from
+gas, nasm, masm;
+a linker from
+gnulink, ilink;
+a Fortran compiler from
+gfortran, g77, ifort, ifl, f95, f90, f77;
+and a static archiver 'ar'.
+It also selects all found from the list
+m4, rpm.
+</para>
+
+<para>
+On Windows systems, the default tools list selects
+(first-found): a C compiler from
+msvc, mingw, gcc, intelc, icl, icc, cc, bcc32;
+a C++ compiler from
+msvc, intelc, icc, g++, cxx, bcc32;
+an assembler from
+masm, nasm, gas, 386asm;
+a linker from
+mslink, gnulink, ilink, linkloc, ilink32;
+a Fortran compiler from
+gfortran, g77, ifl, cvf, f95, f90, fortran;
+and a static archiver from
+mslib, ar, tlib;
+It also selects all found from the list
+msvs, midl.
+</para>
+
+<para>
+On MacOS systems, the default tools list selects
+(first-found): a C compiler from
+gcc, cc;
+a C++ compiler from
+g++, cxx;
+an assembler 'as';
+a linker from
+applelink, gnulink;
+a Fortran compiler from
+gfortran, f95, f90, g77;
+and a static archiver ar.
+It also selects all found from the list
+m4, rpm.
+</para>
+
+<para>
+Default lists for other platforms can be found by
+examining the &scons;
+source code (see
+<filename>SCons/Tool/__init__.py</filename>).
+</para>
+
 </summary>
 </tool>
-
 </sconsdoc>
diff --git a/src/engine/SCons/Tool/link.xml b/src/engine/SCons/Tool/link.xml
index 2f913fe..75b2ed8 100644
--- a/src/engine/SCons/Tool/link.xml
+++ b/src/engine/SCons/Tool/link.xml
@@ -26,7 +26,9 @@ See its __doc__ string for a discussion of the format.
 <tool name="link">
 <summary>
 <para>
-Sets construction variables for generic POSIX linkers.
+Sets construction variables for generic POSIX linkers. This is
+a "smart" linker tool which selects a compiler to complete the linking
+based on the types of source files.
 </para>
 </summary>
 <sets>
diff --git a/src/engine/SCons/Tool/midl.xml b/src/engine/SCons/Tool/midl.xml
index efd83cc..63cf527 100644
--- a/src/engine/SCons/Tool/midl.xml
+++ b/src/engine/SCons/Tool/midl.xml
@@ -86,7 +86,7 @@ The command line used to pass files to the Microsoft IDL compiler.
 <summary>
 <para>
 The string displayed when
-the Microsoft IDL copmiler is called.
+the Microsoft IDL compiler is called.
 If this is not set, then &cv-link-MIDLCOM; (the command line) is displayed.
 </para>
 </summary>