GNU bug report logs - #28763
docbug (stat -t): missing field names in docs(manpage) for 'stat -t'

Previous Next

Package: coreutils;

Reported by: L A Walsh <coreutils <at> tlinx.org>

Date: Mon, 9 Oct 2017 19:01:02 UTC

Severity: normal

Done: Assaf Gordon <assafgordon <at> gmail.com>

Bug is archived. No further changes may be made.

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

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

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Mon, 09 Oct 2017 19:01:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to L A Walsh <coreutils <at> tlinx.org>:
New bug report received and forwarded. Copy sent to bug-coreutils <at> gnu.org. (Mon, 09 Oct 2017 19:01:02 GMT) Full text and rfc822 format available.

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

From: L A Walsh <coreutils <at> tlinx.org>
To: bug-coreutils <at> gnu.org
Subject: docbug (stat -t): missing field names in docs(manpage) for 'stat -t'
Date: Mon, 09 Oct 2017 11:59:44 -0700
I typed stat -t to look at the terse form of 'stat', and see
a bunch of numbers -- but nowhere do I see what those numbers
are suppose to be (i.e. they aren't documented in the manpage
and they obviously aren't the same as what is in the non-terse display).






Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Mon, 09 Oct 2017 19:39:02 GMT) Full text and rfc822 format available.

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: L A Walsh <coreutils <at> tlinx.org>, 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Mon, 9 Oct 2017 13:38:26 -0600
Hello,

On 2017-10-09 12:59 PM, L A Walsh wrote:
> I typed stat -t to look at the terse form of 'stat', and see
> a bunch of numbers -- but nowhere do I see what those numbers
> are suppose to be (i.e. they aren't documented in the manpage
> and they obviously aren't the same as what is in the non-terse display).

The "--terse" format is documented in the info manual,
available either with "info stat" or online [1].

[1]
https://www.gnu.org/software/coreutils/manual/html_node/stat-invocation.html#index-terse-output

Note that it has two output formats, one for filesystems (when using
"-f") and the other for file/directories.

This is a (somewhat) recent addition by Bernhard Voelker
in 2014 [2] , so if you have coreutils version 8.23 or older installed,
it might not appear in the local "info" manual.

[2] https://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=b020002b


I also see in the code itself that if SELinux is enabled
an additional "%C" is appended at the end of the format [3]
(though that is not mentioned in the manual).

[3] https://opengrok.housegordon.com/source/xref/coreutils/src/stat.c#1393


Perhaps it's worth mentioning in the help-screen/man-page that the
full format is available in info/online ? What do others think?


Regards,
 - assaf




Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Mon, 09 Oct 2017 19:53:01 GMT) Full text and rfc822 format available.

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

From: L A Walsh <coreutils <at> tlinx.org>
To: Assaf Gordon <assafgordon <at> gmail.com>
Cc: 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Mon, 09 Oct 2017 12:52:03 -0700

Assaf Gordon wrote:
> Hello,
> 
> On 2017-10-09 12:59 PM, L A Walsh wrote:
>> I typed stat -t to look at the terse form of 'stat', and see
>> a bunch of numbers -- but nowhere do I see what those numbers
>> are suppose to be (i.e. they aren't documented in the manpage
>> and they obviously aren't the same as what is in the non-terse display).
> 
> The "--terse" format is documented in the info manual,
> available either with "info stat" or online [1].
---
	Not in mine.

> 
> [1]
> https://www.gnu.org/software/coreutils/manual/html_node/stat-invocation.html#index-terse-output
> 
> Note that it has two output formats, one for filesystems (when using
> "-f") and the other for file/directories.
> 
> This is a (somewhat) recent addition by Bernhard Voelker
> in 2014 [2] , so if you have coreutils version 8.23 or older installed,
> it might not appear in the local "info" manual.
---
	According to the 'info' page, I have version:

GNU coreutils 8.26.18-5e871      January 2017                          STAT(1)

So I don't see it there either


Though, if it isn't in the manpage, it's not very easy to
find since stat is a gnu-only format that requires arcane
knowledge to use and navigate.  


> Perhaps it's worth mentioning in the help-screen/man-page that the
> full format is available in info/online ? What do others think?
---
Why not put it in the manpage?






Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Tue, 10 Oct 2017 06:01:02 GMT) Full text and rfc822 format available.

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Assaf Gordon <assafgordon <at> gmail.com>, L A Walsh <coreutils <at> tlinx.org>,
 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Tue, 10 Oct 2017 08:00:18 +0200
On 10/09/2017 09:38 PM, Assaf Gordon wrote:
> Perhaps it's worth mentioning in the help-screen/man-page that the
> full format is available in info/online ? What do others think?

IMO this is sufficient:

  $ man man/stat.1 | grep Full
       Full documentation at: <http://www.gnu.org/software/coreutils/stat>

Have a nice day,
Berny




Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Wed, 11 Oct 2017 03:52:02 GMT) Full text and rfc822 format available.

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

From: L A Walsh <law <at> tlinx.org>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 L A Walsh <coreutils <at> tlinx.org>, Assaf Gordon <assafgordon <at> gmail.com>,
 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Tue, 10 Oct 2017 20:50:58 -0700
Bernhard Voelker <mail <at> bernhard-voelker.de> wrote:

> On 10/09/2017 09:38 PM, Assaf Gordon wrote:
> > Perhaps it's worth mentioning in the help-screen/man-page that the
> > full format is available in info/online ? What do others think?
>
> IMO this is sufficient:
>
>   $ man man/stat.1 | grep Full
>        Full documentation at: <http://www.gnu.org/software/coreutils/stat>
>
> Have a nice day,
> Berny
>
And when you are offline?  

Not everyone is always connected to the cloud...




Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Wed, 11 Oct 2017 06:59:01 GMT) Full text and rfc822 format available.

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: L A Walsh <law <at> tlinx.org>, L A Walsh <coreutils <at> tlinx.org>,
 Assaf Gordon <assafgordon <at> gmail.com>, 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Wed, 11 Oct 2017 08:58:03 +0200
On 10/11/2017 05:50 AM, L A Walsh wrote:
> Bernhard Voelker <mail <at> bernhard-voelker.de> wrote:
> 
>> On 10/09/2017 09:38 PM, Assaf Gordon wrote:
>>> Perhaps it's worth mentioning in the help-screen/man-page that the
>>> full format is available in info/online ? What do others think?
>>
>> IMO this is sufficient:
>>
>>   $ man man/stat.1 | grep Full
>>        Full documentation at: <http://www.gnu.org/software/coreutils/stat>
>>
>> Have a nice day,
>> Berny
>>
> And when you are offline?  
> 
> Not everyone is always connected to the cloud...

Adding a bit more context (-A1) to the grep command helps:

  $ man man/stat.1 | grep -A1 Full
       Full documentation at: <http://www.gnu.org/software/coreutils/stat>
       or available locally via: info '(coreutils) stat invocation'

I personally prefer 'pinfo' over 'info' as reader.

Have a nice day,
Berny




Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Wed, 11 Oct 2017 19:27:01 GMT) Full text and rfc822 format available.

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 L A Walsh <coreutils <at> tlinx.org>, 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Wed, 11 Oct 2017 13:26:26 -0600
[Message part 1 (text/plain, inline)]
Hello,

On 2017-10-11 12:58 AM, Bernhard Voelker wrote:
> Adding a bit more context (-A1) to the grep command helps:
> 
>   $ man man/stat.1 | grep -A1 Full
>        Full documentation at: <http://www.gnu.org/software/coreutils/stat>
>        or available locally via: info '(coreutils) stat invocation'
> 
> I personally prefer 'pinfo' over 'info' as reader.

Perhaps there is some merit in making the usage text more complete ?

For example, "date --help" does show the exact output of --iso-8601,
--rfc-2822 and --rfc-3339 .

Attached are two draft patches, one adds the information at the end of
the "--help" screen, the other inside the "--terse" parameter.
(these will also be propagated to the man-pages).

What do you think ?


regards,
 - assaf


[0001-stat-update-usage-with-terse-FORMAT-at-end-of-usage.patch (text/x-patch, attachment)]
[0001-stat-update-usage-with-terse-FORMAT-inlined-in-terse.patch (text/x-patch, attachment)]

Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Wed, 11 Oct 2017 20:40:03 GMT) Full text and rfc822 format available.

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Assaf Gordon <assafgordon <at> gmail.com>, L A Walsh <coreutils <at> tlinx.org>,
 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Wed, 11 Oct 2017 22:39:24 +0200
[Message part 1 (text/plain, inline)]
On 10/11/2017 09:26 PM, Assaf Gordon wrote:
> What do you think ?

Nice but redundant.
WDYT about something like the attached?

Have a nice day,
Berny
[0001-stat-output-default-formats-for-terse-in-usage.patch (text/x-patch, attachment)]

Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Wed, 11 Oct 2017 21:38:01 GMT) Full text and rfc822 format available.

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 L A Walsh <coreutils <at> tlinx.org>, 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Wed, 11 Oct 2017 15:37:44 -0600
On 2017-10-11 02:39 PM, Bernhard Voelker wrote:
> On 10/11/2017 09:26 PM, Assaf Gordon wrote:
>> What do you think ?
> 
> Nice but redundant.
> WDYT about something like the attached?

Indeed, much better.

Thanks!

-assaf






Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Thu, 12 Oct 2017 03:28:02 GMT) Full text and rfc822 format available.

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

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Assaf Gordon <assafgordon <at> gmail.com>, L A Walsh <coreutils <at> tlinx.org>,
 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Wed, 11 Oct 2017 20:27:32 -0700
On 11/10/17 13:39, Bernhard Voelker wrote:
> +
> +      printf (_("\n\
> +--terse without SELinux is equivalent to the following FORMAT:\n\
> +    %s\
> +--terse with SELinux enabled is equivalent to the following FORMAT:\n\
> +    %s\
> +"), fmt_terse_regular, fmt_terse_selinux);
> +        printf (_("\
> +--terse --file-system is equivalent to the following FORMAT:\n\
> +    %s\
> +"), fmt_terse_fs);
> +

That's an improvement thanks.
I'd be a bit happier if it was more terse (pardon the pun).
Could this bit instead be:


      printf (_("\n\
--terse is equivalent to the following FORMAT:\n\
    %s"),
#if HAVE_SELINUX_SELINUX_H
fmt_terse_selinux
#else
fmt_terse_regular
#endif
);

I used the define rather than is_selinux_enabled()
to give less variability in the man pages and
to indicate in --help that selinux is significant.

cheers,
Pádraig




Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Thu, 12 Oct 2017 06:02:01 GMT) Full text and rfc822 format available.

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>,
 Assaf Gordon <assafgordon <at> gmail.com>, L A Walsh <coreutils <at> tlinx.org>,
 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Thu, 12 Oct 2017 08:01:05 +0200
On 10/12/2017 05:27 AM, Pádraig Brady wrote:
> I'd be a bit happier if it was more terse (pardon the pun).

+1

@Assaf, would you please go ahead? ... it's your patch :-)

Have a nice day,
Berny




Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Thu, 12 Oct 2017 06:52:02 GMT) Full text and rfc822 format available.

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Pádraig Brady <P <at> draigBrady.com>,
 L A Walsh <coreutils <at> tlinx.org>, 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Thu, 12 Oct 2017 00:51:14 -0600
[Message part 1 (text/plain, inline)]
On 2017-10-12 12:01 AM, Bernhard Voelker wrote:
> On 10/12/2017 05:27 AM, Pádraig Brady wrote:
>> I'd be a bit happier if it was more terse (pardon the pun).
> 
> +1

Thank you all for the suggestions and improvements.

Attached an updated patch.

regards,
 - assaf

[0001-stat-output-default-formats-for-terse-in-usage.patch (text/x-patch, attachment)]

Information forwarded to bug-coreutils <at> gnu.org:
bug#28763; Package coreutils. (Mon, 30 Oct 2017 10:30:01 GMT) Full text and rfc822 format available.

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Assaf Gordon <assafgordon <at> gmail.com>, Pádraig Brady
 <P <at> draigBrady.com>, L A Walsh <coreutils <at> tlinx.org>, 28763 <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Mon, 30 Oct 2017 11:28:54 +0100
On 10/12/2017 08:51 AM, Assaf Gordon wrote:
> Attached an updated patch.

+1

Thanks & have a nice day,
Berny




Reply sent to Assaf Gordon <assafgordon <at> gmail.com>:
You have taken responsibility. (Tue, 31 Oct 2017 22:39:02 GMT) Full text and rfc822 format available.

Notification sent to L A Walsh <coreutils <at> tlinx.org>:
bug acknowledged by developer. (Tue, 31 Oct 2017 22:39:02 GMT) Full text and rfc822 format available.

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Pádraig Brady <P <at> draigBrady.com>,
 L A Walsh <coreutils <at> tlinx.org>, 28763-done <at> debbugs.gnu.org
Subject: Re: bug#28763: docbug (stat -t): missing field names in docs(manpage)
 for 'stat -t'
Date: Tue, 31 Oct 2017 16:38:32 -0600
On 2017-10-30 04:28 AM, Bernhard Voelker wrote:
> On 10/12/2017 08:51 AM, Assaf Gordon wrote:
>> Attached an updated patch.
> 
> +1
> 
> Thanks & have a nice day,
> Berny

Thank you,
pushed here:
 https://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=5ab71e4d3


I'm thus closing this bug.

regards,
 - assaf






bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Wed, 29 Nov 2017 12:24:04 GMT) Full text and rfc822 format available.

This bug report was last modified 6 years and 122 days ago.

Previous Next


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