Re: TAB character in groff output

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3138 bytes --]



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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]