* alist.c, chars.c, debug.c, dynl.c, dynwind.c, error.c, eval.c,

   evalext.c, filesys.c, gc.c, hash.c, hashtab.c, ioext.c,
   keywords.c, list.c, load.c, macros.c, net_db.c, numbers.c,
   objprop.c, ports.c, posix.c, print.c, procprop.c, procs.c,
   ramap.c, regex-posix.c, root.c, scmsigs.c, simpos.c, socket.c,
   stacks.c, stime.c, strings.c, strop.c, strports.c, struct.c,
   symbols.c, throw.c, unif.c, vectors.c, version.c, vports.c,
   weaks.c: Converted docstrings to ANSI C format.

1 files changed, 128 insertions, 141 deletions

diff --git a/libguile/unif.c b/libguile/unif.c
index 85325d408..9948bed28 100644
--- a/libguile/unif.c
+++ b/libguile/unif.c
@@ -239,7 +239,7 @@ scm_make_uve (long k, SCM prot)
 
 SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0, 
            (SCM v),
-"Returns the number of elements in @var{uve}.")
+	    "Returns the number of elements in @var{uve}.")
 #define FUNC_NAME s_scm_uniform_vector_length
 {
   SCM_ASRTGO (SCM_NIMP (v), badarg1);
@@ -269,10 +269,9 @@ SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
 
 SCM_DEFINE (scm_array_p, "array?", 1, 1, 0,
            (SCM v, SCM prot),
-"Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
-
-The @var{prototype} argument is used with uniform arrays and is described
-elsewhere.")
+	    "Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.\n\n"
+	    "The @var{prototype} argument is used with uniform arrays and is described\n"
+	    "elsewhere.")
 #define FUNC_NAME s_scm_array_p
 {
   int nprot;
@@ -337,8 +336,8 @@ loop:
 
 SCM_DEFINE (scm_array_rank, "array-rank", 1, 0, 0, 
            (SCM ra),
-"Returns the number of dimensions of @var{obj}.  If @var{obj} is not an
-array, @code{0} is returned.")
+	    "Returns the number of dimensions of @var{obj}.  If @var{obj} is not an\n"
+	    "array, @code{0} is returned.")
 #define FUNC_NAME s_scm_array_rank
 {
   if (SCM_IMP (ra))
@@ -372,11 +371,11 @@ array, @code{0} is returned.")
 
 SCM_DEFINE (scm_array_dimensions, "array-dimensions", 1, 0, 0, 
            (SCM ra),
-"@code{Array-dimensions} is similar to @code{array-shape} but replaces
-elements with a @code{0} minimum with one greater than the maximum. So:
-@example
-(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
-@end example")
+	    "@code{Array-dimensions} is similar to @code{array-shape} but replaces\n"
+	    "elements with a @code{0} minimum with one greater than the maximum. So:\n"
+	    "@example\n"
+	    "(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)\n"
+	    "@end example")
 #define FUNC_NAME s_scm_array_dimensions
 {
   SCM res = SCM_EOL;
@@ -510,11 +509,11 @@ scm_shap2ra (SCM args, const char *what)
 
 SCM_DEFINE (scm_dimensions_to_uniform_array, "dimensions->uniform-array", 2, 1, 0,
            (SCM dims, SCM prot, SCM fill),
-"@deffnx primitive make-uniform-vector length prototype [fill]
-Creates and returns a uniform array or vector of type corresponding to
-@var{prototype} with dimensions @var{dims} or length @var{length}.  If
-@var{fill} is supplied, it's used to fill the array, otherwise 
-@var{prototype} is used.")
+	    "@deffnx primitive make-uniform-vector length prototype [fill]\n"
+	    "Creates and returns a uniform array or vector of type corresponding to\n"
+	    "@var{prototype} with dimensions @var{dims} or length @var{length}.  If\n"
+	    "@var{fill} is supplied, it's used to fill the array, otherwise \n"
+	    "@var{prototype} is used.")
 #define FUNC_NAME s_scm_dimensions_to_uniform_array
 {
   scm_sizet k, vlen = 1;
@@ -621,21 +620,21 @@ scm_ra_set_contp (SCM ra)
 
 SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1,
            (SCM oldra, SCM mapfunc, SCM dims),
-"@code{make-shared-array} can be used to create shared subarrays of other
-arrays.  The @var{mapper} is a function that translates coordinates in
-the new array into coordinates in the old array.  A @var{mapper} must be
-linear, and its range must stay within the bounds of the old array, but
-it can be otherwise arbitrary.  A simple example:
-@example
-(define fred (make-array #f 8 8))
-(define freds-diagonal
-  (make-shared-array fred (lambda (i) (list i i)) 8))
-(array-set! freds-diagonal 'foo 3)
-(array-ref fred 3 3) @result{} foo
-(define freds-center
-  (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
-(array-ref freds-center 0 0) @result{} foo
-@end example")
+	    "@code{make-shared-array} can be used to create shared subarrays of other\n"
+	    "arrays.  The @var{mapper} is a function that translates coordinates in\n"
+	    "the new array into coordinates in the old array.  A @var{mapper} must be\n"
+	    "linear, and its range must stay within the bounds of the old array, but\n"
+	    "it can be otherwise arbitrary.  A simple example:\n"
+	    "@example\n"
+	    "(define fred (make-array #f 8 8))\n"
+	    "(define freds-diagonal\n"
+	    "  (make-shared-array fred (lambda (i) (list i i)) 8))\n"
+	    "(array-set! freds-diagonal 'foo 3)\n"
+	    "(array-ref fred 3 3) @result{} foo\n"
+	    "(define freds-center\n"
+	    "  (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))\n"
+	    "(array-ref freds-center 0 0) @result{} foo\n"
+	    "@end example")
 #define FUNC_NAME s_scm_make_shared_array
 {
   SCM ra;
@@ -747,25 +746,23 @@ it can be otherwise arbitrary.  A simple example:
 /* args are RA . DIMS */
 SCM_DEFINE (scm_transpose_array, "transpose-array", 0, 0, 1, 
            (SCM args),
-"Returns an array sharing contents with @var{array}, but with dimensions
-arranged in a different order.  There must be one @var{dim} argument for
-each dimension of @var{array}.  @var{dim0}, @var{dim1}, @dots{} should
-be integers between 0 and the rank of the array to be returned.  Each
-integer in that range must appear at least once in the argument list.
-
-The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions
-in the array to be returned, their positions in the argument list to
-dimensions of @var{array}.  Several @var{dim}s may have the same value,
-in which case the returned array will have smaller rank than
-@var{array}.
-
-examples:
-@example
-(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
-(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
-(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
-                #2((a 4) (b 5) (c 6))
-@end example")
+	    "Returns an array sharing contents with @var{array}, but with dimensions\n"
+	    "arranged in a different order.  There must be one @var{dim} argument for\n"
+	    "each dimension of @var{array}.  @var{dim0}, @var{dim1}, @dots{} should\n"
+	    "be integers between 0 and the rank of the array to be returned.  Each\n"
+	    "integer in that range must appear at least once in the argument list.\n\n"
+	    "The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions\n"
+	    "in the array to be returned, their positions in the argument list to\n"
+	    "dimensions of @var{array}.  Several @var{dim}s may have the same value,\n"
+	    "in which case the returned array will have smaller rank than\n"
+	    "@var{array}.\n\n"
+	    "examples:\n"
+	    "@example\n"
+	    "(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))\n"
+	    "(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)\n"
+	    "(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}\n"
+	    "                #2((a 4) (b 5) (c 6))\n"
+	    "@end example")
 #define FUNC_NAME s_scm_transpose_array
 {
   SCM ra, res, vargs, *ve = &vargs;
@@ -859,27 +856,24 @@ examples:
 /* args are RA . AXES */
 SCM_DEFINE (scm_enclose_array, "enclose-array", 0, 0, 1, 
            (SCM axes),
-"@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
-the rank of @var{array}.  @var{enclose-array} returns an array
-resembling an array of shared arrays.  The dimensions of each shared
-array are the same as the @var{dim}th dimensions of the original array,
-the dimensions of the outer array are the same as those of the original
-array that did not match a @var{dim}.
-
-An enclosed array is not a general Scheme array.  Its elements may not
-be set using @code{array-set!}.  Two references to the same element of
-an enclosed array will be @code{equal?} but will not in general be
-@code{eq?}.  The value returned by @var{array-prototype} when given an
-enclosed array is unspecified.
-
-examples:
-@example
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
-   #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
-
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
-   #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
-@end example")
+	    "@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than\n"
+	    "the rank of @var{array}.  @var{enclose-array} returns an array\n"
+	    "resembling an array of shared arrays.  The dimensions of each shared\n"
+	    "array are the same as the @var{dim}th dimensions of the original array,\n"
+	    "the dimensions of the outer array are the same as those of the original\n"
+	    "array that did not match a @var{dim}.\n\n"
+	    "An enclosed array is not a general Scheme array.  Its elements may not\n"
+	    "be set using @code{array-set!}.  Two references to the same element of\n"
+	    "an enclosed array will be @code{equal?} but will not in general be\n"
+	    "@code{eq?}.  The value returned by @var{array-prototype} when given an\n"
+	    "enclosed array is unspecified.\n\n"
+	    "examples:\n"
+	    "@example\n"
+	    "(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}\n"
+	    "   #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>\n\n"
+	    "(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}\n"
+	    "   #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>\n"
+	    "@end example")
 #define FUNC_NAME s_scm_enclose_array
 {
   SCM axv, ra, res, ra_inr;
@@ -962,7 +956,7 @@ examples:
 
 SCM_DEFINE (scm_array_in_bounds_p, "array-in-bounds?", 0, 0, 1, 
            (SCM args),
-"Returns @code{#t} if its arguments would be acceptable to array-ref.")
+	    "Returns @code{#t} if its arguments would be acceptable to array-ref.")
 #define FUNC_NAME s_scm_array_in_bounds_p
 {
   SCM v, ind = SCM_EOL;
@@ -1045,7 +1039,7 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref);
 
 SCM_DEFINE (scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0,
            (SCM v, SCM args),
-"Returns the element at the @code{(index1, index2)} element in @var{array}.")
+	    "Returns the element at the @code{(index1, index2)} element in @var{array}.")
 #define FUNC_NAME s_scm_uniform_vector_ref
 {
   long pos;
@@ -1239,8 +1233,8 @@ SCM_REGISTER_PROC(s_uniform_array_set1_x, "uniform-array-set1!", 3, 0, 0, scm_ar
    PROC is used (and it's called from C too).  */
 SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1, 
            (SCM v, SCM obj, SCM args),
-"Sets the element at the @code{(index1, index2)} element in @var{array} to
-@var{new-value}.  The value returned by array-set! is unspecified.")
+	    "Sets the element at the @code{(index1, index2)} element in @var{array} to\n"
+	    "@var{new-value}.  The value returned by array-set! is unspecified.")
 #define FUNC_NAME s_scm_array_set_x           
 {
   long pos = 0;
@@ -1345,17 +1339,16 @@ SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1,
 		     wouldn't have contiguous elements.  */
 SCM_DEFINE (scm_array_contents, "array-contents", 1, 1, 0,
            (SCM ra, SCM strict),
-"@deffnx primitive array-contents array strict
-If @var{array} may be @dfn{unrolled} into a one dimensional shared array
-without changing their order (last subscript changing fastest), then
-@code{array-contents} returns that shared array, otherwise it returns
-@code{#f}.  All arrays made by @var{make-array} and
-@var{make-uniform-array} may be unrolled, some arrays made by
-@var{make-shared-array} may not be.
-
-If the optional argument @var{strict} is provided, a shared array will
-be returned only if its elements are stored internally contiguous in
-memory.")
+	    "@deffnx primitive array-contents array strict\n"
+	    "If @var{array} may be @dfn{unrolled} into a one dimensional shared array\n"
+	    "without changing their order (last subscript changing fastest), then\n"
+	    "@code{array-contents} returns that shared array, otherwise it returns\n"
+	    "@code{#f}.  All arrays made by @var{make-array} and\n"
+	    "@var{make-uniform-array} may be unrolled, some arrays made by\n"
+	    "@var{make-shared-array} may not be.\n\n"
+	    "If the optional argument @var{strict} is provided, a shared array will\n"
+	    "be returned only if its elements are stored internally contiguous in\n"
+	    "memory.")
 #define FUNC_NAME s_scm_array_contents
 {
   SCM sra;
@@ -1451,21 +1444,19 @@ scm_ra2contig (SCM ra, int copy)
 
 SCM_DEFINE (scm_uniform_array_read_x, "uniform-array-read!", 1, 3, 0,
            (SCM ra, SCM port_or_fd, SCM start, SCM end),
-"@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]
-Attempts to read all elements of @var{ura}, in lexicographic order, as
-binary objects from @var{port-or-fdes}.
-If an end of file is encountered during
-uniform-array-read! the objects up to that point only are put into @var{ura}
-(starting at the beginning) and the remainder of the array is
-unchanged.
-
-The optional arguments @var{start} and @var{end} allow
-a specified region of a vector (or linearized array) to be read,
-leaving the remainder of the vector unchanged.
-
-@code{uniform-array-read!} returns the number of objects read.
-@var{port-or-fdes} may be omitted, in which case it defaults to the value
-returned by @code{(current-input-port)}.")
+	    "@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]\n"
+	    "Attempts to read all elements of @var{ura}, in lexicographic order, as\n"
+	    "binary objects from @var{port-or-fdes}.\n"
+	    "If an end of file is encountered during\n"
+	    "uniform-array-read! the objects up to that point only are put into @var{ura}\n"
+	    "(starting at the beginning) and the remainder of the array is\n"
+	    "unchanged.\n\n"
+	    "The optional arguments @var{start} and @var{end} allow\n"
+	    "a specified region of a vector (or linearized array) to be read,\n"
+	    "leaving the remainder of the vector unchanged.\n\n"
+	    "@code{uniform-array-read!} returns the number of objects read.\n"
+	    "@var{port-or-fdes} may be omitted, in which case it defaults to the value\n"
+	    "returned by @code{(current-input-port)}.")
 #define FUNC_NAME s_scm_uniform_array_read_x
 {
   SCM cra = SCM_UNDEFINED, v = ra;
@@ -1609,18 +1600,16 @@ loop:
 
 SCM_DEFINE (scm_uniform_array_write, "uniform-array-write", 1, 3, 0,
            (SCM v, SCM port_or_fd, SCM start, SCM end),
-"@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]
-Writes all elements of @var{ura} as binary objects to
-@var{port-or-fdes}.
-
-The optional arguments @var{start}
-and @var{end} allow
-a specified region of a vector (or linearized array) to be written.
-
-The number of objects actually written is returned. 
-@var{port-or-fdes} may be
-omitted, in which case it defaults to the value returned by
-@code{(current-output-port)}.")
+	    "@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]\n"
+	    "Writes all elements of @var{ura} as binary objects to\n"
+	    "@var{port-or-fdes}.\n\n"
+	    "The optional arguments @var{start}\n"
+	    "and @var{end} allow\n"
+	    "a specified region of a vector (or linearized array) to be written.\n\n"
+	    "The number of objects actually written is returned. \n"
+	    "@var{port-or-fdes} may be\n"
+	    "omitted, in which case it defaults to the value returned by\n"
+	    "@code{(current-output-port)}.")
 #define FUNC_NAME s_scm_uniform_array_write
 {
   long sz, vlen, ans;
@@ -1734,7 +1723,7 @@ static char cnt_tab[16] =
 
 SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0,
            (SCM item, SCM seq),
-"Returns the number occurrences of @var{bool} in @var{bv}.")
+	    "Returns the number occurrences of @var{bool} in @var{bv}.")
 #define FUNC_NAME s_scm_bit_count
 {
   long i;
@@ -1769,9 +1758,9 @@ SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0,
 
 SCM_DEFINE (scm_bit_position, "bit-position", 3, 0, 0,
            (SCM item, SCM v, SCM k),
-"Returns the minimum index of an occurrence of @var{bool} in @var{bv}
-which is at least @var{k}.  If no @var{bool} occurs within the specified
-range @code{#f} is returned.")
+	    "Returns the minimum index of an occurrence of @var{bool} in @var{bv}\n"
+	    "which is at least @var{k}.  If no @var{bool} occurs within the specified\n"
+	    "range @code{#f} is returned.")
 #define FUNC_NAME s_scm_bit_position
 {
   long i, lenw, xbits, pos;
@@ -1837,15 +1826,13 @@ range @code{#f} is returned.")
 
 SCM_DEFINE (scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
            (SCM v, SCM kv, SCM obj),
-"If uve is a bit-vector @var{bv} and uve must be of the same length.  If
-@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the
-inversion of uve is AND'ed into @var{bv}.
-
-If uve is a unsigned integer vector all the elements of uve must be
-between 0 and the @code{LENGTH} of @var{bv}.  The bits of @var{bv}
-corresponding to the indexes in uve are set to @var{bool}.
-
-The return value is unspecified.")
+	    "If uve is a bit-vector @var{bv} and uve must be of the same length.  If\n"
+	    "@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the\n"
+	    "inversion of uve is AND'ed into @var{bv}.\n\n"
+	    "If uve is a unsigned integer vector all the elements of uve must be\n"
+	    "between 0 and the @code{LENGTH} of @var{bv}.  The bits of @var{bv}\n"
+	    "corresponding to the indexes in uve are set to @var{bool}.\n\n"
+	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_bit_set_star_x
 {
   register long i, k, vlen;
@@ -1899,11 +1886,11 @@ The return value is unspecified.")
 
 SCM_DEFINE (scm_bit_count_star, "bit-count*", 3, 0, 0,
            (SCM v, SCM kv, SCM obj),
-"Returns
-@example
-(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
-@end example
-@var{bv} is not modified.")
+	    "Returns\n"
+	    "@example\n"
+	    "(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).\n"
+	    "@end example\n"
+	    "@var{bv} is not modified.")
 #define FUNC_NAME s_scm_bit_count_star
 {
   register long i, vlen, count = 0;
@@ -1967,7 +1954,7 @@ SCM_DEFINE (scm_bit_count_star, "bit-count*", 3, 0, 0,
 
 SCM_DEFINE (scm_bit_invert_x, "bit-invert!", 1, 0, 0, 
            (SCM v),
-"Modifies @var{bv} by replacing each element with its negation.")
+	    "Modifies @var{bv} by replacing each element with its negation.")
 #define FUNC_NAME s_scm_bit_invert_x
 {
   register long k;
@@ -2050,7 +2037,7 @@ ra2l (SCM ra,scm_sizet base,scm_sizet k)
 
 SCM_DEFINE (scm_array_to_list, "array->list", 1, 0, 0, 
            (SCM v),
-"Returns a list consisting of all the elements, in order, of @var{array}.")
+	    "Returns a list consisting of all the elements, in order, of @var{array}.")
 #define FUNC_NAME s_scm_array_to_list
 {
   SCM res = SCM_EOL;
@@ -2157,10 +2144,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet k);
 
 SCM_DEFINE (scm_list_to_uniform_array, "list->uniform-array", 3, 0, 0,
            (SCM ndim, SCM prot, SCM lst),
-"@deffnx procedure list->uniform-vector prot lst
-Returns a uniform array of the type indicated by prototype @var{prot}
-with elements the same as those of @var{lst}.  Elements must be of the
-appropriate type, no coercions are done.")
+	    "@deffnx procedure list->uniform-vector prot lst\n"
+	    "Returns a uniform array of the type indicated by prototype @var{prot}\n"
+	    "with elements the same as those of @var{lst}.  Elements must be of the\n"
+	    "appropriate type, no coercions are done.")
 #define FUNC_NAME s_scm_list_to_uniform_array
 {
   SCM shp = SCM_EOL;
@@ -2512,9 +2499,9 @@ tail:
 
 SCM_DEFINE (scm_array_prototype, "array-prototype", 1, 0, 0, 
            (SCM ra),
-"Returns an object that would produce an array of the same type as
-@var{array}, if used as the @var{prototype} for
-@code{make-uniform-array}.")
+	    "Returns an object that would produce an array of the same type as\n"
+	    "@var{array}, if used as the @var{prototype} for\n"
+	    "@code{make-uniform-array}.")
 #define FUNC_NAME s_scm_array_prototype
 {
   int enclosed = 0;