Re: 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: 5776 bytes --]

Hi Branden,

> Date: 2026-08-23 09:16:22-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> Hi Alex,
> 
> At 2026-08-23T15:55:29+0200, Alejandro Colomar wrote:
> > > From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> > > > 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.  For groff(1), writing
a portable hand-written Makefile might be too hard to write.  But for
the man-pages, I love the hand-written Makefile we have.  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.

[...]
> I do _not_ get such errors.  Shell session attached.
> 
> ...but I'm building _from the release candidate archive_, as I advised
> you to do.

Yup; I don't like using tarballs.  It's much easier to just check out
git HEAD.  :)

> > > Build finished successfully for me in about 60 seconds.
> > 
> > Out of curiosity, where did you get those timestamps from?  Does your
> > history file store them?
> 
> Yes.  That's simply the output of Bash's "history" built-in.  I chopped
> off the command numbers and removed irrelevancies like "ls".

Oh, I don't have that!

	$ history | tail -n1
	 1997  history | tail -n1

After checking `help history`, I now realize it has a HISTTIMEFORMAT
variable for doing that.

I've added it now to my bashrc:

	alx@devuan:~/src/alx/config/main$ git show -U0
	commit 9b64c78f797fc3abab83148b24143402a5d2a839 (HEAD -> main)
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-08-23 16:53:59 +0200

	    bash: HISTTIMEFORMAT: Add variable
	    
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/etc/bash.bashrc b/etc/bash.bashrc
	index af974d211e14..f2f7772c8e51 100644
	--- a/etc/bash.bashrc
	+++ b/etc/bash.bashrc
	@@ -2,0 +3 @@ export GPG_TTY="$(tty)";
	+export HISTTIMEFORMAT="%F %T%z ";

I've been wanting that for a long long time!  It's good to know it
exists.  :)

> > Using groff from git HEAD, I see the list as this:
> > 
> > 	$ cat ls.man 
> > 	.TH a s d f
> > 	.SH test
> > 	foo
> > 	.LS
> > 	.IP \[bu] 3
> > 	bar
> > 	.IP \[bu]
> > 	baz
> > 	.LS
> > 	.P
> > 	qwe
> > 	$ /opt/local/gnu/groff/20260823_master/bin/groff -man -Tutf8 ./ls.man 
> > 	a(s)                                                                        a(s)
> > 
> > 	test
> > 	     foo
> > 
> > 	     •  bar
> > 
> > 	     •  baz
> > 
> > 	     qwe
> > 
> > 	f                                       d                                   a(s)
> > 
> > Is this intended?  I thought it would imply PD 0.
> 
> Yes, it's intended.  If you want the list compact, you have to say so.
> 
> Also, you need to say what kind of list you're presenting.
> 
> groff_man(7):
>      .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.
> 
> > 	.LS
> 
> Say instead:
> 
> .LS itemized 1

Oh, yeah, I forgot to RTFM.  :-)

Here's an interesting thing (it might be okay, just noting it):

	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?


Cheers,
Alex

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

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