Help: Format and revise file() command documentation

Organize the documentation by sub-command to keep the signatures and
their descriptions nearby.  Use inline and explicit reST markup.  Revise
wording as necessary for the updated layout.  Clarify behavior of the
file(GENERATE) command w.r.t. conflicting file names.

1 files changed, 266 insertions, 178 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 83ade1d..14ca20c 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -3,211 +3,299 @@ file
 
 File manipulation command.
 
+------------------------------------------------------------------------------
+
 ::
 
-  file(WRITE filename "message to write"... )
-  file(APPEND filename "message to write"... )
-  file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
-  file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
-  file(STRINGS filename variable [LIMIT_COUNT num]
-       [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
-       [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
-       [NEWLINE_CONSUME] [REGEX regex]
-       [NO_HEX_CONVERSION])
-  file(GLOB variable [RELATIVE path] [globbing expressions]...)
-  file(GLOB_RECURSE variable [RELATIVE path]
-       [FOLLOW_SYMLINKS] [globbing expressions]...)
-  file(RENAME <oldname> <newname>)
-  file(REMOVE [file1 ...])
-  file(REMOVE_RECURSE [file1 ...])
-  file(MAKE_DIRECTORY [directory1 directory2 ...])
-  file(RELATIVE_PATH variable directory file)
-  file(TO_CMAKE_PATH path result)
-  file(TO_NATIVE_PATH path result)
-  file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
-       [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
-       [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
-       [TLS_VERIFY on|off] [TLS_CAINFO file])
-  file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
-       [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
-  file(TIMESTAMP filename variable [<format string>] [UTC])
-  file(GENERATE OUTPUT output_file
-       <INPUT input_file|CONTENT input_content>
-       [CONDITION expression])
-
-WRITE will write a message into a file called 'filename'.  It
-overwrites the file if it already exists, and creates the file if it
-does not exist.  (If the file is a build input, use configure_file to
-update the file only when its content changes.)
-
-APPEND will write a message into a file same as WRITE, except it will
-append it to the end of the file
-
-READ will read the content of a file and store it into the variable.
-It will start at the given offset and read up to numBytes.  If the
-argument HEX is given, the binary data will be converted to
-hexadecimal representation and this will be stored in the variable.
-
-MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
-cryptographic hash of the content of a file.
-
-STRINGS will parse a list of ASCII strings from a file and store it in
-a variable.  Binary data in the file are ignored.  Carriage return
-(CR) characters are ignored.  It works also for Intel Hex and Motorola
-S-record files, which are automatically converted to binary format
-when reading them.  Disable this using NO_HEX_CONVERSION.
-
-LIMIT_COUNT sets the maximum number of strings to return.  LIMIT_INPUT
-sets the maximum number of bytes to read from the input file.
-LIMIT_OUTPUT sets the maximum number of bytes to store in the output
-variable.  LENGTH_MINIMUM sets the minimum length of a string to
-return.  Shorter strings are ignored.  LENGTH_MAXIMUM sets the maximum
-length of a string to return.  Longer strings are split into strings
-no longer than the maximum length.  NEWLINE_CONSUME allows newlines to
-be included in strings instead of terminating them.
-
-REGEX specifies a regular expression that a string must match to be
-returned.  Typical usage
+  file(WRITE <filename> <content>...)
+  file(APPEND <filename> <content>...)
+
+Write ``<content>`` into a file called ``<filename>``.  If the file does
+not exist, it will be created.  If the file already exists, ``WRITE``
+mode will overwrite it and ``APPEND`` mode will append to the end.
+(If the file is a build input, use the :command:`configure_file` command
+to update the file only when its content changes.)
+
+------------------------------------------------------------------------------
+
+::
+
+  file(READ <filename> <variable>
+       [OFFSET <offset>] [LIMIT <max-in>] [HEX])
+
+Read content from a file called ``<filename>`` and store it in a
+``<variable>``.  Optionally start from the given ``<offset>`` and
+read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
+be converted to a hexadecimal representation (useful for binary data).
+
+------------------------------------------------------------------------------
 
 ::
 
+  file(STRINGS <filename> <variable> [<options>...])
+
+Parse a list of ASCII strings from ``<filename>`` and store it in
+``<variable>``.  Binary data in the file are ignored.  Carriage return
+(``\r``, CR) characters are ignored.  The options are:
+
+``LENGTH_MAXIMUM <max-len>``
+ Consider only strings of at most a given length.
+
+``LENGTH_MINIMUM <min-len>``
+ Consider only strings of at least a given length.
+
+``LIMIT_COUNT <max-num>``
+ Limit the number of distinct strings to be extracted.
+
+``LIMIT_INPUT <max-in>``
+ Limit the number of input bytes to read from the file.
+
+``LIMIT_OUTPUT <max-out>``
+ Limit the number of total bytes to store in the ``<variable>``.
+
+``NEWLINE_CONSUME``
+ Treat newline characters (``\n``, LF) as part of string content
+ instead of terminating at them.
+
+``NO_HEX_CONVERSION``
+ Intel Hex and Motorola S-record files are automatically converted to
+ binary while reading unless this option is given.
+
+``REGEX <regex>``
+ Consider only strings that match the given regular expression.
+
+For example, the code
+
+.. code-block:: cmake
+
   file(STRINGS myfile.txt myfile)
 
-stores a list in the variable "myfile" in which each item is a line
+stores a list in the variable ``myfile`` in which each item is a line
 from the input file.
 
-GLOB will generate a list of all files that match the globbing
-expressions and store it into the variable.  Globbing expressions are
-similar to regular expressions, but much simpler.  If RELATIVE flag is
-specified for an expression, the results will be returned as a
-relative path to the given path.  (We do not recommend using GLOB to
-collect a list of source files from your source tree.  If no
-CMakeLists.txt file changes when a source is added or removed then the
-generated build system cannot know when to ask CMake to regenerate.)
+------------------------------------------------------------------------------
+
+::
+
+  file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>)
+
+Compute a cryptographic hash of the content of ``<filename>`` and
+store it in a ``<variable>``.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...])
+  file(GLOB_RECURSE <variable> [RELATIVE <path>]
+       [FOLLOW_SYMLINKS] [<globbing-expressions>...])
+
+Generate a list of files that match the ``<globbing-expressions>`` and
+store it into the ``<variable>``.  Globbing expressions are similar to
+regular expressions, but much simpler.  If ``RELATIVE`` flag is
+specified, the results will be returned as relative paths to the given
+path.
+
+.. note::
+  We do not recommend using GLOB to collect a list of source files from
+  your source tree.  If no CMakeLists.txt file changes when a source is
+  added or removed then the generated build system cannot know when to
+  ask CMake to regenerate.
+
+Examples of globbing expressions include::
+
+  *.cxx      - match all files with extension cxx
+  *.vt?      - match all files with extension vta,...,vtz
+  f[3-5].txt - match files f3.txt, f4.txt, f5.txt
+
+The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
+matched directory and match the files.  Subdirectories that are symlinks
+are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
+:policy:`CMP0009` is not set to ``NEW``.
+
+Examples of recursive globbing include::
+
+  /dir/*.py  - match all python files in /dir and subdirectories
+
+------------------------------------------------------------------------------
+
+::
+
+  file(RENAME <oldname> <newname>)
+
+Move a file or directory within a filesystem from ``<oldname>`` to
+``<newname>``, replacing the destination atomically.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(REMOVE [<files>...])
+  file(REMOVE_RECURSE [<files>...])
+
+Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
+files and directories, also non-empty directories
+
+------------------------------------------------------------------------------
+
+::
+
+  file(MAKE_DIRECTORY [<directories>...])
 
-Examples of globbing expressions include:
+Create the given directories and their parents as needed.
+
+------------------------------------------------------------------------------
 
 ::
 
-   *.cxx      - match all files with extension cxx
-   *.vt?      - match all files with extension vta,...,vtz
-   f[3-5].txt - match files f3.txt, f4.txt, f5.txt
+  file(RELATIVE_PATH <variable> <directory> <file>)
 
-GLOB_RECURSE will generate a list similar to the regular GLOB, except
-it will traverse all the subdirectories of the matched directory and
-match the files.  Subdirectories that are symlinks are only traversed
-if FOLLOW_SYMLINKS is given or cmake policy CMP0009 is not set to NEW.
-See cmake --help-policy CMP0009 for more information.
+Compute the relative path from a ``<directory>`` to a ``<file>`` and
+store it in the ``<variable>``.
 
-Examples of recursive globbing include:
+------------------------------------------------------------------------------
 
 ::
 
-   /dir/*.py  - match all python files in /dir and subdirectories
-
-MAKE_DIRECTORY will create the given directories, also if their parent
-directories don't exist yet
-
-RENAME moves a file or directory within a filesystem, replacing the
-destination atomically.
-
-REMOVE will remove the given files, also in subdirectories
-
-REMOVE_RECURSE will remove the given files and directories, also
-non-empty directories
-
-RELATIVE_PATH will determine relative path from directory to the given
-file.
-
-TO_CMAKE_PATH will convert path into a cmake style path with unix /.
-The input can be a single path or a system path like "$ENV{PATH}".
-Note the double quotes around the ENV call TO_CMAKE_PATH only takes
-one argument.  This command will also convert the native list
-delimiters for a list of paths like the PATH environment variable.
-
-TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a
-cmake style path into the native path style \ for windows and / for
-UNIX.
-
-DOWNLOAD will download the given URL to the given file.  If LOG var is
-specified a log of the download will be put in var.  If STATUS var is
-specified the status of the operation will be put in var.  The status
-is returned in a list of length 2.  The first element is the numeric
-return value for the operation, and the second element is a string
-value for the error.  A 0 numeric error means no error in the
-operation.  If TIMEOUT time is specified, the operation will timeout
-after time seconds, time should be specified as an integer.  The
-INACTIVITY_TIMEOUT specifies an integer number of seconds of
-inactivity after which the operation should terminate.  If
-EXPECTED_HASH ALGO=value is specified, the operation will verify that
-the downloaded file's actual hash matches the expected value, where
-ALGO is one of MD5, SHA1, SHA224, SHA256, SHA384, or SHA512.  If it
-does not match, the operation fails with an error.  ("EXPECTED_MD5
-sum" is short-hand for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is
-specified, progress information will be printed as status messages
-until the operation is complete.  For https URLs CMake must be built
-with OpenSSL.  TLS/SSL certificates are not checked by default.  Set
-TLS_VERIFY to ON to check certificates and/or use EXPECTED_HASH to
-verify downloaded content.  Set TLS_CAINFO to specify a custom
-Certificate Authority file.  If either TLS option is not given CMake
-will check variables CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO,
-respectively.
-
-UPLOAD will upload the given file to the given URL.  If LOG var is
-specified a log of the upload will be put in var.  If STATUS var is
-specified the status of the operation will be put in var.  The status
-is returned in a list of length 2.  The first element is the numeric
-return value for the operation, and the second element is a string
-value for the error.  A 0 numeric error means no error in the
-operation.  If TIMEOUT time is specified, the operation will timeout
-after time seconds, time should be specified as an integer.  The
-INACTIVITY_TIMEOUT specifies an integer number of seconds of
-inactivity after which the operation should terminate.  If
-SHOW_PROGRESS is specified, progress information will be printed as
-status messages until the operation is complete.
-
-TIMESTAMP will write a string representation of the modification time
-of filename to variable.
-
-Should the command be unable to obtain a timestamp variable will be
-set to the empty string "".
-
-See documentation of the string TIMESTAMP sub-command for more
-details.
-
-The file() command also provides COPY and INSTALL signatures:
+  file(TO_CMAKE_PATH "<path>" <variable>)
+  file(TO_NATIVE_PATH "<path>" <variable>)
+
+The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
+path with forward-slashes (``/``).  The input can be a single path or a
+system search path like ``$ENV{PATH}``.  A search path will be converted
+to a cmake-style list separated by ``;`` characters.
+
+The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
+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.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(DOWNLOAD <url> <file> [<options>...])
+  file(UPLOAD   <file> <url> [<options>...])
+
+The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``.
+The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``.
+
+Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
+
+``INACTIVITY_TIMEOUT <seconds>``
+  Terminate the operation after a period of inactivity.
+
+``LOG <variable>``
+  Store a human-readable log of the operation in a variable.
+
+``SHOW_PROGRESS``
+  Print progress information as status messages until the operation is
+  complete.
+
+``STATUS <variable>``
+  Store the resulting status of the operation in a variable.
+  The status is a ``;`` separated list of length 2.
+  The first element is the numeric return value for the operation,
+  and the second element is a string value for the error.
+  A ``0`` numeric error means no error in the operation.
+
+``TIMEOUT <seconds>``
+  Terminate the operation after a given total time has elapsed.
+
+Additional options to ``DOWNLOAD`` are:
+
+``EXPECTED_HASH ALGO=<value>``
+
+  Verify that the downloaded content hash matches the expected value, where
+  ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or
+  ``SHA512``.  If it does not match, the operation fails with an error.
+
+``EXPECTED_MD5 <value>``
+  Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
+
+``TLS_VERIFY <ON|OFF>``
+  Specify whether to verify the server certificate for ``https://`` URLs.
+  The default is to *not* verify.
+
+``TLS_CAINFO <file>``
+  Specify a custom Certificate Authority file for ``https://`` URLs.
+
+For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
+certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
+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.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(TIMESTAMP <filename> <variable> [<format>] [UTC])
+
+Compute a string representation of the modification time of ``<filename>``
+and store it in ``<variable>``.  Should the command be unable to obtain a
+timestamp variable will be set to the empty string ("").
+
+See the :command:`string(TIMESTAMP)` command for documentation of
+the ``<format>`` and ``UTC`` options.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(GENERATE <options>...)
+
+Generate an output file for each build configuration supported by the current
+:manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
+:manual:`generator expressions <cmake-generator-expressions(7)>`
+from the input content to produce the output content.  The options are:
+
+``CONDITION <condition>``
+  Generate the output file for a particular configuration only if
+  the condition is true.  The condition must be either ``0`` or ``1``
+  after evaluating generator expressions.
+
+``CONTENT <content>``
+  Use the content given explicitly as input.
+
+``INPUT <input-file>``
+  Use the content from a given file as input.
+
+``OUTPUT <output-file>``
+  Specify the output file name to generate.  Use generator expressions
+  such as ``$<CONFIG>`` to specify a configuration-specific output file
+  name.  Multiple configurations may generate the same output file only
+  if the generated content is identical.  Otherwise, the ``<output-file>``
+  must evaluate to an unique name for each configuration.
+
+Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
+``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
+
+------------------------------------------------------------------------------
 
 ::
 
-  file(<COPY|INSTALL> files... DESTINATION <dir>
-       [FILE_PERMISSIONS permissions...]
-       [DIRECTORY_PERMISSIONS permissions...]
+  file(<COPY|INSTALL> <files>... DESTINATION <dir>
+       [FILE_PERMISSIONS <permissions>...]
+       [DIRECTORY_PERMISSIONS <permissions>...]
        [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
-        [EXCLUDE] [PERMISSIONS permissions...]] [...])
+        [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
 
-The COPY signature copies files, directories, and symlinks to a
+The ``COPY`` signature copies files, directories, and symlinks to a
 destination folder.  Relative input paths are evaluated with respect
 to the current source directory, and a relative destination is
 evaluated with respect to the current build directory.  Copying
 preserves input file timestamps, and optimizes out a file if it exists
 at the destination with the same timestamp.  Copying preserves input
-permissions unless explicit permissions or NO_SOURCE_PERMISSIONS are
-given (default is USE_SOURCE_PERMISSIONS).  See the install(DIRECTORY)
-command for documentation of permissions, PATTERN, REGEX, and EXCLUDE
-options.
-
-The INSTALL signature differs slightly from COPY: it prints status
-messages, and NO_SOURCE_PERMISSIONS is default.  Installation scripts
-generated by the install() command use this signature (with some
-undocumented options for internal use).
-
-GENERATE will write an <output_file> with content from an
-<input_file>, or from <input_content>.  The output is generated
-conditionally based on the content of the <condition>.  The file is
-written at CMake generate-time and the input may contain generator
-expressions.  The <condition>, <output_file> and <input_file> may also
-contain generator expressions.  The <condition> must evaluate to
-either '0' or '1'.  The <output_file> must evaluate to a unique name
-among all configurations and among all invocations of file(GENERATE).
+permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
+are given (default is ``USE_SOURCE_PERMISSIONS``).
+See the :command:`install(DIRECTORY)` command for documentation of
+permissions, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options.
+
+The ``INSTALL`` signature differs slightly from ``COPY``: it prints
+status messages, and ``NO_SOURCE_PERMISSIONS`` is default.
+Installation scripts generated by the :command:`install` command
+use this signature (with some undocumented options for internal use).