Hello Alejandro,
Alejandro Colomar wrote on Thu, Aug 21, 2025 at 09:58:01PM +0200:
> alx@debian:~/tmp$ cat ./man-pages.7
> .TH man-pages 7 2025-08-21 "Linux man-pages (unreleased)"
> .SH NAME
> man-pages \- conventions for writing Linux man pages
> .SH DESCRIPTION
> The following table lists some preferred terms to use in man pages,
> mainly to ensure consistency across pages.
> .P
> .TS
> l l l
> ---
That's terrible style.
Using "-" in the tbl(7) layout only makes sense when the same layout
line also contains at least one cell that receives data.
A horizontal line that extends across the table as a whole
should *not* get its own layout line but can be specified purely
in the data section of the table. That's not only more robust,
but also results in source code that is easier to read and maintain.
The above is not just convention, but also makes sense logically
and is related to the root cause of your earlier blank line woes.
A table line that receives no data should not be specified in the
layout because every layout line requires at least one data line,
so a layout line receiving no data is an oxymoron, and that logical
contradiction is precisely what causes the issue of needing a
blank line in the first place.
Note that in a layout line that only contains "-" for *some* cells,
while at leat one cell receives data, the problem does not occur
because the coressponding data line(s) do contain actual data
for at least one cell, so they are not blank.
I'm appending a patch below fixing the style of the table.
When applying it, please also check whether the same style issue
occurs in other tables in the file or in other files in the
repository. That should be easy by searching for /^--*$/
and /^__*$/ and /^==*/, or something like that.
> l l ll.
That looks broken to me.
This layout line specifies a fourth column, but none of the
data lines contains a fourth cell.
That's also fixed in the patch below.
> I suspect the glitch in the separating line has something to do with the
> diagnostic.
No, it has nothing to do with the diagnostic.
It is caused by the erroneous "l l ll" layout line.
Yours,
Ingo
diff --git a/man/man7/man-pages.7 b/man/man7/man-pages.7
index fa60e2f8f..bc7bc2426 100644
--- a/man/man7/man-pages.7
+++ b/man/man7/man-pages.7
@@ -845,11 +845,9 @@ The following table lists some preferred terms to use in
man pages,
mainly to ensure consistency across pages.
.ad l
.TS
-l l l
----
-l l ll.
+l l l.
Term Avoid using Notes
-
+_
bit mask bitmask
built-in builtin
Epoch epoch T{
