Documentation: Clarify a few subtleties

* Clarify accepted values of <LANG> suffix in CMAKE_COMPILER_IS_GNU<LANG>.

* Clarify fact that target property GENERATOR_FILE_NAME usually cannot be
  used at configure time.

* Clarify that enable_language() can only be used in global scope of
  top-level project using language.

* State that enable_language(... OPTIONAL) currently doesn't work.

* Document regular expression operator precedence.

Source/cmDocumentVariables.cxx

@@ -1551,7 +1551,14 @@ void cmDocumentVariables::DefineVariables(cmake* cm)
     ("CMAKE_COMPILER_IS_GNU<LANG>", cmProperty::VARIABLE,
      "True if the compiler is GNU.",
      "If the selected <LANG> compiler is the GNU "
-     "compiler then this is TRUE, if not it is FALSE.",false,
+     "compiler then this is TRUE, if not it is FALSE. "
+     "Unlike the other per-language variables, this uses the GNU syntax for "
+     "identifying languages instead of the CMake syntax. Recognized values of "
+     "the <LANG> suffix are:\n"
+     "  CC = C compiler\n"
+     "  CXX = C++ compiler\n"
+     "  G77 = Fortran compiler",
+     false,
      "Variables for Languages");
 
   cm->DefineProperty

Source/cmEnableLanguageCommand.h

@@ -65,7 +65,12 @@ public:
       "any of the extra variables that are created by the project command. "
       "Example languages are CXX, C, Fortran. "
       "If OPTIONAL is used, use the CMAKE_<languageName>_COMPILER_WORKS "
-      "variable to check whether the language has been enabled successfully.";
+      "variable to check whether the language has been enabled successfully."
+      "\n"
+      "This command must be called on file scope (not inside a function) and "
+      "the language enabled can only be used in the calling project or its "
+      "subdirectories added by add_subdirectory(). Also note that at present, "
+      "the OPTIONAL argument does not work.";
     }
 
   cmTypeMacro(cmEnableLanguageCommand, cmCommand);

Source/cmStringCommand.h

@@ -136,6 +136,9 @@ public:
       "   [^ ]      Matches any character(s) not inside the brackets\n"
       "    -        Inside brackets, specifies an inclusive range between\n"
       "             characters on either side e.g. [a-f] is [abcdef]\n"
+      "             To match a literal - using brackets, make it the first\n"
+      "             or the last character e.g. [+*/-] matches basic\n"
+      "             mathematical operators.\n"
       "   *         Matches preceding pattern zero or more times\n"
       "   +         Matches preceding pattern one or more times\n"
       "   ?         Matches preceding pattern zero or once only\n"
@@ -144,6 +147,10 @@ public:
       "             in the REGEX REPLACE operation. Additionally it is saved\n"
       "             by all regular expression-related commands, including \n"
       "             e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).\n"
+      "*, + and ? have higher precedence than concatenation. | has lower "
+      "precedence than concatenation. This means that the regular expression "
+      "\"^ab+d$\" matches \"abbd\" but not \"ababd\", and the regular "
+      "expression \"^(ab|cd)$\" matches \"ab\" but not \"abd\".\n"
       "TIMESTAMP will write a string representation of "
       "the current date and/or time to the output variable.\n"
       "Should the command be unable to obtain a timestamp "

Source/cmTarget.cxx

@@ -1232,7 +1232,9 @@ void cmTarget::DefineProperties(cmake *cm)
     ("GENERATOR_FILE_NAME", cmProperty::TARGET,
      "Generator's file for this target.",
      "An internal property used by some generators to record the name of "
-     "project or dsp file associated with this target.");
+     "project or dsp file associated with this target. Note that at configure "
+     "time, this property is only set for targets created by "
+     "include_external_msproject().");
 
   cm->DefineProperty
     ("SOURCES", cmProperty::TARGET,