Hi DJ,

> Date: 2026-08-06 11:33:47-0400
> From: DJ Delorie <dj@redhat.com>
>
> Alejandro Colomar <alx@kernel.org> writes:
> > A few minor comments below.
> 
> I'll defer a v5 until we finish discussing...

Good.  :)

> >> +The file may also contain
> >> +.IR filters ,
> >> +which limit the tunables following it,
> >> +up to the end of the file
> >> +(or end of the included file,
> >> +or start of a new included file)
> >
> > I'd append within the parentheses:
> > 	, whichever comes first
> 
> "first"?  Or "next"?
> 
> >> +or a line with only
> >> +.B []
> >> +on it.
> >
> > So, this is like an end-all-filters directive, right?
> >
> > I wonder something: Does a filter end previous filters, or do they
> > compound until a [] ends them all?
> 
> There is only ever one filter active at a time.  It stops being the
> active filter when another filter is encountered, or the current file
> ends, or an include directive.  An empty filter spec (i.e. "[]") is a "no
> filters" filter.  It acts as a "new filter" for the purpose of ending
> the previous filter, but does not specify a new filter, so no new filter
> is active after that.
> 
> If you can get that into five words or less, you win ;-)

Hmmmm, let's see.  I couldn't do it in five words, but how about this
schematic approach?

	The file may also contain
	.IR filters ,
	which limit the tunables following it,
	The effects of a filter are terminated by
	any of the following:
	.IP \[bu] 3
	The end of the file.
	.IP \[bu]
	The end of an included file.
	.IP \[bu]
	An
	.B include
	directive.
	.IP \[bu]
	A new (possibly empty) filter.

> 
> >> +The syntax is:
> >> +.P
> >> +.in +4n
> >> +.EX
> >> +.RI [ filter : pattern ]
> >
> > Since '[', ':', and ']' are literal, let's put them in bold.  Thus, BI.
> 
> Done.

Since a filter can be empty, we should document that.  If we document
that 'filter:pattern' is optional, it'd be [[filter:pattern]] (with the
appropriate formatting differences: the inner '[' wouldn't be bold).
However, that's likely to be confusing, so let's document that
separately:

	A filter can also be empty:
	.BR [] .
	Such a filter has no effects.


Have a lovely day!
Alex

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