Re: [DRAFT] Revised groff ms manual for review

[Larry Kollar]

G. Branden Robinson <g.branden.robinson@gmail.com> wrote:

> Happy Halloween!
> 
> Ready for something on the gory and disturbing side?

I got six staples in my head, day before Halloween. They’re out now,
but I had a live-action creepshow going for the day. Bring it. :D

> I feel like I'm about 40% of my way through a huge update of Larry
> Kollar's ms.ms document, as promised earlier this year.  I've done most
> of the work over the past 2-3 weekends; the promise of a release kicked
> my rear into gear.

I’ve looked it over. I’m not sure if the chatty parts are yours or mine
at the moment. When I get a chance, I’ll run a diff and see which of us
said what.

Overall, let’s (both of us) focus on trimming anything that doesn’t
help a reader get a -ms document together.

> … I started discovering just how much is of our
> s.tmac is undocumented, and how much confusion there has historically
> been over what, _exactly_, constitutes the historical ms interface.

I have mixed feelings about this. What’s the goal, here? Unless people
are trying to resurrect older documents, they shouldn’t have to care about
the “historical” interface — just use what’s there. But…

There was once “the” *roff. Then it sunk, and Groff took its place. But
thanks to Plan9, the “the” *roff resurfaced with a lot of nice updates, then
got forked to Neatroff and Heirloom. Fortunately, the differences are
small enough that one can write a -ms extension package for both, using
“.ie g / .el” or “.if g / .if neat" in a few places.

The whole point of ms.ms was *not* to get into internal details. It was
mostly “here’s how you use Groff and -ms to put a document together,
and here’s how you can control the formatting.” Yes, the end of the
document does describe differences from the original -ms, and that’s
probably helpful for the Plan9 derivatives.

But unless you’ve unearthed a 35 year old document that assumes it’s
using “the” *roff, and is doing all sorts of creepy things under the hood,
it shouldn’t matter much. My college roommate sent me a book he wrote
in -mm, back in the 80s, and I got Groff to format it by adding “\&” to
the beginning (he had a custom cover). The same should apply to -ms
documents.

If we want to support data archaeologists, maybe we should write a
separate document for them. :D

— Larry