Re: Using LS/LE

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

Hi Ingo,

At 2026-08-24T00:31:07+0200, Ingo Schwarze wrote:
> I don't yet understand what the point of .LS is

I have articulated clearly several specific points about it.  I
initially had the idea for LS/LE as early as December 2022.

https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html

At that time, I got no feedback on my proposal, which I interpreted as
indifference.  That's the usual fate of my proposals.  ;-)

For example:
https://lists.gnu.org/archive/html/groff/2026-07/msg00096.html

Earlier this year, after list nesting caused Alex pain again, and having
gotten more familiar with the bash(1) man page source, I consulted with
Alex, Pádraig Brady (GNU coreutils), Stephen Gildea (help2man), and Chet
Ramey (GNU Bash) regarding its interface, semantics, and goals.

> - in my experience, assembling items from .IP and .TP blocks to form
> lists is *not* among the problems the man(7) language causes - quite
> to the contrary,

Assembling a list is not difficult.   Exercising control over
indentation and inter-paragraph spacing (even just to turn it on and
shut it off) as they apply to the items of lists, especially when
nested, can get quite tedious.

> even though HTML is a strongly structural and semantic language,
> assembling even HTML code from .IP and .TP is a almost never a
> problem, and i don't see which other target format could possibly
> be harder to handle than HTML.

I don't disagree there.  To get groff man(7) to generate <ol>, <ul>, and
<dl> elements as desired, I'm going to have to make other revisions to
grohtml(1) first, because it insists on using HTML tables to mock up
indentation.[1]  I don't want that.  So unfortunately I don't expect
that improvement to element tagging in HTML output in groff 1.25, though
I hope to get that done for 1.26.  (All the other features of LS/LE are,
and Alex just this week helped ensure that some bugs in it got stomped.)

That's not really HTML's fault, but arises from groff's long tradition
of swinging a Mario mallet to force its stream-based paradigmatic
processing peg into HTML's block-structured hole.

> I would probably have to read up on prior discussions, but the topic
> feels unrelated and i won't mix it into this mail.

groff's documentation attempts to motivate the macros' presence.

groff_man(7):
   List enclosure macros
     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.  These macros are GNU extensions.

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

NEWS:

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

Regards,
Branden

[1] https://savannah.gnu.org/bugs/?68424

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