Merge topic 'doc-fixups'

fa04673 Documentation: Clarify configure_file behavior
07d5e4b Documentation: Clarify some command descriptions
965de97 Documentation: Correct typos and grammar

Source/cmConfigureFileCommand.h

@@ -68,6 +68,9 @@ public:
         "If <output> names an existing directory the input file is placed "
         "in that directory with its original name.  "
         "\n"
+        "If the <input> file is modified the build system will re-run CMake "
+        "to re-configure the file and generate the build system again."
+        "\n"
         "This command replaces any variables in the input file referenced as "
         "${VAR} or @VAR@ with their values as determined by CMake.  If a "
         "variable is not defined, it will be replaced with nothing.  "
@@ -76,13 +79,18 @@ public:
         "will be C-style escaped.  "
         "The file will be configured with the current values of CMake "
         "variables. If @ONLY is specified, only variables "
-        "of the form @VAR@ will be replaces and ${VAR} will be ignored.  "
+        "of the form @VAR@ will be replaced and ${VAR} will be ignored.  "
-        "This is useful for configuring scripts that use ${VAR}. "
+        "This is useful for configuring scripts that use ${VAR}."
-        "Any occurrences of #cmakedefine VAR will be replaced with "
+        "\n"
-        "either #define VAR or /* #undef VAR */ depending on "
+        "Input file lines of the form \"#cmakedefine VAR ...\" "
-        "the setting of VAR in CMake. Any occurrences of #cmakedefine01 VAR "
+        "will be replaced with either \"#define VAR ...\" or "
-        "will be replaced with either #define VAR 1 or #define VAR 0 "
+        "\"/* #undef VAR */\" depending on whether VAR is set in CMake to "
-        "depending on whether VAR evaluates to TRUE or FALSE in CMake.\n"
+        "any value not considered a false constant by the if() command. "
+        "(Content of \"...\", if any, is processed as above.) "
+        "Input file lines of the form \"#cmakedefine01 VAR\" "
+        "will be replaced with either \"#define VAR 1\" or "
+        "\"#define VAR 0\" similarly."
+        "\n"
         "With NEWLINE_STYLE the line ending could be adjusted: \n"
         "    'UNIX' or 'LF' for \\n, 'DOS', 'WIN32' or 'CRLF' for \\r\\n.\n"
         "COPYONLY must not be used with NEWLINE_STYLE.\n";

Source/cmFileCommand.h

@@ -89,7 +89,8 @@ public:
       "       [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])\n"
       "WRITE will write a message into a file called 'filename'. It "
       "overwrites the file if it already exists, and creates the file "
-      "if it does not exist.\n"
+      "if it does not exist. (If the file is a build input, use "
+      "configure_file to update the file only when its content changes.)\n"
       "APPEND will write a message into a file same as WRITE, except "
       "it will append it to the end of the file\n"
       "READ will read the content of a file and store it into the "

Source/cmFunctionCommand.h

@@ -90,7 +90,9 @@ public:
       "will have the actual values of the arguments passed in. This "
       "facilitates creating functions with optional arguments. Additionally "
       "ARGV holds the list of all arguments given to the function and ARGN "
-      "holds the list of argument past the last expected argument."
+      "holds the list of arguments past the last expected argument."
+      "\n"
+      "A function opens a new scope: see set(var PARENT_SCOPE) for details."
       "\n"
       "See the cmake_policy() command documentation for the behavior of "
       "policies inside functions."

Source/cmIncludeDirectoryCommand.h

@@ -72,9 +72,12 @@ public:
       "CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. "
       "By using AFTER or BEFORE explicitly, you can select between "
       "appending and prepending, independent of the default. "
+      "\n"
       "If the SYSTEM option is given, the compiler will be told the "
       "directories are meant as system include directories on some "
-      "platforms.";
+      "platforms (signalling this setting might achieve effects such as "
+      "the compiler skipping warnings, or these fixed-install system files "
+      "not being considered in dependency calculations - see compiler docs).";
     }
 
   cmTypeMacro(cmIncludeDirectoryCommand, cmCommand);

Source/cmMacroCommand.h

@@ -92,12 +92,12 @@ public:
       "facilitates creating macros with optional arguments. Additionally "
       "${ARGV} holds the list of all arguments given to the macro and "
       "${ARGN} "
-      "holds the list of argument past the last expected argument. "
+      "holds the list of arguments past the last expected argument. "
       "Note that the parameters to a macro and values such as ARGN "
       "are not variables in the usual CMake sense. They are string "
-      "replacements much like the c preprocessor would do with a "
+      "replacements much like the C preprocessor would do with a macro. "
-      "macro. If you want true CMake variables you should look at "
+      "If you want true CMake variables and/or better CMake scope control "
-      "the function command."
+      "you should look at the function command."
       "\n"
       "See the cmake_policy() command documentation for the behavior of "
       "policies inside macros."

Source/cmMathCommand.h

@@ -58,11 +58,11 @@ public:
     {
     return
       "  math(EXPR <output variable> <math expression>)\n"
-      "EXPR evaluates mathematical expression and return result in the "
+      "EXPR evaluates mathematical expression and returns result in the "
       "output variable. Example mathematical expression is "
       "'5 * ( 10 + 13 )'.  Supported operators are "
       "+ - * / % | & ^ ~ << >> * / %.  They have the same meaning "
-      " as they do in c code.";
+      " as they do in C code.";
     }
 
   cmTypeMacro(cmMathCommand, cmCommand);

Source/cmMessageCommand.h

@@ -67,8 +67,9 @@ public:
       "  STATUS         = Incidental information\n"
       "  WARNING        = CMake Warning, continue processing\n"
       "  AUTHOR_WARNING = CMake Warning (dev), continue processing\n"
-      "  SEND_ERROR     = CMake Error, continue but skip generation\n"
+      "  SEND_ERROR     = CMake Error, continue processing,\n"
-      "  FATAL_ERROR    = CMake Error, stop all processing\n"
+      "                                but skip generation\n"
+      "  FATAL_ERROR    = CMake Error, stop processing and generation\n"
       "The CMake command-line tool displays STATUS messages on stdout "
       "and all other message types on stderr.  "
       "The CMake GUI displays all messages in its log area.  "

Source/cmPolicies.cxx

@@ -457,7 +457,7 @@ cmPolicies::cmPolicies()
     "This makes sure that the modules belonging to "
     "CMake always get those files included which they expect, and against "
     "which they were developed and tested.  "
-    "In call other cases, the files found in "
+    "In all other cases, the files found in "
     "CMAKE_MODULE_PATH still take precedence over the ones in "
     "the CMake module directory.  "
     "The OLD behaviour is to always prefer files from CMAKE_MODULE_PATH over "

Source/cmSourceFile.cxx

@@ -458,7 +458,7 @@ void cmSourceFile::DefineProperties(cmake *cm)
      "A property on a source file that indicates if the source file "
      "is a header file with no associated implementation. This is "
      "set automatically based on the file extension and is used by "
-     "CMake to determine is certain dependency information should be "
+     "CMake to determine if certain dependency information should be "
      "computed.");
 
   cm->DefineProperty

Source/cmSourceGroupCommand.h

@@ -68,7 +68,7 @@ public:
       "expression matches the file will be favored.\n"
       "The name of the group may contain backslashes to specify subgroups:\n"
       "  source_group(outer\\\\inner ...)\n"
-      "For backwards compatibility, this command is also supports the "
+      "For backwards compatibility, this command also supports the "
       "format:\n"
       "  source_group(name regex)";
     }

Source/cmTargetLinkLibrariesCommand.h

@@ -100,11 +100,11 @@ public:
       "to the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent "
       "target properties instead of using them for linking.  "
       "Libraries specified as \"debug\" are appended to the "
-      "the LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties "
+      "LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties "
       "corresponding to configurations listed in the DEBUG_CONFIGURATIONS "
       "global property if it is set).  "
       "Libraries specified as \"optimized\" are appended to the "
-      "the LINK_INTERFACE_LIBRARIES property.  "
+      "LINK_INTERFACE_LIBRARIES property.  "
       "Libraries specified as \"general\" (or without any keyword) are "
       "treated as if specified for both \"debug\" and \"optimized\"."
       "\n"

Source/cmTryRunCommand.h

@@ -81,7 +81,7 @@ public:
       "the executable, but it will not try to run the executable. Instead it "
       "will create cache variables which must be filled by the user or by "
       "presetting them in some CMake script file to the values the "
-      "executable would have produced if it would have been run on its actual "
+      "executable would have produced if it had been run on its actual "
       "target platform. These variables are RUN_RESULT_VAR (explanation see "
       "above) and if RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) was used, an "
       "additional cache variable "