Merge topic 'doc-source_group-FILES'

0060e95 Help: Format and clarify source_group() documentation (#14631)

1 files changed, 30 insertions, 14 deletions

diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst
index 77bb9ad..6e3829c 100644
--- a/Help/command/source_group.rst
+++ b/Help/command/source_group.rst
@@ -1,28 +1,44 @@
 source_group
 ------------
 
-Define a grouping for sources in the makefile.
+Define a grouping for source files in IDE project generation.
 
-::
+.. code-block:: cmake
 
-  source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
+  source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
 
 Defines a group into which sources will be placed in project files.
-This is mainly used to setup file tabs in Visual Studio.  Any file
-whose name is listed or matches the regular expression will be placed
-in this group.  If a file matches multiple groups, the LAST group that
-explicitly lists the file will be favored, if any.  If no group
-explicitly lists the file, the LAST group whose regular expression
-matches the file will be favored.
+This is intended to set up file tabs in Visual Studio.
+The options are:
 
-The name of the group may contain backslashes to specify subgroups:
+``FILES``
+ Any source file specified explicitly will be placed in group
+ ``<name>``.  Relative paths are interpreted with respect to the
+ current source directory.
 
-::
+``REGULAR_EXPRESSION``
+ Any source file whose name matches the regular expression will
+ be placed in group ``<name>``.
+
+If a source file matches multiple groups, the *last* group that
+explicitly lists the file with ``FILES`` will be favored, if any.
+If no group explicitly lists the file, the *last* group whose
+regular expression matches the file will be favored.
+
+The ``<name>`` of the group may contain backslashes to specify subgroups:
+
+.. code-block:: cmake
 
   source_group(outer\\inner ...)
 
-For backwards compatibility, this command also supports the format:
+For backwards compatibility, the short-hand signature
+
+.. code-block:: cmake
+
+  source_group(<name> <regex>)
+
+is equivalent to
 
-::
+.. code-block:: cmake
 
-  source_group(name regex)
+  source_group(<name> REGULAR_EXPRESSION <regex>)