improved command line option handling

 * it turns out that option-like arguments could not be reliably passed to
   SciTECO scripts for two reasons:
   a) "--" arguments are not removed from argv by GOption if it detects
      and following option-like argument.
      "--" would thus be passed as a script argument which will disable
      option parsing in scripts that interpret "--".
   b) A script run via the Hash-Bang line "#!...sciteco -m" would
      require an explicit "--" to turn of GOption parsing.
      However it is __impossible__ to insert after the script file name
      on UNIX.
 * Therefore, SciTECO now removes leading "--" arguments left over by GOption.
 * If possible (Glib >= 2.44), option parsing is performed in strict POSIX
   mode which inhibits parsing after the first non-option argument.
   This reduces the number of cases where an explicit "--" is required.
 * --mung no longer takes an argument. Instead, the first non-option argument
   is expected to be the script file name.
   This looks weird at first but is more consistent with how other interpeters
   work. Once we revise argument passing to scripts, the script name can also
   be passed to the script which is more consistent with it being the first
   non-option argument.
   Also, with strict POSIX parsing, this fixed Hash-Bang lines since
   the script file name constructed by the kernel will automatically switch
   off option parsing, passing all option-like script arguments uninterpreted
   to the script.
 * Since we're supporting Glib < 2.44, the Hash-Bang lines are still broken
   for certain builds.
   Therefore, a wrapper script is installed to libexecdir (it never has to be
   executed by users and Hash-Bang lines need absolute paths anyway) which
   transparently inserts "--" into the SciTECO command line and should be used
   as the interpreter in portable SciTECO scripts.
   The wrapper script is generated and points to the exact SciTECO binary
   installed. This is important when doing parallel installs of Curses and Gtk
   binaries since each one will get its own working wrapper script.
   The wrapper-script workaround can be removed once we depend on Glib >= 2.44
   (some day...).
 * The default /usr/bin/env Hash-Bang lines are no longer used in the
   scripts since they are broken anyway (UNIX incl. Linux cannot pass
   multiple arguments to the interpreter!).
   Scripts that get installed will get a fixed-up Hash-Bang line referring
   to the installed SciTECO binary anyway.
 * Interface::main() has been renamed to Interface::init() and is optional
   now. The Interface::main() method was introduced because of the misconception
   that interfaces will find their options in the argv array and have to do
   their own parsing.
   This is wrong, since their option group already cares about parsing.
   Therefore, gtk_init() does not have to called explicitly, too.

1 files changed, 35 insertions, 7 deletions

diff --git a/doc/sciteco.1.in b/doc/sciteco.1.in
index e6c4d8a..ed3892f 100644
--- a/doc/sciteco.1.in
+++ b/doc/sciteco.1.in
@@ -17,10 +17,11 @@ Scintilla-based \fBT\fPext \fBE\fPditor and \fBCO\fPrrector
 .SY @PACKAGE@
 .OP "-h|--help"
 .OP "-e|--eval" macro
-.OP "-m|--mung" file
+.OP "-m|--mung"
 .OP "--no-profile"
 .RI [ "UI option .\|.\|." ]
 .OP "--"
+.RI [ script ]
 .RI [ "argument .\|.\|." ]
 .YS
 .
@@ -40,26 +41,46 @@ natively supports Microsoft Windows NT\*(Tm.
 .LP
 .SCITECO_TOPIC mung
 When executed, \*(ST mungs (executes) the TECO macro stored in the file
-specified by the
+specified in the \fIscript\fP argument if
 .B "--mung"
-option or the macro specified via
+is given or the macro specified via
 .B "--eval"
 respectively.
 Munged files and macros are executed in non-interactive (\fIbatch\fP)
 mode, allowing the user to write stand-alone TECO scripts.
 Only when munging files as opposed to other means of executing macros,
-the first line is ignored if it begins with \(lq#!\(rq.
+the first line is ignored if it begins with a \(lq#\(rq (hash sign).
 Therefore under UNIX-like operating systems, TECO macro files may be
 invoked as scripts by using a Hash-Bang line like
 .\" FIXME: We'd like to include #! as a topic, but ! character are currently
 .\" not allowed since they are not escaped correctly.
 .SCITECO_TOPIC scripting
 .RS
-.SCITECO_TT
 .EX
+.SCITECO_TT
 #!@bindir@/sciteco -m
+.SCITECO_TT_END
 .EE
+.RE
+.
+.LP
+Note that UNIX Hash-Bang lines will only pass a \fBsingle\fP argument to the
+interpreter before the script's file name, so all required \*(ST options must
+be mangled into a single argument with their single-letter names.
+Passing option-like arguments (beginning with a dash) to scripts may cause
+problems because \*(ST might try to interpret these options.
+Beginning with Glib 2.44, \*(ST thus stops parsing at the first non-option
+argument (which will always be the munged file name in a script invocation).
+For binaries linked against older versions of Glib, \*(ST works around this
+issue by providing a wrapper script that can be used in place of the main
+executable.
+A portable Hash-Bang line should thus look like:
+.RS
+.EX
+.SCITECO_TT
+#!@libexecdir@/sciteco-wrapper -m
 .SCITECO_TT_END
+.EE
 .RE
 .
 .LP
@@ -69,6 +90,8 @@ All command line arguments after the \*(ST options are passed as
 .I arguments
 to the munged macro by placing each argument on its own line in
 the buffer.
+The \fIscript\fP file name expected when \(lq--mung\(rq is given
+is currently \fBnot\fP considered a macro argument.
 In any case the current buffer position (called
 .IR dot )
 is left at the beginning of the buffer.
@@ -137,6 +160,8 @@ option is absent, \*(ST will mung
 On UNIX/Linux, the default profile is at
 .I ~/.teco_ini
 (see \fBENVIRONMENT\fP).
+It will consequently not expect a \fIscript\fP file name as
+the first non-option argument.
 The profile will usually set up various Scintilla and \*(ST options,
 configure syntax highlighting,
 define commonly used macros and open files specified as arguments to \*(ST.
@@ -160,9 +185,12 @@ Similar to munging but always exits afterwards.
 If the option is specified, the
 .B \-\-mung
 option has no effect.
-.IP "\fB-m\fR, \fB--mung\fR \fIfile"
+.IP "\fB-m\fR, \fB--mung\fR"
 .SCITECO_TOPIC "-m" "--mung"
-Mung \fIfile\fP.
+Mung \fIscript\fP.
+The script file name is expected as the first non-option
+argument, so it does not necessarily have to follow the
+\fB--mung\fP option.
 Default is
 .IR $SCITECOCONFIG/.teco_ini .
 .IP "\fB--no-profile\fP"