From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from euclid.skiles.gatech.edu (euclid.skiles.gatech.edu [130.207.146.50]) by melb.werple.net.au (8.7.4/8.7.3) with ESMTP id HAA09367 for ; Tue, 19 Mar 1996 07:03:40 +1100 (EST) Received: (from list@localhost) by euclid.skiles.gatech.edu (8.7.3/8.7.3) id OAA14715; Mon, 18 Mar 1996 14:48:56 -0500 (EST) Resent-Date: Mon, 18 Mar 1996 14:48:56 -0500 (EST) Sender: mdb@cdc.noaa.gov To: zsh-workers@math.gatech.edu Subject: Re: ZSH presence on WWW cf. Perl Organization: CIRES, University of Colorado X-Attribution: mb References: <3061.199603180908@stone.dcs.warwick.ac.uk> From: Mark Borges Date: 18 Mar 1996 12:47:49 -0700 In-Reply-To: Zefram's message of Mon, 18 Mar 1996 09:07:59 +0000 (GMT) Message-Id: Resent-Message-ID: <"fup8-2.0.rb3.euRJn"@euclid> Resent-From: zsh-workers@math.gatech.edu X-Mailing-List: archive/latest/840 X-Loop: zsh-workers@math.gatech.edu Precedence: list Resent-Sender: zsh-workers-request@math.gatech.edu >> On Mon, 18 Mar 1996 09:07:59 +0000 (GMT), >> Zefram (Z) wrote: >> Zefram writes: >> >> [quoted out of context] >> HTML is irrelevant. ?? Zefram, can you define what you mean by "irrelevant" here? How do you judge whether something is irrelevant? By tradition? Or functionality? Or demonstrated use? What? I'm not particularly fond of HTML myself, but it is a workable tool that makes some documentation easier to navigate. Certainly you'd agree it's much harder to find a particular piece of emacs documentation using `man' than info (were a complete man page for emacs to exist, that is). Many vendors (MATLAB, NCAR Graphics to name a couple) provide HTML documentation online, because they apparently realize that web browsers, if not prevalent already, will be or are readily available. Whether zsh documentation fits into this category remains to be answered. The length of the documentation is somewhat in-between a clear demarcation. >> an info file, which is also irrelevant. >> >> Could you explain this? I think info files are quite useful. >> IMHO, they are easier to navigate than long man pages, whether >> those man pages are split or not. Z> It may be useful, but it's not directly relevant to this Z> discussion. We're discussing documentation for a Unix shell, so Z> the primary requirement is that we have online documentation in the Z> form of a Unix man page. Info is an unnecessary extra. HTML is Z> even less useful. Automated conversion to TeX or LaTeX, however, Z> is of some use, ...and impossible. AFAIK, there is no automated "man2texi" tool. And *if* we want to make current, up-to-date HTML docs, there is also no automated "man2html" tool. This latter is important, because I personally will not be converting nroff source to HTML. I know about `rman', but it does a far from perfect job on the zsh nroff source. I know, because that's how the current (and obsolete) HTML documentation was created in the first place. I just simply don't have the time to do this anymore (so answering `no' to the first sentence would be OK with me). And for the record, I *never* stated that nroff man pages should not be supported. In fact, I believe nroff source should be *required* for any unix utility (and I would categorize shells as unix utilities for this discussion). Note that Tom Christiansen, who helped develop perl, absolutely detests unix programs without proper (read nroff source) documentation. (He also detests emacs, but that's another thread ;-) ). Yet, you will find no nroff-source documentation for perl; the baseline docs are written in perl-pod, and converted when necessary. BTW, what language has more $#@[{+ characters than perl? The pod2man-converted perl man page still gets the information across, by having these characters stand out in other ways besides embellishing them. I don't think a death blow to pod should be dealt just because (for example) some characters cannot appear in bold face very easily. Or is there some other limiting factor of pod that makes it utterly unusable for zsh documentation that I'm unaware of? Examples? I guess we need to answer the elegance/functionality aspect of the zsh man page once and for all, and then take it from there. If we must have the current typesetting of the zsh man page (or something even prettier) I guess pod is out. Finally, here are some crude numbers for the past month access of the man page documentation at the ZSH web site: $ egrep 'Feb/1996.*zsh/Doc/man' /WWW/httpd/logs/access_log | wc -l 657 and for comparison, $ egrep 'Feb/1996.*zsh/FAQ' /WWW/httpd/logs/access_log | wc -l 601 So, despite the out-of-date man page, some people (cats? ;-^) are using the on-line docs. (I can refine these numbers more if anyone wants history and/or access by subsection, etc. to debate some more. There is 38Mb of access data available to parse). OK. Enough rambling. I just wanted to hopefully make my views and position a bit more clear. -mb-