Re: reformatting man pages at SIGWINCH

G. Branden Robinson
2023-04-17T06:23:47Z

[-- Attachment #1: Type: text/plain, Size: 3234 bytes --]

[CC list trimmed of Texinfo people/lists]

At 2023-04-11T11:39:11+0200, Dirk Gouders wrote:
[I wrote:]
> > 4. A habit has grown up among man(1) programs and pagers to call
> > for and support, respectively, a "blank line squeezing" feature: any
> > runs of more than one blank line are condensed to 1 blank line each.
> > In groff 1.23.0, this will no longer be necessary when continuously
> > rendering. (Historically, this squeezing feature was used to
> > "tighten up" vertical space after the page header, prior to the
> > "NAME" section heading of the document.) In my opinion, pager
> > programs should perform as few transformations as possible on the
> > output of grotty(1), the groff output driver that supports terminal
> > devices. The long-time author and maintainer of less(1) does not
> > agree, so you have to call that program with its "-R" flag to view
> > grotty(1) output as groff intends it. (To see what those intentions
> > are, format the document without paging it.)
>
> Thank you for the detailled assessment. Perhaps my misunderstanding
> is because I'm not a native speaker but which document should I format
> to see what those intentions are?

Just about any man page will do. By "intentions" I mean things like
typeface changes and, in the forthcoming groff 1.23.0,[1] OSC 8 escape
sequences to encode hyperlinks.

For instance, if I want to look at groff_man(7)'s man page without the
intermediation of man(1) or a pager, I can do this.

$ man -w groff_man # to tell me where the document is installed
/usr/share/man/man7/groff_man.7.gz
$ zcat $(!!) | nroff -t -mandoc

I recommend the above as an early troubleshooting step with rendering
problems, though your terminal emulator may need a lot of scrollback
buffer, depending on the document.

(On rare occasions, a document may require a preprocessor other than
tbl(1), but the parts that use them generally won't produce good (eqn)
or any (pic) results on terminal devices. "-t -mandoc" should suffice
for well over 95% of man pages.)

> > Since I flogged groff 1.23.0 three times in this email, I suppose I
> > should point people to where they can get the 1.23.0.rc3 release
> > candidate source archive. Feedback would be appreciated.
>
> Oh well, I didn't measure it but I spent quite some time to work on
> doc/lsp-help.1 and try to find a solution for that "nasty empty line"
> that appeared in of the tables that I use for the online help -- I was
> convinced it was my fault.

I am sure a lot of people thought that. I was quite pleased to track
down and stomp that bug.

> Gentoo already has an ebuild for groff-1.23.0-rc3 and simply using
> this fixes that problem in the table. So, from now on all my testing
> happens with groff-1.23.0-rc3 and I will report should I recognize
> problems.

Please do. Bruno Haible has found a passel of portability problems to
non-GNU/Linux systems, and helped us to resolve several of them; I am
hopeful that 1.23.0 will be the most easily deployed groff in quite some
time.

Regards,
Branden

[1] We just tagged and put out 1.23.0.rc4 this past weekend.

https://lists.gnu.org/archive/html/groff/2023-04/msg00135.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]