Re: [Groff] What does .\" NS mean in the unstripped tmac files?

[Ingo Schwarze]

Hi,

Ralph Corderoy wrote on Sat, Feb 25, 2017 at 02:14:17PM +0000:
> Werner Lemberg wrote:
>> John Gardner wrote:

>>> .\" NS Dd user macro (not parsed, not callable)

I guess that means "namespace".

The syntax of these lines (almost) always is

  .\" NS <identifier> <class> <description>

where <identifier> usually is a two letter name (capital + lower case
or vice versa), <class> ist "macro", "string", "register", or (rarely)
"diversion", and <description> is free text.  mdoc(7), for the first
time and in contrast to man(7), had a sufficient number of macros, in
particular if you count the internal ones, that losing track of which
names were already taken became a real danger.  Then there is the
additional trap in roff in general that macros and strings share the
same namespace.

I *guess* that Cynthia Livingston, the designer of these macros and
the author of the original implementation, periodically did something
like

  grep -Fh '" NS' * | sort | more

while developing the macros and looked for clashes and inconsistencies.
I doubt that she had more sophisticated tools for that purpose;
at least i see none in the source code of 4.3BSD Net/2 (released
August 20, 1991), and i can't imagine what any more sophisticated
tool should have accomplished.

Then again, if people *really* want to know, we should ask Cynthia.
She still answers questions about her macros, even though she stopped
working on them more than 20 years ago.

>> I no longer know, sorry.  It marks documentation lines, that's for
>> sure.

> They appeared in a48ab7b6db26b1d98f77f59f22896fe02a700c40,
> 
>     Author: James Clark <address@hidden>
>     Date:   Wed Mar 18 04:29:18 1992 -0500
> 
>       groff before CVS: release 1.05

Yeah, back then, people picked up each other's work quickly.  The
oldest codebase of groff that is still preserved and that i'm aware
of is that of groff-1.01 in 4.3BSD Net/2, almost a year older than
the oldest checkin in the official groff CVS / git repo: groff was
quickly picked up by BSD soon after James Clark started publishing
it.  Conversely, James Clark quickly picked up the BSD mdoc macros
and included them in his groff releases, certainly within less than
a year after Cynthia made them publicly available.

> and part of CHANGES there says
> 
>     The -mdoc macros have been upgraded to the version in the second
>     Berkeley networking release.  This version

That is "Version 3" of the mdoc macros, as Cynthia called them:
The version we are still using today.

>     is not completely compatible with earlier versions; the old
>     version is still available as -mdoc.old.

That is "Version 2" of the mdoc macros, which is almost forgotten
nowadays, but the source code has been preserved, and some example
manual pages were published with 4.3BSD-Reno in June 1990 and have
been preserved as well.

According to Cynthia, "Version 1" is probably completely lost.
She does not think that the source code, any manual or description,
or even any example manual pages remain.

> So you may find a hint in an old BSD that can code to process them.

As explained above, not necessarily.  I suspect less of mystery
here than it might seem at first.  Those were happy days:  People
neither needed nor built overengineered toolboxes.
Well, mostly.  :)

Yours,
  Ingo