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. Remember that Cynthia designed mdoc(7) on behalf of
USENIX before Tim Berners-Lee put the first version of HTML in production, and
almost two years before Tim published his first description of HTML. 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. 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.
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.
> My argument would be that `No` is described
... is an example of hilariously outdated, anachronistic documentation.
Yes, that happens, even in OpenBSD, unfortunately.
> 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.
> 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.
> 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.
> 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).
> 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.
> 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. 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, 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.
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. 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.
> 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.
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)
> 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"
In interactive use, this parameter is set to the last word of the
[...]
.IP \fBCDPATH\fP
Search path for the \fBcd\fP built-in command. Works the same way as
(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)
When an external command is executed by the shell, this parameter is set in
the
[...]
.It Ev CDPATH
Search path for the
.Ic cd
built-in command.
in line with mdoc(7) conventions.
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.
> 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
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
> 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.
If in doubt, just start a new line input line after punctuation and you are
safe.
> 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.
> 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.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?68708>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
