Hello Helge,
On Tue, 17 Aug 2021 at 15:38, Helge Kreutzmann <debian@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> 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
