Re: ZSH presence on WWW cf. Perl

[Mark Borges <mdb@cdc.noaa.gov>]

>> On Mon, 18 Mar 1996 09:07:59 +0000 (GMT),
>> Zefram (Z) wrote:
>> Zefram  <A.Main@dcs.warwick.ac.uk> 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-