Follow-up Comment #3, bug#65101 (group groff):
Okay, that reply seems a tad heated.
[comment #2 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.robin...@gmail.com>
Date: Wed Feb 23 22:08:01 2022 +1100
[mdoc]: Stop setting `Tn` arguments smaller.
* tmac/doc.tmac (Tn):
* tmac/mdoc/doc-syms (Ux, Bx): Stop interpolating string
`doc-Tn-font-size` to set macro arguments at a smaller type size.
This leaves the string without a purpose, so...
* tmac/mdoc/doc-ditroff:
* tmac/mdoc/doc-nroff: Drop definitions of `doc-Tn-font-size`.
* tmac/mdoc/doc-syms: Drop interpolations of that string from numerous
other string definitions.
Fixes <https://savannah.gnu.org/bugs/?60616>.
However, if you grep, you will notice that _no other_ mdoc _macro_ permits
customization of its type size like this.
$ git grep -- -size tmac/doc.tmac tmac/mdoc/*
tmac/doc.tmac:.\" NS doc-fontmode-size-stackXXX global register
tmac/doc.tmac:.nr doc-fontmode-size-stack0 0
tmac/doc.tmac:.\" NS doc-fontmode-size-stackXXX
tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-fontmode-depth] \n[.ps]
tmac/doc.tmac:. nop
\)\s[\n[doc-fontmode-size-stack\n[doc-fontmode-depth]]u]\c
tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-fontmode-depth] 0
tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-reg-dsgv]-saved
\n[doc-fontmode-size-stack\n[doc-reg-dsgv]]
tmac/doc.tmac:. nr doc-fontmode-size-stack\n[doc-reg-drgv]
\n[doc-fontmode-size-stack\n[doc-reg-drgv]]-saved
tmac/mdoc/doc-common:. tm doc-fontmode-size-stack\n[doc-reg-Rd] ==
'\n[doc-fontmode-size-stack\n[doc-reg-Rd]]'
You can try this grep on an older _groff_ source tree, if you like.
So, why did I pick on poor little `Tn`?
1. It was a challenge to manage its fiddling with the type size in a
coherent, reliable, and predictable away. _mdoc_'s bespoke reentrant macro
system made this really hard.
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.
[https://www.investopedia.com/articles/personal-finance/120415/trade-name-vs-trademark-know-difference.asp
"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
[https://lists.gnu.org/archive/html/groff/2015-01/msg00013.html 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.
[https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
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. [https://lists.gnu.org/archive/html/groff/2022-12/msg00123.html 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
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?65101>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
