Hi Lennart,
At 2023-07-31T18:40:11+0000, Lennart Jablonka wrote:
> > > I’d argue that’s acceptable for those utilities adhering to the
> > > POSIX Utility Syntax Guidelines; that is, those that just use
> > > getopt.
[...]
> Actually, reading it again, I would just drop the ellipsis.
>
> foobar [-v]
>
> -v Be more verbose. This option can be specified
> multiple times to increase the verbosity level.
That's fine. Syntactical issues can always be kicked upstairs to the
semantic level. At some cost.
> > 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.
>
> Oh, but synopses are prose!
Maybe we're using different definitions of "prose". I reckon I'm using
it to mean "sentential, natural language utterances that are not verse".
> You say that you want unambiguous synopses, I agree; but you still
> need to read the options’ descriptions to know all about the utility’s
> command-line syntax.
Normally, you don't. Not to grasp its _syntax_.
> You don’t embed regular expressions for the arguments in the synopsis.
No, because synopsis syntax maps to a subset of regular expression
syntax.
foo -> foo
foo? -> [foo]
foo+ -> foo ...
foo* -> [foo] ...
(foo|bar)? -> [foo|bar]
It's a little clumsier, formally, to express alternation of a mandatory
argument.
baz (foo|bar) -> baz foo
baz bar
This is a concern mostly for interfaces like tar(1)'s, which seems to
trip up everybody when they first learn it.
> While there are styles for specifying different requirements, like
> having multiple symbolic command lines for alternatives with largely
> different syntaxes (e.g., a symbolic command line per sub-command),
A gentler version of this is seen in grotty(1), where the availability
of certain options is modal.
grotty [-dfho] [-i|-r] [-F dir] [file ...]
grotty -c [-bBdfhouU] [-F dir] [file ...]
grotty --help
grotty -v
grotty --version
> there are still requirements only expressed in the DESCRIPTION: One
> option might be optional unless a certain other option is given.
You can get a fair way toward that; see above.
> You wouldn’t write [-a] [-b -a], you’d just write [-a]
> [-b], or rather [-ab].
I might critique this if I understood what you were trying to
express with it.
> If you should follow quite strict rules in you synopses (and you
> should), it still is more or less free-form.
I invite you to review the synopsis suggestions offered in
groff_man_style(7) and point out any ambiguity problems more severe than
those of POSIX's Guidelines conventions. I didn't have those in mind
when writing them--just general practice, which is chaotic and not
difficult to improve upon.
> Exactly. Which means: All we can and something we should do is have
> guidelines. Saying nothing of what those guidelines should be.
We can say more than that. If no objective criteria for comparing
synopsis language conventions exist, then let's develop some.
> > 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]
>
> I’m inclined to agree, though here I value convention over taste—and
> the convention for mdoc manuals has been from the start to italicize
> the ellipses.
I'm not anxious to sacrifice so much to taste. :)
> > Thanks for raising this. The fix was straightforward, and you can
> > expect it in my next push to groff Git.[9]
I may not be willing to die on this hill, but I'm willing to risk being
MEDEVACed from it. It won't matter, if everybody who really cares about
mdoc(7) is loyal to mandoc(1) unto death, which seems to approximately
be the case.
My goal is that it not be obvious to the causal reader of a man page
whether man(7) or mdoc(7) was used to compose it. So I'm not tolerant
of gratuitous rendering differences, and in groff 1.23.0 I made changes
to both packages to align them better with each other. I'm happy if
only an expert man page author can tell without looking at the source.
> Heh, that sneaky spreading of ellipses is funny.
Alex had a comment about that too, and I remember making a mental note
to respond to it, but not actually doing so. So I will now. You may
already know this, but on terminal devices, \| (like \^) does not render
as anything at all. So we lose the interest of maybe 95% of the man
page reading community right away.
Illustration attached, in source and a PNG of rendered PostScript.
> I don’t think it should be there, but whatever.
It's a practice that has at least a decade on mdoc(7)'s italic ellipsis.
https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man0/intro
> Do note that this only works if the ellipsis is its own argument: Not
> having read doc.tmac more closely this looks like it somewhat
> contradicts your position on spaces with ellipses.
The position I adopted was not ab initio but a consequence of other
rules I apply to synopsis interpretation. I'm not enamored of option
reduplication (i.e., "-vvvv")--just accept an integral option argument,
you lazy sods--nor of any strain it puts on my synopsis guidelines.
> foobar [-o option] ... \" .Ar ...
>
> -o option Apply more options. Because there’s only so
> much space for single-letter options, you see.
>
> The -o options:
>
> .\" .Ar v...
> v... Be verbose. The more v, the more verbose.
>
> Oops, now the first ellipsis looks better than the second one. Yeah,
> I dislike that hack.
It may not be clear to everyone, but mdoc(7)'s special handling of "..."
only applies when it appears as its own token. _But_ there are a lot of
rules about how mdoc(7) processes tokens in its utterly bespoke approach
to input interpretation, unlike any other *roff macro package.
For example, I cannot completely account for the behavior of:
.Fl x Op Fl v Ar file ... Op Fl v... Op Fl v Ns ...
And bugs _have_ been found both in groff's and mandoc's implementations.
As another case--a real-world one--the correct resolution of
https://savannah.gnu.org/bugs/?63289 is not yet decidable to me.
If I ever master the package, maybe I'll get a chance to improve the
groff_mdoc(7) page.
> What I found in 4.3BSD-Reno’s mdoc.samples(7) and think is funny:
>
> [mdoc's] purpose is to allow translation of man pages from
> .Xr troff 1
> to
> .Xr TeX Coming\ Soon
> and vice versa.
>
> Is (was then) there an equivalent to nroff for TeX? I think not.
Nope. Interconvertibility of *roff and TeX may have been a forlorn hope
at the time, but even if not, the issue was muddled for about 20 years
by the Web appearing and SGML and then XML sucking up every molecule of
oxygen (and talent) in the problem space. (It inhaled James Clark, I
assume to his remunerative benefit.) Nowadays the best hope would
appear to lie in pandoc, which at least had the wisdom to build on a
foundation that should be strong enough for the task: Haskell.
> > 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.
>
> So that’s why!
It's conjecture that I have shared several times before, in forums where
people who are placed to know better could tell me I'm full of fecalith.
If I ever run into Rik Faith, I'll ask him. If he doesn't know, or know
who can tell me, perhaps no one does. It might have been one of those
decisions made by community gestalt rather than any deliberative
process.
> > 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.
>
> Couldn’t they have rendered italics as a different color then?
They could, and before long, they did. The Linux console driver _today_
by default (at least on my Debian-based box) renders bold in bright
white (stroke thickness does not vary, I assume because the tiny font
and therefore character cell size cannot accommodate anything wider),
underscored cells in cyan, and "true" italics in (light) green.
Back in the day (1990s) you'd get red for bold, I think, and blue for
underscore (which was a stupid choice, because it had low contrast with
the black background--but it stuck for years; this might also have been
a factor in driving man page authors to use bold for everything).[1]
Sometimes the colors were reversed, thanks to a magnificent own-goal in
the chaotic days of early ncurses development.[2] By the time _that_
got fixed, followers of the displaced ncurses maintainer swore that
they'd never use it or terminfo again, and pledged undying loyalty to
S-Lang, the moldering corpse of termcap, or programming the terminal
directly, because who cares about portability? Some of these are the
same people who will, upon considering any exhibit of code they don't
like, play the "layering violation" card as the first or second move,
often without any consideration of how that term actually _applies_.
I would advise against anyone playing a drinking game wherein they throw
one back every time I complain about something. It'd be lethal.
> > Anyway, an italic ellipsis in a synopsis is always wrong, I submit.
>
> If using mdoc, it’s less wrong to follow the established, if bad,
> convention of making ellipses for arguments italic, I submit.
If I see you from the MEDEVAC chopper, I'll wave.
> > I also don't approve of the esthetics of boldfaced man page cross
> > references. They are neither typographically pleasant nor
> > historically informed.
>
> And here you have my fullest agreement.
I even persuaded Ingo.[3] Not to change mandoc(1), but to concede the
historical point. Which feels to me like a bigger win anyway.
> Wouldn’t it be easiest to let grotty use terminfo? Then whoever
> wishes to have colorful man pages would simply write a terminfo file
> and set MANROFFOPT=-P-Txterm-colorful.
Indeed.
https://savannah.gnu.org/bugs/?63583
Regards,
Branden
[1] As far as I know, it was a long time before anyone in the free Unix
world bothered to support SGR 3 [real italics]. I have no doubt
that the ritual auto-da-fé of loyalty to Teletype Model 37-esque
overstriking largely accounts for this passivity. It is a bitter
indictment of our community that we stuck to stuff like ul(1) and
col(1) to massage the output of nroff(1) when even Unix Version 7
(1979) nroff countenanced the achievement of stylistic markup via
escape sequences, as I confirmed first-hand.
https://lists.gnu.org/archive/html/groff/2022-06/msg00048.html
...just not for the default output device. The Teletype was
manufactured by Western Electric. This is the same company--the
same subsidiary of the AT&T monopoly--that manufactured telephones.
Our community's loyalty to overstriking is closely analogous to
insisting upon being able to connect a rotary dial telephone to the
existing network. No, worse--to placing a rotary dial on everyone's
mobile phone by default and requiring an upgrade to touch-tone
dialing. (And yes, I know mobile communications are not conducted
using DTMF; even land lines migrated away from that after the phone
phreaks figured out how to issue administrative commands in-band via
that means. That's the point. The zombie inertia in this area is
breathtaking. Is it unconscious rather than deliberate? So much
the worse.)
[2] https://invisible-island.net/ncurses/ncurses.faq.html#interchanged_colors
[3] https://lists.gnu.org/archive/html/groff/2021-08/msg00034.html
Attachment:
ellipsis-spacing.man
Description: Unix manual page
Attachment:
ellipsis-spacing.png
Description: PNG image
Attachment:
signature.asc
Description: PGP signature
