Why does groff use Texinfo? (was: "Writing my PhD using groff")

[G. Branden Robinson]

[dropped DJ from Cc]

At 2022-07-24T13:18:46-0700, Larry McVoy wrote:
> Has anyone proposed redoing the texinfo stuff in Groff?

You do, approximately every time the subject comes up.[1]  ;-)

> Am I the only person who thinks that have *roff documentation in a
> different markup is crazy?

In literal terms, you might be.

> I wrote a couple source management systems, this is like I was storing
> BitKeeper in Git.  That says I trust Git but not my own code.

In groff Git, and in 1.23 whenever we can get that out, we'll be
shipping the (at current count) 385-page compiled groff man pages along
with the 303-page TeXinfo manual, as well as the 27-page ms.ms document.
Among other *roff documents.

So, yes, we eat our own dog food.

> If not, why not?

My guess?  History and priorities.  Trent Fisher contributed the
original cut of the manual in Texinfo format, sometime in 1999
apparently.[2]  Werner Lemberg expanded it from there.  And I've done my
stuff to it since 2019.

"Officially," "GNU manuals" are in Texinfo format.  If I had to guess, I
would assume that is why the original selection of format was made.
Perhaps the idea was to try to invite the, ehrm, "thought leader" of the
GNU project to cease the practice of treating groff like a red-headed
stepchild.  (Refusing to recognize the value or even existence of man
pages, for instance.)  The FSF never published paper-bound copies of the
groff manual.  (Admittedly, there were some incomplete, stubbed-out
sections, but they weren't essential, and ca. 20 years ago I saw printed
and bound GNU manuals with worse professionalism problems than that.)

I think that in turn was a matter of chasing different tail-lights.
Brian Reid's Scribe was everything you--for particular values of
"you"--could want in a formatting markup language, except for its
license, and TeX was all you could ever want in a typesetting engine and
moreover had the holy aura of Donald Knuth around it.  Meanwhile,
everything that came from Bell Labs was a bit suspect of being crap.
Maybe this was because (1) it didn't come from an elite CS university
like MIT or Stanford and (2) AT&T lawyers had spent a decade-plus being
magnificent dicks about it.  Recall that the Unix kernel itself was
evaluated as a bit naff,[3] and something that was supposed to be
"replaced" by a microkernel accompanied by a "hird" of "daemons".

Now, for my part, having read Liedtke and Heiser and others, I _do_
happen to have drunk the microkernel Kool-Aid.  As I understand the
literature, Mach seriously stumbled by trying to take a monolithic
kernel and slim it down instead of starting from nothing and only
putting into the microkernel what you absolutely had to to get something
that could account for hardware capabilities and switch tasks (Liedtke's
minimality principle).  (Even the former isn't _strictly_ necessary, but
omitting it makes a poor candidate for a high-integrity system.)  Mach's
working set was too big--it parked itself in nearly all of the meager
processor cache you had back in 1990, murdering your performance.

At the same time I kind of wonder how much kernel selection mattered
when the only users who mattered were going to spend all day every day
in an Emacs window anyway.

My surmise is probably excessively cynical.  GNU did, by the accounts
I've read, actually _fund_ James Clark to implement groff in the first
place.  From what I can tell he worked effectively, and quickly, given
the volume of work to be done.  So why the comprehensive diss afterward?
Is there another story to be told?

Moving from speculation about the past to facts about the present, yes,
I'm well situated to undertake the work of migrating our Texinfo manual
to a groff macro package.  Why haven't I?

If you look closely, you'll find that a great deal of our Texinfo manual
has parallel forms in other groff documentation.  I'll characterize the
manual as it exists in Git today.

Chapter 1: Introduction: ~4 pages of basic concepts and a nice capsule
           background from Doug McIlroy
Chapter 2: Invoking groff: duplicates portions of groff(1) and troff(1)
           (mostly the "Options" sections)
Chapter 3: Tutorial for Macro Users: duplicates meintro.me, more or
           less--it is generalized a bit
Chapter 4: Macro Packages: almost entirely stumps referring to man
           pages; the remainder is a description of the tmac/man.ultrix
           file or duplicates ms.ms
Chapter 5: gtroff Reference: this has much original content, and it is
           in fact the bulk of the manual by page count.  However, even
           here, much if not quite all of the description of GNU
           extensions to CSTR #54 troff (excluding examples) is
           duplicated in groff_diff(7).  Notwithstanding, much
           presentation of fundamental concepts is duplicated in
           roff(7).
Chapter 6: File Formats: duplicated in groff_font(5) and groff_out(5).

That's it.  The remaining 50 pages are a copy of the GNU FDL (but the
manual is nevertheless dual-licensed under the GPL[4]) and indexes.

Regarding Chapter 4 in particular, my intention has been to stub out the
description of ms as well, once I'm "done" updating Larry Kollar's ms.ms
document, which I characterized as near earlier in this thread.[5]  I've
described my plans before, but can't scare up a citation.  My fault for
sending a lot of mail.  :-/

As you can see, there are some things our Texinfo manual has that you
can't find elsewhere (mostly examples), but less than you might suppose
when considering its page count.

So, when someone asks why we, as developers of a document formatting
system, have a bunch of essential content locked up in a document format
that isn't ours and which we don't control, I know they haven't done
their homework, or had someone do it for them--in other words, that they
haven't been _reading_ it.  It reminds me of interviewing with the
founder of a startup.  They've got vision.  Boy, do they.  Their
eyesight is another matter.

But even that's okay, if they're willing to listen when I explain how
they're mistaken (assuming I am equipped to do so).  I get it.  Guys
like me don't book sales.  But delivery gets tough if you drive away all
your implementors.

To get simplistic and Manichean about it, there are two types of
personality in the tech field.  There's Steve Jobs and his Reality
Distortion Field, to which one willingly submits if one wants to keep
drawing a salary...

...and there's Isaac Asimov, who said "There is a cult of ignorance in
the United States, and there has always been.  The strain of
anti-intellectualism has been a constant thread winding its way through
our political and cultural life, nurtured by the false notion that
democracy means that 'my ignorance is just as good as your knowledge.'"

That does sound a bit preachy, doesn't it?  This is why we don't
organize workplaces as democracies.  Who wouldn't prefer a confident,
ignorant autocrat?

Maybe I'll rant a little less when these 90 dBs' worth of dehumidifer
and fans are out of the damned house.  The ass clown plumber who plants
a time bomb to go off in your home after seven years is just one
specimen of the celebrated small business owner of America.

Regards,
Branden

[1] A sampling:
    https://lists.gnu.org/archive/html/groff/2002-12/msg00007.html
    https://lists.gnu.org/archive/html/groff/2005-10/msg00107.html
    https://lists.gnu.org/archive/html/groff/2020-02/msg00033.html

[2] Our "NEWS" file declares its arrival in groff 1.12, but that
    release, like 1.13, is _not_ archived at
    <https://ftp.gnu.org/gnu/groff/old/>.

[3] Someday I want to run ITS under simulation, if that is even
    possible, and see if I can form any notion at all of why it was so
    freakin' beloved in contrast even to V7 Unix.  I expect little.

[4] https://git.savannah.gnu.org/cgit/groff.git/tree/LICENSES
[5] https://lists.gnu.org/archive/html/groff/2022-07/msg00148.html

signature.asc
Description: PGP signature