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

[G. Branden Robinson]

At 2020-10-31T13:00:38+0100, Ingo Schwarze wrote:
> Hi Brandon,

D'oh!  My vowels are discombobulated!

> 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.

I was kind of wondering why they were there, but I figured the designers
of mdoc knew best...

Happily, we are similarly discouraging of string usage in
groff_man_style(7):

 None of the above is necessary in a contemporary man page.  \*S is su‐
 perfluous, since point size changes are invisible on terminal devices
 and macros that change it restore its original value afterward.  Better
 alternatives exist for the rest; simply use the \(rg, \(lq, \(rq, and
 \(tm special character escape sequences directly.  Unless a man page
 author is aiming for a pathological level of portability, such as the
 composition of pages for consumption on simulators of 1980s Unix sys‐
 tems (or Solaris troff, though even it supports \rg), the above strings
 should be avoided.

Maybe I should add a sentence to groff_man(7) discouraging them there,
too, and pointing people to the other page for details.

> 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.

I agree.

> > 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.

Okay.  I'm implementing CS and CT register support in mdoc right now;
just need to write the regression tests.

Sometimes, convincing me is easy.  :)

Regards,
Branden

signature.asc
Description: PGP signature