Re: [PATCH v2] man*/: ffix (migrate to `MR`)

[Alejandro Colomar]

Hi Branden, Ingo,

On 2023-08-01 16:12, G. Branden Robinson wrote:
> At 2023-08-01T15:35:10+0200, Alejandro Colomar wrote:
>> [CC += groff]
>>
>> Hi Jakub, Branden,
>>
>> On 2023-08-01 03:31, G. Branden Robinson wrote:
>>> Hi Jakub,
>>>
>>> At 2023-08-01T00:16:41+0200, Jakub Wilk wrote:
>>>> * G. Branden Robinson <g.branden.robinson@gmail.com>, 2023-07-31 12:52:
>>>>> Use the man(7) macro `MR`, new to groff 1.23.0,
>>>>
>>>> Given that this version of groff was released approximately
>>>> yesterday¹, this is very premature.
>>>>
>>>> NACK from me.
>>>>
>>>> ¹ More precisely, about a month ago.
>>>
>>> 5 July UTC, to be (a little) more precise.
>>>
>>> Linux man-pages release scheduling is Alex's prerogative, not mine.
>>
>> I just made a new release, so that we have plenty of time for the next
>> one.
> 
> I saw that, and thought, "ooh, that's a bit quick--surely he didn't..."
> 
> And no, you didn't (include the giant `MR` migration patch).

Not yet.  I hope to have MR support in mandoc(1) before I release that.
Ingo, would you mind?  :)

> 
> I trust the announcement didn't give Jakub a heart attack...
> 
>> I don't expect to make a new one in months.  :)
> 
> I can't cast stones about release frequency, that's for sure.
> 
>>> He asked me (a long time ago) to deliver this after groff 1.23.0 was
>>> released.  That is what I have tried to do.
>>
>> Thanks!
> 
> A pleasure.  Not merely to promulgate my "baby", but also to get a lot
> of that cargo-culty stuff around tables cleaned out of the Linux
> man-pages.  Tidy man(7) sources make for happier documentation writers
> who have an easier time getting what they want.

Yup!

> 
>>> groff 1.22.4 man(7) does not support the `MF` string (see below).
>>> That could be backported too, but there seems no point before there
>>> is a concrete need.
>>>
>>>> After applying the patch, the man page references are typeset in
>>>> italics,
>>>
>>> For great justice!  (See below.)
>>
>> Still I think this should be documented in our commit.  Would you
>> please send a paragraph (and the position at which you'd place it)
>> with which I can amend the commit?
> 
> Yes.  That was on oversight on my part; I was scrubbing out all font
> changes (with "-P -cbou") because my concern was with unexpected changes
> to adjustment and hyphenation.  The style change for man page topics
> (from bold to italics) was a "known factor" (to me).

Would you mind sending an updated commit message?

> 
> Also, I saw that some "=3D" quoted-printable ugliness got into the
> commit message, buried inside groff command-line options where people
> unaccustomed to writing them might not mentally screen out the noise.

Heh, I noticed some weirdness about it, but it happened to be after a
-rCHECKSTYLE, so it seemed like it could be some improvements that you
had applied upstream to CHECKSTYLE.  =3 definitely made sense to that
register.

> 
> Please double-check for that before pushing to kernel.org.

Please send one that I don't need to modify.  I don't like modifying
other's stuff, in case I break it.  :)

> 
>>>> which is ugly
>>>
>>> See my recent exchanges with Lennart Jablonka on this list.
>>>
>>>> and against man-pages(7) recommendations.
>>
>> Well, we should update those to use MR.
> 
> And man(7) too, I guess.  What do you think?

I want to kill that page.  Please have a look at it, take anything
good that it has for groff_man{,_style}(7), and ping me when I
should sharpen the scythe.  ;)

Cheers,
Alex

> 
>> Branden is right that italics is more appropriate.  He has defended
>> that position very well, so I'll let him defend that point.  The
>> conversation to which he referred was:
>>
>> <https://lists.gnu.org/archive/html/groff/2021-08/msg00034.html>
> 
> Yes.  That message includes Ingo's acknowledgement of my historical
> analysis, which can be found in the parent message.
> 
> https://lists.gnu.org/archive/html/groff/2021-08/msg00023.html
> 
> But we had a fairly wide-ranging discussion, much of which will not be
> of interest to someone who updates to man-pages 6.6.6 🤘, sees italics
> appearing where they had been accustomed to bold, and flies into a rage.
> 
> I reckon the virtuous thing to do would be to write an ms(7) article
> about the history of cross reference styling in Unix man pages.  I
> regret that my conjecture about _why_ the GNU/Linux community shifted
> the style (VGA text mode limitations) remains unsupported by testimonial
> accounts from people who deliberately made this change.
> 
> Maybe this change will attract the attention of those folks.  Even if
> they get angry with me in the process, I'm willing to risk being called
> out as the price of improving the historical record.  :)
> 
>> But we should document in the commit message that the MR default
>> implies a behavior change in our pages.
> 
> Yes.  And it's not hard to offer MANROFFOPT="-dMF=B" as an initial
> workaround.  One could throw this into one's shell startup file, but
> only man-db man(1) honors that variable.  The more systemic approach is
> to edit the site configuration file for groff man(7).
> 
> Files
> [...]
>    /usr/share/groff/site-tmac/man.local
>           Local changes and customizations should be put into this file.
> 
> (Debian symlinks this to "/etc/groff/man.local".)
> 
> groff_man_style(7) offers further suggestions for content, based
> (mostly) on feedback we've often seen over the years.
> 
>             .\" Use narrower indentation on terminals and similar.
>             .if n .nr IN 4n
>             .\" Put only one space after the end of a sentence.
>             .ss 12 0 \" See groff(7).
>             .\" Keep pages narrow even on wide terminals.
>             .if n .if \n[LL]>78n .nr LL 78n
>             .\" Ensure hyperlinks are enabled for terminals.
>             .nr U 1
> 
> Debian's groff 1.23.0 packages in testing and unstable in fact already
> enable the last (thanks, Colin!).
> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature