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
