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
_______________________________________________
Groff mailing list
Groff@gnu.org
http://lists.gnu.org/mailman/listinfo/groff
