PATCH: Re: documentation (was Re: New user questions)

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

On Mar 31, 11:36am, Oliver Kiddle wrote:
} Subject: documentation (was Re: New user questions)
}
} I think we should move the basic descriptions for fundamental builtins
} like bindkey to where the builtins are all described and add a
} reference to it from the zsh modules section.

If you look at the 3.0.x documentation (where there aren't any modules)
you'll see that it used to be like that.  The builtins that were moved
to modules had their doc moved to each module's doc approximately at the
same time the code was broken out.

} It would also make them easier to find in printed manuals
} because it is easy to flick through the manual until getting a glimpse
} of something that looks like the builtins and then using the
} alphabetical order to find the right one.

I don't disagree, but don't you ever look in the index?

It's been a very long time since the first thing I did after bringing
up the zsh info was not to hit `i' and enter the keyword I want.  (That's
why I finally got annoyed enough to add the styles and tags to an index.)
 
} Also on the subject of the arrangement of the documentation. I think it
} would be better if chapter 23 (Completion System) was moved to come
} before chapter 22 (Zsh Modules) so that we have the chapter on
} Completion Widgets and Completion System together.

Yes.

} I also think it might be a good idea to turn the chapter on completion
} using compctl into just a subsection of Zsh Modules. I think of the
} compctl module as just there for backward compatibility for those
} people who haven't moved to the new system. It would also bring new
} user's attention to the new system first.

No, I disagree.  The new completion system and completion widgets are
both introduced in the compctl section, and it's a better simple intro
to completion than either of the others.  At least until we get a more
substantial rewrite, I think it should stay where it is.

On the other hand, having the word "Programmable" in the title of only
the compctl section is a bit misleading.  This patch drops that word.

It's too bad texinfo doesn't deal better with more deeply-nested section
hierarchy.

Index: Doc/zsh.yo
===================================================================
@@ -61,10 +61,10 @@
 ifnzman(includefile(Zsh/options.yo))

 ifnzman(includefile(Zsh/builtins.yo))

 ifnzman(includefile(Zsh/zle.yo))

-ifnzman(includefile(Zsh/compwid.yo))

 ifnzman(includefile(Zsh/compctl.yo))

-ifnzman(includefile(Zsh/modules.yo))

+ifnzman(includefile(Zsh/compwid.yo))

 ifnzman(includefile(Zsh/compsys.yo))

+ifnzman(includefile(Zsh/modules.yo))

 ifnzman(includefile(Zsh/zftpsys.yo))

 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
@@ -75,10 +75,10 @@
 source(zshoptions)
 source(zshbuiltins)
 source(zshzle)
-source(zshcompwid)
 source(zshcompctl)
-source(zshmodules)
+source(zshcompwid)
 source(zshcompsys)
+source(zshmodules)
 source(zshzftpsys)
 manpage(ZSHALL)(1)(date())(zsh version())
 )\
Index: Doc/Zsh/compctl.yo
===================================================================
@@ -1,5 +1,5 @@
-texinode(Programmable Completion Using compctl)(Zsh Modules)(Completion Widgets)(Top)
-chapter(Programmable Completion Using compctl)
+texinode(Completion Using compctl)(Completion Widgets)(Zsh Line Editor)(Top)
+chapter(Completion Using compctl)
 cindex(completion, programmable)
 cindex(completion, controlling)
 ifzman(\
@@ -50,7 +50,7 @@
 menu(Example)
 endmenu()
 
-texinode(Command Flags)(Option Flags)()(Programmable Completion Using compctl)
+texinode(Command Flags)(Option Flags)()(Completion Using compctl)
 sect(Command Flags)
 Completion of the arguments of a command may be different for each
 command or may use the default.  The behavior when completing the
@@ -145,7 +145,7 @@
 (the empty string) and, if that generates no matches, will try case
 insensitive completion.
 
-texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion Using compctl)
+texinode(Option Flags)(Alternative Completion)(Command Flags)(Completion Using compctl)
 sect(Option Flags)
 startlist()
 list([ tt(-fcFBdeaRGovNAIOPZEnbjrzu/12) ])
@@ -540,7 +540,7 @@
 )
 enditem()
 
-texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion Using compctl)
+texinode(Alternative Completion)(Extended Completion)(Option Flags)(Completion Using compctl)
 sect(Alternative Completion)
 startlist()
 list(tt(compctl) [ tt(-CDT) ] var(options) tt(PLUS()) var(options) [ tt(PLUS()) ... ] \
@@ -555,7 +555,7 @@
 If the list of flags contains a tt(-t) with a tt(PLUS()) character, the next
 list of flags is used even if the current list produced matches.
 
-texinode(Extended Completion)(Example)(Alternative Completion)(Programmable Completion Using compctl)
+texinode(Extended Completion)(Example)(Alternative Completion)(Completion Using compctl)
 sect(Extended Completion)
 startlist()
 list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
@@ -666,7 +666,7 @@
 )
 enditem()
 
-texinode(Example)()(Extended Completion)(Programmable Completion Using compctl)
+texinode(Example)()(Extended Completion)(Completion Using compctl)
 sect(Example)
 
 example(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' \ 
Index: Doc/Zsh/compsys.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Completion System)(Zftp Function System)(Zsh Modules)(Top)
+texinode(Completion System)(Zsh Modules)(Completion Widgets)(Top)
 chapter(Completion System)
 cindex(completion system)
 cindex(completion, programmable)
Index: Doc/Zsh/compwid.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Completion Widgets)(Programmable Completion Using compctl)(Zsh Line Editor)(Top)
+texinode(Completion Widgets)(Completion System)(Completion Using compctl)(Top)
 chapter(Completion Widgets)
 cindex(completion, widgets)
 cindex(completion, programmable)
Index: Doc/Zsh/manual.yo
===================================================================
@@ -28,10 +28,10 @@
 menu(Options)
 menu(Shell Builtin Commands)
 menu(Zsh Line Editor)
+menu(Completion Using compctl)
 menu(Completion Widgets)
-menu(Programmable Completion Using compctl)
-menu(Zsh Modules)
 menu(Completion System)
+menu(Zsh Modules)
 menu(Zftp Function System)
 
  --- Indices ---
@@ -98,7 +98,7 @@
 menu(Completion)
 menu(Miscellaneous)
 
-Programmable Completion Using compctl
+Completion Using compctl
 
 menu(Command Flags)
 menu(Option Flags)
@@ -112,6 +112,15 @@
 menu(Builtin Commands)
 menu(Condition Codes)
 menu(Examples)
+
+Completion System
+
+menu(Initialization)
+menu(Completion System Configuration)
+menu(Control Functions)
+menu(Bindable Commands)
+menu(Completion Functions)
+menu(Completion Directories)
 
 Zsh Modules
 
Index: Doc/Zsh/mod_compctl.yo
===================================================================
@@ -4,7 +4,7 @@
 The tt(zsh/compctl) module makes available two builtin commands. tt(compctl),
 is the old, deprecated way to control completions for ZLE.  See
 ifzman(zmanref(zshcompctl))\
-ifnzman(noderef(Programmable Completion Using compctl))\
+ifnzman(noderef(Completion Using compctl))\
 .
 The other builtin command, tt(compcall) can be used in user-defined
 completion widgets, see
Index: Doc/Zsh/modules.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Zsh Modules)(Completion System)(Programmable Completion Using compctl)(Top)
+texinode(Zsh Modules)(Zftp Function System)(Completion System)(Top)
 chapter(Zsh Modules)
 cindex(modules)
 sect(Description)
Index: Doc/Zsh/zftpsys.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Zftp Function System)()(Completion System)(Top)
+texinode(Zftp Function System)()(Zsh Modules)(Top)
 chapter(Zftp Function System)
 cindex(zftp function system)
 cindex(FTP, functions for using shell as client)
Index: Doc/Zsh/zle.yo
===================================================================
@@ -1,4 +1,4 @@
-texinode(Zsh Line Editor)(Completion Widgets)(Shell Builtin Commands)(Top)
+texinode(Zsh Line Editor)(Completion Using compctl)(Shell Builtin Commands)(Top)
 chapter(Zsh Line Editor)
 cindex(line editor)
 cindex(editor, line)

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