documentation (was Re: New user questions)

[Oliver Kiddle <opk@xxxxxxxxxxxxx>]

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