Re: [groff] 04/04: groff_mdoc(7): Update "Predefined strings".

[Ingo Schwarze]

Hi Brandon,

G. Branden Robinson wrote on Fri, Oct 30, 2020 at 10:14:43PM -0400:

> commit 9529b9f0ab2db7df0cd9dc79496eaf699772ae52
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> AuthorDate: Sat Oct 31 13:00:17 2020 +1100
> 
>     groff_mdoc(7): Update "Predefined strings".
>     
>     This material seems not have been touched since devutf8 was written.
>     
>     * Advise page writers to use the predefined strings preferentially;
>       it surely makes mandoc's job easier.
>     * Note another advantage of the strings; they can degrade in a
>       device-specific way controlled by the macro package.  Prompted by
>       discussion with Ingo Schwarze and Anthony J. Bentley.

Absolutely not.  I strongly object to both points.  The mandoc(1)
program supports predefined strings purely for compatibilty with
historical documents.  The OpenBSD manual page collection has been
completely purged of their use many years ago.  Here is what the
mandoc_char(7) manual page in the mandoc package says:

  PREDEFINED STRINGS
     Predefined strings are inherited from the macro packages of
     historical troff implementations.  They are not recommended
     for use, as they differ across implementations.  Manuals using
     these predefined strings are almost certainly not portable.

Also, i don't see *any* advantage of using them.  They contribute
some complication to the code of the mandoc(1) program and they make
the life of manual page authors harder for no benefit.

Finally, degrading unavailable characters for display is a job for
the *output device*, not for the (application level) macro package.
Trying to teach individual application level macro packages about
individual output devices is a layering violation causing both
rampant code duplication and inconsistency among macro packages.
A good example of controlled degradation associated with an output
device is tty.tmac.

> diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
[...]
> +The following strings are predefined,
> +and should be used in preference to any corresponding special character
> +escapes in
> +.Nm \-mdoc
> +documents.

No.  This is terrible advice, outdated by at least a decade.

Please change the text to say exactly the opposite.

Yours,
  Ingo