Errors in man pages, here: access.2

Errors in man pages, here: access.2

[Helge Kreutzmann]

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

Dear Linux manpages maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including Linux
Manpages) as well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometimes this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once in a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports
should use another channel, please let me know.

Man page: access.2
Issue: FIXME: The if construct does not reeally work well, better: B<access>() and B<faccessat>() return the following exit codes:

"B<access>()  and B<faccessat>()  shall fail if:"

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Errors in man pages, here: access.2

[Michael Kerrisk (man-pages)]

Helo Helge,

On Sun, 25 Jul 2021 at 19:05, Helge Kreutzmann <debian@helgefjell.de> wrote:
>
> I'm now reporting the errors for your project. If future reports
> should use another channel, please let me know.
>
> Man page: access.2
> Issue: FIXME: The if construct does not reeally work well, better: B<access>() and B<faccessat>() return the following exit codes:
>
> "B<access>()  and B<faccessat>()  shall fail if:"

I think the wording is okay. It appears in a number of pages.

Thanks,

Michael

Re: Errors in man pages, here: access.2

[Helge Kreutzmann]

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

Hello Michael,
On Sun, Jul 25, 2021 at 10:45:45PM +0200, Michael Kerrisk (man-pages) wrote:
> On Sun, 25 Jul 2021 at 19:05, Helge Kreutzmann <debian@helgefjell.de> wrote:
> >
> > I'm now reporting the errors for your project. If future reports
> > should use another channel, please let me know.
> >
> > Man page: access.2
> > Issue: FIXME: The if construct does not reeally work well, better: B<access>() and B<faccessat>() return the following exit codes:
> >
> > "B<access>()  and B<faccessat>()  shall fail if:"
> 
> I think the wording is okay. It appears in a number of pages.

I'm giving you a longer rationale for our report:

Currently the man page reads:
       access() and faccessat() may fail if:

       EFAULT pathname points outside your accessible address space.

       EINVAL mode was incorrectly specified.

This looks like a sentence on the one hand and like a table on the
other.

If it was a sentence, it could not be read, take the first case as an
example:
… may fail if EFAULT pathname points …

So we thought it might be better like a table:

       EXIT CODE     DESCRIPTION
       EFAULT        pathname points outside your accessible address space.

       EINVAL        mode was incorrectly specified.


To avoid the actual table formatting and keep it more sentence like we
proposed the above suggestion.

Another fix could be to move the "if" downwards and reword slightly:
       access() and faccessat() may fail with

       EFAULT if pathname points outside your accessible address space.

       EINVAL if mode was incorrectly specified.

And no, we did not check for other occurences.

If you state the current wording is fine ("sloppy sentence") then I
wont argue further of course, I'm not a native speaker, but we might
translate it more freely. 

Greetings

           Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Errors in man pages, here: access.2

[Michael Kerrisk (man-pages)]

Hello Helge,

On Tue, 17 Aug 2021 at 15:38, Helge Kreutzmann <debian@helgefjell.de> wrote:
>
> Hello Michael,
> On Sun, Jul 25, 2021 at 10:45:45PM +0200, Michael Kerrisk (man-pages) wrote:
> > On Sun, 25 Jul 2021 at 19:05, Helge Kreutzmann <debian@helgefjell.de> wrote:
> > >
> > > I'm now reporting the errors for your project. If future reports
> > > should use another channel, please let me know.
> > >
> > > Man page: access.2
> > > Issue: FIXME: The if construct does not reeally work well, better: B<access>() and B<faccessat>() return the following exit codes:
> > >
> > > "B<access>()  and B<faccessat>()  shall fail if:"
> >
> > I think the wording is okay. It appears in a number of pages.
>
> I'm giving you a longer rationale for our report:
>
> Currently the man page reads:
>        access() and faccessat() may fail if:
>
>        EFAULT pathname points outside your accessible address space.
>
>        EINVAL mode was incorrectly specified.
>
> This looks like a sentence on the one hand and like a table on the
> other.
>
> If it was a sentence, it could not be read, take the first case as an
> example:
> … may fail if EFAULT pathname points …
>
> So we thought it might be better like a table:
>
>        EXIT CODE     DESCRIPTION
>        EFAULT        pathname points outside your accessible address space.
>
>        EINVAL        mode was incorrectly specified.
>
>
> To avoid the actual table formatting and keep it more sentence like we
> proposed the above suggestion.
>
> Another fix could be to move the "if" downwards and reword slightly:
>        access() and faccessat() may fail with
>
>        EFAULT if pathname points outside your accessible address space.
>
>        EINVAL if mode was incorrectly specified.
>
> And no, we did not check for other occurences.
>
> If you state the current wording is fine ("sloppy sentence") then I
> wont argue further of course, I'm not a native speaker, but we might
> translate it more freely.

Thanks for the clarification. I said that the wording appears in a
number of other pages, but upon investigation, it's only a few other
pages, and there's no consistency. I decided to remove these sorts of
wordings, in some cases combining the errors into a single list. See
this commit:

https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=18ce9c4a1b81dcfc1a8d2fb12ae1bf65413adcf3

Thanks,

Michael