Attn gawk and man-db maintainers: 3am pages shadowing 3p

Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Warren Young]

Several gawk module manual pages (fnmatch, fork, readdir, and time(3am)) currently shadow pages of the same name in section 3p, owned by man-pages-posix.  These are currently dumped into the generic man3 directory, which causes them to take precedence over 3p because of this line in /etc/man_db.conf:

  SECTION     1 1p 8 2 3 3p 4 5 6 7 9 0p n

This causes “man readdir” to return the gawk page, not the POSIX page, as the user almost certainly intended.

To fix this, the man_db maintainer should add a 3am after 3p here, and the gawk maintainer should install the pages into the man3am directory.

Alternately, 3p could move in front of 3, since it’s more specific.  (You could say that man3p subclasses man3.)

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Corinna Vinschen]

[-- Attachment #1: Type: text/plain, Size: 1093 bytes --]

On Oct 22 12:03, Warren Young wrote:
> Several gawk module manual pages (fnmatch, fork, readdir, and
> time(3am)) currently shadow pages of the same name in section 3p,
> owned by man-pages-posix.  These are currently dumped into the generic
> man3 directory, which causes them to take precedence over 3p because
> of this line in /etc/man_db.conf:
> 
>   SECTION     1 1p 8 2 3 3p 4 5 6 7 9 0p n
> 
> This causes “man readdir” to return the gawk page, not the POSIX page,
> as the user almost certainly intended.
> 
> To fix this, the man_db maintainer should add a 3am after 3p here, and
> the gawk maintainer should install the pages into the man3am
> directory.
> 
> Alternately, 3p could move in front of 3, since it’s more specific.
> (You could say that man3p subclasses man3.)

Yaakov, how do we go about that?  I'm open to all suggestions, including
dropping gawk and man-db from the distro ;)


Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat

[-- Attachment #2: Type: application/pgp-signature, Size: 819 bytes --]

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Achim Gratz]

Corinna Vinschen writes:
> On Oct 22 12:03, Warren Young wrote:
>> Several gawk module manual pages (fnmatch, fork, readdir, and
>> time(3am)) currently shadow pages of the same name in section 3p,
>> owned by man-pages-posix.  These are currently dumped into the generic
>> man3 directory, which causes them to take precedence over 3p because
>> of this line in /etc/man_db.conf:
>> 
>>   SECTION     1 1p 8 2 3 3p 4 5 6 7 9 0p n
>> 
>> This causes “man readdir” to return the gawk page, not the POSIX page,
>> as the user almost certainly intended.
>> 
>> To fix this, the man_db maintainer should add a 3am after 3p here, and
>> the gawk maintainer should install the pages into the man3am
>> directory.
>> 
>> Alternately, 3p could move in front of 3, since it’s more specific.
>> (You could say that man3p subclasses man3.)
>
> Yaakov, how do we go about that?  I'm open to all suggestions, including
> dropping gawk and man-db from the distro ;)

I suggest looking at some Linux packages  You'll find that there are a
bunch of patches that a) make the SECTION setup considerably more
complex than the one shown above and b) add an (optional) prompt that
tells you when a manpage exists in multiple sections and allows you to
chose something other than the first in search order (which is what man
on Cygwin shows unless you give the additional option to show _all_
manpages matching the query, which can be too many).

(*)
https://build.opensuse.org/package/show?project=openSUSE%3AFactory&package=man


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldUserWavetables

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Yaakov Selkowitz]

On Fri, 2015-10-23 at 11:38 +0200, Corinna Vinschen wrote:
> On Oct 22 12:03, Warren Young wrote:
> > Several gawk module manual pages (fnmatch, fork, readdir, and
> > time(3am)) currently shadow pages of the same name in section 3p,
> > owned by man-pages-posix.  These are currently dumped into the generic
> > man3 directory, which causes them to take precedence over 3p because
> > of this line in /etc/man_db.conf:
> > 
> >   SECTION     1 1p 8 2 3 3p 4 5 6 7 9 0p n
> > 
> > This causes “man readdir” to return the gawk page, not the POSIX page,
> > as the user almost certainly intended.
> > 
> > To fix this, the man_db maintainer should add a 3am after 3p here, and
> > the gawk maintainer should install the pages into the man3am
> > directory.
> > 
> > Alternately, 3p could move in front of 3, since it’s more specific.
> > (You could say that man3p subclasses man3.)
> 
> Yaakov, how do we go about that?  I'm open to all suggestions, including
> dropping gawk and man-db from the distro ;)

Ironic, given that awk and man are both required by POSIX, without which
we wouldn't care about 3p. :-)

On Linux, 'man readdir' gets you readdir(2) (the kernel system call),
which promptly states:

    This is not the function you are interested in.  Look at readdir(3)
    for the POSIX conforming C library interface.

So you have to 'man 3 readdir' for the glibc function documentation,
'man 3p readdir' for the POSIX specification, and 'man 3am readdir' for
the gawk extension documentation.  The bottom line is that when there
are pages with the same name, you just need to be specific if you want
to get the right thing.  Therefore, I see nothing to fix in either
package.

--
Yaakov

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Achim Gratz]

Yaakov Selkowitz writes:
> The bottom line is that when there
> are pages with the same name, you just need to be specific if you want
> to get the right thing.  Therefore, I see nothing to fix in either
> package.

> man readdir
Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
 * readdir (3)
   readdir (3am)
   readdir (2)
   readdir (3p)
Man: What manual page do you want?
Man: 

The bottom line is that it is much nicer to tell the user that he may
have wanted to be more specific.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Samples for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldSamplesExtra

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Yaakov Selkowitz]

On Fri, 2015-10-23 at 21:59 +0200, Achim Gratz wrote:
> Yaakov Selkowitz writes:
> > The bottom line is that when there
> > are pages with the same name, you just need to be specific if you want
> > to get the right thing.  Therefore, I see nothing to fix in either
> > package.
> 
> > man readdir
> Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
>  * readdir (3)
>    readdir (3am)
>    readdir (2)
>    readdir (3p)
> Man: What manual page do you want?
> Man: 
> 
> The bottom line is that it is much nicer to tell the user that he may
> have wanted to be more specific.

This is not stock behaviour, nor does Fedora carry such a patch.  As
this is a user-visible change to a core POSIX-mandated utility, I do not
believe such a patch should be included without broader support thereto.

--
Yaakov

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Achim Gratz]

Yaakov Selkowitz writes:
> This is not stock behaviour, nor does Fedora carry such a patch.

I've linked that patch in an earlier message.

> As this is a user-visible change to a core POSIX-mandated utility, I
> do not believe such a patch should be included without broader support
> thereto.

The point of that change is indeed that it's user-visible.  The other
two options (showing the first page of an essentially unknowable order)
or showing all pages just don't make sense from a user perspective,
especially since the aporopos command ususally returns many more matches
than the same keyword used as an argument for man.  It used to be the
case that you could know which section you were expecting to find
something.  With all the extra extended sections these days (different
on each system) that no longer works reliably enough.

> env MAN_POSIXLY_CORRECT=1 man readdir
Man: find all matching manual pages
 * readdir (3)
   readdir (3am)
   readdir (2)
   readdir (3p)
[goes on to show 3 readdir, preferred over section 2 by /etc/manpath.config]


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: Attn gawk and man-db maintainers: 3am pages shadowing 3p

[Warren Young]

On Oct 23, 2015, at 1:18 PM, Yaakov Selkowitz wrote:
> 
> On Linux, 'man readdir' gets you readdir(2) (the kernel system call),
> which promptly states:
> 
>    This is not the function you are interested in.  Look at readdir(3)
>    for the POSIX conforming C library interface.

Interesting, but irrelevant, since Cygwin doesn’t have that collision.

Also, not all of the pages mentioned have such a collision on Linux.  opendir and fnmatch, for two.

I don’t think Cygwin needs to replicate every Linux imperfection.  It’s okay if it manages to improve on some things, occasionally. :)

> I see nothing to fix in either package.

Would moving 3p in front of 3 be such a horrible change?

I mean, how often does someone want the gawk module pages anyway, as compared to the POSIX pages they shadow?

I expect 3 is in front of 3p for Linux because Linux has a separate set of non-POSIX pages.  But Cygwin doesn’t, and isn’t likely to, so 3p should be preferred.