Re: TAB character in groff output

[Alejandro Colomar]

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/>

OpenPGP_signature
Description: OpenPGP digital signature