Re: .ad l/.ad b

[G. Branden Robinson]

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.

signature.asc
Description: PGP signature