Doc for getopt-long's new stop-at-first-non-option option

[bpt/guile.git] / doc / ref / mod-getopt-long.texi

diff --git a/doc/ref/mod-getopt-long.texi b/doc/ref/mod-getopt-long.texi
index cba660b..1740215 100644 (file)
--- a/doc/ref/mod-getopt-long.texi
+++ b/doc/ref/mod-getopt-long.texi
@@ -13,8 +13,9 @@ The @code{(ice-9 getopt-long)} module exports two procedures:
 @itemize @bullet
 @item
 @code{getopt-long} takes a list of strings --- the command line
-arguments --- and an @dfn{option specification}.  It parses the command
-line arguments according to the option specification and returns a data
+arguments --- an @dfn{option specification}, and some optional keyword
+parameters.  It parses the command line arguments according to the
+option specification and keyword parameters, and returns a data
 structure that encapsulates the results of the parsing.
 
 @item
@@ -254,7 +255,7 @@ as ordinary argument strings.
 @node getopt-long Reference
 @subsection Reference Documentation for @code{getopt-long}
 
-@deffn {Scheme Procedure} getopt-long args grammar
+@deffn {Scheme Procedure} getopt-long args grammar [#:stop-at-first-non-option #t]
 Parse the command line given in @var{args} (which must be a list of
 strings) according to the option specification @var{grammar}.
 
@@ -263,7 +264,7 @@ The @var{grammar} argument is expected to be a list of this form:
 @code{((@var{option} (@var{property} @var{value}) @dots{}) @dots{})}
 
 where each @var{option} is a symbol denoting the long option, but
-without the two leading dashes (e.g. @code{version} if the option is
+without the two leading dashes (e.g.@: @code{version} if the option is
 called @code{--version}).
 
 For each option, there may be list of arbitrarily many property/value
@@ -284,12 +285,19 @@ If @var{bool} is @code{#t}, the option accepts a value; if it is
 @code{#f}, it does not; and if it is the symbol @code{optional}, the
 option may appear in @var{args} with or without a value.
 @item @code{(predicate @var{func})}
-If the option accepts a value (i.e. you specified @code{(value #t)} for
+If the option accepts a value (i.e.@: you specified @code{(value #t)} for
 this option), then @code{getopt-long} will apply @var{func} to the
 value, and throw an exception if it returns @code{#f}.  @var{func}
 should be a procedure which accepts a string and returns a boolean
 value; you may need to use quasiquotes to get it into @var{grammar}.
 @end table
+
+The @code{#:stop-at-first-non-option} keyword, if specified with any
+true value, tells @code{getopt-long} to stop when it gets to the first
+non-option in the command line.  That is, at the first word which is
+neither an option itself, nor the value of an option.  Everything in the
+command line from that word onwards will be returned as non-option
+arguments.
 @end deffn
 
 @code{getopt-long}'s @var{args} parameter is expected to be a list of
@@ -323,6 +331,18 @@ happen using the long option @code{--opt=@var{value}} syntax).
 An option predicate fails.
 @end itemize
 
+@code{#:stop-at-first-non-option} is useful for command line invocations
+like @code{guile-tools [--help | --version] [script [script-options]]}
+and @code{cvs [general-options] command [command-options]}, where there
+are options at two levels: some generic and understood by the outer
+command, and some that are specific to the particular script or command
+being invoked.  To use @code{getopt-long} in such cases, you would call
+it twice: firstly with @code{#:stop-at-first-non-option #t}, so as to
+parse any generic options and identify the wanted script or sub-command;
+secondly, and after trimming off the initial generic command words, with
+a script- or sub-command-specific option grammar, so as to process those
+specific options.
+
 
 @node option-ref Reference
 @subsection Reference Documentation for @code{option-ref}