zsh.texi commentary (actually, HTML pages commentary)

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

On Jun 20,  3:03pm, Mark Borges wrote:
} Subject: Re: zsh-2.6-beta21 released
}
} I've applied this patch and re-generated the html files via
} texi2html-1.50. The URL is still
} 
} 	http://www.mal.com/zsh/Doc/test/
} 
} where zsh.texi.gz is version 2.03.

I think maybe it should be clearer in the documents that 2.03 is the
version number of the document and not the version of zsh to which it
refers.  `Edition 2.0.3' on the TOC page is confusing.

For the rest of these comments, I don't know which need to change the
man pages, the FAQ, zsh.texi, and/or all of them; but they're all from
reading the HTML at the above URL.

I've scattered semi-related thoughts and commentary throughout, usually
prefixed with "Aside:".


Intro section:

<pf@xxxxxxxxxx> hasn't been a usable address for Paul since almost two
years ago.  He's now <pf@xxxxxxxxxxxx>.

Aside:  Question about NO_RCS:
    Commands are first read from `/etc/zshenv'. If the -f flag is
    given or if the NO_RCS option is set within `/etc/zshenv', all
    other initialization files are skipped.
Why doesn't NO_RCS in any init file stop reading of any files that would
normally follow the one where it is set?  Or does it, and the doc just
doesn't explicitly say so?

Spell checking still hasn't happened ... "defauly"?


Shell Grammar section:

    A simple command is a sequence of optional parameter assignments
    followed by blank-separated words,
                ^^^^^
Should this read "whitespace" or some such?  (Too early to mention $IFS.)

Aside:  What's the value of a command executed in the background?  E.g.
	if false & then echo Hmmm & fi
Is it always consistent?

Precommand modifiers, `exec', should explain that the "parent" zsh is
replaced by the exec'd command, as if zsh had exited and the command
was run in its place.

Spell checking again ... "anexternal" --> "an external".

Almost all the complex command descriptions could be clarified.  Example:

    (Existing text)
	if list 
	then list 
	[ elif list ; then list ] ... 
	[ else list ] 
	fi	The if list is executed, and, if it returns a zero
		exit status, the then list is executed.  Otherwise,
		the elif list is executed and, if its value is zero,
		the then list is executed. If each elif list returns
		nonzero, the else list is executed.   

    (Better, I think)
	  if list1
	  then list2
	[ elif list3
	  then list4 ] ...
	[ else list5 ]
	  fi	First list1 is executed, and, if its value is zero (it
		returns a zero exit status), then list2 is executed.
		Otherwise, if any elif is present, list3 is executed,
		and, if its value is zero, then list4 is executed.
		There may be more than one elif, each of which is
		tried in turn.  Finally, if an else is present, and if
		all the if or elif lists returned nonzero values, then
		list5 is executed.

The others aren't quite as bad because they don't need to repeat any one
term in so many different places, but "while" and "until" are similar.

Further, the whole section could benefit from some vertical white space
between defined terms.  Looks like it's there in the source but gets
squashed out when displayed.  I suppose its a texi2html problem (some
strategic <br> need to be output).

Aside:  "select" is pretty much useless for more than 200 words or so.
I've got some scripts that examine the file system that sometimes come
up with 1000+ possible choices.  Anybody have any solutions?

Aside:  Why doesn't `foreach name ( word ... )' need CSH_JUNKIE_PARENS?

Aside:  That it is possible to `disable -r fi' without first disabling
`if', scares the willies out of me.  Simliarly for `done' and `esac'.

Aside:  Given the above behavior of `disable -r', it'd be nice to be able
to get at the internal tokens for the disabled reserved words.  E.g.:
    foo() { if true ; then echo This function keeps working ; fi }
    alias endif=fi
    disable -r fi
    bar() { if true ; then echo I wish this still worked ; endif }
Maybe an option to the alias builtin?

The paragraph on Comments still refers to HISTCHARS; it's now histchars.

texi2html is still having problems with pairs of single quotes (''),
rendering that as a double quote (").


Expansion section:

Why doesn't this section order the explanations of the kinds of expansion
in the same order in which they are listed as taking place?  Or at least
in some sensible order, such as alphabetical?

I'd love it if there were more hrefs, e.g. from every reference to an
option name to the description of that option, or from a builtin's name
to its description.  E.g., in the sentence:
    The PUSHD_MINUS option exchanges the effects of ~+ and ~-
    where they are followed by a number.
It'd be great to be able to click on PUSHD_MINUS.

Only the "expression" part of identifier=expression is expanded, right?
    If the option MAGIC_EQUAL_SUBST is set, any unquoted shell
    argument in the form identifier=expression becomes eligible
    for file expansion as described in the previous paragraph.
Say so?

Parameter expansion:  Italics on usages of `name[@]' are not consistent.
Typo in ${name:#pattern}, "the } flag" should probably be "the @ flag".
${^spec}, ${=spec}, and ${~spec} still say "Toggle ..."; they should say
"Turn on ...", right?  Also, more details of what `spec' may be would be
nice; e.g., is there a difference between ${#${foo}} and ${#foo} ??

The following statement is false for ${name:#pattern}, is it not?
    If the colon is omitted from one of the above expressions
    containing a colon, then the shell only checks whether name
    is set or not, not whether it is null.

There's something odd here:
    Arithmetic Expansion

    A string of the form $[exp] is substituted with the value of
    the arithmetic expression exp. exp is subjected to parameter
    expansion, command substitution and arithmetic expansion before
                                    ^^^^^^^^^^^^^^^^^^^^^^^^
    it is evaluated. See section Arithmetic Evaluation. 
Is this wrong, or is it just a goofy way of saying that $[exp] can be
nested?  (Which doesn't seem to be true, so that's not it.)

Aside:  Filename generation:  If you set both NULL_GLOB and NO_NOMATCH,
which one wins?  What the heck happened to NO_NOMATCH when the change
was made to make the prefix "no" into a magic equivalent of "unsetopt"?
`setopt nonomatch' should be the same as `unsetopt nomatch', but what
about `setopt nomatch'??  Why isn't it `unsetopt match'?  Gaahhh.  Or
did I completely misunderstand what that was all about?

Why isn't ***/ mentioned anywhere?  That's like **/ except it follows
symlinks, correct?

Modifiers:  One of either the doc or the behavior of the `g' prefix is
wrong.  The doc says:
    g	Apply the change to the first occurrence of a match in
	each word, by prefixing the above (for example, g&). 
In fact, the behavior is that the change is applied to EVERY occurrence
of a match in every word; the `w' modifier does only the first in each.
(The description above, and not the actual behavior, is what I'd expect
from the `g' modifier based on csh, but ....)

That's as far as I'm going to get tonight; tomorrow night I might get to
read the rest.

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