Help: Organize file command docs into sections

Add a synopsis section at the top summarizing all signatures.

Issue: #17948

Help/command/file.rst

@@ -3,7 +3,44 @@ file
 
 File manipulation command.
 
-------------------------------------------------------------------------------
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  `Reading`_
+    file(`READ`_ <filename> <out-var> [...])
+    file(`STRINGS`_ <filename> <out-var> [...])
+    file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
+    file(`TIMESTAMP`_ <filename> <out-var> [...])
+
+  `Writing`_
+    file({`WRITE`_ | `APPEND`_} <filename> <content>...)
+    file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
+    file(`GENERATE`_ OUTPUT <output-file> [...])
+
+  `Filesystem`_
+    file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
+    file(`RENAME`_ <oldname> <newname>)
+    file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
+    file(`MAKE_DIRECTORY`_ [<dir>...])
+    file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
+
+  `Path Conversion`_
+    file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
+    file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
+
+  `Transfer`_
+    file(`DOWNLOAD`_ <url> <file> [...])
+    file(`UPLOAD`_ <file> <url> [...])
+
+  `Locking`_
+    file(`LOCK`_ <path> [...])
+
+Reading
+^^^^^^^
+
+.. _READ:
 
 ::
 
@@ -15,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a
 read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
 be converted to a hexadecimal representation (useful for binary data).
 
-------------------------------------------------------------------------------
+.. _STRINGS:
 
 ::
 
@@ -66,7 +103,7 @@ For example, the code
 stores a list in the variable ``myfile`` in which each item is a line
 from the input file.
 
-------------------------------------------------------------------------------
+.. _HASH:
 
 ::
 
@@ -77,7 +114,7 @@ store it in a ``<variable>``.  The supported ``<HASH>`` algorithm names
 are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
 command.
 
-------------------------------------------------------------------------------
+.. _TIMESTAMP:
 
 ::
 
@@ -90,7 +127,11 @@ timestamp variable will be set to the empty string ("").
 See the :command:`string(TIMESTAMP)` command for documentation of
 the ``<format>`` and ``UTC`` options.
 
-------------------------------------------------------------------------------
+Writing
+^^^^^^^
+
+.. _WRITE:
+.. _APPEND:
 
 ::
 
@@ -106,7 +147,8 @@ exist will be created.
 If the file is a build input, use the :command:`configure_file` command
 to update the file only when its content changes.
 
-------------------------------------------------------------------------------
+.. _TOUCH:
+.. _TOUCH_NOCREATE:
 
 ::
 
@@ -123,7 +165,7 @@ does not exist it will be silently ignored.
 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
 modified.
 
-------------------------------------------------------------------------------
+.. _GENERATE:
 
 ::
 
@@ -169,7 +211,11 @@ generation phase. The output file will not yet have been written when the
 ``file(GENERATE)`` command returns, it is written only after processing all
 of a project's ``CMakeLists.txt`` files.
 
-------------------------------------------------------------------------------
+Filesystem
+^^^^^^^^^^
+
+.. _GLOB:
+.. _GLOB_RECURSE:
 
 ::
 
@@ -224,7 +270,7 @@ Examples of recursive globbing include::
 
   /dir/*.py  - match all python files in /dir and subdirectories
 
-------------------------------------------------------------------------------
+.. _RENAME:
 
 ::
 
@@ -233,7 +279,8 @@ Examples of recursive globbing include::
 Move a file or directory within a filesystem from ``<oldname>`` to
 ``<newname>``, replacing the destination atomically.
 
-------------------------------------------------------------------------------
+.. _REMOVE:
+.. _REMOVE_RECURSE:
 
 ::
 
@@ -244,7 +291,7 @@ Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
 files and directories, also non-empty directories. No error is emitted if a
 given file does not exist.
 
-------------------------------------------------------------------------------
+.. _MAKE_DIRECTORY:
 
 ::
 
@@ -252,7 +299,8 @@ given file does not exist.
 
 Create the given directories and their parents as needed.
 
-------------------------------------------------------------------------------
+.. _COPY:
+.. _INSTALL:
 
 ::
 
@@ -285,7 +333,10 @@ and ``NO_SOURCE_PERMISSIONS`` is default.
 Installation scripts generated by the :command:`install` command
 use this signature (with some undocumented options for internal use).
 
-------------------------------------------------------------------------------
+Path Conversion
+^^^^^^^^^^^^^^^
+
+.. _RELATIVE_PATH:
 
 ::
 
@@ -294,7 +345,8 @@ use this signature (with some undocumented options for internal use).
 Compute the relative path from a ``<directory>`` to a ``<file>`` and
 store it in the ``<variable>``.
 
-------------------------------------------------------------------------------
+.. _TO_CMAKE_PATH:
+.. _TO_NATIVE_PATH:
 
 ::
 
@@ -312,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
 Always use double quotes around the ``<path>`` to be sure it is treated
 as a single argument to this command.
 
-------------------------------------------------------------------------------
+Transfer
+^^^^^^^^
+
+.. _DOWNLOAD:
+.. _UPLOAD:
 
 ::
 
@@ -399,7 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
 If neither ``TLS`` option is given CMake will check variables
 ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
 
-------------------------------------------------------------------------------
+Locking
+^^^^^^^
+
+.. _LOCK:
 
 ::