Help: Move general FILE_SET info to cmake-buildsystem(7)

File sets have evolved to be more ubiquitous throughout a CMake build,
outside the scope of simply the target_sources command. Move general
information to the `cmake-buildsystem(7)` manual and keep only
reference information specific to the syntax of target_sources in its
command page. Sprinkle some more cross-references to the new location.

Fixes: #27900

Suggested-By: Marc Chevrier <marc.chevrier@gmail.com>

Help/command/install.rst

@@ -247,9 +247,9 @@ Signatures
   ``FILE_SET <set-name>``
     .. versionadded:: 3.23
 
-    File sets are defined by the :command:`target_sources(FILE_SET)` command.
+    :ref:`File sets` are defined by the :command:`target_sources(FILE_SET)`
-    If the file set ``<set-name>`` exists and is ``PUBLIC`` or ``INTERFACE``,
+    command. If the file set ``<set-name>`` exists and is ``PUBLIC`` or
-    any files in the set of type ``HEADERS`` are installed under
+    ``INTERFACE``, any files in the set of type ``HEADERS`` are installed under
     the destination (see below). Other types do not have any default
     destination, so ``DESTINATION`` option must be specified for each
     ``FILE_SET``.
@@ -534,9 +534,10 @@ Signatures
 
   .. note::
 
-    If installing header files, consider using file sets defined by
+    If installing header files, consider using :ref:`file sets` defined by
     :command:`target_sources(FILE_SET)` instead. File sets associate
-    headers with a target and they install as part of the target.
+    headers with a target and they install as part of the target. See the
+    :manual:`cmake-buildsystem(7)` manual for more details.
 
   Install files or programs:
 
@@ -643,10 +644,11 @@ Signatures
 
   .. note::
 
-    To install a directory sub-tree of headers, consider using file sets
+    To install a directory sub-tree of headers, consider using :ref:`file sets`
     defined by :command:`target_sources(FILE_SET)` instead. File sets not only
     preserve directory structure, they also associate headers with a target
-    and install as part of the target.
+    and install as part of the target. See the :manual:`cmake-buildsystem(7)`
+    manual for more details.
 
   Install the contents of one or more directories:
 

Help/command/source_group.rst

@@ -88,6 +88,8 @@ Commands
     List of file sets. Files of these file sets will be placed in group
     ``<group>``. Arguments to ``FILE_SETS`` may use
     :manual:`generator expressions <cmake-generator-expressions(7)>`.
+    See the :manual:`cmake-buildsystem(7)` manual for more details on
+    :ref:`File Sets`.
 
   ``TARGET <target>``
     .. versionadded:: 4.5

Help/command/target_sources.rst

@@ -63,8 +63,6 @@ expressions to ensure the sources are correctly assigned to the target.
 See the :manual:`cmake-buildsystem(7)` manual for more on defining
 buildsystem properties.
 
-.. _`File Sets`:
-
 File Sets
 ^^^^^^^^^
 
@@ -78,49 +76,11 @@ File Sets
     ]...)
 
 Adds a file set to a target, or adds files to an existing file set. Targets
-have zero or more named file sets. Each file set has a name, a type, a scope of
+have zero or more named file sets.
-``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
-files within those directories.
 
-.. versionchanged:: 4.4
+See the :manual:`cmake-buildsystem(7)` manual for more on :ref:`File Sets`,
-  A file may belong to at most one non-``HEADERS`` file set in a target.
+including their types and scope semantics, properties, and installation/export
-  See policy :policy:`CMP0211`.
+behavior.
-
- The acceptable types include:
-
-``HEADERS``
-
-  Sources intended to be used via a language's ``#include`` mechanism.
-
-``SOURCES``
-  .. versionadded:: 4.4
-
-  Specifies sources to use when building a target and/or its dependents.
-  With the scope ``PRIVATE`` and ``PUBLIC``, ``<files>`` will populate the
-  :prop_fs:`SOURCES` property of ``<set>``, which are used when building the
-  target itself. With the scope ``PUBLIC`` and ``INTERFACE``, ``<files>`` will
-  populate the :prop_fs:`INTERFACE_SOURCES` property of ``<set>``, which are
-  used when building dependents. The sources specified by the
-  :prop_fs:`INTERFACE_SOURCES` property are propagated, transitively, to all
-  the dependents.
-
-``CXX_MODULES``
-  .. versionadded:: 3.28
-
-  Sources which contain C++ interface module or partition units (i.e., those
-  using the ``export`` keyword). This file set type may not have an
-  ``INTERFACE`` scope except on ``IMPORTED`` targets.
-
-The optional default file sets are named after their type. The target may not
-be a custom target or, for ``HEADERS`` and ``CXX_MODULES`` types, a
-:prop_tgt:`FRAMEWORK` target.
-
-Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
-the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
-have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an
-``INTERFACE`` or ``PUBLIC`` file set can be installed with the
-:command:`install(TARGETS)` command, and exported with the
-:command:`install(EXPORT)` and :command:`export` commands.
 
 Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``,
 or ``PRIVATE`` and accepts the following arguments:
@@ -137,10 +97,10 @@ or ``PRIVATE`` and accepts the following arguments:
 ``TYPE <type>``
 
   Every file set is associated with a particular type of file. Only types
-  specified above may be used and it is an error to specify anything else. As
+  listed under :ref:`File Sets` may be used and it is an error to specify
-  a special case, if the name of the file set is one of the types, the type
+  anything else. As a special case, if the name of the file set is one of these
-  does not need to be specified and the ``TYPE <type>`` arguments can be
+  types, the type does not need to be specified and the ``TYPE <type>``
-  omitted. For all other file set names, ``TYPE`` is required.
+  arguments can be omitted. For all other file set names, ``TYPE`` is required.
 
 ``BASE_DIRS <dirs>...``
 
@@ -168,51 +128,6 @@ or ``PRIVATE`` and accepts the following arguments:
   are treated as relative to the target's source directory after evaluation
   of generator expressions.
 
-The following target properties are set by ``target_sources(FILE_SET)``,
-but they should not generally be manipulated directly:
-
-For file sets of type ``HEADERS``:
-
-* :prop_tgt:`HEADER_SETS`
-* :prop_tgt:`INTERFACE_HEADER_SETS`
-* :prop_tgt:`HEADER_SET`
-* :prop_tgt:`HEADER_SET_<NAME>`
-* :prop_tgt:`HEADER_DIRS`
-* :prop_tgt:`HEADER_DIRS_<NAME>`
-
-For file sets of type ``SOURCES``:
-
-* :prop_tgt:`SOURCE_SETS`
-* :prop_tgt:`INTERFACE_SOURCE_SETS`
-* :prop_tgt:`SOURCE_SET`
-* :prop_tgt:`SOURCE_SET_<NAME>`
-* :prop_tgt:`SOURCE_DIRS`
-* :prop_tgt:`SOURCE_DIRS_<NAME>`
-
-For file sets of type ``CXX_MODULES``:
-
-* :prop_tgt:`CXX_MODULE_SETS`
-* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
-* :prop_tgt:`CXX_MODULE_SET`
-* :prop_tgt:`CXX_MODULE_SET_<NAME>`
-* :prop_tgt:`CXX_MODULE_DIRS`
-* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`
-
-Target properties related to include directories are also modified by
-``target_sources(FILE_SET)`` as follows:
-
-:prop_tgt:`INCLUDE_DIRECTORIES`
-
-  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
-  or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
-  :genex:`$<BUILD_INTERFACE>` and appended to this property.
-
-:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
-
-  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
-  ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
-  wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.
-
 See Also
 ^^^^^^^^
 

Help/manual/cmake-buildsystem.7.rst

@@ -378,6 +378,115 @@ The commands are:
   Populates the :prop_tgt:`LINK_OPTIONS` build specification and
   :prop_tgt:`INTERFACE_LINK_OPTIONS` usage requirement properties.
 
+.. _`File Sets`:
+
+File Sets
+^^^^^^^^^
+
+.. versionadded:: 3.23
+
+File sets associate files with a target as structured groups. A target has
+zero or more named file sets. Each file set has:
+
+* a name
+* a type
+* a scope of ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``
+* one or more base directories
+* files within those directories
+
+File sets are added to targets with :command:`target_sources` using the
+``FILE_SET`` signature. See :command:`target_sources` for argument syntax and
+validation details.
+
+.. versionchanged:: 4.4
+  A file may belong to at most one non-``HEADERS`` file set in a target.
+  See policy :policy:`CMP0211`.
+
+Acceptable file set types are:
+
+``HEADERS``
+
+  Sources intended to be used via a language's ``#include`` mechanism.
+
+``SOURCES``
+  .. versionadded:: 4.4
+
+  Specifies sources to use when building a target and/or its dependents.
+  With the scope ``PRIVATE`` and ``PUBLIC``, items populate the
+  :prop_fs:`SOURCES` property of the file set, which is used when building the
+  target itself. With the scope ``PUBLIC`` and ``INTERFACE``, items populate
+  the :prop_fs:`INTERFACE_SOURCES` property of the file set, which is used
+  when building dependents. Sources specified by
+  :prop_fs:`INTERFACE_SOURCES` propagate transitively to dependents.
+
+``CXX_MODULES``
+  .. versionadded:: 3.28
+
+  Sources which contain C++ interface module or partition units (i.e., those
+  using the ``export`` keyword). This file set type may not have an
+  ``INTERFACE`` scope except on ``IMPORTED`` targets.
+
+The optional default file sets are named after their type. The target may not
+be a custom target or, for ``HEADERS`` and ``CXX_MODULES`` types, a
+:prop_tgt:`FRAMEWORK` target.
+
+Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
+IDE integration. Additionally, files in ``HEADERS`` file sets have their
+:prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``.
+
+Files in an ``INTERFACE`` or ``PUBLIC`` file set can be installed by
+:command:`install(TARGETS)` and exported by :command:`install(EXPORT)` and
+:command:`export`.
+
+The following target properties are set by file sets and should not generally
+be manipulated directly:
+
+For file sets of type ``HEADERS``:
+
+* :prop_tgt:`HEADER_SETS`
+* :prop_tgt:`INTERFACE_HEADER_SETS`
+* :prop_tgt:`HEADER_SET`
+* :prop_tgt:`HEADER_SET_<NAME>`
+* :prop_tgt:`HEADER_DIRS`
+* :prop_tgt:`HEADER_DIRS_<NAME>`
+
+For file sets of type ``SOURCES``:
+
+* :prop_tgt:`SOURCE_SETS`
+* :prop_tgt:`INTERFACE_SOURCE_SETS`
+* :prop_tgt:`SOURCE_SET`
+* :prop_tgt:`SOURCE_SET_<NAME>`
+* :prop_tgt:`SOURCE_DIRS`
+* :prop_tgt:`SOURCE_DIRS_<NAME>`
+
+For file sets of type ``CXX_MODULES``:
+
+* :prop_tgt:`CXX_MODULE_SETS`
+* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
+* :prop_tgt:`CXX_MODULE_SET`
+* :prop_tgt:`CXX_MODULE_SET_<NAME>`
+* :prop_tgt:`CXX_MODULE_DIRS`
+* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`
+
+Target properties related to include directories are also modified by file
+sets as follows:
+
+:prop_tgt:`INCLUDE_DIRECTORIES`
+
+  If the type is ``HEADERS``, and the scope of the file set is ``PRIVATE`` or
+  ``PUBLIC``, all ``BASE_DIRS`` of the file set are wrapped in
+  :genex:`$<BUILD_INTERFACE>` and appended to this property.
+
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
+
+  If the type is ``HEADERS``, and the scope of the file set is ``INTERFACE``
+  or ``PUBLIC``, all ``BASE_DIRS`` of the file set are wrapped in
+  :genex:`$<BUILD_INTERFACE>` and appended to this property.
+
+File sets do not populate the :prop_tgt:`SOURCES` or
+:prop_tgt:`INTERFACE_SOURCES` target properties. They are represented by
+their own file set and type-specific properties.
+
 .. _`Target Build Specification`:
 
 Target Build Specification

Help/manual/cmake-file-api.7.rst

@@ -1581,15 +1581,16 @@ with members:
   .. codemodel-versionadded:: 2.5
 
   An optional member that is present when a target defines one or more
-  file sets.  The value is a JSON array of entries corresponding to the
+  :ref:`File Sets`.  The value is a JSON array of entries corresponding to the
   target's file sets.  Each entry is a JSON object with members:
 
   ``name``
     A string specifying the name of the file set.
 
   ``type``
-    A string specifying the type of the file set.  See
+    A string specifying the type of the file set.  See the
-    :command:`target_sources` supported file set types.
+    :manual:`cmake-buildsystem(7)` manual for the list of supported file set
+    types.
 
   ``visibility``
     A string specifying the visibility of the file set; one of ``PUBLIC``,
@@ -1642,7 +1643,7 @@ with members:
 
     Optional member that is present when the source is part of at least one
     file set; see also policy :policy:`CMP0211`. The value is
-    an array of unsigned integer 0-based indexes inte the ``fileSets`` array.
+    an array of unsigned integer 0-based indexes into the ``fileSets`` array.
 
   ``backtrace``
     .. deprecated:: 4.4
@@ -1709,7 +1710,7 @@ with members:
 
     Optional member that is present when the source is part of at least one
     file set; see also policy :policy:`CMP0211`. The value is
-    an array of unsigned integer 0-based indexes inte the ``fileSets`` array.
+    an array of unsigned integer 0-based indexes into the ``fileSets`` array.
 
 ``sourceGroups``
   Optional member that is present when sources are grouped together by