summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/ChangeLog11
-rw-r--r--doc/ref/guile.texi6
-rw-r--r--doc/ref/intro.texi8
-rw-r--r--doc/ref/scheme-compound.texi55
-rwxr-xr-xdoc/ref/scheme-data.texi78
5 files changed, 86 insertions, 72 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 89eea9bb5..501f3c4a6 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,14 @@
+2002-03-27 Neil Jerram <neil@ossau.uklinux.net>
+
+ * scheme-compound.texi (List Searching): Remove docs for
+ `scm_sloppy_mem*', which no longer exist.
+
+2002-03-24 Neil Jerram <neil@ossau.uklinux.net>
+
+ * guile.texi (Top), intro.texi (What is Guile?, The Basic Guile
+ Package): Use @ifnottex instead of @ifinfo, so that HTML
+ generation works correctly.
+
2002-03-24 Marius Vollmer <mvo@zagadka.ping.de>
* tools.texi: Updated to reflect changes to the guile-snarf tool.
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 4e131332d..cd83b3e79 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -121,7 +121,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.15 2002-03-16 13:51:03 ossau Exp $
+@subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@c AUTHORS
@@ -208,7 +208,7 @@ by Free Software Foundation.
@c Where to find Guile examples.
@set example-dir doc/examples
-@ifinfo
+@ifnottex
@node Top, Guile License, (dir), (dir)
@top The Guile Reference Manual
@@ -218,7 +218,7 @@ and interesting ways.
This Info file contains edition @value{MANUAL_EDITION} of the reference
manual, corresponding to Guile version @value{VERSION}.
-@end ifinfo
+@end ifnottex
@menu
Preface
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index 6d373a7cc..af1b48d0e 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -8,9 +8,9 @@ described in the
@tex
Revised$^5$
@end tex
-@ifinfo
+@ifnottex
Revised^5
-@end ifinfo
+@end ifnottex
Report on the Algorithmic Language Scheme (usually known as R5RS),
providing clean and general data and control structures. Guile goes
beyond the rather austere language presented in R5RS, extending it with
@@ -899,9 +899,9 @@ known as R5RS, or the
@iftex
``Revised$^5$ Report on the Algorithmic Language Scheme'',
@end iftex
-@ifinfo
+@ifnottex
``Revised^5 Report on the Algorithmic Language Scheme'',
-@end ifinfo
+@end ifnottex
we have included the report in the Guile distribution;
@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
Language Scheme}.
diff --git a/doc/ref/scheme-compound.texi b/doc/ref/scheme-compound.texi
index ec49bccd7..cff67d012 100644
--- a/doc/ref/scheme-compound.texi
+++ b/doc/ref/scheme-compound.texi
@@ -27,8 +27,6 @@ values can be looked up within them.
@section Pairs
@tpindex Pairs
-@c FIXME::martin: Review me!
-
Pairs are used to combine two Scheme objects into one compound object.
Hence the name: A pair stores a pair of objects.
@@ -133,8 +131,6 @@ by @code{set-cdr!} is unspecified.
@section Lists
@tpindex Lists
-@c FIXME::martin: Review me!
-
A very important data type in Scheme---as well as in all other Lisp
dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
Scheme does not have a real datatype @dfn{list}. Lists are made up of
@@ -173,8 +169,6 @@ or a pair which has a list in its cdr.
@node List Syntax
@subsection List Read Syntax
-@c FIXME::martin: Review me!
-
The syntax for lists is an opening parentheses, then all the elements of
the list (separated by whitespace) and finally a closing
parentheses.@footnote{Note that there is no separation character between
@@ -208,8 +202,6 @@ applications (@pxref{Simple Invocation}).
@node List Predicates
@subsection List Predicates
-@c FIXME::martin: Review me!
-
Often it is useful to test whether a given Scheme object is a list or
not. List-processing procedures could use this information to test
whether their input is valid, or they could do different things
@@ -279,8 +271,6 @@ use the procedure @code{copy-tree} (@pxref{Copying}).
@node List Selection
@subsection List Selection
-@c FIXME::martin: Review me!
-
These procedures are used to get some information about a list, or to
retrieve one or more elements of a list.
@@ -323,8 +313,6 @@ return it.
@node Append/Reverse
@subsection Append and Reverse
-@c FIXME::martin: Review me!
-
@code{append} and @code{append!} are used to concatenate two or more
lists in order to form a new list. @code{reverse} and @code{reverse!}
return lists with the same elements as their arguments, but in reverse
@@ -463,8 +451,6 @@ Like @code{delete!}, but only deletes the first occurrence of
@node List Searching
@subsection List Searching
-@c FIXME::martin: Review me!
-
The following procedures search lists for particular elements. They use
different comparison predicates for comparing list elements with the
object to be searched. When they fail, they return @code{#f}, otherwise
@@ -504,33 +490,10 @@ the non-empty lists returned by @code{(list-tail @var{lst}
empty list) is returned.
@end deffn
-[FIXME: Is there any reason to have the `sloppy' functions available at
-high level at all? Maybe these docs should be relegated to a "Guile
-Internals" node or something. -twp]
-
-@deffn {Scheme Procedure} sloppy-memq x lst
-This procedure behaves like @code{memq}, but does no type or error checking.
-Its use is recommended only in writing Guile internals,
-not for high-level Scheme programs.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-memv x lst
-This procedure behaves like @code{memv}, but does no type or error checking.
-Its use is recommended only in writing Guile internals,
-not for high-level Scheme programs.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-member x lst
-This procedure behaves like @code{member}, but does no type or error checking.
-Its use is recommended only in writing Guile internals,
-not for high-level Scheme programs.
-@end deffn
@node List Mapping
@subsection List Mapping
-@c FIXME::martin: Review me!
-
List processing is very convenient in Scheme because the process of
iterating over the elements of a list can be highly abstracted. The
procedures in this section are the most basic iterating procedures for
@@ -893,7 +856,7 @@ The field holds a Scheme value and is GC protected. When a structure is
created with this type of field, the field is initialized to refer to
the structure's own handle. This kind of field is mainly useful when
mixing Scheme and C code in which the C code may need to compute a
-structure's handle given only the address of its malloc-ed data.
+structure's handle given only the address of its malloc'd data.
@end itemize
@@ -1713,19 +1676,19 @@ because association lists are so useful, Guile also provides specific
procedures for manipulating them.
@menu
-* Alist Key Equality::
-* Adding or Setting Alist Entries::
-* Retrieving Alist Entries::
-* Removing Alist Entries::
-* Sloppy Alist Functions::
-* Alist Example::
+* Alist Key Equality::
+* Adding or Setting Alist Entries::
+* Retrieving Alist Entries::
+* Removing Alist Entries::
+* Sloppy Alist Functions::
+* Alist Example::
@end menu
@node Alist Key Equality
@subsubsection Alist Key Equality
All of Guile's dedicated association list procedures, apart from
-@code{acons}, come in three flavors, depending on the level of equality
+@code{acons}, come in three flavours, depending on the level of equality
that is required to decide whether an existing key in the association
list is the same as the key that the procedure call uses to identify the
required entry.
@@ -1864,7 +1827,7 @@ function is @emph{not} destructive; @var{alist} is not modified.
@deffnx {C Function} scm_assq_set_x (alist, key, val)
@deffnx {C Function} scm_assv_set_x (alist, key, val)
@deffnx {C Function} scm_assoc_set_x (alist, key, val)
-Re-associate @var{key} in @var{alist} with @var{value}: find any existing
+Reassociate @var{key} in @var{alist} with @var{value}: find any existing
@var{alist} entry for @var{key} and associate it with the new
@var{value}. If @var{alist} does not contain an entry for @var{key},
add a new one. Return the (possibly new) alist.
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
index 1c46a7004..b935dd952 100755
--- a/doc/ref/scheme-data.texi
+++ b/doc/ref/scheme-data.texi
@@ -3,7 +3,7 @@
@chapter Simple Generic Data Types
This chapter describes those of Guile's simple data types which are
-primarily are used for their role as items of generic data. By
+primarily used for their role as items of generic data. By
@dfn{simple} we mean data types that are not primarily used as
containers to hold other data --- i.e. pairs, lists, vectors and so on.
For the documentation of such @dfn{compound} data types, see
@@ -193,8 +193,7 @@ discover whether the value is any of the supported numerical types.
@deffn {Scheme Procedure} number? obj
@deffnx {C Function} scm_number_p (obj)
-Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
-@findex number?
+Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
@end deffn
For example:
@@ -265,7 +264,7 @@ completely invisible to the Scheme level programmer.
@deffn {Scheme Procedure} integer? x
@deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an integer number, @code{#f} else.
+Return @code{#t} if @var{x} is an integer number, else @code{#f}.
@lisp
(integer? 487)
@@ -329,11 +328,10 @@ with those that are already implemented.
@deffn {Scheme Procedure} real? obj
@deffnx {C Function} scm_real_p (obj)
-Return @code{#t} if @var{obj} is a real number, @code{#f} else.
+Return @code{#t} if @var{obj} is a real number, else @code{#f}.
Note that the sets of integer and rational values form subsets
of the set of real numbers, so the predicate will also be fulfilled
if @var{obj} is an integer number or a rational number.
-@findex real?
@end deffn
@deffn {Scheme Procedure} rational? x
@@ -1464,6 +1462,7 @@ called with string containing unusual characters.
* String Searching:: Searching in strings.
* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
* Appending Strings:: Appending strings to form a new string.
+* String Miscellanea:: Miscellaneous string procedures.
@end menu
@node String Syntax
@@ -1859,6 +1858,19 @@ concatenation of the given strings, @var{args}.
@end deffn
+@node String Miscellanea
+@subsection String Miscellanea
+
+This section contains all remaining string procedures.
+
+@deffn {Scheme Procedure} string-ci->symbol str
+@deffnx {C Function} scm_string_ci_to_symbol (str)
+Return the symbol whose name is @var{str}. @var{str} is
+converted to lowercase before the conversion is done, if Guile
+is currently reading symbols case-insensitively.
+@end deffn
+
+
@node Regular Expressions
@section Regular Expressions
@tpindex Regular expressions
@@ -2262,6 +2274,7 @@ objects @i{per se}.
@menu
* Symbol Read Syntax:: Extended read syntax for symbols.
* Symbol Primitives:: Operations related to symbols.
+* Symbol Tables:: Collecting symbols into obarrays.
* Symbol Discrete:: Using symbols as discrete values.
* Symbol Props:: Function slots and property lists.
* Symbol Uninterned:: Uninterned symbols.
@@ -2271,7 +2284,7 @@ objects @i{per se}.
@node Symbol Read Syntax
@subsection Extended Read Syntax for Symbols
-The read syntax for symbols is a sequence of letters, digits, and
+The read syntax for a symbol is a sequence of letters, digits, and
@dfn{extended alphabetic characters}, beginning with a character that
cannot begin a number. In addition, the special cases of @code{+},
@code{-}, and @code{...} are read as symbols even though numbers can
@@ -2281,7 +2294,7 @@ Extended alphabetic characters may be used within identifiers as if
they were letters. The set of extended alphabetic characters is:
@example
-! $ % & * + - . / : < = > ? @@ ^ _ ~
+! $ % & * + - . / : < = > ? @@ ^ _ ~
@end example
In addition to the standard read syntax defined above (which is taken
@@ -2348,8 +2361,8 @@ standard case is lower case:
(eq? 'mISSISSIppi 'mississippi) @result{} #t
(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-(eq? 'JollyWog
- (string->symbol (symbol->string 'JollyWog))) @result{} #t
+(eq? 'LolliPop
+ (string->symbol (symbol->string 'LolliPop))) @result{} #t
(string=? "K. Harper, M.D."
(symbol->string
(string->symbol "K. Harper, M.D."))) @result{}#t
@@ -2391,10 +2404,17 @@ standard case is lower case:
@end lisp
@end deffn
-@deffn {Scheme Procedure} symbol-hash symbol
-@deffnx {C Function} scm_symbol_hash (symbol)
-Return a hash value for @var{symbol}.
-@end deffn
+@node Symbol Tables
+@subsection Symbol Tables
+
+@c FIXME::martin: Are all these procedures still relevant?
+
+Guile symbol tables are hash tables. Each hash table, also called an
+@dfn{obarray} (for `object array'), is a vector of association lists.
+Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To
+@dfn{intern} a symbol in a symbol table means to return its
+(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
+table (with an undefined value) if none is yet present.
@deffn {Scheme Procedure} gensym [prefix]
@deffnx {C Function} scm_gensym (prefix)
@@ -2405,6 +2425,12 @@ is increased by 1 at each call. There is no provision for
resetting the counter.
@end deffn
+@vgone{gentemp,1.6}
+@vgone{intern-symbol,1.6}
+@vgone{string->obarray-symbol,1.6}
+@vgone{symbol-binding,1.6}
+@vgone{symbol-bound?,1.6}
+
@node Symbol Discrete
@subsection Using Symbols as Discrete Values
@@ -2434,6 +2460,17 @@ Return the contents of @var{symbol}'s @dfn{function slot}.
Change the binding of @var{symbol}'s function slot.
@end deffn
+@deffn {Scheme Procedure} symbol-hash symbol
+@deffnx {C Function} scm_symbol_hash (symbol)
+Return a hash value for @var{symbol}.
+@end deffn
+
+@deffn {Scheme Procedure} symbol-interned? obarray string
+@deffnx {C Function} scm_symbol_interned_p (obarray, string)
+Return @code{#t} if @var{obarray} contains a symbol with name
+@var{string}, and @code{#f} otherwise.
+@end deffn
+
@deffn {Scheme Procedure} symbol-pref symbol
@deffnx {C Function} scm_symbol_pref (symbol)
Return the @dfn{property list} currently associated with @var{symbol}.
@@ -2444,6 +2481,10 @@ Return the @dfn{property list} currently associated with @var{symbol}.
Change the binding of @var{symbol}'s property slot.
@end deffn
+@vgone{symbol-set!,1.6}
+@vgone{unintern-symbol,1.6}
+
+
@node Symbol Uninterned
@subsection Uninterned Symbols
@@ -2465,14 +2506,14 @@ just returns that symbol. When not, a new symbol with the name is
created and entered into the table so that it can be found later.
Sometimes you might want to create a symbol that is guaranteed `fresh',
-i.e., a symbol that did not exist previously. You might also want to
+i.e. a symbol that did not exist previously. You might also want to
somehow guarantee that no one else will ever unintentionally stumble
across your symbol in the future. These properties of a symbol are
often needed when generating code during macro expansion. When
introducing new temporary variables, you want to guarantee that they
-don't conflict with variables in other peoples code.
+don't conflict with variables in other people's code.
-The simplest way to arrange for this is to create a new symbol and to
+The simplest way to arrange for this is to create a new symbol but
not enter it into the global table of all symbols. That way, no one
will ever get access to your symbol by chance. Symbols that are not in
the table are called @dfn{uninterned}. Of course, symbols that
@@ -2531,6 +2572,7 @@ foo-3
@end lisp
+
@node Keywords
@section Keywords
@tpindex Keywords
@@ -2717,8 +2759,6 @@ ABORT: (unbound-variable)
@node Keyword Procedures
@subsection Keyword Procedures
-@c FIXME::martin: Review me!
-
The following procedures can be used for converting symbols to keywords
and back.