Re: [PATCH v4 2/4] man/man5/tunables.conf: Document system-wide tunables config

"G. Branden Robinson" <[email protected]> Thu, 6 Aug 2026 21:12:56 -0500
Newsgroups	org.kernel.vger.linux-man
Message-ID	<20260807021256.pwzsls7awqmbslti@illithid>
At 2026-08-06T16:42:35-0400, DJ Delorie wrote:
> Alejandro Colomar <[email protected]> writes:
> > (I haven't tested; I've written it in the mail editor directly)
> 
> The placement of the .PD's is important ;-)
> 
> I'll send a v5 with these, you can decide if you like them or not.

Managing `PD` placement to achieve "compact lists" is indeed tedious.

If you like, you guys can pilot groff 1.25.0's new `LS` and `LE` macros
for man(7).  I expect to release 1.25.0 in the next week and a half.

Unlike the `MR` macro introduction/reform, `LS` and `LE` can be adopted
early and without any negative consequence except a GNU troff(1) warning
in category `mac`, which is not enabled by default, but which some
people enable for linting purposes.

If even that is unacceptable, you can add the following anywhere after
the `TH` macro call and before your use of `LS`.

.\" Avoid `mac` warnings from groff < 1.25.
.as LS \" empty
.as LE \" empty

Use the `as` request instead of `ds`, lest you clobber groff 1.25's
macro definitions.

So how do `LS` and `LE` help?  Here's groff's "NEWS" file:

*  The an (man) package offers new macros to ease the formatting of
   lists.  Enclose paragraphing macros between `LS` and `LE` to identify
   them as list items.  Doing so can mark them as "compact", ease
   management of their indentation, and supply hints to the output
   driver to improve their rendering (as with HTML).  Lists can be
   nested.  (Sub)sectioning macro calls, and the end of the document,
   close all open lists.  See groff_man(7) for details, and
   groff_man_style(7) for an example.  Thanks to Alex Colomar, Chet
   Ramey, Pádraig Brady, and Stephen Gildea for consultation and
   encouragement, and to Alex for selecting these macros' names.

   Because these macros format no text, documents employing them risk no
   damage to their content if the formatter does not support them.  A
   man(7) document author can choose either to transition to these
   macros, to manage list "compactness" and item indentation with
   existing man(7) package facilities, or to employ both approaches.

...and here's groff_man(7).

   List enclosure macros
...
     .LS type [compactness [indentation]]
            (since groff 1.25) Start (or open) a list.  type is one of
            “definition”, “enumerated”, or “itemized”.  compactness is a
            Boolean value directing suppression of inter‐paragraph
            spacing between list items.  indentation specifies an
            indentation amount for the body of each list item; it is
            then unnecessary to specify this argument to the list item
            macros.  Use IP with a mark argument to represent an
            itemized or enumerated list item, and TP for a definition
            list item.  Use IP without arguments to associate successive
            paragraphs with an existing list item; to these, inter‐
            paragraph spacing applies even in compact lists.

     .LE    (since groff 1.25) End (or close) the most recent open list.

For groff 1.26, I hope to use the "type" property to select appropriate
HTML elements to bracket paragraphs within list enclosures.

See:

https://savannah.gnu.org/bugs/?68335
https://savannah.gnu.org/bugs/?68424

Regards,
Branden
signature.asc (application/pgp-signature, 833 B)