PATCH: Correct the corrections to func.yo

PATCH: Correct the corrections to func.yo

[Bart Schaefer]

"the flag -U must be created" didn't make much sense.

Emacs' M-q appears to have run amok at one point.

The summary of how fpath searching works was just plain wrong.

A trailing quote got lost (and the whole phrase seemed to fit better in
parentheses anyway).

I also noticed that, in the printed manual, a new paragraph is begun any
time an findex() or cindex() etc. is used.  So there are some places in
e.g. jobs.yo that look really awful when printed, because cindex() calls
appear in the middle of sentences.  No patch for this yet; should there
be one?

(The reason for that placement of cindex() appears to be to get the page
number right in case the surrounding paragraph crosses a page boundary.
This is irrelevant to HTML and info, where the output looks fine; so we
appear to have a choice between stupid-looking accuracy or intelligent-
looking inaccuracy.)

Index: Doc/Zsh/func.yo
===================================================================
@@ -45,7 +45,7 @@
 tt(autoload) builtin or its equivalent is given the option tt(-U). This is
 recommended for the use of functions supplied with the zsh distribution.
 Note that for functions precompiled with the tt(zcompile) builtin command
-the flag tt(-U) must be created when the tt(.zwc) file is created, as the
+the flag tt(-U) must be provided when the tt(.zwc) file is created, as the
 corresponding information is compiled into the latter.
 
 For each var(element) in tt(fpath), the shell looks for three possible
@@ -67,20 +67,25 @@
 without the suffix.  Thus including an element such as
 `tt(/usr/local/funcs.zwc)' in tt(fpath) will speed up the search for
 functions, with the disadvantage that functions included must be explicitly
-recompiled by hand before the shell notices any changes.  )
-item(var(element)tt(/)var(function)tt(.zwc))( A file created with
-tt(zcompile), which is expected to contain the definition for
-var(function).  It may include other function definitions as well, but
-those are neither loaded nor executed; a file found in this way is searched
-em(only) for the definition of var(function).  )
-item(var(element)tt(/)var(function))( A file of zsh command text, taken to
-be the definition for var(function).  ) enditem()
-
-In summary, the order of searching is, first, directories in tt(fpath),
-with the earliest directory containing a function definition being used;
-within that directory, the newest of the three possibilities --- a compiled
-directory, a compiled function, or an ordinary function defition --- is
-used.
+recompiled by hand before the shell notices any changes.
+)
+item(var(element)tt(/)var(function)tt(.zwc))(
+A file created with tt(zcompile), which is expected to contain the
+definition for var(function).  It may include other function definitions
+as well, but those are neither loaded nor executed; a file found in this
+way is searched em(only) for the definition of var(function).
+)
+item(var(element)tt(/)var(function))(
+A file of zsh command text, taken to be the definition for var(function).
+)
+enditem()
+
+In summary, the order of searching is, first, in the em(parents of)
+directories in tt(fpath) for the newer of either a compiled directory or
+a directory in tt(fpath); second, if more than one of these contains a
+definition for the function that is sought, the leftmost in the tt(fpath)
+is chosen; and third, within a directory, the newer of either a compiled
+function or an ordinary function definition is used.
 
 pindex(KSH_AUTOLOAD, use of)
 If the tt(KSH_AUTOLOAD) option is set, or the file contains only a
@@ -90,8 +95,8 @@
 and may therefore define local parameters.  It is an error if the function
 is not defined by loading the file.
 
-Otherwise, the function body with no surrounding `var(funcname)tt(()
-{)var(...)tt(}) is taken to be the complete contents of the file.  This
+Otherwise, the function body (with no surrounding `var(funcname)tt(()
+{)var(...)tt(})') is taken to be the complete contents of the file.  This
 form allows the file to be used directly as an executable shell script.  If
 processing of the file results in the function being re-defined, the
 function itself is not re-executed.  To force the shell to perform

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Re: PATCH: Correct the corrections to func.yo

[Bart Schaefer]

While I'm on the topic ... can anybody give a good reason why chapter 12
(Compatibility) is (a) located where it is and (b) a full-fledged chapter?

It would seem to me that it'd make a whole lot more sense if it were just
a section within chapter 3 (Invocation).

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

PATCH (?): Relocate "Compatibility" and "Restricted Shell" docs

[Bart Schaefer]

On May 22,  5:29am, Bart Schaefer wrote:
}
} It would seem to me that it'd make a whole lot more sense if it were just
} a section within chapter 3 (Invocation).

I haven't committed this to SourceForge, but here it is for consideration.
I mean, what do compatibility and the restricted shell have in common with
conditional expressions, prompts, and expansion?

The one question I have left is why they're relagated to the zshmisc manual.
Would it be OK to include them in zsh.1, i.e., take out the ifnzman() in
invoke.yo?

Index: Doc/zsh.yo
===================================================================
@@ -53,9 +53,7 @@
 ifnzman(includefile(Zsh/jobs.yo))\x01
 ifnzman(includefile(Zsh/arith.yo))\x01
 ifnzman(includefile(Zsh/cond.yo))\x01
-ifnzman(includefile(Zsh/compat.yo))\x01
 ifnzman(includefile(Zsh/prompt.yo))\x01
-ifnzman(includefile(Zsh/restricted.yo))\x01
 ifnzman(includefile(Zsh/expn.yo))\x01
 ifnzman(includefile(Zsh/params.yo))\x01
 ifnzman(includefile(Zsh/options.yo))\x01
Index: Doc/zshmisc.yo
===================================================================
@@ -7,6 +7,6 @@
 includefile(Zsh/jobs.yo)\x01
 includefile(Zsh/arith.yo)\x01
 includefile(Zsh/cond.yo)\x01
-includefile(Zsh/compat.yo)\x01
 includefile(Zsh/prompt.yo)\x01
+includefile(Zsh/compat.yo)\x01
 includefile(Zsh/restricted.yo)\x01
Index: Doc/Zsh/compat.yo
===================================================================
@@ -1,8 +1,5 @@
-texinode(Compatibility)(Prompt Expansion)(Conditional Expressions)(Top)
-chapter(Compatibility)
-ifzman(\
+texinode(Compatibility)(Restricted Shell)()(Invocation)
 sect(Compatibility)
-)\
 cindex(compatibility)
 cindex(sh, compatibility)
 cindex(ksh, compatibility)
Index: Doc/Zsh/cond.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Conditional Expressions)(Compatibility)(Arithmetic Evaluation)(Top)
+texinode(Conditional Expressions)(Prompt Expansion)(Arithmetic Evaluation)(Top)
 chapter(Conditional Expressions)
 ifzman(\
 sect(Conditional Expressions)
Index: Doc/Zsh/expn.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Expansion)(Parameters)(Restricted Shell)(Top)
+texinode(Expansion)(Parameters)(Prompt Expansion)(Top)
 chapter(Expansion)
 cindex(expansion)
 sect(Description)
Index: Doc/Zsh/invoke.yo
===================================================================
@@ -32,3 +32,11 @@
 
 runs the script tt(scr), setting the tt(XTRACE) option by the corresponding
 letter `tt(-x)' and the tt(SH_WORD_SPLIT) option by name.
+
+startmenu()
+menu(Compatibility)
+menu(Restricted Shell)
+endmenu()
+
+ifnzman(includefile(Zsh/compat.yo))\x01
+ifnzman(includefile(Zsh/restricted.yo))\x01
Index: Doc/Zsh/manual.yo
===================================================================
@@ -20,9 +20,7 @@
 menu(Jobs & Signals)
 menu(Arithmetic Evaluation)
 menu(Conditional Expressions)
-menu(Compatibility)
 menu(Prompt Expansion)
-menu(Restricted Shell)
 menu(Expansion)
 menu(Parameters)
 menu(Options)
Index: Doc/Zsh/prompt.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Prompt Expansion)(Restricted Shell)(Compatibility)(Top)
+texinode(Prompt Expansion)(Expansion)(Conditional Expressions)(Top)
 chapter(Prompt Expansion)
 ifzman(\
 sect(Prompt Expansion)
Index: Doc/Zsh/restricted.yo
===================================================================
@@ -1,8 +1,5 @@
-texinode(Restricted Shell)(Expansion)(Prompt Expansion)(Top)
-chapter(Restricted Shell)
-ifzman(\
+texinode(Restricted Shell)()(Compatibility)(Invocation)
 sect(Restricted Shell)
-)\
 cindex(restricted shell)
 pindex(RESTRICTED)
 When the basename of the command used to invoke zsh starts with the letter

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Re: PATCH (?): Relocate "Compatibility" and "Restricted Shell" docs

[Peter Stephenson]

> On May 22,  5:29am, Bart Schaefer wrote:
> Would it be OK to include them in zsh.1, i.e., take out the ifnzman() in
> invoke.yo?

Sounds a good idea.

-- 
Peter Stephenson <pws@cambridgesiliconradio.com>
Cambridge Silicon Radio, Unit 300, Science Park, Milton Road,
Cambridge, CB4 0XL, UK                          Tel: +44 (0)1223 392070