OSI: add documentation, improve changelog

CHANGELOG

@@ -29,6 +29,10 @@
 
 * Pending changes since 16.1.3
 ** Enhancements
+- ext:run-program has been rewritten (almost) from scratch
+- improved documentation of operating system interface (newdoc)
+- example of parsing arguments in standalone executable (newdoc)
+- example of using shared libraries from C world (newdoc)
 - reduced =format= directive tables size
 - simplified =atan2= implementation by using c99 equivalent ::
      Now we produce correct output for signed zeros, infinities and nans.
@@ -36,8 +40,14 @@
   =--with-libgc-incdir= and =--with-libgc-libdir= (these flags work the
   same as flags for =libffi= and =libgmp=)
 ** Issues fixed
+- interactive input stream in ext:run-program on Windows
+- removed race condition between waitpid and sigchld handler on UNIX
 - buildsystem parallel builds work (i.e make -j999)
 - ECL builds on consoles with unusual encodings on Windows (i.e cp936)
+** API changes
+- No more explicit option in =main.d= to trap SIGCHLD asynchronously.
+- Zombie processes are cleaned in external-process finalizer. If process is
+  referenced in the memory, it's programmer duty to call wait on it.
 * 16.1.3 changes since 16.1.2
 ** Announcement
 Dear Community,

src/doc/new-doc/extensions/osi.txi

@@ -2,12 +2,145 @@
 @section Operating System Interface
 
 @menu
+* Command line arguments::
 * External processes::
-@c * Command line arguments::
 @c * Signals and interrupts::
 * Operating System Interface Reference::
 @end menu
 
+@cindex Command line processing
+@node Command line arguments
+@subsection Command line arguments
+@deftypevar string ext:*help-message*
+Command line help message. Initial value is ECL help message. This
+variable contains the help message which is output when ECL is invoked
+with the @code{--help}.
+@end deftypevar
+
+@deftypevar list-of-pathname-designators ext:*lisp-init-file-list*
+ECL initialization files. Initial value is @code{'("~/.ecl"
+"~/.eclrc")}. This variable contains the names of initialization files
+that are loaded by ECL or embedding programs. The loading of
+initialization files happens automatically in ECL unless invoked with
+the option @code{--norc}. Whether initialization files are loaded or
+not is controlled by the command line options rules, as described in
+@code{ext:process-command-args}.
+@end deftypevar
+
+@deftypevar list-of-lists ext:+default-command-arg-rules+
+ECL command line options. This constant contains a list of rules for
+parsing the command line arguments. This list is made of all the
+options which ECL accepts by default. It can be passed as first
+argument to @code{ext:process-command-args}, and you can use it as a
+starting point to extend ECL.
+@end deftypevar
+
+@defun ext:command-args
+Original list of command line arguments. This function returns the
+list of command line arguments passed to either ECL or the program it
+was embedded in. The output is a list of strings and it corresponds to
+the argv vector in a C program. Typically, the first argument is the
+name of the program as it was invoked. You should not count on ths
+filename to be resolved.
+@end defun
+
+@defun ext:process-command-args &key args rules
+
+@defvr argument args
+A list of strings. Defaults to the output of @code{ext:command-args}.
+@end defvr
+@defvr argument rules
+A list of lists. Defaults to the value of
+@code{ext:+default-command-arg-rules+}.
+@end defvr
+
+This function processes the command line arguments passed to either
+ECL or the program that embeds it. It uses the list of rules rules,
+which has the following syntax:
+
+@code{(option-name nargs template [:stop | :noloadrc | :loadrc]*)}
+
+@defvr opt option-name
+A string with the option prefix as typed by the user. For instance
+@code{--help}, @code{-?}, @code{--compile}, etc.
+@end defvr
+
+@defvr opt nargs
+A non-negative integer denoting the number of arguments taken by this
+option.
+@end defvr
+
+@defvr opt template
+A lisp form, not evaluated, where numbers from 0 to nargs will be
+replaced by the corresponding option argument.
+@end defvr
+
+@defvr opt :STOP
+If present, parsing of arguments stops after this option is found and
+processed. The list of remaining arguments is passed to the
+rule. ECL's top-level uses this option with the @code{--} command line
+option to set @code{ext:*unprocessed-ecl-command-args*} to the list of
+remaining arguments.
+@end defvr
+
+@defvr opt :NOLOADRC
+@defvrx opt :LOADRC
+Determine whether the lisp initalization file
+@code{(ext:*lisp-init-file-list*)} will be loaded before processing
+all forms.
+@end defvr
+
+@code{ext:process-command-args} works as follows. First of all, it
+parses all the command line arguments, except for the first one, which
+is assumed to contain the program name. Each of these arguments is
+matched against the rules, sequentially, until one of the patterns
+succeeeds.
+
+A special name @code{*DEFAULT*}, matches any unknown command line
+option. If there is no @code{*DEFAULT*} rule and no match is found, an
+error is signalled. For each rule that succeeds, the function
+constructs a lisp statement using the template.
+
+After all arguments have been processed,
+@code{ext:process-command-args}, and there were no occurences of
+@code{:noloadrc}, one of the files listed in
+@code{ext:*lisp-init-file-list*} will be loaded. Finally, the list of
+lisp statements will be evaluated.
+@end defun
+
+@cindex Parsing arguments in standalone executable
+@exindex LS implementation
+
+The following piece of code implements the ls command using
+lisp. Instructions for building this program are found under
+@code{ecl/examples/cmdline/ls.lsp}.
+
+@lisp
+@verbatim
+(setq ext:*help-message* "
+ls [--help | -?] filename*
+     Lists the file that match the given patterns.
+")
+
+(defun print-directory (pathnames)
+  (format t "~{~A~%~}"
+          (mapcar #'(lambda (x) (enough-namestring x (si::getcwd)))
+                  (mapcan #'directory (or pathnames '("*.*" "*/"))))))
+
+(defconstant +ls-rules+
+  '(("--help" 0 (progn (princ ext:*help-message* *standard-output*) (ext:quit 0)))
+    ("-?" 0 (progn (princ ext:*help-message* *standard-output*) (ext:quit 0)))
+    ("*DEFAULT*" 1 (print-directory 1) :stop)))
+
+(let ((ext:*lisp-init-file-list* NIL)) ; No initialization files
+  (handler-case (ext:process-command-args :rules +ls-rules+)
+                (error (c)
+                       (princ ext:*help-message* *error-output*)
+                       (ext:quit 1))))
+(ext:quit 0)
+@end verbatim
+@end lisp
+
 @cindex External processes
 @node External processes
 @subsection External processes
@@ -41,7 +174,7 @@ Updates process status. @code{ext:external-process-status} calls
 it is a signal code. Otherwise NIL.
 @end defun
 
-@defunx ext:external-process-wait proces wait
+@defun ext:external-process-wait proces wait
 If the second argument is non-NIL, function blocks until external
 process is finished. Otherwise status is updated. Returns two values
 (see @code{ext:external-process-status}).
@@ -154,11 +287,6 @@ Controls escaping of the arguments passed to CreateProcess.
 
 @c environment routines
 
-@defun ext:command-args
-Returns the original command line arguments as list. First argument is
-the ECL program itself.
-@end defun
-
 @c Don't advertise argc and argv, we have command-args
 
 @c @defun ext:argc
@@ -176,7 +304,7 @@ Creates a pipe and wraps it in a two way stream.
 @end defun
 
 
-@defun ext:quit &optional code kill-all-threads
+@defun ext:quit &optional exit-code kill-all-threads
 This function abruptly stops the execution of the program in which ECL
 is embedded. Depending on the platform, several other functions will
 be invoked to free resources, close loaded modules, etc.