Re: AT&T troff requests

[Ingo Schwarze]

Hi,

Humm wrote on Tue, Mar 29, 2022 at 06:51:34AM +0000:
> Quoth G. Branden Robinson:
>> Someone wrote:

>>> As far as I can tell, none of them are mentioned in the Troff User’s
>>> Manual (CSTR 54, Plan 9, and Heirloom versions), in Mandoc docs, or in
>>> Groff docs.  I suggest mentioning these somewhere in the docs, even if
>>> not implemented.

>> That's a bit beyond the scope of the groff documents we have.  I've
>> added substantial historical and comparative material, but that's
>> generally in the context of addressing compatibility issues and
>> motivating why features are present or work the way they do.
>>
>> About flat-out unimplemented requests (or escape sequences), I can't
>> find much to say.

> I understand.  I wonder where such documentation might be appropriate 
> today—I wish for future me to have an easier time finding information.

The mandoc roff(7) manual page https://man.openbsd.org/roff.7 intends
to list all requests and escape sequences that that are GNU or Heirloom
extensions, even those ignored or unsupported by mandoc.  For the ignored
and unsupported ones, the description is usually restricted to a single,
short sentence, and a full description is typically not provided.

Adding the Plan 9 extensions can be considered if there aren't too many.  
Note that would imply deciding for each one whether it should be
ignored or unsupported.  Compare:

  lc_ctype localename
    Set the LC_CTYPE locale.  This is a Heirloom extension and
    currently unsupported.

  lhang font char ... afmunits
    Hang characters at left margin.  This is a Heirloom extension and
    currently ignored.

The historic .li request is not mentioned in the manual.

   $ echo .lc_ctype | mandoc -Wall
  mandoc: <stdin>:1:2: UNSUPP: unsupported roff request: lc_ctype
  [...]

   $ echo .lhang | mandoc -Wall    
  [... no warning message ...]

   $ echo .li | mandoc -Wall 
  mandoc: <stdin>:1:2: ERROR: skipping unknown macro: .li

The more specific message "unsupported roff request" is intended
to warn authors and manual page maintainers when the lack of a
feature they appear to rely on is likely to cause information loss
or severe misformatting.

So documenting Plan 9 extensions is only crucial if there are some
manual page authors out there who use Plan 9 troff while writing
their manual pages (for example, while maintaining the manual
page collection of Plan 9 itself?).  Even if such authors hardly
exist, documenting a small number of additional requests does
little harm, given how many extensions groff and Heirloom already
define.

I tend to agree with Branden that documenting purely historical requests
not implemented anywhere in current software is even less important
because such requests are unlikely to occur in practice and if they do,
the generic error message "skipping unknown macro" seems sufficient.
Then again, documenting them might help users who look at very old manual
page sources.  If the number is *very* small, maybe paragraphs similar
to the following could be considered if someone does the work of
writing them:

  li [N]
    Treat the N next input lines as a literal block.  This request was
    only supported by historical AT&T troff.  Treated as an unknown
    macro by mandoc(1).

Yours,
  Ingo