Re: [groff] 09/10: groff(1): Fix error in example.

[G. Branden Robinson]

Hi Dave,

At 2022-08-05T18:10:45-0500, Dave Kemper wrote:
> > --- a/src/roff/groff/groff.1.man
> > +++ b/src/roff/groff/groff.1.man
> > @@ -1801,7 +1801,7 @@ constructing a pipeline to page the output.
> >  .RS
> >  .P
> >  .EX
> > -groff \-t \-man /usr/share/man/man1/groff.1.man | less \-R
> > +groff \-t \-man -Tutf8 /usr/share/man/man1/groff.1.man | less \-R
> 
> The trivial problem with this change is that the \ in front of the new
> -T flag is missing.

Yes, indeed!  I'll fix that.

> The slightly larger problem is that it hard-codes into the man page
> text an assumption about the user's encoding environment.  Were this
> difficult to avoid, that'd be one thing, but all that would have
> change is the "groff" command to "nroff," since nroff.sh is pretty
> robust at figuring out the user's encoding.  And nroff has already
> been mentioned on this page a few times, so it wouldn't be coming out
> of left field at this point.

Yes, but I think you're missing the context.  This is an _example_.

.\" ====================================================================
.SH Examples
.\" ====================================================================
.
.I roff
systems are best known for formatting man pages.
.
Once a
.MR man 1
librarian program has located a man page,
it may execute a
.I groff
command much like the following,
constructing a pipeline to page the output.
.
.
.RS
.P
.EX
groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1.man | less \-R
.EE
.RE

I think the section title and phrases like "much like the following" cue
the reader to not slavishly copy and paste without consideration.

Similarly, I avoided demonstrating nroff because this is the groff(1)
page, and that is the subject of discussion.  Examples of nroff usage
are better placed in its own page.  Beyond that, it is important to
reinforce the fact that the nroff command does nothing that can't be
accomplished with the groff command, in contrast to (some? all?) other
troff implementations.

I added the foregoing example because unfortunately it seems to be a
mystery to many people how to get groff to directly render a man page,
and I wanted to call attention to the method.  This is important
background for addressing the religious fervor with which people oppose
grotty(1)'s emission of SGR escape sequences.[1]  If your terminal
(emulator) interprets them without the pager, but using the pager messes
up rendering, then the fault is with the pager, not grotty.

Regards,
Branden

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=312935

signature.asc
Description: PGP signature