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@xxxxxxxxx>, 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
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
