From d65b5a8e035f6055975f939dc69a18275a6daab4 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 11 Sep 2024 09:50:55 -0400 Subject: [PATCH] Help: Format file(ARCHIVE*) options as definition lists --- Help/command/file.rst | 86 +++++++++++++++++++++++++------------------ 1 file changed, 50 insertions(+), 36 deletions(-) diff --git a/Help/command/file.rst b/Help/command/file.rst index a72b652057..b7d3413ca5 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -901,7 +901,7 @@ Archiving PATHS ... [FORMAT ] [COMPRESSION - [COMPRESSION_LEVEL ]] + [COMPRESSION_LEVEL ]] [MTIME ] [VERBOSE]) :target: ARCHIVE_CREATE @@ -913,40 +913,47 @@ Archiving listed in ````. Note that ```` must list actual files or directories; wildcards are not supported. - Use the ``FORMAT`` option to specify the archive format. Supported values - for ```` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and - ``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. + The options are: - Some archive formats allow the type of compression to be specified. - The ``7zip`` and ``zip`` archive formats already imply a specific type of - compression. The other formats use no compression by default, but can be - directed to do so with the ``COMPRESSION`` option. Valid values for - ```` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. + ``FORMAT `` + Specify the archive format. Supported values for ```` are + ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and ``zip``. + If ``FORMAT`` is not given, the default format is ``paxr``. + + ``COMPRESSION `` + Some archive formats allow the type of compression to be specified. + The ``7zip`` and ``zip`` archive formats already imply a specific type of + compression. The other formats use no compression by default, but can be + directed to do so with the ``COMPRESSION`` option. Valid values for + ```` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. + + .. note:: + With ``FORMAT`` set to ``raw``, only one file will be compressed + with the compression type specified by ``COMPRESSION``. + + ``COMPRESSION_LEVEL `` + .. versionadded:: 3.19 - .. versionadded:: 3.19 The compression level can be specified with the ``COMPRESSION_LEVEL`` option. The ```` should be between 0-9, with the default being 0. The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. - .. versionadded:: 3.26 - The ```` of the ``Zstd`` algorithm can be set - between 0-19. + .. versionadded:: 3.26 + The ```` of the ``Zstd`` algorithm can be set + between 0-19. - .. note:: - With ``FORMAT`` set to ``raw``, only one file will be compressed with the - compression type specified by ``COMPRESSION``. + ``MTIME `` + Specify the modification time recorded in tarball entries. - The ``VERBOSE`` option enables verbose output for the archive operation. - - To specify the modification time recorded in tarball entries, use - the ``MTIME`` option. + ``VERBOSE`` + Enable verbose output from the archive operation. .. signature:: file(ARCHIVE_EXTRACT INPUT [DESTINATION ] - [PATTERNS ...] + [PATTERNS ...] [LIST_ONLY] [VERBOSE] [TOUCH]) @@ -956,17 +963,30 @@ Archiving Extracts or lists the content of the specified ````. - The directory where the content of the archive will be extracted to can - be specified using the ``DESTINATION`` option. If the directory does not - exist, it will be created. If ``DESTINATION`` is not given, the current - binary directory will be used. + The options are: - If required, you may select which files and directories to list or extract - from the archive using the specified ````. Wildcards are - supported. If the ``PATTERNS`` option is not given, the entire archive will - be listed or extracted. + ``DESTINATION `` + Specify the directory under which the content of the archive will be + extracted. If the directory does not exist, it will be created. + If ``DESTINATION`` is not given, the current binary directory will + be used. - ``LIST_ONLY`` will list the files in the archive rather than extract them. + ``PATTERNS ...`` + Extract/list only files and directories that match one of the given + patterns. Wildcards are supported. If the ``PATTERNS`` option is + not given, the entire archive will be listed or extracted. + + ``LIST_ONLY`` + List the files in the archive rather than extract them. + + ``TOUCH`` + .. versionadded:: 3.24 + + Give extracted files a current local timestamp instead of extracting + file timestamps from the archive. + + ``VERBOSE`` + Enable verbose output from the extraction operation. .. note:: The working directory for this subcommand is the ``DESTINATION`` directory @@ -975,12 +995,6 @@ Archiving ``INPUT`` archives as they are unlikely to be extracted where a relative path works. - .. versionadded:: 3.24 - The ``TOUCH`` option gives extracted files a current local - timestamp instead of extracting file timestamps from the archive. - - With ``VERBOSE``, the command will produce verbose output. - Handling Runtime Binaries ^^^^^^^^^^^^^^^^^^^^^^^^^