GNU bug report logs - #47324
Missing information in documentation

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 47324 in the body.
You can then email your comments to 47324 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: Walter Harms <wharms <at> bfs.de>
To: "bug-coreutils <at> gnu.org" <bug-coreutils <at> gnu.org>
Subject: Missing information in documentation
Date: Mon, 22 Mar 2021 16:37:58 +0000

hi list,
in the documentation (man page) a nice feature is mssing
when a fs is mounted on a directory ls marks that with a dot
behing the permission mask (see example)

drwxr-xr-x. 2 1003 users 4096 Mar 22 17:53 vendor
                    ^^
           notice the dot here

I found nothing mentioned in the documentation.

hope that helps.

re,
 wh

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Walter Harms <wharms <at> bfs.de>, 47324-done <at> debbugs.gnu.org
Subject: Re: bug#47324: Missing information in documentation
Date: Mon, 22 Mar 2021 23:21:31 +0100

On 3/22/21 5:37 PM, Walter Harms via GNU coreutils Bug Reports wrote:
> hi list,
> in the documentation (man page) [...]

According to the GNU guidelines and to avoid double work, the man page of
the coreutils is essentially not much more than the output of --help
(and actually gets generated via that).
Instead, the real documentation is available via the Texinfo manual,
which is available in diverse formats.  In a usual installation, it
is reachable via:
  $ info '(coreutils) ls invocation'
Alternative formats include HTML, PDF etc., see:
  https://www.gnu.org/software/coreutils/manual/

> [...] nice feature is mssing
> when a fs is mounted on a directory ls marks that with a dot
> behing the permission mask (see example)
> 
> drwxr-xr-x. 2 1003 users 4096 Mar 22 17:53 vendor
>          ^^
>          notice the dot here
> 
> I found nothing mentioned in the documentation.

It is documented in the section about the '-l' option:

  https://www.gnu.org/software/coreutils/manual/html_node/What-information-is-listed.html

  [...]
  Following the file mode bits is a single character that specifies whether an
  alternate access method such as an access control list applies to the file.
  When the character following the file mode bits is a space, there is no alternate
  access method. When it is a printing character, then there is such a method.

  GNU ls uses a ‘.’ character to indicate a file with a security context, but no
  other alternate access method.

  A file with any other combination of alternate access methods is marked with a ‘+’ character.

Assuming that this section is clear enough, I'm hereby marking this as done
in our bug tracker. Of course, the discussion can continue, and we could even
reopen the issue if needed.

Have a nice day,
Berny

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

From: Walter Harms <wharms <at> bfs.de>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>, "47324-done <at> debbugs.gnu.org"
 <47324-done <at> debbugs.gnu.org>
Subject: AW: bug#47324: Missing information in documentation
Date: Tue, 23 Mar 2021 10:18:08 +0000

In my case there was no security context involved.
It was a loop device mounted (that i was not aware of,
the image was already gone).
and rm -r stoped here because of "in use".

I expected some mentioning of mount somewhere.

re,
 wh


________________________________________
Von: Bernhard Voelker <mail <at> bernhard-voelker.de>
Gesendet: Montag, 22. März 2021 23:21
An: Walter Harms; 47324-done <at> debbugs.gnu.org
Betreff: Re: bug#47324: Missing information in documentation

WARNUNG: Diese E-Mail kam von außerhalb der Organisation. Klicken Sie nicht auf Links oder öffnen Sie keine Anhänge, es sei denn, Sie kennen den/die Absender*in und wissen, dass der Inhalt sicher ist.


On 3/22/21 5:37 PM, Walter Harms via GNU coreutils Bug Reports wrote:
> hi list,
> in the documentation (man page) [...]

According to the GNU guidelines and to avoid double work, the man page of
the coreutils is essentially not much more than the output of --help
(and actually gets generated via that).
Instead, the real documentation is available via the Texinfo manual,
which is available in diverse formats.  In a usual installation, it
is reachable via:
  $ info '(coreutils) ls invocation'
Alternative formats include HTML, PDF etc., see:
  https://www.gnu.org/software/coreutils/manual/

> [...] nice feature is mssing
> when a fs is mounted on a directory ls marks that with a dot
> behing the permission mask (see example)
>
> drwxr-xr-x. 2 1003 users 4096 Mar 22 17:53 vendor
>          ^^
>          notice the dot here
>
> I found nothing mentioned in the documentation.

It is documented in the section about the '-l' option:

  https://www.gnu.org/software/coreutils/manual/html_node/What-information-is-listed.html

  [...]
  Following the file mode bits is a single character that specifies whether an
  alternate access method such as an access control list applies to the file.
  When the character following the file mode bits is a space, there is no alternate
  access method. When it is a printing character, then there is such a method.

  GNU ls uses a ‘.’ character to indicate a file with a security context, but no
  other alternate access method.

  A file with any other combination of alternate access methods is marked with a ‘+’ character.

Assuming that this section is clear enough, I'm hereby marking this as done
in our bug tracker. Of course, the discussion can continue, and we could even
reopen the issue if needed.

Have a nice day,
Berny

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

From: L A Walsh <gnu <at> tlinx.org>
To: 47324 <at> debbugs.gnu.org, mail <at> bernhard-voelker.de, wharms <at> bfs.de
Subject: Re: bug#47324: Missing information in documentation
Date: Thu, 25 Mar 2021 06:49:36 -0700

On 2021/03/22 15:21, Bernhard Voelker wrote:
>
> According to the GNU guidelines and to avoid double work, the man page of
> the coreutils is essentially not much more than the output of --help.
>   
---
   It sure would be nice if GNU would join the *nix family and
put full documentation in the manpage (as well as or in place of
putting it in 'info').

   If languages such as python and perl can document their usage
in manpages, certainly gnu could be as helpful.


-l

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

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: L A Walsh <gnu <at> tlinx.org>, 47324 <at> debbugs.gnu.org,
 mail <at> bernhard-voelker.de, wharms <at> bfs.de
Subject: Re: bug#47324: Missing information in documentation
Date: Thu, 25 Mar 2021 08:05:35 -0700

On 3/25/21 6:49 AM, L A Walsh wrote:
>     If languages such as python and perl can document their usage
> in manpages, certainly gnu could be as helpful.

You must be joking. Python and Perl are not fully documented in 
manpages. Most free-software projects treat manpages the way the Gnu 
project does, or don't even bother with manpages.

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

From: "Glenn Golden" <gdg <at> zplane.com>
To: "L A Walsh" <gnu <at> tlinx.org>, 47324 <at> debbugs.gnu.org,
 mail <at> bernhard-voelker.de, wharms <at> bfs.de
Subject: Re: bug#47324: Missing information in documentation
Date: Thu, 25 Mar 2021 09:36:48 -0600

On Thu, Mar 25, 2021, at 07:49, L A Walsh wrote:
> On 2021/03/22 15:21, Bernhard Voelker wrote:
> >
> > According to the GNU guidelines and to avoid double work, the man page of
> > the coreutils is essentially not much more than the output of --help.
> >   
> ---
>     It sure would be nice if GNU would join the *nix family and
> put full documentation in the manpage (as well as or in place of
> putting it in 'info').
> 
>     If languages such as python and perl can document their usage
> in manpages, certainly gnu could be as helpful.
> 
> 

Perl is by no means fully documented via its man pages. And
the top-level man page (perl.1perl) has made that explicit up front
for many years. The present language (perl.1perl, from 5.32.1) is:

   "Some documentation is not available as man pages, so if a cross-
    reference is not found by man, try it with perldoc."

Perl's perldoc(1) is more or less analogous in spirit to GNU's
approach based on info(1). The man pages contain quite a bit of
useful info, but do not purport to be exhaustive. 

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Walter Harms <wharms <at> bfs.de>,
 "47324-done <at> debbugs.gnu.org" <47324-done <at> debbugs.gnu.org>
Subject: Re: bug#47324: AW: bug#47324: Missing information in documentation
Date: Fri, 26 Mar 2021 00:00:21 +0100

On 3/23/21 11:18 AM, Walter Harms via GNU coreutils Bug Reports wrote:
> In my case there was no security context involved.
> It was a loop device mounted (that i was not aware of,
> the image was already gone).
> and rm -r stoped here because of "in use".
> 
> I expected some mentioning of mount somewhere.

According to the source code [1], the directory must have had a security
context set.

[1] https://git.sv.gnu.org/cgit/coreutils.git/tree/src/ls.c?id=4698e284f#n4243

So if it was a mount point, then the only logical conclusion is that the top-most
directory of the mounted filesystem had this security context set.
Reproducer:

  # Create an EXT4 file system and loop-mount it.
  $ dd if=/dev/zero of=x.img bs=1M count=128 status=none
  $ mkfs.ext4 -q x.img
  $ mount -o loop x.img /mnt

  # Initially, there's no security context, hence no '.' after the permission string.
  $ ls -ld /mnt
  drwxr-xr-x 3 root root 1024 Mar 25 23:54 /mnt

  # Apply a security context.
  $ setfattr -n security.selinux -v somevalue /mnt

  # Now, ls(1) prints the '.' after the permission string as a hint to the security context.
  $ ls -ld /mnt
  drwxr-xr-x. 3 root root 1024 Mar 25 23:54 /mnt

Have a nice day,
Berny

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

From: L A Walsh <coreutils <at> tlinx.org>
To: Glenn Golden <gdg <at> zplane.com>, Paul Eggert <eggert <at> cs.ucla.edu>
Cc: mail <at> bernhard-voelker.de, wharms <at> bfs.de, 47324 <at> debbugs.gnu.org
Subject: Re: bug#47324: Missing information in documentation
Date: Thu, 25 Mar 2021 16:05:55 -0700

On 2021/03/25 08:36, Glenn Golden wrote:
> Perl's perldoc(1) is more or less analogous in spirit to GNU's
> approach based on info(1). The man pages contain quite a bit of
> useful info, but do not purport to be exhaustive. 
>   
=====

On 2021/03/25 08:05, Paul Eggert wrote:

> Most free-software projects treat manpages the way the Gnu 
> project does, or don't even bother with manpages.
>   

Re: perldoc analogous to info:

  Perl, by default, installs all of its perldocs as manpages.  Distro
supplied modules follow the same practice.  CPAN modules usually
have their information installed as manpages.

  Individual packages that don't follow existing standards may
not be converted. So yeah, that's analogous to .info: Gnu who does
their own thing doesn't supply full docs in manpages -- doesn't
really try.

---

Re: "most"[sic] fs projs...

Most or all of perl's base language information is installed as
manpages. As for 'most free-sw', if it is GUI based or
windows based, *nix manpages don't exist in their world.

If a project is run via the command line on *nix, the manpages are
the primary documentation -- for MOST free-sw targeting the *nix
cmdline.  Gnu is one of the worst offenders in *nix-cmdline-sw for
not following that standard.


Arguing the point w/Gnu-SW-devs who refuse to consider outside
viewpoints isn't very useful.

Cheers!

Previous Next

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