Re: [PATCH 4/9] man/clear.1: Migrate macro usage conventions.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Mon, Oct 02, 2023 at 11:53:51AM -0500:

> Turns out I can reproduce this after all.  But I have to call mandoc(1)
> with its "-Tlint" option; it doesn't occur (for me) in ordinary use.

Yes, see https://man.openbsd.org/mandoc#DIAGNOSTICS

 "Messages of the base, style, warning, error, and unsupp levels are
  hidden unless their level, or a lower level, is requested using a
  -W option or -T lint output mode."

[...]
> The `.g` register only gives you some of the story--that the formatter
> claims to support groff extensions.  But that is susceptible to false
> positives _and_ false negatives.  Any non-groff formatter could define
> a register named `.g`,

Correct so far.  That's also unavoidable because the meaning of the
term "groff extensions" changes over time.

In general, a flag (one single bit of information) is next to useless
in describing supported functionality.  Providing a version number -
like, for example, C language standards do it - isn't very good
either bcause different implementations can introduce features in
different orders, and may have good reasons to decline support for
some older features indefinitely.

Consequently, in autoconfiguration systems, *never* test for version
numbers or program names, always use feature tests as specific as
possible.

Needless to say, feature testing is not possible in manual page source
code, but that doesn't change the fact that attempting to test for
program names (with .g) or version numbers is more likely to cause
frustration to all involved parties than to help with good formatting.

If you *really* want to support systems running old Kernighan troff,
then you have no reasonable choice but to use 1979 Version 7 UNIX
man(7) syntax and nothing else, which obviously implies that your
manual pages will not benefit from any language and formatting
improvements developed since then, and hence will be less useful
on modern systes.  Yes, that's a tradeoff.  Trying to be extra clever
and combining the best of both worlds in the manual page source code
is more likely to actually result in combining the worst of both
worlds - unreliability on both historical and modern systems.

I see one way out that is likely to yield both good results on modern
systems and passable results on historical systems.  Write your pages
using a reasonably modern version of the language, such that they
work well on modern systems and are easy to maintain.  Install the
manual pages as-is by default, containing not a single .de and not
a single .if.

When you use a modern feature - say, for example, .EX/.EE - and
get reports that it doesn't work on their system from some of your
users: write a configuration test for the feature, run that test
at the ./configure stage, and if the configuration test fails, run
a custom script that downgrades the feature in the installed pages
during installation.  For example, your script might replace .EX with
something like

  .nf
  .ft CW

and .EE with something like

  .ft R
  .fi

It doesn't need to be fancy, no need to bother supporting nesting
of .EX in itself or inside surrounding .ft or .PD etc. etc. because
it's only for your pages and you know how you use .EX in your pages.
Avoiding unusual nesting in your pages is trivial - apart from the
fact that it is also a bad idea in general.
No need to publish such a script because i don't think any other
project will need it: the requirement here feels so extremely unusual.

> and mandoc(1) _doesn't_ define it but nevertheless supports many
> groff extensions.

That's not true, mandoc defines a .g read-only number register
in exactly the same way as groff, see the test file below.

The reason for claiming to be groff is the same as the reason
that most Web browsers claim they are running on Microsoft
Windows no matter what.  The (very few) manual pages testing the
register usually make catastrophic decisions based on it, usually
substantially degrading rendering quality unless you claim you are
groff, sometimes even failing to render anything at all.  That's not
surprising because reasonable manual pages almost never test for it.
If a page tests for it, that's a very strong indication the author
has no idea what they are doing and picked up some cargo cult rumours
somewhere.  Claiming to be groff is by far the most reasonable thing
any formatter can do in such a situation and in no way related to the
number or quality of GNU extension features it supports - actually,
the number of GNU man(7) extensions that mandoc supports isn't small,
but that's not the reason for setting .g to 1.

Yours,
  Ingo

> Heirloom Doctools troff can simulate AT&T troff _or_ groff,
> and has its own extensions besides.


 $ cat tmp.man
.TH TEST 1 2023-10-02
.SH NAME
test \- test
.SH DESCRIPTION
Mandoc
.ie r.g defines
.el does not define
the .g number register
with a value of \n(.g.
.br
Trying to change the value now,
.nr .g 42
but the value remains \n(.g.

 $ mandoc -T ascii tmp.man
TEST(1)                General Commands Manual               TEST(1)

NAME
       test - test

DESCRIPTION
       Mandoc defines the .g number register with a value of 1.
       Trying to change the value now, but the value remains 1.

                             2023-10-02                      TEST(1)