zsh.texi

zsh.texi

[Clive Messer]

Hi,

For several weeks now, I've been hacking/modifying/updating the texinfo
source (zsh.texi) to reflect the changes made since it was last updated
(about 25 years ago ;-), and now have it finished.  

Anyway, to cut a long story short, the diff is larger than the new
file so it would be pretty stupid mailing that. 

The updated zsh.texi is 65k gzip'd.
Am I going to get flamed for posting it to the list - should I just mail
it to Zoltan ?????

Clive.
-- 
C Messer. Epos Systems. UK.  |
<clive@epos.demon.co.uk>     |   "I pressed her thigh and death smiled."
<clive@epos.easynet.co.uk>   |    Jim Morrison.                       

Re: zsh.texi

[Hrvoje Niksic]

Clive Messer (clive@epos.demon.co.uk) wrote:
> The updated zsh.texi is 65k gzip'd.
> Am I going to get flamed for posting it to the list - should I just mail
> it to Zoltan ?????

I think it's OK to post it -- large messages do get posted to the list
from time to time. And, some of us would probably like to see what
you've done before Zoltan makes it to the release.

-- 
hniksic@srce.hr              |  Student of electrical engineering
hniksic@fly.cc.fer.hr        |  University of Zagreb, Croatia
------------------------------------------------------------------
* Q: What is an experienced Emacs user?
* A: A person who wishes that the terminal had pedals.

Re: zsh.texi

[Zoltan Hidvegi]

> 
> Hi,
> 
> For several weeks now, I've been hacking/modifying/updating the texinfo
> source (zsh.texi) to reflect the changes made since it was last updated
> (about 25 years ago ;-), and now have it finished.  
> 
> Anyway, to cut a long story short, the diff is larger than the new
> file so it would be pretty stupid mailing that. 
> 
> The updated zsh.texi is 65k gzip'd.
> Am I going to get flamed for posting it to the list - should I just mail
> it to Zoltan ?????

Mark Borges <mdb@cdc.noaa.gov> is also working on the documentation.  Please
contact him.  If anyone wants to start a big work like that it is better to
tell his plans on the zsh-workers list to avoid duplicate work.

Zoltan

Re: zsh.texi

[Clive Messer]

On Mon, 10 Jun 1996, Zoltan Hidvegi wrote:
 
> > For several weeks now, I've been hacking/modifying/updating the texinfo
> > source (zsh.texi) to reflect the changes made since it was last updated
> > (about 25 years ago ;-), and now have it finished.  
> > 
> > Anyway, to cut a long story short, the diff is larger than the new
> > file so it would be pretty stupid mailing that. 
> > 
> > The updated zsh.texi is 65k gzip'd.
> > Am I going to get flamed for posting it to the list - should I just mail
> > it to Zoltan ?????
> 
> Mark Borges <mdb@cdc.noaa.gov> is also working on the documentation. 
> Please contact him.  

Mark has already contacted me. :-)

> If anyone wants to start a big work like that it is better to
> tell his plans on the zsh-workers list to avoid duplicate work.

Well, the truth is that when I started working on it, I had no idea I
would ever finish it.  Whilst I appreciate that it may have saved
duplication of effort, had I announced my intention I would have felt
committed to coming up with the goods.  Without going into detail, my
personal circumstances are such at the moment that I am unable to commit 
myself to any project no matter how big or small.  Anyway, Mark has mailed
me so I'll let him take a look at what I've done and see if he has
anything to add/change and we'll take it from there.

Clive
-- 
C Messer. Epos Systems. UK.  |
<clive@epos.demon.co.uk>     |   "I pressed her thigh and death smiled."
<clive@epos.easynet.co.uk>   |    Jim Morrison.                       

Re: zsh.texi

[Mark Borges]

>> On Mon, 10 Jun 1996 16:52:25 +0100 (BST),
>> Clive Messer(CM) wrote:
CM> For several weeks now, I've been hacking/modifying/updating the
CM> texinfo source (zsh.texi) to reflect the changes made since it was
CM> last updated (about 25 years ago ;-), and now have it finished.

With Clive's permission, I've uploaded this to the zsh web site at

   http://www.mal.com/zsh/Doc/test/zsh.texi.gz

I've also run it through texi2html-1.50; you can access the table of
contents via

   http://www.mal.com/zsh/Doc/test/zsh_toc.html

Please take a look if you're interested. We would appreciate any
suggestions or comments (or better, patches) anyone may have. Now is
the time to make your wishes known.

Also, please don't forget to CC any correspondence to Clive
(clive@epos.demon.co.uk).

Thanks.

-- 
  -mb-

Re: zsh.texi

[Bart Schaefer]

Forbidden

Your client does not have permission to get URL /zsh/Doc/test/zsh.texi.gz from this server.
On Jun 12, 11:25pm, Mark Borges wrote:
} Subject: Re: zsh.texi
}
}    http://www.mal.com/zsh/Doc/test/zsh.texi.gz

"403 Forbidden

Your client does not have permission to get URL /zsh/Doc/test/zsh.texi.gz
from this server."

}    http://www.mal.com/zsh/Doc/test/zsh_toc.html
} 
} Please take a look if you're interested. We would appreciate any
} suggestions or comments (or better, patches) anyone may have.

Spell-check it.

-- 
Bart Schaefer                             Brass Lantern Enterprises
http://www.well.com/user/barts            http://www.nbn.com/people/lantern

New male in /home/schaefer:
>N  2 Justin William Schaefer  Sat May 11 03:43  53/4040  "Happy Birthday"

Re: zsh.texi

[Bart Schaefer]

On Jun 12, 11:25pm, Mark Borges wrote:
} Subject: Re: zsh.texi
}
} Please take a look if you're interested. We would appreciate any
} suggestions or comments (or better, patches) anyone may have.

I'm just glancing at the programmable completion section at the moment.
Some of it is still pretty hard to decipher.  Here's an example:


-d This can be combined with -F, -B, -w, -a, -R and -G to get names of
       disabled functions, builtins, reserved words or aliases. 
-e Without -d this option has no effect. Otherwise this can be combined
       with -F, -B, -w, -a, -R and -G to get names of functions, builtins,
       reserved words or aliases even if they are disabled. 


That stuff under -e doesn't make sense to me -- Without -d, has no effect?
You mean I have to use `compctl -d -e ...'?  Why? -- and it conflicts with
the zshcompctl.man description:

-e Names of executable (and enabled) commands.

Here's another example:


-C controls completion when there is no current command, in other words when
       the command word itself is being completed. Without this command, the
       names of any executable command (whether in the path or specific to
       the shell, such as aliases or functions) are completed.



"Without this command, ..." ??  Without what command?  I think it means
"If no `compctl -C' command has been issued in the current shell, ...".

Then there's this:


If the + flag is alone and followed immediately by the command list, the
completion behavior for all the commands in the list is reset to its default
by deleting the command from the list of those handled specially.



I think this means:

If the + flag is alone and followed immediately by a list of command names,
any previous programmable completion for each of those commands is disabled.
This restores the default completions for the listed commands.


As a general remark, this sort of documentation should avoid talking about
how a given operation is accomplished (e.g., above, dump the "by deleting
the command from the list ... handled specially") and just state what the
end result is.  Only discuss how something works if that's important for
using the feature correctly; and even then, *first* concisely describe
the end result, and *then* elaborate how it comes to pass.

-- 
Bart Schaefer                             Brass Lantern Enterprises
http://www.well.com/user/barts            http://www.nbn.com/people/lantern

New male in /home/schaefer:
>N  2 Justin William Schaefer  Sat May 11 03:43  53/4040  "Happy Birthday"

Re: zsh.texi

[Bart Schaefer]

On Jun 12, 11:25pm, Mark Borges wrote:
} Subject: Re: zsh.texi
}
} I've also run it through texi2html-1.50
} 
} Please take a look if you're interested. We would appreciate any
} suggestions or comments (or better, patches) anyone may have.

I don't know if it's broken in the base document or if it's the fault
of texi2html, but double-quoted strings in some examples are really
messed up:


-H num pattern 
       [...snip...]
       A typical use is `compctl -D -f + -H 0 " -X '(No file found; using history)''

-l cmd
       [...snip...] 
       example, `compctl -x 'r[-exec,;]' -l " -- find'

-- 
Bart Schaefer                             Brass Lantern Enterprises
http://www.well.com/user/barts            http://www.nbn.com/people/lantern

New male in /home/schaefer:
>N  2 Justin William Schaefer  Sat May 11 03:43  53/4040  "Happy Birthday"

Re: zsh.texi

[Clive Messer]

On Wed, 12 Jun 1996, Bart Schaefer wrote:

> On Jun 12, 11:25pm, Mark Borges wrote:

> } Subject: Re: zsh.texi
> }
> }    http://www.mal.com/zsh/Doc/test/zsh.texi.gz
> 
> "403 Forbidden
> 
> Your client does not have permission to get URL /zsh/Doc/test/zsh.texi.gz
> from this server."

I dare say Mark will fix this.
 
> }    http://www.mal.com/zsh/Doc/test/zsh_toc.html
> } 
> } Please take a look if you're interested. We would appreciate any
> } suggestions or comments (or better, patches) anyone may have.
> 
> Spell-check it.

Unfortunately, Mark does not have the latest working copy (with spelling
corrections) and will not have until I return home and upload it this
evening. 

> I'm just glancing at the programmable completion section at the moment.
> Some of it is still pretty hard to decipher.  Here's an example:
>
>
> -d This can be combined with -F, -B, -w, -a, -R and -G to get names of
>        disabled functions, builtins, reserved words or aliases. 
> -e Without -d this option has no effect. Otherwise this can be combined
>        with -F, -B, -w, -a, -R and -G to get names of functions, builtins,
>        reserved words or aliases even if they are disabled. 
>
>
> That stuff under -e doesn't make sense to me -- Without -d, has no
> effect?
> You mean I have to use `compctl -d -e ...'?  Why? -- and it conflicts
> with the zshcompctl.man description:
>
> -e Names of executable (and enabled) commands.

Yes, the above is wrong.  I will correct it when I return home this
evening before I upload the latest version to Mark.

> Here's another example:
>
>
> -C controls completion when there is no current command, in other words
> when the command word itself is being completed. Without this command,
> the names of any executable command (whether in the path or specific to
> the shell, such as aliases or functions) are completed.
>
>
> "Without this command, ..." ??  Without what command?  I think it means
> "If no `compctl -C' command has been issued in the current shell, ...".

This is a direct copy of zshcompctl.man.
Perhaps it needs to be clarified in the man page.

> Then there's this:
>
>
> If the + flag is alone and followed immediately by the command list, the
> completion behavior for all the commands in the list is reset to its
> default by deleting the command from the list of those handled
> specially.
>
> I think this means:
>
> If the + flag is alone and followed immediately by a list of command
> names, any previous programmable completion for each of those commands
> is disabled. This restores the default completions for the listed
> commands.

Again, this is a direct copy of the man page.

> As a general remark, this sort of documentation should avoid talking
> about how a given operation is accomplished (e.g., above, dump the "by
> deleting the command from the list ... handled specially") and just
> state what the end result is.  Only discuss how something works if
> that's important for using the feature correctly; and even then, *first*
> concisely describe the end result, and *then* elaborate how it comes to
> pass.

I did not set out to re-write the man pages, just port them to texinfo.
zsh.texi (at present) is a copy of the man pages in texinfo format with 
an expanded "Introduction" that includes the META-FAQ.

> I don't know if it's broken in the base document or if it's the fault
> of texi2html, but double-quoted strings in some examples are really
> messed up:
>
>
> -H num pattern 
>        [...snip...]
>        A typical use is `compctl -D -f + -H 0 " -X '(No file found;
>        using history)''
>
> -l cmd
>        [...snip...] 
>        example, `compctl -x 'r[-exec,;]' -l " -- find'

This is a problem with doubled single-quote characters ie. ''
They are correctly handled (@iftex / @ifinfo) in the source so I would
assume that the problem is with texi2html.

Clive.
-- 
C Messer. Epos Systems. UK.  |
<clive@epos.demon.co.uk>     |   "I pressed her thigh and death smiled."
<clive@epos.easynet.co.uk>   |    Jim Morrison.                       

Re: zsh.texi

[Bart Schaefer]

On Jun 13,  2:49pm, Clive Messer wrote:
} Subject: Re: zsh.texi
}
} > -C controls completion when there is no current command, in other words
} > when the command word itself is being completed. Without this command,
} 
} This is a direct copy of zshcompctl.man.
} Perhaps it needs to be clarified in the man page.
} 
} > If the + flag is alone and followed immediately by the command list, the
} 
} Again, this is a direct copy of the man page.
} 
} > As a general remark, this sort of documentation should avoid talking
} > about how a given operation is accomplished (e.g., above, dump the "by
} > deleting the command from the list ... handled specially") and just
} > state what the end result is.  Only discuss how something works if
} > that's important for using the feature correctly; and even then, *first*
} > concisely describe the end result, and *then* elaborate how it comes to
} > pass.
} 
} I did not set out to re-write the man pages, just port them to texinfo.

Aha.  I haven't read through all the new man pages.  Well, then, whoever
is maintaining the manual pages should consider the above as commentary
on those, and it should get fixed in *both* places. ;->

-- 
Bart Schaefer                             Brass Lantern Enterprises
http://www.well.com/user/barts            http://www.nbn.com/people/lantern

New male in /home/schaefer:
>N  2 Justin William Schaefer  Sat May 11 03:43  53/4040  "Happy Birthday"

Re: zsh.texi

[Mark Borges]

>> On Thu, 13 Jun 1996 14:49:05 +0100 (BST),
>> Clive Messer(CM) wrote:
CM> On Wed, 12 Jun 1996, Bart Schaefer wrote:
>> On Jun 12, 11:25pm, Mark Borges wrote:
>> }
>> }    http://www.mal.com/zsh/Doc/test/zsh.texi.gz
>> 
>> "403 Forbidden
>> 
>> Your client does not have permission to get URL /zsh/Doc/test/zsh.texi.gz
>> from this server."

CM> I dare say Mark will fix this.

Yes, sorry. Someday I'll remember to fix the  permissions after
ftp'ing a file.

>> Spell-check it.

CM> Unfortunately, Mark does not have the latest working copy (with
CM> spelling corrections) and will not have until I return home and
CM> upload it this evening.

I do now (zsh-2.0.2).

Anyway, anyone wanting a copy of this second draft, please try
again. I guarantee the permissions are OK this time :-).

-- 
  -mb-

Re: zsh.texi

[Zoltan Hidvegi]

Bart Schaefer wrote:
> I'm just glancing at the programmable completion section at the moment.
> Some of it is still pretty hard to decipher.  Here's an example:
> 
> 
> -d This can be combined with -F, -B, -w, -a, -R and -G to get names of
>        disabled functions, builtins, reserved words or aliases. 
> -e Without -d this option has no effect. Otherwise this can be combined
>        with -F, -B, -w, -a, -R and -G to get names of functions, builtins,
>        reserved words or aliases even if they are disabled. 
> 
> 
> That stuff under -e doesn't make sense to me -- Without -d, has no effect?
> You mean I have to use `compctl -d -e ...'?  Why? -- and it conflicts with
> the zshcompctl.man description:
> 
> -e Names of executable (and enabled) commands.

Sorry for the late response but I was away in the last few days.  Actually
in beta20 I corrected the documentation of compctl -e and compctl -d, and I
also changed its behaviout a little bit.  If you try compctl -e and compctl
-d in any zsh version you'll see that it does not behave as it is
documented.  In beta20 it behaved as described above.  -e or -d only have
effect if combined with -F, -B, -w, -a, -R or -G.  But these flags by
default only complete enabled commands, so compctl -e has no effect
(because it is assumed as default).  This means that -e is only necessary
if you'd like to complete both enabled and disabled commands when you use
-ed.  This may seem to be illogical.  The logical solution is to list
enabled commands by default, but with -d, list only disabled ones and with
an other flag list all of them but this would be incompatible with the old
versions (but since -e and -d was not documented correctly this may not be
a big problem).

Before beta20 the above options listed all builtins/aliases/functions even
if they were disabled.  Before beta20 there were no commands to complete
external commands or reserved words.  These new flags were added in beta20.

There are some problems with compctl -L output in beta20 which I've already
fixed (but I did not send patch, it'll be in beta21).  The maual still
needs some corrections.  The description of -, command, noglob and exec
prefixes should probably be moved into zshbuiltins.man because these are
builtins now.  But the present location may be better for these so it may
be better to keep them there noting that these are builtins, remove these
from the reserved word list and add to zshbuiltins.man with pointers to the
documentation in zshmisc(1).

There will be some other changes in beta21 which require changes in the
maual.  I rewrote redirection handling to conform POSIX.  In beta21 in a
>& $foo redirection $foo will be expanded first, and if the result is a
number, - or p, that filenumber is duplicated, a file is closed or the
output is written to the coprocess.  Otherwise >& redirects both stdout and
stderr.  The &>, &>|, &>> etc. syntax can be used for redirecting both
stdout and stderr when the filename is a number or - or p.  This was taken
from bash.

I'd like to implement <> redirection as well which is often quite useful
and it is required by POSIX as well.  When not in sh/ksh mode <> will only
be recocnized as a redirection if it is delimited from the word before and
after it or if it is immediately preceeded by a digit.  E.g.
% foo arguments 2<> bar      # redirection
% foo arguments2<>  bar      # numeric glob
% foo arguments 22<> bar     # numeric glob
% foo arguments <>bar        # numeric glob
% foo arguments <> bar       # redirection
% foo arguments <-> bar      # numeric glob

In sh/ksh mode <> will always be interpreted as a redirection and <-> will
be required to match an arbitrary number.

Zoltan

Re: zsh.texi

[Zefram]

>I'd like to implement <> redirection as well which is often quite useful
>and it is required by POSIX as well.  When not in sh/ksh mode <> will only
>be recocnized as a redirection if it is delimited from the word before and
>after it or if it is immediately preceeded by a digit.  E.g.

I think actually <> should *always* do redirection.  The glob syntax,
<->, is only one charater longer.

-zefram

<> redirection operator (was: zsh.texi)

[Zoltan Hidvegi]

Zefram wrote:
> >I'd like to implement <> redirection as well which is often quite useful
> >and it is required by POSIX as well.  When not in sh/ksh mode <> will only
> >be recocnized as a redirection if it is delimited from the word before and
> >after it or if it is immediately preceeded by a digit.  E.g.
> 
> I think actually <> should *always* do redirection.  The glob syntax,
> <->, is only one charater longer.

I agree with that but I'm afraid that this change will break many scripts.
But it would be definitely simpler and cleaner, and the documentation would
be much simpler and less confusing.

Zoltan

Re: <> redirection operator (was: zsh.texi)

[Zefram]

>I agree with that but I'm afraid that this change will break many scripts.
>But it would be definitely simpler and cleaner, and the documentation would
>be much simpler and less confusing.

How often do you use numerical globbing?  I've only ever used it
interactively.  It wouldn't be the first time we've changed behaviour,
and the change required to scripts is trivial.

And regarding the &> redirection you mentioned: I think this is a bad
idea.  It's not POSIX conformant (consider `a &> b c`), and it's not
really necessary.  It is possible to redirect to a file called "-" by
doing `>& ./-`.

-zefram

Re: <> redirection operator (was: zsh.texi)

[Zoltan Hidvegi]

> >I agree with that but I'm afraid that this change will break many scripts.
> >But it would be definitely simpler and cleaner, and the documentation would
> >be much simpler and less confusing.
> 
> How often do you use numerical globbing?  I've only ever used it
> interactively.  It wouldn't be the first time we've changed behaviour,
> and the change required to scripts is trivial.

I decided: in beta21, <> will always do redirection.

> And regarding the &> redirection you mentioned: I think this is a bad
> idea.  It's not POSIX conformant (consider `a &> b c`), and it's not

Yes, a &> b c will work differently from what POSIX requires but a & > b c
will be OK.  I do not think that there is any script which contains
adjacent & and >.

> really necessary.  It is possible to redirect to a file called "-" by
> doing `>& ./-`.

The biggest problem is when you use parameter expansion.  When you write
>& $foo you cannot tell in advance wether the output will be closed or if
it goes to a file, or to an other file descriptor or to the coprocess.

Implementing &> is very simple and I do not think that it conflicts with
any scripts (and a portable script which expects POSIX behaviour should not
use &> anyway since bash uses it for redirectiog standard output and
error which means that such a script will not work under Linux).

Zoltan

Re: <> redirection operator (was: zsh.texi)

[Peter Stephenson]

hzoli@cs.elte.hu wrote:
> I decided: in beta21, <> will always do redirection.

This is a big enough change it should go on zsh-announce to see what
the punters think.  It was probably inevitable eventually, but it
would be nice to have some way of easing the pain.  For example,
perhaps the DEBUG code for the next few betas could print some message
like "warning: <> interpreted as redirection".  That shouldn't be much
bother since people are going to be slow to use it.  Otherwise,
debugging is going to be nasty.

Just in case you wanted to know, I have had scripts with this in in
the past.  It's very convenient for managing sets of data files.  That
may have been in the days when I didn't automatically write everything
in perl.

-- 
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: <> redirection operator (was: zsh.texi)

[Peter Whaite]

Peter Stephenson said:
> hzoli@cs.elte.hu wrote:
> > I decided: in beta21, <> will always do redirection.
> 
> This is a big enough change it should go on zsh-announce to see what
> the punters think.

Yeah.  '<->' is a bit cumbersome.  Too bad '#' means something else.

One thing that isnt clear to me.  Is this change just for scripts (everyone
keeps talking about scripts)?  Is it intended that '<>' still means numeric
glob in interactive mode?

> Just in case you wanted to know, I have had scripts with this in in
> the past.  It's very convenient for managing sets of data files.  That
> may have been in the days when I didn't automatically write everything
> in perl.

You bet.  And for managing mh directories.  However all these are things I do
in interactive mode.  Having to use '<->' in a script is fine.