Skip to contentSkip to conversation

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

DISCUSSION Alejandro Colomar (man-pages) 3 participants 5 messages Dec 11, 2020 – Dec 20, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

Hi Michael,

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

Thanks,

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es
#1 lore raw

Hi Alex,

Quoted 5 lines · Alejandro Colomar (man-pages)

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

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw

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

Quoted 16 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 5 lines · Alejandro Colomar (man-pages)

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

#3 lore raw

Hi Alex,

Quoted 6 lines · Alejandro Colomar (man-pages)
Quoted 5 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 1 line · Alejandro Colomar (man-pages)
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines

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

#4 lore raw

Hi Branden,

Thanks :)

I'll use 78 from now on, then.

Cheers,

Alex

Quoted 42 lines · G. Branden Robinson

Hi Alex,

Quoted 6 lines · Alejandro Colomar (man-pages)
Quoted 5 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 1 line · Alejandro Colomar (man-pages)
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines

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

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