Re: [Groff] Critique this bold-italic private macro for man pages

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Wed, May 03, 2017 at 08:52:42PM -0400:

> Why do my man pages need to be more portable the shell scripts
> or C code I ship with them?

They need not, but i would consider aiming for about the same level
of portability reasonable.  Meaning, that they work on systems that
you target.

> What is the value in reading the _formatted_ version of a man page
> for a tool that won't compile or run correctly on the host?

That's indeed not very high priority, but why do you think that
any (reasonably portable) software would not run on Solaris 11?

I do not want to promote Oracle software, and in fact i use none
for my own purposes.  But Solaris 11 is a certified UNIX system
conforming to the 2016 edition of the Single UNIX Specification,
version 4:

  https://www.opengroup.org/openbrand/register/brand3585.htm

That implies that the native compiler conforms to ISO C 99
and that the native /bin/sh is a POSIX shell.

> I refuse to write shell scripts for general-purpose consumption
> only in the historical Bourne dialect that Solaris /bin/sh was,

That doesn't apply to Solaris 11.

> and I refuse to write man pages for general-purpose consumption
> only in some minimal common subset that _no one_ has troubled
> themselves to carefully define.

Admittedly, C and sh(1) are well standardized, and man(7) is not.
All the same, would you want your manual pages to break on systems
where your program compiles and runs just fine?

Yes, Solaris typically does need some porting work for code that
is mostly developed on BSD or Linux, even though it is a POSIX
system.  But porting is usually not a big deal.  At least not for
Solaris 11.  Solaris 9, on the other hand, is a bit more of an
adventure, but i didn't talk about the nroff you might find there,
either.

[...]
> For example, even if that old Solaris system

I often snarkily call any version of Solaris "archaic software"
myself.  All the same, this particular system is a very new system
on sale today.

> can render the output of docbook-to-man legibly,

It absolutely cannot.  On that system, even though it is the newest
that you can buy from Oracle today, any kind of docbook-to-man
output will fall flat on its face before it even finds the time
to be surprised enough to utter a grunt.

[...]
> Finally, Groff's own portability is sufficiently broad that we should be
> able to say, "as a rule, if you want man pages written in the past 25
> years to render nicely on Boozix 11.0, Gizmoware's custom hybrid of
> 4.3BSD and SVr3, please build and install Groff so that its macro
> packages can achieve this for you."

As a matter of fact, groff is already installed on that system:

 $ groff -v | head -n1
GNU groff version 1.19.2

It is a very new Solaris system and not exactly the newest groff
available.  So, you want to use groff?  Fine, read the manual!

 $ man groff 2>&1 | cat
Reformatting page.  Please Wait... done
 $ echo $?
0

Hum.  It looks like that manual page uses features that the native
man(1) cannot handle, likely because it uses the native nroff(1).

So, to read the groff manual pages, you already need to know how to
use groff:

 $ gnroff -c -mandoc /usr/share/man/man1/groff.1 | less

Voila.  Now it works.


I admit such a system is hard to use, and i wouldn't use it for
productive work myself.  But completely dismissing it when
talking about "portable software" is not gonna cut it.

Oh, by the way, if you don't like the native shell:

 $ bash --version | head -n2
GNU bash, version 4.1.17(1)-release (sparc-sun-solaris2.11)
Copyright (C) 2009 Free Software Foundation, Inc.

Same pattern as with groff: Not at all up to date, but *something*
is there that is maybe almost acceptable for some purposes.

Yours,
  Ingo