* Improve doc on variables and definitions.

doc/ref/ChangeLog

@@ -1,3 +1,14 @@
+2001-11-19  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* scheme-data.texi (Symbol Tables), new-docstrings.texi: Removed
+	doc for builtin-bindings (no longer exists).
+	(Variables): Expanded existing description of variables.  Removed
+	doc for builtin-variable (no longer exists).
+
+	* scheme-binding.texi (Top Level): New docs for define, scm_define
+	and scm_c_define.  Also clarified point about interchangeability
+	of define and set!.
+
 2001-11-18  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* scheme-data.texi (Vectors): Autoupdate docs for

doc/ref/new-docstrings.texi

@@ -573,11 +573,6 @@ Return the value from @var{obj}'s slot with the name
 @var{slot_name}.
 @end deffn
 
-@deffn {Scheme Procedure} builtin-bindings
-Create and return a copy of the global symbol table, removing all
-unbound symbols.
-@end deffn
-
 @deffn {Scheme Procedure} %tag-body body
 @deffnx {C Function} scm_sys_tag_body (body)
 Internal GOOPS magic---don't use this function!

doc/ref/scheme-binding.texi

@@ -20,35 +20,71 @@ and expressions.  This is important for modularity and data abstraction.
 @node Top Level
 @section Top Level Variable Definitions
 
-@c FIXME::martin: Review me!
-
 @cindex variable definition
 
-On the top level of a program (e.g. when not inside of a procedure
-definition or a @code{let}, @code{let*} or @code{letrec} expression), a
-definition of the form
+On the top level of a program (i.e. when not inside the body of a
+procedure definition or a @code{let}, @code{let*} or @code{letrec}
+expression), a definition of the form
 
 @lisp
-(define a 1)
+(define a @var{value})
 @end lisp
 
 @noindent
-defines a variable called @var{a} and sets it to the value 1.  When the
-variable already was bound with a @code{define} expression, the above
+defines a variable called @code{a} and sets it to the value @var{value}.
+
+If the variable already exists, because it has already been created by a
+previous @code{define} expression with the same name, its value is
+simply changed to the new @var{value}.  In this case, then, the above
 form is completely equivalent to
 
 @lisp
-(set! a 1)
+(set! a @var{value})
 @end lisp
 
 @noindent
-that means that @code{define} can be used interchangeably with
-@code{set!} when at the top level of the REPL or a Scheme source file.
-But note that a @code{set!} is not allowed if the variable was not bound
-before.
+This equivalence means that @code{define} can be used interchangeably
+with @code{set!} to change the value of variables at the top level of
+the REPL or a Scheme source file.  It is useful during interactive
+development when reloading a Scheme file that you have modified, because
+it allows the @code{define} expressions in that file to work as expected
+both the first time that the file is loaded and on subsequent occasions.
 
-Attention: definitions inside local binding constructs (@pxref{Local
-Bindings}) act differently (@pxref{Internal Definitions}).
+Note, though, that @code{define} and @code{set!} are not always
+equivalent.  For example, a @code{set!} is not allowed if the named
+variable does not already exist, and the two expressions can behave
+differently in the case where there are imported variables visible from
+another module.
+
+@deffn {Scheme Syntax} define name value
+Create a top level variable named @var{name} with value @var{value}.
+If the named variable already exists, just change its value.  The return
+value of a @code{define} expression is unspecified.
+@end deffn
+
+The C API equivalents of @code{define} are @code{scm_define} and
+@code{scm_c_define}, which differ from each other in whether the
+variable name is specified as a @code{SCM} symbol or as a
+null-terminated C string.
+
+@deffn {C Function} scm_define (sym, value)
+@deffnx {C Function} scm_c_define (const char *name, value)
+C equivalents of @code{define}, with variable name specified either by
+@var{sym}, a symbol, or by @var{name}, a null-terminated C string.  Both
+variants return the new or preexisting variable object.
+@end deffn
+
+@code{define} (when it occurs at top level), @code{scm_define} and
+@code{scm_c_define} all create or set the value of a variable in the top
+level environment of the current module.  If there was not already a
+variable with the specified name belonging to the current module, but a
+similarly named variable from another module was visible through having
+been imported, the newly created variable in the current module will
+shadow the imported variable, such that the imported variable is no
+longer visible.
+
+Attention: Scheme definitions inside local binding constructs
+(@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
 
 
 @node Local Bindings

doc/ref/scheme-data.texi

@@ -2475,14 +2475,6 @@ Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}).  To
 (@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
 table (with an undefined value) if none is yet present.
 
-@c FIXME::martin: According to NEWS, removed.  Remove here too, or 
-@c leave for compatibility?
-@c @c docstring begin (texi-doc-string "guile" "builtin-bindings")
-@c @deffn {Scheme Procedure} builtin-bindings
-@c Create and return a copy of the global symbol table, removing all
-@c unbound symbols.
-@c @end deffn
-
 @deffn {Scheme Procedure} gensym [prefix]
 @deffnx {C Function} scm_gensym (prefix)
 Create a new symbol with a name constructed from a prefix and
@@ -2571,30 +2563,47 @@ function returns @code{#t} if the symbol was present and @code{#f}
 otherwise.
 @end deffn
 
+
 @node Variables
 @subsection Variables
 @tpindex Variables
 
-@c FIXME::martin: Review me!
+A variable is a box-like object that can hold any Scheme value.  It is
+said to be @dfn{undefined} if its box holds a special Scheme value that
+denotes undefined-ness (which is different from all other Scheme values,
+including for example @code{#f}); otherwise the variable is
+@dfn{defined}.
 
-Variables are objects with two fields.  They contain a value and they
-can contain a symbol, which is the name of the variable.  A variable is
-said to be bound if it does not contain the object denoting unbound
-variables in the value slot.
+On its own, a variable object is anonymous.  A variable is said to be
+@dfn{bound} when it is associated with a name in some way, usually a
+symbol in a module obarray.  When this happens, the relationship is
+mutual: the variable is bound to the name (in that module), and the name
+(in that module) is bound to the variable.
 
-Variables do not have a read syntax, they have to be created by calling
-one of the constructor procedures @code{make-variable} or
-@code{make-undefined-variable} or retrieved by @code{builtin-variable}.
+(That's the theory, anyway.  In practice, defined-ness and bound-ness
+sometimes get confused, because Lisp and Scheme implementations have
+often conflated --- or deliberately drawn no distinction between --- a
+name that is unbound and a name that is bound to a variable whose value
+is undefined.  We will try to be clear about the difference and explain
+any confusion where it is unavoidable.)
+
+Variables do not have a read syntax.  Most commonly they are created and
+bound implicitly by @code{define} expressions: a top-level @code{define}
+expression of the form
+
+@lisp
+(define @var{name} @var{value})
+@end lisp
+
+@noindent
+creates a variable with initial value @var{value} and binds it to the
+name @var{name} in the current module.  But they can also be created
+dynamically by calling one of the constructor procedures
+@code{make-variable} and @code{make-undefined-variable}.
 
 First-class variables are especially useful for interacting with the
 current module system (@pxref{The Guile module system}).
 
-@deffn {Scheme Procedure} builtin-variable name
-Return the built-in variable with the name @var{name}.
-@var{name} must be a symbol (not a string).
-Then use @code{variable-ref} to access its value.
-@end deffn
-
 @deffn {Scheme Procedure} make-undefined-variable
 @deffnx {C Function} scm_make_undefined_variable ()
 Return a variable that is initially unbound.