Merge of 21899: add "roadmap" to manual.

2 files changed, 131 insertions, 28 deletions

diff --git a/Doc/Zsh/invoke.yo b/Doc/Zsh/invoke.yo
index 7add05b38..01e9b00e6 100644
--- a/Doc/Zsh/invoke.yo
+++ b/Doc/Zsh/invoke.yo
@@ -1,34 +1,93 @@
-texinode(Invocation)(Files)(Introduction)(Top)
+texinode(Invocation)(Files)(Roadmap)(Top)
 chapter(Invocation)
 cindex(invocation)
 sect(Invocation Options)
-cindex(flags, shell)
+cindex(shell options)
+cindex(options, shell)
 cindex(shell flags)
-If the tt(-s) flag is not present and an argument is given,
-the first argument is taken to be the pathname of a script to
-execute.  The remaining arguments are assigned to the positional
-parameters.  The following flags are interpreted by the shell
-when invoked:
+cindex(flags, shell)
+The following flags are interpreted by the shell when invoked to determine
+where the shell will read commands from:
 
 startitem()
-item(tt(-c) var(string))(
-Read commands from var(string).
+item(tt(-c))(
+Take the first argument as a command to execute, rather than reading commands
+from a script or standard input.  If any further arguments are given, the
+first one is assigned to tt($0), rather than being used as a positional
+parameter.
 )
 item(tt(-i))(
 Force shell to be interactive.
 )
 item(tt(-s))(
-Read command from the standard input.
+Force shell to read commands from the standard input.
+If the tt(-s) flag is not present and an argument is given,
+the first argument is taken to be the pathname of a script to
+execute.
 )
 enditem()
 
+After the first one or two arguments have been appropriated as described above,
+the remaining arguments are assigned to the positional parameters.
+
 For further options, which are common to invocation and the tt(set)
 builtin, see
 ifzman(zmanref(zshoptions))\
 ifnzman(noderef(Options))\
-.  Flags may be specified by name using the tt(-o) option.  For example,
+.
+
+Options may be specified by name using the tt(-o) option.  tt(-o) acts like
+a single-letter option, but takes a following string as the option name.
+For example,
 
 example(zsh -x -o shwordsplit scr)
 
 runs the script tt(scr), setting the tt(XTRACE) option by the corresponding
 letter `tt(-x)' and the tt(SH_WORD_SPLIT) option by name.
+Options may be turned em(off) by name by using tt(PLUS()o) instead of tt(-o).
+tt(-o) can be stacked up with preceding single-letter options, so for example
+`tt(-xo shwordsplit)' or `tt(-xoshwordsplit)' is equivalent to
+`tt(-x -o shwordsplit)'.
+
+cindex(long option)
+Options may also be specified by name in GNU long option style,
+`tt(-)tt(-)var(option-name)'.  When this is done, `tt(-)' characters in the
+option name are permitted: they are translated into `tt(_)', and thus ignored.
+So, for example, `tt(zsh -)tt(-sh-word-split)' invokes zsh with the
+tt(SH_WORD_SPLIT) option turned on.  Like other option syntaxes, options can
+be turned off by replacing the initial `tt(-)' with a `tt(PLUS())'; thus
+`tt(+-sh-word-split)' is equivalent to `tt(-)tt(-no-sh-word-split)'.
+Unlike other option syntaxes, GNU-style long options cannot be stacked with
+any other options, so for example `tt(-x-shwordsplit)' is an error,
+rather than being treated like `tt(-x -)tt(-shwordsplit)'.
+
+cindex(--version)
+cindex(--help)
+The special GNU-style option `tt(-)tt(-version)' is handled; it sends to
+standard output the shell's version information, then exits successfully.
+`tt(-)tt(-help)' is also handled; it sends to standard output a list of
+options that can be used when invoking the shell, then exits successfully.
+
+Option processing may be finished, allowing following arguments that start with
+`tt(-)' or `tt(PLUS())' to be treated as normal arguments, in two ways.
+Firstly, a lone `tt(-)' (or `tt(PLUS())') as an argument by itself ends
+option processing.  Secondly, a special option `tt(-)tt(-)' (or
+`tt(PLUS()-)'), which may be specified on its own (which is the standard
+POSIX usage) or may be stacked with preceding options (so `tt(-x-)' is
+equivalent to `tt(-x -)tt(-)').  Options are not permitted to be stacked
+after `tt(-)tt(-)' (so `tt(-x-f)' is an error), but note the GNU-style
+option form discussed above, where `tt(-)tt(-shwordsplit)' is permitted
+and does not end option processing.
+
+Except when the bf(sh)/bf(ksh) emulation single-letter options are in effect,
+the option `tt(-b)' (or `tt(PLUS()b)') ends option processing.
+`tt(-b)' is like `tt(-)tt(-)', except that further single-letter options
+can be stacked after the `tt(-b)' and will take effect as normal.
+
+startmenu()
+menu(Compatibility)
+menu(Restricted Shell)
+endmenu()
+
+includefile(Zsh/compat.yo)

+includefile(Zsh/restricted.yo)

diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo
index 53176e079..9820f1f23 100644
--- a/Doc/Zsh/manual.yo
+++ b/Doc/Zsh/manual.yo
@@ -1,16 +1,20 @@
-texiifinfo(\
+texiifnottex(\
 texinode(Top)(The Z Shell Manual)((dir))((dir))
 texitop(The Z Shell Manual)
+)\
+texiifinfo(\
 This Info file documents Zsh, a freely available UNIX command interpreter
 (shell), which of the standard shells most closely resembles the Korn shell
 (ksh), although it is not completely compatible.
 
+cindex(version)
 Version version(), last updated date().
 )\
 
 startmenu()
 menu(The Z Shell Manual)
 menu(Introduction)
+menu(Roadmap)
 menu(Invocation)
 menu(Files)
 menu(Shell Grammar)
@@ -20,19 +24,19 @@ menu(Functions)
 menu(Jobs & Signals)
 menu(Arithmetic Evaluation)
 menu(Conditional Expressions)
-menu(Compatibility)
 menu(Prompt Expansion)
-menu(Restricted Shell)
 menu(Expansion)
 menu(Parameters)
 menu(Options)
 menu(Shell Builtin Commands)
 menu(Zsh Line Editor)
 menu(Completion Widgets)
-menu(Programmable Completion Using compctl)
-menu(Zsh Modules)
 menu(Completion System)
+menu(Completion Using compctl)
+menu(Zsh Modules)
+menu(TCP Function System)
 menu(Zftp Function System)
+menu(User Contributions)
 
  --- Indices ---
 
@@ -41,7 +45,7 @@ menu(Variables Index)
 menu(Options Index)
 menu(Functions Index)
 menu(Editor Functions Index)
-menu(Keystroke Index)
+menu(Style and Tag Index)
 
  --- The Detailed Node Listing ---
 
@@ -52,8 +56,14 @@ menu(Availability)
 menu(Mailing Lists)
 menu(The Zsh FAQ)
 menu(The Zsh Web Page)
+menu(The Zsh Userguide)
 menu(See Also)
 
+Invocation
+
+menu(Compatibility)
+menu(Restricted Shell)
+
 Shell Grammar
 
 menu(Simple Commands & Pipelines)
@@ -86,7 +96,9 @@ menu(Parameters Used By The Shell)
 
 Options
 
+menu(Specifying Options)
 menu(Description of Options)
+menu(Option Aliases)
 menu(Single Letter Options)
 
 Zsh Line Editor
@@ -98,7 +110,24 @@ menu(Arguments)
 menu(Completion)
 menu(Miscellaneous)
 
-Programmable Completion Using compctl
+Completion Widgets
+
+menu(Special Parameters)
+menu(Builtin Commands)
+menu(Condition Codes)
+menu(Matching Control)
+menu(Completion Widget Example)
+
+Completion System
+
+menu(Initialization)
+menu(Completion System Configuration)
+menu(Control Functions)
+menu(Bindable Commands)
+menu(Completion Functions)
+menu(Completion Directories)
+
+Completion Using compctl
 
 menu(Command Flags)
 menu(Option Flags)
@@ -106,16 +135,30 @@ menu(Alternative Completion)
 menu(Extended Completion)
 menu(Example)
 
-Completion Widgets
-
-menu(Special Parameters)
-menu(Builtin Commands)
-menu(Condition Codes)
-menu(Examples)
-
 Zsh Modules
 
 includefile(Zsh/manmodmenu.yo)

+
+TCP Function System
+
+menu(TCP Functions)
+menu(TCP Parameters)
+menu(TCP Examples)
+menu(TCP Bugs)
+
+Zftp Function System
+
+menu(Installation)
+menu(Zftp Functions)
+menu(Miscellaneous Features)
+
+User Contributions
+
+menu(Utilities)
+menu(Prompt Themes)
+menu(ZLE Functions)
+menu(Other Functions)
+
 endmenu()
 texinode(The Z Shell Manual)(Introduction)(Top)(Top)
 chapter(The Z Shell Manual)
@@ -138,11 +181,12 @@ produce a nicely formatted printed manual.
 item(The HTML manual)(
 An HTML version of this manual is available at the Zsh web site via:
 
-tt(http://sunsite.auc.dk/zsh/Doc/index.html).
+tt(http://zsh.sunsite.dk/Doc/).
 
 (The HTML version is produced with bf(texi2html), which may be obtained
-from tt(http://wwwcn.cern.ch/dci/texi2html/). The command is
-`tt(texi2html -split_chapter -expandinfo zsh.texi)'.)
+from tt(http://www.mathematik.uni-kl.de/~obachman/Texi2html/). The command is
+`tt(texi2html -split chapter -expand info zsh.texi)'.  If necessary,
+upgrade to version 1.64 of texi2html.)
 )
 enditem()