groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Ingo Schwarze
Subject: Re: [Groff] Critique this bold-italic private macro for man pages
Date: Thu, 4 May 2017 00:30:50 +0200
User-agent: Mutt/1.6.2 (2016-07-01)

Hi,

Carsten Kunze Heirloom wrote on Wed, May 03, 2017 at 09:37:21PM +0200:

> I assume also mandoc(1) reads \(.g as 1.

Yes:

 $ echo '\\n(.g' | mandoc | sed -n 5p   
1

 $ less /co/mdocml/roff.c
int
roff_getreg(const struct roff *r, const char *name)
{
        int val;

        if ('.' == name[0] && '\0' != name[1] && '\0' == name[2]) {
                val = roff_getregro(r, name + 1);
                if (-1 != val)
                        return val;
        }
        /* ... handle read-write registers ... */
}

/*
 * Handle some predefined read-only number registers.
 * ...
 */
static int
roff_getregro(const struct roff *r, const char *name)
{
        switch (*name) {
        case 'g':  /* Groff compatibility mode is always on. */
                return 1;
        /* ... handle some other read-only registers ... */
        }
}



It's a pervasive pattern:  When writing portable software (or in
this case, portable documentation), and when trying to figure out
whether the platform we are currently trying to run on supports a
given feature we wish to use, *never* test for software or operating
system names or for version numbers.  That plainly doesn't work in
practice: If you test for names, the functionality of those programs
or systems will change over time, and if you test for version
numbers, you will run into implementations you never considered
(and hence don't know any version numbers for) but that still support
the feature, or you run into implementations that do have version
numbers, but where they mean something completely unexpected.

For software, write feature tests instead and configure your software
accordingly for compilation.

For manual pages, do not write any test code at all.  If you put
your feature tests into the manual pages themselves, they are not
only exceedingly ugly, but often a bigger portability problem than
the features you are trying to test for in the first place.  If you
keep the feature tests separate and try to automatically edit the
manual page source code accordingly before installing the manual
pages, that usually turns into a maintenance nightmare.  Manual
pages just don't need the compilation step that program code needs,
and inventing one just for autoconfiguration purposes is seriously
going over the top.

If writing man(7), stick to the lowest common denominator features
that are supported by practically everything.

If writing mdoc(7), write it for the modern standard as documented
in groff_mdoc(7) and mandoc mdoc(7).  Heirloom copes with that as
well, and legacy implementations are virtually inexistent.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]