Re: custom NS and NE man(7) macros

[Thomas Dickey]

On Sun, Sep 24, 2023 at 03:12:47PM -0500, G. Branden Robinson wrote:
> Hi Thomas,
> 
> 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
 
> .\" these would be fallbacks for DS/DE,
> .\" but groff changed the meaning of the macros.
> .de NS
> .ie n  .sp
> .el    .sp .5
> .ie n  .in +4
> .el    .in +2
> .nf
> .ft \*(CW
> ..
> .de NE
> .fi
> .ft R
> .ie n  .in -4
> .el    .in -2
> ..
> 
> 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...

>     man(7) document.  (This restriction on placement is due to the way
>     andoc.tmac/the "-mandoc" argument works, which in turn goes back to
>     4.3BSD-Reno in 1990.)  And in fact I can change these definitions
>     (and their corresponding calls) to `DS` and `DE` with no impact on
>     the formatted pages.  `DS` and `DE` have never been "standard"
>     man(7) macros [there is no standard].  They do not appear in Seventh
>     Edition Unix man(7)[1], nor in any USL descendant I have
>     encountered.  They are not in PWB, DWB, or Solaris troffs.  I do see
>     a late Berkeley implementation but they do not change the
>     typeface.[2]  (DEC Ultrix did have display macros named `Ds` and
>     `De`--note the mixed case.)
> 
> 2.  The Ninth Edition Unix (1986) and groff 1.20 extension macros `EX`
>     and `EE` do much of what these macro definitions do: `EX` turns off
>     filling and selects a monospaced font (in a device-appropriate way),
>     while `EE` restores filling and selects the default font.

yes... I see in my history that I used to use EX/EE.

> 3.  The vertical spacing used by `NS` is very nearly what you'd get from
>     an ordinary paragraphing macro.  On terminals there is no
>     difference, and on typesetters, your `NS` macro adds .1 vee more
>     vertical space than the man(7) package default of 0.4v.  On a
>     typesetter using 10-point type on 12-point spacing (*roff defaults),
>     this is a difference of 1.2 points, or 1/60th of an inch (there are
>     72 points to an inch).  Is this difference important to you?

no - a normal interparagraph gap was what I wanted.
 
> 4.  I am curious about the different amount of indentation used on
>     terminals vs. typesetters.  The default scaling unit for the `in`
>     request is ens, and on terminals, one em is equal to one en, so the
>     result here is that you get four times as much indentation on
>     terminals as typesetters.  Was that your intention?

perhaps not -
but I often preview this stuff with "gv", and didn't notice anything odd.

> Thanks for any light you can shed here.
> 
> Regards,
> Branden
> 
> [1] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/lib/tmac/tmac.an
> 
> [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).  These macros got backported to 2.11BSD (a separate line of

... I probably modified manpages in that era, but probably started creating
them in 1988 or 1989 (since others wanted the documentation).

>     Unix developed that retained support for PDP-11 machines), and
>     remained for 4.3BSD-Tahoe (1988) but disappeared from 4.3BSD-Reno
>     (1990), which also saw the debut of mdoc(7), so maybe the CSRG saw
>     no point in maintaining extensions to man(7) when they were trying
>     to deprecate that macro language altogether.  BSD Net/2 (1991) and
>     4.4BSD shipped groff, which did not implement them.[3][4]
> 
>     These BSD `DS` and `DE` macros moreover use the existing man(7) `RS`
>     and `RE` to manage indentation, not the custom requests that your
>     `NS` and `NE` macros employ.
> 
>     If a person wants authentic BSD `DS` and `DE` workalike behavior, it
>     seems to me they should use the following.
> 
>     .de DS
>     .RS
>     .nf
>     .sp
>     ..
>     .de DE
>     .fi
>     .RE
>     .sp .5
>     ..

Actually, it seems that I wanted EX/EE (for fixed-pitch font), and
encountering some system lacking those, decided DS/DE would suffice.
 
> [3] 
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/groff/macros/grot/tmac.an
> [4] 
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.groff_an


-- 
Thomas E. Dickey <dickey@invisible-island.net>
https://invisible-island.net

signature.asc
Description: PGP signature