groff
[Top][All Lists]
Advanced

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

Re: <OK> Re: [Groff] ESR in manpages versus the WEB


From: Miklos Somogyi
Subject: Re: <OK> Re: [Groff] ESR in manpages versus the WEB
Date: Wed, 3 Jan 2007 21:00:02 +1100


On 03/01/2007, at 9:18 AM, Clarke Echols wrote:

It is important to minimize clutter at the start of the page.

and later on :-)

the old AT&T page which combined them with a NAME line:

cp, mv, ln \- copy, link, or move files

Yeah, we had the same thing on our then top-of-the-world SGI system.
I remember well, I was looking for ln but cp and mv got in the way all the time. I nearly exploded in anger. I applaud your effort to de-link these three and applaud your synopsis that made it clear what was
a new file, even without reading the explanations.

A few things like this (and closer to home: counting backslashes in troff, etc), and more than a hundred research engineers were running away, they asked for (and got and were happy with) vastly inferior PCs. Only two were prepared to de-cypher docs and experiment where needed (lots of time wasted) so that
they could enjoy the benefits of a much better system.


There is a lot more to creating a *good* manpage than meets the eye.
It not only involves content, but must artisticly combine form, style,
content, presentation, and visual/mental ergonomics to render it easy
to read, easy to scan, easy to use, easy to understand, and easy to
apply.  The latter usually means lots of examples.


Agreed, wholeheartedly. Looking at a few man pages on my Mac, I would add:

- Don't use other commands in the examples, unless absolutely necessary.
  If necessary, use a word or two to explain their role.

- Start with typical (and simple) examples, not with things with lots of parameters.

-  Make it clear, at a glance, where a new example starts...

I am happy that questions like these came up in the big swirl of HTML and Co, 'cause
they are most important and they seem to be orphans.
As far as HTML and Co go, I don't mind if people use browser-based things as long as I can stay with
PDF and PostScript.
And dream that one day graphics will be a natural part of groff and even man pages.

Miklos





reply via email to

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