Subject: Re: [Documentation] man page inconstency
From: Paul Eggert <[email-masked]>
To: Carpe Sébastien <[email-masked]>
Cc: [email-masked]
Date: Fri, 1 Apr 2022 09:50:51 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Thanks for reporting that bug in the gzip documentation. I finally got 
around to fixing it by installing the attached patch, which should 
appear in the next gzip release. This patch fixes some nearby 
documentation problems too.

From 881c34e0ca65a0ba4999d7cf1417e4071d067ea1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Fri, 1 Apr 2022 09:46:23 -0700
Subject: [PATCH] doc: improve doc for saved timestamps etc.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem reported by Carpe Sébastien (Bug#24559).
---
 doc/gzip.texi | 18 ++++++++++++------
 gzip.1        | 18 ++++++++++++------
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/doc/gzip.texi b/doc/gzip.texi
index fc4368a..b1e03c2 100644
--- a/doc/gzip.texi
+++ b/doc/gzip.texi
@@ -170,10 +170,13 @@ coding (as used in @command{pack}), or adaptive Huffman coding
 
 Compression is always performed, even if the compressed file is slightly
 larger than the original.  The worst case expansion is a few bytes for
-the @command{gzip} file header, plus 5 bytes every 32K block, or an expansion
-ratio of 0.015% for large files.  Note that the actual number of used
-disk blocks almost never increases.  @command{gzip} normally preserves the mode,
-ownership and timestamps of files when compressing or decompressing.
+the @command{gzip} file header, plus 5 bytes per 32@tie{}KiB block, or
+an expansion ratio of 0.015% for large files.  The actual number of
+used disk blocks almost never increases.
+
+@command{gzip} normally preserves the mode and modification timestamp
+of a file when compressing or decompressing.  If you have appropriate
+privileges, it also preserves the file's owner and group.
 
 The @command{gzip} file format is specified in P. Deutsch, GZIP file
 format specification version 4.3,
@@ -332,8 +335,11 @@ is the default when decompressing.
 @item --name
 @itemx -N
 When compressing, always save the original file name, and save
-the original timestamp if the original is a regular file; this
-is the default.  When decompressing, restore the original file name and
+the seconds part of the original modification timestamp if the
+original is a regular file and its timestamp is at least 1 (1970-01-01
+00:00:01 UTC) and is less than 2@sup{32} (2106-02-07 06:28:16 UTC,
+assuming leap seconds are not counted); this
+is the default.  When decompressing, restore from the saved file name and
 timestamp if present.  This option is useful on systems which have
 a limit on file name length or when the timestamp has been lost after
 a file transfer.
diff --git a/gzip.1 b/gzip.1
index 05ed6d2..80a4bd3 100644
--- a/gzip.1
+++ b/gzip.1
@@ -183,12 +183,14 @@ or adaptive Huffman coding
 .PP
 Compression is always performed, even if the compressed file is
 slightly larger than the original. The worst case expansion is
-a few bytes for the gzip file header, plus 5 bytes every 32K block,
-or an expansion ratio of 0.015% for large files. Note that the actual
+a few bytes for the gzip file header, plus 5 bytes per 32\ KiB block,
+or an expansion ratio of 0.015% for large files. The actual
 number of used disk blocks almost never increases.
+.PP
 .B gzip
-preserves the mode, ownership and timestamps of files when compressing
-or decompressing.
+normally preserves the mode and modification timestamp
+of a file when compressing or decompressing. If you have appropriate
+privileges, it also preserves the file's owner and group.
 .SH OPTIONS
 .TP
 .B \-a --ascii
@@ -277,8 +279,12 @@ timestamp if present (copy it from the compressed file). This option
 is the default when decompressing.
 .TP
 .B \-N --name
-When compressing, always save the original file name and timestamp; this
-is the default. When decompressing, restore the original file name and
+When compressing, always save the original file name, and save
+the seconds part of the original modification timestamp if the
+original is a regular file and its timestamp is at least 1 (1970-01-01
+00:00:01 UTC) and is less than 2**32 (2106-02-07 06:28:16 UTC,
+assuming leap seconds are not counted); this
+is the default. When decompressing, restore from the saved file name and
 timestamp if present. This option is useful on systems which have
 a limit on file name length or when the timestamp has been lost after
 a file transfer.
-- 
2.32.0