bugGNU roff - Bugs: bug #65101, [mdoc] topics in "Name"...

 
 

bug #65101: [mdoc] topics in "Name" section set in roman since 1.23.0

Submitter:  None
Submitted:  Sun 31 Dec 2023 10:26:12 PM UTC
   
 
Category:  Macro mdoc Severity:  2 - Minor
Item Group:  Rendering/Cosmetics Status:  Need Info
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 02 Jan 2024 10:07:00 PM UTC, comment #5: 

I won't wade into the minutiae of man-page rendering, but I'll address some larger points.

comment #4:

> Why do you consider "all the manuals must look the same, by
> force, regardless of what the authors have written" a goal?


This is how typesetting is done in the modern world.  If you contribute a chapter to a book of technical documentation, the publisher will feel free to tweak your submission to conform to house style, so that the entire book has a consistent style.  This is for the benefit of readers, who can locate and process information more easily if it's presented consistently.

And man-page formatting only concerns itself with matters of typography.  In the above hypothetical anthology, editors would also change an author's punctuation (e.g., to ensure consistency of use of the serial comma), spelling (e.g., to make the entire book use either US or UK spellings), and other aspects.  Real-world publishing is a collaborative process, and the original author's words and rendering are not sacrosanct.

But to address this in the context of man pages: presenting things consistently is far more valuable to readers than preserving individual authors' typesetting preferences.

> as the god-king of groff


I wonder if you can cite an instance of Branden doing what he wanted in the face of consensus to the contrary.  That would be god-king behavior.  Gathering consensus and implementing it is project-manager behavior.

> not challenged by downstream maintainers because of the, as you
> say, moribundity of the subject matter and you being seen as an
> expert.


The groff email list has its share of experts in typography (including people who have done it professionally) and the history of man pages (including one who helped develop the original nroff).  These people aren't shy about expressing contrary opinions.  If Branden is seen as an expert in this community, it's because he's demonstrated some level of expertise.

Comments on this bug tracker reach a pretty small audience; it'd be a fairer test of where consensus lies if you posted your grievances with -man's current behavior on the email list (groff at gnu.org), where they'd reach a much wider audience.

Dave <barx>
Group Member
Tue 02 Jan 2024 05:03:22 PM UTC, comment #4: 


>    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.robinson@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,

Anonymous
Mon 01 Jan 2024 05:56:59 AM UTC, comment #3: 

Okay, that reply seems a tad heated.

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."

> 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.


"The manual was intended to be typeset; some detail is sacrificed
on terminals." (man(1), _Unix Time-Sharing System Programmer's
Manual_, Eighth Edition, Volume 1, February 1985)


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


I have yet to see good use cases for Courier italic or bold-italic in man pages.  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.

(What BSD managed to milk out of a plotter via vtroff may be another matter.)

> 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.

> 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.

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.robinson@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.

2. No clear semantics, as noted above.  It was documented, via materials of BSD origin, as being for "type names", but no one seemed to use it that way.  An alternative expansion was for "trade names", but people didn't consistently use it for that either.  "A trade name refers to the company's official name, while a trademark provides a company's brand with legal protection."  Historically, people seized upon the words "trade name", applied it to "trademarks" used for products, like "Unix", or "nroff", or "troff", or "GECOS", of which the last was the only appropriate application, because it was a pronounceable acronym.  (1) It actually stood for something (though that fact got damaged when General Electric sold GECOS to Honeywell, forcing a rebrand to GCOS).  (2) Acronyms are not the same thing as initialisms.  "FBI", "CIA", and "NSA" are initialisms; "NASA" and "DEFCON" are acronyms.  Traditionally, only acronyms are set in small caps (at this point, the thing I suspect you actually care about enters the discussion).  This was done to cue the reader that you were to read the capital letters together as a word, not pronounce the individual letters as in an initialism.

3.  This careful distinction between acronyms and initialisms was largely lost (possibly in the crib) at some point during the Cold War (50+ years ago), when brand managers saw the small caps used for acronyms in materials produced with great prolificity by the U.S. Defense Department and its many contractors, which included numerous large U.S. firms, including those in the tech sector and the ARPAnet, the immediate predecessor of today's Internet.  Anyway, the brand managers thought small caps "looked cool" and decided to mandate their use for all sorts of things, including the word "Unix", expressly against the desires of the people who actually developed Unix.  See testimonials by people who were there and know: https://lists.gnu.org/archive/html/groff/2015-01/msg00026.html and https://lists.gnu.org/archive/html/groff/2015-01/msg00029.html.

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.

5.  A good reason for that dovetails with another thing Ingo pointed out: shouting capitals are bad for assistive technologies like screen readers.  Apparently, what they tend to do upon encountering a sequence of capitals is to spell them out by letter name.  This has included (historically) the section titles of man pages, which is surely tedious for the users of such devices to deal with.  That's also why groff now uses mixed case for these--but, seeing furious complaints like yours coming, I added a tunable register to man(7) and mdoc(7) to enable the user to make them shout once more.  Their man pages have documented this since I landed the feature.  (Well, groff_mdoc(7) might have lagged a little, but I got it done for 1.23.0.)

> 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.

> 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 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.

> Do you feel you should be doing this and that this is a good thing to be doing?


Yes, of course.  If you review my commit messages, I think you will find that I am generally at pains to motivate my decisions.

> 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.

> 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.

> 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.)

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.  (When I don't, I strive to clearly accept blame, as--again--one can see in my commit messages.)

> 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.

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.

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.

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.
 

>, 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.

> with occasional bug fixes and extensions, sure, but not with a fundamental change of what output is generated, and how it behaves.


If you want a TRIP test, you will need to migrate to TeX.  Neither the *roff formatter nor any of its macro packages has a specification as rigid as your stated position suggests you desire.

What you are offering in the place of such a specification is mere inertia.

> 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.

> 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.  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).

(To be honest, I'm not sure Ossanna troff was ever ported to the VAX, so I'm not sure what the CSRG used to set their manuals.  Maybe they had to pay for a Documenter's Workbench or other commercial troff license like everybody else at the time--until James Clark came along with groff.  Actually, come to think of it, it was Berkeley--so I'd guess they used the System V device-independent troff on SunOS.)

> 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?

> 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.

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.

> 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.

> 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?

> 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'm telling you that you are mistaken to infer "we will never change this" from any statement in groff documentation.

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.  As of this week, groff is up to 188 regression and unit tests.  Of those, I've written 185.  If that doesn't suggest to you the depth of my commitment to stable and predictable behavior, then I will have to conclude that nothing will.

> 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.

> 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.

If only you'd been there, no?

> 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.

> 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.

And colonialism, meh, well, that just comes with the pale skin.  Spending all day indoors at the computer doesn't help with that, but it does keep me out of my neighbors' business...

> 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.  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.

Happy New Year!

Regards,
Branden

G. Branden Robinson <gbranden>
Group administrator
Mon 01 Jan 2024 03:23:34 AM UTC, comment #2: 

Why are you doing this? Should I expect mdoc to use four fonts and have all the controls that make precise layouts possible stripped out because man doesn't have them? 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. 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? 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? 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. Do you feel you should be doing this and that this is a good thing to be doing? 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"? 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. 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), 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), you are providing an interface for others to write documents against, which has been consistent for 30 years, with occasional bug fixes and extensions, sure, but not with a fundamental change of what output is generated, and how it behaves. I would 100% opt into a groff_new_mdoc "look" and write documents against it. If you market it as The New Unified Common Free Way most authors probably would. 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! 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. 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. And you decided to completely violate this. 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. 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. Shuffling the fonts around 100% breaks this. 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.

Sorry, long post. If you don't care about reading my essay about colonialism 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 :)

Anonymous
Sun 31 Dec 2023 11:07:51 PM UTC, comment #1: 

I'm recategorizing this as a "rendering/cosmetics" issue.

I'm aware of no standard regarding how the topic(s) of a man page should be set.  man(7) pages generally don't set them in bold, and mdoc(7) pages generally do.

However, in recent work on ncurses man pages, I have found that despite being written in man(7), they generally do set the topics in bold.

You are right that this groff change was deliberate.  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.

Put differently, that the Berkeley CSRG decided to go its own way with respect to man page macro package selection (largely, I think, because the man(7) package was perceived, correctly at the time, to be encumbered by AT&T's copyright, which Unix Systems Laboratories was enforcing vigorously) and its esthetic decisions regarding man page rendering are separate concerns.

I therefore take issue with the claim "broken".

What needs to be done for this issue:

1.  Further study the history of how man page topics got rendered over time, irrespective of macro package selection.

2.  Consider reverting this change to mdoc, and promulgating emboldening of man page topic names (the comma-separated list of items before the em dash in a man page's "Name" section) in groff's own man(7) pages.

3.  Consider adding yet another register or string to the shared man / mdoc name space in groff so that people who find the default "broken" can change it.  (Probably a string.  If people are going to get their knickers in a twist over this, might as well give them latitude to set the topics in Zapf Chancery Medium Italic.)

mandoc(1) will of course continue to do whatever Ingo thinks best, with no configurability.

G. Branden Robinson <gbranden>
Group administrator
Sun 31 Dec 2023 10:26:12 PM UTC, original submission:  

Downstream bug: https://bugs.debian.org/1059536, part 1.

The first invocation of Nm in NAME is broken: it correctly saves the first argument to the string register, but it draws the argument in R instead of B.
This is in contrast to every other use of Nm (and, thus, every other reference to the object the Nms refer to).
This is baffling and confusing; please revert this (a quick peep at https://sources.debian.org/src/groff/1.23.0-3/tmac/doc.tmac/#L1166 shows that this is a seemignly-intended change).

This is much harder to correct (I'd say impossible) for a casual user, though I've added this to my mdoc.local (it's not pretty nor is it nice but it does work against 1.23.0-3):

.\" Handle '.Nm ...' in "Name" section: use the Nm font! It doesn't anymore in 1.23.
.als Nm_old Nm
.rm Nm
.de Nm
.if \\n[doc-in-name-section] \{\
.  if "\\*[doc-topic-name]"" \
.    ds doc-topic-name "\\$1\"
.  nr doc-in-name-section 0
.\}
.Nm_old \\$@
..


Anonymous

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by gbranden (original reporter)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-12-31 gbranden Summarymdoc nroff output for Nm broken since 1.23 [mdoc] topics in "Name" section set in roman since 1.23.0
    2023-12-31 gbranden Severity3 - Normal 2 - Minor
        Item GroupIncorrect behaviour Rendering/Cosmetics
        StatusNone Need Info
        Assigned toNone gbranden
    2023-12-31 gbranden Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code