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

[Clarke Echols]

Here are some examples of what I did back in 1992 in the HP-UX
Reference manual.  This is a good example of my thinking in what
makes a "useful" manpage:

   http://docs.hp.com/en/B2355-90128/cp.1.html

I reviewed my copy of the entire manual (3000 pages, 1450 files)
and did not find any case where more than one line was used for
the NAME section.

A bulleted list at the start of the DESCRIPTION section alerts the
user to what can be done with the utility/function/system call/
whatever before exploring each "personality" described in the manpage
file.

It is important to minimize clutter at the start of the page.  That
is one advantage of the one-line NAME section rule.  The SYNOPSIS
section can illustrate the syntax related to each name/purpose, thus
minimizing the time needed for the "expert user" to determine whether
that is what he/she is looking for.  If it isn't clear at that point,
the user can refer to the DESCRIPTION for further details which are
presented first in overview form before digging into the gory details.

This approach makes a reference page/manual much easier/faster to use
for experts without snowing or losing the non-expert who may have to
read a bit more, but who can still get the needed answers.

The cp(1) page cited is similar to the ln(1) and mv(1) pages I wrote
(see: http://docs.hp.com/en/B2355-90128/ln.1.html and 
http://docs.hp.com/en/B2355-90128/mv.1.html ) which were my answer to
the old AT&T page which combined them with a NAME line:

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

The reason AT&T used one page was because a single program (utility)
did all three, its behavior altered according to which command was used
to call it.  It was confusing to the non-guru and when I split it out
into three and rewrote them, I found all sorts of gaping holes in the
AT&T page that were not properly documented.

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.

For example, how do I create a zero-length file?  See the examples in

http://docs.hp.com/en/B2355-90128/cp.1.html
http://docs.hp.com/en/B2355-90128/cat.1.html
http://docs.hp.com/en/B2355-90128/touch.1.html

The printed manual has entries for "create a zero-length file",
"zero-length file, create" and under the topic "file:" there are
three entries for "create zero-length" as there are three entries
for the other two.  A major factor in usability of printed manuals
is an *excellent* index.  The old AT&T "index" for "rename a file"
was the rename(2) system call.  Not one word about using "mv(1)".
In fact, the cp/mv/ln manpage didn't even mention renaming a file!!!
*BAD* -- *very bad*.

M Bianchi wrote:
> > On Mon, Jan 01, 2007 at 11:32:11AM -0500, Eric S. Raymond wrote:
> > > Gunnar Ritter <address@hidden>:
> > > > Eric S. Raymond wrote:
> > > > ... and "don't write multiple description lines".
> > > Multiple description lines?
> > I'm talking about name sections like this:
> >
> > NAME
> >        bzip2, bunzip2 - a block-sorting file compressor, v1.0.3
> >        bzcat - decompresses files to stdout
> >        bzip2recover - recovers data from damaged bzip2 files
> >
> > This is perfectly legitimate as troff, but the DocBook DTD only allows
> > one description line.  ...
>
> But that form is _so_ much easier to read and understand, especially for the
> novice!  That, to my mind, is the overriding goal of the exercise.
>
> This would seem be argue for structural macros.  E.g.
>
>  .SH  NAME
>  .NamePurpose  "bzip2, bunzip2"  "a block-sorting file compressor, v1.0.3"
>  .NamePurpose  "bzcat"           "decompresses files to stdout"
>  .NamePurpose  "bzip2recover"    "recovers data from damaged bzip2 files"
>
> Here, particularly, is a case where a few man page templates would go a long
> way towards encouraging good practice, even for us "experienced" groffers, but
> especially for the new-comers.
>
> Surely  doclifter  could deal with macros of that model and create DocBook stub
> pages to point to the full-blown page; or am I missing something?
>
> --
>  Mike Bianchi
>
>
> _______________________________________________
> Groff mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/groff