.ad l/.ad b

.ad l/.ad b

[Alejandro Colomar (man-pages)]

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/

AW: .ad l/.ad b

[Oliver Corff]

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/

Re: AW: .ad l/.ad b

[Alejandro Colomar (man-pages)]

Hi Oliver,

On 9/12/21 1:33 PM, Oliver Corff wrote:
> 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'.

Thanks, then it seems that we don't need it (otherwise we would have 
been using it in all pages already).

Cheers,

Alex


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

Re: .ad l/.ad b

[Ingo Schwarze]

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

Re: .ad l/.ad b

[G. Branden Robinson]

[-- 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 --]

Re: .ad l/.ad b

[G. Branden Robinson]

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

Hi Oliver,

At 2021-09-12T13:33:38+0200, Oliver Corff wrote:
> .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?

Yes, pretty much.

> Just my uninformed guess, and I am not at all sure about my impromptu
> Interpretation of 'n'.

Adjustment modes 'b' and 'n' are strictly synonymous and are in every
implementation I'm aware of going back to AT&T troff in Unix Version
7 (1979)[1].  I suppose that the mnemonics for them are "both" (or
"block") and "normal".

In my opinion, the .ad request entangles the concepts of alignment and
adjustment, something that would be more clear in a *roff that supported
right-to-left and/or boustrophedonic languages[2].  Really, the term
"adjustment" should apply _only_ to the distribution of extra space on
an output line for the purpose of producing straight vertical margins on
both sides of the text.

If we ever contemplate a groff 2.x that grants itself permission to
merrily break with tradition, such a conceptual separation is one of the
items on my wish list.

Regards,
Branden

[1] See
<https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/src/cmd/troff/n5.c>,
lines 104-128.

casead(){
        register i;

        ad = 1;
        /*leave admod alone*/
        if(skip())return;
        switch(i = getch() & CMASK){
                case 'r':       /*right adj, left ragged*/
                        admod = 2;
                        break;
                case 'l':       /*left adj, right ragged*/
                        admod = ad = 0; /*same as casena*/
                        break;
                case 'c':       /*centered adj*/
                        admod = 1;
                        break;
                case 'b': case 'n':
                        admod = 0;
                        break;
                case '0': case '2': case '4':
                        ad = 0;
                case '1': case '3': case '5':
                        admod = (i - '0')/2;
        }
}

[2] I think neatroff is capable of handling RTL scripts.

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