ZSH presence on WWW cf. Perl

ZSH presence on WWW cf. Perl

[Mark Borges]

[It's late Friday afternoon -- too late to do any real work ]

Hey--

Has anyone seen the Perl WWW page lately? It's at

	http://www.perl.com/perl/

With the release of perl-5.002 came a much better (IMO at least)
organization. There are several aspects I like about it -- the broad
categories, the update time-stamps, the diversions.

I think it could serve as good boilerplate material for zsh. Not
that there is anything seriously wrong with the zsh page at present
-- it's certainly functional. But I'm getting bored with it.

In particular, I'd like to suggest that the baseline documentation be
converted to something other than nroff, such as perlpod. Before you
yell and flame back, wait...

I do think it's very important to have a current, up-to-date, good old
man page for zsh; I'm just not convinced nroff is the best source. In
fact, after viewing the perl page, I'm far from convinced. The frame
interface for the documentation, at

ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/doc/manual/html/frames.html

-- if your browser/machine can withstand the bombardment -- is pretty
powerful for navigating the documentation. (I think Tom had must've had
some graduate slavery in addition to pod2html here.)

Further, POD is easy to type, which is important because documentation
updates would be far more likely to be bundled with the patches.

I know, POD is somewhat restrictive on the embellishments you can put
in the text, but that's secondary to information content as I see it.
And you get pod2man, pod2html, maybe even a pod2texi, for free.

Comments anyone? 

  -mb-

P.S> Of course, I myself have little time to do work on any of this ;-).

Re: ZSH presence on WWW cf. Perl

[Richard J. Coleman]

> With the release of perl-5.002 came a much better (IMO at least)
> organization. There are several aspects I like about it -- the broad
> categories, the update time-stamps, the diversions.
> 
> I think it could serve as good boilerplate material for zsh. Not
> that there is anything seriously wrong with the zsh page at present
> -- it's certainly functional. But I'm getting bored with it.

Yes, these pages are very nice.  Using them as a base for changes
to the zsh web pages is a good idea.

> In particular, I'd like to suggest that the baseline documentation be
> converted to something other than nroff, such as perlpod. Before you
> yell and flame back, wait...

I have looked at pod (and SGML, and other things) several times.
One of the things I don't like about pod, is that you can't put
things like boldface/italics in code examples.  The zsh pages uses
this quite a bit.

I agree that nroff is terrible.  I've been thinking maybe it's time
to scrap man pages altogether.  Put all the documentation into a
latex file, and create a nice zsh manual.

rc

Re: ZSH presence on WWW cf. Perl

[Chris Dean]

Mark Borges <mdb@cdc.noaa.gov> writes:
> Has anyone seen the Perl WWW page lately? It's at
> 
> 	http://www.perl.com/perl/

Yes, it's very good.

> In particular, I'd like to suggest that the baseline documentation be
> converted to something other than nroff, such as perlpod. 

This seems like a great idea.  I've been writing a lot (for me at
least) documentation recently using perlpod and am quite taken with
it.  It is so easy to make simple pages that I find myself actually
giving my end users documentation much quicker than I used to.

In the past I used TeX, but that made it difficult to distribute
online documentation.

The caveat is that perlpod's "intent is simplicity, not power", and
that you can't do complex things.

We should also provide a zsh*.man as well as a zsh*.pod for those
people who don't have Perl installed.

> And you get pod2man, pod2html, maybe even a pod2texi, for free.

As of today the pod2texi isn't very usable.

Chris Dean

Re: ZSH presence on WWW cf. Perl

[Zefram]

[on Perl POD]
>Further, POD is easy to type, which is important because documentation
>updates would be far more likely to be bundled with the patches.

We already tend to get man page updates, when necessary, with code
patches.  The cases where we don't I think are more due to people
forgetting than to the difficulty of using nroff.  Editing nroff source
is not difficult.

>And you get pod2man, pod2html, maybe even a pod2texi, for free.

pod2man would get us a man page, which we already have, and would do a
worse job of it than we would.  HTML is irrelevant.  pod2texi would let
us produce a printed manual, which can already be done from nroff, or
an info file, which is also irrelevant.  I don't see the advantage
here.

-zefram

Re: ZSH presence on WWW cf. Perl

[Bas V. de Bakker]

Zefram  <A.Main@dcs.warwick.ac.uk> writes:

[quoted out of context]

> HTML is irrelevant.
> 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.

Bas.

Re: ZSH presence on WWW cf. Perl

[Bas V. de Bakker]

"Richard J Coleman" <coleman@math.gatech.edu> writes:

> I agree that nroff is terrible.  I've been thinking maybe it's time
> to scrap man pages altogether.  Put all the documentation into a
> latex file, and create a nice zsh manual.

I like to have documentation on-line as well.  But every time I
proposed keeping only the texinfo file, there were loud protests from
various people.  I don't remember exactly why, probably because they
had nothing to read info with.

Bas.

Re: ZSH presence on WWW cf. Perl

[Peter Stephenson]

bas@astro.uva.nl wrote:
> "Richard J Coleman" <coleman@math.gatech.edu> writes:
> 
> > I agree that nroff is terrible.  I've been thinking maybe it's time
> > to scrap man pages altogether.  Put all the documentation into a
> > latex file, and create a nice zsh manual.
> 
> I like to have documentation on-line as well.  But every time I
> proposed keeping only the texinfo file, there were loud protests from
> various people.  I don't remember exactly why, probably because they
> had nothing to read info with.

One of the things I hate about systems that other people have set up
is finding there's no detailed documentation for (say) elm because the
only thing that got installed was a minimal manual page which points
you somewhere else, which might be on the machine in the directory
/usr/local/.hidden/.even_more_hidden/doc/dunno_where_to_put_this/elm
but might not be.  Only ordinary manual pages have a reasonable
probability of being installed by the average system administrator,
who has typically got better things to do than create new directory
structures for non-standard manual formats.  Even if you arrange for
info files to be installed automatically you have to rely on the
administrator not only providing an info reader but also changing the
`dir' file or even writing a new one --- although a decent script
should be able to handle this.

On the other hand, nroff is the worst format I can think of for a
standard.  It would be much better to have something which converts
easily into nroff.  I don't know of anything reliable and powerful
enough at the moment.

-- 
Peter Stephenson <pws@ifh.de>       Tel: +49 33762 77366
WWW:  http://www.ifh.de/~pws/       Fax: +49 33762 77330
Deutches Electronen-Synchrotron --- Institut fuer Hochenergiephysik Zeuthen
DESY-IfH, 15735 Zeuthen, Germany.

Re: ZSH presence on WWW cf. Perl

[Zefram]

>Zefram  <A.Main@dcs.warwick.ac.uk> writes:
>
>[quoted out of context]
>> HTML is irrelevant.
>> 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.

It may be useful, but it's not directly relevant to this discussion.
We're discussing documentation for a Unix shell, so the primary
requirement is that we have online documentation in the form of a Unix
man page.  Info is an unnecessary extra.  HTML is even less useful.
Automated conversion to TeX or LaTeX, however, is of some use, as a
nice printed manual would be a good thing.  (But it is possible to
simply print the man page anyway.)

-zefram

Re: ZSH presence on WWW cf. Perl

[Vidiot]

<
<"Richard J Coleman" <coleman@math.gatech.edu> writes:
<
<> I agree that nroff is terrible.  I've been thinking maybe it's time
<> to scrap man pages altogether.  Put all the documentation into a
<> latex file, and create a nice zsh manual.
<
<I like to have documentation on-line as well.  But every time I
<proposed keeping only the texinfo file, there were loud protests from
<various people.  I don't remember exactly why, probably because they
<had nothing to read info with.
<
<Bas.

Bingo.  Man pages are the way to get info on Unix programs.  Trying to tell
a user that there are TWO ways to find out how a program works will not
go over very well.  Nroff man pages are here to stay.

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

Re: ZSH presence on WWW cf. Perl

[Mark Borges]

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