Re: [groff] 02/04: grotty.1.man: Make editorial fixes.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Jun 30, 2019 at 05:19:43AM -0400:

> commit c105b1725cc928e225d23237f3cf1a7a5239d5ba
> Author: G. Branden Robinson <address@hidden>
> Date:   Thu Jun 27 22:14:50 2019 +1000
> 
>     grotty.1.man: Make editorial fixes.

Thanks; overall, these seem to be impovements.

(Ignoring a few points we already know we disagree on, like the
 artificial complication of the SYNOPSIS, and ignoring that we
 disagree about whether to recommend -c rather than encouraging
 the scary less -R)

There is one detail that should really be removed though, i think:

> +When paging
> +.IR grotty 's
> +output with
> +.IR less (1),
> +it is necessary to use either the
> +.B \-r
> +or the
> +.B \-R
> +option of the latter for SGR sequences to be rendered correctly.

It would be better to say that

  When paging
  .IR grotty 's
  output with
  .IR less (1),
  it is necessary to use the
  .B \-R
  option of the latter for SGR sequences to be rendered correctly.

The -R option is already scary.  The -r option is even worse,
introducing substantial security risks *and* usually resulting in
broken output, too.  We should absolutely not recommend it.  Mentioning
it causes the totally misleading impression that it might provide
any benefit at all in the groff context.

People who are reckless enough to consider using it for other reasons
can see easily enough in the less(1) manual that it implies -R.

> +Consequently,
> +programs like
> +.IR man (1)
> +which page
> +.I roff
> +documents with
> +.I less
> +must pass one of these options to it.

In case you change the above, this needs to be adjusted, too.

Yours,
  Ingo