From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 1857 invoked from network); 31 Jan 1997 12:58:39 -0000 Received: from euclid.skiles.gatech.edu (list@130.207.146.50) by coral.primenet.com.au with SMTP; 31 Jan 1997 12:58:39 -0000 Received: (from list@localhost) by euclid.skiles.gatech.edu (8.7.3/8.7.3) id HAA10958; Fri, 31 Jan 1997 07:45:30 -0500 (EST) Resent-Date: Fri, 31 Jan 1997 07:36:05 -0500 (EST) Date: Fri, 31 Jan 1997 13:36:48 +0100 Message-Id: <199701311236.AA30548@mail2.gmd.de> From: Juergen Christoffel To: zefram@dcs.warwick.ac.uk Cc: brown@ftms.COM, zsh-users@math.gatech.edu In-Reply-To: <5847.199701311153@stone.dcs.warwick.ac.uk> (message from Zefram on Fri, 31 Jan 1997 11:53:27 +0000 (GMT)) Subject: Re: Man pages missing Resent-Message-ID: <"lliFY2.0.wc2.qSUyo"@euclid> Resent-From: zsh-users@math.gatech.edu X-Mailing-List: archive/latest/652 X-Loop: zsh-users@math.gatech.edu X-Loop: zsh-workers@math.gatech.edu Precedence: list Resent-Sender: zsh-workers-request@math.gatech.edu From: Zefram 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