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

[G. Branden Robinson]

Hi Ralph,

I think some context might have gotten lost.  As I said at the outset of
this thread, my opinions about the portability of this ".BOLD-ITALIC"
macro are _strictly confined_ to the writing of a non-groff man page for
a highly specialized package that in practice just does not get
installed in legacy environments.

At 2017-05-04T10:24:09+0100, Ralph Corderoy wrote:
> Hi Branden,
> 
> > Ingo wrote:
> > > There are real-world systems (sold today) where neither \(lq nor the
> > > 'c' conditional is supported.
> 
> And I know from experience that they become much more palatable after
> building source for better versions of their binaries, and adding new
> programs they don't have.  That source builds, and man pages format, on
> these POSIX systems is a real benefit to those stuck using them.  And
> `install groff' isn't an answer because permission often needs to be
> sought for each.

While thanks to Autoconf, many GNU (and non-GNU) packages--including
groff--build, install, and work just fine with --configure=$HOME, I
agree with you.

Tools targeting legacy systems, including GNU tools, should be highly
mindful of portability.

Similarly, there are multiple levels of shell script portability:

1.  You can write to the conventions of a particular shell, and
    preferably document that.  For instance, in my Bash startup files I
    have a conditional like this:
                        # Load my shell functions.
                        if [ ${BASH_VERSINFO[0]} -ge 3 ]; then
                            . "$HOME"/.${USER}_lib_bash
                        else
                            . "$HOME"/.${USER}_lib_bash2
                            warn "very old Bash: $BASH_VERSION"
                        fi

2.  You can write to the IEEE/POSIX standard shell.

3.  You can write for maximum portability, forgoing many POSIX features
    and resigning yourself to obfuscated and/or pretzel-like
    constructions to get the functionality you want.  See:
      
https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Portable-Shell.html

Autoconf macros and supporting shell scripts are written at level 3
because they have to be, otherwise they lose the plot.

This absolutely, emphatically does not mean that everyone should always
be writing their shell scripts in that lowest-common-denominator,
most-portable dialect.  In fact, doing so makes scripts harder to read,
understand, and maintain.

Personally, I prefer to write in militantly portable POSIX shell unless
the problem domain absolutely screams for a Bash feature.  And if that
keeps happening in the same script (or group thereof), for multiple
features, I start considering if I shouldn't be writing in, say, Python
instead.

In my opinion, a big problem with man page portability is that we don't
have categories as well-defined as those for the shell, above.

A.  There does not exist a document describing many of the bugs and
    caveats in legacy *roff and man macro package implementations that
    a conscientious man page writer needs to know.
B.  *roff (and therefore the macro packages based thereupon) are not
    formally standardized.  I just now re-checked
      http://pubs.opengroup.org/onlinepubs/9699919799/
    to be sure.
C.  Even the very conditional construct we might use in-language to
    test for the availability of features and the identity of
    implementations becomes non-portable if we try to apply it to that
    goal.

> > Why do my man pages need to be more portable the shell scripts or C
> > code I ship with them?
> 
> Yours don't, but don't constrain the rest of us, or lead us astray with
> non-portable -man extensions that will just increase the problems on
> systems you don't use.

I'm not attempting to constrain anyone else, or lead anyone astray with
what I said in the thread title was a _private_ macro.

My objective in starting this thread was to get expert opinion on
whether the macro was written well or badly, from an audience of *roff
experts.

> > I refuse to write shell scripts for general-purpose consumption only
> > in the historical Bourne dialect that Solaris /bin/sh was
> 
> Again, that's your choice.  Many of us go to the effort of writing
> portable code, and coping with the issues from those using it on less
> common systems, including proprietary ones.

I value portability intensely as well.  However, the portability of a
software package is often constrained by multiple factors.  To my view,
it makes no sense to write a man page for a software package to a lower
common denominator than is supported by the environments demanded by the
rest of the package.

The macro I set forth in this thread is for a non-groff, non-GNU
package.  I wanted to know if I had written it competently.

If there existed a groff-help mailing list (or better yet, roff-help), I
would have used it.

> > 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.
> 
> If your viewpoint is "it's Linux, Mac OS X, or BSD, or it doesn't exist"
> then I don't think it counts for much in considering changes to groff,
> -man, mdoc, etc., that have a wider impact.

How many times do I have to emphasize that the "bold italic" macro I
pitched in this thread is *** NOT *** something I intend to propose as a
change to groff, man, or mdoc?

You're welcome to disregard my views as a (new) groff contributor, but
you won't do any of us any good if you impute to me attitudes I do not
possess.  Please do me the courtesy of evaluating proposals I actually
make based on principles I actually espouse.

Regards,
Branden

signature.asc
Description: PGP signature