Update vector docs.

Remove Guile extensions index.
A few other odds and ends.

doc/ref/ChangeLog

@@ -1,5 +1,20 @@
 2002-04-01  Neil Jerram  <neil@ossau.uklinux.net>
 
+	* scheme-intro.texi (Scheme Layout): Remove reference to defunct
+	Guile Extensions index.
+
+	* guile.texi: Removed Guile Extensions index.
+
+	* scheme-indices.texi (Guile Extensions Index): Removed.
+
+	* guile.texi: Remove vgone, vdeprecated, vchanged and vnote
+	macros; they're not actually useful after all.  Update copyright
+	years.
+
+	* scheme-compound.texi (Vectors): Make subsections into nodes.
+	(Vectors): Review, slightly reorg and clarify docs in this
+	section.
+
 	* scheme-data.texi (Symbols): Reorganized node substructure and
 	added lots of explanatory text around the @deffn's.
 

doc/ref/guile.texi

@@ -46,37 +46,15 @@
 @c reference manual to group stuff according to whether it is R5RS or a
 @c Guile extension.
 @defcodeindex rn
-@defcodeindex ge
 
 @include version.texi
 
-@c Macros for describing version information.  I've initially defined
-@c all of these to expand to nothing, but they could perhaps be made to
-@c expand to something like "New in Guile 45!" in future.
-
-@c vnew - indicates the Guile version in which item first appeared.
+@c vnew - For (some) new items, indicates the Guile version in which
+@c item first appeared.  In future, this could be made to expand to
+@c something like a "New in Guile 45!" banner.
 @macro vnew{VERSION}
 @end macro
 
-@c vdeprecated - indicates that the item has been deprecated, and the
-@c Guile version in which the deprecation started.
-@macro vdeprecated{VERSION}
-@end macro
-
-@c vgone - a way of tracking items that are no longer here.  In this
-@c case, VERSION is the last Guile version in which the item was present.
-@macro vgone{WHAT, VERSION}
-@end macro
-
-@c vchanged - indicates the Guile version in which item's behaviour
-@c significantly changed.
-@macro vchanged{VERSION}
-@end macro
-
-@c vnote - catchall for any additional notes.
-@macro vnote{NOTE}
-@end macro
-
 @c @iftex
 @c @cropmarks
 @c @end iftex
@@ -93,7 +71,8 @@ Guile Reference Manual
 Copyright (C) 1996 Free Software Foundation @*
 Copyright (C) 1997 Free Software Foundation @*
 Copyright (C) 2000 Free Software Foundation @*
-Copyright (C) 2001 Free Software Foundation
+Copyright (C) 2001 Free Software Foundation @*
+Copyright (C) 2002 Free Software Foundation
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -121,7 +100,7 @@ by the Free Software Foundation.
 @sp 10
 @comment The title is printed in a large font.
 @title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $
+@subtitle $Id: guile.texi,v 1.17 2002-04-01 18:46:26 ossau Exp $
 @subtitle For use with Guile @value{VERSION}
 
 @c AUTHORS
@@ -186,6 +165,10 @@ Copyright @copyright{} 1997 Free Software Foundation
 
 Copyright @copyright{} 2000 Free Software Foundation
 
+Copyright @copyright{} 2001 Free Software Foundation
+
+Copyright @copyright{} 2002 Free Software Foundation
+
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
 are preserved on all copies.
@@ -291,7 +274,6 @@ Indices
 * Variable Index::
 * Type Index::
 * R5RS Index::
-* Guile Extensions Index::
 
 @end menu
 

doc/ref/scheme-compound.texi

@@ -528,11 +528,6 @@ return value is not specified.
 @section Vectors
 @tpindex Vectors
 
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Should the subsections of this section be nodes
-@c of their own, or are the resulting nodes too short, then?
-
 Vectors are sequences of Scheme objects.  Unlike lists, the length of a
 vector, once the vector is created, cannot be changed.  The advantage of
 vectors over lists is that the time required to access one element of a vector
@@ -545,7 +540,15 @@ different types of objects in the same vector.  For vectors containing
 vectors, you may wish to use arrays, instead.  Note, too, that some array
 procedures operate happily on vectors (@pxref{Arrays}).
 
-@subsection Vector Read Syntax
+@menu
+* Vector Syntax::               Read syntax for vectors.
+* Vector Creation::             Dynamic vector creation and validation.
+* Vector Accessors::            Accessing and modifying vector contents.
+@end menu
+
+
+@node Vector Syntax
+@subsection Read Syntax for Vectors
 
 Vectors can literally be entered in source code, just like strings,
 characters or some of the other data types.  The read syntax for vectors
@@ -561,25 +564,15 @@ number in hexadecimal notation.
 #("Hello" foo #xdeadbeef)
 @end lisp
 
-@subsection Vector Predicates
 
-@rnindex vector?
-@deffn {Scheme Procedure} vector? obj
-@deffnx {C Function} scm_vector_p (obj)
-Return @code{#t} if @var{obj} is a vector, otherwise return
-@code{#f}.
-@end deffn
+@node Vector Creation
+@subsection Dynamic Vector Creation and Validation
 
-@subsection Vector Constructors
-
-@rnindex make-vector
-@deffn {Scheme Procedure} make-vector k [fill]
-@deffnx {C Function} scm_make_vector (k, fill)
-Return a newly allocated vector of @var{k} elements.  If a
-second argument is given, then each position is initialized to
-@var{fill}.  Otherwise the initial contents of each position is
-unspecified.
-@end deffn
+Instead of creating a vector implicitly by using the read syntax just
+described, you can create a vector dynamically by calling one of the
+@code{vector} and @code{list->vector} primitives with the list of Scheme
+values that you want to place into a vector.  The size of the vector
+thus created is determined implicitly by the number of arguments given.
 
 @rnindex vector
 @rnindex list->vector
@@ -594,6 +587,14 @@ given arguments.  Analogous to @code{list}.
 @end lisp
 @end deffn
 
+(As an aside, an interesting implementation detail is that the Guile
+reader reads the @code{#(@dots{})} syntax by reading everything but the
+initial @code{#} as a @emph{list}, and then passing the list that
+results to @code{list->vector}.  Notice how neatly this fits with the
+similarity between the read (and print) syntaxes for lists and vectors.)
+
+The inverse operation is @code{vector->list}:
+
 @rnindex vector->list
 @deffn {Scheme Procedure} vector->list v
 @deffnx {C Function} scm_vector_to_list (v)
@@ -605,19 +606,71 @@ Return a newly allocated list composed of the elements of @var{v}.
 @end lisp
 @end deffn
 
-@subsection Vector Modification
+To allocate a vector with an explicitly specified size, use
+@code{make-vector}.  With this primitive you can also specify an initial
+value for the vector elements (the same value for all elements, that
+is):
 
-A vector created by any of the vector constructor procedures
-(@pxref{Vectors}) documented above can be modified using the
-following procedures.
+@rnindex make-vector
+@deffn {Scheme Procedure} make-vector k [fill]
+@deffnx {C Function} scm_make_vector (k, fill)
+Return a newly allocated vector of @var{k} elements.  If a
+second argument is given, then each position is initialized to
+@var{fill}.  Otherwise the initial contents of each position is
+unspecified.
+@end deffn
 
-@emph{NOTE:} According to R5RS, using any of these procedures on
-literally entered vectors is an error, because these vectors are
-considered to be constant, although Guile currently does not detect this
+To check whether an arbitrary Scheme value @emph{is} a vector, use the
+@code{vector?} primitive:
+
+@rnindex vector?
+@deffn {Scheme Procedure} vector? obj
+@deffnx {C Function} scm_vector_p (obj)
+Return @code{#t} if @var{obj} is a vector, otherwise return
+@code{#f}.
+@end deffn
+
+
+@node Vector Accessors
+@subsection Accessing and Modifying Vector Contents
+
+@code{vector-length} and @code{vector-ref} return information about a
+given vector, respectively its size and the elements that are contained
+in the vector.
+
+@rnindex vector-length
+@deffn {Scheme Procedure} vector-length vector
+@deffnx {C Function} scm_vector_length vector
+Return the number of elements in @var{vector} as an exact integer.
+@end deffn
+
+@rnindex vector-ref
+@deffn {Scheme Procedure} vector-ref vector k
+@deffnx {C Function} scm_vector_ref vector k
+Return the contents of position @var{k} of @var{vector}.
+@var{k} must be a valid index of @var{vector}.
+@lisp
+(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
+(vector-ref '#(1 1 2 3 5 8 13 21)
+    (let ((i (round (* 2 (acos -1)))))
+      (if (inexact? i)
+        (inexact->exact i)
+           i))) @result{} 13
+@end lisp
+@end deffn
+
+A vector created by one of the dynamic vector constructor procedures
+(@pxref{Vector Creation}) can be modified using the following
+procedures.
+
+@emph{NOTE:} According to R5RS, it is an error to use any of these
+procedures on a literally read vector, because such vectors should be
+considered as constants.  Currently, however, Guile does not detect this
 error.
 
 @rnindex vector-set!
 @deffn {Scheme Procedure} vector-set! vector k obj
+@deffnx {C Function} scm_vector_set_x vector k obj
 Store @var{obj} in position @var{k} of @var{vector}.
 @var{k} must be a valid index of @var{vector}.
 The value returned by @samp{vector-set!} is unspecified.
@@ -659,30 +712,6 @@ same vector, @code{vector-move-right!} is usually appropriate when
 @var{start1} is less than @var{start2}.
 @end deffn
 
-@subsection Vector Selection
-
-These procedures return information about a given vector, such as the
-size or what elements are contained in the vector.
-
-@rnindex vector-length
-@deffn {Scheme Procedure} vector-length vector
-Return the number of elements in @var{vector} as an exact integer.
-@end deffn
-
-@rnindex vector-ref
-@deffn {Scheme Procedure} vector-ref vector k
-Return the contents of position @var{k} of @var{vector}.
-@var{k} must be a valid index of @var{vector}.
-@lisp
-(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
-    (let ((i (round (* 2 (acos -1)))))
-      (if (inexact? i)
-        (inexact->exact i)
-           i))) @result{} 13
-@end lisp
-@end deffn
-
 
 @node Records
 @section Records

doc/ref/scheme-indices.texi

@@ -5,13 +5,6 @@
 @printindex rn
 
 
-@page
-@node Guile Extensions Index
-@unnumbered Guile Extensions Index
-
-@printindex ge
-
-
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:

doc/ref/scheme-intro.texi

@@ -45,9 +45,8 @@ parts and Guile-specific extensions, the text indicates which parts of
 the documentation describe R5RS behaviour and which parts describe Guile
 extensions.
 
-For a breakdown of Guile's core language and features in terms of what
-is R5RS-compliant and what is Guile-specific, see the corresponding
-indices: @ref{R5RS Index} and @ref{Guile Extensions Index}.
+For a quick way of identifying the parts of Guile that implement
+R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.
 
 
 @c Local Variables: