GNU bug report logs - #67656
'man touch' text about --time hard to read compared to 'touch --help'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 67656 in the body.
You can then email your comments to 67656 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Arsen Arsenović <arsen <at> aarsen.me>
To: bug-coreutils <at> gnu.org
Subject: 'man touch' text about --time hard to read compared to 'touch --help'
Date: Wed, 06 Dec 2023 10:03:52 +0100

[Message part 1 (text/plain, inline)]

Hi,

In the manpage of touch, 'touch' flag --time is described as:

       --time=WORD
              change the specified time: WORD is access, atime, or use:
              equivalent to -a WORD is modify or mtime: equivalent to -m

... whereas, in the --help text, --time is described as:

    --time=WORD        change the specified time:
                         WORD is access, atime, or use: equivalent to -a
                         WORD is modify or mtime: equivalent to -m

The latter is far more readable, and the manpage appears to be
mis-formatted (perhaps by help2man?).

IMO, the help text should also say 'if WORD is ..., or ...: ...' to
provide further clarity in the text.

The formatting issue is more pressing, however, as it makes the manpage
highly confusing compared to the help or manual texts.

Could this be corrected?

Thanks, have a lovely day!
-- 
Arsen Arsenović

[signature.asc (application/pgp-signature, inline)]

Message #10 received at 67656-done <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Arsen Arsenović <arsen <at> aarsen.me>,
 67656-done <at> debbugs.gnu.org
Subject: Re: bug#67656: 'man touch' text about --time hard to read compared to
 'touch --help'
Date: Wed, 6 Dec 2023 13:11:31 +0000

On 06/12/2023 09:03, Arsen Arsenović via GNU coreutils Bug Reports wrote:
> Hi,
> 
> In the manpage of touch, 'touch' flag --time is described as:
> 
>         --time=WORD
>                change the specified time: WORD is access, atime, or use:
>                equivalent to -a WORD is modify or mtime: equivalent to -m
> 
> ... whereas, in the --help text, --time is described as:
> 
>      --time=WORD        change the specified time:
>                           WORD is access, atime, or use: equivalent to -a
>                           WORD is modify or mtime: equivalent to -m
> 
> The latter is far more readable, and the manpage appears to be
> mis-formatted (perhaps by help2man?).
> 
> IMO, the help text should also say 'if WORD is ..., or ...: ...' to
> provide further clarity in the text.
> 
> The formatting issue is more pressing, however, as it makes the manpage
> highly confusing compared to the help or manual texts.
> 
> Could this be corrected?

I pushed the following:

      --time=WORD        specify which time to change:
                           access time (-a): 'access', 'atime', 'use';
                           modification time (-m): 'modify', 'mtime'

Marking this as done.

thanks,
Pádraig

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.