Re: Man pages missing

[Juergen Christoffel <Christoffel@gmd.de>]

   From: Zefram <zefram@dcs.warwick.ac.uk>
   Date: Fri, 31 Jan 1997 11:53:27 +0000 (GMT)

   Vidiot wrote:
   >I commented to RC separately about the documentation.  Personally I think
   >the man pages and the manual should be separated.  The man pages should be
   >very brief, to the point that the zsh man page could be only a couple of
   >pages long.

   No!  man pages are the primary form of online documentation for Unix
   programs; they *must* have complete information.  I regularly look
   things up in the man page, and would be severely inconvenienced if I
   had to log in to a graphical terminal and fire up ghostview (or
   whatever) to get authoritative information.

Man pages *must* have the complete documentation? I don't think so.
With today's complex commands (which somehow violate the Unix toolbox
philosophy of small tools put together to get work done anyway ;-)
man pages get so big that they tend to be much less useful. They
worked well for the small tools and work less well for the more
complex ones like perl or zsh.

It started with tools like perl; I'm a regular perl user and would not
want to miss it; but I remember the feeling I had when I first saw the
30 or so pages of perl in the early days. And as the man pages grow
larger it gets more difficult to locate a specific section because I
can't browse the whole stuff anymore and to find it with a regexp I
sometimes need two or three approaches to find stuff if I don't
remember the exact wording I'm looking for.

   (Nor would I want to print out the manual.  That would cost me money,
   and waste paper, and be less convenient than online documentation, and
   it would be difficult to keep up with each new release.)

There's no need to print out a manual if you don't want to. Today a
hypertext approach would work for me due to tools like lynx (the vt100
based web browser, so you wouldn't need Netscape or its ilk) or Emacs'
info mode. For me it's much more effective to browse through a well
organized manual with lynx or emacs than it is to page through 60+
pages of man pages with less.

I second Vidiot's suggestion to separate (a set of) terse man page(s)
and a much larger/better manual. I'd even be willing to help in
putting the latter together.

	--jc