Re: TAB character in groff output

Alejandro Colomar <alx.manpages@xxxxxxxxx> · Tue, 16 Aug 2022 00:01:40 +0200

On 8/11/22 14:34, Ingo Schwarze wrote:
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.

I'll keep it for now.  What is trivial to some might not be so to others.

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.

Would you mind sending a patch?  This page is not something I'm very 
familiar with.

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.

Agree.

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 like it.  I applied a patch with exactly that (but .MR -> .BR; I'll 
still wait a few years before using that).  BTW, Branden, did you notice? :P

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=9249e0f0e9caf9da696e1a3830d2a104abc80591>

Ingo, is mandoc(1) planning to support .MR?

I think I'll fix it with tbl(1).

That's a very bad idea: 

[...]

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature

Description: OpenPGP digital signature