Right margin for code (SYNOPSIS, EXAMPLES, ...)

Right margin for code (SYNOPSIS, EXAMPLES, ...)

[Alejandro Colomar (man-pages)]

Hi Michael,

For code, for example function prototypes in SYNOPSIS, do you have a
preferred right margin? 80? 72?

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es

Re: Right margin for code (SYNOPSIS, EXAMPLES, ...)

[Michael Kerrisk (man-pages)]

Hi Alex,

On Fri, 11 Dec 2020 at 22:14, Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> For code, for example function prototypes in SYNOPSIS, do you have a
> preferred right margin? 80? 72?

If I understand your question, 80. But what prompts you to ask?

Thanks,

Michael

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

Re: Right margin for code (SYNOPSIS, EXAMPLES, ...)

[Alejandro Colomar (man-pages)]

Hey M,

I guessed it was 80.  Just wanted to make sure while I was writing some
prototypes for cacheflush.2.  Nothing special. :)

Thanks,

Alex

On 12/11/20 10:26 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On Fri, 11 Dec 2020 at 22:14, Alejandro Colomar (man-pages)
> <alx.manpages@gmail.com> wrote:
>>
>> Hi Michael,
>>
>> For code, for example function prototypes in SYNOPSIS, do you have a
>> preferred right margin? 80? 72?
> 
> If I understand your question, 80. But what prompts you to ask?
> 
> Thanks,
> 
> Michael
> 

Re: Right margin for code (SYNOPSIS, EXAMPLES, ...)

[G. Branden Robinson]

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

Hi Alex,

At 2020-12-12T19:01:30+0100, Alejandro Colomar (man-pages) wrote:
> On 12/11/20 10:26 PM, Michael Kerrisk (man-pages) wrote:
> > Hi Alex,
> > 
> > On Fri, 11 Dec 2020 at 22:14, Alejandro Colomar (man-pages)
> > <alx.manpages@gmail.com> wrote:
> >>
> >> Hi Michael,
> >>
> >> For code, for example function prototypes in SYNOPSIS, do you have a
> >> preferred right margin? 80? 72?
> > 
> > If I understand your question, 80. But what prompts you to ask?

I researched the question of right margin/line length for a change I
made to groff earlier this year, and my findings were that you should
format man pages for 78 columns; this will probably work practically
everywhere.  Things other than tbl(1) tables will work okay at widths
even narrow than this.

Why 78 and not 80?  I couldn't find an authoritative answer, but my
guess is that 80 was viewed as too risky for terminals that would
misbehave with respect to wrapping or scrolling when a write was done to
the last cell on the line or screen.  That gets us down to 79, and
perhaps a preference for even numbers over odd ones explains 78.

Quoting my own research:

"...man-db man(1) has supported the LL register for eighteen years, and
Brouwer/Lucifredi man(1) for fifteen.  Heirloom Doctools's man macros
set the line length to 78n on nroff devices unconditionally.  mandoc(1)
similarly also always formats for 78 columns on terminals.  groff's
mdoc(7) macros grew support for LL in parallel with man(7) in 2002 and
never added the \n[.l] introspection at all."[1]

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=7770e10fa4d5b903b6923f466154c806c44de35a

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

Re: Right margin for code (SYNOPSIS, EXAMPLES, ...)

[Alejandro Colomar (man-pages)]

Hi Branden,

Thanks :)

I'll use 78 from now on, then.

Cheers,

Alex

On 12/20/20 9:57 AM, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2020-12-12T19:01:30+0100, Alejandro Colomar (man-pages) wrote:
>> On 12/11/20 10:26 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On Fri, 11 Dec 2020 at 22:14, Alejandro Colomar (man-pages)
>>> <alx.manpages@gmail.com> wrote:
>>>>
>>>> Hi Michael,
>>>>
>>>> For code, for example function prototypes in SYNOPSIS, do you have a
>>>> preferred right margin? 80? 72?
>>>
>>> If I understand your question, 80. But what prompts you to ask?
> 
> I researched the question of right margin/line length for a change I
> made to groff earlier this year, and my findings were that you should
> format man pages for 78 columns; this will probably work practically
> everywhere.  Things other than tbl(1) tables will work okay at widths
> even narrow than this.
> 
> Why 78 and not 80?  I couldn't find an authoritative answer, but my
> guess is that 80 was viewed as too risky for terminals that would
> misbehave with respect to wrapping or scrolling when a write was done to
> the last cell on the line or screen.  That gets us down to 79, and
> perhaps a preference for even numbers over odd ones explains 78.
> 
> Quoting my own research:
> 
> "...man-db man(1) has supported the LL register for eighteen years, and
> Brouwer/Lucifredi man(1) for fifteen.  Heirloom Doctools's man macros
> set the line length to 78n on nroff devices unconditionally.  mandoc(1)
> similarly also always formats for 78 columns on terminals.  groff's
> mdoc(7) macros grew support for LL in parallel with man(7) in 2002 and
> never added the \n[.l] introspection at all."[1]
> 
> Regards,
> Branden
> 
> [1] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=7770e10fa4d5b903b6923f466154c806c44de35a
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/