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). 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. > > 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). 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. Please double-check for that before pushing to kernel.org. > >> 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? > 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
Attachment:
signature.asc
Description: PGP signature
