Re: Using LS/LE

[Alejandro Colomar <alx@kernel.org>]

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

Hi Ingo,

> Date: 2026-08-29 13:34:55+0200
> From: Ingo Schwarze <schwarze@usta.de>
>
[...]
> The mandoc(1) -T man output mode uses
> [...]

Oh, there's a -Tman mode!  That's interesting!  Some years ago,
I wondered whether groff(1) could have a -Troff mode, which would
evaluate the man(7) (or any other -m macros, FWIW) macros without
formatting the document.  This -Tman from mandoc(1) sounds like a
similar (but not same, of course) thing.

[...]
> >      .LS type [compactness [indentation]]
> 
> What is the logical reason for requiring that, to specify the
> indentation, you also need to specify the compactness?

I guess I'd have the same question if it were the other way around, and
this way I expect it's simple to implement (I'd certainly be more
worried if groff(1) attempted to guess the meaning of my argument if I
only pass one of them), so I think I'm okay with it.  Do you have any
ideas for a better interface?

> >             (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.
> 
> That sounds very confusing.  Does "Boolean" mean: either the string "0"
> or the string "1"?  Or what would "true" or "false" mean?
> Then, "Boolean value directing suppression" sounds vaguely as if "1"
> might mean "suppress", but that's not expressed unambiguously.

Agree.

> Finally, why only *between* list items?  Why not *before each*
> list item?  Would suppressing the vertical spacing before the first
> list item still require .PD 0 *in addition* to "compact"?

The idea, I think, is that if you write '.P' surriounding LS/LS, you'll
get the outer blanks, and if not, you'll get compactness also before
and/or after the list.

[...]
> >             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.
> 
> Not sure the phrase staring with "to these" should be advertised
> so prominently.  *If* an author chooses to make a list "compact"
> but then kind of contradicts themselves by inserting paragraph
> breaks into individual list items, the behaviour you describe is
> probably what the formatter should do.

I'm not convinced about this detail either.  I think in a compact list
this should not produce a blank line:

	.P
	.LE

But this should:

	.LE
	.P

> But authors ought to be strongly discouraged from doing that.
> When one or more items of your list are so complicated that they
> require more than one paragraph of text, making your list "compact"
> makes no sense in the first place and will result in ugly and
> confusing typography.

+1

> To summarize, after reviewing the design of .LS/.LE, my first
> impression is that it is likely a small-value, small-harm
> addition.  I think i will support them in mandoc(1) -man when
> i find the time, but not emit them from mandoc(1) -T man, at least
> not for many years to come, because the whole point of that output
> mode is dealing with operating systems that use ancient
> manual page formatters, and those are unlikely to support .LS/.LE.

Makes sense.

> Chances are the the deeper scrutiny that will be necessary to
> implement .LS/.LE in mandoc(1) may lead to additional criticism;
> or if we are lucky, it may not.


Have a lovely day!
Alex

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

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