Rendering the Bash man page with commercial Unix/System V nroff (was: [PATCH 17/18] doc/bash.1: migrate to strings for troublesome characters)

[G. Branden Robinson]

Hi Chet,

I see that most of my proposed man page changes from the recent series
landed in the devel branch.  Thanks!

I did notice that this one and its follow-up did not.  Was that on
purpose?  Is there something I can do to improve the patch?

The reason I submitted 17/18 and 18/18 is because, out of the box,
Solaris 10 nroff won't render the special characters \(ha and \(ti,
which does some violence to the Bash man page.[1]

Here are two examples.

At 2024-01-31T02:43:45-0600, G. Branden Robinson wrote:
> Diff of rendering (DWB):
[...]
> -                 An additional binary operator, =, is available, with
> +                 An additional binary operator, =~, is available, with
> 
> -                 string.  Anchor the pattern using the  and $ regular
> +                 string.  Anchor the pattern using the ^ and $ regular

The fix for DWB 3.3 is really straightforward.

$ diff -u lib/nterm/tab.man{,.new}
--- lib/nterm/tab.man   2024-02-12 05:30:56.265300808 -0600
+++ lib/nterm/tab.man.new       2024-02-12 11:53:28.357145394 -0600
@@ -26,6 +26,8 @@
 left   ""

 charset
+ha 1 ^
+ti 1 ~
 em 1 -
 hy 1 -
 \- 1 -

I just now tested this on a real Solaris 10 host, and as expected, it is
consistent with Documenter's Workbench (DWB) 3.3 behavior.  Solaris 10
troff seems to still default its nroff output to the Teletype Model
37.[2]  So one could do the same thing for the "tab.37" file in
/usr/share/lib/nterm.

$ diff -u tab.37*
--- tab.37      Mon Feb 12 19:07:35 2024
+++ tab.37.new  Mon Feb 12 19:07:58 2024
@@ -26,6 +26,8 @@
 left   ""

 charset
+ha 1 ^
+ti 1 ~
 em 1 -
 hy 1 -
 \- 1 -

But I admit I wasn't able to actually test this since I don't have root
privileges on the Solaris 10 host I'm using, and AT&T nroff doesn't
offer a way to point it at a user-specified set of driving tables.[3]

On the other hand, Solaris 10 troff is the only data point I have of a
deployed system still using a System V troff.  And I don't know if any
people using System V Unices care anymore about good man page rendering.

(As far as I know, the _only_ use case for DWB 3.3 troff, a System V
troff, is for retrocomputing and historical research.  It's invaluable
to me for the latter purpose.)

My plan had been to discontinue offering advice for man(7) document
portability to System V troffs like DWB and Solaris's once Oracle
finally EOBed Solaris 10, but they keep staying its execution.[4]
And maybe there is no point waiting for that day if that Solaris 10
lives only in lights-out environments where no one reads man pages.[5]

So maybe I should discontinue that sort of advice now instead of
waiting.  Chet, what would you prefer with respect to Bash?

So I'm looping in the groff list to try and get any users of such
systems to speak up.

I'm also attaching a sample document that people can use to test the
nroff(1)/man(7) on their system.

Here's how I tested it with groff, mandoc(1), Heirloom Doctools, and DWB
3.3.  The location of your installed groff will likely differ.

$ ~/groff-stable/bin/nroff -t -man manexercise.man
$ mandoc manexercise.man | ul
$ ./bin/tbl manexercise.man | ./bin/nroff  -man | ul
$ DWBHOME=. ./bin/tbl manexercise.man | DWBHOME=. ./bin/nroff  -man | ul

(The pipe through ul(1) is necessary with non-GNU nroffs to convert the
output from Model 37-oriented overstriking sequences to the escape
sequences suitable to produce varying font styles on the terminal.  AT&T
nroff preceded termcap and terminfo by several years and as far as I
know, no one ever migrated it to use either one, even long after
teletypewriters were abandoned as terminal devices.  If your system
doesn't have ul(1), use col(1).)

Anyway, Chet, let me know how much portability you'd like for Bash's man
pages in the next release and I'll do my best to assist.

Regards,
Branden

[1] The Bash available on Solaris 10 is 3.2; its man page uses the older
    convention of employing ^ and ~ literally, which does _different_
    violence to man page rendering for the presumably more numerous
    users on other POSIX systems employing UTF-8-capable terminal
    emulators, or those actually typesetting the manual.

[2] Per the following experiment.

.TH foo 1 2024-02-12 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
We're rendering this page for device \*(.T.

    And fair enough--that's consistent with Seventh Edition Unix, if
    impressively un-useful for decades now.

[3] This is an old bit of terminology particular to AT&T troff/nroff.
    https://www.ibm.com/docs/en/aix/7.2?topic=n-nroff-command

[4] 
https://blogs.oracle.com/solaris/post/new-end-date-of-extended-support-for-oracle-solaris-10-and-113
[5] Solaris 11 uses groff 1.22.3.

signature.asc
Description: PGP signature