Re: [groff] 04/05: {g, n}roff.1.man: Give assistance to pager users.

[Ingo Schwarze]

Hi Branden,

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

> commit 4e5439d9827232a1910bda5cac6ccea8d00243f6
> Author: G. Branden Robinson <address@hidden>
> Date:   Wed Jun 26 20:32:31 2019 +1000
> 
>     {g,n}roff.1.man: Give assistance to pager users.
>     
>     Many users (I was one of them) did not know why pagers degraded nroff
>     output.  Give people a hint where to look for help.
>     
>     The application of screen-paging utilities to cp1047-based output
>     devices is conjectural on my part; I have no experience with EBCDIC
>     systems.
> ---
>  src/roff/groff/groff.1.man | 22 ++++++++++++++++++++++
>  src/roff/nroff/nroff.1.man | 13 +++++++++++++
>  2 files changed, 35 insertions(+)
> 
> diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
> index 165507e..c943c90 100644
> --- a/src/roff/groff/groff.1.man
> +++ b/src/roff/groff/groff.1.man
> @@ -1611,6 +1611,28 @@ groffer foo.me
>  .
>  .
>  .\" ====================================================================
> +.SH NOTES
> +.\" ====================================================================

Please do not add "NOTES" sections.  That section header is non-standard
and in particular a formatting tool like groff should set an example
for other software in avoiding it.

Besides being non-standard, it also makes no sense logically.  The
title "NOTES" is totally non-descriptive and doesn't tell the reader
what to expect in the section.  If a page is long and complicated
such that subdividing the DESCRIPTION into multiple sections makes
sense, the content should be structured logically with section
titles clearly summarizing the content of each sections.

In practice, "NOTES" sections are mostly used by documentation of
inferior quality, OpenSSL being particularly notorious for it:
content is not presented once in a consistent manner, but first
addressed incompletely, leaving out random aspects, and then it is
explained again, typically in a wordy and repetitive manner, below
NOTES.

In the case at hand, the natural place to explain this is at either
of these places:

 - below -T
 - or below -c
 - or below "Postprocessors"

(Yes, the groff(1) manual page already is somewhat repetitive in this
respect, which is another reason to not add yet another section
discussing the same topic as an afterthought).

> +When paging output for the
> +\[lq]ascii\[rq],
> +\[lq]cp1047\[rq],
> +\[lq]latin1\[rq],
> +and
> +\[lq]utf8\[rq]
> +devices,
> +programs like
> +.IR more (1)
> +and
> +.IR less (1)
> +may require command-line options to correctly handle some output
> +sequences;
> +see
> +.IR \%grotty (@MAN1EXT@).

On top of the above, i consider that bad advice.  If you think people
need to be told about roff's bad habit of defaulting to SGR escapes,
then let's recommend groff(1) -c rather than less(1) -R.

> diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man
> index 4969f28..4e4e086 100644
> --- a/src/roff/nroff/nroff.1.man
> +++ b/src/roff/nroff/nroff.1.man
> @@ -81,6 +81,7 @@ formats documents written in the
>  .IR roff (@MAN7EXT@)
>  language for typewriter-like devices such as terminal emulators.
>  .
> +.
>  .P
>  GNU
>  .I @g@nroff
> @@ -235,6 +236,18 @@ is unset.
>  .SH NOTES
>  .\" ====================================================================

Ouch; nroff(1) already has a NOTES section - given the existing content,
it should actually be a FILES section.  Alternatively, the text could
be moved to the DESCRIPTION, to become the third paragraph.  The nroff(1)
page isn't so long that it needs subdivisions.

> +.P
> +Pager programs like
> +.IR more (1)
> +and
> +.IR less (1)
> +may require command-line options to correctly handle some output
> +sequences;
> +see
> +.IR \%grotty (@MAN1EXT@).

Same point again: please recommend groff(1) -c rather than less(1) -R.

Yours,
  Ingo