From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <zsh-workers-request@euclid.skiles.gatech.edu>
Received: (qmail 4107 invoked from network); 31 Jan 1997 17:06:35 -0000
Received: from euclid.skiles.gatech.edu (list@130.207.146.50)
  by coral.primenet.com.au with SMTP; 31 Jan 1997 17:06:35 -0000
Received: (from list@localhost) by euclid.skiles.gatech.edu (8.7.3/8.7.3) id LAA19811; Fri, 31 Jan 1997 11:17:14 -0500 (EST)
Resent-Date: Fri, 31 Jan 1997 11:10:05 -0500 (EST)
From: Vidiot <brown@ftms.COM>
Message-Id: <199701311611.KAA17450@ftms.ftms.com>
Subject: Re: Man pages missing
To: zsh-users@math.gatech.edu (ZSH Mailing List)
Date: Fri, 31 Jan 1997 10:11:18 -0600 (CST)
In-Reply-To: <5847.199701311153@stone.dcs.warwick.ac.uk> from "Zefram" at Jan 31, 97 11:53:27 am
X-Mailer: ELM [version 2.4 PL24]
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Resent-Message-ID: <"4zwiT2.0.eg4.TbXyo"@euclid>
Resent-From: zsh-users@math.gatech.edu
X-Mailing-List: <zsh-users@math.gatech.edu> archive/latest/658
X-Loop: zsh-users@math.gatech.edu
X-Loop: zsh-workers@math.gatech.edu
Precedence: list
Resent-Sender: zsh-workers-request@math.gatech.edu

<>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.

This is not true.  There are many man pages that are not authoritative,
sh and csh being examples.  For detailed information, one has to consult
the separate sections about sh or csh.  The man page only needs to be
authoritative iff there is not a separate document that expands the man page.

<(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.)

That is definately your choice and PDF gives you the ability to do both,
or just one.

<>The main manual should be done using a package like Framemaker, which would
<>allow for easier WYSIWYG editing and formatting.
<
<I've never yet seen a WYSIWYG system that was as good
<as the WYGIWYG systems running on the same computers.

Huh?

<>                           Zsh needs a decent manual.  What we have now
<>are the man pages without the nroff/man-page-looking-format.
<
<And what do you have against man pages?

They are meant to be a quick reference to the syntax of a command or an
option.  For details and/or examples, expanded manuals are used.  Complicated
programs like Zsh require greatly expanded manuals, which is not the purpose
of man pages.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)