Re: custom NS and NE man(7) macros

[G. Branden Robinson]

[looping in groff list; find start of thread at
<https://lists.gnu.org/archive/html/bug-ncurses/2023-09/msg00076.html>.]

At 2023-09-24T19:45:22-0400, Thomas Dickey wrote:
> On Sun, Sep 24, 2023 at 03:12:47PM -0500, G. Branden Robinson wrote:
> > I see the following macro definitions in the man pages of some of
> > your projects (ncurses, xterm, lynx), but not in pages from other
> > projects (by other people; I didn't check all the rest of yours).
> 
> I see this comment in xterm.man, from a change in early 2009.
> My checkin comment says it was groff 1.18.1

Okay.  If my reading of groff release history is correct,[1] groff 1.19
came out in February 2004--I would think even a slow-releasing
distribution like Debian would have had 1.19 in stable release by 2009.
Not that it matters much--the introduction of EX/EE (and empty stubs for
DS/DE) arrived only later with groff 1.20 (January 2009).  The timing is
an interesting coincidence, though.

[...]
> > I have several questions about them.
> > 
> > 1.  I don't understand the comment.  While it is true that groff
> >     man(7) has defined `DS` and `DE` as no-ops for many years (first
> >     committed January 2007, released in groff 1.20 January 2009),
> >     its definitions do not foreclose local redefinitions after the
> >     `TH` macro in a
> 
> I probably tried redefining with a macro before .TH -- and your note
> explains why that did not work.
> 
> I can recall working with EX/EE and DS/DE, finding one or the other
> would not work well with porting -- it seems that I had settled on
> the latter.
> 
> Making a coherant history of that would take some time...

I certainly don't expect you to do so, but I'd be happy to compare
sources with you if/as you happen across them.  Developing groff has
compelled me to become something of an amateur *roff historian.

[...]
> yes... I see in my history that I used to use EX/EE.
[.sp vs. the man(7) default paragraph spacing of 0.4v]
> no - a normal interparagraph gap was what I wanted.
[indentation]
> perhaps not - but I often preview this stuff with "gv", and didn't
> notice anything odd.

Cool.  I will pilot a replacement of NS/NE with "standard" macros in
man/clear.1 and we'll see how it shakes out.

> > [2] The relevant file name appears to be "tmac.an.new".  It has a
> >     long history in BSD, but `DS` and `DE` macros did not appear
> >     until 4.3BSD (1986).
> 
> ... I probably modified manpages in that era, but probably started
> creating them in 1988 or 1989 (since others wanted the documentation).

Makes sense.  4.3BSD was super popular, and longevous (thanks in part to
litigious successors-in-title of the Unix copyrights).

> Actually, it seems that I wanted EX/EE (for fixed-pitch font), and
> encountering some system lacking those, decided DS/DE would suffice.

I don't know of an explicitly articulated reason groff man(7)'s `DS` and
`DE` have remained stubbed out for 16 years, but my _guess_ is that
there is little demand for general displays in man pages.

What I do sometimes see demand for is reduction of the inter-paragraph
vertical space amount to zero, and that frequently to present a list of
some sort with a compact appearance.

Last December I pitched some ideas for new groff man(7) extensions to
cover some use cases that have itched me and other page authors.

>>     KS/KE   Keeps.  Easy.[...]  Harmlessly ignorable by other
>>             implementations.
>>     LS/LE   List enclosure.  Throws a semantic hint (e.g., for HTML
>>             output) and eliminates final use case of `PD` macro.[...]
>>     DC/TG   Semantics at last.  Sure to rouse anger in people who
>>             decided long ago that man(7) can't do this.[...]  Having
>>             looked more closely at mdoc(7) since writing that, I
>>             think `DC` should accept a _pair_ of arguments as its
>>             second and third parameters for bracketing purposes.
>>             But again, most man page authors would never need to
>>             mess with `DC` at all.

I've also been dickering with the idea of quotation macros, since
attractive quotation marks are so hard to get (portably), and therefore
see little use in man pages; people abuse italics instead.  This would
probably look line one or both of these:

  Q      Quote arguments.  Would work like `B` or `I`, except that I am
         reluctant to mess with setting up an input trap.  In practice,
         the use of input traps with `B`, `I`, `SH`, `SS`, and `SM` is
         seldom seen.

  QO/QC  Open/close quotation.  These would take no arguments and would
         therefore degrade more nicely (to no-ops) if unsupported, as
         mandoc maintainer Ingo Schwarze has pointed out.[3]  It should
         be straightforward to support nesting of these with alternation
         in the style of quotation marks used.

.QO
The Care and Feeding of
.QO
MR
.QC
Macro Calls
.QC

...would render (in UTF-8) as:

“The Care and Feeding of ‘MR’ Macro Calls”

...for example.

An implementation lacking QO/QC would render

The Care and Feeding of MR Macro Calls

instead, which has the saving grace of not losing the formatted text as

.Q "The Care and Feeding of \(oqMR\(cq Macro Calls"

...would.

I further observed, with less awareness then of 4.3BSD's tmac.an.new
file, that the effect of `DS`/`DE`, when _not_ being used to set
examples, can be readily achieved with a tbl(1) table.  Part of groff
itself has worked at cross purposes to such simplicity, unfortunately,
because when it renders to HTML, the textual content of tables gets
lots, replaced with a PostScript image.  There is a better way; all it
demands is a developer with some time and ambition.[2]

For now I am only mentally red-teaming (and repeatedly proposing) these
extensions to see what conceptual flaws surface.  And also seeing how my
previous reform effort, `MR`, fares in the wild.

Regards,
Branden

[1] https://ftp.gnu.org/gnu/groff/old/
[2] https://savannah.gnu.org/bugs/?60052
[3] This is an important factor to consider when man pages using new
    extensions appear on systems before the new groff version that
    supports them.  groff 1.23.0's man pages all carry a boilerplate
    providing a fallback definition of `MR` to mitigate this problem; I
    knew I'd have to do that, and I think it was worth it, but I'm not
    eager to add more.

signature.asc
Description: PGP signature