21898: insert-composed-char can take command line argument

21899: add "roadmap" to manual

ChangeLog

@@ -1,3 +1,14 @@
+2005-10-21  Peter Stephenson  <pws@csr.com>
+
+	* 21899: Doc/.distfiles, Doc/Makefile.in, Doc/zsh.yo,
+	Doc/zshroadmap.yo, Doc/Zsh/.distfiles, Doc/Zsh/intro.yo,
+	Doc/Zsh/invoke.yo, Doc/Zsh/manual.yo, Doc/Zsh/roadmap.yo:
+	Add "roadmap" section to manual for new users to get
+	acquainted.
+
+	* 21898: Functions/Zle/insert-composed-char, Doc/Zsh/contrib.yo:
+	insert-composed-char can take a command line argument.
+
 2005-10-19  Wayne Davison  <wayned@users.sourceforge.net>
 
 	* unposted: Src/Zle/zle_refresh.c: fixed a compiler warning.

Doc/.distfiles

@@ -4,11 +4,11 @@ DISTFILES_SRC='
     version.yo zmacros.yo zman.yo ztexi.yo
     zsh.yo zshbuiltins.yo zshcompctl.yo zshcompsys.yo zshcompwid.yo
     zshexpn.yo zshmisc.yo zshmodules.yo zshoptions.yo zshparam.yo
-    zshzftpsys.yo zshzle.yo zshcontrib.yo zshtcpsys.yo
+    zshroadmap.yo zshzftpsys.yo zshzle.yo zshcontrib.yo zshtcpsys.yo
     zsh.texi
     zsh.1 zshbuiltins.1 zshcompctl.1 zshcompsys.1 zshcompwid.1 zshexpn.1
-    zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1 zshzle.1 zshall.1
-    zshzftpsys.1 zshcontrib.1 zshtcpsys.1
+    zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1 zshroadmap.1
+    zshzle.1 zshall.1 zshzftpsys.1 zshcontrib.1 zshtcpsys.1
 '
 
 DISTFILES_DOC='

Doc/Makefile.in

@@ -47,7 +47,8 @@ TEXI2HTML = texi2html --output . --ifinfo --split=chapter
 # man pages to install
 MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 zshcompsys.1 \
 zshcontrib.1 zshexpn.1 zshmisc.1 zshmodules.1 \
-zshoptions.1 zshparam.1 zshtcpsys.1 zshzftpsys.1 zshzle.1 zshall.1
+zshoptions.1 zshparam.1 zshroadmap.1 zshtcpsys.1 zshzftpsys.1 zshzle.1 \
+zshall.1
 
 # yodl documentation
 
@@ -194,6 +195,8 @@ zshoptions.1: Zsh/options.yo
 
 zshparam.1: Zsh/params.yo
 
+zshroadmap.1: Zsh/roadmap.yo
+
 zshtcpsys.1: Zsh/tcpsys.yo
 
 zshzftpsys.1: Zsh/zftpsys.yo

Doc/Zsh/.distfiles

@@ -12,6 +12,7 @@ DISTFILES_SRC='
     mod_terminfo.yo mod_zftp.yo mod_zle.yo mod_zleparameter.yo
     mod_zselect.yo mod_zutil.yo mod_zprof.yo mod_zpty.yo
     modules.yo modlist.yo modmenu.yo manmodmenu.yo
-    options.yo params.yo prompt.yo redirect.yo restricted.yo seealso.yo
+    options.yo params.yo prompt.yo redirect.yo restricted.yo
+    roadmap.yo seealso.yo
     zftpsys.yo zle.yo contrib.yo tcpsys.yo
 '

Doc/Zsh/contrib.yo

@@ -671,6 +671,13 @@ together form a mnemonic for the character to be inserted.  The
 two-character codes are a subset of those given by RFC 1345 (see for
 example tt(http://www.faqs.org/rfcs/rfc1345.html)).
 
+The function may optionally be followed by up to two characters which
+replace one or both of the characters read from the keyboard; if both
+characters are supplied, no input is read.  For example,
+tt(insert-composed-char a:) can be used within a widget to insert an a with
+umlaut into the command line.  This has the advantages over use of a
+literal character that it is more portable.
+
 For best results zsh should have been built with support for multibyte
 characters (configured with tt(--enable-multibyte)); however, the function
 works for the limited range of characters available in single-byte

Doc/Zsh/intro.yo

@@ -1,4 +1,4 @@
-texinode(Introduction)(Invocation)(The Z Shell Manual)(Top)
+texinode(Introduction)(Roadmap)(The Z Shell Manual)(Top)
 chapter(Introduction)
 cindex(introduction)
 ifzman(\
@@ -15,6 +15,7 @@ startlist()
 ifzshone(\
 list(em(zsh)          Zsh overview (this section))
 )\
+list(em(zshroadmap)   Informal introduction to the manual)
 list(em(zshmisc)      Anything not fitting into the other sections)
 list(em(zshexpn)      Zsh command and parameter expansion)
 list(em(zshparam)     Zsh parameters)

Doc/Zsh/invoke.yo

@@ -1,4 +1,4 @@
-texinode(Invocation)(Files)(Introduction)(Top)
+texinode(Invocation)(Files)(Roadmap)(Top)
 chapter(Invocation)
 cindex(invocation)
 sect(Invocation Options)

Doc/Zsh/manual.yo

@@ -14,6 +14,7 @@ Version version(), last updated date().
 startmenu()
 menu(The Z Shell Manual)
 menu(Introduction)
+menu(Roadmap)
 menu(Invocation)
 menu(Files)
 menu(Shell Grammar)

Doc/Zsh/roadmap.yo

@@ -0,0 +1,150 @@
+texinode(Roadmap)(Invocation)(Introduction)(Top)
+chapter(Roadmap)
+cindex(roadmap)
+
+The Zsh Manual, like the shell itself, is large and often complicated.
+This section of the manual provides some pointers to areas of the shell
+that are likely to be of particular interest to new users, and indicates
+where in the rest of the manual the documentation is to found.
+
+sect(When the shell starts)
+
+When it starts, the shell reads commands from various files.  These can
+be created or edited to customize the shell.  See ifzman(the section
+Startup/Shutdown Files in zmanref(zsh))\
+ifnzman(noderef(Files)).
+
+sect(Interactive use)
+
+Interaction with the shell uses the builtin Zsh Line Editor, ZLE.  This is
+described in detail in ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor)).
+
+The first decision a user must make is whether to use the Emacs or Vi
+editing mode as the keys for editing are substantially different.  Emacs
+editing mode is probably more natural for beginners and can be selected
+explicitly with the command tt(bindkey -e).
+
+A history mechanism for retrieving previously typed lines (most simply with
+the Up or Down arrow keys) is available; note that, unlike other shells,
+zsh will not save these lines when the shell exits unless you set
+appropriate variables.  See the description of the shell variables
+(referred to in the documentation as parameters) tt(HISTFILE), tt(HISTSIZE)
+and tt(SAVEHIST) in ifzman(zmanref(zshparams))\
+ifnzman(noderef(Parameters Used By The Shell)).
+
+The line editor provides an extensive completion system and the shell
+is supplied for completions with many commonly used commands.  Note
+that the new completion system referred to as tt(compsys) is preferred
+over the older tt(compctl) system.  The completion system must be enabled
+explicitly when the shell starts.  For more information see
+ifzman(zmanref(zshcompssy))\
+ifnzman(noderef(Completion System)).
+
+Apart from completion, the line editor is highly extensible by means of
+shell functions.  Some useful functions are provided with the shell; they
+provide facilities such as:
+
+startitem()
+item(tt(insert-composed-char))(
+composing characters not found on the keyboard
+)
+item(tt(match-words-by-style))(
+configuring what the line editor considers a word when moving or
+deleting by word
+)
+item(tt(history-beginning-search-backward-end), etc.)(
+alternative ways of searching the shell history
+)
+item(tt(replace-string), tt(replace-pattern))(
+functions for replacing strings or patterns globally in the command line.
+)
+enditem()
+
+See ifzman(the section `ZLE Functions' in zmanref(zshcontrib))\
+ifnzman(noderef(ZLE Functions)) for descriptions of these.
+
+sect(Options)
+
+The shell has a large number of options for changing its behaviour.
+These cover all aspects of the shell; browsing the full documentation is
+the only good way to become acquainted with the many possibilities.  See
+ifzman(zmanref(zshoptions))\
+ifnzman(noderef(Options)).
+
+sect(Pattern matching)
+
+The shell has a rich set of patterns which are available for file matching
+(described in the documentation as `filename generation' and also known for
+historical reasons as `globbing') and for use when programming.  These are
+described in ifzman(the section `Filename Generation' in zmanref(zshexpn))\
+ifnzman(noderef(Filename Generation)).
+
+Of particular interest are the following patterns that are not commonly
+supported by other systems of pattern matching:
+
+startitem()
+item(tt(**))(
+for matching over multiple directories
+)
+item(tt(~), tt(^))(
+the ability to exclude patterns from matching when the tt(EXTENDED_GLOB)
+option is set
+)
+item(tt(LPAR())var(...)tt(RPAR()))(
+glob qualifiers, included in parentheses at the end of the pattern,
+which select files by type (such as directories) or attribute (such as
+size).
+)
+enditem()
+
+sect(General Comments on Syntax)
+
+Although the syntax of zsh is in ways similar to the Korn shell, and
+therefore more remotely to the original UNIX shell, the Bourne shell,
+its default behaviour does not entirely correspond to those shells.
+General shell syntax is introduced in ifzman(the section `Shell Grammar' in
+zmanref(zshmisc))\
+ifnzman(noderef(Shell Grammar)).
+
+One commonly encountered difference is that variables (other than arrays, a
+particular type of variable) substituted onto the command line are not
+split into words.  See the description of the shell option
+tt(SH_WORD_SPLIT) in ifzman(the section `Parameter Expansion' in
+zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion)).
+
+sect(Programming)
+
+The most convenient way of adding enhancements to the shell is typically
+by writing a shell function and arranging for it to be autoloaded.
+Functions are described in ifzman(the section `Functions' in
+zmanref(zshmisc))\
+ifnzman(noderef(Functions)).
+
+A few general functions, other than those for the line editor described
+above, are provided with the shell and are described in
+ifzman(zmanref(zshcontrib))\
+ifnzman(noderef(User Contributions)).  Features include:
+
+startitem()
+item(tt(promptinit))(
+a prompt theme system for changing prompts easily, see ifzman(the section
+`Prompt Themes'
+)\
+ifnzman(noderef(Prompt Themes))
+)
+item(tt(zsh-mime-setup))(
+a MIME-handling system which dispatches commands according to the suffix of
+a file as done by graphical file managers
+)
+item(tt(zcalc))(
+a calculator
+)
+item(tt(zargs))(
+a version of tt(xargs) that makes the tt(find) command redundant
+)
+item(tt(zmv))(
+a command for renaming files with patterns.
+)
+enditem()

Doc/zsh.yo

@@ -44,6 +44,7 @@ texiendtitlepage()
 )\
 ifnzman(includefile(Zsh/manual.yo))

 includefile(Zsh/intro.yo)

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

 includefile(Zsh/invoke.yo)

 includefile(Zsh/files.yo)

 ifnzman(includefile(Zsh/grammar.yo))

@@ -69,6 +70,7 @@ ifnzman(includefile(Zsh/contrib.yo))

 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
 CMT()
+source(zshroadmap)
 source(zshmisc)
 source(zshexpn)
 source(zshparam)

Doc/zshroadmap.yo

@@ -0,0 +1,3 @@
+manpage(ZSHROADMAP)(1)(date())(zsh version())
+manpagename(zshroadmap)(informal introduction to the zsh manual)
+includefile(Zsh/roadmap.yo)

Functions/Zle/insert-composed-char

@@ -147,8 +147,22 @@ if (( ${+zsh_accented_chars} == 0 )); then
   unfunction define-composed-chars
 fi
 
-read -k basechar || return 1
-read -k accent || return 1
+if (( $# )); then
+  basechar=${1[1]}
+  if [[ $1 = ? ]]; then
+    shift
+  else
+    1=${1[2,-1]}
+  fi
+else
+  read -k basechar || return 1
+fi
+
+if (( $# )); then
+  accent=${1[1]}
+else
+  read -k accent || return 1
+fi
 
 local -A charmap
 charmap=(${=zsh_accented_chars[$accent]})