Hi Alex & Stephen, At 2026-05-09T00:12:13+0200, Alejandro Colomar wrote: > On 2026-05-08T15:41:18-0500, G. Branden Robinson wrote: > IIRC, I agreed to it back then. It still seems reasonable to me.
Cool! Glad to hear it.
> > I propose two new macros for groff man(7), `LS` and `LE`, to mark
> > the
>
> Yes, I seem to remember those names. :)
Yup, they're yours! :D
> Pedantically, the description of LE is incorrect, I think. I'd say
> it's the most recent _not-yet-ended_ LS call. But I think everyone
> would understand the right thing from that text, and it's shorter, so
> maybe it's good.
Good point. There will be time to wordsmith the description.
> > Possibly also at "regular" paragraphing
> > macro calls,
>
> I don't think so. This would unnecessarily preclude having
> multi-paragraph list elements.
It wouldn't _preclude_ them. I snipped it from this reply, but as
noted, you could still achieve this with argumentless `IP` calls.
For example, bash(1)'s `GLOBSORT` is defined with a multi-paragraph yet
"compact" list.
$ nl -ba doc/bash.1
...
2410 The shell uses the following variables. In some cases,
2411 .B bash
2412 assigns a default value to a variable; these cases are noted
2413 below.
2414 .PP
2415 .PD 0
2416 .TP
2417 .B BASH_COMPAT
2418 The value is used to set the shell's compatibility level.
...
2589 The pattern matching honors the setting of the \fBextglob\fP shell
2590 option.
2591 .TP
2592 .B GLOBSORT
2593 .PD
2594 Controls how the results of pathname expansion are sorted.
2595 The value of this variable specifies the sort criteria and sort order
for
2596 the results of pathname expansion.
2597 If this variable is unset or set to the null string, pathname expansion
2598 uses the historical behavior of sorting by name,
2599 in ascending lexicographic order as determined by the
2600 .SM
2601 .B \%LC_COLLATE
2602 shell variable.
2603 .IP
2604 If set, a valid value begins with an optional \fI+\fP, which is ignored,
2605 or \fI\-\fP, which reverses the sort order from ascending to descending,
2606 followed by a sort specifier.
2607 The valid sort specifiers are
2608 .IR name ,
...
2642 If the sort specifier is missing, it defaults to \fIname\fP,
2643 so a value of \fI+\fP is equivalent to the null string,
2644 and a value of \fI-\fP sorts by name in descending order.
2645 Any invalid value restores the historical sorting behavior.
2646 .PD 0
2647 .TP
2648 .B HISTCONTROL
2649 A colon-separated list of values controlling how commands are saved on
2650 the history list.
Chet already uses `IP` for development of compact list item, as it were.
But he has to remember line 2591 or the paragraphs will run together in
an almost undifferentiated way.
Having the non-list-related paragraphing macros (so, `P`, `LP`, `PP` and
`HP`) automatically terminate all active lists _would_ mess with the
following hypothetical (and abbreviated) redraft of the foregoing.
.LS definition 1
.TP
.B BASH_COMPAT
.RS
The value is used to set the shell's compatibility level.
.RE
.TP
.B GLOBSORT
.RS
Controls how the results of pathname expansion are sorted.
.P
If set,
a valid value begins with an optional
.IR + ,
which is ignored.
.RE
.LE
> And in general, it would be a bad idea to leave too many unterminated
> LS, so why promote that? Let's force users to terminate their stuff.
I don't think I'd offer that as a selling point--man page authors are
grumpy enough about having to do their jobs as it is. But an auxiliary
advantage might be that you can teach text editors to match `LS` and
`LE` pairs the way they match braces, which can be helpful in drafting.
> Yup! :)
Hooray! Thanks for your support.
At 2026-05-08T16:43:46-0700, Stephen Gildea wrote:
> > Why not let the man(7) package handle the tedium for you?
>
> Indeed. As a manual author, I'm happy to see the manual-authoring
> language expand with more high-level constructs. A richer semantic
> language it makes it easier to write man pages that look good with
> groff without having to resort to low-level troff commands that don't
> work with other manual processors.
I don't want to get carried away with extensions. First, most people
won't use them. Second, I find the semantically oriented mdoc(7) macro
language too big. (I have other gripes with it as well.)
> I am also pleased to see you thinking about how to better map
> man-macro constructs to HTML and CSS. I welcome a way to
> create lists that know they are lists.
We'll see if my cogitation is equal to the task. :)
> > What do you think? If I build it, will you come? ;-)
>
> The problem with adding new macros is that authors then cannot
> use them without breaking other formatters.
Ah, but here I've attempted to be clever.
Recall (a) what other formatters do with unrecognized macro calls and
(b) the specified synopses. Dropping the explanations, they are as
follows.
.LS {definition|itemized|enumerated} [compactness [indentation]]
.LE
Observe that _none of the macro arguments are formatted text_.
Therefore, when a formatter that doesn't support them encounters them,
there will be no failure to deliver the content of the page. Your page
content might spread vertically more than you'd like, or it might suffer
suboptimal HTML markup (as it does today), but the content remains.
Further, I rely only on existing macros of long pedigree to present list
item content: `IP`, `TP`, and `LP`/`PP`/`P`, which all date back to 1979
or 1980.
Migrating will demand more than a negligible effort only of man page
authors who nest these lists; they'll have to manually recover the
nesting structure that they flattened/discarded when composing the page,
and by using `LS`/`LE`, they can preserve it henceforth.
But that's the smallest of the three man page audiences I perceive for
this feature.
The next larger group is those who use `.PD 0` and `PD` but don't nest
their lists. They need only do this:
$ sed -i -e 's/^\.PD 0/.LS FIXME 1/' -e 's/^.PD$/.LE/' mypage.man
...then make one pass over the document, replacing the "FIXME" with
"definition", "itemized", or "enumerated" as appropriate.
The last and largest group is those who don't even attempt today to
render lists compactly, or overcome the existing limitations of groff
man(7)'s translation to HTML. They'll adopt the new feature on their
own time table, following the trail blazed by the first two groups.
> In particular, I want my pages to look good with mandoc. If Ingo
> comes along, I'm in.
I'm less worried about Ingo rejecting this idea--in fact, he's been
strident about the importance of any macros added to man(7) _or_ mdoc(7)
not taking formattable text as arguments--than I am about mandoc(1)'s
support for the `MR` extension (which he already committed years ago[1])
making it into a release.[2]
This proposal is gentler. Even if mandoc(1) takes a long time to grow
support for `LS`/`LE`, people using it will not be deprived of content.
Anyway, I can't cast stones about slow release cycles. Not yet. We'll
see if I manage to get groff 1.25 out in July, and 1.26 in December, as
I've planned.[3]
> Yes, quote away.
Thanks!
Regards,
Branden
[1]
https://cvsweb.bsd.lv/mandoc/man_term.c?rev=1.243&content-type=text/x-cvsweb-markup&sortby=date
[2] `MR` breaks the aforementioned rule, but I didn't think there was
any better alternative. Updating man page cross references needs to
be a robotic process, such that people can just:
$ sed -i \
-e 's/^\.[BI]R \([^ ]\+\) (\([[:alnum:]_]\+\))$/.MR \1 \2/' \
-e 's/^\.[BI]R \([^ ]\+\) (\([[:alnum:]_]\+\))\(.\+\)/.MR \1 \2 \3/' \
doc/bash.1 ./lib/readline/doc/history.3 ./lib/readline/doc/readline.3
...for example.
[3] https://lists.gnu.org/archive/html/groff/2026-03/msg00046.html
signature.asc
Description: PGP signature
