From 0060e955db6d200613db46937211cc971fd252bb Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 5 Dec 2013 13:22:57 -0500 Subject: [PATCH] Help: Format and clarify source_group() documentation (#14631) Refine the .rst formatting. Document the FILES option explicitly and specify how it treats relative paths. --- Help/command/source_group.rst | 44 ++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 77bb9ad92..6e3829c04 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( [FILES ...] [REGULAR_EXPRESSION ]) 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 + ````. 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 ````. + +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 ```` 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) + source_group( ) + +is equivalent to + +.. code-block:: cmake + + source_group( REGULAR_EXPRESSION )