On Fri, Aug 22, 2025 at 05:09:42PM +0200, Ingo Schwarze wrote: > Hello Alejandro,
Hi Ingo,
> 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.
Thanks! I'm not very used to tbl yet, which is why I've avoided
questioning most of the existing tbl code so far. I've considered it
something that just works and didn't touch it unless strictly necessary.
It seems I need to revise that.
> 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.
Yup, I'll extend the patches to wherever they make sense.
> > 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.
Thanks!
> 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{
Would you mind providing two separate patches for the logically
different issues, with commit messages?
Cheers,
Alex
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
