Improve the docs.

* doc/mailfromd.texi, NEWS: Update.



git-svn-id: file:///svnroot/mailfromd/trunk@1720 7a8a7f39-df28-0410-adc6-e0d955640f24

1 files changed, 54 insertions, 7 deletions

diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 07a14f15..ea42e42d 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -8565,25 +8565,26 @@ the function.
 @cindex optional arguments, checking if supplied
   The actual parameter for argument @code{n} is supplied if the number
 of actual parameters (@code{$#}) is greater than its ordinal number
-in the declaration list (@code{@@@var{n}}).  This, to check if
-@var{pfx} is given:
+in the declaration list (@code{@@@var{n}}).  So, to check if an
+optional argument @var{arg} is supplied, the following condition can
+be used:
 
 @smallexample
-func foo(string msg, string email; number x, string pfx)
+func foo(string msg, string email; number x, string arg)
 do
-  if $# > @@pfx
+  if $# > @@arg
     @dots{}
   fi
 @end smallexample
 
   The default @command{mailfromd} installation provides a special
 macro for this purpose: @pxref{defined}.  Using it, the example above
-will be rewritten as:
+could be rewritten as:
 
 @smallexample
-func foo(string msg, string email; number x, string pfx)
+func foo(string msg, string email; number x, string arg)
 do
-  if defined(pfx)
+  if defined(arg)
     @dots{}
   fi
 @end smallexample
@@ -8594,6 +8595,52 @@ optional argument for which no actual parameter was supplied, results
 in an undefined value, so be sure to check whether a parameter is
 passed before dereferencing it.
 
+@cindex variable number of arguments
+  A function can also take variable number of arguments.  This is
+indicated by the use of ellipsis as the last abstract argument.  The
+statement below defines a funtion @code{foo} taking one mandatory, one
+optional and any number of additional arguments:
+
+@smallexample
+func foo (string a ; string b, ...)
+@end smallexample
+
+All actual arguments passed in a list of variable arguments are
+coerced to string data type.  To refer to these arguments in the
+function body, the following construct is used:
+
+@smallexample
+$(@var{expr})
+@end smallexample
+
+@noindent
+where @var{expr} is any valid @acronym{MFL} expression, evaluating to
+a number @var{n}.  This construct refers to the value of @var{n}th
+actual parameter from the variable argument list.  Parameters are
+numbered from @samp{1}, so the first variable parametr is @code{$(1)},
+and the last one is @code{$($# - @var{Nm} - @var{No})}, where @var{Nm}
+and @var{No} are numbers of mandatory and optional arguments to the
+function.
+
+For example, the function below prints all its arguments:
+
+@smallexample
+func pargs (string text, ...)
+do
+  echo "text=%text"
+  loop for number i 1,
+       while %i <= $# - 1,
+       set i %i + 1
+  do
+    echo "arg %i=" $(%i)
+  done
+done
+@end smallexample
+
+@noindent
+Note the loop limits.  The last variable argument has number @code{$#
+- 1}, because the function takes one mandatory argument.
+
 @cindex return statement, defined
   The @var{function-body} is any list of valid @command{mailfromd}
 statements.  In addition to the statements discussed below