Hi Lennart,
At 2023-07-31T11:48:22+0000, Lennart Jablonka wrote:
> Quoth G. Branden Robinson:
> > "[-v ...]" would imply that only "-v -v -v" is allowed, instead of
> > "-vvv".
>
> Only if you can’t group options.
I term this "clustering", but yes. And most Unix `argv` interpreters
support doing so, at least those that make it into libraries used by
more than one application.
> It is an issue that there are a few different options syntaxes and
> often, the specific one used is not documented.
I suppose it'd be too demanding to ask authors of command-line programs
to document which they use in the Synopsis sections of their man pages.
Imagine:
Synopsis
tbl [-C] [file ...]
tbl --help
tbl -v
tbl --version
Arguments are parsed by getopt_long(3).
Only the last line is not already present.
If a lot of people actually _did_ this, then you'd know from its absence
that someone might be using a hand-rolled argument parser, and to watch
out for land mines for the usual quality-of-implementation issues that
accompany NIH syndrome.
> I’d argue that’s acceptable for those utilities adhering to the POSIX
> Utility Syntax Guidelines; that is, those that just use getopt. And
> thus,
>
> foobar [-v ...]
>
> -v ... Be more verbose. This options can be specified
> multiple times to increase the verbosity level.
>
> Makes it reasonably clear that you can make it very verbose by both
> -vvv and -v -v -v.
I don't have a mastery of those Guidelines but I accept that they can
contextualize the syntax enough to remove the ambiguity.
> Now, if you do not adhere to the guidelines—if you require -vvv or
> don’t allow grouping or both—you likely want a different synopsis
> syntax anyway: Then, -asdf could be interpreted as “the single-dash
> long options asdf” and you shouldn’t write the short options as -adX.
Yes. It used to matter a great deal that nearly every X11 client
application in the world applied a different conventions here, but a
consistent one thanks to the ubiquity of the X Toolkit Intrinsics
library. Eventually, when GTK+ and Qt came along, that convention was
discarded.
> None of this invalidates your explanation of ellipses and space
> therebefor. But I don’t like your explanation. Point is, I wouldn’t
> have gotten the idea of not putting a space there in the first place:
> An ellipsis is most always delimited by spaces, in synopses as in
> prose.
[rearranged]
> In POSIX, an ellipsis is not italicized and not delimited by spaces,
> as in
>
> p̲a̲t̲h̲...
> [-o f̲o̲r̲m̲a̲t̲]...
Applying the rules of prose here is what makes me nervous about your
interpretation. And POSIX's, for that matter; `argv` processing is far
less forgiving of whitespace errors than readers of prose are.
I have no serious beef with POSIX if they supply enough context in their
interpretation guidelines for people to make sense of their synopsis
notation. The hazard lies in people who don't write to those guidelines
thoughtlessly aping POSIX's notation, unmoored from its context.
I find that two rules are popular among software developers.
1. Don't write technical documentation.
2. If you find you must write technical documentation, do it badly.
> Now, for opinions differing from yours: In mdoc world, the ellipses
> frequently are part of the argument, as in
>
> .Ar path ...
>
> and thus also italicized.
I know, and I hate it; the ellipsis doesn't merit italicization any more
than option brackets do. mdoc(7) is expressive enough that you don't
actually type the brackets; you use its `Op` macro. To me, it is
telling that, thus having full control of the styling of synopsis
brackets, mdoc's author(s) (most prominently Cynthia Livingston, in the
macro language's second and final edition) set them in roman.[7]
Thanks for raising this. The fix was straightforward, and you can
expect it in my next push to groff Git.[9]
I speculate that mdoc's italicization of ellipses would have been
regarded as a problem, but that it was overlooked, and here's why.
Chronologically, it appears to me that Livingston was still working in
the pre-x86 Unix tradition, even if at what we now recognize to be its
twilight. People still had access to, and consulted, typeset manuals.
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Tahoe/usr/doc/usd/
4.3BSD-Tahoe was 1988. mdoc(7) arrived in 4.3BSD-Reno in 1990.
"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)
Try telling the difference between a roman ellipsis and an italic one,
when you can actually get italics instead of underlining. I surmise
that, as a serious *roff macro package developer, Livingston did more of
her proofreading and validation with respect to typeset, rather than
terminal, output. At least that's the approach I'd _recommend_: more
can go wrong on a typesetter--it's a better QA testbed.
But if she did, then among people concerned with man pages, she was a
member of a dying breed.
It is now the early 1990s. Enter the thundering hordes of 386BSD and
Linux users, nearly all of them somewhat new to Unix.[10] Every single
one of them has a VGA video card. These same hordes can't afford
printed manuals (except for a few who took the time to print them using
university resources) and do _all_ of their reading of documentation on
VGA monitors. The Web at first doesn't exist yet, and later, nothing's
on it--certainly not Unix documentation from which several publishers
derive revenue. These new users know little of *roff. If they even
know that any documentation beyond man pages exists, they don't know how
to type a troff/nroff/groff command to view it. And if they do, it will
often look ugly because macro package authors neglected to ensure that
output degraded well when rendered to a terminal. I claim this because
I have seen first-hand what the ms and mm packages from DWB 3.3 troff
do. groff's implementations haven't been without defect, but I fixed
some bugs in terminal output for 1.23.0. More fixes are in Git.
So what did the thundering hordes do? They read man pages, only man
pages,[11] only via the man(1) command [this, at least, is excusable],
and only ever on VGA monitors. Keep in mind that in the 1990s, a
significant portion of the *BSD and GNU/Linux user community seldom or
never started an X server. The proud achievement of XFree86 was pulling
a hardware support story together well enough that by about 2002, nearly
every installer CD or USB stick gambled on X working, and defaulted to
a graphical environment. (Too bad about the other XFree86 issues.[1])
Why does this matter? Why are you reading this?
Because the VGA character cell attribute model not only didn't
contemplate italics, the devices also didn't support underlining.[8]
In terms of stroke weight, the glyphs on your screen could be normal or
heavy (bold). And, at least on GNU/Linux, people badly wanted man page
names to be marked up differently than regular text.[6]
And so it was done. In bold. Because that's all VGA had to offer. Man
pages had demanded since 1979 that three text styles be available. The
display hardware that every 386BSD and Linux user was running supported
two. The, uh, obvious solution was just to use bold for everything.
Screw italics, who needs 'em? And thus, the man(1)-using community
ejected itself from paradise with such force that it forgot that man
page cross references (or to a large extent, anything else) were ever
set in italics in the first place.
As any 1980s PC gamer or USENET binary newsgroup aficionado could tell
you, another thing that VGA hardware could do was color. (CGA and EGA
were marginal and MDA/Hercules so neglected that I don't know if any
386BSD or Linux kernel hackers even bothered to write drivers for them.
x86 Unix users were nothing if not class-conscious. "Here's a nickel,
kid, buy yourself a better graphics card.")
It didn't take a genius to figure out that you could fake having
additional styles by applying color attributes to man pages (as was done
in GNU ls in early days--was it in "fileutils" back then?). This, too,
started a tradition that persists to this day.[5]
Now, to be candid, no veteran of the 1990s BSD/Linux wars has ever
admitted to me that this is what happened. But I was there and
familiar with the hardware, if wholly ignorant at the time of any Unix
before 4.3BSD and SunOS 4.
I'll always appreciate Ingo Schwarze relating this account:
"At some point after groff was first released (1990) but before 4.4BSD
(1993), Cynthia suggested to simplify the macros and the manual pages by
making groff mandatory and dropping support for Kernighan's troff, but
the Berkeley Computer Systems Reasearch Group objected, insisting that
support for Kernighan's troff was retained."
https://lists.gnu.org/archive/html/groff/2020-10/msg00170.html
That was a noteworthy place to draw a line, given that this decision was
taken during the very peak of animosity and litigation between the AT&T
and BSD Unix worlds,[2] and anything that AT&T locked up had to be
discarded or reimplemented, due to fear of a legal injunction
prohibiting distribution of one's software.[3] Thus it was done, and
BSD adopted groff itself to replace the then-proprietary (and
expensively licensed) AT&T/DWB troff.[4]
It's hard to understand why the decision Ingo describes was taken. A
charitable interpretation is that some CSRG people hoped that Kernighan
would find some way to get his troff into the free world. A less
charitable one is that Charles Hannum, a founder of NetBSD and as rabid
an anti-GNU, anti-copyleft personality as I have ever met, had to learn
at _someone_'s feet, and that someone was at CSRG at the time.
What might have been, eh?
Anyway, an italic ellipsis in a synopsis is always wrong, I submit.
I also don't approve of the esthetics of boldfaced man page cross
references. They are neither typographically pleasant nor historically
informed. But _you_, the man page reader, can have them if you want.
groff_man_style(7):
-dMF=man‐page‐topic‐font
Set the font used for man page topics named in .TH and .MR
calls; the default is “I” (italic style of the default family).
Any valid argument to groff’s “.ft” request may be used. If the
MF string ends in “I”, it is assumed to be an oblique typeface,
and italic corrections are applied before and after man page
topics.
I expect
.ds MF B
to become a popular addition to man.local files after Alex lands the
"Mister Sed" (MR.sed) change. But people might try the default, along
with, if their terminal emulator's up to it,
MANROFFOPT="-P -i"
for a little while, just to see if they like 'em.
Regards,
Branden
[1] https://dwheeler.com/essays/gpl-compatible.html#xfree86
[2] https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc._v._Berkeley_Software_Design,_Inc.
[3] "[Keith] Bostic pioneered the technique of doing a mass net-based
development effort. He solicited folks to rewrite the Unix utilities
from scratch based solely on their published descriptions."
https://www.oreilly.com/openbook/opensources/book/kirkmck.html
Applying this technique to SunOS 4.0's troff documentation, my
understanding is that this is exactly what James Clark did for GNU
troff (and the programs around it--tbl in particular carries
evidence to this day of having been targeted at Unix troff at some
point--why, oh, why does it not create environments to manage
formatting parameters?).
[4] https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/groff/
I cannot now remember where I saw it, but my recollection is that
a price schedule for DWB troff was something like $2,000. I don't
know if that was per-site, per-CPU, or per-seat.
[5] https://bugs.archlinux.org/task/79053
At some point, less(1) users are going to have to decide which they
want more: colorful man pages or OSC 8 hyperlinks.
We _could_ support color attributes in man pages directly in groff.
I feel sure it would horrify Ingo. It might horrify me. It would
take a lot of design work (ironically, in groff's mdoc(7)
implementation, which is based on 4.4BSD's, much of that work may be
already done, for other reasons). Right now I doubt whether it
would be worth the trouble or even satisfy the people who want it.
less(1)'s support for colorizing man pages works by pattern matching
terminal output when the *roff output driver's geriatric--literally
pre-termcap--and ambiguous overstriking output convention is used.
I would not bet on it being completely robust. grotty(1) talks
about these matters. The mechanism I can conceive would still
require SGR support, to which people, including Ingo, are opposed
anyway. ¯_(ツ)_/¯
[6] mdoc didn't. Courier roman on Times roman, or--on terminals--roman
on roman was fine for them.
(mdoc originally used a string called `xR` to control the typeface
of the man page topic name.)
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/share/tmac/tmac.doc.old
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-ditroff
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-nroff
[7] See the definitions of the `Op` macro...
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc
...and of the `lB` and `rB` strings.
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-ditroff
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-nroff
[8] If you were a product (or purchasing) manager ticking off boxes on a
requirements checklist, VGA _did_ support underlining in text mode.
In practice...
https://en.wikipedia.org/wiki/VGA_text_mode
[9]
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 70ec41ea2..6267d2a08 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -359,7 +359,7 @@
. ie "\$1"|" \
. ds doc-arg\n[doc-arg-count] \f[R]|\f[]
. el \{ .ie "\$1"..." \
-. ds doc-arg\n[doc-arg-count] \|.\|.\|.
+. ds doc-arg\n[doc-arg-count] \f[R]\|.\|.\|.\f[]
. el \
. ds doc-arg\n[doc-arg-count] "\$1
. \}
[10] Serious and experienced Unix users in 1993 invariably had $10,000+
workstations, paid for by their employers and running RISC
processors of some sort, for their daily drivers, not a $1,500
bucket of bolts with an 80386.
[11] Yes, there was, and still is, the Linux Documentation Project. For
a while, people devoted loving attention to these works. I learned
a lot from them. The Linux Manpage HOWTO document has not been
updated in 20 years.
https://tldp.org/HOWTO/Man-Page/
http://www.schweikhardt.net/man_page_howto.html
I'm sure there is some kind of message for me in that fact.
Attachment:
signature.asc
Description: PGP signature
