Re: TAB character in groff output

Re: TAB character in groff output

[Alejandro Colomar]

[-- 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 --]

Re: TAB character in groff output

[Alejandro Colomar]

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

Hi Ingo,

On 8/16/22 00:01, Alejandro Colomar wrote:
> 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>

Meh, I had two typos.  One was missing parentheses, which I fixed in a 
subsequent commit.  The other was that I misspelled your surname; I 
can't fix that, sorry.  I should paste it next time.  My German seems to 
be rusty.  :/

Cheers,

Alex

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: TAB character in groff output

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Tue, Aug 16, 2022 at 12:01:40AM +0200:

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

Yes, almost certainly.

I'm not enthusiastic about it, but given that groff is going ahead
with it, it is clearly better to support it than to not support it.

The most likely timing for adding support is shortly after the next
groff release.  Before the groff release, it isn't urgent at all
for obvious reasons.

Right now, i'm slowly working through inconsistencies that popped up
in the mandoc test suite after regenerating the expected output with
-current groff.  Getting that sorted out before the groff release would
be ideal because some of these issues might be regressions in groff
(like the groff_mdoc(7) prologue regressions i reported earlier).
What makes this work a bit tedious is that apparently, not all changes
that popped up are groff regressions.  For example, for the second
change is i looked into, it appears behaviour is mostly consistent
between GNU, Heirloom, and Plan 9 roff and it is mandoc that is off,
so there is no need to report that here and i'm instead fixing mandoc
(it is related to literal tab characters in filled text).

Eleven new differences are left right now and i suspect these
are likely due to at least four and probably not more than eight
different changes; the exact number of issues is not clear yet.
Most are differences in vertical spacing, but in different contexts, so
there is likely more than one vertical spacing issue.  One difference
concerns paragraph breaking, one concerns horizontal spacing, and
two concern the scope of font markup.

Yours,
  Ingo

Re: TAB character in groff output

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 352 bytes --]

At 2022-08-16T00:01:40+0200, Alejandro Colomar wrote:
> 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

Yes. :D

But waiting a "few years", oof!  Well, it'll come sooner if we can get
our official maintainer/release manager back...

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]