Re: [groff] mom manpage

[Peter Schaffter]

Ingo et al. --

Thanks for replying so thoroughly, and so passionately, to my query
about the mom manpage.

A fact I have kept to myself since releasing mom is that the one of
the reasons for the project was to test some ideas I had about the role
of documentation in programming.  The reason for wanting to do so
had its origin in my initial exposure to manpages, which came in
1996 or thereabouts when I installed my first GNU/Linux (Debian) on
a second-hand 386.

At the time, I had no knowledge of Unix.  I had to learn everything
with only manpages and the occasional gem in /usr/share/doc as
guides.

I found manpages to be frustrating and offputting.

  - The prose was dense to the point of being opaque.  I was
    reminded of what a friend once said about Webern's Five Pieces
    for Orchestra: "Like Jello without the water."

  - There was an assumption I knew things I didn't.

  - The less(1) pager only let me navigate by text search--not much use
    when I didn't know what I was looking for.

  - In printed copies, the lack of an index made it even harder to
    find material.

  - The terminal display was unfriendly to eyes used to grouping
    text into meaningful chunks from typographic clues rather more
    sophisticated than caps/brighter/underlined/ansi-olour.

Most frustrating was the feeling that manpages were useful only if
you already understood everything.  Documentation Catch-22.

All I could think was, this is not how you foster adoption of an
operating system.  At the time, GNU/Linux was being fudded as
a hacker's toy.  Sadly, in 1996, that is how exactly Debian's
"universal operating system" came across, largely because the
primary source of documentation resided in a sort of hacker
Empyrean, far above the ground mere mortals walk upon.

When I analyze my initial impression of manpages, I see that it
was a clash between approaching computing from the humanities,
as a non-programming user, versus approaching computing from the
sciences, as a programmer.

Whatever the reasons, those first impressions stuck with me.
True to my suspicion, the usefulness of manpages only revealed
itself after I knew what they contained.  Smaller ones documenting
tools that "do one thing and do it well" made ideal in-a-nutshell
aides-mémoire--once I understood the tool in question and knew
what I was looking for.  But for programs with a larger scope, the
frosty, "just the facts, Ma'am" style interfered with absorbing
the content, and the lack of indices and linking made navigation a
nightmare regardless of how logically organized the material.  I
gather I'm not the only one who has ever felt this way.  The GNU
decision to make texinfo its official documentation format would
seem to acknowledge the problem, even if the solution was less than
ideal.

I'm going on at length, so it wouldn't be a bad idea to make clear
that I've been talking about a single, GNU/Linux user's impression
of manpages on first exposure.  It doesn't reflect my feelings now.
The impressions are relevant only because they coloured decisions I
made several years later.

When I began work on mom, I wanted to create a typesetting and
document formatting system for GNU/Linux that humanities-oriented
writers could use without taking a course in computer science.  I
spent time pondering how that could be accomplished, and came to
the surprising conclusion that the key lay in documentation, not
implementation.  Helpful, *enjoyable* documentation.  We grasp
information faster and better when we enjoy how it's conveyed, no
matter what our level of expertise.

Helpful and enjoyable being vague terms, I broke them down.
Helpful, in addition to complete and accurate, meant instructional
(not just "this is what x does" but also "this is when/where/how
to use x"), well-indexed, and with extensive cross-referencing of
possibly unfamiliar concepts and terms associated with typesetting
and printing.  (We tend to forget that writers used to just write.
"Formatting," as we now call it, was done by typesetters, paste-up
artists, and lithographic strippers who had their own jargon.  It's
worth remembering that prior to the mid '80s, the word "font" was
practically unknown in the general population.)

"Enjoyable" meant that the content should be easily digestible
visually and written in a relaxed style that fostered engagement
with the text.  The decision to call the typesetting system "mom,"
for example, was so it could be referred to as "she" to lighten
things up.  I believed that if users developed a feeling of
connection with mom through the intermediary of her creator,
who spoke to them with an identifiable voice, she would be more
effective in achieving her goal.

If it sounds like I'm describing an anti-manpage, I guess I am.
"Relaxed, easy to read, instructional...."  The horror, the
horror. :)

After considering the available choices, I concluded that html
(later xhtml) was the best option for formatting.  It had an
interface familiar to everyone (ye olde web browser), painless
linking, ease of organizing diverse files from a single table of
contents, adequate presentational control of semantic elements
(heads and subheads that *looked* like heads and subheads,
easily-identified tips and other secondary information, monospaced
code that stood out well from the surrounding text), and room to
provide needed explanations whose length didn't impinge on the
ability to go straight to the bare bones of a particular macro.

Formatting decision made, I chose groff as the typesetting platform
for mom and proceeded to write all the documentation for her
initial release--without defining a single macro.  I scarcely knew
how.  (Okay, that's a bit of an exaggeration.  I'd already cobbled
together some macros to print out my recipes.)

Once I began coding, I followed a single, firm guideline: no editing
of the documentation other than for style.  Expedient adaptation of
the text was forbidden, no matter what coding hell it threw me in.
The code articulated what was in the docs, not the other way around.

The trendy and vague term "holistic" springs to mind here.  I
am trying to convey that mom and her html docs are inextricably
connected.  Mom *is* her documentation.  Users are not expected to
consult it, rather to be in fruitful contact with it while they're
working.  It is the most important part of the user interface, what
mom provides that duly-manpaged macro sets do not.

How successful has mom been at achieving the goal of creating "a
typesetting and document formatting system for GNU/Linux that
humanities-oriented writers can use without taking a course in
computer science?" Hard to judge given the paucity of data, but
I don't think it's a stretch to say that mom is the first choice
macroset for most groff newcomers these days--has been for a
while--and they tend to stick with her.  How much a part has the
documentation played in her adoption?  Again, hard to judge, but
users actually thank me for it from time to time.  (I leave open
the question of why mom's documentation inspires gratitude where
manpages do not.)  Month after month, the stats from mom's webpage
show more hits on mom's online documentation (identical to what's
installed with groff) than all the other files on my site combined.
No one's whined yet that they don't look like manpages.

> if you are interested in my perspective - scrap the HTML
> documentation and fix the manpage.

See above. :)

> The reference manual - i.e. the manpage - is really important: when
> you use some software regularly, you use the reference manual all
> your life.  Catering to the experienced user is most important
> because whoever is serious about using the software will become
> experienced sooner rather than later.  So the reference manual
> (manpage) must be concise, precise, and correct.
> 
> If an author has too much time on his hands and doesn't doesn't know
> what to do with it, there is nothing wrong with writing a beginner's
> tutorial, too.  But it's really not so important.  You skim through
> that once, than quickly move on to the real thing for further learning,
> often even before finishing the tutorial.  And then there is never a
> need to come back to it, so it doesn't really matter that much - "use
> once" is much less important than "use always".
>
> Besides, even beginners can easily learn from a well-written
> reference manual.

Your position is that mom's html documentation is a beginner's
guide aimed at frivolous users.  Furthermore, you presume to know
the needs and habits of experienced mom users--all users, in fact,
whom you adjudge "serious."  I'm unoffended because I am, in fact,
one of your experienced users.  I know where you're coming from,
so to speak.  But have you any idea how condescending, dismissive,
and elitist those two paragraphs sound to someone who doesn't?
Very likely not.  Unix culture is rife with elitist assumptions.
Innocently elitist, I hasten to add.  I doubt anyone who responded
to this subject realises how doctrinaire and prescriptivist their
pronouncements on manpages are.  I hope no one is offended by my
saying so because I'm guilty of the same sort of accidental lapse
more often than I care to admit.

> Write the real manual in some other format than a manpage?  Bad
> idea. it means you make it harder to access, out of the usual
> place where people look for documentation, in a gratuitiously
> different format.

Harder to access?  Marginally at best.

  man groff_mom
  w3m <docdir>/macrolist.html

Not an enormous amount of difference, if terminal display is
desired.  A one-liner shell script if the 2nd example is too onerous
to type.  I honestly can't see how that's harder to access.

Out of the usual place?  No, just not in /usr/share/man.
Documentation resides in other common locations.  Are texinfo docs
somehow not "usual?"

Gratuitously?  I selected xhtml for the mom docs after careful
consideration.  It served my purposes best.

> You want HTML and PDF versions?  Not a problem

There is some irony in your dismissing html documentation, then
acknowledging, as you do here, that some folks want it.

> You want hyperlinking?  Not a problem with .Xr links in modern
> manual pages either.

Linking wasn't a feature of manpages when mom was created.
Switching to manpage format now just because linking is possible
would be monumentally pointless.

> You want bells, whistles, and moving gifs of cute cats?  Bad idea,
> documentation is about efficiently conveying information, not
> about fluff and pictures and gimmicks.

Not sure where you're getting your ideas about html documentation
from.  It is capable of moments of sobriety, you know.  The online
git documentation, for example, doesn't have any cute cats that I
can see.  Or bells, or whistles, or fluff, or gimmicks.  At most, a
some very helpful graphics.

> Even moderately large systems can be beautifully documented in a
> single manual page - for example, a shell.

Which, by its very nature, is well suited to being documented in
a manpage.  The right tool for the job.  Not the right tool for
documenting everything.

Insisting that manpages are the only true documentation format,
elevating them to the point that become a measure of the quality of
one's coding, runs counter to the Unix Rule of Diversity: distrust
all claims for one true way.  It's a good admonishment.

> If is system is too large and a single page would become unwieldy,
> yes, in the first step, you split it up to the next logical level
> -i guess for mom that would be macros, but you can probably judge
> better than i can what that next level is.  That gives you too
> many pages, most of them unreasonably short?  So you form logical
> groups of related macros, make one page for each group, and name
> the page after the most important or typical macro of the group.

I giggled.  Honestly.  What you've described has resulted in the
sprawling mess of the groff manpages!  To my mind, the most useful
piece of information in groff(1) is "The groff info file contains
all information on the groff system in a single document."  Why?
Because the info file is indexed and hyperlinked and I don't have to
figure out whether groff(1), groff_font(5), groff(7), groff_char(7),
groff_diff(7), nroff(1), troff(1), ditroff(1) or groff_out(1) has
the information I'm looking for.  From the command line, I can go
straight to what I want.  (For the record, I'm no fan of info.)

Some programs simply are not well served by manpage-style
documentation.  Mom is one of them.  Does that make her an example
of bad coding (Doug's view on the subject)?  Perhaps.  Has she
been successful at the purpose for which she was created?  From my
perspective, resoundingly yes.  In addition to aiding her target
users, mom is helping groff itself remain vital.

> This is not rocket science and nothing new - just do it...  ;-)

Methinks you underestimate what would be involved. :) It wouldn't
be the grunt work; it would be the conceptual reworking of the
material, a daunting task for zero gain--and likely a loss--in
utility.  I haven't shirked creating a manpage for mom; I would
prefer she didn't have one at all, other than, as proposed, one with
a description, calling instructions, and a pointer to the html (and
pdf) documentation.

-- 
Peter Schaffter
http://www.schaffter.ca