RE: New user questions

RE: New user questions

[Sven Wischnowsky]

[ moved to zsh-workers ]

Andrej Borsenkow wrote:

> ...
> 
> This is in modules section (Zle module). But, yes, I never liked this.
> Users are not supposed to know, if command is implemented in core or
> module.
> 
> man zshmodules

But without the module they won't get the builtin (parameter,
condition code, whatever...), so they may be in for a surprise.

Hm, maybe add pointers to the module docs in builtins.yo? (And also in 
params.yo, cond.yo??)

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

RE: New user questions

[Andrej Borsenkow]

> >
> > This is in modules section (Zle module). But, yes, I never
> liked this.
> > Users are not supposed to know, if command is implemented in core or
> > module.
> >
> > man zshmodules
>
> But without the module they won't get the builtin (parameter,
> condition code, whatever...), so they may be in for a surprise.
>
> Hm, maybe add pointers to the module docs in builtins.yo?
> (And also in
> params.yo, cond.yo??)
>

I mostly referred to those modules, that are autoloaded by default. You
hardly can imagine Zsh without ZLE. And this is completely transparent,
users do not need to load any modules manually and may not even know
that modules exist.

-andrej

documentation (was Re: New user questions)

[Oliver Kiddle]

Sven Wischnowsky wrote:
 
> Andrej Borsenkow wrote:

> > This is in modules section (Zle module). But, yes, I never liked this.
> > Users are not supposed to know, if command is implemented in core or
> > module.

> But without the module they won't get the builtin (parameter,
> condition code, whatever...), so they may be in for a surprise.

I agree with Andrej here - I generally do know when a command is
implemented in a module yet I still find myself looking among all the
other builtins before my slow brain kicks in and I remember that I
should be looking at the back. 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. 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.

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

Oliver

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

[Bart Schaefer]

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))\x01
 ifnzman(includefile(Zsh/builtins.yo))\x01
 ifnzman(includefile(Zsh/zle.yo))\x01
-ifnzman(includefile(Zsh/compwid.yo))\x01
 ifnzman(includefile(Zsh/compctl.yo))\x01
-ifnzman(includefile(Zsh/modules.yo))\x01
+ifnzman(includefile(Zsh/compwid.yo))\x01
 ifnzman(includefile(Zsh/compsys.yo))\x01
+ifnzman(includefile(Zsh/modules.yo))\x01
 ifnzman(includefile(Zsh/zftpsys.yo))\x01
 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