Re: Rendering the Bash man page with commercial Unix/System V nroff

[G. Branden Robinson]

Hi Chet,

At 2024-02-12T14:45:30-0500, Chet Ramey wrote:
> On 2/12/24 2:00 PM, G. Branden Robinson wrote:
> > 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?
> 
> I just ran out of steam.

Oh!  That possibility had not occurred to me.  :-O

> > 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]
> 
> I wonder if there's a way to make Solaris use the pre-formatted
> nroffed versions of the man pages that are in the bash distribution.

In theory, maybe.  (These are historically called "cat pages", because
you can cat(1) them and not get a face full of *roff syntax.)  But...

1.  The Solaris 10 system to which I have access (via the FSF France's
    compiler farm) seems to be configured to not use /usr/share/man/cat*
    directories.  Not for the _system_ (more on this later).

2.  /opt/csw/share/man/man1 seems to have a more modern Bash man page in
    it, 4.3.  That's good.  But no /opt/csw/share/man/cat* directories
    are present, either.

3.  They don't appear to be part of the relevant Solaris packages.

      $ egrep 'bash\.[0-9]+' /var/sadm/install/contents
      /opt/csw/share/man/man1/bash.1 f none 0644 root bin 299110 17440 
1424016035 CSWbash
      /usr/share/man/man1/bash.1 f none 0444 root bin 250091 11343 1344856607 
SUNWsfman
      /usr/share/man/man1/rbash.1 f none 0444 root bin 612 48562 1344856608 
SUNWsfman

I therefore don't think you're going to have any luck unless you can (1)
get Solaris 10 to restore(?) support for cat pages; (2) get whoever's in
charge of preparing Solaris packages to rebuild Bash's packages to
include the cat page; and (3) convince the people involved in (2) to do
this for a system that is on the ragged, unraveling telomere of support.

Maybe (1) isn't an issue.  Maybe there's a system-configgy option that
enables cat pages.  And maybe package installation payloads are filtered
by it, taking care of (2).  That leaves barrier (3).

But if you're only concerned about people doing their own builds of Bash
from source, I think the answer is yes!

I scp'ed the doc/bash.{1,0} files from my Git checkout of the Bash devel
branch to the Solaris 10 host, placing them in $HOME/share/man/man1 and
$HOME/share/man/cat1, respectively.

$ man -M $HOME/share/man bash

(equivalently,

MANPATH=$HOME/share/man man bash
)

...worked fine, taking noticeable time to render and showing me a Bash
5.3 page.

Running it again rendered much faster.  I looked, and the system man(1)
apparently ran catman(1) for me.

Unfortunately that means it wasn't the pre-formatted version, but one
rendered by rotten old Solaris 10 nroff.

$ man -M ./share/man bash | grep '<<='
     = *= /= %= += -= <<= >>= &= = |=

------- should be ~= ------------^

So I clobbered it.

$ cp $HOME/share/man/cat1/bash.0 $HOME/share/man/cat1/bash.1

Lo and behold, I get a good result--complete with working boldface, not
just italics^Wunderlining.[1]

The ~= shows up correctly, but I can't illustrate that with an obvious
grep because the overstriking sequences defeat my simple pattern.

Unfortunately (depending on how you look at it), touch(1)ing the bash.1
source document provokes catman(1) into replacing the pre-rendered page.

So I guess what you might want to do is have the installation procedure
on Solaris 10 install bash.0 as $DESTDIR/share/man/cat1/bash.1.  (I
haven't looked into Bash's build process at all.)

Does this help, or influence your appetite for maximal portability vs.
sending a bouquet to the funeral service I'm holding for System V troff?

Regards,
Branden

[1] I can't account for why DWB 3.3 nroff, a fairly close relative of
    Solaris 10 troff, (correctly) overstrikes characters with themselves
    to produce bold when rendering for a Teletype Model 37, while
    Solaris 10 troff does not.  Nor do I mean to look into it.  But I do
    find it a pretty ironic defect given the depth of SunOS 4.0's
    commitment to expanded use of boldface in man pages.[2]  But I
    remember that front in the Unix wars.  Many champions of SunOS 4
    viewed Solaris with the deepest contempt.  I guess this aspect of
    Kernighan *roff simply fell off of Solaris and no one put it back.

[2] https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html
    https://lists.gnu.org/archive/html/groff-commit/2023-08/msg00030.html

signature.asc
Description: PGP signature