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
