Re: [groff] mom manpage

[Peter Schaffter]

On Wed, Dec 05, 2018, James K. Lowden wrote:
> On Tue, 4 Dec 2018 15:16:50 -0500
> Peter Schaffter <address@hidden> wrote:
> 
> > 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.
> 
> I don't think that's quite right, Peter.  I suggest to you that's the
> difference between a user guide and a reference manual.  We need both,
> always have, and the humanities have nothing to do with it, except
> insofar as they teach clear exposition. 

I used humanities as a collective noun referring to users who come
to a Unix system as philosophers, historians, linguists, writers of
fiction, essayists...  Such users do, generally, approach computing
from a different perspective than sysadmins and programmers.  They
do not *think* like sysadmins and programmers.  The filters they
bring to bear on documentation are very much related to the issue at
hand.  Not to acknowledge that leads to BOFH thinking.

Manpages target the B.Sc. crowd, not the B.A. crowd, if I may speak
very broadly to make the point.  I believe the latter tends
to have the same reaction to manpages that I did on first exposure.
"Manpage" implies "a manual."  A common understanding of the term
manual, the one brought to bear by my "B.A crowd," is

 "[A] comprehensive and step-by-step guide to a particular topic for
  both beginners and practitioners that also serves as a reference
  book.  A manual details what is given and what is required,
  explains how to put the presented information into practice, and
  instructs how to solve problems as they occur." [BuinessDictionary.com]

Manpages are the antithesis of this, so conceptual clashes of the
sort I experienced are likely to occur.  I'd hate to be guilty of
extrapolating the general from the specific, but I'm certain I am
not alone in my initial reaction to manpages.  

I do hope it's clear I am not attacking manpages or suggesting
their content, style, or formatting be altered, except insofar as
I'm Ingo's camp when it comes to mandoc.  Manpages serve the needs
of their target audience, of which I am a card carrying member.
How well they do so will likely always be contentious, as, IMO, it
should be; that's how we make them better.  Nevertheless, they are
not and will never be suitable for all documentation.  I dispute the
notion that if you can't document your work manpage style, your code
is sub par.  Classic case of "true in most instances, not in all."

> You'd have a hard time convincing me that MOM is more complex
> than troff itself, or that groff_mom(7) would be longer or
> harder to organize than groff(7).

Heaven forfend!  I'd never suggest mom was more complex than troff.
But she is nothing like g/troff.  Groff is a typesetting
*program*.  Mom is, for all intents and purposes, a formatting
*language*--as such, akin to html/css.  Nowhere is html/css
documented in manpage format, for the obvious reason that you can't
learn a language from reading the dictionary.  You need more than
just "this is what the words mean."  Organizing html/css into a
usable manpage would, I think, prove a complex task indeed.  _Ita
quoque mom._

A better analogy might be GNU Lilypond, which provides a formatting
language for engraving music.  The language is not covered in a
manpage because, quite simply, it cannot be, not in any meaningful
way.  Instead, its manpage does what I propose is best for mom: it
gives the NAME, a DESCRIPTION, the invocation SYNOPSIS, and command
line OPTIONS--the kind of information I want from a manpage, which
I am likely to be consulting at the terminal because I intend to
perform a command line operation.  For actually creating lilypond
documents, users are directed to the full manual.  (I shudder to
think of consulting a manpage for all that guile/scheme.)

> The very fact that your HTML documentation is frequently viewed is
> proof, actually, that a reference manual is needed.

I see it differently.  What it tells me is that mom users like
consulting the documentation from their web browser.  The experience
is comfortable and familiar.  Users don't have to go on the Web to
consult the docs, which ship with groff, yet they persist in doing
so.  More a question of "familiarity breeds ease of use" than silent
pleas for a manpage, I should think. :)

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