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 > .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.