Follow-up Comment #4, bug#65101 (group groff):
> comment #2: > > Why are you doing this? > I said already. See comment #1. "I was pursuing my goal of consistent styling between rendered groff's own man(7) and mdoc(7) documents. In my opinion, it should be difficult to impossible for a person reading a rendered man page to tell which macro package was used for its composition." This is "what". Why do you consider "all the manuals must look the same, by force, regardless of what the authors have written" a goal? > > Should I expect mdoc to use four fonts > Why do you pick four, in particular? I hope you are not referring to "R, I, B, and BI" specifically. If so, you may benefit from a the following perspective. Because man is four-font and if you want all man and mdoc to be indistinguishable then you must do so by lowering mdoc to four fonts, because man is a glorified "hey give me \f(BI" system. (Sans the very-recent Xr analogues which you added.) > But to answer your question, no. I expect mainly to see: > > On terminals: > > mainly roman, bold, and italics > occasionally bold italics, for example in `Sh` and `Ss` where the font weight is already heavy (bold) > > On typesetters: > > as above, plus > Courier roman in displayed examples > Courier bold in displayed examples where input and output need to be distinguished So you do intend to lower the Nm and Cm and Fl fonts to B? Why? Do I need to say this is horrific? > I have yet to see good use cases for Courier italic or bold-italic in man pages. This is "I don't like this". IMO troff Pa should be CI. This would actually be pretty cool and consistent across nroff and troff but I can just set this in my manuals (or only for some renders) so this doesn't affect anyone else. > Nor will you see them in many man pages produced when AT&T and BSD Unix were going concerns, because back then you paid for your fonts by the typeface. At the time of Unix System III (1980), the only constant width font was upgright (Courier roman) and it bore the name "CW" because evidently no one foresaw that more than one style of constant-width face would ever be needed. And BSD troff didn't support even that; they were stuck on Ossanna troff for the C/A/T, which supported neither a constant-width face nor even proportional bold-italic. Why does this matter? How is this relevant? Are you producing a macro system for computers of the seventies or for those of today? Are you seriously suggesting that _because we didn't have this is the eighties, we should proactively choose to regress to the rendering of the eighties_, rather than continue to utilise the full spectrum of niceties provided to us by the modern free ecosystem? > > and have all the controls that make precise layouts possible stripped out because man doesn't have them? > I "stripped out" exactly one control; see below. I have no plans to remove any others. This was another riff on stripping down mdoc-rendered pages to look exactly like man-rendered ones, as is your stated goal. > > I never should've bothered reporting this after that time I posted about using Tn and you deleted it because you don't like it. > I changed the `Tn` default to stop altering the type size because doing so simplified other reforms I was making and because I consulted with mandoc(1) maintainer Ingo Schwarze, and he said that there did not seem to be a clear and well-established semantic meaning for it. It may be that his preference and/or *BSD tradition has neglected use of the macro. Schwarze is a puritan and mandoc simply doesn't work (be it simply broken because he never wrote a document that used them or active anti-support for many features that make writing, for example, tables and lists that fit within the rest of the manual or are correctly-spaced impossible) for a plurality of use-cases because he doesn't like them. Even his own mandoc-specific features are fundamentally broken sometimes. "Because Ingo said it" is worse than no justification at all. He doesn't like Tn, so it does nothing. Consider that because now it doesn't do anything (and it's hard to apply properly now that people don't typeset their manuals except for HTML, for which they use mandoc, which does nothing with them anyway), there is no incentive to use or even way to check how Tn works for new manuals. Give it 12 years (became default on OpenBSD in 2010) and wow no-one uses it and it's "useless" (-Tlint warns about Tn usage to delete it as "useless macro". which, you may notice, is _only useless because schwarze made it, against all historic implementations except the one that came in 4.3BSD-Reno_) so you should delete it in groff too. mdoc grows Tn in 4.4BSD-Lite1, and does unfortunately call it ".\" NS Tn macro - Trade Name Macro". Why? Typographical convention probably (trade names tend to be all-caps but you use them as normal words and not explicit acronyms so you want to set caps-but-sized-to-normal-letters to distinguish "this is an acronym" from "this is an all-caps noun", but uh-oh the latter is a semantic!). Doesn't really matter, because aside from all the usual pre-defined strings: $ grep -r tN README:.\" NS tN string (site) Trade Name Style doc:. as b1 \\*(tN\\*(tF doc:. as b1 \\*(tN doc-syms:.as b1 \&\\*(tNUNIX\\*(aa doc-syms:.\" . ie \\n(.$==0 \&\\*(tNBSD\\*(aa \\*(tNUNIX\\*(aa doc-syms:. ie \\n(.$==0 \&\\*(tNBSD\\*(aa doc-syms:. as b1 \&\\*(A\\n(aP\&\\*(tNBSD\\*(aa doc-syms:. as b1 \&\\*(tNBSD\\*(aa doc-syms:. if "\\$1"32v" \&Version 32V \\*(tNAT&T UNIX\\*(aa\\$2 doc-syms:. if "\\$1"v6" \&Version 6 \\*(tNAT&T UNIX\\*(aa\\$2 doc-syms:. if "\\$1"v7" \&Version 7 \\*(tNAT&T UNIX\\*(aa\\$2 doc-syms:. if "\\$1"V" \&\\*(tNAT&T\\*(aa System V \\*(tNUNIX\\*(aa\\$2 doc-syms:. if "\\$1"V.1" \&\\*(tNAT&T\\*(aa System V.1 \\*(tNUNIX\\*(aa\\$2 doc-syms:. if "\\$1"V.4" \&\\*(tNAT&T\\*(aa System V.4 \\*(tNUNIX\\*(aa\\$2 doc-syms:. if "\\$1"32v" \&Version 32V \\*(tNAT&T UNIX\\*(aa doc-syms:. if "\\$1"v6" \&Version 6 \\*(tNAT&T UNIX\\*(aa doc-syms:. if "\\$1"v7" \&Version 7 \\*(tNAT&T UNIX\\*(aa doc-syms:. if "\\$1"V" \&\\*(tNAT&T\\*(aa System V \\*(tNUNIX\\*(aa doc-syms:. if "\\$1"V.1" \&\\*(tNAT&T\\*(aa System V.1 \\*(tNUNIX\\*(aa doc-syms:. if "\\$1"V.4" \&\\*(tNAT&T\\*(aa System V.4 \\*(tNUNIX\\*(aa doc-syms:\&\\*(tNAT&T UNIX\\*(aa doc-syms:.ds Px \\*(tNPOSIX doc-syms:.ds Ai \\*(tNANSI doc-syms:. ds b1 \&\\*(tNIEEE Std\\*(aa1003.1-1988\\*(sV doc-syms:. as b1 (``\\*(tN\\*(Px\\*(aa'') doc-syms:. ds b1 \&\\*(tNIEEE Std\\*(aa1003.1-1988\\*(sV doc-syms:. as b1 (``\\*(tN\\*(Px\\*(aa'') doc-syms:. ds b1 \&\\*(tNIEEE Std\\*(aa1003.2 doc-syms:. as b1 (``\\*(tN\\*(Px\\*(aa'') doc-syms:. ds b1 \&\\*(tNIEEE Std\\*(aa1003.2\\*(sV doc-syms:. as b1 (``\\*(tN\\*(Px\\*(aa'') doc-syms:. ds b1 \&\\*(tNANSI C \\*(aaX3.159-1989\\*(sV doc-syms:. as b1 (``\\*(tNANSI C\\*(aa'') doc-syms:. ds b1 \&\\*(tNANSI C \\*(aaX3.159-1989\\*(sV doc-syms:. as b1 (``\\*(tNANSI C \\*(aa'') doc-syms:. ds b1 \&\\*(tNANSI C \\*(aaX3.159-1989\\*(sV doc-syms:. as b1 (``\\*(tNANSI C \\*(aa'') doc-syms:. ds b1 \&\\*(tNANSI C \\*(aaX3.159-1989\\*(sV doc-syms:. as b1 (``\\*(tNANSI C \\*(aa'') doc-syms:. ds b1 \&\\*(tNISO \\*(aa8802-3: 1989\\*(sV doc-syms:.\" . as b1 (``\\*(tNANSI C\\*(aa'') doc-syms:. ds b1 \&\\*(tNISO \\*(aa8802-3: 1989\\*(sV doc-syms:.\" . as b1 (``\\*(tNANSI C\\*(aa'') doc-nroff:.ds tN doc-ditroff:.ds tN \s9 Where they are used pretty much as-described; mdoc.7 says: ../man/man7/mdoc.7:.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX" ../man/man7/mdoc.7:.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." which I'd say is floundering for trying to come up with "get a smaller font with this". It doesn't actually do caps either. I haven't seen it actually used on a type name. But mdoc.samples.7 is, I'd say, the only page to _abuse them_: ../man/man7/mdoc.samples.7:.Tn "TROFF IDIOSYNCRASIES" ../man/man7/mdoc.samples.7:.Tn "THE ANATOMY OF A MAN PAGE" ../man/man7/mdoc.samples.7:.Tn "INTRODUCTION OF TITLE MACROS" . ../man/man7/mdoc.samples.7:.Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . ../man/man7/mdoc.samples.7:.Tn "MANUAL DOMAIN" ../man/man7/mdoc.samples.7:.Tn "GENERAL TEXT DOMAIN" ../man/man7/mdoc.samples.7:.Tn "PAGE STRUCTURE DOMAIN" ../man/man7/mdoc.samples.7:.Tn "PREDEFINED STRINGS" ../man/man7/mdoc.samples.7:.Tn "DIAGNOSTICS" ../man/man7/mdoc.samples.7:.Tn "FORMATTING WITH GROFF, TROFF AND NROFF" ../man/man7/mdoc.samples.7:.Tn "BUGS" ../man/man7/mdoc.samples.7:.Tn "ANSI C" ../man/man7/mdoc.samples.7:.Tn AT&T ../man/man7/mdoc.samples.7:.Tn CAPITALS ../man/man7/mdoc.samples.7:.Tn BSD ../man/man7/mdoc.samples.7:.Tn ATT . ../man/man7/mdoc.samples.7:.Tn BSD ../man/man7/mdoc.samples.7:.Tn LOCAL . ../man/man7/mdoc.samples.7:.Dl Usage: .Tn symbol ... \*(Pu ../man/man7/mdoc.samples.7:.Bl -tag -width ".Tn ASCII" -compact -offset 14n ../man/man7/mdoc.samples.7:.It Li \&.Tn DEC ../man/man7/mdoc.samples.7:.Tn DEC ../man/man7/mdoc.samples.7:.It Li \&.Tn ASCII ../man/man7/mdoc.samples.7:.Tn ASCII ../man/man7/mdoc.samples.7:.Ql \&.Tn ../man/man7/mdoc.samples.7:.Tn TeX ../man/man7/mdoc.samples.7:.Tn I/O Ns 's ../man/man7/mdoc.samples.7:\&.Tn I/O Ns 's If this was the only way Tn was used, then sure. But this there are 1143 explicit uses of Tn _in that system's manual_, not to mention the implicit ones, used heavily with the predefined strings; a representative (I think) sample of grep -rw Tn ../man/ shows -verbatim- ../man/man4/man4.vax/up.4:.Tn FUJITSU ../man/man4/man4.vax/up.4:.Tn FUJITSU ../man/man4/man4.vax/up.4:.Tn CDC No 9762 partitions ../man/man4/man4.vax/up.4:.Tn CDC No 9766 300M drive partitions: ../man/man4/man4.vax/up.4:.Tn AMPEX DM Ns No 980 partitions ../man/man4/man4.vax/up.4:.Tn AMPEX No 9300 300M drive partitions: ../man/man4/man4.vax/up.4:.Tn AMPEX No Capricorn 330M drive partitions: ../man/man4/man4.vax/up.4:.Tn FUJITSU No 160M drive partitions: ../man/man4/man4.vax/up.4:.Tn FUJITSU No Eagle partitions ../man/man4/man4.vax/up.4:.Tn UNIBUS ../man/man4/man4.vax/uda.4:.Tn UDA50 ../man/man4/man4.vax/uda.4:.Tn DEC UDA50 ../man/man4/man4.vax/uda.4:.Tn UDA50 ../man/man4/man4.vax/uda.4:.Pq Tn MSCP . ../man/man4/man4.vax/uda.4:.Tn I/O . ../man/man4/man4.vax/uda.4:.Tn I/O ../man/man4/man4.vax/uda.4:.Tn RA60 No partitions ../man/man4/man4.vax/uda.4:.Tn RA70 No partitions ../man/man4/man4.vax/uda.4:.Tn RA80 No partitions ../man/man4/man4.vax/uda.4:.Tn RA81 No partitions ../man/man4/man4.vax/uda.4:.Tn RA81 No partitions with 4.2BSD-compatible partitions ../man/man4/man4.vax/uda.4:.Tn RA82 No partitions ../man/man4/man4.vax/uda.4:.Tn DEC ../man/man4/man4.vax/uda.4:.Tn AA-M185B-TC , ../man/man4/man4.vax/uda.4:.Tn I/O . ../man/man4/man4.vax/uda.4:.Tn DMA ../man/man4/man4.vax/uda.4:.Tn MSCP ../man/man4/man4.vax/uda.4:.Tn RA80 ../man/man4/man4.vax/uda.4:.Tn RA60 . ../man/man4/man4.vax/uda.4:.Tn DEC ../man/man4/man4.vax/uda.4:.Tn EVRLK . ../man/man4/man4.vax/uda.4:.Tn REPLACE ../man/man4/man4.vax/uda.4:.Tn REPLACE Ns s , ../man/man4/ip.4:.Tn IP ../man/man4/ip.4:.Tn IP ../man/man4/ip.4:.Tn TCP ../man/man4/ip.4:.Tn UDP ) . ../man/man4/ip.4:.Tn IP-level ../man/man4/ip.4:.Tn IP ../man/man4/ip.4:.Tn UDP ../man/man4/ip.4:.Tn IP ../man/man4/ip.4:.Tn BSD ../man/man4/ip.4:.Tn IP ../man/man4/ip.4:.Tn IP ../man/man4/inet.4:.Pq Tn IP ../man/man4/inet.4:.Tn IP ../man/man4/inet.4:.Tn VAX ../man/man4/inet.4:.Tn IP ../man/man4/inet.4:.Pq Tn ICMP , ../man/man4/inet.4:.Pq Tn TCP , ../man/man4/inet.4:.Pq Tn UDP . ../man/man4/inet.4:.Tn TCP ../man/man4/inet.4:.Tn UDP ../man/man4/inet.4:.Tn IP ../man/man4/inet.4:.Tn ICMP -verbatim- some of this should be cleaned up to use predefined strings or Nses better, but in general "Tn is for writing in smallcaps when you have a CAPITALISED WORD you're copying it verbatim". The same can be said of modern uses of Tn in Debian https://codesearch.debian.net/search?q=%5C.Tn+%5BA-Z%5D&literal=0 (again, for those ~three outliers I have submitted fixes). And of modern uses in OpenBSD: openbsd-src$ git grep -wF Tn $(ls | grep -v gnu) bin/test/test.1:.Pq Tn FIFO . lib/libc/db/man/recno.3:.Tn OR Ns 'ing lib/libc/gen/cgetent.3:.Tn ASCII lib/libc/gen/cgetent.3:.Tn ASCII lib/libc/gen/cgetent.3:.Tn ASCII lib/libc/gen/cgetent.3:.Tn ASCII lib/libc/gen/execv.3:.Tn POSIX lib/libc/gen/fnmatch.3:.Tn OR lib/libc/gen/fts_open.3:.Tn OR Ns 'ing lib/libc/gen/readpassphrase.3:.Tn OR lib/libc/gen/times.3:.Tn CPU lib/libc/gen/times.3:.Tn CPU lib/libc/gen/ttyname.3:.Tn I/O lib/libc/gen/vis.3:.Tn ASCII lib/libc/gen/vis.3:.Li \ea Tn - BEL No (007) lib/libc/gen/vis.3:.Li \eb Tn - BS No (010) lib/libc/gen/vis.3:.Li \ef Tn - NP No (014) lib/libc/gen/vis.3:.Li \en Tn - NL No (012) lib/libc/gen/vis.3:.Li \er Tn - CR No (015) lib/libc/gen/vis.3:.Li \es Tn - SP No (040) lib/libc/gen/vis.3:.Li \et Tn - HT No (011) lib/libc/gen/vis.3:.Li \ev Tn - VT No (013) lib/libc/gen/vis.3:.Li \e0 Tn - NUL No (000) lib/libc/net/ether_aton.3:.Tn ASCII lib/libc/net/ether_aton.3:.Tn ASCII lib/libc/net/getaddrinfo.3:.Tn IP lib/libc/net/getaddrinfo.3:.Tn OR Ns 'ing lib/libc/net/getaddrinfo.3:.Tn IP lib/libc/net/getnameinfo.3:.Tn OR Ns 'ing lib/libc/net/getnameinfo.3:.Tn UDP lib/libc/net/getnameinfo.3:.Tn TCP . lib/libc/net/getnameinfo.3:.Tn "RFC 2553" lib/libc/net/link_ntoa.3:.Tn ASCII lib/libc/net/rcmd.3:.Tn UNIX lib/libc/stdlib/a64l.3:.Tn ASCII lib/libc/stdlib/ecvt.3:.Tn ASCII lib/libc/stdlib/getopt.3:.Tn GNU lib/libc/stdlib/getopt.3:.Tn GNU lib/libc/stdlib/getopt.3:.Tn GNU lib/libc/stdlib/getopt.3:.Tn GNU lib/libc/stdlib/posix_openpt.3:.Tn OR Ns 'ing lib/libc/string/strlen.3:.Tn NUL lib/libc/string/strlen.3:.Tn NUL lib/libc/string/strrchr.3:.Tn NUL lib/libc/string/wcstok.3:.Tn ASCII lib/libc/termios/tcsetattr.3:.Tn OR Ns 'ing lib/libc/termios/tcsetattr.3:.Tn OR Ns 'ed lib/libpthread/man/flockfile.3:.Pq Dq Tn POSIX lib/libpthread/man/getc_unlocked.3:.Pq Dq Tn POSIX (this continues for a long time, 1092 lines in fact; some of it is in mandoc source and random data as well, but not a remotely significant amount). > But what I did not do was remove anyone's capacity for customizing this arrangement. The elaborate style-sheet-esque system that (I suppose) Cynthia Livingston designed in to mdoc remains there, just with much longer identifiers naming them (blissfully). > > The one knob I removed is the one you're complaining about (not as the topic of this ticket, mind you, but as a change of subject). > > Here is the commit message relevant to that change. > > > commit 5125754cdfaa7008f65d9c3f2936626b7bcf0498 > Author: G. Branden Robinson <g.branden.robin...@gmail.com> > Date: Wed Feb 23 22:08:01 2022 +1100 > > [mdoc]: Stop setting `Tn` arguments smaller. > > * tmac/doc.tmac (Tn): > * tmac/mdoc/doc-syms (Ux, Bx): Stop interpolating string > `doc-Tn-font-size` to set macro arguments at a smaller type size. > This leaves the string without a purpose, so... > > * tmac/mdoc/doc-ditroff: > * tmac/mdoc/doc-nroff: Drop definitions of `doc-Tn-font-size`. > > * tmac/mdoc/doc-syms: Drop interpolations of that string from numerous > other string definitions. > > Fixes <https://savannah.gnu.org/bugs/?60616>. > > > However, if you grep, you will notice that no other mdoc macro permits customization of its type size like this. > > > $ git grep -- -size tmac/doc.tmac tmac/mdoc/* > tmac/doc.tmac:.\" NS doc-fontmode-size-stackXXX global register > tmac/doc.tmac:.nr doc-fontmode-size-stack0 0 > tmac/doc.tmac:.\" NS doc-fontmode-size-stackXXX > tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-fontmode-depth] \n[.ps] > tmac/doc.tmac:. nop \)\s[\n[doc-fontmode-size-stack\n[doc-fontmode-depth]]u]\c > tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-fontmode-depth] 0 > tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-reg-dsgv]-saved \n[doc-fontmode-size-stack\n[doc-reg-dsgv]] > tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-reg-drgv] \n[doc-fontmode-size-stack\n[doc-reg-drgv]]-saved > tmac/mdoc/doc-common:. tm doc-fontmode-size-stack\n[doc-reg-Rd] == '\n[doc-fontmode-size-stack\n[doc-reg-Rd]]' > > > You can try this grep on an older groff source tree, if you like. > > So, why did I pick on poor little `Tn`? > > 1. It was a challenge to manage its fiddling with the type size in a coherent, reliable, and predictable away. mdoc's bespoke reentrant macro system made this really hard. If only this were part of that macro package that could manage this complexity for the user! > 2. No clear semantics, as noted above. The actual semantics (as in "how people really use this") I think are quite clear, and have been from the start. Philosophising about american war-time (indeed, american war-machine) nomenclatural nomenclature and market forces is irrelevant. Except maybe as an incentive to change the manual from Trade Names (or Acronyms and Type Names) The trade name macro prints its arguments in a smaller font. Its intended use is to imitate a small caps fonts for uppercase acronyms. to Small Font Tn renders its arguments in a smaller font, which may be useful for all-caps words. Be wary of using those when not required, because they interfere with screen readers. > 4. We have professional typographers on the groff mailing list. I take their views seriously. They aver that getting the small caps affect by simply setting a standard typeface smaller is actually a bad way to achieve the desired effect. There exist fonts that are actually designed as all-caps faces. They still have distinct upper and lower cases, it is simply that the glyph designs for the lowercase letters strikingly resemble uppercase. See this 2015 post and follow-ups to the list. This all to me reads like you actually want to make mdoc2 (gmdoc) (and man2/gman) with a radical re-design. Which I don't disagree with necessarily. But forcibly opting users of mdoc, let's say, into it both limits your ability to innovate and reinvent manual rendering and reduces their impact. (For Sh/Dt most manuals already bake in capitals, so this just turns half-baked.) If you actually, say, left mdoc at 1.22.4 (with the spacing fixes or whatever) and forked 1.23 mdoc as mdoc2, this would let you do a fuller revamp, with bigger impact. And it would both give authors incentive to upgrade, write manuals for the new system, and _a way to validate their manuals for it_. If there is a mdoc2, Now Designed By Profesional Typographers, with porting guidelines > > But I'll dig because this is just so insane to me. How are mdoc and man related here and man relevant here at all? > Documents in these macro languages are what you see when you use the "man" command at a Unix shell prompt. They are document preparation languages. The fact that you get them via "man" makes them as related as JPEGs and PDFs (both contain instructions on what to show and you see them both when you run "open" at a Unix shell prompt). > > > Why do you feel like you have the right to take a document someone else wrote and alter it because you don't like how it looks? > That right and responsibility is part of parcel of developing a document formatting software system. It is not. You're saying you, personally, know better than the authors how their documents should look. You have a responsibility to the users to empower them to write documents in a manner that realises their vision and goal, not enforce your own goals upon their manuals ex post facto. > > It may not feel like that's what you're doing mechanically but you are altering a 30-year-old body of work out of personal preference. > Not solely that. I run my ideas by the groff mailing list and many of them spend months or years gathering feedback. The overall level thereof is pretty low, though. Your unbroken paragraph may constitute a perceptible percentage of the feedback offered in the past 12 months. This is because users are so disenfranchised that "and accept that manpages look even shittier on GNU systems now, as many kinda always did there already anyway" (a comment I received about this block of issues and the direction groff 1.23 has demonstrated) or "Groff 1.23 is out and my manpages look weird now." (public post from 2023-07-11) is much easier than trying to do anything about it. It is impossible for users to do anything about it. I'm the psycho here, not the rule. That authors don't have to care about what groff is or how ?roff processes [whatever]. They will never hear about groff. It's a _stellar achievement_ that they can write manuals in a fully-hermetic language. They cannot and will not be able to do anything about this, because no-one has the time or spare attention to unravel the seventeen levels of mud mdoc amounts to. This user has even identified the issue but hasn't managed to do anything about it: https://social.treehouse.systems/@mgorny/110694092596011251 (https://github.com/Calysto/metakernel/issues/266) (obtained by searching for groff). > > What in god's own name is "history of how man page topics got rendered over time" doing in a response to "you made a macro that rendered in a specific consistent way for 30 years render in a completely different way"? > Understanding historical development is one element of making an informed decision responsibly. Going by the dates in the date field: 1973: v4 uses man .sh NAME cat \*- whatever .sh SYNOPSIS .bd cat (\fR, \fB) 1990: 4.3BSD-Reno uses mdoc .Nm in both (\f(CB, \f(CB) 1989: SysVr4 uses mdoc .Nm in both (\f(CB, \f(CB) (well, the PDF I have looks like it was printed on something that only had one courier font which is roughly bold thickness, but it's clearly mdoc and UCB troff and macro packages were distributed with svr4, so.) 4.3BSD-Reno calls the register .\" Name (subject of manpage) Style .ds nM \f(CB The "history of manual rendering" clearly shows that in 1990 when troff gained the courier sutie everyone started setting their NAMEs in \f(CB. (This is probably, obviously, to match the synopses just below. Which are now also set in courier because they are literals.) You ought to be turning man output to look like mdoc. This is kinda obvious to me because the ancient four-font man package has been clearly superseded by the eight-font mdoc package. But you don't have that knob because man NAME sections are just text, so for some reason you're making modern manuals render like they were written in the seventies before printers^Wphototypesetters even had courier fonts to choose? This is weird to me because as the god-king of groff you could just as well _advance man_ instead of regressing mdoc. To that end, similarly, Xr has always been rendered in \fR and it's \fC/\fR in 4.3BSD-Reno mdoc. They aren't italicised or emphasised ever. Why would they be. Section (page) names aren't italicised either, but they're always set in \fR. (AFAICT the Hs string controls this in 4.3BSD-Reno. It gets \s10 in 4.4. groff-1.08's tmacs that are distributed but not used 4.4BSD-Lite2 agree with this.) I think the document title in the top right oughtn't be set in a non-default font at all, because (a) of temporal consistency (see below) but also (b) of its function being to mark the page and not to function as a reference. But if Xr is set in a non-default font (as it is under mdoc) then the document title in the top right _shouldn't_ be, unless it is also the canonical name. And with allcaps being baked into most manuals, it isn't. This could be averted with revamped mdoc2 guidelines, but see previous para. This, to me, once again means "don't change mdoc, affect the same change onto man", especially since you now have MR and changing that to be \f[CR] will likely be trivial. > > If you like that way better, because this is all your personal visual and editorial preference, then gate it all on \n[groff_new_mdoc] and let individual authors opt into it. > That is a sound approach for some changes--not all. Not those that simply fix bugs or add extentions that don't affect existing documents, of course. > > You are not manufacturing a singular system here (you can tell because you haven't written any new manuals or edited any existing manuals to fit the new macro system), > This is nor merely an unfair statement but an inaccurate one. I have done extensive work on man(7) and mdoc(7) documents for multiple projects. (Much more the former than the latter, by roughly the same proportion as these formats appear in field, I would guess.) Former point stands to me. Unless you intend to review and fix all documents the latter strikes me as lukewarm at best. > On balance, my suggestions are well received (often accepted as-is), and in fact I get into far fewer arguments than I expect. One might dare to conclude that I generally come across as knowing what I'm doing. Even just the latter would be enough, because most users simply do not and could not possibly have a way to form an opinion on the minutiae of manual formatting. If they care at all about manuals. > > and your goal is not to make every page somehow magically look identical (because you didn't write those documents; this is also obviously impossible) > "Identical" is a vast overstatement here. Please keep in mind that the sequence of English words that composes a man page is the information of first order, not typeface, indentation, or other details of formatting. Incorrect. I am to understand that you consider all manuals which are not written in your holy tongue to be devoid of information. If I had the same attitude then maybe I wouldn't be having this discussion. So maybe I agree. But even barring that openly racist remark, you yourself complained about the "unbroken paragraph" format of my original reply. If this were the case, then no-one would care about fonts or punctuation changing, if fonts and punctuation were to be present in the first place. It is blatantly obvious that, yes, the way different bits of text use the same or different fonts, as well as punctuation used to denote how they relate to each other, and the spacing used to correlate the various parts of the text, conveys fundamental and indelible semantic information. > Once one considers that point, one realizes--I would hope--that "magically" presenting man pages in a consistent format is in fact a benefit to the reader. Locally-consistent: yes (this is what this particular bug is about, you have made the name of the program (or function, or whatever) locally-inconsistent). Temporally-consistent (as in "i understand what each part of the manual means because i have read this manual before and potentially other manuals before, therefore it is implicit how differently-framed parts relate to each other semantically"): very much so. Globally-consistent: even if there are two styles (though, frankly, I'd say there is The Mdoc Style, and "whatever someone invents with the man macros they find", which is usually something sane but I've seen my fair share of crazily-formatted manuals), they are quite similar under nroff, and temporal consistency is much more important than laundering how manuals are rendered so they > Occasionally someone gets angry with the man page format and decides to radically depart from it just to make a point. Here's my favorite example of such petulance. Is this a departure from the manual format? This looks almost idiomatic to me. I'd like indents for the sections, but meh. (Hell, under your "everything that isn't words doesn't matter" policy, there is no difference between this and using a macro package.) Cf. user disenfranchisement. > In any case, properly considered, this goal is restricted to the groff corpus of man pages. I want those to be consistent with each other. Even that is not done yet. But I would claim that they have much greater parity with each other now than they did in, say, the 1.22.3 release. > > The process of revising groff's own man page corpus is generally what has drawn my attention to and motivated adjustments to macro package behavior. I invite you to check out groff's Git repository and measure such changes compared to my revisions to man page formatting within the existing macro languages. Sure, semilocal-consistency is nice, but I think this spilled from "the groff manuals were inconsistent and I didn't like them" to changing all manuals for this reason. This strikes me as the classic > >, you are providing an interface for others to write documents against, which has been consistent for 30 years, > This is another way of saying "unmaintained", which is only a slight overstatement. No it isn't, this is an americanism. "Unmaintained" means "there were hard spaces in Pq from the nineties which we can finally delete, but haven't", not "a wide-spread deep-seated output format change". > What you are offering in the place of such a specification is mere inertia. The standard solution to "the function you're using changes behaviour because of New Developments" is "you were using a versioned symbol so no it hasn't, you can deal with this when you next re-visit this code", which with the following: > > I would 100% opt into a groff_new_mdoc "look" and write documents against it. > Well, stay tuned--I may have some ideas along these lines over the next few years. Reads to me, again, as "I want to develop a new, modern, mdoc". Hell, this is the time for it! It's been like-20-years since the last good revamp from man to mdoc! Make this gmdoc (or mdoc2). Make it an optional thing for authors to opt into until you believe it is ready. Maybe then turn it on by default and require the inverse to load the old renderer. > > If you market it as The New Unified Common Free Way most authors probably would. > I dislike marketing. In any case, I've been working the same way Ingo has been with mandoc(1)'s dialect of mdoc. This, IME, means you are about to stop supporting a feature (or not support it at all) and tell me I'm wrong for using it because you don't like it. Or you're about to hard-loop on some common input. Please confirm you are not going to do this. > Small, incremental changes over time. To my knowledge, no software system in the world exists that can support the demand "take this mdoc input and render it as AT&T troff on 4.3BSD-Reno would have." If you want that, you'll need to run the exact system in question (probably under simulation). I don't really. I just want the document I wrote last year to be recognisable and require no fundamental changes in two years. > > I will not tolerate, defined as "getting my knickers in a twist" 🤮, just flagrantly changing my documents because you don't like them. I don't think you would either! > It depends. I'm a detail-oriented person. I'm willing to acknowledge that I sometimes put great weight on matters that other people consider unimportant. Can you say the same? We're having this discussion, so clearly. > > This is crazy to me because I thought if there's one API one could count on being consistent to lay out documents with it'd be mdoc which has been used to lay out documents for decades with a consistent look and feel and a well-behaved and constant interface. > Every "full-service" macro package that groff ships, apart from possibly mom (only 20 years old or so), is about this moribund: man, ms, me, mm, and of course man. I get the impression you are indeed an mdoc partisan, so you might not have troubled yourself to read the "History" section of the groff_man(7) document. I would ask you to do so. I don't use the man API because it is of no use to anyone but the maintainers of large bodies of work which are already bought into it. 1.22.4 groff_man(7) doesn't even have HISTORY. The version on manpages.d.o looks like omits the fact that the many man-style macros (but lowercase) were hard-coded (I think? I don't really see a reference to a macro package) into nroff and troff, which is why v4 manuals look like man ones but with the macros in lowercase, and you can render them pretty accurately with some choice uppercasings and one or two substitutions. I'd even say you can see the influence of this to this day when people use ".I something," instead of ".IR something ,". It is of course important to recognise the difference between how the other macro packages are (tend to be) used (interactively, the user is the author, using a single version) and how man and mdoc are (widely distributed across a multitude of implementations, the user just sees it). And thus how the minimal stability guarantees must be different. > And I have a shock for you. mdoc has evolved over the past 30 years, too. As noted above, Ingo's added some things (though I can't remember which, off the top of my head), and more tellingly there are the `Brq`, `Brc`, and `Bro` macros, which obviously cannot possibly have been supported with distinct meaning by AT&T troff. I have, however, troubled myself with observing and rendering a plethora of early-BSD mdoc manuals under and can similarly tell you they... mostly kinda work. Some, IIRC mostly list-drawing macros, were removed in modern mdoc and behaved differently in these early versions (some would say they work much more like the man pseudo-lists). I don't think much is lost by this. Or that much would be lost if those manuals rendered differently, even significantly-differently, so long as they can be read at all. This is a very low bar. But the modern suite of manuals, from the modern era of software, needs to be supported in a way that preserves their fundamental qualities. Minor spacing adjustments aren't fundamental qualities, but as established. > > Groff itself has for a long time defined a contract: hey Nm looks like this. Xr looks like this. Li looks like this. Sx looks like this. Tn looks like this. The manual is perfectly clear on what all the macros look like. > It's not a contract--it's a description. But otherwise, yes. If you could ship the macro suites with your manuals, and this was the Thing To Do, then yes. Or if this was a normal program you could link against and the behaviour of the document was automatically preserved with versioning. But because it isn't, this must be a contract to rely on. > > And you decided to completely violate this. > I do strive to document the changes I make. In what respect do you assert that I haven't? I don't really, but if you compare this with the release of a normal library (which a macro package is, effectively), and compare how output changes and removals in those are handled and how they affect existing source, especially if you intend for the same source to be portable to different versions of the library, you can see how "i deleted this" in the Bugs or simply a quiet change in the documentation is drastically different to what is usually expected and required. > > They no longer look like what they have been documented to look like for decades. This isn't cruft (like the Pq thin spaces were), this isn't something to correct (like the Ss indent the section name goes multi-line), this is deliberate design. > Some people nevertheless may have relied upon such cruft or bugs to achieve the effects they produced. You would have no trouble telling people that they were wrong to do so. I would say that it is unfortunate that they could've done so, but that most of the issues I found in 1.23.4 wasn't really meaningful beyond being annoying. I think we just have different thresholds for the minimal difference that we consider fundamental alterations to the manual, and that yours is above "removing font sizedness distinctions and shuffling fonts around". Whereas mine is below this. > That said, I don't change things unless I think I have a good reason. So the grounds on which you need to engage me when disagreeing with such a change are the ones upon which I premised them. A rant about how I'm some mindless force of entropic havoc smashing its way through the groff code base is unlikely to change my mind. I don't think you're a mindless entropic force, I think your reasons are fundamentally ill-conceived and at odds with the expectations of both users (authors) and end-users (readers), which is not challenged by downstream maintainers because of the, as you say, moribundity of the subject matter and you being seen as an expert. > > I have personally spent days if not weeks (months, actually, but most of that time was also spent producing the text itself, and I also care about troff renders; this will just be days-to-weeks for most people) making sure that out of four fonts available in nroff mode the body of the text is clear and obvious. > That is laudable. I care about that too. However, I would always treat choice of typeface as a supplement to semantics. As noted above, some of your audience (the visually impaired) may be unable to perceive their signification (or are unassisted by their technology in doing so). Much more prosaically, any time we copy and paste from a man page, we lose all the typeface information. From a technical writing perspective, I urge you to compose your materials to be as robust against this loss as you can manage. Those users who can use them, however, benefit profusely from considering this. And affecting the ratio of fonts used or the punctuation applied to certain segments decidedly hampers this, and can have the opposite effect; this is largely what I meant with: > > Shuffling the fonts around 100% breaks this. > Around the time of 386BSD and Linux 1.0, man page authors--and this may have included the original developers of mdoc--already took it upon themselves to shuffle the fonts around because of a stupid limitation of VGA text mode, and essentially flushed italics down the toilet in the favor of spraying boldface everywhere they possibly could, because it was just so cool to have *nix running on your PC instead of having to go to campus to play with it. (And it was, but in their excitement, they made some short-sighted decisions.) > > https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html > > Anyway, I complained a while back that mdoc in particular uses "too much Courier and too much bold". In fact, I appear to have said this more than once. No one bothered to argue with me about it. Because it's a personal preference and it doesn't matter to me what your opinion about this is. I think there are some choice places where the fonts could be different sometimes, but the temporal and local consistency gained from not changing it are far greater than changing it. I think this amounts less to "too much bold" and more "not enough italic". But again, this can be tuned for renders. And doesn't affect anyone else if I want to change it. Even if I _were_ the god-king of groff I wouldn't change it. Sometimes personal goals and duty to one's users are at odds. This tends to be the case, it just doesn't surface when downstreams don't care. > If only you'd been there, no? Well, I was definitely not there for Linux 1. But I was there for the mail (I don't see it in my mailbox but I vaguely remember skimming this after having it linked to me maybe) and decided I didn't care enough about commenting on your blog post. Especially since cross-references aren't bold. > > Again, if this were just a new mode? I'd opt in and write with it when it reaches stability. If this new german psyche is rendered unto my documents by force? I am violated. > I'm not happy to hear that you feel that way. I suggest that a better response is to join the groff mailing list (and bug-groff and groff-commit if you have the spoons) and engage these issues you disagree with at the time they're mooted. I don't have the time, energy, or vitriol required. Sometimes the best thing to do is "not much" instead of "something, anything", which appears to be a common sentiment (also from a comment I received: "I have a feeling that the recent groff release(s?) was(were?) only so full of useless or even bad changes to make the authors still feel useful… kinda like some standards… it’s a PITA."). It's much easier for everyone involved to just ship a reversion mdoc.local which I can write once per release. > > Sorry, long post. If you don't care about reading my essay about colonialism > I believe I have done you the courtesy of engaging with it. You have, thank you. > > please just put the altered L&F behind .if dgroff_new_mdoc and unbreak the last 30 years of documents. I'd define groff_new_mdoc in my new mdoc documents :) > I will not pledge to do that, but I'm open to suggestions for preparing means of rendering historical mdoc documents in a more historically authentic way. Again, this is less about historical ones (already kinda broken but work enough to mostly use (but a style-sheet isn't enough), I don't think there's much point to reinventing the wheel there when they are only really used by shitlords like me), and more about the ones written in the current era. > Maybe something analogous to groff's own "compatibility mode". Possibly we could have little macro packages loadable with "-m" that bundle piles of register and string definitions constitutive of a style sheet for mdoc. This would take a bit of work to develop in the details and I would hope you'd contribute to such an effort. I already use this on CI and my sid systems: https://git.sr.ht/~nabijaczleweli/groff-1.23-unbreaking/blob/trunk/mdoc.local (it doesn't deal with the titles). Best, _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?65101> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
