Hi Branden, G. Branden Robinson wrote on Thu, Jun 27, 2019 at 10:13:40AM -0400:
> commit 4e5439d9827232a1910bda5cac6ccea8d00243f6 > Author: G. Branden Robinson <g.branden.robin...@gmail.com> > 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