Using LS/LE (was: [PATCH v4 2/4] man/man5/tunables.conf: Document system-wide tunables config)

[Alejandro Colomar <alx@kernel.org>]

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

[CC -= DJ]

Hi Branden,

> Date: 2026-08-06 21:12:56-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> At 2026-08-06T16:42:35-0400, DJ Delorie wrote:
> > Alejandro Colomar <alx@kernel.org> 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.

Oops, I forgot about this before pushing.  I can still patch the page
to do that.  I was planning to release tomorrow, so it'd be interesting
to have one page with that.

BTW, I haven't heard of Mr. Sed for some long time.  It'd be nice to
meet him again.  ;-)

I've tried building groff from git HEAD now, and have some issues.
Bootstrap succeeds, configure succeeds, and then make(1) eventually
fails:

	$ make 
	  GEN      doc/groff.html
	Cannot find a locale compatible with document strings translations
	doc/groff.texi:12253: warning: @image file `line-layout' (for HTML) not found, using `line-layout.png'
	doc/groff.texi:26767: warning: @image file `gnu' (for HTML) not found, using `gnu.png'
	cp: cannot stat './doc/gnu.png': No such file or directory
	cp: cannot stat './doc/line-layout.png': No such file or directory
	make: *** [Makefile:20047: doc/groff.html] Error 1

Do you know what's wrong?


Have a lovley day!
Alex

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



-- 
<https://www.alejandro-colomar.es>

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