[bug #64018] [man, mdoc] decide on a common base paragraph indentation

[Ingo Schwarze]

Follow-up Comment #22, bug #64018 (project groff):

[comment #15 comment #15:]
> > > > We cannot, obviously, have three-letter requests.
> > > Nope.  Like I said, there's room for `Cq`, `Co`, and `Cc`.
> > 
> > Indeed, I see only Co used grepping through all tmacs:
> > tmac.doc.old has it as macro (just .tm’ing to say it’s
> > not an mdoc macro) plus…
> 
> It's in _groff_'s "doc-old.tmac", too, which has the same origin.
> 
> Huh.  I wonder what the story behind that is.

Some years ago, i talked to Cynthia, i think Kirk McKusick helped establish
the contact back then.

What groff calls "doc-old.tmac" is what Cynthia used to call "tmac version 2"
around 1990, whereas she called the language we are now used to "tmac version
3" back then.  If i remember correctly, even Cynthia herself did not keep a
copy of "tmac version 1", and i think she considered it unlikely that such a
copy exists anywhere.  But it's also next to irrelevant at this point.  As
people usually do when designing a new language, she experimented a lot with
preliminary ideas during the early stages and took stuff out again when she
had better ideas and/or collected experience using her new language for
practical work.

Even version 2 was a pre-alpha thing and never used consistently, not even for
any alpha release of the BSD system.  It was used in a relatively small
minority of manual pages in 4.3BSD-Reno (June 1990), which you might call an
official Beta release; the name was intended to indicate "running this is akin
to visiting a Casino."  The vast majority of manual pages in Reno still used
man(7) because the design of the mdoc(7) language was nowhere near finished
and the main work of rewriting the documentation under a free license had
barely started.

Consequently, what mdoc version 2 did or did not do is of very limited
interest even to extreme BSD history geeks.  Compatibility with mdoc version 2
is completely irrelevant for any purpose one could possibly think of because
version 2 was never considered ready for production in the first place.  There
certainly aren't *any* mdoc version 2 documents that anybody uses for any
contemporary purpose in 2023.  Even finding purely historical mdoc version 2
documents that you could use a version 2 formatter on is not all that easy, in
particular not outside McKusick's BSD history CDs.

I suspect that *maybe* Cynthia poisoned .Co in mdoc version 2 because in
4.2BSD, 4.3BSD-Reno, and 4.4BSD, the documentation of the "MH" email handling
system, written in Eric Raymond's -me macros, defined its own .Co macro and
used it at quite a few places - but i'm not sure that's the reason.  It
certainly no longer matters today.

> > | mdoc/README:.\" NS Co register (site) Width Needed for Column offset
> > 
> > … I’m not sure if this is still true, given my grep
> > did not find any other occurrence? I think this is
> > old/wrong and needs to be removed.
> 
> It seems likely to me.

I failed to unearth evidence for \n(Co ever being used for anything in any of
my 4.2BSD, 4.3BSD, or 4.4BSD trees.
It seems that line in Cythia's README file refers to one of her experimental
ideas that she discarded before it ever grew up sufficiently for production
use.

By the way, do we still have that ancient README file in the groff git tree?
I don't readily see it in git, and keeping it would almost certainly be a
mistake.

I think that OpenBSD still has it lying around in the source tree in
/usr/src/share/tmac/mdoc/README is a mistake, too.


> I would guess that Ingo has the world's biggest corpus of _mdoc_(7)
documents readily at hand--but perhaps not the time to grep them for our
benefit.  :P

I tried to figure out why you consider `Cq`, `Co`, and `Cc` only to fail -
still scratching my head...

All the same, FWIW, i just grep'ed the manual pages in the base systems of

OpenBSD-current
FreeBSD-13.0
NetBSD-9.2
DragonFly-3.8.2
4.4BSD-Lite2  (some of these are old, but that may not matter for the purpose
at hand)

and came out completely empty-handed for '^\. *\<Co\>', i.e. .Co as a line
macro.

Obviously, .Co as a sub-macro is harder to grep for, but '^\..* Co ' and
'^\..* Co$' did not find anything, either.

And Co as a register name?  Well-written mdoc(7) manuals should not expand
registers, but i looked anyway using '\\n.Co': again, nothing.

Maybe a string register name then?  I tried '\\\*.Co': again, only false
positives.

So it doesn't appear anything anywhere is using "Co" as a roff(7) identifier
in mdoc(7) manual pages.

Then again, please be aware that i never attempted to build a repository of
mdoc(7) manual pages as comprehensive as possible, i merely have a number of
BSD trees lying around.  I did not check Illumos nor some stand-alone portable
software projects that are using mdoc(7).  Then again, it would be seriously
ill-adwised for Illumos or any such projects to introduce any completely new
features, at least not without carefully coordinating with both groff and
mandoc.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?64018>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/