From c2ff977ddb1b8892fd1e374f3360b70290cfeabb Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Fri, 21 Oct 2005 09:51:54 +0000 Subject: 21898: insert-composed-char can take command line argument 21899: add "roadmap" to manual --- Doc/.distfiles | 6 +-- Doc/Makefile.in | 5 +- Doc/Zsh/.distfiles | 3 +- Doc/Zsh/contrib.yo | 7 +++ Doc/Zsh/intro.yo | 3 +- Doc/Zsh/invoke.yo | 2 +- Doc/Zsh/manual.yo | 1 + Doc/Zsh/roadmap.yo | 150 +++++++++++++++++++++++++++++++++++++++++++++++++++++ Doc/zsh.yo | 2 + Doc/zshroadmap.yo | 3 ++ 10 files changed, 175 insertions(+), 7 deletions(-) create mode 100644 Doc/Zsh/roadmap.yo create mode 100644 Doc/zshroadmap.yo (limited to 'Doc') diff --git a/Doc/.distfiles b/Doc/.distfiles index 18ac5272b..6a0c44e3d 100644 --- a/Doc/.distfiles +++ b/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=' diff --git a/Doc/Makefile.in b/Doc/Makefile.in index 414ef4b28..998085c30 100644 --- a/Doc/Makefile.in +++ b/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 diff --git a/Doc/Zsh/.distfiles b/Doc/Zsh/.distfiles index 9b529885d..5961f6201 100644 --- a/Doc/Zsh/.distfiles +++ b/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 ' diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 9baee7a1b..71980180e 100644 --- a/Doc/Zsh/contrib.yo +++ b/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 diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo index be2bd6acf..065f53b0e 100644 --- a/Doc/Zsh/intro.yo +++ b/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) diff --git a/Doc/Zsh/invoke.yo b/Doc/Zsh/invoke.yo index 1701c4149..01e9b00e6 100644 --- a/Doc/Zsh/invoke.yo +++ b/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) diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo index 9fb81d99a..9820f1f23 100644 --- a/Doc/Zsh/manual.yo +++ b/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) diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo new file mode 100644 index 000000000..ad4c679e1 --- /dev/null +++ b/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() diff --git a/Doc/zsh.yo b/Doc/zsh.yo index 5258555a8..6b4076d8c 100644 --- a/Doc/zsh.yo +++ b/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) diff --git a/Doc/zshroadmap.yo b/Doc/zshroadmap.yo new file mode 100644 index 000000000..ed34f0a4c --- /dev/null +++ b/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) -- cgit 1.4.1