Help: Organize and clarify export() command documentation

Add section headers for each signature, and a synopsis linking to them.
Re-order sections to introduce the main `export(TARGETS)` functionality
before mentioning the `export(EXPORT)` shorthand, which may be confused
with `install(EXPORT)`.

Fixes: #23221

Help/command/export.rst

@@ -1,44 +1,62 @@
 export
 ------
 
-Export targets from the build tree for use by outside projects.
+Export targets or packages for outside projects to use them directly
+from the current project's build tree, without installation.
+
+See the :command:`install(EXPORT)` command to export targets from an
+install tree.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  export(`TARGETS`_ <target>... [...])
+  export(`EXPORT`_ <export-name> [...])
+  export(`PACKAGE`_ <PackageName>)
+
+Exporting Targets
+^^^^^^^^^^^^^^^^^
+
+.. _`export(TARGETS)`:
+.. _TARGETS:
 
 .. code-block:: cmake
 
-  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
+  export(TARGETS <target>... [NAMESPACE <namespace>]
+         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
 
 Creates a file ``<filename>`` that may be included by outside projects to
-import targets from the current project's build tree.  This is useful
+import targets named by ``<target>...`` from the current project's build tree.
-during cross-compiling to build utility executables that can run on
+This is useful during cross-compiling to build utility executables that can
-the host platform in one project and then import them into another
+run on the host platform in one project and then import them into another
-project being compiled for the target platform.  If the ``NAMESPACE``
+project being compiled for the target platform.
-option is given the ``<namespace>`` string will be prepended to all target
-names written to the file.
-
-Target installations are associated with the export ``<export-name>``
-using the ``EXPORT`` option of the :command:`install(TARGETS)` command.
 
 The file created by this command is specific to the build tree and
 should never be installed.  See the :command:`install(EXPORT)` command to
-export targets from an installation tree.
+export targets from an install tree.
 
-The properties set on the generated IMPORTED targets will have the
+The options are:
-same values as the final values of the input TARGETS.
 
-.. code-block:: cmake
+``NAMESPACE <namespace>``
+  Prepend the ``<namespace>`` string to all target names written to the file.
 
-  export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
+``APPEND``
-         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
+  Append to the file instead of overwriting it.  This can be used to
+  incrementally export multiple targets to the same file.
 
-This signature is similar to the ``EXPORT`` signature, but targets are listed
+``EXPORT_LINK_INTERFACE_LIBRARIES``
-explicitly rather than specified as an export-name.  If the APPEND option is
+  Include the contents of the properties named with the pattern
-given the generated code will be appended to the file instead of overwriting it.
+  ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
-The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
+  in the export, even when policy :policy:`CMP0022` is NEW.  This is useful
-contents of the properties matching
+  to support consumers using CMake versions older than 2.8.12.
-``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
+
-policy CMP0022 is NEW.  If a library target is included in the export
+This signature requires all targets to be listed explicitly.  If a library
-but a target to which it links is not included the behavior is
+target is included in the export, but a target to which it links is not
-unspecified.
+included, the behavior is unspecified.  See the `export(EXPORT)`_ signature
+to automatically export the same targets from the build tree as
+:command:`install(EXPORT)` would from an install tree.
 
 .. note::
 
@@ -49,6 +67,50 @@ unspecified.
   transitive usage requirements of other targets that link to the
   object libraries in their implementation.
 
+Exporting Targets to Android.mk
+"""""""""""""""""""""""""""""""
+
+.. code-block:: cmake
+
+  export(TARGETS <target>... ANDROID_MK <filename>)
+
+.. versionadded:: 3.7
+
+This signature exports cmake built targets to the android ndk build system
+by creating an ``Android.mk`` file that references the prebuilt targets. The
+Android NDK supports the use of prebuilt libraries, both static and shared.
+This allows cmake to build the libraries of a project and make them available
+to an ndk build system complete with transitive dependencies, include flags
+and defines required to use the libraries. The signature takes a list of
+targets and puts them in the ``Android.mk`` file specified by the
+``<filename>`` given. This signature can only be used if policy
+:policy:`CMP0022` is NEW for all targets given. A error will be issued if
+that policy is set to OLD for one of the targets.
+
+Exporting Targets matching install(EXPORT)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _`export(EXPORT)`:
+.. _EXPORT:
+
+.. code-block:: cmake
+
+  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
+
+Creates a file ``<filename>`` that may be included by outside projects to
+import targets from the current project's build tree.  This is the same
+as the `export(TARGETS)`_ signature, except that the targets are not
+explicitly listed.  Instead, it exports the targets associated with
+the installation export ``<export-name>``.  Target installations may be
+associated with the export ``<export-name>`` using the ``EXPORT`` option
+of the :command:`install(TARGETS)` command.
+
+Exporting Packages
+^^^^^^^^^^^^^^^^^^
+
+.. _`export(PACKAGE)`:
+.. _PACKAGE:
+
 .. code-block:: cmake
 
   export(PACKAGE <PackageName>)
@@ -74,20 +136,3 @@ registry.
   outside the source and build trees.  Set the
   :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
   to the CMake user package registry.
-
-.. code-block:: cmake
-
-  export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])
-
-.. versionadded:: 3.7
-
-This signature exports cmake built targets to the android ndk build system
-by creating an Android.mk file that references the prebuilt targets. The
-Android NDK supports the use of prebuilt libraries, both static and shared.
-This allows cmake to build the libraries of a project and make them available
-to an ndk build system complete with transitive dependencies, include flags
-and defines required to use the libraries. The signature takes a list of
-targets and puts them in the Android.mk file specified by the ``<filename>``
-given. This signature can only be used if policy CMP0022 is NEW for all
-targets given. A error will be issued if that policy is set to OLD for one
-of the targets.