Hi Branden, > Date: 2026-08-23 11:44:51-0500 > From: "G. Branden Robinson" <[email protected]> > > [looping in groff list because Alex brought to my attention an item of > work on the new man(7) `LS` and `LE` macros that needs to be done] > > Hi Alex, > > At 2026-08-23T17:06:16+0200, Alejandro Colomar wrote: > > > Date: 2026-08-23 09:16:22-0500 > > > From: "G. Branden Robinson" <[email protected]> > > > At 2026-08-23T15:55:29+0200, Alejandro Colomar wrote: > > > > > From: "G. Branden Robinson" <[email protected]> > > > > > > Do you know what's wrong? > > > > > More or less. It turns out to be damned hard to balance the > > > > > requirements of (1) Automake maintainer mode; (2) building from > > > > > Git repository checkouts; and (3) building from distribution > > > > > archives. Bruno Haible has been helpful in finding scenarios > > > > > that don't work. > > > > > > > > > > https://lists.gnu.org/archive/html/groff/2026-08/msg00039.html > > > > > > > > Hmmmm, now it rings a bell. bootstrap said something about > > > > configure with maintainer mode, but I ignored that, since I had > > > > never used maintainer mode. > > > > > > Right. I introduced that very recently during the RCs for 1.25.0, > > > because it seemed necessary. But as shown, Bruno has proposed > > > patches ripping it back out. > > > > > > I'm pretty frustrated with Automake's lack of explicit support for > > > building from Git working copies. Or maybe it's brilliantly > > > documented somewhere I haven't seen yet... > > > > I dislike autotools for that and other reasons. > > Autoconf, Automake, and Libtool, the collective "autotools", are all > strongly distinguishable in purpose.
I guess if you deal with them enough, you get to distinguish them.
In shadow-utils, where we have an autotools-based build system, I
consistently avoid to learn it. I leave it up to the other maintainers
and the distro maintainers to keep it working. I only report the issues
to them. To me, it'd be easier to wipe it all and write a Makefile from
scratch than learning the tools. The day I have to maintain that, I'll
probably do so. But distro maintainers don't want that, and so they
keep helping maintain it.
> Autoconf is a brilliant idea, very
> well executed. I suspect that many of its its detractors possess a
> constellation of negative traits:
>
> 1. They're not terribly competent at writing portable shell scripts;
I believe I'm quite competent writing shell scripts. :)
> 2. they refuse to understand the very simple principle of operation
> of the m4 macro language; and
I have the 2nd negative trait, though.
> 3. they refuse to believe that the variety of possible deployment
> environments is as wide as it is.
I acknowledge this. However, some people refuse to believe that
hand-crafted makefiles can also handle quite different environments too.
I believe makefiles can do that just fine. It's a matter of how much
makefile code you write.
In the Linux man-pages project, we have 120 kB of makefiles.
$ find share/mk/ -type f | xargs wc -c GNUmakefile | tail -n1
119125 total
I believe that a set of makefiles that would handle all of the targets
of a project like groff wouldn't take much more than that. It might be
a few hundred kB. If it's well organized, it can be maintainable.
Because the makefile language is so simple, bugs are easy to spot and
fix, compared to autotools (possibly automake, but I can't distinguish
them enough).
[...]
>
> I've encountered CMake. It burned me far worse than the Autotools ever
> have. In my view, rather than being a toolkit with which you can manage
> your project's build system to your own specifications--meaning that you
> can _understand_ it--it's a gigantic, baroque DWIM engine that permits a
> software project to outsource their build system engineering to CMake's
> maintainers.
Oh, yeah, I agree with everyone here. CMake is way worse than
autotools. autotools is the least evil of the non-pure-makefile build
systems.
> As always with outsourcing, that'll work great--and managers will love
> it--until it doesn't.
>
> And when it doesn't, people will stumble around, blinking and wondering
> where to find the expertise they'll need.
>
> > For groff(1), writing a portable hand-written Makefile might be too
> > hard to write.
>
> I saw what we had before. Bertrand Garrigues did us an unquestionable
> service in porting groff to Automake back in 2013/4.
>
> > But for the man-pages, I love the hand-written Makefile we have.
>
> I, too, love sticking with pure make(1) anywhere I can. POSIX Issue 8
> make(1) really allows the tool to shine.
>
> I nurse a glimmer of hope that the *BSD Make people can be pressured/
> bribed/shamed into supporting pattern rules at long last, and then we'll
> finally get as close to world peace as is possible.
>
> https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/doc/doc.am?h=1.24.1#n310
>
> That's an exhibit of an extremely stupid, and extremely old, problem
> that I defy any BSD partisan to defend.
>
> > I'm still waiting for GNU Make to make a new release, and then be able
> > to get rid of the mandatory -R, but other than that, it works quite
> > nicely.
>
> Hmm, no release since 4.4 on Halloween 2022. Yeah, they might be due.
Yup, I've been pinging Paul a few times in the last years. But I gave
up last year.
> > Yup; I don't like using tarballs. It's much easier to just check out
> > git HEAD. :)
>
> Yes, but the tarballs get tested in a greater diversity of environments.
> While I keep git HEAD "green"--I don't "git push" unless "make
> distcheck" runs successfully--that applies only to my personal
> development environment. groff doesn't have a CI infrastructure.
>
> The build system is the thing that consistently gives us the most pain
> when trying to firm up a release. So right now you are pulling on HEAD
> at its most fragile, ironically. The code quality should be good, _if_
> you can get the build to completion.
I'm happy to uncover those bugs; it's not a problem.
[...]
> > diff --git i/man/man5/tunables.conf.5 w/man/man5/tunables.conf.5
> > index 91bb6b81cb85..835c409eb074 100644
> > --- i/man/man5/tunables.conf.5
> > +++ w/man/man5/tunables.conf.5
> > @@ -89,9 +89,10 @@ .SS Filters
> > Filters limit the tunables following it.
> > The effects of a filter are terminated by
> > any of the following:
> > +.P
> > +.LS itemized 1
> > .IP \[bu] 3
> > The end of the file.
> > -.PD 0
> > .IP \[bu]
> > The end of an included file.
> > .IP \[bu]
> > @@ -100,7 +101,7 @@ .SS Filters
> > directive.
> > .IP \[bu]
> > A new (possibly empty) filter.
> > -.PD
> > +.LE
> > .P
> > The syntax is:
> > .P
> >
> > I had to add that P paragraph so that there's a blank before the list.
> > That's a bit unusual, since that would technically be an empty
> > paragraph; or maybe we can consider that paragraph to be the entire
> > list, but that's unusual in man(7). That said, I'm fine with that.
> >
> > What do you think?
>
> I agree that it looks a little funny; if one imagines the `LS` call as
> not being there at all, it looks truly redundant, and "mandoc -T lint"
> will likely complain about it.
>
> However, you have to remember that *roff documents are not truly
> block-structured. mandoc(1) really badly wants them to be, so it
> pretends that they are, and that sometimes leads it to jump through
> hoops...or to arguments between groff and mandoc maintainers. ;-)
>
> In *roffs, paragraphing macros mean "break for paragraph here", not
> "paragraph opens here".
True.
> So, in the foregoing, given that you _want_ inter-paragraph spacing
> before you start the compact list, the "isolated" `P` makes perfect
> sense. I think it would be unwise to force a compact list to not be
> compact prior to its first item, because doing that would foreclose the
> following sort of layout.
Agree.
> (But I see a complementary problem.)
>
> $ cat ATTIC/inline-compact-list.man
> .TH foo 1 2026-08-23 "groff test suite"
> .SH Name
> foo \- frobnicate a bar
> .SH Description
> This is my man page.
> There are many like it,
> but this one is mine.
> People should read more about
> .LS itemized 1 4n
> .IP \[bu]
> bash
> .IP \[bu]
> m4
> .IP \[bu]
> make
> .P
> .LE
Why not this?:
.LE
.P
> and learn what these tools can do for them.
>
> $ nroff -rLL=72n -man ATTIC/inline-compact-list.man
> foo(1) General Commands Manual foo(1)
>
> Name
> foo - frobnicate a bar
>
> Description
> This is my man page. There are many like it, but this one is mine.
> People should read more about
> • bash
> • m4
> • make
>
> and learn what these tools can do for them.
>
> groff test suite 2026‐08‐23 foo(1)
>
> So there is a post-compact list space challenge. You don't want an
> "empty" `IP` call prior to the `LE`--that will cause unwanted
> indentation of "and learn...".
You might use compactness keywords:
.LS itemized precompact
You could have 'precompact', 'postcompact', 'compact', and 'noncompact'
(feel free to use names that aren't so terrible).
> Maybe `LE` needs to accept an argument applying post-list space (and
> suppress it if the argument absent).
>
> And maybe `LS` needs to accept another argument applying pre-list space
> (and suppress it if the argument is absent).
>
> I'll dig into this. I might switch those defaults around; the objective
> is to have `LS` and `LE` slot into existing man(7) documents as
> unobtrusively as possible. As the "NEWS" file says:
>
> 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.
>
> Another governing principle is "man(7) document authors should not have
> to use *roff requests".[3]
>
> groff_man_style(7):
>
> Portability
> ...
> In roff systems, elemental functions called requests and escape
> sequences control formatting operations. A request appears on a
> control line. An escape sequence starts with a backslash (\) and
> can appear almost anywhere. However, use of roff requests (apart
> from the empty request “.”) risks poor rendering when a page is
> processed by non‐roff formatters that attempt to interpret page
> sources. (Historically, this was commonly attempted for HTML
> conversion.) Many of these programs don’t interpret the full roff
> language (let alone extensions): they may be incapable of handling
> numeric expressions, control structures, or register, string, and
> macro definitions, causing a document’s contents to be omitted or
> presented incomprehensibly. If your document uses formatter
> requests, or escape sequences not shown below, it accepts
> responsibility for restoring formatter state to what the man macro
> package expects.
>
> So I'll see what I can figure out with those lodestars in sight.
>
> An idea involving only compact lists and `sp` and `ns` requests is
> forming already. I think I might profitably use them in the `LS` and
> `LE` macro definitions, respectively.
>
> The foregoing example will likely spawn an automated test.
>
> Thanks for putting groff pre-1.25 to the test!
:-)
Have a lovely night!
Alex
>
> Regards,
> Branden
>
> [1] https://www.irif.fr/~treinen/publi/slides/minidebconf18.pdf
> [2]
> https://archive.org/details/bitsavers_attunix7thersManualSeventhEditionVol21983_34117955
>
> [3] There are exceptional circumstances, like overcoming problems that
> AT&T troff and man(7) lacked mechanisms for solving, or providing
> "fallbacks" for pic(1) or eqn(1) input. And I use `br` and `ne`
> requests in groff's man pages for "stranded line management", a
> problem that affects only paginated documents--that's a problem
> mandoc(1) is explicitly designed not to ever deal with.
--
<https://www.alejandro-colomar.es>
signature.asc
Description: PGP signature
