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

[Ingo Schwarze]

Hi Branden,

thanks for working on groff documentation again.  :-)

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


G. Branden Robinson wrote on Thu, Jun 27, 2019 at 10:13:40AM -0400:

> commit 0da230cd81eb5dc8b3c37c0060a5c16aa61b64bc
> Author: G. Branden Robinson <address@hidden>
> Date:   Sun Jun 16 00:43:26 2019 +1000
> 
>     nroff.1.man: Make editorial fixes.
[...]
>     * Describe the tabs produced by the "-h" option as "hard", since that
>       is a possible mnenmonic for the flag.
>     
>     * Refer to the "old" output scheme as "legacy" (a parallel change to
>       grotty(1) is forthcoming).
>     
>     * Indicate the context of the unexplained "SGR" jargon--ISO 6429.
[...]
> diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man
> index 516b412..e0267a7 100644
> --- a/src/roff/nroff/nroff.1.man
> +++ b/src/roff/nroff/nroff.1.man
[...]
> @@ -139,9 +141,9 @@ are equivalent to
>  .IR grotty 's
>  options
>  .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.
This is merely a reference that ought to be concise.

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.

Here, i think "using tabs in the output" is sufficient.
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.

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.

>  .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.

I consider backspace encoding far superior to ISO 6429 SGR for
security reasons.  Backspace encoding always works, and with no
risk, whereas using ISO 6429 SGR would require using the scary
less(1) -R option.

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.

Yours,
  Ingo