Out of the box user experience

Out of the box user experience

[Bruce Stephens]

I'm a bit unhappy about all these completion scripts not being
installed somewhere.  How about sticking them in $prefix/lib/zsh/ (in
suitable subdirectories---maybe version-specific?), and adding a
shell-set parameter, ZSH_SCRIPTS or ZSH_LIB or something, so it's easy
to find them.

Then the suggestions in the README can be made more concrete for new
users (we could even provide a script to do it).  Something like:

        % zsh -f
        % mkdir ~/completion
        % cp $ZSH_LIB/**/*(.) ~/completion
        % touch ~/.zshrc; echo 'fpath=(~/completion $fpath)' >> .zshrc
        % echo '[[ -f ~/completion/compinit ]] && . ~/completion/compinit -d' >> .zshrc

or something.  I like the idea of individual users being able to have
whatever completions they like, and to be able to avoid ones that they
don't want, but I'd like it to be as easy as possible.  (Perhaps we'd
want just "cp $ZSH_LIB/{Core,Base,User}/* ~/completion", or something,
assuming that there'd be lots of seriously optional scripts.)

Hmm.  There are other scripts that could be installed, too, which
aren't completion-related.  Maybe it has to be
$ZSH_LIB/Completion/{Core,...


On a different topic, I noticed some typos in the new documentation.
Would it be helpful if I took the pws-12 docs and checked them?  I
don't guarantee to spot errors (since there's lots of stuff I just
don't understand), but I'm likely to spot most spelling errors and the
more obvious things.  Or would it be better if I waited for a bit
longer (when things are closer to a release)?

Re: Out of the box user experience

[Peter Stephenson]

Bruce Stephens wrote:
> I'm a bit unhappy about all these completion scripts not being
> installed somewhere.  How about sticking them in $prefix/lib/zsh/ (in
> suitable subdirectories---maybe version-specific?), and adding a
> shell-set parameter, ZSH_SCRIPTS or ZSH_LIB or something, so it's easy
> to find them.

This will probably happen (if someone does it).  The last thing I though of
was two configure options, --completion-lib for where to install it
and --completion-install=core,base,builtins,all (with a cumulative effect)
to specify what to install.

> Then the suggestions in the README can be made more concrete for new
> users (we could even provide a script to do it).

That might be a good idea.

> On a different topic, I noticed some typos in the new documentation.
> Would it be helpful if I took the pws-12 docs and checked them?  I
> don't guarantee to spot errors (since there's lots of stuff I just
> don't understand), but I'm likely to spot most spelling errors and the
> more obvious things.  Or would it be better if I waited for a bit
> longer (when things are closer to a release)?

The zshcompwid manual is probably not finished yet, since there are a few
bits still in the pipeline.  I was intending to tidy it up when it was.
Then there may be a separate manual for the standard functions.  Any
existing non-completion-widget documentation is probably unlikely to change
much unless changed forcibly.

-- 
Peter Stephenson <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy

Re: Out of the box user experience

[Bruce Stephens]

Peter Stephenson <pws@ibmth.df.unipi.it> writes:

> Bruce Stephens wrote:
> > How about sticking them in $prefix/lib/zsh/ (in suitable
> > subdirectories---maybe version-specific?), and adding a shell-set
> > parameter, ZSH_SCRIPTS or ZSH_LIB or something, so it's easy to
> > find them.
> 
> This will probably happen (if someone does it).  The last thing I
> though of was two configure options, --completion-lib for where to
> install it and --completion-install=core,base,builtins,all (with a
> cumulative effect) to specify what to install.

What about Functions, Misc (and StartupFiles, for that matter)?

Specifically, what does RedHat do when they build a binary package of
zsh?  (I really ought to look, I suppose!)  

I'm guessing they regard the example functions and things as
documentation, and install it into /usr/doc/zsh-$ZSH_VERSION.

Why not install the whole lot in subdirectories of
$prefix/lib/zsh/3.1.6?  Actually, I suppose that looks ugly, since the
modules get stuck there.  Maybe the modules could go into a
subdirectory too?  

I suppose the scripts really ought to go into
$prefix/share/zsh/$ZSH_VERSION/*.  That would be a better division.
So the modules stay where they are, and the scripts (including
completion) get stuck in share somewhere.

I'd prefer to have them installed automatically.  I don't see the need
for optional installation of these scripts.

> The zshcompwid manual is probably not finished yet, since there are
> a few bits still in the pipeline.  I was intending to tidy it up
> when it was.

OK.

> Then there may be a separate manual for the standard functions.  Any
> existing non-completion-widget documentation is probably unlikely to
> change much unless changed forcibly.

OK.  As far as I remember, the last time I read the manual I didn't
notice anything wrong (other than features I hadn't noticed before,
and the general overwhelming complexity of it).  

So I probably shouldn't spend time on checking the documentation.  If
I feel the urge, I may have a go at writing some new documentation
instead.

Re: Out of the box user experience

[Bart Schaefer]

Bruce Stephens writes:
 > Peter Stephenson <pws@ibmth.df.unipi.it> writes:
 > 
 > What about Functions, Misc (and StartupFiles, for that matter)?

Please let's NOT encourage admins to installed canned /etc/z* files.  They
very seldom accomplish what the admin thought they would, and I don't want
to give anyone the impression that StartupFiles contains stuff that we
believe should appear in /etc/z* -- because it doesn't.

 > Specifically, what does RedHat do when they build a binary package of
 > zsh?  (I really ought to look, I suppose!)
 > 
 > I'm guessing they regard the example functions and things as
 > documentation, and install it into /usr/doc/zsh-$ZSH_VERSION.

Yes; `rpm -ql zsh` says:

/bin/zsh
/etc/zlogin
/etc/zlogout
/etc/zprofile
/etc/zshenv
/etc/zshrc
/usr/doc/zsh-3.0.5
/usr/doc/zsh-3.0.5/BUGS
/usr/doc/zsh-3.0.5/CONTRIBUTORS
/usr/doc/zsh-3.0.5/ChangeLog
/usr/doc/zsh-3.0.5/Etc
/usr/doc/zsh-3.0.5/Etc/BUGS
/usr/doc/zsh-3.0.5/Etc/CONTRIBUTORS
/usr/doc/zsh-3.0.5/Etc/FAQ
/usr/doc/zsh-3.0.5/Etc/FEATURES
/usr/doc/zsh-3.0.5/Etc/MACHINES
/usr/doc/zsh-3.0.5/Etc/Makefile
/usr/doc/zsh-3.0.5/Etc/Makefile.in
/usr/doc/zsh-3.0.5/Etc/NEWS
/usr/doc/zsh-3.0.5/FAQ
/usr/doc/zsh-3.0.5/FEATURES
/usr/doc/zsh-3.0.5/Functions
/usr/doc/zsh-3.0.5/Functions/Makefile
/usr/doc/zsh-3.0.5/Functions/Makefile.in
/usr/doc/zsh-3.0.5/Functions/acx
/usr/doc/zsh-3.0.5/Functions/cat
/usr/doc/zsh-3.0.5/Functions/cdmatch
/usr/doc/zsh-3.0.5/Functions/cdmatch2
/usr/doc/zsh-3.0.5/Functions/checkmail
/usr/doc/zsh-3.0.5/Functions/cx
/usr/doc/zsh-3.0.5/Functions/harden
/usr/doc/zsh-3.0.5/Functions/mere
/usr/doc/zsh-3.0.5/Functions/multicomp
/usr/doc/zsh-3.0.5/Functions/proto
/usr/doc/zsh-3.0.5/Functions/pushd
/usr/doc/zsh-3.0.5/Functions/randline
/usr/doc/zsh-3.0.5/Functions/run-help
/usr/doc/zsh-3.0.5/Functions/yp
/usr/doc/zsh-3.0.5/Functions/yu
/usr/doc/zsh-3.0.5/Functions/zed
/usr/doc/zsh-3.0.5/META-FAQ
/usr/doc/zsh-3.0.5/NEWS
/usr/doc/zsh-3.0.5/README
/usr/doc/zsh-3.0.5/Util
/usr/doc/zsh-3.0.5/Util/Makefile
/usr/doc/zsh-3.0.5/Util/Makefile.in
/usr/doc/zsh-3.0.5/Util/helpfiles
/usr/doc/zsh-3.0.5/Util/reporter
/usr/doc/zsh-3.0.5/Util/zsh-development-guide
/usr/info/zsh.info-1.gz
/usr/info/zsh.info-2.gz
/usr/info/zsh.info-3.gz
/usr/info/zsh.info-4.gz
/usr/info/zsh.info-5.gz
/usr/info/zsh.info-6.gz
/usr/info/zsh.info-7.gz
/usr/info/zsh.info.gz
/usr/man/man1/zsh.1
/usr/man/man1/zshall.1
/usr/man/man1/zshbuiltins.1
/usr/man/man1/zshcompctl.1
/usr/man/man1/zshexpn.1
/usr/man/man1/zshmisc.1
/usr/man/man1/zshoptions.1
/usr/man/man1/zshparam.1
/usr/man/man1/zshzle.1

However, the /etc/z* files are NOT the ones from StartupFiles.

/etc/zshenv sets up X11HOME and $path; /etc/zshrc sets the umask and a few
aliases (like mv='nocorrect mv'), exports USER, LOGIN, HOSTNAME, and MAIL,
and runs bindkey -e; /etc/zlogin and /etc/zprofile are entirely comments,
and /etc/zlogout contains only "clear".

This is all zsh-3.0.5, of course; there's no "official" packaging of any
3.1 version.  There's a contrib of 3.1.2-zefram4, but I've never installed
it anywhere.

Re: Out of the box user experience

[Bruce Stephens]

Bart Schaefer <schaefer@tiny.zanshin.com> writes:

> Please let's NOT encourage admins to installed canned /etc/z* files.
> They very seldom accomplish what the admin thought they would, and I
> don't want to give anyone the impression that StartupFiles contains
> stuff that we believe should appear in /etc/z* -- because it
> doesn't.

I wasn't suggesting that!  I agree absolutely that administrators
should consider carefully what, if anything, should go into /etc/z*.

>  > I'm guessing they regard the example functions and things as
>  > documentation, and install it into /usr/doc/zsh-$ZSH_VERSION.
> 
> Yes; `rpm -ql zsh` says:

[...]

Right, that all looks sensible.  I still like the idea of installing
scripts into $prefix/share or something, and defining a convenience
variable that points at them.  

If nobody beats me to it, I may make a patch for that.  Would it be
helpful if I wrote an RPM spec file?  (I have no experience whatsoever
in doing this, but I've been reading about it recently.)