Re: out of date documentation

[Dirk Herrmann]

On 13 Apr 2001, Neil Jerram wrote:

> Hi Dirk,
> 
> I've now included api.txt in the Data Representation chapter as a node
> called `Unpacking the SCM type'.  It still needs a little more
> integration, as material on, say, SCM_IMP, is now in more than one
> place in this chapter.  But all the material that was in api.txt is
> now in this node (and its subnodes).  Could you take a brief look just
> to review?  If you are happy with it, I'd like to remove api.txt from
> CVS, to avoid the risk that someone updates api.txt rather than the
> reference manual version.

Hi Neil,

I am currently looking into it.  However, I realized that due to recent
changes to libguile the comment about SCM_ASSERT is no longer appropriate.  
Thus, I first send you a diff to update that part.  This will, however,
only be correct for guile versions after 1.4.

Best regards,
Dirk Herrmann


Index: data-rep.texi
===================================================================
RCS file: /cvsroot/guile/guile/guile-core/doc/data-rep.texi,v
retrieving revision 1.20
diff -u -r1.20 data-rep.texi
--- data-rep.texi       2001/04/13 11:12:01     1.20
+++ data-rep.texi       2001/04/16 08:50:10
@@ -1021,15 +1021,10 @@
 causing a segmentation fault.  Guile provides some macros to make this
 easier.
 
address@hidden Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, int 
@var{position}, char address@hidden)
-If @var{test} is zero, signal an error, attributed to the subroutine
-named @var{subr}, operating on the value @var{obj}.  The @var{position}
-value determines exactly what sort of error to signal.
-
-If @var{position} is a string, @code{SCM_ASSERT} raises a
-``miscellaneous'' error whose message is that string.
-
-Otherwise, @var{position} should be one of the values defined below.
address@hidden Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned 
int @var{position}, const char address@hidden)
+If @var{test} is zero, signal a ``wrong type argument'' error,
+attributed to the subroutine named @var{subr}, operating on the value
address@hidden, which is the @var{position}'th argument of @var{subr}.
 @end deftypefn
 
 @deftypefn Macro int SCM_ARG1
@@ -1037,35 +1032,21 @@
 @deftypefnx Macro int SCM_ARG3
 @deftypefnx Macro int SCM_ARG4
 @deftypefnx Macro int SCM_ARG5
-Signal a ``wrong type argument'' error.  When used as the @var{position}
-argument of @code{SCM_ASSERT}, @address@hidden claims that
address@hidden has the wrong type for the @var{n}'th argument of @var{subr}.
-
-The only way to complain about the type of an argument after the fifth
-is to use @code{SCM_ARGn}, defined below, which doesn't specify which
-argument is wrong.  You could pass your own error message to
address@hidden as the @var{position}, but then the error signalled is
-a ``miscellaneous'' error, not a ``wrong type argument'' error.  This
-seems kludgy to me.
address@hidden Any function with more than two arguments is wrong --- Perlis
address@hidden Despite Perlis, I agree.  Why not have two Macros, one with
address@hidden a string error message, and the other with an integer position
address@hidden that only claims a type error in an argument?
address@hidden --- Keith Wright
address@hidden Macro int SCM_ARG6
address@hidden Macro int SCM_ARG7
+One of the above values can be used for @var{position} to indicate the
+number of the argument of @var{subr} which is being checked.
+Alternatively, a positive integer number can be used, which allows to
+check arguments after the seventh.  However, for parameter numbers up to
+seven it is preferable to use @code{SCM_ARGN} instead of the
+corresponding raw number, since it will make the code easier to
+understand.
 @end deftypefn
 
 @deftypefn Macro int SCM_ARGn
-As above, but does not specify which argument's type is incorrect.
address@hidden deftypefn
-
address@hidden Macro int SCM_WNA
-Signal an error complaining that the function received the wrong number
-of arguments.
-
-Interestingly, the message is attributed to the function named by
address@hidden, not @var{subr}, so @var{obj} must be a Scheme string object
-naming the function.  Usually, Guile catches these errors before ever
-invoking the subr, so we don't run into these problems.
+Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
+leave it unspecified which argument's type is incorrect.  Again,
address@hidden should be preferred over a raw zero constant.
 @end deftypefn