option processing docs

Based on the lengthy thread in bug-m4, I'm installing this clarification:

branch:
2006-09-21  Eric Blake  <[email protected]>

	* doc/m4.texinfo (Invoking m4): Add clarification on option
	processing behavior.
	* THANKS: Update.
	Reported by Mikhail Teterin.

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.78
diff -u -r1.1.1.1.2.78 m4.texinfo
--- doc/m4.texinfo	21 Sep 2006 04:13:21 -0000	1.1.1.1.2.78
+++ doc/m4.texinfo	21 Sep 2006 14:55:17 -0000
@@ -378,12 +378,32 @@
 
 @cindex command line, options
 @cindex options, command line
+@cindex @env{POSIXLY_CORRECT}
 All options begin with @samp{-}, or if long option names are used, with
-a @samp{--}.  A long option name need not be written completely, any
-unambiguous prefix is sufficient.  Options may be intermixed with files,
-use @option{--} as a marker to denote the end of options.  @code{m4}
-understands the following options, grouped by functionality.
+@samp{--}.  A long option name need not be written completely, any
+unambiguous prefix is sufficient.  Unless @env{POSIXLY_CORRECT} is set
+in the environment, options may be intermixed with files.  The argument
+@option{--} is a marker to denote the end of options.
+
+With short options, options that do not take arguments may be combined
+into a single command line argument with subsequent options, options
+with mandatory arguments may be provided either as a single command line
+argument or as two arguments, and options with optional arguments must
+be provided as a single argument.  In other words, without
+@env{POSIXLY_CORRECT}, @kbd{m4 -QPDfoo -d a -d+f} is equivalent to
+@kbd{m4 -Q -P -D foo -d -d+f -- a}, although the latter form is
+considered canonical.  (With @env{POSIXLY_CORRECT}, it is equivalent to
+@kbd{m4 -Q -P -D foo -d -- a ./-d+f}).
+
+With long options, options with mandatory arguments may be provided with
+an equal sign (@samp{=}) in a single argument, or as two arguments, and
+options with optional arguments must be provided as a single argument.
+In other words, @kbd{m4 --def foo --debug a} is equivalent to
+@kbd{m4 --define=foo --debug= -- a}, although the latter form is
+considered canonical (not to mention more robust, in case a future
+version of @code{m4} introduces an option named @option{--default}).
 
+@code{m4} understands the following options, grouped by functionality.
 Several options control the overall operation of @code{m4}:
 
 @table @code


head:
2006-09-21  Eric Blake  <[email protected]>

	* doc/m4.texinfo (Invoking m4): Add clarification on option
	processing behavior.
	* tests/options.at (option grouping): Test this.
	* THANKS: Update.
	Reported by Mikhail Teterin.

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.50
diff -u -r1.50 m4.texinfo
--- doc/m4.texinfo	21 Sep 2006 04:12:55 -0000	1.50
+++ doc/m4.texinfo	21 Sep 2006 16:28:36 -0000
@@ -397,13 +397,32 @@
 
 @cindex command line, options
 @cindex options, command line
+@cindex @env{POSIXLY_CORRECT}
 All options begin with @samp{-}, or if long option names are used, with
-a @samp{--}.  A long option name need not be written completely, any
+@samp{--}.  A long option name need not be written completely, any
 unambiguous prefix is sufficient.  Unless @env{POSIXLY_CORRECT} is set
-in the environment, options may be intermixed with files, with
-@option{--} as a marker to denote the end of options.  @code{m4}
-understands the following options, grouped by functionality.
+in the environment, options may be intermixed with files.  The argument
+@option{--} is a marker to denote the end of options.
+
+With short options, options that do not take arguments may be combined
+into a single command line argument with subsequent options, options
+with mandatory arguments may be provided either as a single command line
+argument or as two arguments, and options with optional arguments must
+be provided as a single argument.  In other words, without
+@env{POSIXLY_CORRECT}, @kbd{m4 -QPDfoo -d a -d+f} is equivalent to
+@kbd{m4 -Q -P -D foo -d -d+f -- a}, although the latter form is
+considered canonical.  (With @env{POSIXLY_CORRECT}, it is equivalent to
+@kbd{m4 -Q -P -D foo -d -- a ./-d+f}).
+
+With long options, options with mandatory arguments may be provided with
+an equal sign (@samp{=}) in a single argument, or as two arguments, and
+options with optional arguments must be provided as a single argument.
+In other words, @kbd{m4 --def foo --debug a} is equivalent to
+@kbd{m4 --define=foo --debug= -- a}, although the latter form is
+considered canonical (not to mention more robust, in case a future
+version of @code{m4} introduces an option named @option{--default}).
 
+@code{m4} understands the following options, grouped by functionality.
 Several options control the overall operation of @code{m4}:
 
 @table @code
Index: tests/options.at
===================================================================
RCS file: /sources/m4/m4/tests/options.at,v
retrieving revision 1.11
diff -u -r1.11 options.at
--- tests/options.at	21 Sep 2006 04:12:55 -0000	1.11
+++ tests/options.at	21 Sep 2006 16:28:36 -0000
@@ -19,6 +19,67 @@
 AT_BANNER([Options.])
 
 
+## ---------------- ##
+## Option grouping. ##
+## ---------------- ##
+
+AT_SETUP([option grouping])
+
+dnl this test group depends on correct settings of POSIXLY_CORRECT
+if test -n "${POSIXLY_CORRECT+set}" ; then
+  (unset POSIXLY_CORRECT) >/dev/null 2>&1 || {
+    echo "Problem unsetting POSIXLY_CORRECT"
+    AT_CHECK([exit 77])
+  }
+  unset POSIXLY_CORRECT
+fi
+
+dnl This comes from the "Invoking m4" node; it was easier to write the
+dnl test separately than to let generate.awk fiddle with it.
+AT_DATA([a], [[foo 1
+m@&t@4_dnl()
+]])
+
+AT_DATA([-d+f], [[hi
+]])
+
+dnl First, run with GNU semantics
+AT_CHECK_M4([-QPDfoo -d a -d+f], [0], [[ 1
+]])
+
+AT_CHECK_M4([-Q -P -D foo -d -d+f -- a], [0], [[ 1
+]])
+
+AT_CHECK_M4([--def foo --debug a], [0], [[ 1
+m@&t@4_dnl()
+]])
+
+AT_CHECK_M4([--define=foo --debug= -- a], [0], [[ 1
+m@&t@4_dnl()
+]])
+
+dnl Next, run with POSIX semantics
+POSIXLY_CORRECT=1
+export POSIXLY_CORRECT
+
+AT_CHECK_M4([-QPDfoo -d a -d+f], [0], [[ 1
+hi
+]])
+
+AT_CHECK_M4([-Q -P -D foo -d -- a ./-d+f], [0], [[ 1
+hi
+]])
+
+AT_CHECK_M4([--def foo --debug a], [0], [[ 1
+m@&t@4_dnl()
+]])
+
+AT_CHECK_M4([--define=foo --debug= -- a], [0], [[ 1
+m@&t@4_dnl()
+]])
+
+AT_CLEANUP
+
 ## ------------------ ##
 ## Discard comments.  ##
 ## ------------------ ##