Re: [groff] 02/05: nroff.1.man: Make editorial fixes.

[G. Branden Robinson]

Hi Ingo,

GMail is marking your mail as spam again.  This would be amusing if it
weren't so irritating.  Your email address has not changed; why do I
have keep to telling Google your mail is not spam?

At 2019-06-29T17:18:12+0200, Ingo Schwarze wrote:
> Hi Branden,
> 
> thanks for working on groff documentation again.  :-)

I'm settled in at the new job and the new continent and got itchy to
improve the state of the world's technical documentation again.  ;-)

> However, i have two comments on this commit, maybe you wish to
> reconsider.

People were so quiet I thought I had successfully ducked controversy...

> >  .B \-h
> > -(using tabs in the output) and
> > +(use hard tabs in the output) and
> 
> While i see the point of explaining the mnemonic, this is not the
> place.

I disagree with that rather stridently.  This is _exactly_ the place to
explain why single-letter option names make any sense at all.  Where on
Earth do you think a better place is?  The local sysadmin?  Stack
Overflow?

The point of documentation is to demystify.  One advantage of GNU long
options, which as I recall you dislike, is that they can use a corpus of
many thousands (closer to 10^6) of English words to communicate their
meaning.

With single-character options you have a space of roughly 50.  Closer to
30 when we remember that few people distinguish semantic meaning by
letter case.

It's pot luck what "-l" means with a traditional Unix command.  I gather
that's the way the BSD world likes it, but I think it's hopeless without
documentation.

So I violently oppose not explaining option mnemonics in man pages for
similar reasons that I oppose the exasperating tradition of classical
Unix source code to have command-line options drive variable names in
the source code like this:

        oflag = 1;

I have a boolean (not really, because boolean types are for wimps, and
waste space better spent on bitfields).  It's called "O flag".  Great.
I know exactly what this means if I've located the documentation, which
is not the man page, that explains it.

In the dissipated and decadent C99, we might say:

        bool optimize = true;

or even (my preference with Booleans is to give them a helping verb so
if and while expressions are harder to misunderstand):

        bool do_optimize = true;

Whoa!  A reader might actually infer that the flag indicates the user's
intention to have the command optimize whatever it's doing!  They might
not need to turn to the local Unix club wizard who has access to a paid
Unix license and the real documentation marked up with the ms macro
package!

> This is merely a reference that ought to be concise.

Only to the point that we don't start throwing out meaning that is not
captured elsewhere that the user can readily find it.

> Besides, while i do see some scattered uses of the term "hard tab"
> for the character U+0009 on the web, i consider it jargon at best,
> imprecise and obscure at worst (at least i had to look it up to
> understand what it is even supposed to mean).  Arguably, it is also
> a blatant misnomer because depending on editor or environment
> settings, the display width of the U+0009 tab character can be
> flexible, which sounds like exactly the opposite of "hard".
> So i think we should avoid the term "hard tab" - except maybe at
> one single place for explaining the mnemonic.

Now, to be more conciliatory, I'm not wedded to the word "hard"--someone
later in the thread suggested "horizontal", and I'd be fine with that.

> If you worry that people could misunderstand, "using tabs instead
> of spaces in the output" would be perfectly clear and not much
> longer without relying on obscure jargon.

This is fine except for the fact that it reveals nothing about why the
letter "h" was chosen.

> grotty(1) should probably say something like:
> 
>   -h  Use ASCII horizontal tab characters ("hard tabs")
>       in the output instead of strings of multiple spaces.
>       Tab stop positions are assumed to be set every 8 columns.
> 
> Saying just "ASCII" is sufficient because that's a subset of latin-1
> and UTF-8, too.

Have I pushed my overhaul of grotty(1) yet?  Hmm, I don't think so.

Yeah, I have something like this coming.  Despite the vigor my
disagreement with you above, I find little to differ with in your
concrete example.

> >  .B \-c
> > -(using the old output scheme instead of SGR escape sequences).
> > +(use the legacy output scheme instead of ISO 6429 SGR escape sequences).
> 
> I strongly dislike both "old" and "legacy" in this context.
> Please call it "backspace encoding", or "traditional backspace
> encoding" if you must.

"traditional backspace coding" is several characters than "legacy output
scheme", so by the metric you proposed above, I pronounce it inferior.
:P

That said, I'm not wedded to the word "legacy".  Many of our man pages
make reference to "classical" *roff...

> I consider backspace encoding far superior to ISO 6429 SGR for
> security reasons.

I strongly disagree with this.  Implementations need not support every
feature described by ISO 6429 and historically, I know of nothing that
actually does.  The standards committee seems to have gotten carried
away and added stuff like double-underlining and underline analogues
applied for the other 3 rectangular edges of the character cell that
nothing, or almost nothing, actually implements.

For several years, xterm has supported true italics (well, "obliques" at
any rate), and I found it interesting to view man pages with them in
lieu of underlining.  ("grotty -i" for those who are interested.)

> Backspace encoding always works, and with no risk, whereas using ISO
> 6429 SGR would require using the scary less(1) -R option.

I'm not about to defend the design choices of the "less" program.  But
grotty doesn't output any ISO 6429 escape sequences that are inherently
a security risk.  Do you disagree?

> Backspace encoding is so much superior that for example mandoc(1) 
> does not, and never will, provide an option to use ISO 6429 SGR
> but is hardcoded to always emit backspace encoding.

I think that's madness, but I am an occasional user of mandoc at best.

Regards,
Branden

signature.asc
Description: PGP signature