* AW: .ad l/.ad b
2021-09-12 11:13 .ad l/.ad b Alejandro Colomar (man-pages)
@ 2021-09-12 11:33 ` Oliver Corff
2021-09-12 13:06 ` Alejandro Colomar (man-pages)
2021-09-12 15:41 ` G. Branden Robinson
2021-09-12 14:03 ` Ingo Schwarze
2021-09-12 15:30 ` G. Branden Robinson
2 siblings, 2 replies; 6+ messages in thread
From: Oliver Corff @ 2021-09-12 11:33 UTC (permalink / raw)
To: Alejandro Colomar (man-pages), Michael Kerrisk (man-pages),
G. Branden Robinson
Cc: linux-man, groff
Hi,
.ad Begin line adjustment for output lines in current
adjust mode.
.ad c Start line adjustment in mode c (c=l,r,c,b,n).
That looks like left, right, centered, block and neutral?
Just my uninformed guess, and I am not at all sure about my impromptu Interpretation of 'n'.
Best regards,
Oliver.
Dr. Oliver Corff
Mailto:oliver.corff@email.de
Originalnachricht
Von: Alejandro Colomar (man-pages)
Gesendet: Sonntag, 12. September 2021 13:13
An: Michael Kerrisk (man-pages); G. Branden Robinson
Cc: linux-man; groff@gnu.org
Betreff: .ad l/.ad b
Hi, Branden and Michael!
I've seen these in shmctl.2, and didn't know what they mean.
groff(7) wasn't very helpful.
[
.SH SYNOPSIS
.nf
.ad l
.B #include <sys/shm.h>
.PP
.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
.ad b
.fi
]
What are those '.ad X' and do we really need them?
I found some other pages that use it:
[
.../linux/man-pages$ grep -rn '^\.ad b' man?
man1/localedef.1:60:.ad b
man2/setsid.2:40:.ad b
man2/acct.2:41:.ad b
man2/shmctl.2:55:.ad b
man2/shmget.2:50:.ad b
]
groff(7) related info:
[
.ad Begin line adjustment for output lines in current
adjust mode.
.ad c Start line adjustment in mode c (c=l,r,c,b,n).
]
But what does each mode mean? I couldn't find anything about them in
the manual page.
Thanks,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: .ad l/.ad b
2021-09-12 11:13 .ad l/.ad b Alejandro Colomar (man-pages)
2021-09-12 11:33 ` AW: " Oliver Corff
@ 2021-09-12 14:03 ` Ingo Schwarze
2021-09-12 15:30 ` G. Branden Robinson
2 siblings, 0 replies; 6+ messages in thread
From: Ingo Schwarze @ 2021-09-12 14:03 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: Michael Kerrisk (man-pages), G. Branden Robinson, linux-man, groff
Hi Alejandro,
Alejandro Colomar (man-pages) wrote on Sun, Sep 12, 2021 at 01:13:07PM +0200:
> I've seen these in shmctl.2, and didn't know what they mean.
> groff(7) wasn't very helpful.
>
> [
> .SH SYNOPSIS
> .nf
> .ad l
> .B #include <sys/shm.h>
> .PP
> .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
> .ad b
> .fi
> ]
This looks like cargo cult programming to me. Probably someone saw
some low-level roff(7) requests somewhere and needlessly picked up
the incantation, hoping it might miraculuously attract some beneficial
effect.
You normally do not need .nf (switch to no-fill mode) in the SYNOPSIS.
When prototypes are short enough, it makes no difference, provided
that .PP paragraph macros are used correctly between prototypes,
which is the case here. When there are prototypes that are longer
than the user's desired output width, .nf is actually harmful because
it prevents the needed line breaking, which the formatter can do
in a nice and clean way. If .nf prevents the formatter from doing
that job, that job is left to the pager or terminal which may either
break lines in ugly ways (usually at any place in the middle of any
word, and without indenting the second half of the line at all) or
it may even show truncated lines depending on the pager or terminal
configuration. Given that you do not need .nf, you do not need .fi
(switch back to the default fill mode) either.
Using .ad (change adjustment mode) in a manual page is even worse
abuse. Whether or not manual page text should be adjusted or not
is a minor technical detail that should not be decided by individual
manual pages but left to the man(1) program, to allow a uniform
user experience across the whole operating system. Attempting to
muck with .ad in a manual page almost invariably risks trouble
and on top of that rarely achieves the micro-control of formatting
details possibly intended by the author. Some man(1) implementations
may globally set .ad, and manual .ad requests in individual pages may
screw up such system wide settings. Some manual page viewers (for
example the mandoc implementation of man(1)) will ignore .ad
completely, so .ad may have no effect at all.
On top of not being useful in manual pages in the first place, the
way .ad is used here is arguably even technically incorrect. The
".ad b" (block adjustment) is apperently intended to end the effect
of the earlier ".ad l" (flush-left), but that's not what it does
because there is no guarantee the mode was "b" before the ".ad l".
Of course, attempting to do correct low-level roff(7) programming
in a manual page and actually save and restore the mode in a manual
page would be even worse abuse. A manual page is not a low-level
roff(7) programming sandbox. A manual page ought to use standard,
easy-to-understand high level macros such that it is intelligible
for the average programmer who wants to help maintain it. If it
contains stuff that makes even documentation specialists like
yourself scratch their heads, that is not good. Not good at all.
> What are those '.ad X'
https://www.gnu.org/software/groff/manual/html_node/Manipulating-Filling-and-Adjusting.html#index-ad
> and do we really need them?
No!
> I found some other pages that use it:
>
> [
> .../linux/man-pages$ grep -rn '^\.ad b' man?
> man1/localedef.1:60:.ad b
> man2/setsid.2:40:.ad b
> man2/acct.2:41:.ad b
> man2/shmctl.2:55:.ad b
> man2/shmget.2:50:.ad b
> ]
It seems a bit late for a spring cleanup, but maybe an autumn cleanup
would be in order. ;-)
Yours,
Ingo
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: .ad l/.ad b
2021-09-12 11:13 .ad l/.ad b Alejandro Colomar (man-pages)
2021-09-12 11:33 ` AW: " Oliver Corff
2021-09-12 14:03 ` Ingo Schwarze
@ 2021-09-12 15:30 ` G. Branden Robinson
2 siblings, 0 replies; 6+ messages in thread
From: G. Branden Robinson @ 2021-09-12 15:30 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: Michael Kerrisk (man-pages), linux-man, groff
[-- Attachment #1: Type: text/plain, Size: 7927 bytes --]
Hi, Alex!
At 2021-09-12T13:13:07+0200, Alejandro Colomar (man-pages) wrote:
> Hi, Branden and Michael!
>
> I've seen these in shmctl.2, and didn't know what they mean.
> groff(7) wasn't very helpful.
:( It's true that our groff(7) page doesn't cover a lot of topics that
were covered in CSTR #54.
As Ingo noted, you can consult the online copy of the groff Texinfo
manual for fuller details, however the manual has seen a lot of updates
from me in the past 2½ years.
Here's some of the applicable new material.
[[
5.1.5 Adjustment
----------------
After GNU 'troff' performs an automatic line break, it then tries to
"adjust" the line: inter-word spaces are widened until the text reaches
the right margin. Extra spaces between words are preserved. Leading
and trailing spaces are handled as noted above. Text can be aligned to
the left or right margins or centered; see *note Manipulating Filling
and Adjustment::.
...
5.7 Manipulating Filling and Adjustment
=======================================
A break interrupts filling. Various ways of causing breaks were shown
in *note Breaking::. The 'br' request likewise causes a break. A break
is implied by several other requests: 'bp', 'ce', 'cf', 'fi', 'fl',
'in', 'nf', 'rj', 'sp', 'ti', and 'trf'. If the no-break control
character is used with any of these requests, GNU 'troff' suppresses the
break; instead the requested operation takes effect at the next break.
.ll 55n
This line is normally filled and adjusted.
.br
A line's alignment is decided
'ce \" Center the next input line (no break).
when it is output.
This line returns to normal filling and adjustment.
=> This line is normally filled and adjusted.
=> A line's alignment is decided when it is output.
=> This line returns to normal filling and adjustment.
Output line properties like adjustment and indentation are not
determined until the line has been broken. An output line is said to be
"pending" if some input has been collected but an output line
corresponding to it has not yet been written; such an output line is
also termed "partially collected". If no output line is pending, it is
as if a break has already happened; additional breaks, whether explicit
or implicit, have no effect.
...
-- Request: .ad [mode]
-- Register: \n[.j]
Enable output line adjustment in MODE, taking effect when the
pending (or next) output line is broken. Adjustment is suppressed
when filling is. MODE can have one of the following values.
'b'
'n'
Adjust "normally": to both margins. This is the GNU 'troff'
default.
'c'
Center filled text. Contrast with the 'ce' request, which
centers text without filling.
'l'
Adjust text to the left margin, producing what is sometimes
called ragged-right text.
'r'
Adjust text to the right margin, producing ragged-left text.
MODE can also be a value previously stored in the '.j' register.
Using 'ad' without an argument is the same as '.ad \n[.j]'. In
particular, GNU 'troff' adjusts lines in the same way it did before
adjustment was disabled (with a call to 'na', say).
.ll 48n
.de AD
. br
. ad \\$1
..
.
.de NA
. br
. na
..
.
left
.AD r
.nr ad \n(.j
right
.AD c
center
.NA
left
.AD
center
.AD \n(ad
right
=> left
=> right
=> center
=> left
=> center
=> right
The adjustment mode and enablement status are encoded in the
read-only register '.j'. These parameters are associated with the
environment (*note Environments::).
The value of '.j' for any adjustment mode is an implementation
detail and should not be relied upon as a programmer's interface.
Do not write logic to interpret or perform arithmetic on it.
-- Request: .na
Disable output line adjustment. This produces the same output as
alignment to the left margin, but the value of the adjustment mode
register '.j' is altered differently. The adjustment mode and
enablement status are associated with the environment (*note
Environments::).
]]
> [
> .SH SYNOPSIS
> .nf
> .ad l
> .B #include <sys/shm.h>
> .PP
> .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
> .ad b
> .fi
> ]
>
> What are those '.ad X' and do we really need them?
As noted in the quote from the groff Texinfo manual above, adjustment is
disabled when filling is, so these .ad invocations are superfluous.
> I found some other pages that use it:
>
> [
> .../linux/man-pages$ grep -rn '^\.ad b' man?
> man1/localedef.1:60:.ad b
> man2/setsid.2:40:.ad b
> man2/acct.2:41:.ad b
> man2/shmctl.2:55:.ad b
> man2/shmget.2:50:.ad b
> ]
I regard it as bad style to attempt manipulation of adjustment in man
pages. For one thing, it requires the use of *roff requests, meaning
inherently low-level manipulation of the typesetting, bypassing the
macro package. For another, its effect is not all that reliable because
some people have an extreme allergy to the default *roff adjustment
mode, and disable it, as Ingo does with mandoc(1). A third reason is
that historically, the man(7) `TH` macro did not reset the adjustment
mode, so if you were formatting multiple pages at once with "groff
-man"[1], you might be stuck unexpectedly with the last adjustment mode
set by a previous page.
In groff 1.23.0 there will be a documented mechanism exposing control of
the default adjustment mode, and the `TH` is more defensively programmed
to use and restore it.
[[
Options
The following groff options set registers (with -r) and strings
(with -d) recognized and used by the man macro package.
-dAD=adjustment‐mode
Set line adjustment to adjustment‐mode, which is typically
“b” for adjustment to both margins (the default), or “l”
for left alignment (ragged right margin). Any valid argu‐
ment to groff's “.ad” request may be used. See groff(7)
for less‐common choices.
]]
> groff(7) related info:
>
> [
> .ad Begin line adjustment for output lines in current
> adjust mode.
> .ad c Start line adjustment in mode c (c=l,r,c,b,n).
> ]
>
> But what does each mode mean? I couldn't find anything about them in
> the manual page.
Sadly it is not yet present (there's a little more detail in the current
version of the page, but not enough to answer your question). It is my
intention to add a brief "Adjustment" section to this page, as I have
with "Line continuation", "Control structures", "Syntax reference
conventions", "Hyphenation", "Localization", and "Writing macros". In
most cases, these are condensed adaptations of corresponding nodes in
the groff Texinfo manual, boiled down to eliminate examples and fulfill
the aim of a reference for the experienced user needing a refresher.
Regards,
Branden
[1] man-db man(1) doesn't do this; instead, it forks a new "groff"
process for each man page to be rendered if multiple ones are requested.
I suspect this is because it is so easy for the use of low-level
requests in a man page document to do irreversible damage to the
formatting of later pages.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread