Hi Branden, G. Branden Robinson wrote on Sat, Jul 16, 2022 at 10:38:47AM -0500: > At 2022-06-18T21:05:09+0200, Ingo Schwarze wrote:
>> The header line does not contain a cross reference, so there is no >> justification for marking it up in the same way as a cross reference. > I think there is, because that way the man page you are looking for > announces itself to your eyes in precisely the same typefaces you saw > when you read a cross reference to it. I think this eases recognition > and constitutes better ergonomics, but that's my opinion. I don't think the congruence between .TH and .MR you describe really matters. The name(number) syntax stands out so much in English text that is is instantly recognizable no matter the typeface. If you really think the congruence matters, i understand your argument even less. In mdoc(7), this was always consistent: both .Dt and .Xr always render in roman font. By contrast, man(7) was much less consistent in the past: - man(7) always used roman font for .TH - For cross references, AT&T UNIX Sixth Edition used R(R) inside SEE ALSO and an inconsistent mixture of R(R), I(R), and I(I) outside SEE ALSO. - For cross references, AT&T UNIX Seventh Edition used R(R) inside SEE ALSO and I(R) outside SEE ALSO (as discussed on this list around August 4, 2021). - various man(7) pages from various projects also used bold face for cross references. You say it matters that .TH appears in the same font as the .MR it came from? Well, that won't be the case when linking from mdoc(7) to man(7) pages nor when linking from man(7) to mdoc(7) pages with your changes. The consistency in the header lines even decreases. [...] >> Finally, we are talking about a header line in the page margin. This >> is *not* something that should be emphasized by using italic or bold >> font. > I have to wonder where you get your evidence from sometimes. Ouch. I'm sorry you spent so much time on this claim. [...] > "Most". Describe your method of measurement. Looking at a smaller sample of books on my shelf, and finding only Stroustrup as a counter-example. It appears my sample was too small and my claim that using bold or italic typefaces in header lines is unusual is not true (I should really know Poisson statistics better *blush*). Your larger sample proves that practice varies widely. >> You might say: "Why do you bother? You are going to set \*(MF >> to R anyway on *BSD. So it makes no difference to you." >> And indeed, *if* you push through with .MR, that's exactly >> what i will do in groff on OpenBSD and in mandoc on all *BSDs, >> and in mandoc, MF=R will not even be optional but hard-coded. > Okay. It's free software. I don't think mandoc's users will be > distressed; you already deny them hyphenation True. > and a configurable line length. No longer true; mandoc supports both the -O width= argument, and even lets the manual page override that by the roff(7) .ll request. If the terminal window is narrower than 80 columns, it even reduces the default line length automatically, with no need for -O width=. [...] >> All the same, i prefer sane defaults over excentric defaults >> that need to be patched away, and i prefer common conventions >> to markup fragmentation. Surely you don't expect the font >> conventions for mdoc(7) .Xr and .Dd to change now, after >> three decades in production, > I don't expect _you_ to change it. Well, i'm also thinking about groff_mdoc(7). I usally strive for mandoc(1) -T ascii and -T utf8 output to be byte-for-byte identical to groff output. But when output from groff_man(7) is inconsistent with output from groff_mdoc(7), i usually decide to let mandoc(1) follow the mdoc(7) conventions for both languages, for consistency, and let the mandoc implementation of man(7) diverge from groff_man(7) so far as that cannot be helped. And then i patch the OpenBSD groff port to be consistent with itself and with mandoc, even if that makes it diverge from upstream groff. [...] >> You are aware that the syntax and semantics of .MR is completely >> identical to the .Xr macro that Cynthia invented 30 years ago? > How is that a bad thing? You spent another prong of this thread > derogating its design intensely. If you were designing man(7) from scratch, it would be a good design. I criticised the design of .MR for its lack of backward compatibility, not for any *intrinsic* design problems. >> Making it render differently also looks like a dubious choice >> to me, in addition to the topic of this mail. > The sources of your doubt seem to be to be your personal preference > backed up by unfounded assertions that are readily contradicted by > observation. True, you can consider my rash claim that bold and italic fonts it header lines are unusual disproven. But all the same, what you did here is copy the design of .Xr to .MR and then change the formatting of the macro such that even though both have exactly the same syntax, cross references look different between mdoc(7) and man(7). I still see no necessity for that inconsistency because man(7) wasn't very consistent in the past in that respect, so since you are copying the macro anyway, why not use the opportunity of also making the formatting consistent? I fear we are starting to go in circles, though. So if you think this is going nowhere, i'll use man.local as you suggested and live with the fact that cross references and header lines look inconsistent on systems other than OpenBSD. Yours, Ingo
