Help: Clarify permission-related command options

The previous docs did not make clear that at most only one of the three
permissions-related options can be given for configure_file() or
file(GENERATE) and that USE_SOURCE_PERMISSIONS is already the
default behavior for these commands.

Use consistent wording to refer to the input and output files for
configure_file().

Add missing "versionadded" directives on some of these keywords.

Use the consistent wording and keyword ordering between the
configure_file(), file(GENERATE) and file(COPY) commands.

2 files changed, 40 insertions, 23 deletions

diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst
index 63ea84d..d00f08b 100644
--- a/Help/command/configure_file.rst
+++ b/Help/command/configure_file.rst
@@ -6,9 +6,9 @@ Copy a file to another location and modify its contents.
 .. code-block:: cmake
 
   configure_file(<input> <output>
-                 [FILE_PERMISSIONS <permissions>...]
+                 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
+                  FILE_PERMISSIONS <permissions>...]
                  [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
-                 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
                  [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
 
 Copies an ``<input>`` file to an ``<output>`` file and substitutes
@@ -75,8 +75,27 @@ The arguments are:
   If the path names an existing directory the output file is placed
   in that directory with the same file name as the input file.
 
+``NO_SOURCE_PERMISSIONS``
+  .. versionadded:: 3.19
+
+  Do not transfer the permissions of the input file to the output file.
+  The copied file permissions default to the standard 644 value
+  (-rw-r--r--).
+
+``USE_SOURCE_PERMISSIONS``
+  .. versionadded:: 3.20
+
+  Transfer the permissions of the input file to the output file.
+  This is already the default behavior if none of the three permissions-related
+  keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
+  or ``FILE_PERMISSIONS``).  The ``USE_SOURCE_PERMISSIONS`` keyword mostly
+  serves as a way of making the intended behavior clearer at the call site.
+
 ``FILE_PERMISSIONS <permissions>...``
-  Use user provided permissions for the output file.
+  .. versionadded:: 3.20
+
+  Ignore the input file's permissions and use the specified ``<permissions>``
+  for the output file instead.
 
 ``COPYONLY``
   Copy the file without replacing any variable references or other
@@ -89,18 +108,6 @@ The arguments are:
   Restrict variable replacement to references of the form ``@VAR@``.
   This is useful for configuring scripts that use ``${VAR}`` syntax.
 
-``NO_SOURCE_PERMISSIONS``
-  .. versionadded:: 3.19
-
-  Does not transfer the file permissions of the original file to the copy.
-  The copied file permissions default to the standard 644 value
-  (-rw-r--r--).
-
-``USE_SOURCE_PERMISSIONS``
-  .. versionadded:: 3.20
-
-  Transfer the file permissions of the original file to the output file.
-
 ``NEWLINE_STYLE <style>``
   Specify the newline style for the output file.  Specify
   ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 3db605d..24e43e9 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -480,8 +480,8 @@ modified.
   file(GENERATE OUTPUT output-file
        <INPUT input-file|CONTENT content>
        [CONDITION expression] [TARGET target]
-       [FILE_PERMISSIONS <permissions>...]
-       [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
+       [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
+        FILE_PERMISSIONS <permissions>...]
        [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
 
 Generate an output file for each build configuration supported by the current
@@ -523,16 +523,26 @@ from the input content to produce the output content.  The options are:
   require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
   ``$<TARGET_PROPERTY:prop>``).
 
-``FILE_PERMISSIONS <permissions>...``
-  Use user provided permissions for the generated file.
-
 ``NO_SOURCE_PERMISSIONS``
+  .. versionadded:: 3.20
+
   The generated file permissions default to the standard 644 value
   (-rw-r--r--).
 
 ``USE_SOURCE_PERMISSIONS``
-  Transfer the file permissions of the original file to the generated file.
-  This option expects INPUT option.
+  .. versionadded:: 3.20
+
+  Transfer the file permissions of the ``INPUT`` file to the generated file.
+  This is already the default behavior if none of the three permissions-related
+  keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
+  or ``FILE_PERMISSIONS``).  The ``USE_SOURCE_PERMISSIONS`` keyword mostly
+  serves as a way of making the intended behavior clearer at the call site.
+  It is an error to specify this option without ``INPUT``.
+
+``FILE_PERMISSIONS <permissions>...``
+  .. versionadded:: 3.20
+
+  Use the specified permissions for the generated file.
 
 ``NEWLINE_STYLE <style>``
   .. versionadded:: 3.20
@@ -702,9 +712,9 @@ Create the given directories and their parents as needed.
 .. code-block:: cmake
 
   file(<COPY|INSTALL> <files>... DESTINATION <dir>
+       [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
        [FILE_PERMISSIONS <permissions>...]
        [DIRECTORY_PERMISSIONS <permissions>...]
-       [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
        [FOLLOW_SYMLINK_CHAIN]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]