Re: [Groff] Effective manpages, a couple of thoughts

[Clarke Echols]

Pete Phillips wrote:

> >>>>> "Larry" == Larry Kollar <address@hidden> writes:
> 
>     Larry> What do you think about the idea of having *both* a long and
>     Larry> a short manpage for a complex subject, where each references
>     Larry> the other? In other words, one is short, the other is
>     Larry> complete. :-)
> 
> Well, from my point of view, it wouldn't break my current working
> practice, so seems reasonable. In principle I think it's a good idea,
> but ......

When I was designing HP-UX sys-admin online help, I kept the short,
simple stuff up front, and the deep, complex stuff later in the file,
not unlike a well-written manpage.  Cover the simple stuff like options
and flags, then keep the detailed stuff for later, but don't split it
into a short/long version or I'm stuck with trying to remember which
has what in it.

> I'm not sure how you would fit it into the accepted man page structure.
> 
> Perhaps 'man ls.s' for the short version, and 'man ls.l' for the long ?
> (all we have to do is stop that practice of local man pages using the
> '.l' suffix)             :-)

YUCK!

> Hmmmm - also, if there was an ENV variable GROFF_MAN_PAGE_PREF you could
> set to 'short' or 'long' you could set it to show you the pages you are
> most likely to be interested in by default? That way, people like Ted
> and I (who basically fire up man so they can trawl through it with
> 'less') wouldn't notice any difference.

Just what we need -- another environment variable to remember...
No wonder some folks think Unix is hard stuff to learn.  I can
also see why I always preferred the paper manuals.  Much easier to
thumb through and look for neat ideas...
 
Clarke