Hi Alejandro,
sorry for getting distracted and returning late to the party.
Alejandro Colomar wrote on Tue, Aug 02, 2022 at 05:14:47PM +0200:
[...]
> $ make lint-man-mandoc
> LINT (mandoc) tmp/lint/man7/spufs.7.lint-man.mandoc.touch
> mandoc: man7/spufs.7:748:7: WARNING: tab in filled text
My general recommendation for this warning is:
* If the tab is used for a good reason (for example, if it is
in a multi-line code sample that becomes more readable with
good indentation), wrap the whole code sample in no-break
mode. In mdoc(7), that usually means .Bd -unfilled (if
the sample uses markup) or .Bd -literal (otherwise).
In man(7), .EX (more semantic) or .nf (more portable)
can be used.
* If the tab is not used for a good reason, just get rid of the tab.
Quite often, that can be achieved in a very simple way.
In this case, it is blatantly obvious there is absolutely no reason
whatsoever for using a tab.
Arguably, the whole example should be deleted because it shows
nothing that is complicated enough to require an example.
All parts of the line are completely trivial.
Below "Mount options", a sentence is missing that in fstab(5), the
fs_spec field needs to be set to "none" and the fs_vfstype field to
"spufs" - most users would probably expect both anyway, but being
explicit is better. I don't think the fs_freq and fs_passno need to
be mentioned, it is clear without saying so that only 0 makes sense
for "none" filesystems.
Remember, it is very bad style to provide EXAMPLES *instead* of
documentation because that leaves the user wondering which parts of
the example are crucial and which arbitrary (e.g., the /spu path),
and why the example was written as it was.
> In the following code:
>
> $ sed -n 745,749p <man7/spufs.7
> .SH EXAMPLES
> .TP
> .IR /etc/fstab " entry"
That's terrible style, too. Manual pages should use complete sentences
and correct English punctuation, for reasons of both clarity and style,
for example:
.SH EXAMPLES
To automatically
.MR mount 8
the SPU filesystem when booting, at the location
.I /spu
chosen by the user, put this line into the
.MR fstab 5
configuration file:
.EX
none /spu spufs gid=spu 0 0
.EE
Just using single spaces is perfectly fine: KISS.
> I think I'll fix it with tbl(1).
That's a very bad idea: tbl(1) should be used very sparingly
and only when there is real tabular data und very strong reasons
to present it as a table. Even when you actually need to present
tabular data, make an effort to avaoid bringing in tbl(1) if at
all possible.
The reason is that tbl(1) is a strongly presentational language
providing no semantic information whatsoever, with the usual
consequence of coming out beautifully in PDF output but usually
rendering *terribly* to HTML with groff and not very well even with
mandoc. Besides, using tbl(1) in manual pages is more fragile and
less portable than using pure man(7) code.
Look at this fiasco:
$ groff -t -man -Thtml man7/spufs.7
[...]
<h2>EXAMPLES
<a name="EXAMPLES"></a>
</h2>
<p style="margin-left:9%; margin-top: 1em"><i>/etc/fstab</i> entry</p>
<p align="center" style="margin-top: 1em"><img src="grohtml-88313-1.png"
alt="Image grohtml-88313-1.png"></p>
<h2>SEE ALSO
$ mandoc -Thtml man7/spufs.7
<section class="Sh">
<h2 class="Sh" id="EXAMPLES"><a class="permalink"
href="#EXAMPLES">EXAMPLES</a></h2>
<dl class="Bl-tag">
<dt><i>/etc/fstab</i> entry</dt>
<dd>
<table class="tbl">
<tr>
<td>none</td>
<td>/spu</td>
<td>spufs</td>
<td>gid=spu</td>
<td>0</td>
<td>0</td>
</tr>
</table>
</dd>
</dl>
</section>
<section class="Sh">
Imagine being blind and then consider both HTML code snippets from
the perspective of accessibility.
Yours,
Ingo
