[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] The future redux

From: Clarke Echols
Subject: Re: [Groff] The future redux
Date: Wed, 26 Feb 2014 08:13:58 -0700
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:16.0) Gecko/20121011 Thunderbird/16.0.1

On 02/26/2014 06:33 AM, Tadziu Hoffmann wrote:

Man pages are not tutorials or complete manuals

Yes they are, or should be.  They used to be.

Fairly complete manuals, yes;  tutorials, I don't think they
ever were.  The manual page for the fortran compiler says what
the compiler options are -- it does not teach you programming
in fortran;  the vi manual page say what the different key
presses do -- it does not teach you how to use vi effectively;
etc.  There have always been separate tutorial books for those
aspects.  The manpages instead were terse.  Of course that
doesn't mean you couldn't learn using the programs from them.
Good ones even included examples for illustration of ideas.

Man pages are the only practical way to reasonably document Unix
and its variants.  "The Ultimate Guide to the Vi and Ex Text
Editors" is between 200 and 300 pages, and I still missed some
features when I wrote it.  And that was 1987, long before 'vim'
came along.

The reference manual is that: a reference manual.  It assumes
you already understand the system well enough to use it and just
need operational details.  And once beyond a certain level, you
can figure it out with minimal difficulty.  For those exceptions,
tutorials are appropriate.

I recall having to do things with HP's "Real-Time Executive"
(RTE) that ran on "mini-computers" in the early 1970s containing
64 Kbytes of magnetic core memory and filling several feet of
rack space in a 19-inch relay rack.  There were no tutorials,
and I had a rough time attempting to understand some of that

That's why I was so user-centric and focused on what the user
really needed to know in order to accomplish the desired end,
and that led to people asking why my manuals were so much better
than others'.  My response was, "I just know how to remain
intelligently stupid."  In other words, having been a newbie
who had to learn it all the "hard way", I had empathy for
the user and that's who made my job necessary and my paycheck

Too many today don't want to learn systems.  They want instant
answers with zero effort.  That makes Windows, Word, and other
really dumb programs popular, but for my world, groff is like
a dream.  I've never used MM, MS, MOM, or any other macros
except man.  I learned troff by taking the man macros which
were devoid of any comments whatever when released by AT&T
(due to cost of disk storage and memory and the smallness of
computers, when compared with today -- which is also why
name space was limited to only two-character request names)...

...Then I added comments to nearly every line, explaining what
that line did.  Once I had that working (without breaking the
macros' behavior), I had a working understanding of troff.

I started writing a troff tutorial that was better than the
original AT&T, but it got changed to an nroff manual because
HP didn't sell or ship troff.

I use groff all the time for anything from simple letters
to forms to white papers, case studies, and even entire
books, and I always write my own macros to fit my own needs.

I can send a PostScript file containing a book to a printer
and get what I want.

My only complaint is I'd like a better way to be able to use
fonts without having to convert to Type 1, because I haven't
learned how to do that yet.

I've seen, but never learned TeX, and I like groff/troff
because of the straight-forward, easy to understand requests
(some less easy than others), that make sense in their own
contexts.  And best of all, I'm not restricted by what
Bill Gates gives me "permission" to do with my computer
because I have to use Word like so many who have no
appreciation for typography, and settle for what they think
"looks good".

I can do more neat stuff with CSS and XHTML than I can with
Word.  Word is junk, from my point of view.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]