Issue in man page puts.3

Issue in man page puts.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue 1:  I<putchar(c)> → B<putchar(>I<c>B<)>
Issue 2:  I<putc(c,\\ stdout)> → B<putc(>I<c>B<, >I<stdout>B<)>

"I<putchar(c)> is equivalent to I<putc(c,\\ stdout)>."

Re: Issue in man page puts.3

[Alejandro Colomar]

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

Hi Helge,

On Sun, Aug 24, 2025 at 02:48:48PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue 1:  I<putchar(c)> → B<putchar(>I<c>B<)>
> Issue 2:  I<putc(c,\\ stdout)> → B<putc(>I<c>B<, >I<stdout>B<)>
> 
> "I<putchar(c)> is equivalent to I<putc(c,\\ stdout)>."

These are correct.  See man-pages(7):

       Expressions, if not written on a separate indented line,
       should be specified in italics.


Cheers,
Alex


-- 
<https://www.alejandro-colomar.es/>

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

Re: Issue in man page puts.3

[Helge Kreutzmann]

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

Am Sun, Aug 24, 2025 at 09:17:17PM +0200 schrieb Alejandro Colomar:
> Hi Helge,
> 
> On Sun, Aug 24, 2025 at 02:48:48PM +0000, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue 1:  I<putchar(c)> → B<putchar(>I<c>B<)>
> > Issue 2:  I<putc(c,\\ stdout)> → B<putc(>I<c>B<, >I<stdout>B<)>
> > 
> > "I<putchar(c)> is equivalent to I<putc(c,\\ stdout)>."
> 
> These are correct.  See man-pages(7):
> 
>        Expressions, if not written on a separate indented line,
>        should be specified in italics.

Thanks for the pointer. I now see that sentence, but it doesn't make
sense. I believed the whole idea of this formatting was to give
meaning to the content, e.g. put variables in italices and "fixed"
strings in bold.

Rules like these also make translations harder, because translators
are not programmers, and guides like layed out in the previous
paragraphs really helped a lot doing good translations.

I guess at least for Linux man pages I stop reporting formatting
issues, as the rules are much more complex than I would like them to
be / than I tought.

Sorry thus for the many (incorrect) reports.

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: Issue in man page puts.3

[Alejandro Colomar]

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

Hi Helge,

On Mon, Aug 25, 2025 at 04:05:55PM +0000, Helge Kreutzmann wrote:
> Am Sun, Aug 24, 2025 at 09:17:17PM +0200 schrieb Alejandro Colomar:
> > Hi Helge,
> > 
> > On Sun, Aug 24, 2025 at 02:48:48PM +0000, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue 1:  I<putchar(c)> → B<putchar(>I<c>B<)>
> > > Issue 2:  I<putc(c,\\ stdout)> → B<putc(>I<c>B<, >I<stdout>B<)>
> > > 
> > > "I<putchar(c)> is equivalent to I<putc(c,\\ stdout)>."
> > 
> > These are correct.  See man-pages(7):
> > 
> >        Expressions, if not written on a separate indented line,
> >        should be specified in italics.
> 
> Thanks for the pointer. I now see that sentence, but it doesn't make
> sense. I believed the whole idea of this formatting was to give
> meaning to the content, e.g. put variables in italices and "fixed"
> strings in bold.

In general, I try to avoid these inlined expressions, and replace them
by indented ones, which don't go in italics (they have no formatting;
just monospaced).  I agree with the problem you mentioned, and think
that the solution is to try to avoid inlined expressions as much as is
sensible to do.

> Rules like these also make translations harder, because translators
> are not programmers, and guides like layed out in the previous
> paragraphs really helped a lot doing good translations.
> 
> I guess at least for Linux man pages I stop reporting formatting
> issues, as the rules are much more complex than I would like them to
> be / than I tought.

No problem; this reports help realize when something is confusing for
readers.  Please continue reporting issues if you don't understand
something.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

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