Re: Man pages missing

[Bruce Stephens <stephens@math.ruu.nl>]

> Perl is a bad example, since there are books available in your local book
> store.  Zsh has no such book and really needs one.

I'd agree here.  When the dynamic loading and programmable zle stuff is
in, I'd have thought a book would be worthwhile.  Has anybody who
actually understands all of zsh looked into publisher interest in such
a thing?  The manual is pretty good, but it's still a bit referency.
The intro was pretty good, the last time I looked at it, but I'd pay
money for a full-length book covering the whole thing (especially once
the important new features have settled down a bit---if the dynamic
loading could be made compatible with ksh93's, and if it could drag in
Tk (perhaps not just yet, but when some future version of Tk is more
language independent), then surely that would sell).

> Advantages: graphical, can included visual examples (though I admit that there
>      isn't much in the way of graphics :-); the user can scale the size of
>      the help pages to suite the needs of the user; hypertext TOC and index;
>      just to name a few.

(On PDF.)  I don't see that much need for pictures.  If they're needed,
Texinfo can do them (you can put arbitrary TeX into the printed
version, and give other text (perhaps a character version of the
picture) for the online version.  Presumably the texinfo2html converter
can do pictures, or could easily be hacked to do them.  Presumably yodl
can also do something that allows access to these features, or could
easily be extended to do so.

> I've used texinfo a few times and do not like the interface.  One tends to
> hit the return key to move down lines.

Really?  I've never found myself doing that.  If it's such a big thing,
you could customize emacs to do that, assuming you're using emacs.  I
couldn't really recommend the standalone info reader---there's
something of a need for a nice up to date X-based reader.

> In any event one can argue about the best way for both systems.  I personally
> prefer a physical copy of a manual.  With PDF the user has the choice of
> using it on-line or printing it and making a copy that looks just like
> the on-line version, graphics and all.  A pure text manual from texinfo
> can't do that.

That's true, but it's deliberate.  I don't need menus in my printed
manual, but they're very useful when reading online.  Pictures are a
bit of a problem, but presumably not for zsh?  Personally, I'd hate
PDF-only manuals: Adobe's Acrobat reader is slow, pretty unreadable,
and generally clunky, especially compared with info in Emacs.  And I've
never found printing with it to be particularly successful
either---horribly slow, horribly big PostScript files.

> Of course, the source files for the text processor would
> be available and FrameMaker allows for the documentation to be used on all
> three major platforms; Unix, PC, Mac.

What's "FrameMaker"?  Should I have heard of it?   If it's commercial,
then I think zsh should avoid requiring it, including for development,
but certainly for use.