Errors in man pages, here: shmop.2

Errors in man pages, here: shmop.2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 2068 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: shmop.2
Issue: file → files

"The following header file is included by the \"reader\" and \"writer\" "
"programs."

-- 
      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: shmop.2

[Michael Kerrisk (man-pages)]

Hello Helge,

> Man page: shmop.2
> Issue: file → files
>
> "The following header file is included by the \"reader\" and \"writer\" "
> "programs."

The existing text looks correct to me. Please let me know further
details if you still think there's a problem after reviewing.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Jakub Wilk]

* Michael Kerrisk <mtk.manpages@gmail.com>, 2021-07-26, 01:02:
>>Man page: shmop.2
>>Issue: file → files
>>
>>"The following header file is included by the \"reader\" and \"writer\" "
>>"programs."
>
>The existing text looks correct to me.

Yes, that's what we concluded last year:
https://lore.kernel.org/linux-man/20200706101634.GA26824@Debian-50-lenny-64-minimal/T/

-- 
Jakub Wilk

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

[Michael Kerrisk (man-pages)]

On 7/26/21 8:44 AM, Jakub Wilk wrote:
> * Michael Kerrisk <mtk.manpages@gmail.com>, 2021-07-26, 01:02:
>>> Man page: shmop.2
>>> Issue: file → files
>>>
>>> "The following header file is included by the \"reader\" and \"writer\" "
>>> "programs."
>>
>> The existing text looks correct to me.
> 
> Yes, that's what we concluded last year:
> https://lore.kernel.org/linux-man/20200706101634.GA26824@Debian-50-lenny-64-minimal/T/

Thanks for checking, Jakub.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Helge Kreutzmann]

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

Hello Michael,
On Mon, Jul 26, 2021 at 01:02:10AM +0200, Michael Kerrisk (man-pages) wrote:
> > Man page: shmop.2
> > Issue: file → files
> >
> > "The following header file is included by the \"reader\" and \"writer\" "
> > "programs."
> 
> The existing text looks correct to me. Please let me know further
> details if you still think there's a problem after reviewing.

Probably we do not understand the sentence correctly, so bear with me.
Currently, the man page reads as follows:

   Program source: svshm_string.h
       The following header file is included by the "reader" and "writer" programs.

           #include <sys/types.h>
           #include <sys/ipc.h>
           #include <sys/shm.h>
           #include <sys/sem.h>
           #include <stdio.h>
           #include <stdlib.h>
           #include <string.h>

           #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                                   } while (0)

The sentence in question seems to refer to the next paragraph, i.e.
the beginning of the program source. There 7 header files (from
types.h up to string.h) are mentioned. In the translation we also
replaced the full stop by a colon. Since there are 7 header files, we
assume that it needs to be plural.

Now explaining this and reading it again, I think I understand the
sentence now (better). The header file is "svshm_string.h" and thus
singular. So logically (but it does not work in the overall formatting
of the man page), the first two lines above would need to be read in a
different order. 

       The following header file is included by the "reader" and "writer" programs.
   Program source: svshm_string.h

If this interpetation is correct, maybe the following change could be
made:

   Program source: svshm_string.h
       This header file is included by the "reader" and "writer" programs:
       ~~~~~~~~~~                                                       ~~

Once I've your confirmation, I'll align the translation.

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: shmop.2

[Michael Kerrisk (man-pages)]

Hello Helge,

On 8/17/21 3:51 PM, Helge Kreutzmann wrote:
> Hello Michael,
> On Mon, Jul 26, 2021 at 01:02:10AM +0200, Michael Kerrisk (man-pages) wrote:
>>> Man page: shmop.2
>>> Issue: file → files
>>>
>>> "The following header file is included by the \"reader\" and \"writer\" "
>>> "programs."
>>
>> The existing text looks correct to me. Please let me know further
>> details if you still think there's a problem after reviewing.
> 
> Probably we do not understand the sentence correctly, so bear with me.
> Currently, the man page reads as follows:
> 
>    Program source: svshm_string.h
>        The following header file is included by the "reader" and "writer" programs.
> 
>            #include <sys/types.h>
>            #include <sys/ipc.h>
>            #include <sys/shm.h>
>            #include <sys/sem.h>
>            #include <stdio.h>
>            #include <stdlib.h>
>            #include <string.h>
> 
>            #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
>                                    } while (0)
> 
> The sentence in question seems to refer to the next paragraph, i.e.
> the beginning of the program source. There 7 header files (from
> types.h up to string.h) are mentioned. In the translation we also
> replaced the full stop by a colon. Since there are 7 header files, we
> assume that it needs to be plural.
> 
> Now explaining this and reading it again, I think I understand the
> sentence now (better). The header file is "svshm_string.h" and thus
> singular. So logically (but it does not work in the overall formatting
> of the man page), the first two lines above would need to be read in a
> different order. 
> 
>        The following header file is included by the "reader" and "writer" programs.
>    Program source: svshm_string.h
> 
> If this interpetation is correct, maybe the following change could be
> made:
> 
>    Program source: svshm_string.h
>        This header file is included by the "reader" and "writer" programs:
>        ~~~~~~~~~~                                                       ~~
> 
> Once I've your confirmation, I'll align the translation.

Thanks for the clarification. I have applied the following patch.

Cheers,

Michael

diff --git a/man2/shmop.2 b/man2/shmop.2
index c9bd92986..2cc49933c 100644
--- a/man2/shmop.2
+++ b/man2/shmop.2
@@ -324,10 +324,14 @@ Hello, world
 .in
 .\"
 .SS Program source: svshm_string.h
-The following header file is included by the "reader" and "writer" programs.
+The following header file is included by the "reader" and "writer" programs:
 .PP
 .in +4n
 .EX
+/* svshm_string.h
+
+   Licensed under GNU General Public License v2 or later.
+*/
 #include <sys/types.h>
 #include <sys/ipc.h>
 #include <sys/shm.h>

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Helge Kreutzmann]

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

Hello Michael,
thanks!

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 --]

Errors in man pages, here: shmop.2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 2109 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: shmop.2
Issue: "I<errno>" correct here? errno indicates the error, but does it fail itself?

"B<shmdt>()  I<errno> can fail with one of the following errors:"

-- 
      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 --]