Follow-up Comment #4, bug #68708 (group groff): At 2026-09-20T16:13:39-0400, Ingo Schwarze wrote: > Follow-up Comment #3, bug #68708 (group groff): > [comment #2 comment #2:] >> Here's what documentation has to say about this macro. > > That's mostly irrelevant.
Well it _shouldn't_ be!
> Remember that Cynthia designed mdoc(7) on behalf of USENIX
I didn't not recall that USENIX sponsored it, as opposed to the CSRG.
> before Tim Berners-Lee put the first version of HTML in production,
> and almost two years before Tim published his first description of
> HTML.
That, I _did_ remember.
> So similarly to how HTML1 (published 1991) was still a mostly
> presentational language, mdoc v2 (1989) still had a number of
> presentational macros, even though not quite as badly as HTML1.
Yup.
> And just like HTML5 no longer has any presentational macros, mdoc(7)
> macros are no longer used for presentational purposes in modern
> documents. Even though Kristaps and myself have worked at lot on the
> documentation, some anachronisms remain, in particular for more
> obscure macros like .No. I definitely ought to fix the description of
> .No - talking about "roman font" stopped making sense about a decade
> ago.
Okay.
> If any OpenBSD developer would use .No to request roman font, i would
> shoot them on sight. Fortunately, people don't do that, the macro is
> used to close a prior in-line macro scope.
I see. How _sure_ you are that that's consistent with the 4.4BSD
version of the mdoc package, and with groff mdoc?
>> My argument would be that `No` is described
>
> ... is an example of hilariously outdated, anachronistic
> documentation. Yes, that happens, even in OpenBSD, unfortunately.
Hmm. Well, groff has some of that too, but I've been trying to update
or kill it.
>> It's fair to ask why one would ever use `No` for the purpose of
>> recovering automatic hyphenation when one could just break the input
>> line and write a _roff_ text line.
>
> Precisely. Not only is that better style - it's so much better that,
> if i would find something like
>
> According to the C standard, the difference between the terms
> .Em parameter No and Em argument
> is ...
>
> i would edit that page on the spot and commit
>
> .Em parameter
> and
> .Em argument
>
> right away. The purpose of .No is *not* formatting normal, running
> text, at least not in the 21st century - but i doubt Cynthia would
> have written ".Em parameter No and Em argument" even in 1990.
Maybe some day you'll get to interview her again.
>> Yes, but "semantics" can have varying implications for automatic
>> hyphenation. A URL should not be hyphenated, but the link text can
>> be. Similarly, Guillem Jover was right to be incensed that function
>> names given as arguments to `Fn` should not be subject to
>> hyphenation.
>
> Sure, but an expression complicated enough to warrant .No in the
> middle almost certainly doesn't want hyphenation in the middle,
> because it is simply not running natural-language text, unless the .No
> macro is being abused.
Not sure I agree. It should be okay to hyphenate (both automatically,
and at explicit hyphens), `Ar` arguments, because they are not literals.
Example:
gdiffmk(1) General Commands Manual gdiffmk(1)
Name
gdiffmk - mark differences between groff/nroff/troff files
Synopsis
gdiffmk [-a add‐mark] [-c change‐mark] [-d delete‐mark] [-x diff‐
command] [-D [-B] [-M mark1 mark2]] [--] file1 file2
[output‐file]
>> I say again, it looks to me for all the world like mdoc(7) was
>> designed to be lifted free of *roff and set down on top of a
>> completely different formatting system.
>
> There is some truth to that, the concept of "callable macros" doesn't
> agree well with how roff(7) normally works. It is highly effective
> for a line-oriented markup language though, and allows for compact and
> very readable notation, in stark contrast to the considerable
> verbosity of HTML.
Readable except for the macro names, which sound like the Black Speech
of Mordor.
>> I'll bet the BSDI founders
>
> I had to look up who these were and conclude BSDI played no role in
> the design of mdoc(7).
That could be true, but that doesn't rule out one of them vetoing its
abandonment of AT&T troff syntax limitations.
>> who were, I suspect, hell bent on keeping groff out of their product
>
> You are very, very wrong. Keith and Kirk were leading developers in
> both the CSRG at UCB and in BSDI. BSD included groff as its main
> roff(7) implementation from 4.3BSD-Net/2 (1991) onward. In 4.4BSD
> (1993) AT&T roff was relegated to an "old" directory, and in
> 4.4BSD-Lite1 (1994), AT&T roff(7) was removed. All versions of 386BSD
> i have seen contained groff, and NetBSD, FreeBSD, and OpenBSD
> contained groff from the outset.
I know that. But someone has to have been unhappy with that state of
affairs, or they wouldn't have gone out of their way to direct Cynthia,
against her own preferences, to preserve compatibility with a
proprietary troff from a company that had just done its damnedest to sue
BSDI into oblivion, and charged 15,000 USD per seat for a source
license.
I archived an old Usenet post.
How much did a DWB (Documenter's Workbench) license cost?
.
The distribution fees for DWB 3.1 were substantially increased
over those for DWB 2.0. For the record, here are the fees
charged by AT&T USL (800-828-UNIX):
.
DWB 2.0 DWB 3.1
-----------------------------------------------
Source License $4,000 $15,000
Sublicensing Fee $3,000 $ 5,000
Minimum Per Copy Fee $ 10 $ 120
(Royalty for binaries)
.
DWB 3.1 does include LaserJet, PostScript and X Window support,
but this represents exactly the value that VARs have already
added to DWB 2.0. VARs seem to be reluctant to pay $20,000 and
an order of magnitude increase in royalties when the most
advanced troff software (like the MONK text compiler) remains
unreleased.
.
https://www.usenet-rewind.com/message/MTAyQHVyYmFuLlVVQ1A
>> did not think it would take thirty years for that completely
>> different formatting system to materialize.
>
> Again, you are very wrong. Cynthia never intended to get rid of the
> roff(7) foundation.
I didn't say she did. But it _seems_ to have been designed with the
prospect of that in mind. It wouldn't have been a dumb move given the
increasing hostility of USG/USL toward (relatively) free Unices.
> Quite to the contrary, inside the the CSRG, she lobbied for mdoc(7)
> and BSD manual pages to be made groff-only and completely remove
> support for AT&T groff, but other members of the CSRG were slightly
> more conservative than Cynthia was and forced her to implement her
> macros in a way compatible with the old AT&T roff,
Yes. You've told me this before. I want to know who that person or
persons were. Whenever I see a bafflingly dumb engineering decision
made by an engineer of obvious ability, I smell a conflict of interest.
Now, surely, it can be told.
> much too her chagrin because implementing the macros for groff only,
> which was already more powerful even in 1991, would have been easier
> and cleaner.
Yes, it would have.
> When i told her about the new semantic searching facilities and about
> HTML4 output, she was pleased that something came of her work that she
> did not even envision. I don't think i so far talked to her about the
> HTML5/CSS output we later implemented.
>
>> I wonder who I can blame for this spite-driven engineering
>> management. I wonder if it was McKusick.
>
> I can assure you no spite was involved, merely innovative energy and
> love of groff.
I can't square that claim with the foregoing chagrin-provoking decision.
> If i remember correctly, neither Cynthia nor Kirk clearly remember
> whether anyone in particular insisted on keeping AT&T compatibility in
> addition to mainly working with groff. It might well have have been a
> consensus of more than just one or two people.
Sometimes an unclear memory is a polite way of forgetting names to
protect the guilty.
Of the BSDI founders, I have little knowledge.
* Keith Bostic, I have an unreservedly positive impression of.
* Bill Jolitz, given his later history with BSDI (quitting because the
company sought a far higher price point than he was comfortable with)
seems unlikely to me to have contributed to this lamentable decision.
* I know virtually noting of Rick Adams, Mike Karels (apart from
appearance in BSD-related RCS strings), and Donn Seeley.
* That leaves M. Kirk McKusick, whom I've met personally since I was a
student in one of his "teaching the FreeBSD kernel" courses with about
50 other Cisco employees many years ago.
I didn't get a solid read on Kirk. Given his fee-based CSRG archive
service on CD-ROM, and his lecture fees, it seems he consistently keeps
an eye turned to how he can monetize his expertise and personal history.
That by itself is not evidence of very much.
And I've never heard anything about Cynthia Livingston that left me
anything but impressed.
Anyway, back to technical issues...
>> No real hazard of that here. The minimum practical line length for
>> a man page is 65n,[1] and list items always break the line first.
>
> Yes, that statement is mostly reasonable, since 65n is a traditional
> limit that was used in some older Unix systems, and in various pages,
> ugly formatting will result from retreating even further.
>
> That's the reason why, for widths of 65n and less, mandoc(1) reduces
> the default text intentation from 5n to 3n, to save at least some
> space.
Interesting. groff man(7) and mdoc(7), of course, let the user control
set that default indentation, if they desire.
> If you are are willing to tolerate some ugliness, it is possible to go
> lower, though. For example, i recently learnt from a Termux developer
> that the typical line length mandoc(1) uses on Android phones is 45n.
> Those are cute, small, cuddly beasts after all. =:c)
Heh. I use Termux myself. Of course I have a shell script called
"gman" that uses mandoc(1) to locate a man page, gunzip it if necessary,
and pipe it through "nroff -mandoc". Gotta eat my dog food!
>> I think it's more likely the ksh(1) author didn't want
>> "(underscore)" _italicized_. That is after all the first thing you
>> tell people about the `No` macro in the documentation.
>
> Well, actually, the pdksh(1) author(s) did want "(underline)"
> intalicised, for reasons i can't guess, and hence OpenBSD initially
> imported this manual page source code in 1996:
>
> The following parameters are set and/or used by the shell:
> .IP "\fB_\fP \fI(underscore)\fP"
That _is_ baffling. What _were_ they thinking?
[...]
> (Yes,it was written in man(7) back then.)
>
> When Jason McIntyre translated the page to mdoc(7) a decade later (in
> 2007), it became
>
> The following parameters are set and/or used by the shell:
> .Bl -tag -width "EXECSHELL"
> .It Ev _ No (underscore)
[...]
> in line with mdoc(7) conventions.
Seems reasonable.
> And Cynthia certainly did not want .Ev to be italic - making .Ev
> italic is one of the recent changes of yours that i like to call
> "regressions" even though you did it on purpose, and that i will patch
> out of groff when the time comes to port a newer version - in 1.23,
> groff still behaves in the traditional way, you must have changed it
> later.
Yes. About 3 months after 1.23.0 released.
commit 6d734a4a40047e43cfccc3b45f5f6b16fe645f81
Author: G. Branden Robinson <[email protected]>
Date: Sun Oct 15 05:24:03 2023 -0500
[mdoc]: Change `Ev` default typeface to italic.
* tmac/mdoc/doc-ditroff (doc-Ev-font):
* tmac/mdoc/doc-nroff (doc-Ev-font): Change typeface for environment
variable identifiers from (Courier) roman to italic, for
consistency with man(7).
And I disagree that this is incorrect stying. I'm strongly confident
that I've seen many precedents, but it will take me time to gather
examples that I haven't had a personal hand in.
>> whether the "semantics" apply to _all_ non-punctuation, non-macro
>> arguments, or just the first.
>
> For most mdoc(7) macros, "all" is the answer, it is documented in the
> mdoc(7) manual:
> Macro=Ev Callable=YES Parsed=Yes Arguments>0
That wasn't clear to me, and still isn't. "Arguments>0" says to me that
the macro requires at least one argument, but it does not indicate that
the "scope" of the macro's affect is limited in any way.
> These are the macros with maximum argument numbers:
> 0: Ap Ns Pp (deprecated: Bt Lp Ud)
> 1: At In Pf Sm St Tg (deprecated: Db)
> 2: Es Xr
Okay. This might be material worth improving in groff_mdoc(7), at
least.
>> For that matter, I don't know if punctuation arguments
>> terminate a "semantic scope". If I had to guess, I'd expect so.
>
> It depends. For some macros, the scope automatically reopens after
> punctuation.
Hrm. The number of columns in the table required to summarize mdoc(7)
macro semantics is growing.
> If in doubt, just start a new line input line after punctuation and
> you are safe.
That's not a good enough rule for me as an implementor.
>> Perhaps you can tell me where mandoc_mdoc(7) spells out these
>> matters.
>
> It says:
>
> Many in-line macros interrupt their scope when they encounter
> delimiters, and resume their scope when more arguments follow
> that are not delimiters. For example,
> .Fl a ( b | c \*(Ba d ) e
> renders as:
> *-a* (*-b* | *-c* | *-d*) *-e*
> This applies to both opening and closing delimiters, and also to
> the middle delimiter, which does not suppress spacing:
> | vertical bar
>
> It does not provide a complete list stating this detail for every
> macro, though. Maybe it should.
Yes--I'm going to need such a resource if you don't want me to run an
even greater risk of breaking groff/mandoc compatibility. This doesn't
mean you have to prepare it; if you haven't by time I need it, I'll
start making it myself.
I will then share it with the groff list and we can have a whole bunch
of arguments over minutia. ;-)
>> Anyway, I don't expect to be able to move on this issue soon even if
>> I do decide on reform. Addressing it means having to more deeply
>> understand groff mdoc's internal macro parsing system, the comments
>> of which use the term "string" in a deeply confusing way.
>
> Indeed, if you attempt to "reform" this without understanding it, you
> are likely to break existing manuals.
I hope you have noticed that my reform proposals tend to follow a
lengthy period of familiarization with the code in question, and the
larger the reform, the longer the familiarization period.
Regards,
Branden
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?68708>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
