PATCH: Docs out of sync

[Phil Pennock <phil@xxxxxxxxxxxxxxxxxxxxx>]

Typing away merrily, Peter Stephenson produced the immortal words:
> Phil Pennock wrote:
> > * bash has arrays.  'declare', 'local' & 'readonly' each accept '-a' to
> >   declare an array.  Is it reasonable to add '-a' to 'typeset'?  This
> >   would automatically duplicate the bash-ism.
> 
> It's not exactly essential, since bash and zsh have rather different
> extensions to sh in any case.  They're only similar in as much as they
> both include sh.  It's hard enough keeping ksh emulation working.

Looking through the source for 3.1.5-patched, bin_typeset et al accept
-a.  This is undocumented.  This functionality is not in 3.1.5.
With no arguments beyond the options, "typeset -a" scans the parameter
table for arrays.  "typeset -A" scans for hashes.  An added bonus!  ;^)
Except that "typeset -a foo" is silently ignored.  An unhandled case
later on.

Scanning back, Bart added this functionality in patch 4608 (Nov 12).
It was documented in the article, but no docs patch.  The options to
'local' were also modified.

Docs patch included at end of this article.

> >   Further, would it be an idea to then deprecate 'set -A' which
> >   overloads parameter setting onto 'set'?
> 
> That's needed for ksh.

Fair enough.  But adding 'setting' to typeset would round it out.

> If you mean `remove the extension if and only if it's .ext', then you
> can do ${${var:t}%.ext}.

Ah.  *DOH!*  Thanks.  My zsh-based javawrapper has now been suitably
fixed.  :^)

> I think it's too close to the history modifiers and we'd better stick
> with the subscript notation, unless we're aiming at a bash
> compatibility mode which is really going a bit far.

That's about what I thought -- too close for normal use.
Note though that there are already a number of option-aliases to match
bash.  How about a bash-compatibility which includes the sh stuff,
disables a new option, say, 'PARAM_HISTMODS' and perhaps one day sets
'BASH_SUBSTRINGS'?  A simpler idea would be to just note the possibility
for now and see what happens to bash in the future.

> It worries me slightly that there are people out there who don't know
> the difference between bash and sh --- which is their problem, but one
> day they may start inflicting it on other people.

Most of them seem to be writing systems scripts for Linux.  Come zsh 3.2
I am planning on trying a very careful experiment -- how much falls
apart with /bin/sh being zsh.

Patch stuff
-----------
The zsh-development-guide specifies context-diffs.  Is it okay to use
unified context diffs in future?

*** dDoc/Zsh/builtins.yo	Tue Nov 10 09:10:01 1998
--- Doc/Zsh/builtins.yo	Wed Dec  9 19:36:34 1998
***************
*** 512,518 ****
  endsitem()
  )
  findex(local)
! item(tt(local) [ {tt(PLUS())|tt(-)}tt(LRZilrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
  Same as tt(typeset), except that the options tt(-x) and
  tt(-f) are not permitted.
  )
--- 512,518 ----
  endsitem()
  )
  findex(local)
! item(tt(local) [ {tt(PLUS())|tt(-)}tt(ALRUZailrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
  Same as tt(typeset), except that the options tt(-x) and
  tt(-f) are not permitted.
  )
***************
*** 878,884 ****
  findex(typeset)
  cindex(parameters, setting)
  cindex(parameters, declaring)
! item(tt(typeset) [ {tt(PLUS())|tt(-)}tt(LRUZfilrtuxm) [var(n)]] [ var(name)[tt(=)var(value)] ... ])(
  Set attributes and values for shell parameters.
  When invoked inside a function a new parameter is created which will be
  unset when the function completes.  The new parameter will not be
--- 878,884 ----
  findex(typeset)
  cindex(parameters, setting)
  cindex(parameters, declaring)
! item(tt(typeset) [ {tt(PLUS())|tt(-)}tt(ALRUZafilrtuxm) [var(n)]] [ var(name)[tt(=)var(value)] ... ])(
  Set attributes and values for shell parameters.
  When invoked inside a function a new parameter is created which will be
  unset when the function completes.  The new parameter will not be
***************
*** 887,892 ****
--- 887,895 ----
  The following attributes are valid:
  
  startitem()
+ item(tt(-A))(
+ Declare var(name) to be an em(A)ssociation parameter (also known as a hash).
+ )
  item(tt(-L))(
  Left justify and remove leading blanks from var(value).
  If var(n) is nonzero, it defines the width of the field;
***************
*** 915,920 ****
--- 918,927 ----
  If var(n) is nonzero it defines the width of the field;
  otherwise it is determined by the width of the value of the
  first assignment.
+ )
+ item(tt(-a))(
+ On its own, this option produces a list of all array parameters.
+ If any non-options are provided, the tt(typeset) command is silently ignored.
  )
  item(tt(-f))(
  The names refer to functions rather than parameters.  No assignments

-- 
--> Phil Pennock ; GAT d- s+:+ a22 C++(++++) UL++++/I+++/S+++/H+ P++@ L+++
E-@ W(+) N>++ o !K w--- O>+ M V !PS PE Y+ PGP+ t-- 5++ X+ R !tv b++>+++ DI+ D+
G+ e+ h* r y?