[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug #65101] [mdoc] topics in "Name" section set in roman since 1.23.0
|
From: |
anonymous |
|
Subject: |
[bug #65101] [mdoc] topics in "Name" section set in roman since 1.23.0 |
|
Date: |
Tue, 2 Jan 2024 12:03:23 -0500 (EST) |
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.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,
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?65101>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/