deprecate dynamic-args-call, and update docs some more

* libguile/deprecated.h (scm_dynamic_args_call): Deprecate.
* libguile/deprecated.c:
* libguile/dynl.h:
* libguile/dynl.c:

* doc/ref/api-foreign.texi: More doc updates.

5 files changed, 67 insertions, 69 deletions

diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
index e1b785468..9e4bd795e 100644
--- a/doc/ref/api-foreign.texi
+++ b/doc/ref/api-foreign.texi
@@ -126,6 +126,10 @@ the above functions throw errors, but they are still available.
 @node Foreign Functions
 @subsection Foreign Functions
 
+The most natural thing to do with a dynamic library is to grovel around
+in it for a function pointer: a @dfn{foreign function}.
+@code{dynamic-func} exists for that purpose.
+
 @deffn {Scheme Procedure} dynamic-func name dobj
 @deffnx {C Function} scm_dynamic_func (name, dobj)
 Return a ``handle'' for the func @var{name} in the shared object referred to
@@ -137,6 +141,9 @@ names in a program, you should @strong{not} include this underscore in
 @var{name} since it will be added automatically when necessary.
 @end deffn
 
+Guile has static support for calling functions with no arguments,
+@code{dynamic-call}.
+
 @deffn {Scheme Procedure} dynamic-call func dobj
 @deffnx {C Function} scm_dynamic_call (func, dobj)
 Call the C function indicated by @var{func} and @var{dobj}.
@@ -153,43 +160,27 @@ Interrupts are deferred while the C function is executing (with
 @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
 @end deffn
 
-@deffn {Scheme Procedure} dynamic-args-call func dobj args
-@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value.  The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
-@smallexample
-int c_func (int argc, char **argv);
-@end smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}.  The array is passed
-in @var{argv} and its size in @var{argc}.  The return value is
-converted to a Scheme number and returned from the call to
-@code{dynamic-args-call}.
-@end deffn
-
-The functions to call a function from a dynamically linked library,
-@code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
-They are mostly intended to be used for calling specially written
-initialization functions that will then add new primitives to Guile.
-For example, we do not expect that you will dynamically link
-@file{libX11} with @code{dynamic-link} and then construct a beautiful
-graphical user interface just by using @code{dynamic-call} and
-@code{dynamic-args-call}.  Instead, the usual way would be to write a
-special Guile<->X11 glue library that has intimate knowledge about both
-Guile and X11 and does whatever is necessary to make them inter-operate
-smoothly.  This glue library could then be dynamically linked into a
+@code{dynamic-call} is not very powerful. It is mostly intended to be
+used for calling specially written initialization functions that will
+then add new primitives to Guile. For example, we do not expect that you
+will dynamically link @file{libX11} with @code{dynamic-link} and then
+construct a beautiful graphical user interface just by using
+@code{dynamic-call}. Instead, the usual way would be to write a special
+Guile<->X11 glue library that has intimate knowledge about both Guile
+and X11 and does whatever is necessary to make them inter-operate
+smoothly. This glue library could then be dynamically linked into a
 vanilla Guile interpreter and activated by calling its initialization
-function.  That function would add all the new types and primitives to
+function. That function would add all the new types and primitives to
 the Guile interpreter that it has to offer.
 
-From this setup the next logical step is to integrate these glue
-libraries into the module system of Guile so that you can load new
-primitives into a running system just as you can load new Scheme code.
+(There is actually another, better option: simply to create a
+@file{libX11} wrapper in Scheme via the dynamic FFI. @xref{Dynamic FFI},
+for more information.)
 
-[foreshadowing regarding dynamic ffi]
+Given some set of C extensions to Guile, the next logical step is to
+integrate these glue libraries into the module system of Guile so that
+you can load new primitives into a running system just as you can load
+new Scheme code.
 
 @deffn {Scheme Procedure} load-extension lib init
 @deffnx {C Function} scm_load_extension (lib, init)
diff --git a/libguile/deprecated.c b/libguile/deprecated.c
index 76ff355cb..4ff1bc2ac 100644
--- a/libguile/deprecated.c
+++ b/libguile/deprecated.c
@@ -1876,6 +1876,46 @@ scm_raequal (SCM ra0, SCM ra1)
 
 
 
+
+
+SCM_DEFINE (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0, 
+            (SCM func, SCM dobj, SCM args),
+	    "Call the C function indicated by @var{func} and @var{dobj},\n"
+	    "just like @code{dynamic-call}, but pass it some arguments and\n"
+	    "return its return value.  The C function is expected to take\n"
+	    "two arguments and return an @code{int}, just like @code{main}:\n"
+	    "@smallexample\n"
+	    "int c_func (int argc, char **argv);\n"
+	    "@end smallexample\n\n"
+	    "The parameter @var{args} must be a list of strings and is\n"
+	    "converted into an array of @code{char *}.  The array is passed\n"
+	    "in @var{argv} and its size in @var{argc}.  The return value is\n"
+	    "converted to a Scheme number and returned from the call to\n"
+	    "@code{dynamic-args-call}.")
+#define FUNC_NAME s_scm_dynamic_args_call
+{
+  int (*fptr) (int argc, char **argv);
+  int result, argc;
+  char **argv;
+
+  if (scm_is_string (func))
+    func = scm_dynamic_func (func, dobj);
+  SCM_VALIDATE_FOREIGN_TYPED (SCM_ARG1, func, VOID);
+
+  fptr = SCM_FOREIGN_POINTER (func, void);
+
+  argv = scm_i_allocate_string_pointers (args);
+  for (argc = 0; argv[argc]; argc++)
+    ;
+  result = (*fptr) (argc, argv);
+
+  return scm_from_int (result);
+}
+#undef FUNC_NAME
+
+
+
+
 void
 scm_i_init_deprecated ()
 {
diff --git a/libguile/deprecated.h b/libguile/deprecated.h
index b9ea5792b..021e31964 100644
--- a/libguile/deprecated.h
+++ b/libguile/deprecated.h
@@ -624,6 +624,9 @@ SCM_DEPRECATED SCM scm_internal_lazy_catch (SCM tag,
 /* Deprecated 2010-03-31, use array-equal? instead */
 SCM_DEPRECATED SCM scm_raequal (SCM ra0, SCM ra1);
 
+/* Deprecated 2010-04-01, use the dynamic FFI instead */
+SCM_DEPRECATED SCM scm_dynamic_args_call (SCM symb, SCM dobj, SCM args);
+
 
 
 void scm_i_init_deprecated (void);
diff --git a/libguile/dynl.c b/libguile/dynl.c
index a204e93d7..449acc0db 100644
--- a/libguile/dynl.c
+++ b/libguile/dynl.c
@@ -333,41 +333,6 @@ SCM_DEFINE (scm_dynamic_call, "dynamic-call", 2, 0, 0,
 }
 #undef FUNC_NAME
 
-SCM_DEFINE (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0, 
-            (SCM func, SCM dobj, SCM args),
-	    "Call the C function indicated by @var{func} and @var{dobj},\n"
-	    "just like @code{dynamic-call}, but pass it some arguments and\n"
-	    "return its return value.  The C function is expected to take\n"
-	    "two arguments and return an @code{int}, just like @code{main}:\n"
-	    "@smallexample\n"
-	    "int c_func (int argc, char **argv);\n"
-	    "@end smallexample\n\n"
-	    "The parameter @var{args} must be a list of strings and is\n"
-	    "converted into an array of @code{char *}.  The array is passed\n"
-	    "in @var{argv} and its size in @var{argc}.  The return value is\n"
-	    "converted to a Scheme number and returned from the call to\n"
-	    "@code{dynamic-args-call}.")
-#define FUNC_NAME s_scm_dynamic_args_call
-{
-  int (*fptr) (int argc, char **argv);
-  int result, argc;
-  char **argv;
-
-  if (scm_is_string (func))
-    func = scm_dynamic_func (func, dobj);
-  SCM_VALIDATE_FOREIGN_TYPED (SCM_ARG1, func, VOID);
-
-  fptr = SCM_FOREIGN_POINTER (func, void);
-
-  argv = scm_i_allocate_string_pointers (args);
-  for (argc = 0; argv[argc]; argc++)
-    ;
-  result = (*fptr) (argc, argv);
-
-  return scm_from_int (result);
-}
-#undef FUNC_NAME
-
 void
 scm_init_dynamic_linking ()
 {
diff --git a/libguile/dynl.h b/libguile/dynl.h
index 2b34c2e49..3239d639e 100644
--- a/libguile/dynl.h
+++ b/libguile/dynl.h
@@ -33,7 +33,6 @@ SCM_API SCM scm_dynamic_object_p (SCM obj);
 SCM_API SCM scm_dynamic_pointer (SCM name, SCM type, SCM dobj, SCM len);
 SCM_API SCM scm_dynamic_func (SCM symb, SCM dobj);
 SCM_API SCM scm_dynamic_call (SCM symb, SCM dobj);
-SCM_API SCM scm_dynamic_args_call (SCM symb, SCM dobj, SCM args);
 
 SCM_INTERNAL void scm_init_dynamic_linking (void);