From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <zsh-workers-request@euclid.skiles.gatech.edu>
Received: (qmail 630 invoked from network); 31 Jan 1997 07:16:18 -0000
Received: from euclid.skiles.gatech.edu (list@130.207.146.50)
  by coral.primenet.com.au with SMTP; 31 Jan 1997 07:16:18 -0000
Received: (from list@localhost) by euclid.skiles.gatech.edu (8.7.3/8.7.3) id AAA04197; Fri, 31 Jan 1997 00:52:44 -0500 (EST)
Resent-Date: Fri, 31 Jan 1997 00:46:12 -0500 (EST)
From: Vidiot <brown@ftms.COM>
Message-Id: <199701310547.XAA05940@ftms.ftms.com>
Subject: Re: Man pages missing
To: zsh-users@math.gatech.edu (ZSH Mailing List)
Date: Thu, 30 Jan 1997 23:47:24 -0600 (CST)
In-Reply-To: <kigg1zi30i6.fsf@jagor.srce.hr> from "Hrvoje Niksic" at Jan 31, 97 05:57:21 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: <"gUtqS1.0.az.aSOyo"@euclid>
Resent-From: zsh-users@math.gatech.edu
X-Mailing-List: <zsh-users@math.gatech.edu> archive/latest/647
X-Loop: zsh-users@math.gatech.edu
X-Loop: zsh-workers@math.gatech.edu
Precedence: list
Resent-Sender: zsh-workers-request@math.gatech.edu

<> In any event, I know n/t/groff and can muddle through TeX stuff.
<> I'll be damned if I am going to learn yodl.  To learn yet another
<> text processor is just too much.
<
<No, it's not too much.  What's too much is to have to handle too
<different documentation format, and sync them all the time.

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.

The manual should be vastly expanded, adding lots of examples of how all
of the various functions work.  Te current documentation discusses all
of the little pieces, but the big picture is easily lost.

The main manual should be done using a package like Framemaker, which would
allow for easier WYSIWYG editing and formatting.  Lots of examples could
be added to the document.  Zsh needs a decent manual.  What we have now
are the man pages without the nroff/man-page-looking-format.

Yes it would be a big project, something that I think Zsh deserves.

Using FrameMaker would also allow for the document to be turned into a PDF
file for on-line help.  Frankly, the current help files are old fashioned.
A state-of-the-art shell needs state-of-the-art manuals.

Those are my thoughts.

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)