summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/.cvsignore26
-rw-r--r--doc/ref/ChangeLog610
-rw-r--r--doc/ref/ChangeLog-guile-doc-ref890
-rw-r--r--doc/ref/Makefile.am62
-rw-r--r--doc/ref/api.txt185
-rw-r--r--doc/ref/autoconf.texi234
-rw-r--r--doc/ref/data-rep.texi2047
-rw-r--r--doc/ref/debugging.texi115
-rw-r--r--doc/ref/deprecated.texi3
-rw-r--r--doc/ref/expect.texi142
-rw-r--r--doc/ref/extend.texi44
-rw-r--r--doc/ref/gh.texi1170
-rw-r--r--doc/ref/guile.texi389
-rw-r--r--doc/ref/indices.texi52
-rw-r--r--doc/ref/intro.texi1128
-rw-r--r--doc/ref/misc-modules.texi426
-rw-r--r--doc/ref/new-docstrings.texi701
-rw-r--r--doc/ref/posix.texi2490
-rw-r--r--doc/ref/preface.texi200
-rw-r--r--doc/ref/program.texi776
-rw-r--r--doc/ref/repl-modules.texi131
-rw-r--r--doc/ref/scheme-binding.texi279
-rw-r--r--doc/ref/scheme-compound.texi2431
-rw-r--r--doc/ref/scheme-control.texi979
-rwxr-xr-xdoc/ref/scheme-data.texi3086
-rw-r--r--doc/ref/scheme-debug.texi206
-rw-r--r--doc/ref/scheme-evaluation.texi426
-rw-r--r--doc/ref/scheme-ideas.texi1459
-rw-r--r--doc/ref/scheme-indices.texi10
-rw-r--r--doc/ref/scheme-intro.texi36
-rw-r--r--doc/ref/scheme-io.texi1116
-rw-r--r--doc/ref/scheme-memory.texi396
-rw-r--r--doc/ref/scheme-modules.texi909
-rw-r--r--doc/ref/scheme-options.texi651
-rw-r--r--doc/ref/scheme-procedures.texi816
-rw-r--r--doc/ref/scheme-reading.texi27
-rw-r--r--doc/ref/scheme-scheduling.texi453
-rw-r--r--doc/ref/scheme-translation.texi48
-rw-r--r--doc/ref/scheme-utility.texi731
-rw-r--r--doc/ref/scm.texi181
-rw-r--r--doc/ref/script-getopt.texi435
-rw-r--r--doc/ref/scripts.texi225
-rw-r--r--doc/ref/scsh.texi18
-rw-r--r--doc/ref/slib.texi105
-rw-r--r--doc/ref/srfi-modules.texi2399
-rw-r--r--doc/ref/tcltk.texi3
-rw-r--r--doc/ref/tools.texi386
47 files changed, 0 insertions, 29632 deletions
diff --git a/doc/ref/.cvsignore b/doc/ref/.cvsignore
deleted file mode 100644
index dd408965c..000000000
--- a/doc/ref/.cvsignore
+++ /dev/null
@@ -1,26 +0,0 @@
-*.aux
-*.cp
-*.cps
-*.dvi
-*.fn
-*.fns
-*.ge
-*.html
-*.info*
-*.ky
-*.log
-*.pg
-*.ps
-*.rn
-*.rns
-*.toc
-*.tp
-*.tps
-*.vr
-*.vrs
-Makefile
-Makefile.in
-autoconf-macros.texi
-stamp-vti
-stamp-vti.1
-version.texi
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
deleted file mode 100644
index 88d4c02d8..000000000
--- a/doc/ref/ChangeLog
+++ /dev/null
@@ -1,610 +0,0 @@
-2002-08-02 Gary Houston <ghouston@arglist.com>
-
- * scheme-modules.texi: split "Scheme and modules" into
- "provide and require" and "Environments". Mention R5RS
- environments.
-
-2002-07-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-options.texi (Debugger options): New subsection
- describing stack overflow and what to do about it.
-
-2002-07-10 Gary Houston <ghouston@arglist.com>
-
- * scheme-modules.texi (Compiled Code Modules): Removed description
- of scm_register_module_xxx, which no longer exists. A description
- of current techniques is needed.
-
-2002-05-09 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-data.texi (Numbers): Added description of the new values
- +inf.0, -inf.0 and +nan.0.
-
- * posix.texi (Runtime Environment): Added entries for 'setenv' and
- 'unsetenv'.
-
-2002-04-28 Marius Vollmer <mvo@zagadka.ping.de>
-
- * gh.texi, data-rep.texi: Moved `@deftyp {Data type} SCM' line
- from gh.texi to data-rep.texi. Both files already had similar
- descriptions for SCM. Given that gh.texi is deprecated, looking
- up `SCM' in the index should take one to the primary location
- rather than deprecated section. Hence this change. Added
- `@deftp' for scm_t_bits data type so that a proper index entry is
- added for this. Thanks to Richard Y. Kim!
-
- * data-rep.texi (Subrs): Changed scm_make_gsubr to
- scm_c_define_gsubr. Thanks to Richard Y. Kim!
-
-2002-04-24 Marius Vollmer <mvo@zagadka.ping.de>
-
- * srfi-modules.texi (SRFI-13 Miscellaneous): Updated docs of
- string-tokenize.
-
-2002-04-20 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-intro.texi (Scheme Layout), scm.texi (Reference Layout):
- Node moved from a to b.
-
- * guile.texi (Scheme Intro, Basic Ideas, Guile Scripting, Command
- Line Handling, Debugging Features, Autoconf Support, Miscellaneous
- Tools, Further Reading): Moved to new Part II.
-
- * preface.texi (Manual Layout): Part numbers updated accordingly.
-
- * guile.texi (Top): Move API Overview node to beginning of Guile
- API Reference part.
- (Part II: Writing and Running Guile Scheme): New part; will
- contain content from `Programming with Guile' that pertains to
- writing and using Guile on the Scheme level.
-
- * scm.texi (API Overview): Renamed from `Guile API'.
-
- * guile.texi (Top), scheme-modules.texi (Included Guile Modules):
- Debugger User Interface node renamed Debugging Features.
-
- * debugging.texi (Stacks and Frames): Node deleted; non-duplicated
- material moved to scheme-debug.texi.
- (Debugging Features): Renamed from `Debugger User Interface'.
-
- * scheme-debug.texi (Debugging): Rename chapter `Debugging
- Infrastructure' and reorganize its contents.
-
- * scheme-debug.texi (Debugging), scheme-control.texi (Handling
- Errors): Move display-error to error-focussed section.
-
- * scheme-debug.texi (Debugging), debugging.texi (Backtrace): Move
- backtrace to user-level debugging chapter.
-
- * scheme-debug.texi (Debugging), scheme-procedures.texi (Procedure
- Properties): Move procedure-name, procedure-source and
- procedure-environment to procedures chapter.
-
- * scheme-debug.texi (Debugging), scheme-memory.texi (Memory
- Blocks): Move malloc-stats to memory management chapter.
-
- * scheme-procedures.texi (Syntax Rules): Remove mention of
- use-modules for loading syncase; only use-syntax really works.
- Thanks to Panagiotis Vossos for spotting this.
-
- * program.texi (Scheme vs C): New node, with existing material
- taken from chapter intro.
- (Programming Overview): New intro para to introduce example of
- Guile integration:
- (Extending Dia): New node.
-
-2002-04-17 Marius Vollmer <mvo@zagadka.ping.de>
-
- * Makefile.am (CLEANFILES): Added guile.cps, guile.fns, guile.rns,
- guile.tps, guile.vrs, guile.tmp.
-
-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.
-
-2002-03-29 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-modules.texi (Variables): Mention obarrays.
-
- * scheme-data.texi (Symbol Tables, Symbol Props): Remove vgone
- markers for deprecated symbol items.
- (Symbol Props): Remove doc for obsolete 2 arg version of
- symbol-interned?.
- (String Miscellanea): Removed, since it only contained duplicate
- doc for string-ci->symbol.
- (Symbol Tables): Move doc for gensym to Symbol Primitives; rest of
- section removed.
-
- * posix.texi (Ports and File Descriptors), scheme-evaluation.texi
- (Fly Evaluation): Remove vgone markers for close-all-ports-except,
- eval2 and read-and-eval!.
-
- * data-rep.texi (Describing a New Type), scheme-compound.texi
- (Append/Reverse), scheme-procedures.texi (Internal Macros):
- Trivial updates to sync with stable branch.
-
-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.
-
-2002-03-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-utility.texi (Hooks): Further updates. New material on
- GC hooks.
-
- * scheme-evaluation.texi (Fly Evaluation): Note disappearance of
- eval2 and read-and-eval!.
-
- * deprecated.texi (Deprecated): Remove docs about previously
- deprecated items that have now been removed.
-
-2002-03-15 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * tools.texi (guile-1.4 guile-snarf): Remove this node.
- (How guile-snarf works): Update usage and description to
- no longer mention "--compat=1.4" and instead "-d" and "-D".
- (Macros guile-snarf recognizes): Add list of deprecated macros
- and blurb. Add cindex for deprecated macros.
-
-2002-03-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-utility.texi (Hooks): Reviewed and updated.
-
- * scheme-options.texi (Feature Tracking): New section.
-
- * scheme-data.texi (Arithmetic, Primitive Numerics): Add
- description of corresponding C functions.
-
- * scheme-utility.texi (Object Properties): Revamp documentation on
- object properties.
-
- * scheme-memory.texi (Weak References): Update reference to Object
- Properties node.
-
- * guile.texi: Add macros for describing version information.
-
- * scheme-data.texi, scheme-debug.texi, scheme-io.texi,
- scheme-procedures.texi: Automatic updates from snarfed libguile
- docstrings.
-
-2002-03-13 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am (guile_toc.html): Look for guile.texi in $(srcdir).
-
- * tools.texi (How guile-snarf works): Mention "--compat=1.4", and
- new processing steps. Update usage example, makefile frag.
-
- (guile-1.4 guile-snarf): New subsubsection under
- "Init Snarfing with guile-snarf".
-
-2002-03-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-compound.texi, scheme-data.texi, new-docstrings.texi:
- Automatic updates from snarfed libguile docstrings.
-
- * data-rep.texi, guile.texi, scheme-evaluation.texi,
- scheme-options.texi, scheme-translation.texi: Various minor
- enhancements ported from the stable CVS branch.
-
-2002-03-08 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * tools.texi (Miscellaneous Tools): New node/chapter.
- (Snarfing, Init Snarfing with guile-snarf, How guile-snarf works,
- Macros guile-snarf recognizes, Doc Snarfing): New nodes/(sub)sections.
- (Executable Modules): Now a section under "Miscellaneous Tools".
-
- * guile.texi (Miscellaneous Tools): Add under "Part II".
- Implement by including tools.texi.
-
- * Makefile.am (guile_TEXINFOS): Add tools.texi.
-
-2002-03-07 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * tools.texi: New file.
-
-2002-03-03 Neil Jerram <neil@ossau.uklinux.net>
-
- * autoconf.texi (Autoconf Background): Insert missing `of'.
-
-2002-03-01 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * api.txt, data-rep.texi: Renamed the struct scm_cell to
- scm_t_cell.
-
- * data-rep.texi: Renamed scm_alloc_cell to scm_cell and
- scm_alloc_double_cell to scm_double_cell.
-
-2002-03-01 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-memory.texi (Upgrading from scm_must_malloc et al): New
- section.
-
-2002-02-28 Marius Vollmer <mvo@zagadka.ping.de>
-
- * data-rep.texi: Use scm_gc_malloc and scm_gc_free instead of
- scm_must_malloc and free in example code. Updated text for the
- new memory management functions.
-
- * scheme-debug.texi (malloc-stats): Refer to scm_gc_malloc instead
- of to scm_must_malloc.
-
-2002-02-27 Stefan Jahn <stefan@lkcc.org>
-
- * gh.texi (scm transition summary): Documented some more
- gh equivalents and removed appropriate FIXME's.
-
-2002-02-26 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am: Update path to pre-inst-guile automake frag.
-
-2002-02-24 Rob Browning <rlb@defaultvalue.org>
-
- * .cvsignore: add autoconf-macros.texi.
-
- * Makefile.am (CLEANFILES): add autoconf-macros.texi.
-
-2002-02-19 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-memory.texi (Memory Blocks): New section.
-
-2002-02-05 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am: Include $(top_srcdir)/pre-inst-guile.am.
-
- (GUILE): Delete var.
- (autoconf-macros.texi): Use $(preinstguiletool).
-
-2002-02-04 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * autoconf.texi (Autofrisk, Using Autofrisk): New sections.
- (Autoconf Support): Add new sections to menu.
-
-2002-02-04 Marius Vollmer <marius.vollmer@uni-dortmund.de>
-
- * scheme-data.texi (Symbol Uninterned): Added node.
-
-2002-01-29 Stefan Jahn <stefan@lkcc.org>
-
- * gh.texi (scm transition summary): Documented gh equivalents
- `scm_c_string2str', `scm_c_substring2str' and `scm_c_symbol2str'
- and removed the appropriate FIXME's.
-
-2002-01-14 Marius Vollmer <marius.vollmer@uni-dortmund.de>
-
- * Makefile.am (autoconf-macros.texi): Also set GUILE_LOAD_PATH
- when invoking the uninstalled guile executable.
-
-2002-01-09 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * Makefile.am (autoconf-macros.texi): Fix build bug:
- Write this file to srcdir. Thanks to I. N. Golubev.
-
-2002-01-08 Gary Houston <ghouston@arglist.com>
-
- * Makefile.am: attempt to use guile from $(top_builddir)/libguile
- when building autoconf-macros.texi. There are still problems with
- modules and running makeinfo when builddir != srcdir.
-
-2002-01-08 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * data-rep.texi, gh.texi, guile.texi, intro.texi,
- misc-modules.texi, new-docstrings.texi, posix.texi, program.texi,
- repl-modules.texi, scheme-binding.texi, scheme-compound.texi,
- scheme-control.texi, scheme-data.texi, scheme-debug.texi,
- scheme-ideas.texi, scheme-io.texi, scheme-memory.texi,
- scheme-modules.texi, scheme-procedures.texi,
- scheme-translation.texi, scheme-utility.texi, scm.texi, slib.texi,
- srfi-modules.texi: Spell check. Thanks to Fabrice Bauzac.
-
-2002-01-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi (Linking Programs With Guile): Fix typo (superfluous
- `do'). Thanks to Fabrice Bauzac.
-
-2002-01-05 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * intro.texi: Spell check. Thanks to Fabrice Bauzac.
-
-2002-01-02 Thien-Thi Nguyen <ttn@giblet.glug.org>
-
- * guile.texi (Part II): Add "Autoconf Support"; include
- autoconf.texi.
-
- * Makefile.am (guile_TEXINFOS): Add autoconf.texi and
- autoconf-macros.texi.
- (autoconf.texi, autoconf-macros.texi): New rules.
-
- * autoconf.texi: New file.
-
-2001-12-22 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scheme-compound.texi (Alist Example): Changed "Bismarck" to
- "Pierre". Thanks to Ron Peterson!
-
-2001-12-22 Neil Jerram <neil@ossau.uklinux.net>
-
- * program.texi (Programming Overview): Chapter renamed from
- `Programming Options'; some new material added.
-
-2001-12-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Guile API): Renamed from `Scheme Primitives' and
- broadened so that this chapter discusses the Guile API as a whole.
-
- * program.texi (Available Functionality): Revise so that text
- reads better.
-
- * guile.texi (Programming Intro): New introductory text.
-
- * scheme-ideas.texi (Definition): Reorder reference bullets in
- ascending page number order.
-
-2001-12-04 Martin Grabmueller <mg@glug.org>
-
- * scheme-procedures.texi (Optional Arguments): Typo fix: wither ->
- either.
-
-2001-12-01 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Hooks): Moved into scheme-utility.texi.
-
- * Makefile.am (guile_TEXINFOS): Added scheme-compound.texi.
-
- * scheme-data.texi (Variables): Node moved to modules chapter.
- (Symbol Read Syntax): New node, with syntax-related material taken
- from old Symbols node.
- (Symbol Primitives): Renamed from `Symbols'.
- (Symbols and Variables): Renamed to `Symbols'.
- (Symbol Props): Renamed from `Symbol Tables'.
- (Symbols): General review, improvements and additional material
- throughout this section.
- (Other Data Types): New material: links to object types documented
- elsewhere. Also renamed node to `Other Types'.
- (Data Types): Split into two: `Simple Data Types' and `Compound
- Data Types'. Introductory blurbs rewritten accordingly.
-
- * guile.texi: Updated Notes comment.
-
- * scheme-data.texi (Rx Interface): Node moved to Guile Modules
- part, as the Rx interface is not core Guile.
-
-2001-11-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (String Miscellanea): Removed, moving doc for
- string-ci->symbol into the node on Symbols.
-
- * Makefile.am (ETAGS_ARGS): Added.
-
- * scheme-data.texi (Symbol Tables): Removed doc for gentemp,
- intern-symbol, string->obarray-symbol, symbol-binding,
- symbol-bound?, symbol-set!, unintern-symbol, symbol-interned?; all
- of which no longer exist.
-
-2001-11-25 Thien-Thi Nguyen <ttn@glug.org>
-
- * posix.texi: Fix spelling. Thanks to Chris Cramer.
- Reword `getpass' intro blurb.
-
-2001-11-23 Neil Jerram <neil@ossau.uklinux.net>
-
- * program.texi (Program Control): Remove spurious placeholder
- text.
-
-2001-11-20 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-options.texi (Install Config):
- Tweak `%load-path' verb to not imply it's a proc.
- Add documentation for `%guile-build-info'.
-
-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
- vector-move-left! and vector-move-right!.
-
-2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
-
- * debugging.texi, deprecated.texi, intro.texi, misc-modules.texi,
- new-docstrings.texi, posix.texi, scheme-binding.texi,
- scheme-control.texi, scheme-data.texi, scheme-debug.texi,
- scheme-evaluation.texi, scheme-io.texi, scheme-memory.texi,
- scheme-modules.texi, scheme-options.texi, scheme-procedures.texi,
- scheme-scheduling.texi, scheme-translation.texi,
- scheme-utility.texi, script-getopt.texi, srfi-modules.texi: Change
- category for "primitive" and "procedure" @deffn's to {Scheme
- Procedure}; add @deffnx lines for {C Function}s; automatic updates
- from libguile docstring changes.
-
- * scheme-memory.texi (Garbage Collection): Removed doc for removed
- `unhash-name'.
-
-2001-11-14 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-procedures.texi: Spell "library" correctly.
-
-2001-11-13 Neil Jerram <neil@ossau.uklinux.net>
-
- * new-docstrings.texi, scheme-data.texi: Merge recent doc
- improvements from stable branch.
-
- * scheme-options.texi: Automatic updates from docstring changes in
- libguile's C source code.
-
-2001-11-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Vtables, Structure Basics): Automatic doc
- updates for struct? and struct-vtable?.
- (String Searching): Add missing "for". Thanks to Scott Lenser.
-
-2001-11-08 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi (Top): Added new chapter `Programming Options'.
-
- * program.texi: New file.
-
- * Makefile.am (guile_TEXINFOS): Added program.texi.
-
-2001-11-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-memory.texi, scheme-io.texi, scheme-debug.texi,
- scheme-data.texi, scheme-binding.texi, posix.texi,
- new-docstrings.texi: Automatic updates from improved libguile
- docstrings.
-
-2001-11-04 Neil Jerram <neil@ossau.uklinux.net>
-
- * preface.texi: Use MANUAL_EDITION variable.
- (Manual Layout): Updated to reflect reorg.
-
- * guile.texi (MANUAL_EDITION): New variable, with value
- incremented from 1.0 to 1.1 to reflect the reorg described here.
- (Top): Use MANUAL_EDITION variable.
-
- * scheme-indices.texi (R5RS Index, Guile Extensions Index): Use
- @unnumbered rather than @chapter for these indices.
-
- * guile.texi (Top): A little top-level reshuffling, with the aims
- that: (1) the `Guile Scheme' (reference) part of the manual
- becomes the `Guile API Reference', and covers both Scheme and C
- interfaces; (2) non-API-reference material such as the `Basic
- Ideas in Scheme' chapter is collected together to form a new part
- `Programming with Guile'. This new part will contain general
- documentation on using and programming Guile in both Scheme and C,
- including - for example - awareness of GC when C programming, how
- to use the snarf macros, how to debug ...
- (Top): Move inclusion of scheme-indices.texi so that all indices
- appear together in the printed manual.
-
- * Makefile.am (guile_TEXINFOS): Removed appendices.texi, added
- debugging.texi.
-
- * appendices.texi: Removed.
-
- * debugging.texi (Debugger User Interface): New file, same as the
- material that used to be in appendices.texi, but now a chapter in
- Part II rather than an appendix.
-
- * appendices.texi (Obtaining and Installing Guile): Moved to
- become a chapter in ...
- * intro.texi: ... Part I: Introduction to Guile.
-
- * scm.texi (I/O Extensions): Moved to become a section of ...
- * scheme-io.texi (Input and Output): ... this chapter.
-
- * scm.texi (Handling Errors): Moved to become a section of ...
- * scheme-control.texi (Control Mechanisms): ... this chapter.
-
-2001-11-06 Thien-Thi Nguyen <ttn@glug.org>
-
- * srfi-modules.texi (SRFI-19, SRFI-19 Constants, SRFI-19 Current
- time and clock resolution, SRFI-19 Time object and accessors,
- SRFI-19 Time comparison procedures, SRFI-19 Time arithmetic
- procedures, SRFI-19 Date object and accessors, SRFI-19
- Time/Date/Julian Day/Modified Julian Day converters, SRFI-19 Date
- to string/string to date converters): New nodes.
- (SRFI Support): Add "SRFI-19" to menu.
-
-2001-11-06 Marius Vollmer <mvo@zagadka.ping.de>
-
- * scripts.texi: Document `--debug' and `--no-debug'.
-
-2001-10-27 Gary Houston <ghouston@arglist.com>
-
- * guile.texi, scsh.texi: removed obsolete guile-scsh material
- and updated links (I don't know if it should remain in the
- main menu. It's like slib I think.)
-
- * minor updates to the slib installation notes.
-
-2001-10-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-evaluation.texi (Fly Evaluation): Removed documentation
- for `read-and-eval!' and `eval2'. (Thanks to Alex Schroeder for
- noticing that they'd disappeared!)
-
-2001-10-05 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-io.texi (Writing): Add entry for `display'.
- Include in R5RS Index. Thanks to Alex Schroeder for suggestion.
-
-2001-09-26 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
-
- * srfi-modules.texi (SRFI-13): Tyop fix.
- (SRFI-13): Changed paragraph about bindings both in the code and
- in SRFI-13.
-
- * misc-modules.texi (Formatted Output): Tyop fix.
- (Formatted Output): Document ~g properly.
-
- Thanks to Alex Schroeder for pointing out the typos and sending
- suggestions.
-
-2001-09-25 Thien-Thi Nguyen <ttn@glug.org>
-
- * scheme-procedures.texi (Syntax Rules): Add `cindex' directive.
- Thanks to suggestion by Alex Schroeder.
-
-2001-08-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi (Top): Group all index nodes together so that
- `Info-index' works more effectively in Info. Thanks to Eric
- Hanchrow for the report and fix.
-
- * scheme-data.texi (Random, String Syntax, String Modification,
- Regular Expressions), scheme-ideas.texi (Definition),
- scheme-modules.texi (Dynamic Linking and Compiled Code Modules),
- scm.texi (Transforming Scheme name to C name, Port
- Implementation): Various typo fixes and clarifications merged from
- the stable CVS branch.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi: Merged wording fixes from stable CVS branch.
-
- * Makefile.am (guile_TEXINFOS): Remove ../AUTHORS.
-
- * guile.texi: Incorporate text previously in separate AUTHORS
- file.
-
-2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
-
- The change log for files in this directory continues backwards
- from 2001-08-27 in ../ChangeLog, as all the Guile documentation
- prior to this date was contained in a single directory.
diff --git a/doc/ref/ChangeLog-guile-doc-ref b/doc/ref/ChangeLog-guile-doc-ref
deleted file mode 100644
index 3d2cc4e09..000000000
--- a/doc/ref/ChangeLog-guile-doc-ref
+++ /dev/null
@@ -1,890 +0,0 @@
-2001-03-09 Neil Jerram <neil@ossau.uklinux.net>
-
- Moving texinfo files from guile-doc/ref into guile-core/doc:
-
- * env.texi, indices.texi, mbapi.texi, mltext.texi, scripts.texi,
- scsh.texi, tcltk.texi, hierarchy.txt, scheme-indices.texi,
- slib.texi, deprecated.texi, scheme-binding.texi, appendices.texi,
- scheme-intro.texi, goops.texi, extend.texi, gh.texi, intro.texi,
- preface.texi, scm.texi, goops-tutorial.texi, hierarchy.eps,
- r4rs.texi, r5rs.texi, texinfo.tex, scheme-reading.texi,
- data-rep.texi, scheme-utility.texi, posix.texi,
- scheme-control.texi, scheme-debug.texi, scheme-evaluation.texi,
- scheme-io.texi, scheme-memory.texi, scheme-modules.texi,
- scheme-options.texi, scheme-procedures.texi,
- scheme-scheduling.texi, scheme-translation.texi, guile.texi,
- scheme-data.texi, scheme-ideas.texi, expect.texi: Removed.
-
-2001-02-28 Gary Houston <ghouston@arglist.com>
-
- * expect.texi (Expect): add missing eof? argument in example code.
-
-2001-02-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi, scheme-data.texi, scheme-ideas.texi: Remove the code
- that set paragraph indent to zero, then add @noindent to several
- places that need not to be indented.
-
-2001-02-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (File System, Time), scheme-control.texi
- (Exceptions), scheme-data.texi (Complex, Primitive Numerics,
- Random, String Fun, Symbols and Variables, Lists, Bit Vectors,
- Hooks), scheme-debug.texi (Debugging), scheme-evaluation.texi
- (Reader Extensions, Scheme Read, Fly Evaluation, Loading,
- Evaluator Options), scheme-io.texi (Reading, Writing, Default
- Ports, File Ports), scheme-memory.texi (Garbage Collection,
- Guardians, Objects), scheme-modules.texi (The Guile module
- system), scheme-options.texi (Install Config),
- scheme-procedures.texi (Procedure Properties, Procedures with
- Setters), scheme-scheduling.texi (Arbiters, Asyncs),
- scheme-translation.texi (Emacs Lisp Support): Automatic docstring
- updates.
-
- * scheme-io.texi (Binary IO): New node.
-
- * scheme-control.texi (Multiple Values): New node.
-
-2001-02-23 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-utility.texi (Sorting), scheme-procedures.texi (Procedure
- Properties), scheme-memory.texi (Guardians), scheme-io.texi
- (Line/Delimited), scheme-data.texi (String Fun, Symbols and
- Variables, Vtables), posix.texi (Ports and File Descriptors, File
- System, Network Sockets and Communication): Automatic docstring
- updates.
-
-2001-02-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * data-rep.texi: Preserve, in comments beginning `@c essay',
- material from the standalone version of this essay which is very
- soon to be retired from its current location at
- guile-core/doc/data-rep.texi.
-
- * data-rep.texi: Incorporate recent changes to smob example
- documentation from the standalone version of this essay.
-
-2001-02-02 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-reading.texi (Further Reading): Add reference to online
- version of SICP.
-
-2001-01-27 Neil Jerram <neil@ossau.uklinux.net>
-
- Further changes to get everything to build to dvi with the latest
- texinfo.tex.
-
- * texinfo.tex: Replaced by latest version from ftp.gnu.org.
-
- * r5rs.texi (Binding constructs): Remove @c inside @t{...} at
- lines 2207-2209.
- (Lexical structure): Remove @c inside @t{...} at line 7517.
-
- * r4rs.texi (Example): Remove @c inside @t{...} at lines 6557 and
- 6569.
-
-2001-01-26 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Handling Errors): Improved markup.
- (snarfing): Deleted.
-
- * data-rep.texi: File copied here from sources directory and
- integrated into the reference manual structure.
-
- * extend.texi (Libguile Intro): New file, new node, to introduce
- new Part.
-
- * guile.texi: Merged Parts V and VI into a single Part: "Extending
- Applications Using Guile". Improved some top level node names and
- descriptions. Include extend.texi and data-rep.texi.
-
- * preface.texi (Manual Layout): Updated according to merge of
- Parts V and VI.
-
- * gh.texi: Restructured into a single chapter.
-
- * scm.texi (C Port Interface, Port Implementation): Moved here
- from scheme-io.texi.
-
- * scheme-io.texi (Default Ports): Renamed from `Port
- Environment'.
- (Port Internals): Contents moved to scm.texi.
-
- * r5rs.texi: Changes to allow building of r5rs.dvi from r5rs.texi.
- Aubrey Jaffer's view - which I agree with - is that, given that
- people have the option of building r5rs.dvi from the original
- LaTeX distribution for R5RS, it is not worth fixing his master
- copy of r5rs.texi and the tool which autogenerates it. On the
- other hand, it is a marginal convenience for people to be able to
- build hardcopy from r5rs.texi, even if the results are less good
- than with the original LaTeX. Hence the following fixes.
- (lines 714, 725, 728, 1614, 2258): Remove invalid parentheses from
- @deffn statements.
- (line 2316): Change @deffnx to @deffn, and insert `@end deffn' to
- terminate preceding @deffn.
- (line 7320): Insert `@c ' at beginning of lines that are intended
- to be @ignore'd.
-
- * guile.texi, r4rs.texi, r5rs.texi: Align @direntry descriptions
- to start in column 32.
-
-2001-01-24 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi: Licensing and Layout material moved to
- preface.texi.
- (Whirlwind Tour): New chapter as top level for preexisting
- sections.
-
- * guile.texi: Various minor changes to improve the structure at
- the beginning of the reference manual.
-
- * preface.texi: New file, to split out "prefatory material".
- Initially with Licensing and Layout material taken from
- intro.texi.
-
- * Makefile.am (dist_texis): Add preface.texi.
-
-2001-01-19 Neil Jerram <neil@ossau.uklinux.net>
-
- * intro.texi: Change R4RS everywhere to R5RS.
- (What is Guile?): Change "compiling" to "translating".
-
-2001-01-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * appendices.texi (Internals): Content merged into Symbols and
- Variables node of scheme-data.texi.
- (Reporting Bugs): Moved to manual Part I.
-
- * guile.texi: Inserted new Part for `Guile Modules' as distinct
- from core Guile Scheme language/features. Other parts renumbered
- correspondingly. Module chapters moved into new part.
-
- * intro.texi (Reporting Bugs): Node moved here from
- appendices.texi.
-
- * posix.texi (POSIX): Node name changed from `POSIX System Calls
- and Networking'.
-
- * scheme-data.texi (Symbols and Variables): Added texinfo markup
- to docstrings that didn't have it. Expanded snarfed argument
- names like `o' and `s' to `obarray' and `string'.
-
- * scheme-debug.texi (Debugging): Node name changed from `Internal
- Debugging Interface'.
-
- * scheme-evaluation.texi (Fly Evaluation): Moved doc for
- `interaction-environment' here (previously under module doc).
-
- * scheme-memory.texi: Structure reorganization.
-
- * scheme-modules.texi: Structure reorganization. Removed empty
- subsections `First-class Variables' and `First-class Modules'.
-
- * scheme-options.texi (Options and Config): Node name changed from
- `Options'.
- (Install Config) Node name changed from `Configuration Data'.
-
- * scheme-scheduling.texi (Scheduling): Node name changed from
- `Threads and Dynamic Roots'.
-
- * scheme-translation.texi (Translation): New top level node for
- translation documentation.
-
-2001-01-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-exceptions.texi: Removed.
-
- * Makefile.am (dist_texis): Removed scheme-exceptions.texi.
-
- * guile.texi (Top): Renamed/redescribed some top level nodes. No
- longer include scheme-exceptions.texi.
-
- * scheme-control.texi: Merge material that was previously in
- scheme-exceptions.texi.
-
- * posix.texi: Updated close-port reference.
-
- * scheme-binding.texi, scheme-control.texi,
- scheme-evaluation.texi, scheme-intro.texi, scheme-io.texi,
- scheme-procedures.texi, scheme-utility.texi: Massaged into desired
- structure.
-
- * scheme-data.texi (Generic Data Types): Changed to "Data Types".
- (Numbers) Introduction streamlined.
- (Complex Numbers) New material.
-
-2001-01-05 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi, scheme-io.texi, scheme-memory.texi,
- scheme-options.texi: Where a single docstring documents more than
- one primitive, add a docstring comment for each additionally
- documented primitive.
-
- * scheme-modules.texi: Update docstring for dynamic-func.
-
- * scheme-data.texi (Numbers, Numerical Tower, Integers, Reals and
- Rationals, Number Syntax): New material.
-
- * deprecated.texi (Deprecated): Remove obsolete MD5 comment line.
-
-2000-12-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Numbers): Documentation added for scientific
- functions.
-
- * Makefile.am (dist_texis): Updated following split of scheme.texi
- into per-chapter files.
-
-2000-12-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Booleans): Written.
- (Numbers): Introduction written, primitives organized into
- subsections.
-
-2000-12-06 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi (Generic Data Types): Added chapter
- introduction.
- (Bitwise Operations, Random): Moved underneath Numbers.
- (Other Data Types): New placeholder section for data types that
- are documented elsewhere.
-
- * scheme-indices.texi, scheme-reading.texi: Added Local Variables
- block.
-
-2000-12-06 Neil Jerram <neil@ossau.uklinux.net>
-
- This change replaces scheme.texi, which is unmanageably large, by
- a set of smaller one-per-chapter files. The set and ordering of
- the new files reflects the intended top level structure of the
- Guile Scheme part of the reference manual. This structure is not
- yet all reflected in the combined Texinfo/Info, though, because I
- haven't yet fixed the @node levels appropriately.
-
- * scheme.texi: Removed, after dividing content into new files.
-
- * scheme-procedures.texi, scheme-utility.texi,
- scheme-binding.texi, scheme-control.texi, scheme-io.texi,
- scheme-evaluation.texi, scheme-exceptions.texi,
- scheme-memory.texi, scheme-modules.texi, scheme-scheduling.texi,
- scheme-options.texi, scheme-translation.texi, scheme-debug.texi,
- slib.texi: New files.
-
- * guile.texi: @include new files instead of scheme.texi. Reorder
- existing top level nodes.
-
-2000-12-01 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-data.texi: Remove @page breaks (following demotion).
-
- * guile.texi (Top), scheme-ideas.texi: Demote everything one level
- so that previous chapters About Data, About Procedures, About
- Expressions and About Closure are now combined into a single
- Scheme Ideas chapter. Add overall chapter introduction. Fix up
- top level nodes accordingly.
-
- * guile.texi (Top), scheme.texi, scheme-data.texi: Gather material
- for Generic Data Types chapter into a new file
- (scheme-data.texi). @include new file in guile.texi. Fix up top
- level nodes accordingly. (This changes demotes all the affected
- material by one level, except for that which was already grouped
- together under the Data Structures node.)
-
- * guile.texi (Top): @include new files.
-
- * scheme-intro.texi, scheme-ideas.texi: New files.
-
- * scheme.texi (Guile and R5RS Scheme): Moved introductory chapter
- to its own file (scheme-intro.texi).
- (About Closure) Chapter completed.
- (About Data, About Procedures, About Expressions, About Closure):
- Ideas chapters moved to their own file (scheme-ideas.texi);
- scheme.texi was just getting too large!
-
-2000-11-09 Gary Houston <ghouston@arglist.com>
-
- * posix.texi (Ports and File Descriptors): updated
- close-all-ports-except.
-
-2000-11-07 Gary Houston <ghouston@arglist.com>
-
- * posix.texi (Ports and File Descriptors): added dup2, close-fdes
- and port-for-each.
- (Pipes): synchronise open-input-pipe, open-output-pipe with
- popen.scm.
-
-2000-11-04 Gary Houston <ghouston@arglist.com>
-
- * scheme.texi (Generic Port Operations): "port?" added.
-
-2000-11-03 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (About Expressions): New material about evaluation
- and program execution.
-
- * scheme.texi (About Procedures): Minor textual improvements.
-
-2000-10-29 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (About Expressions, About Closure): Placeholder
- structure for remaining introductory Scheme material.
-
- * guile.texi (Top): Shorten some menu item lines to fit on a
- single console line.
-
-2000-10-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme-indices.texi (R5RS Index, Guile Extensions Index): Print
- new indices.
-
- * guile.texi: Define new R5RS and Guile extension indices.
-
-2000-10-27 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (Guile and R5RS Scheme): Filled in examples of Guile
- extensions.
- (About Procedures): New introductory material.
-
- * scheme-reading.texi: New file.
-
- * scheme-indices.texi: New file.
-
- * intro.texi (Scripting Examples): Added @* to fix TeX overfull
- hboxes (twice).
- (end of file): Added Local Variables block for TeX-master
- variable.
-
- * scheme.texi (R4RS Scheme): Node changed to "Guile and R5RS
- Scheme". Content changed to indicate that we plan to document
- both standard Scheme and Guile extensions.
- (About Data, About Procedures, About Expressions): New Scheme
- introductory material chapters.
- (Options): Moved material on Options into its own chapter.
- (Coding With Keywords): New subsection; extends material on use of
- keywords to include examples of and references to (ice-9 optargs).
- (passim): Change many uses of @example to @lisp, since the
- formatting seems to come out better in TeX.
- (Optional Arguments): New placeholder chapter (empty).
- (end of file): Added Local Variables block for TeX-master
- variable.
-
- * guile.texi (Top): "R4RS Scheme" node changed to "Guile and R5RS
- Scheme". Added Scheme introductory chapters: About Data, About
- Procedures and About Expressions. New Options chapter for options
- material. New Optional Arguments chapter as placeholder for
- (ice-9 optargs) material. New chapter for "Further Reading". New
- chapters for indices showing what is standard Scheme and what is
- Guile extension.
-
-2000-10-25 Mikael Djurfeldt <mdj@linnaeus.mit.edu>
-
- * Makefile.am: Added goops.texi and new files to dist_texis.
-
- * goops.texi, goops-tutorial.texi, hierarchy.eps, hierarchy.txt:
- New files.
-
-2000-10-15 Neil Jerram <neil@ossau.uklinux.net>
-
- * gh.texi (Starting and controlling the interpreter): Removed
- obsolete note about boot-9.scm not being loaded by gh_enter.
- (Thanks to Chris Cramer for pointing this out.)
-
-2000-10-06 Neil Jerram <neil@ossau.uklinux.net>
-
- * guile.texi, scheme.texi, posix.texi: Simplified docstring
- comments: (i) they new refer to the Texinfo-format file that is
- generated by snarfing when libguile is built, rather than to
- individual C files in the libguile source; (ii) there is no longer
- a need to keep MD5 digest values for the corresponding source
- docstring, since I'm now using a different mechanism for keeping
- track of source material changes.
-
- * scheme.texi (Lists): Use "@example" in docstring for append.
-
- * guile.texi, scheme.texi (Primitive Properties): New chapter,
- documenting new primitive property primitives.
-
-2000-09-22 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (I/O internals): Add full stops (periods) after
- standalone uses of @xref.
-
- * scheme.texi (Structure Layout): Doc for make-struct-layout
- changed to remove reference to "read-only" strings, which no
- longer exist.
- (Structure Basics): Use @pxref rather than @xref for parenthetical
- reference.
- (Dynamic Roots): Use @code rather than @var for code, in doc for
- call-with-dynamic-root.
- (Low level thread primitives): Ditto call-with-new-thread.
- (Higher level thread procedures): Ditto call-with-new-thread.
- (Symbols and Variables): Docs for gensym and symbol-hash updated
- according to libguile changes.
-
- * posix.texi (Generic Port Operations): Synchronized docstring
- for unread-string.
-
- * gh.texi (Defining new Scheme procedures in C): Avoid texinfo
- warning by using @code rather than @var for code.
-
- * scheme.texi: Lots more docstring comments added, and docs
- synchronized with libguile source.
- (interaction-environment, make-struct, make-vtable-vtable): Newer,
- better doc taken from source file.
- (cons-source): New docstring written.
- (Vectors): New section added.
- (Random, Symbols and Variables): New chapters.
-
- * posix.texi: Lots more docstring comments added.
- (pipe, tzset) Newer, better documentation taken from source file.
-
- * deprecated.texi: New file, for documenting features that are
- deprecated and so planned to disappear.
-
- * guile.texi (Procedures, Reading and Writing, Random, Sorting,
- Symbols and Variables, Deprecated): New chapters in the Scheme
- part of the reference manual, to hold docstrings that don't
- currently fit anywhere else.
-
-2000-08-28 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Pipes): open-pipe and close-pipe are procedures (in
- ice-9/popen.scm), not primitives.
-
- * scheme.texi (Generic Port Operations): Remove doc for
- port-revealed and set-port-revealed!, since these are covered in
- posix.texi.
-
- * posix.texi: Inserted docstring synchronization comments and
- synchronized docstrings for all primitives defined in posix.c,
- simpos.c, scmsigs.c, stime.c.
- (Ports and File Descriptors) Similarly synchronized port-revealed
- and set-port-revealed!.
-
-2000-08-25 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi: Lots more docstrings added.
-
- * guile.texi (Top): More new chapters: Pairs, Objects, Guardians,
- Emacs Lisp Support.
-
- * scheme.texi (Numbers): New chapter containing docs (many still
- empty right now) for numerical primitives.
-
- * guile.texi (Top): Add chapter for numerical primitives.
-
-2000-08-18 Neil Jerram <neil@ossau.uklinux.net>
-
- * posix.texi (Ports and File Descriptors): Docstring for select
- substantially changed by update from libguile source.
-
- * scheme.texi, posix.texi: Lots more primitive docstrings added.
-
- * guile.texi (Top): Removed empty Reflection chapter, added new
- Hooks chapter.
-
- * scheme.texi: Added docstrings for all Guile primitives from
- libguile files from arbiters.c to error.c.
- (Reflection): Empty chapter removed.
-
- * guile.texi (Top): New chapters "Booleans" and "Equality"
- (temporary - until we improve the overall organization).
-
- * scheme.texi (Uniform Arrays): Fix "indentical" typo.
-
-2000-08-12 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi: Removed superfluous "@c docstring end" markers -
- docstring.el now uses "@end deffn" to find the end of the
- docstring.
- Added a lot more docstring comments, and synced up docstrings with
- libguile - all libguile primitives documented in scheme.texi now
- have docstring comments and are up to date.
- (Evaluation): Updated docstring for eval and eval-string (now
- R5RS-compliant).
-
- * intro.texi (Guile Scripts): Added a couple of blank lines.
-
-2000-08-11 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi: Add docstring comments and sync up existing
- docstrings with libguile source - complete as far as Association
- Lists.
- (Keywords): Fill out and improve documentation about
- keywords.
-
- * guile.texi: Set paragraph indent to zero.
-
-2000-08-07 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (libguile error handling): Add note (text supplied by
- Gary Houston) giving a pointer on how to do C exception handling
- since scm_error_callback was removed.
-
-2000-08-01 Dirk Herrmann <D.Herrmann@tu-bs.de>
-
- * scm.texi (libguile error handling): Removed reference to
- scm_error_callback, which is not available any more since
- guile-1.3. Thanks to Juli-Manel Merino Vidal and to Gary Houston
- for pointing this out.
-
-2000-07-31 Neil Jerram <neil@ossau.uklinux.net>
-
- * scm.texi (Relationship between Scheme and C functions):
- Expand. (Contributed by Thien-Thi Nguyen <ttn@gnu.org>.)
-
-2000-07-30 Neil Jerram <neil@ossau.uklinux.net>
-
- * scheme.texi (Association Lists): New, more complete
- documentation.
- * guile.texi: New top-level manual file based on guile-ref.texi
- but modified to reflect the better organization suggested in
- sources/jimb-org.texi.
- * expect.texi: New file to separate out Expect doc.
- * indices.texi: New file to separate indices from appendices.
- * intro.texi: Invoking Guile and Meta Switch nodes moved to Guile
- Scripting part (scripts.texi). Manual layout node moved to end of
- introduction.
- * posix.texi: All nodes downgraded one level. Expect, SCSH and
- Tcl/Tk nodes moved to dedicated files.
- * scheme.texi: Stuff moved around in accordance with
- sources/jimb-org.texi reorganization (cvs diff totally confused,
- I'm afraid).
- * scsh.texi: New file to separate out SCSH doc.
- * scripts.texi: New file to separate out Guile scripting doc.
- * tcltk.texi: New file to separate out Tcl/Tk interface doc.
- * Makefile.am: Changed guile-ref to guile; more distribution
- texis.
- * Makefile.in: Changed guile-ref to guile; more distribution
- texis.
-
-
-2000-05-14 Marius Vollmer <mvo@zagadka.ping.de>
-
- * posix.texi (Conventions): Added example on how to retrieve errno
- value from a system-exception. Thanks to Eric Hanchrow!
-
-2000-05-04 Marius Vollmer <mvo@zagadka.ping.de>
-
- * intro.texi: Added chapter about Guile's license.
- * guile-ref.texi: Updated menu.
-
-1999-12-15 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (SLIB installation): new node.
-
-1999-12-06 Gary Houston <ghouston@freewire.co.uk>
-
- * r4rs.texi: tweaked the dircategory/direntry for compatibility
- with the r5 version.
- guile-ref.texi: tweaked the dircategory.
- * Makefile.am (info_TEXINFOS): add r5rs.texi.
- * r5rs.texi: new file, lifted from Aubrey Jaffer's site.
-
-1999-12-04 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (Generic Port Operations): add "port-closed?".
-
-1999-11-22 Jim Blandy <jimb@savonarola.red-bean.com>
-
- * mbapi.texi: Don't promise any behavior on ill-formed text.
-
-1999-11-19 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi: rewrote the intros in the array nodes.
-
-1999-11-18 Gary Houston <ghouston@freewire.co.uk>
-
- * posix.texi (Network Sockets and Communication): add htons etc.
- (Ports and File Descriptors, Network Sockets and Communication):
- suggest setvbuf instead of duplicate-port for converting
- unbuffered ports to buffered.
-
- * scheme.texi (Uniform Array): add missing array types to the
- table.
-
-1999-11-17 Gary Houston <ghouston@freewire.co.uk>
-
- * posix.texi (Network Databases): updated.
-
-1999-10-24 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (String Ports): add with-output-to-string and
- with-input-from-string.
- (Port Implementation): update for ptob seek.
-
-1999-10-18 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi (C Port Interface): update the description of
- the rw_random port flag.
-
-1999-09-22 Gary Houston <ghouston@freewire.co.uk>
-
- * scheme.texi: added a bit of documentation for port internals.
-
-1999-09-12 Gary Houston <ghouston@easynet.co.uk>
-
- * posix.texi (File System): make that "directory-stream?".
-
-1999-09-11 Gary Houston <ghouston@easynet.co.uk>
-
- * posix.texi (File System): added "directory?".
-
-1999-09-06 James Blandy <jimb@mule.m17n.org>
-
- * mbapi.texi, mltext.texi: New files, describing interfaces for
- dealing with multilingual code.
-
-1999-07-25 Gary Houston <ghouston@easynet.co.uk>
-
- * scheme.texi, posix.texi: updated for changes in the I/O system
- and expect macros.
-
-1999-01-25 Mark Galassi <rosalia@cygnus.com>
-
- * scheme.texi (General option interface): applied a typo fix.
- Thanks to Eric Hanchrow (offby1@blarg.net).
-
-1998-11-01 Mark Galassi <rosalia@cygnus.com>
-
- * scheme.texi (Weak References): incorporated David Lutterkort's
- chapter on Weak References, which is based on Mikael's email
- message exchange with with Michael Livshin.
-
-1998-10-29 Jim Blandy <jimb@zwingli.cygnus.com>
-
- * scheme.texi: Corrected shell commands in example. (Thanks to
- Chris Bitmead.)
-
-1998-10-25 Mikael Djurfeldt <mdj@barbara.nada.kth.se>
-
- * gh.texi (C to Scheme, Scheme to C): Completed entries about
- vector conversions.
-
-1998-08-26 Mark Galassi <rosalia@cygnus.com>
-
- * gh.texi (Starting and controlling the interpreter): modified the
- gh_enter() docs in response to some good comments from Dirk
- Herrmann: now they address the issue of loading ice-9/boot-9.scm,
- and include Dirk's hackaround for the problem until we fix it
- properly.
-
-1998-04-29 Mark Galassi <rosalia@cygnus.com>
-
- * scheme.texi (Dynamic Linking from Marius): added Marius's new
- chapter on dynamic linking; there is still a section in dynamic
- linking (written by Tim maybe?), and I have to examine how to
- resolve that.
-
-1998-03-30 Mikael Djurfeldt <mdj@nada.kth.se>
-
- * scheme.texi (Port Operations): Changed entry for port-column and
- port-line. (Thanks to Per Bothner.)
-
-1998-02-02 Mikael Djurfeldt <mdj@mdj.nada.kth.se>
-
- * scheme.texi (Exceptions): Adjusted documentation to reflect the
- removal of the (catch #f ...) mechanism.
-
-1998-01-28 Mark Galassi <rosalia@nis.lanl.gov>
-
- * guile-ref.texi: changed @dircategory to "Scheme Programming".
- It seems to be the consensus.
-
-1998-01-20 Mikael Djurfeldt <mdj@mdj.nada.kth.se>
-
- * gh.texi (C to Scheme): Added documentation for gh_doubles2scm
- and gh_doubles2dvect.
- (Scheme to C): Added documentation for gh_scm2doubles.
-
-1998-01-15 Mark Galassi <rosalia@nis.lanl.gov>
-
- * gh.texi (Calling Scheme procedures from C): removed
- gh_make_subr() since Mikael pointed out that it is gone from
- Guile. I don't remember its history any more, but I don't think
- anyone is missing it.
-
-1998-01-03 Tim Pierce <twp@skepsis.com>
-
- * scheme.texi (Evaluation): Several corrections supplied by MDJ.
-
-Sat Dec 27 19:02:36 1997 Tim Pierce <twp@skepsis.com>
-
- * appendices.texi (Internals, Symbols): New nodes.
- * scheme.texi (Configuration Data): New node.
-
-1997-12-27 Tim Pierce <twp@skepsis.com>
-
- * guile-ref.texi (Bitwise Operations): New description.
-
-1997-12-24 Tim Pierce <twp@skepsis.com>
-
- * scheme.texi (Port Operations, Evaluation): New nodes.
-
-1997-12-13 Tim Pierce <twp@skepsis.com>
-
- * scheme.texi, posix.texi: Documented each procedure as `procedure',
- `primitive' or `syntax' as appropriate.
- (Records): Change record-type-field-names to record-type-fields.
- (Low level thread primitives): Change with-new-thread to
- call-with-new-thread.
-
-Sun Dec 7 22:47:22 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * posix.texi (Processes): add "system" procedure.
-
-1997-11-23 Mark Galassi <rosalia@cygnus.com>
-
- * gh.texi (Starting and controlling the interpreter): added
- documentation for gh_repl() -- gh_repl() has changed since I saw
- the scm_shell() routine.
-
-1997-11-19 Tim Pierce <twp@twp.tezcat.com>
-
- * scheme.texi (String Fun): New node.
- (Hash Tables): Added `get-handle' and `create-handle!' docs.
-
- * posix.texi (Networking Databases): Add docs for gethost, getnet,
- getserv, getproto. Expanded on miscellaneous docs.
-
-1997-11-18 Tim Pierce <twp@twp.tezcat.com>
-
- * posix.texi: New file; moved docs for POSIX interface here.
- * Makefile.am: Add posix.texi.
- * Makefile.in: Regenerated.
- * guile-ref.texi: Reorganize top-level menu. @include posix.texi.
- * scheme.texi: Moved many nodes around, some restructuring
- (e.g. new "Data Structures" node for records, structures, arrays,
- hash tables, and so on).
-
-1997-10-19 Mark Galassi <rosalia@cygnus.com>
-
- * gh.texi (Calling Scheme procedures from C): added many routines
- as I go through R4RS and try to complete the gh_ interface.
-
-Wed Oct 8 04:51:54 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (Dynamic Roots): added batch mode procedures.
-
-1997-10-03 Mikael Djurfeldt <mdj@nada.kth.se>
-
- * scheme.texi (Vtables): Changed 0 --> @code{vtable-index-layout};
- Changed @code{struct-vtable-offset} --> @code{vtable-offset-user};
- Added short note about the print call-back initializer. (This
- section is in need of review. However, we shoudn't spend much
- time on it since the structs will be replaced by something
- equivalent, but with a different interface.}
-
-Sun Sep 28 00:02:35 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (Keywords): very small re-organization to take
- advantage of the fact that read-options is now documented in
- another chapter.
-
-Thu Sep 25 23:37:02 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (Guile options interface): renamed the symbol case
- section to "Guile options interface". "Reader options" is now a
- subsection of that. I've finally figured a lot of how options
- work, thanks to discovering Mikael's comments in options.c and an
- old note from Mikael to Jim describing it.
- (Guile options interface): reorganized the individual option
- groups. This section (on options) of the manual is now reasonably
- complete, unless I am completely missing something.
-
-Wed Sep 24 15:25:03 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (The Guile module system): Added a bit more to this
- chapter, mostly the more user-friendly (use-modules (ice-9
- module-name)) approach.
- (Symbol case): tried to write something about this, but it will
- need to be reviewed by someone who understands the big picture of
- read options. I also think the section name should be changed to
- something like "Read options".
-
-Sun Sep 21 18:45:57 1997 Mark Galassi <rosalia@nis.lanl.gov>
-
- * scheme.texi (SLIB): some little details, including splitting off
- what does in the installation chapter. Also added a section on
- Jacal, which has some open issues.
-
- * appendices.texi (Packages not shipped with Guile): added this
- section to describe getting resources on SCSH, SLIB and Jacal (and
- who knows what else in the future).
-
-Sat Aug 30 19:31:22 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (Uniform Array): mention start and end arguments
- for uniform-array-read! and uniform-array-write.
-
-Sat Aug 23 19:05:08 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * guile-ref.texi (Top): corresponding changes.
- * scheme.texi (Exception Handling): add scm-error, strerror.
- (Exceptions): renamed from Exception Handling.
- (Exceptions): deleted empty section.
-
-Mon Aug 18 16:11:43 1997 Jim Blandy <jimb@totoro.red-bean.com>
-
- * texinfo.tex: Installed from texinfo release 3.11.
-
-Fri Aug 15 08:14:32 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (file system): added truncate-file.
- chown, fcntl, fseek, ftell updated.
- (ports vs file descriptors): added fsync, open, open-fdes.
- (time): added times.
-
-Sun Aug 10 07:39:55 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (processes): added execle.
-
-Tue Jul 29 02:01:21 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * setvbuf added. primitive-dup[2] removed.
-
-Sat Jul 26 04:25:40 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * various close and dup procedures added, plus setenv.
-
-Sat Jul 19 04:04:50 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (signals): new section.
- (processes): primitive-exit.
- (ports vs. file descriptors): force-output, flush-all-ports.
- fcntl from NEWS.
-
-Fri Jul 18 07:58:52 1997 Gary Houston <ghouston@actrix.gen.nz>
-
- * scheme.texi (SLIB): update initialization details.
- (expect): likewise.
- (The Scheme shell (scsh)): likewise.
-
-Fri Jun 27 00:31:25 1997 Tim Pierce <twp@twp.tezcat.com>
-
- * scheme.texi (Regexp Functions): Add docs for make-regexp flags
- regexp/icase, regexp/newline, regexp/basic, regexp/extended.
-
-Mon Jun 23 12:35:57 1997 Tim Pierce <twpierce@bio-5.bsd.uchicago.edu>
-
- * appendices.texi (debugger user interface): new text.
- (Single-Step, Trace, Backtrace): new nodes.
-
- * scheme.texi: Many revised nodes, some new ones.
-
- (Binary Numeric Operations, Input/Output Ports, File Ports, Soft
- Ports, String Ports): Imported documentation from SCM and SLIB manuals.
-
- (Association Lists and Hash Tables, Dictionary Types, Association
- Lists, Hash Tables): New nodes.
- (Dictionaries in general): Removed.
-
- (Regular Expressions): Replaced.
- (Rx Interface): New node, renamed from old `Regular Expressions'.
- (Regexp Functions, Match Functions, Backslash Escapes): new nodes.
-
- (Property Lists): new node with documentation for both object and
- procedure properties.
- (Object Properties): removed.
- * guile-ref.texi: change `Object Properties' to `Property Lists'.
-
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
deleted file mode 100644
index 584bd8229..000000000
--- a/doc/ref/Makefile.am
+++ /dev/null
@@ -1,62 +0,0 @@
-## Process this file with Automake to create Makefile.in
-##
-## Copyright (C) 1998 Free Software Foundation, Inc.
-##
-## This file is part of GUILE.
-##
-## GUILE is free software; you can redistribute it and/or modify
-## it under the terms of the GNU General Public License as
-## published by the Free Software Foundation; either version 2, or
-## (at your option) any later version.
-##
-## GUILE is distributed in the hope that it will be useful, but
-## WITHOUT ANY WARRANTY; without even the implied warranty of
-## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-## GNU General Public License for more details.
-##
-## You should have received a copy of the GNU General Public
-## License along with GUILE; see the file COPYING. If not, write
-## to the Free Software Foundation, Inc., 59 Temple Place, Suite
-## 330, Boston, MA 02111-1307 USA
-
-AUTOMAKE_OPTIONS = gnu
-
-info_TEXINFOS = guile.texi
-
-guile_TEXINFOS = preface.texi intro.texi program.texi scheme-intro.texi \
- scheme-ideas.texi scheme-data.texi scheme-procedures.texi \
- scheme-utility.texi scheme-binding.texi scheme-control.texi \
- scheme-io.texi scheme-evaluation.texi scheme-memory.texi \
- scheme-modules.texi scheme-scheduling.texi scheme-options.texi \
- scheme-translation.texi scheme-debug.texi deprecated.texi \
- scheme-reading.texi scheme-indices.texi slib.texi posix.texi \
- expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.texi \
- debugging.texi indices.texi script-getopt.texi data-rep.texi \
- extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi \
- scheme-compound.texi autoconf.texi autoconf-macros.texi tools.texi
-
-ETAGS_ARGS = $(info_TEXINFOS) $(guile_TEXINFOS)
-
-include $(top_srcdir)/am/pre-inst-guile
-
-# Automated snarfing
-
-autoconf.texi: autoconf-macros.texi
-autoconf-macros.texi: $(top_srcdir)/guile-config/guile.m4
- $(preinstguiletool)/snarf-guile-m4-docs $< > $(srcdir)/$@
-
-# Optionally support building an HTML version of the reference manual.
-
-if HTMLDOC
-
-htmldir = $(prefix)/html/guile-$(VERSION)
-
-html_DATA = guile_toc.html $(shell ls guile_*.html 2>/dev/null)
-
-guile_toc.html: guile.texi $(guile_TEXINFOS)
- $(TEXI2HTML) -split_chapter $(srcdir)/guile.texi
-
-endif
-
-CLEANFILES = autoconf-macros.texi \
- guile.cps guile.fns guile.rns guile.tps guile.vrs guile.tmp
diff --git a/doc/ref/api.txt b/doc/ref/api.txt
deleted file mode 100644
index cc26b839f..000000000
--- a/doc/ref/api.txt
+++ /dev/null
@@ -1,185 +0,0 @@
-Scheme objects
-==============
-
-There are two basic C data types to represent objects in guile:
-
-- SCM: SCM is the user level abstract C type that is used to represent all of
-guile's scheme objects, no matter what the scheme object type is. No C
-operation except assignment is guaranteed to work with variables of type SCM.
-Only use macros and functions to work with SCM values. Values are converted
-between C data types and the SCM type with utility functions and macros.
-
-- scm_bits_t: An integral data type that is guaranteed to be large enough to
-hold all information that is required to represent any scheme object. While
-this data type is used to implement guile internals, the use of this type is
-also necessary to write certain kinds of extensions to guile.
-
-
-Relationship between SCM and scm_bits_t
-=======================================
-
-A variable of type SCM is guaranteed to hold a valid scheme object. A
-variable of type scm_bits_t, however, may either hold a representation of a
-SCM value as a C integral type, but may also hold any C value, even if it does
-not correspond to a valid scheme object.
-
-For a variable x of type SCM, the scheme object's type information is stored
-in a form that is not directly usable. To be able to work on the type
-encoding of the scheme value, the SCM variable has to be transformed into the
-corresponding representation as a scm_bits_t variable y by using the
-SCM_UNPACK macro. After this has been done, the type of the scheme object x
-can be derived from the content of the bits of the scm_bits_t value y, as is
-described in -->data-rep. A valid bit encoding of a scheme value as a
-scm_bits_t variable can be transformed into the corresponding SCM value by
-using the SCM_PACK macro.
-
-- scm_bits_t SCM_UNPACK (SCM x): Transforms the SCM value x into it's
-representation as an integral type. Only after applying SCM_UNPACK it is
-possible to access the bits and contents of the SCM value.
-
-- SCM SCM_PACK (scm_bits_t x): Takes a valid integral representation of a
-scheme object and transforms it into its representation as a SCM value.
-
-
-Immediate objects
-=================
-
-A scheme object may either be an immediate, i. e. carrying all necessary
-information by itself, or it may contain a reference to a 'cell' with
-additional information on the heap. While the fact, whether an object is an
-immediate or not should be irrelevant for user code, within guile's own code
-the distinction is sometimes of importance. Thus, the following low level
-macro is provided:
-
-- int SCM_IMP (SCM x): A scheme object is an immediate if it fullfills the
-SCM_IMP predicate, otherwise it holds an encoded reference to a heap cell.
-The result of the predicate is delivered as a C style boolean value. User
-code and code that extends guile should normally not be required to use this
-macro.
-
-Summary:
-* For a scheme object x of unknown type, check first with SCM_IMP (x) if it is
-an immediate object. If so, all of the type and value information can be
-determined from the scm_bits_t value that is delivered by SCM_UNPACK (x).
-
-
-Non immediate objects
-=====================
-
-- (scm_t_cell *) SCM2PTR (SCM x) (FIXME:: this name should be changed)
-- SCM PTR2SCM (scm_t_cell * x) (FIXME:: this name should be changed)
-
-A scheme object of type SCM that does not fullfill the SCM_IMP predicate holds
-an encoded reference to a heap cell. This reference can be decoded to a C
-pointer to a heap cell using the SCM2PTR macro. The encoding of a pointer to
-a heap cell into a SCM value is done using the PTR2SCM macro.
-
-Note that it is also possible to transform a non immediate SCM value by using
-SCM_UNPACK into a scm_bits_t variable. Hower, the result of SCM_UNPACK may
-not be used as a pointer to a scm_t_cell: Only SCM2PTR is guaranteed to
-transform a SCM object into a valid pointer to a heap cell. Also, it is not
-allowed to apply PTR2SCM to anything that is not a valid pointer to a heap
-cell.
-
-Summary:
-* Only use SCM2PTR for SCM values for which SCM_IMP is false!
-* Don't use '(scm_t_cell*) SCM_UNPACK (x)'! Use 'SCM2PTR (x)' instead!
-* Don't use PTR2SCM for anything but a cell pointer!
-
-
-Heap Cell Type Information
-==========================
-
-Heap cells contain a number of entries, each of which is either a scheme
-object of type SCM or a raw C value of type scm_bits_t. Which of the cell
-entries contain scheme objects and which contain raw C values is determined by
-the first entry of the cell, which holds the cell type information.
-
-- scm_bits_t SCM_CELL_TYPE (SCM x): For a non immediate scheme object x,
-deliver the content of the first entry of the heap cell referenced by x. This
-value holds the information about the cell type as described in -->data-rep.
-
-- void SCM_SET_CELL_TYPE (SCM x, scm_bits_t t): For a non immediate scheme
-object x, write the value t into the first entry of the heap cell referenced
-by x. The value t must hold a valid cell type as described in -->data-rep.
-
-
-Accessing Cell Entries
-======================
-
-For a non immediate scheme object x, the object type can be determined by
-reading the cell type entry using the SCM_CELL_TYPE macro. For the different
-types of cells it is known which cell entry holds scheme objects and which cell
-entry holds raw C data. To access the different cell entries appropriately,
-the following macros are provided:
-
-- scm_bits_t SCM_CELL_WORD (SCM x, unsigned int n): Deliver the cell entry n
-of the heap cell referenced by the non immediate scheme object x as raw data.
-It is illegal, to access cell entries that hold scheme objects by using these
-macros. For convenience, the following macros are also provided:
- SCM_CELL_WORD_0 (x) --> SCM_CELL_WORD (x, 0)
- SCM_CELL_WORD_1 (x) --> SCM_CELL_WORD (x, 1)
- ...
- SCM_CELL_WORD_n (x) --> SCM_CELL_WORD (x, n)
-
-- SCM SCM_CELL_OBJECT (SCM x, unsigned int n): Deliver the cell entry n of
-the heap cell referenced by the non immediate scheme object x as a scheme
-object. It is illegal, to access cell entries that do not hold scheme objects
-by using these macros. For convenience, the following macros are also
-provided:
- SCM_CELL_OBJECT_0 (x) --> SCM_CELL_OBJECT (x, 0)
- SCM_CELL_OBJECT_1 (x) --> SCM_CELL_OBJECT (x, 1)
- ...
- SCM_CELL_OBJECT_n (x) --> SCM_CELL_OBJECT (x, n)
-
-- void SCM_SET_CELL_WORD (SCM x, unsigned int n, scm_bits_t w): Write the raw
-C value w into entry number n of the heap cell referenced by the non immediate
-scheme value x. Values that are written into cells this way may only be read
-from the cells using the SCM_CELL_WORD macros or, in case cell entry 0 is
-written, using the SCM_CELL_TYPE macro. For the special case of cell entry 0
-it has to be made sure that w contains a cell type information (see
--->data-rep) which does not describe a scheme object. For convenience, the
-following macros are also provided:
- SCM_SET_CELL_WORD_0 (x, w) --> SCM_SET_CELL_WORD (x, 0, w)
- SCM_SET_CELL_WORD_1 (x, w) --> SCM_SET_CELL_WORD (x, 1, w)
- ...
- SCM_SET_CELL_WORD_n (x, w) --> SCM_SET_CELL_WORD (x, n, w)
-
-- void SCM_SET_CELL_OBJECT (SCM x, unsigned int n, SCM o): Write the scheme
-object o into entry number n of the heap cell referenced by the non immediate
-scheme value x. Values that are written into cells this way may only be read
-from the cells using the SCM_CELL_OBJECT macros or, in case cell entry 0 is
-written, using the SCM_CELL_TYPE macro. For the special case of cell entry 0
-the writing of a scheme object into this cell is only allowed, if the cell
-forms a scheme pair. For convenience, the following macros are also provided:
- SCM_SET_CELL_OBJECT_0 (x, o) --> SCM_SET_CELL_OBJECT (x, 0, o)
- SCM_SET_CELL_OBJECT_1 (x, o) --> SCM_SET_CELL_OBJECT (x, 1, o)
- ...
- SCM_SET_CELL_OBJECT_n (x, o) --> SCM_SET_CELL_OBJECT (x, n, o)
-
-Summary:
-* For a non immediate scheme object x of unknown type, get the type
- information by using SCM_CELL_TYPE (x).
-* As soon as the cell type information is available, only use the appropriate
- access methods to read and write data to the different cell entries.
-
-
-Basic Rules for Accessing Cell Entries
-======================================
-
-For each cell type it is generally up to the implementation of that type which
-of the corresponding cell entries hold scheme objects and which hold raw C
-values. However, there is one basic rules that has to be followed: Scheme
-pairs consist of exactly two cell entries, which both contain scheme objects.
-Further, a cell which contains a scheme object in it first entry has to be a
-scheme pair. In other words, it is not allowed to store a scheme object in
-the first cell entry and a non scheme object in the second cell entry.
-
-Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
-- int SCM_CONSP (SCM x): Determine, whether the scheme object x is a scheme
-pair, i. e. whether x references a heap cell consisting of exactly two
-entries, where both entries contain a scheme object. In this case, both
-entries will have to be accessed using the SCM_CELL_OBJECT macros. On the
-contrary, if the SCM_CONSP predicate is not fulfilled, the first entry of the
-scheme cell is guaranteed not to be a scheme value and thus the first cell
-entry must be accessed using the SCM_CELL_WORD_0 macro.
diff --git a/doc/ref/autoconf.texi b/doc/ref/autoconf.texi
deleted file mode 100644
index 8d05b2ecc..000000000
--- a/doc/ref/autoconf.texi
+++ /dev/null
@@ -1,234 +0,0 @@
-@page
-@node Autoconf Support
-@chapter Autoconf Support
-
-When Guile is installed, a set of autoconf macros is also installed as
-PREFIX/share/aclocal/guile.m4. This chapter documents the macros provided in
-that file, as well as the high-level guile-tool Autofrisk. @xref{Top,The GNU
-Autoconf Manual,,autoconf}, for more info.
-
-@menu
-* Autoconf Background:: Why use autoconf?
-* Autoconf Macros:: The GUILE_* macros.
-* Using Autoconf Macros:: How to use them, plus examples.
-* Autofrisk:: AUTOFRISK_CHECKS and AUTOFRISK_SUMMARY.
-* Using Autofrisk:: Example modules.af files.
-@end menu
-
-
-@node Autoconf Background
-@section Autoconf Background
-
-As explained elsewhere (@pxref{Top,The GNU Autoconf Manual,,autoconf}), any
-package needs configuration at build-time. If your package uses Guile (or
-uses a package that in turn uses Guile), you probably need to know what
-specific Guile features are available and details about them.
-
-The way to do this is to write feature tests and arrange for their execution
-by the @file{configure} script, typically by adding the tests to
-@file{configure.ac}, and running @code{autoconf} to create @file{configure}.
-Users of your package then run @file{configure} in the normal way.
-
-Macros are a way to make common feature tests easy to express. Autoconf
-provides a wide range of macros (@pxref{Existing Tests,,,autoconf}), and
-Guile installation provides Guile-specific tests in the areas of:
-program detection, compilation flags reporting, and Scheme module
-checks.
-
-
-@node Autoconf Macros
-@section Autoconf Macros
-
-The macro names all begin with "GUILE_".
-
-@c see Makefile.am
-@include autoconf-macros.texi
-
-
-@node Using Autoconf Macros
-@section Using Autoconf Macros
-
-Using the autoconf macros is straightforward: Add the macro "calls" (actually
-instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
-run @code{autoconf}. If your system doesn't have guile.m4 installed, place
-the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
-and @code{aclocal} will do the right thing.
-
-Some of the macros can be used inside normal shell constructs: @code{if foo ;
-then GUILE_BAZ ; fi}, but this is not guaranteed. It's probably a good idea
-to instantiate macros at top-level.
-
-We now include two examples, one simple and one complicated.
-
-The first example is for a package that uses libguile, and thus needs to know
-how to compile and link against it. So we use @code{GUILE_FLAGS} to set the
-vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
-substituted in the Makefile.
-
-@example
-In configure.ac:
-
- GUILE_FLAGS
-
-In Makefile.in:
-
- GUILE_CFLAGS = @@GUILE_CFLAGS@@
- GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
-
- myprog.o: myprog.c
- $(CC) -o $@ $(GUILE_CFLAGS) $<
- myprog: myprog.o
- $(CC) -o $@ $< $(GUILE_LDFLAGS)
-@end example
-
-The second example is for a package of Guile Scheme modules that uses an
-external program and other Guile Scheme modules (some might call this a "pure
-scheme" package). So we use the @code{GUILE_SITE_DIR} macro, a regular
-@code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
-
-@example
-In configure.ac:
-
- GUILE_SITE_DIR
-
- probably_wont_work=""
-
- # pgtype pgtable
- GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
- test $have_guile_pg = no &&
- probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"
-
- # gpgutils
- AC_PATH_PROG(GNUPG,gpg)
- test x"$GNUPG" = x &&
- probably_wont_work="(my gpgutils) $probably_wont_work"
-
- if test ! "$probably_wont_work" = "" ; then
- p=" ***"
- echo
- echo "$p"
- echo "$p NOTE:"
- echo "$p The following modules probably won't work:"
- echo "$p $probably_wont_work"
- echo "$p They can be installed anyway, and will work if their"
- echo "$p dependencies are installed later. Please see README."
- echo "$p"
- echo
- fi
-
-In Makefile.in:
-
- instdir = @@GUILE_SITE@@/my
-
- install:
- $(INSTALL) my/*.scm $(instdir)
-@end example
-
-
-@node Autofrisk
-@section Autofrisk
-
-The @dfn{guile-tools autofrisk} command looks for the file @file{modules.af}
-in the current directory and writes out @file{modules.af.m4} containing
-autoconf definitions for @code{AUTOFRISK_CHECKS} and @code{AUTOFRISK_SUMMARY}.
-@xref{Autoconf Background}, and @xref{Using Autoconf Macros}, for more info.
-
-The modules.af file consists of a series of configuration forms (Scheme
-lists), which have one of the following formats:
-
-@example
- (files-glob PATTERN ...) ;; required
- (non-critical-external MODULE ...) ;; optional
- (non-critical-internal MODULE ...) ;; optional
- (programs (MODULE PROG ...) ...) ;; optional
- (pww-varname VARNAME) ;; optional
-@end example
-
-@var{pattern} is a string that may contain "*" and "?" characters to be
-expanded into filenames. @var{module} is a list of symbols naming a module,
-such as `(srfi srfi-1)'. @var{varname} is a shell-safe name to use instead of
-@code{probably_wont_work}, the default. This var is passed to `AC_SUBST'.
-@var{prog} is a string that names a program, such as "gpg".
-
-Autofrisk expands the @code{files-glob} pattern(s) into a list of files, scans
-each file's module definition form(s), and constructs a module dependency
-graph wherein modules defined by @code{define-module} are considered
-@dfn{internal} and the remaining, @dfn{external}. For each external module
-that has an internal dependency, Autofrisk emits a
-@code{GUILE_MODULE_REQUIRED} check (@pxref{Autoconf Macros}), which altogether
-form the body of @code{AUTOFRISK_CHECKS}.
-
-@code{GUILE_MODULE_REQUIRED} causes the @file{configure} script to exit with
-an error message if the specified module is not available; it enforces a
-strong dependency. You can temper dependency strength by using the
-@code{non-critical-external} and @code{non-critical-internal} configuration
-forms in modules.af. For graph edges that touch such non-critical modules,
-Autofrisk uses @code{GUILE_MODULE_AVAILABLE}, and arranges for
-@code{AUTOFRISK_SUMMARY} to display a warning if they are not found.
-
-The shell code resulting from the expansion of @code{AUTOFRISK_CHECKS} and
-@code{AUTOFRISK_SUMMARY} uses the shell variable @code{probably_wont_work} to
-collect the names of unfound non-critical modules. If this bothers you, use
-configuration form @code{(pww-name foo)} in modules.af.
-
-Although Autofrisk does not detect when a module uses a program (for example,
-in a @code{system} call), it can generate @code{AC_PATH_PROG} forms anyway if
-you use the @code{programs} configuration form in modules.af. These are
-collected into @code{AUTOCONF_CHECKS}.
-
-@xref{Using Autofrisk}, for some modules.af examples.
-
-
-@node Using Autofrisk
-@section Using Autofrisk
-
-Using Autofrisk (@pxref{Autofrisk}) involves writing @file{modules.af} and
-adding two macro calls to @file{configure.in}. Here is an example of the
-latter:
-
-@example
-AUTOFRISK_CHECKS
-AUTOFRISK_SUMMARY
-@end example
-
-Here is an adaptation of the second "GUILE_*" example (@pxref{Using Autoconf
-Macros}) that does basically the same thing.
-
-@example
-(files-glob "my/*.scm")
-(non-critical-external (database postgres))
-(programs ((my gpgutils) "gpg")) ;; (my gpgutils) uses "gpg"
-@end example
-
-If the SRFI modules (@pxref{SRFI Support}) were a separate package, we could
-use @code{guile-tools frisk} to find out its dependencies:
-
-@example
-$ guile-tools frisk srfi/*.scm
-13 files, 18 modules (13 internal, 5 external), 9 edges
-
-x (ice-9 and-let-star)
- regular (srfi srfi-2)
-x (ice-9 syncase)
- regular (srfi srfi-11)
-x (ice-9 rdelim)
- regular (srfi srfi-10)
-x (ice-9 receive)
- regular (srfi srfi-8)
- regular (srfi srfi-1)
-x (ice-9 session)
- regular (srfi srfi-1)
-@end example
-
-Then, we could use the following modules.af to help configure it:
-
-@example
-(files-glob "srfi/*.scm")
-(non-critical-external ;; relatively recent
- (ice-9 rdelim)
- (ice-9 receive)
- (ice-9 and-let-star))
-(pww-varname not_fully_supported)
-@end example
-
-@c autoconf.texi ends here
diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi
deleted file mode 100644
index 30fcee6c6..000000000
--- a/doc/ref/data-rep.texi
+++ /dev/null
@@ -1,2047 +0,0 @@
-@c essay \input texinfo
-@c essay @c -*-texinfo-*-
-@c essay @c %**start of header
-@c essay @setfilename data-rep.info
-@c essay @settitle Data Representation in Guile
-@c essay @c %**end of header
-
-@c essay @include version.texi
-
-@c essay @dircategory The Algorithmic Language Scheme
-@c essay @direntry
-@c essay * data-rep: (data-rep). Data Representation in Guile --- how to use
-@c essay Guile objects in your C code.
-@c essay @end direntry
-
-@c essay @setchapternewpage off
-
-@c essay @ifinfo
-@c essay Data Representation in Guile
-
-@c essay Copyright (C) 1998, 1999, 2000 Free Software Foundation
-
-@c essay Permission is granted to make and distribute verbatim copies of
-@c essay this manual provided the copyright notice and this permission notice
-@c essay are preserved on all copies.
-
-@c essay @ignore
-@c essay Permission is granted to process this file through TeX and print the
-@c essay results, provided the printed document carries copying permission
-@c essay notice identical to this one except for the removal of this paragraph
-@c essay (this paragraph not being relevant to the printed manual).
-@c essay @end ignore
-
-@c essay Permission is granted to copy and distribute modified versions of this
-@c essay manual under the conditions for verbatim copying, provided that the entire
-@c essay resulting derived work is distributed under the terms of a permission
-@c essay notice identical to this one.
-
-@c essay Permission is granted to copy and distribute translations of this manual
-@c essay into another language, under the above conditions for modified versions,
-@c essay except that this permission notice may be stated in a translation approved
-@c essay by the Free Software Foundation.
-@c essay @end ifinfo
-
-@c essay @titlepage
-@c essay @sp 10
-@c essay @comment The title is printed in a large font.
-@c essay @title Data Representation in Guile
-@c essay @subtitle $Id: data-rep.texi,v 1.7 2002-03-29 20:25:23 ossau Exp $
-@c essay @subtitle For use with Guile @value{VERSION}
-@c essay @author Jim Blandy
-@c essay @author Free Software Foundation
-@c essay @author @email{jimb@@red-bean.com}
-@c essay @c The following two commands start the copyright page.
-@c essay @page
-@c essay @vskip 0pt plus 1filll
-@c essay @vskip 0pt plus 1filll
-@c essay Copyright @copyright{} 1998 Free Software Foundation
-
-@c essay Permission is granted to make and distribute verbatim copies of
-@c essay this manual provided the copyright notice and this permission notice
-@c essay are preserved on all copies.
-
-@c essay Permission is granted to copy and distribute modified versions of this
-@c essay manual under the conditions for verbatim copying, provided that the entire
-@c essay resulting derived work is distributed under the terms of a permission
-@c essay notice identical to this one.
-
-@c essay Permission is granted to copy and distribute translations of this manual
-@c essay into another language, under the above conditions for modified versions,
-@c essay except that this permission notice may be stated in a translation approved
-@c essay by Free Software Foundation.
-@c essay @end titlepage
-
-@c essay @c @smallbook
-@c essay @c @finalout
-@c essay @headings double
-
-
-@c essay @node Top, Data Representation in Scheme, (dir), (dir)
-@c essay @top Data Representation in Guile
-
-@c essay @ifinfo
-@c essay This essay is meant to provide the background necessary to read and
-@c essay write C code that manipulates Scheme values in a way that conforms to
-@c essay libguile's interface. If you would like to write or maintain a
-@c essay Guile-based application in C or C++, this is the first information you
-@c essay need.
-
-@c essay In order to make sense of Guile's @code{SCM_} functions, or read
-@c essay libguile's source code, it's essential to have a good grasp of how Guile
-@c essay actually represents Scheme values. Otherwise, a lot of the code, and
-@c essay the conventions it follows, won't make very much sense.
-
-@c essay We assume you know both C and Scheme, but we do not assume you are
-@c essay familiar with Guile's C interface.
-@c essay @end ifinfo
-
-
-@page
-@node Data Representation
-@chapter Data Representation in Guile
-
-@strong{by Jim Blandy}
-
-[Due to the rather non-orthogonal and performance-oriented nature of the
-SCM interface, you need to understand SCM internals *before* you can use
-the SCM API. That's why this chapter comes first.]
-
-[NOTE: this is Jim Blandy's essay almost entirely unmodified. It has to
-be adapted to fit this manual smoothly.]
-
-In order to make sense of Guile's SCM_ functions, or read libguile's
-source code, it's essential to have a good grasp of how Guile actually
-represents Scheme values. Otherwise, a lot of the code, and the
-conventions it follows, won't make very much sense. This essay is meant
-to provide the background necessary to read and write C code that
-manipulates Scheme values in a way that is compatible with libguile.
-
-We assume you know both C and Scheme, but we do not assume you are
-familiar with Guile's implementation.
-
-@menu
-* Data Representation in Scheme:: Why things aren't just totally
- straightforward, in general terms.
-* How Guile does it:: How to write C code that manipulates
- Guile values, with an explanation
- of Guile's garbage collector.
-* Defining New Types (Smobs):: How to extend Guile with your own
- application-specific datatypes.
-@end menu
-
-@node Data Representation in Scheme
-@section Data Representation in Scheme
-
-Scheme is a latently-typed language; this means that the system cannot,
-in general, determine the type of a given expression at compile time.
-Types only become apparent at run time. Variables do not have fixed
-types; a variable may hold a pair at one point, an integer at the next,
-and a thousand-element vector later. Instead, values, not variables,
-have fixed types.
-
-In order to implement standard Scheme functions like @code{pair?} and
-@code{string?} and provide garbage collection, the representation of
-every value must contain enough information to accurately determine its
-type at run time. Often, Scheme systems also use this information to
-determine whether a program has attempted to apply an operation to an
-inappropriately typed value (such as taking the @code{car} of a string).
-
-Because variables, pairs, and vectors may hold values of any type,
-Scheme implementations use a uniform representation for values --- a
-single type large enough to hold either a complete value or a pointer
-to a complete value, along with the necessary typing information.
-
-The following sections will present a simple typing system, and then
-make some refinements to correct its major weaknesses. However, this is
-not a description of the system Guile actually uses. It is only an
-illustration of the issues Guile's system must address. We provide all
-the information one needs to work with Guile's data in @ref{How Guile
-does it}.
-
-
-@menu
-* A Simple Representation::
-* Faster Integers::
-* Cheaper Pairs::
-* Guile Is Hairier::
-@end menu
-
-@node A Simple Representation
-@subsection A Simple Representation
-
-The simplest way to meet the above requirements in C would be to
-represent each value as a pointer to a structure containing a type
-indicator, followed by a union carrying the real value. Assuming that
-@code{SCM} is the name of our universal type, we can write:
-
-@example
-enum type @{ integer, pair, string, vector, ... @};
-
-typedef struct value *SCM;
-
-struct value @{
- enum type type;
- union @{
- int integer;
- struct @{ SCM car, cdr; @} pair;
- struct @{ int length; char *elts; @} string;
- struct @{ int length; SCM *elts; @} vector;
- ...
- @} value;
-@};
-@end example
-with the ellipses replaced with code for the remaining Scheme types.
-
-This representation is sufficient to implement all of Scheme's
-semantics. If @var{x} is an @code{SCM} value:
-@itemize @bullet
-@item
- To test if @var{x} is an integer, we can write @code{@var{x}->type == integer}.
-@item
- To find its value, we can write @code{@var{x}->value.integer}.
-@item
- To test if @var{x} is a vector, we can write @code{@var{x}->type == vector}.
-@item
- If we know @var{x} is a vector, we can write
- @code{@var{x}->value.vector.elts[0]} to refer to its first element.
-@item
- If we know @var{x} is a pair, we can write
- @code{@var{x}->value.pair.car} to extract its car.
-@end itemize
-
-
-@node Faster Integers
-@subsection Faster Integers
-
-Unfortunately, the above representation has a serious disadvantage. In
-order to return an integer, an expression must allocate a @code{struct
-value}, initialize it to represent that integer, and return a pointer to
-it. Furthermore, fetching an integer's value requires a memory
-reference, which is much slower than a register reference on most
-processors. Since integers are extremely common, this representation is
-too costly, in both time and space. Integers should be very cheap to
-create and manipulate.
-
-One possible solution comes from the observation that, on many
-architectures, structures must be aligned on a four-byte boundary.
-(Whether or not the machine actually requires it, we can write our own
-allocator for @code{struct value} objects that assures this is true.)
-In this case, the lower two bits of the structure's address are known to
-be zero.
-
-This gives us the room we need to provide an improved representation
-for integers. We make the following rules:
-@itemize @bullet
-@item
-If the lower two bits of an @code{SCM} value are zero, then the SCM
-value is a pointer to a @code{struct value}, and everything proceeds as
-before.
-@item
-Otherwise, the @code{SCM} value represents an integer, whose value
-appears in its upper bits.
-@end itemize
-
-Here is C code implementing this convention:
-@example
-enum type @{ pair, string, vector, ... @};
-
-typedef struct value *SCM;
-
-struct value @{
- enum type type;
- union @{
- struct @{ SCM car, cdr; @} pair;
- struct @{ int length; char *elts; @} string;
- struct @{ int length; SCM *elts; @} vector;
- ...
- @} value;
-@};
-
-#define POINTER_P(x) (((int) (x) & 3) == 0)
-#define INTEGER_P(x) (! POINTER_P (x))
-
-#define GET_INTEGER(x) ((int) (x) >> 2)
-#define MAKE_INTEGER(x) ((SCM) (((x) << 2) | 1))
-@end example
-
-Notice that @code{integer} no longer appears as an element of @code{enum
-type}, and the union has lost its @code{integer} member. Instead, we
-use the @code{POINTER_P} and @code{INTEGER_P} macros to make a coarse
-classification of values into integers and non-integers, and do further
-type testing as before.
-
-Here's how we would answer the questions posed above (again, assume
-@var{x} is an @code{SCM} value):
-@itemize @bullet
-@item
- To test if @var{x} is an integer, we can write @code{INTEGER_P (@var{x})}.
-@item
- To find its value, we can write @code{GET_INTEGER (@var{x})}.
-@item
- To test if @var{x} is a vector, we can write:
-@example
- @code{POINTER_P (@var{x}) && @var{x}->type == vector}
-@end example
- Given the new representation, we must make sure @var{x} is truly a
- pointer before we dereference it to determine its complete type.
-@item
- If we know @var{x} is a vector, we can write
- @code{@var{x}->value.vector.elts[0]} to refer to its first element, as
- before.
-@item
- If we know @var{x} is a pair, we can write
- @code{@var{x}->value.pair.car} to extract its car, just as before.
-@end itemize
-
-This representation allows us to operate more efficiently on integers
-than the first. For example, if @var{x} and @var{y} are known to be
-integers, we can compute their sum as follows:
-@example
-MAKE_INTEGER (GET_INTEGER (@var{x}) + GET_INTEGER (@var{y}))
-@end example
-Now, integer math requires no allocation or memory references. Most
-real Scheme systems actually use an even more efficient representation,
-but this essay isn't about bit-twiddling. (Hint: what if pointers had
-@code{01} in their least significant bits, and integers had @code{00}?)
-
-
-@node Cheaper Pairs
-@subsection Cheaper Pairs
-
-However, there is yet another issue to confront. Most Scheme heaps
-contain more pairs than any other type of object; Jonathan Rees says
-that pairs occupy 45% of the heap in his Scheme implementation, Scheme
-48. However, our representation above spends three @code{SCM}-sized
-words per pair --- one for the type, and two for the @sc{car} and
-@sc{cdr}. Is there any way to represent pairs using only two words?
-
-Let us refine the convention we established earlier. Let us assert
-that:
-@itemize @bullet
-@item
- If the bottom two bits of an @code{SCM} value are @code{#b00}, then
- it is a pointer, as before.
-@item
- If the bottom two bits are @code{#b01}, then the upper bits are an
- integer. This is a bit more restrictive than before.
-@item
- If the bottom two bits are @code{#b10}, then the value, with the bottom
- two bits masked out, is the address of a pair.
-@end itemize
-
-Here is the new C code:
-@example
-enum type @{ string, vector, ... @};
-
-typedef struct value *SCM;
-
-struct value @{
- enum type type;
- union @{
- struct @{ int length; char *elts; @} string;
- struct @{ int length; SCM *elts; @} vector;
- ...
- @} value;
-@};
-
-struct pair @{
- SCM car, cdr;
-@};
-
-#define POINTER_P(x) (((int) (x) & 3) == 0)
-
-#define INTEGER_P(x) (((int) (x) & 3) == 1)
-#define GET_INTEGER(x) ((int) (x) >> 2)
-#define MAKE_INTEGER(x) ((SCM) (((x) << 2) | 1))
-
-#define PAIR_P(x) (((int) (x) & 3) == 2)
-#define GET_PAIR(x) ((struct pair *) ((int) (x) & ~3))
-@end example
-
-Notice that @code{enum type} and @code{struct value} now only contain
-provisions for vectors and strings; both integers and pairs have become
-special cases. The code above also assumes that an @code{int} is large
-enough to hold a pointer, which isn't generally true.
-
-
-Our list of examples is now as follows:
-@itemize @bullet
-@item
- To test if @var{x} is an integer, we can write @code{INTEGER_P
- (@var{x})}; this is as before.
-@item
- To find its value, we can write @code{GET_INTEGER (@var{x})}, as
- before.
-@item
- To test if @var{x} is a vector, we can write:
-@example
- @code{POINTER_P (@var{x}) && @var{x}->type == vector}
-@end example
- We must still make sure that @var{x} is a pointer to a @code{struct
- value} before dereferencing it to find its type.
-@item
- If we know @var{x} is a vector, we can write
- @code{@var{x}->value.vector.elts[0]} to refer to its first element, as
- before.
-@item
- We can write @code{PAIR_P (@var{x})} to determine if @var{x} is a
- pair, and then write @code{GET_PAIR (@var{x})->car} to refer to its
- car.
-@end itemize
-
-This change in representation reduces our heap size by 15%. It also
-makes it cheaper to decide if a value is a pair, because no memory
-references are necessary; it suffices to check the bottom two bits of
-the @code{SCM} value. This may be significant when traversing lists, a
-common activity in a Scheme system.
-
-Again, most real Scheme systems use a slightly different implementation;
-for example, if GET_PAIR subtracts off the low bits of @code{x}, instead
-of masking them off, the optimizer will often be able to combine that
-subtraction with the addition of the offset of the structure member we
-are referencing, making a modified pointer as fast to use as an
-unmodified pointer.
-
-
-@node Guile Is Hairier
-@subsection Guile Is Hairier
-
-We originally started with a very simple typing system --- each object
-has a field that indicates its type. Then, for the sake of efficiency
-in both time and space, we moved some of the typing information directly
-into the @code{SCM} value, and left the rest in the @code{struct value}.
-Guile itself employs a more complex hierarchy, storing finer and finer
-gradations of type information in different places, depending on the
-object's coarser type.
-
-In the author's opinion, Guile could be simplified greatly without
-significant loss of efficiency, but the simplified system would still be
-more complex than what we've presented above.
-
-
-@node How Guile does it
-@section How Guile does it
-
-Here we present the specifics of how Guile represents its data. We
-don't go into complete detail; an exhaustive description of Guile's
-system would be boring, and we do not wish to encourage people to write
-code which depends on its details anyway. We do, however, present
-everything one need know to use Guile's data.
-
-
-@menu
-* General Rules::
-* Conservative GC::
-* Immediates vs Non-immediates::
-* Immediate Datatypes::
-* Non-immediate Datatypes::
-* Signalling Type Errors::
-* Unpacking the SCM type::
-@end menu
-
-@node General Rules
-@subsection General Rules
-
-Any code which operates on Guile datatypes must @code{#include} the
-header file @code{<libguile.h>}. This file contains a definition for
-the @code{SCM} typedef (Guile's universal type, as in the examples
-above), and definitions and declarations for a host of macros and
-functions that operate on @code{SCM} values.
-
-All identifiers declared by @code{<libguile.h>} begin with @code{scm_}
-or @code{SCM_}.
-
-@c [[I wish this were true, but I don't think it is at the moment. -JimB]]
-@c Macros do not evaluate their arguments more than once, unless documented
-@c to do so.
-
-The functions described here generally check the types of their
-@code{SCM} arguments, and signal an error if their arguments are of an
-inappropriate type. Macros generally do not, unless that is their
-specified purpose. You must verify their argument types beforehand, as
-necessary.
-
-Macros and functions that return a boolean value have names ending in
-@code{P} or @code{_p} (for ``predicate''). Those that return a negated
-boolean value have names starting with @code{SCM_N}. For example,
-@code{SCM_IMP (@var{x})} is a predicate which returns non-zero iff
-@var{x} is an immediate value (an @code{IM}). @code{SCM_NCONSP
-(@var{x})} is a predicate which returns non-zero iff @var{x} is
-@emph{not} a pair object (a @code{CONS}).
-
-
-@node Conservative GC
-@subsection Conservative Garbage Collection
-
-Aside from the latent typing, the major source of constraints on a
-Scheme implementation's data representation is the garbage collector.
-The collector must be able to traverse every live object in the heap, to
-determine which objects are not live.
-
-There are many ways to implement this, but Guile uses an algorithm
-called @dfn{mark and sweep}. The collector scans the system's global
-variables and the local variables on the stack to determine which
-objects are immediately accessible by the C code. It then scans those
-objects to find the objects they point to, @i{et cetera}. The collector
-sets a @dfn{mark bit} on each object it finds, so each object is
-traversed only once. This process is called @dfn{tracing}.
-
-When the collector can find no unmarked objects pointed to by marked
-objects, it assumes that any objects that are still unmarked will never
-be used by the program (since there is no path of dereferences from any
-global or local variable that reaches them) and deallocates them.
-
-In the above paragraphs, we did not specify how the garbage collector
-finds the global and local variables; as usual, there are many different
-approaches. Frequently, the programmer must maintain a list of pointers
-to all global variables that refer to the heap, and another list
-(adjusted upon entry to and exit from each function) of local variables,
-for the collector's benefit.
-
-The list of global variables is usually not too difficult to maintain,
-since global variables are relatively rare. However, an explicitly
-maintained list of local variables (in the author's personal experience)
-is a nightmare to maintain. Thus, Guile uses a technique called
-@dfn{conservative garbage collection}, to make the local variable list
-unnecessary.
-
-The trick to conservative collection is to treat the stack as an
-ordinary range of memory, and assume that @emph{every} word on the stack
-is a pointer into the heap. Thus, the collector marks all objects whose
-addresses appear anywhere in the stack, without knowing for sure how
-that word is meant to be interpreted.
-
-Obviously, such a system will occasionally retain objects that are
-actually garbage, and should be freed. In practice, this is not a
-problem. The alternative, an explicitly maintained list of local
-variable addresses, is effectively much less reliable, due to programmer
-error.
-
-To accommodate this technique, data must be represented so that the
-collector can accurately determine whether a given stack word is a
-pointer or not. Guile does this as follows:
-
-@itemize @bullet
-@item
-Every heap object has a two-word header, called a @dfn{cell}. Some
-objects, like pairs, fit entirely in a cell's two words; others may
-store pointers to additional memory in either of the words. For
-example, strings and vectors store their length in the first word, and a
-pointer to their elements in the second.
-
-@item
-Guile allocates whole arrays of cells at a time, called @dfn{heap
-segments}. These segments are always allocated so that the cells they
-contain fall on eight-byte boundaries, or whatever is appropriate for
-the machine's word size. Guile keeps all cells in a heap segment
-initialized, whether or not they are currently in use.
-
-@item
-Guile maintains a sorted table of heap segments.
-@end itemize
-
-Thus, given any random word @var{w} fetched from the stack, Guile's
-garbage collector can consult the table to see if @var{w} falls within a
-known heap segment, and check @var{w}'s alignment. If both tests pass,
-the collector knows that @var{w} is a valid pointer to a cell,
-intentional or not, and proceeds to trace the cell.
-
-Note that heap segments do not contain all the data Guile uses; cells
-for objects like vectors and strings contain pointers to other memory
-areas. However, since those pointers are internal, and not shared among
-many pieces of code, it is enough for the collector to find the cell,
-and then use the cell's type to find more pointers to trace.
-
-
-@node Immediates vs Non-immediates
-@subsection Immediates vs Non-immediates
-
-Guile classifies Scheme objects into two kinds: those that fit entirely
-within an @code{SCM}, and those that require heap storage.
-
-The former class are called @dfn{immediates}. The class of immediates
-includes small integers, characters, boolean values, the empty list, the
-mysterious end-of-file object, and some others.
-
-The remaining types are called, not surprisingly, @dfn{non-immediates}.
-They include pairs, procedures, strings, vectors, and all other data
-types in Guile.
-
-@deftypefn Macro int SCM_IMP (SCM @var{x})
-Return non-zero iff @var{x} is an immediate object.
-@end deftypefn
-
-@deftypefn Macro int SCM_NIMP (SCM @var{x})
-Return non-zero iff @var{x} is a non-immediate object. This is the
-exact complement of @code{SCM_IMP}, above.
-@end deftypefn
-
-Note that for versions of Guile prior to 1.4 it was necessary to use the
-@code{SCM_NIMP} macro before calling a finer-grained predicate to
-determine @var{x}'s type, such as @code{SCM_CONSP} or
-@code{SCM_VECTORP}. This is no longer required: the definitions of all
-Guile type predicates now include a call to @code{SCM_NIMP} where
-necessary.
-
-
-@node Immediate Datatypes
-@subsection Immediate Datatypes
-
-The following datatypes are immediate values; that is, they fit entirely
-within an @code{SCM} value. The @code{SCM_IMP} and @code{SCM_NIMP}
-macros will distinguish these from non-immediates; see @ref{Immediates
-vs Non-immediates} for an explanation of the distinction.
-
-Note that the type predicates for immediate values work correctly on any
-@code{SCM} value; you do not need to call @code{SCM_IMP} first, to
-establish that a value is immediate.
-
-@menu
-* Integer Data::
-* Character Data::
-* Boolean Data::
-* Unique Values::
-@end menu
-
-@node Integer Data
-@subsubsection Integers
-
-Here are functions for operating on small integers, that fit within an
-@code{SCM}. Such integers are called @dfn{immediate numbers}, or
-@dfn{INUMs}. In general, INUMs occupy all but two bits of an
-@code{SCM}.
-
-Bignums and floating-point numbers are non-immediate objects, and have
-their own, separate accessors. The functions here will not work on
-them. This is not as much of a problem as you might think, however,
-because the system never constructs bignums that could fit in an INUM,
-and never uses floating point values for exact integers.
-
-@deftypefn Macro int SCM_INUMP (SCM @var{x})
-Return non-zero iff @var{x} is a small integer value.
-@end deftypefn
-
-@deftypefn Macro int SCM_NINUMP (SCM @var{x})
-The complement of SCM_INUMP.
-@end deftypefn
-
-@deftypefn Macro int SCM_INUM (SCM @var{x})
-Return the value of @var{x} as an ordinary, C integer. If @var{x}
-is not an INUM, the result is undefined.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_MAKINUM (int @var{i})
-Given a C integer @var{i}, return its representation as an @code{SCM}.
-This function does not check for overflow.
-@end deftypefn
-
-
-@node Character Data
-@subsubsection Characters
-
-Here are functions for operating on characters.
-
-@deftypefn Macro int SCM_CHARP (SCM @var{x})
-Return non-zero iff @var{x} is a character value.
-@end deftypefn
-
-@deftypefn Macro {unsigned int} SCM_CHAR (SCM @var{x})
-Return the value of @code{x} as a C character. If @var{x} is not a
-Scheme character, the result is undefined.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_MAKE_CHAR (int @var{c})
-Given a C character @var{c}, return its representation as a Scheme
-character value.
-@end deftypefn
-
-
-@node Boolean Data
-@subsubsection Booleans
-
-Here are functions and macros for operating on booleans.
-
-@deftypefn Macro SCM SCM_BOOL_T
-@deftypefnx Macro SCM SCM_BOOL_F
-The Scheme true and false values.
-@end deftypefn
-
-@deftypefn Macro int SCM_NFALSEP (@var{x})
-Convert the Scheme boolean value to a C boolean. Since every object in
-Scheme except @code{#f} is true, this amounts to comparing @var{x} to
-@code{#f}; hence the name.
-@c Noel feels a chill here.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_BOOL_NOT (@var{x})
-Return the boolean inverse of @var{x}. If @var{x} is not a
-Scheme boolean, the result is undefined.
-@end deftypefn
-
-
-@node Unique Values
-@subsubsection Unique Values
-
-The immediate values that are neither small integers, characters, nor
-booleans are all unique values --- that is, datatypes with only one
-instance.
-
-@deftypefn Macro SCM SCM_EOL
-The Scheme empty list object, or ``End Of List'' object, usually written
-in Scheme as @code{'()}.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_EOF_VAL
-The Scheme end-of-file value. It has no standard written
-representation, for obvious reasons.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_UNSPECIFIED
-The value returned by expressions which the Scheme standard says return
-an ``unspecified'' value.
-
-This is sort of a weirdly literal way to take things, but the standard
-read-eval-print loop prints nothing when the expression returns this
-value, so it's not a bad idea to return this when you can't think of
-anything else helpful.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_UNDEFINED
-The ``undefined'' value. Its most important property is that is not
-equal to any valid Scheme value. This is put to various internal uses
-by C code interacting with Guile.
-
-For example, when you write a C function that is callable from Scheme
-and which takes optional arguments, the interpreter passes
-@code{SCM_UNDEFINED} for any arguments you did not receive.
-
-We also use this to mark unbound variables.
-@end deftypefn
-
-@deftypefn Macro int SCM_UNBNDP (SCM @var{x})
-Return true if @var{x} is @code{SCM_UNDEFINED}. Apply this to a
-symbol's value to see if it has a binding as a global variable.
-@end deftypefn
-
-
-@node Non-immediate Datatypes
-@subsection Non-immediate Datatypes
-
-A non-immediate datatype is one which lives in the heap, either because
-it cannot fit entirely within a @code{SCM} word, or because it denotes a
-specific storage location (in the nomenclature of the Revised^5 Report
-on Scheme).
-
-The @code{SCM_IMP} and @code{SCM_NIMP} macros will distinguish these
-from immediates; see @ref{Immediates vs Non-immediates}.
-
-Given a cell, Guile distinguishes between pairs and other non-immediate
-types by storing special @dfn{tag} values in a non-pair cell's car, that
-cannot appear in normal pairs. A cell with a non-tag value in its car
-is an ordinary pair. The type of a cell with a tag in its car depends
-on the tag; the non-immediate type predicates test this value. If a tag
-value appears elsewhere (in a vector, for example), the heap may become
-corrupted.
-
-Note how the type information for a non-immediate object is split
-between the @code{SCM} word and the cell that the @code{SCM} word points
-to. The @code{SCM} word itself only indicates that the object is
-non-immediate --- in other words stored in a heap cell. The tag stored
-in the first word of the heap cell indicates more precisely the type of
-that object.
-
-The type predicates for non-immediate values work correctly on any
-@code{SCM} value; you do not need to call @code{SCM_NIMP} first, to
-establish that a value is non-immediate.
-
-@menu
-* Pair Data::
-* Vector Data::
-* Procedures::
-* Closures::
-* Subrs::
-* Port Data::
-@end menu
-
-
-@node Pair Data
-@subsubsection Pairs
-
-Pairs are the essential building block of list structure in Scheme. A
-pair object has two fields, called the @dfn{car} and the @dfn{cdr}.
-
-It is conventional for a pair's @sc{car} to contain an element of a
-list, and the @sc{cdr} to point to the next pair in the list, or to
-contain @code{SCM_EOL}, indicating the end of the list. Thus, a set of
-pairs chained through their @sc{cdr}s constitutes a singly-linked list.
-Scheme and libguile define many functions which operate on lists
-constructed in this fashion, so although lists chained through the
-@sc{car}s of pairs will work fine too, they may be less convenient to
-manipulate, and receive less support from the community.
-
-Guile implements pairs by mapping the @sc{car} and @sc{cdr} of a pair
-directly into the two words of the cell.
-
-
-@deftypefn Macro int SCM_CONSP (SCM @var{x})
-Return non-zero iff @var{x} is a Scheme pair object.
-@end deftypefn
-
-@deftypefn Macro int SCM_NCONSP (SCM @var{x})
-The complement of SCM_CONSP.
-@end deftypefn
-
-@deftypefun SCM scm_cons (SCM @var{car}, SCM @var{cdr})
-Allocate (``CONStruct'') a new pair, with @var{car} and @var{cdr} as its
-contents.
-@end deftypefun
-
-The macros below perform no type checking. The results are undefined if
-@var{cell} is an immediate. However, since all non-immediate Guile
-objects are constructed from cells, and these macros simply return the
-first element of a cell, they actually can be useful on datatypes other
-than pairs. (Of course, it is not very modular to use them outside of
-the code which implements that datatype.)
-
-@deftypefn Macro SCM SCM_CAR (SCM @var{cell})
-Return the @sc{car}, or first field, of @var{cell}.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CDR (SCM @var{cell})
-Return the @sc{cdr}, or second field, of @var{cell}.
-@end deftypefn
-
-@deftypefn Macro void SCM_SETCAR (SCM @var{cell}, SCM @var{x})
-Set the @sc{car} of @var{cell} to @var{x}.
-@end deftypefn
-
-@deftypefn Macro void SCM_SETCDR (SCM @var{cell}, SCM @var{x})
-Set the @sc{cdr} of @var{cell} to @var{x}.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CAAR (SCM @var{cell})
-@deftypefnx Macro SCM SCM_CADR (SCM @var{cell})
-@deftypefnx Macro SCM SCM_CDAR (SCM @var{cell}) @dots{}
-@deftypefnx Macro SCM SCM_CDDDDR (SCM @var{cell})
-Return the @sc{car} of the @sc{car} of @var{cell}, the @sc{car} of the
-@sc{cdr} of @var{cell}, @i{et cetera}.
-@end deftypefn
-
-
-@node Vector Data
-@subsubsection Vectors, Strings, and Symbols
-
-Vectors, strings, and symbols have some properties in common. They all
-have a length, and they all have an array of elements. In the case of a
-vector, the elements are @code{SCM} values; in the case of a string or
-symbol, the elements are characters.
-
-All these types store their length (along with some tagging bits) in the
-@sc{car} of their header cell, and store a pointer to the elements in
-their @sc{cdr}. Thus, the @code{SCM_CAR} and @code{SCM_CDR} macros
-are (somewhat) meaningful when applied to these datatypes.
-
-@deftypefn Macro int SCM_VECTORP (SCM @var{x})
-Return non-zero iff @var{x} is a vector.
-@end deftypefn
-
-@deftypefn Macro int SCM_STRINGP (SCM @var{x})
-Return non-zero iff @var{x} is a string.
-@end deftypefn
-
-@deftypefn Macro int SCM_SYMBOLP (SCM @var{x})
-Return non-zero iff @var{x} is a symbol.
-@end deftypefn
-
-@deftypefn Macro int SCM_VECTOR_LENGTH (SCM @var{x})
-@deftypefnx Macro int SCM_STRING_LENGTH (SCM @var{x})
-@deftypefnx Macro int SCM_SYMBOL_LENGTH (SCM @var{x})
-Return the length of the object @var{x}. The result is undefined if
-@var{x} is not a vector, string, or symbol, respectively.
-@end deftypefn
-
-@deftypefn Macro {SCM *} SCM_VECTOR_BASE (SCM @var{x})
-Return a pointer to the array of elements of the vector @var{x}.
-The result is undefined if @var{x} is not a vector.
-@end deftypefn
-
-@deftypefn Macro {char *} SCM_STRING_CHARS (SCM @var{x})
-@deftypefnx Macro {char *} SCM_SYMBOL_CHARS (SCM @var{x})
-Return a pointer to the characters of @var{x}. The result is undefined
-if @var{x} is not a symbol or string, respectively.
-@end deftypefn
-
-There are also a few magic values stuffed into memory before a symbol's
-characters, but you don't want to know about those. What cruft!
-
-
-@node Procedures
-@subsubsection Procedures
-
-Guile provides two kinds of procedures: @dfn{closures}, which are the
-result of evaluating a @code{lambda} expression, and @dfn{subrs}, which
-are C functions packaged up as Scheme objects, to make them available to
-Scheme programmers.
-
-(There are actually other sorts of procedures: compiled closures, and
-continuations; see the source code for details about them.)
-
-@deftypefun SCM scm_procedure_p (SCM @var{x})
-Return @code{SCM_BOOL_T} iff @var{x} is a Scheme procedure object, of
-any sort. Otherwise, return @code{SCM_BOOL_F}.
-@end deftypefun
-
-
-@node Closures
-@subsubsection Closures
-
-[FIXME: this needs to be further subbed, but texinfo has no subsubsub]
-
-A closure is a procedure object, generated as the value of a
-@code{lambda} expression in Scheme. The representation of a closure is
-straightforward --- it contains a pointer to the code of the lambda
-expression from which it was created, and a pointer to the environment
-it closes over.
-
-In Guile, each closure also has a property list, allowing the system to
-store information about the closure. I'm not sure what this is used for
-at the moment --- the debugger, maybe?
-
-@deftypefn Macro int SCM_CLOSUREP (SCM @var{x})
-Return non-zero iff @var{x} is a closure.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_PROCPROPS (SCM @var{x})
-Return the property list of the closure @var{x}. The results are
-undefined if @var{x} is not a closure.
-@end deftypefn
-
-@deftypefn Macro void SCM_SETPROCPROPS (SCM @var{x}, SCM @var{p})
-Set the property list of the closure @var{x} to @var{p}. The results
-are undefined if @var{x} is not a closure.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CODE (SCM @var{x})
-Return the code of the closure @var{x}. The result is undefined if
-@var{x} is not a closure.
-
-This function should probably only be used internally by the
-interpreter, since the representation of the code is intimately
-connected with the interpreter's implementation.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_ENV (SCM @var{x})
-Return the environment enclosed by @var{x}.
-The result is undefined if @var{x} is not a closure.
-
-This function should probably only be used internally by the
-interpreter, since the representation of the environment is intimately
-connected with the interpreter's implementation.
-@end deftypefn
-
-
-@node Subrs
-@subsubsection Subrs
-
-[FIXME: this needs to be further subbed, but texinfo has no subsubsub]
-
-A subr is a pointer to a C function, packaged up as a Scheme object to
-make it callable by Scheme code. In addition to the function pointer,
-the subr also contains a pointer to the name of the function, and
-information about the number of arguments accepted by the C function, for
-the sake of error checking.
-
-There is no single type predicate macro that recognizes subrs, as
-distinct from other kinds of procedures. The closest thing is
-@code{scm_procedure_p}; see @ref{Procedures}.
-
-@deftypefn Macro {char *} SCM_SNAME (@var{x})
-Return the name of the subr @var{x}. The result is undefined if
-@var{x} is not a subr.
-@end deftypefn
-
-@deftypefun SCM scm_make_gsubr (char *@var{name}, int @var{req}, int @var{opt}, int @var{rest}, SCM (*@var{function})())
-Create a new subr object named @var{name}, based on the C function
-@var{function}, make it visible to Scheme the value of as a global
-variable named @var{name}, and return the subr object.
-
-The subr object accepts @var{req} required arguments, @var{opt} optional
-arguments, and a @var{rest} argument iff @var{rest} is non-zero. The C
-function @var{function} should accept @code{@var{req} + @var{opt}}
-arguments, or @code{@var{req} + @var{opt} + 1} arguments if @code{rest}
-is non-zero.
-
-When a subr object is applied, it must be applied to at least @var{req}
-arguments, or else Guile signals an error. @var{function} receives the
-subr's first @var{req} arguments as its first @var{req} arguments. If
-there are fewer than @var{opt} arguments remaining, then @var{function}
-receives the value @code{SCM_UNDEFINED} for any missing optional
-arguments. If @var{rst} is non-zero, then any arguments after the first
-@code{@var{req} + @var{opt}} are packaged up as a list as passed as
-@var{function}'s last argument.
-
-Note that subrs can actually only accept a predefined set of
-combinations of required, optional, and rest arguments. For example, a
-subr can take one required argument, or one required and one optional
-argument, but a subr can't take one required and two optional arguments.
-It's bizarre, but that's the way the interpreter was written. If the
-arguments to @code{scm_make_gsubr} do not fit one of the predefined
-patterns, then @code{scm_make_gsubr} will return a compiled closure
-object instead of a subr object.
-@end deftypefun
-
-
-@node Port Data
-@subsubsection Ports
-
-Haven't written this yet, 'cos I don't understand ports yet.
-
-
-@node Signalling Type Errors
-@subsection Signalling Type Errors
-
-Every function visible at the Scheme level should aggressively check the
-types of its arguments, to avoid misinterpreting a value, and perhaps
-causing a segmentation fault. Guile provides some macros to make this
-easier.
-
-@deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
-If @var{test} is zero, signal a ``wrong type argument'' error,
-attributed to the subroutine named @var{subr}, operating on the value
-@var{obj}, which is the @var{position}'th argument of @var{subr}.
-@end deftypefn
-
-@deftypefn Macro int SCM_ARG1
-@deftypefnx Macro int SCM_ARG2
-@deftypefnx Macro int SCM_ARG3
-@deftypefnx Macro int SCM_ARG4
-@deftypefnx Macro int SCM_ARG5
-@deftypefnx Macro int SCM_ARG6
-@deftypefnx 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
-Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
-leave it unspecified which argument's type is incorrect. Again,
-@code{SCM_ARGn} should be preferred over a raw zero constant.
-@end deftypefn
-
-
-@node Unpacking the SCM type
-@subsection Unpacking the SCM Type
-
-The previous sections have explained how @code{SCM} values can refer to
-immediate and non-immediate Scheme objects. For immediate objects, the
-complete object value is stored in the @code{SCM} word itself, while for
-non-immediates, the @code{SCM} word contains a pointer to a heap cell,
-and further information about the object in question is stored in that
-cell. This section describes how the @code{SCM} type is actually
-represented and used at the C level.
-
-In fact, there are two basic C data types to represent objects in Guile:
-
-@itemize @bullet
-@item
-@code{SCM} is the user level abstract C type that is used to represent
-all of Guile's Scheme objects, no matter what the Scheme object type is.
-No C operation except assignment is guaranteed to work with variables of
-type @code{SCM}, so you should only use macros and functions to work
-with @code{SCM} values. Values are converted between C data types and
-the @code{SCM} type with utility functions and macros.
-
-@item
-@code{scm_t_bits} is an integral data type that is guaranteed to be
-large enough to hold all information that is required to represent any
-Scheme object. While this data type is mostly used to implement Guile's
-internals, the use of this type is also necessary to write certain kinds
-of extensions to Guile.
-@end itemize
-
-@menu
-* Relationship between SCM and scm_t_bits::
-* Immediate objects::
-* Non-immediate objects::
-* Allocating Cells::
-* Heap Cell Type Information::
-* Accessing Cell Entries::
-* Basic Rules for Accessing Cell Entries::
-@end menu
-
-
-@node Relationship between SCM and scm_t_bits
-@subsubsection Relationship between @code{SCM} and @code{scm_t_bits}
-
-A variable of type @code{SCM} is guaranteed to hold a valid Scheme
-object. A variable of type @code{scm_t_bits}, on the other hand, may
-hold a representation of a @code{SCM} value as a C integral type, but
-may also hold any C value, even if it does not correspond to a valid
-Scheme object.
-
-For a variable @var{x} of type @code{SCM}, the Scheme object's type
-information is stored in a form that is not directly usable. To be able
-to work on the type encoding of the scheme value, the @code{SCM}
-variable has to be transformed into the corresponding representation as
-a @code{scm_t_bits} variable @var{y} by using the @code{SCM_UNPACK}
-macro. Once this has been done, the type of the scheme object @var{x}
-can be derived from the content of the bits of the @code{scm_t_bits}
-value @var{y}, in the way illustrated by the example earlier in this
-chapter (@pxref{Cheaper Pairs}). Conversely, a valid bit encoding of a
-Scheme value as a @code{scm_t_bits} variable can be transformed into the
-corresponding @code{SCM} value using the @code{SCM_PACK} macro.
-
-@deftypefn Macro scm_t_bits SCM_UNPACK (SCM @var{x})
-Transforms the @code{SCM} value @var{x} into its representation as an
-integral type. Only after applying @code{SCM_UNPACK} it is possible to
-access the bits and contents of the @code{SCM} value.
-@end deftypefn
-
-@deftypefn Macro SCM SCM_PACK (scm_t_bits @var{x})
-Takes a valid integral representation of a Scheme object and transforms
-it into its representation as a @code{SCM} value.
-@end deftypefn
-
-
-@node Immediate objects
-@subsubsection Immediate objects
-
-A Scheme object may either be an immediate, i.e. carrying all necessary
-information by itself, or it may contain a reference to a @dfn{cell}
-with additional information on the heap. Although in general it should
-be irrelevant for user code whether an object is an immediate or not,
-within Guile's own code the distinction is sometimes of importance.
-Thus, the following low level macro is provided:
-
-@deftypefn Macro int SCM_IMP (SCM @var{x})
-A Scheme object is an immediate if it fulfills the @code{SCM_IMP}
-predicate, otherwise it holds an encoded reference to a heap cell. The
-result of the predicate is delivered as a C style boolean value. User
-code and code that extends Guile should normally not be required to use
-this macro.
-@end deftypefn
-
-@noindent
-Summary:
-@itemize @bullet
-@item
-Given a Scheme object @var{x} of unknown type, check first
-with @code{SCM_IMP (@var{x})} if it is an immediate object.
-@item
-If so, all of the type and value information can be determined from the
-@code{scm_t_bits} value that is delivered by @code{SCM_UNPACK
-(@var{x})}.
-@end itemize
-
-
-@node Non-immediate objects
-@subsubsection Non-immediate objects
-
-A Scheme object of type @code{SCM} that does not fulfill the
-@code{SCM_IMP} predicate holds an encoded reference to a heap cell.
-This reference can be decoded to a C pointer to a heap cell using the
-@code{SCM2PTR} macro. The encoding of a pointer to a heap cell into a
-@code{SCM} value is done using the @code{PTR2SCM} macro.
-
-@c (FIXME:: this name should be changed)
-@deftypefn Macro (scm_t_cell *) SCM2PTR (SCM @var{x})
-Extract and return the heap cell pointer from a non-immediate @code{SCM}
-object @var{x}.
-@end deftypefn
-
-@c (FIXME:: this name should be changed)
-@deftypefn Macro SCM PTR2SCM (scm_t_cell * @var{x})
-Return a @code{SCM} value that encodes a reference to the heap cell
-pointer @var{x}.
-@end deftypefn
-
-Note that it is also possible to transform a non-immediate @code{SCM}
-value by using @code{SCM_UNPACK} into a @code{scm_t_bits} variable.
-However, the result of @code{SCM_UNPACK} may not be used as a pointer to
-a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a
-@code{SCM} object into a valid pointer to a heap cell. Also, it is not
-allowed to apply @code{PTR2SCM} to anything that is not a valid pointer
-to a heap cell.
-
-@noindent
-Summary:
-@itemize @bullet
-@item
-Only use @code{SCM2PTR} on @code{SCM} values for which @code{SCM_IMP} is
-false!
-@item
-Don't use @code{(scm_t_cell *) SCM_UNPACK (@var{x})}! Use @code{SCM2PTR
-(@var{x})} instead!
-@item
-Don't use @code{PTR2SCM} for anything but a cell pointer!
-@end itemize
-
-@node Allocating Cells
-@subsubsection Allocating Cells
-
-Guile provides both ordinary cells with two slots, and double cells
-with four slots. The following two function are the most primitive
-way to allocate such cells.
-
-If the caller intends to use it as a header for some other type, she
-must pass an appropriate magic value in @var{word_0}, to mark it as a
-member of that type, and pass whatever value as @var{word_1}, etc that
-the type expects. You should generally not need these functions,
-unless you are implementing a new datatype, and thoroughly understand
-the code in @code{<libguile/tags.h>}.
-
-If you just want to allocate pairs, use @code{scm_cons}.
-
-@deftypefn Function SCM scm_cell (scm_t_bits word_0, scm_t_bits word_1)
-Allocate a new cell, initialize the two slots with @var{word_0} and
-@var{word_1}, and return it.
-
-Note that @var{word_0} and @var{word_1} are of type @code{scm_t_bits}.
-If you want to pass a @code{SCM} object, you need to use
-@code{SCM_UNPACK}.
-@end deftypefn
-
-@deftypefn Function SCM scm_double_cell (scm_t_bits word_0, scm_t_bits word_1, scm_t_bits word_2, scm_t_bits word_3)
-Like @code{scm_cell}, but allocates a double cell with four
-slots.
-@end deftypefn
-
-@node Heap Cell Type Information
-@subsubsection Heap Cell Type Information
-
-Heap cells contain a number of entries, each of which is either a scheme
-object of type @code{SCM} or a raw C value of type @code{scm_t_bits}.
-Which of the cell entries contain Scheme objects and which contain raw C
-values is determined by the first entry of the cell, which holds the
-cell type information.
-
-@deftypefn Macro scm_t_bits SCM_CELL_TYPE (SCM @var{x})
-For a non-immediate Scheme object @var{x}, deliver the content of the
-first entry of the heap cell referenced by @var{x}. This value holds
-the information about the cell type.
-@end deftypefn
-
-@deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_t_bits @var{t})
-For a non-immediate Scheme object @var{x}, write the value @var{t} into
-the first entry of the heap cell referenced by @var{x}. The value
-@var{t} must hold a valid cell type.
-@end deftypefn
-
-
-@node Accessing Cell Entries
-@subsubsection Accessing Cell Entries
-
-For a non-immediate Scheme object @var{x}, the object type can be
-determined by reading the cell type entry using the @code{SCM_CELL_TYPE}
-macro. For each different type of cell it is known which cell entries
-hold Scheme objects and which cell entries hold raw C data. To access
-the different cell entries appropriately, the following macros are
-provided.
-
-@deftypefn Macro scm_t_bits SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})
-Deliver the cell entry @var{n} of the heap cell referenced by the
-non-immediate Scheme object @var{x} as raw data. It is illegal, to
-access cell entries that hold Scheme objects by using these macros. For
-convenience, the following macros are also provided.
-@itemize @bullet
-@item
-SCM_CELL_WORD_0 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 0)
-@item
-SCM_CELL_WORD_1 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 1)
-@item
-@dots{}
-@item
-SCM_CELL_WORD_@var{n} (@var{x}) @result{} SCM_CELL_WORD (@var{x}, @var{n})
-@end itemize
-@end deftypefn
-
-@deftypefn Macro SCM SCM_CELL_OBJECT (SCM @var{x}, unsigned int @var{n})
-Deliver the cell entry @var{n} of the heap cell referenced by the
-non-immediate Scheme object @var{x} as a Scheme object. It is illegal,
-to access cell entries that do not hold Scheme objects by using these
-macros. For convenience, the following macros are also provided.
-@itemize @bullet
-@item
-SCM_CELL_OBJECT_0 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 0)
-@item
-SCM_CELL_OBJECT_1 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 1)
-@item
-@dots{}
-@item
-SCM_CELL_OBJECT_@var{n} (@var{x}) @result{} SCM_CELL_OBJECT (@var{x},
-@var{n})
-@end itemize
-@end deftypefn
-
-@deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_t_bits @var{w})
-Write the raw C value @var{w} into entry number @var{n} of the heap cell
-referenced by the non-immediate Scheme value @var{x}. Values that are
-written into cells this way may only be read from the cells using the
-@code{SCM_CELL_WORD} macros or, in case cell entry 0 is written, using
-the @code{SCM_CELL_TYPE} macro. For the special case of cell entry 0 it
-has to be made sure that @var{w} contains a cell type information which
-does not describe a Scheme object. For convenience, the following
-macros are also provided.
-@itemize @bullet
-@item
-SCM_SET_CELL_WORD_0 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, 0, @var{w})
-@item
-SCM_SET_CELL_WORD_1 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, 1, @var{w})
-@item
-@dots{}
-@item
-SCM_SET_CELL_WORD_@var{n} (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, @var{n}, @var{w})
-@end itemize
-@end deftypefn
-
-@deftypefn Macro void SCM_SET_CELL_OBJECT (SCM @var{x}, unsigned int @var{n}, SCM @var{o})
-Write the Scheme object @var{o} into entry number @var{n} of the heap
-cell referenced by the non-immediate Scheme value @var{x}. Values that
-are written into cells this way may only be read from the cells using
-the @code{SCM_CELL_OBJECT} macros or, in case cell entry 0 is written,
-using the @code{SCM_CELL_TYPE} macro. For the special case of cell
-entry 0 the writing of a Scheme object into this cell is only allowed
-if the cell forms a Scheme pair. For convenience, the following macros
-are also provided.
-@itemize @bullet
-@item
-SCM_SET_CELL_OBJECT_0 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
-(@var{x}, 0, @var{o})
-@item
-SCM_SET_CELL_OBJECT_1 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
-(@var{x}, 1, @var{o})
-@item
-@dots{}
-@item
-SCM_SET_CELL_OBJECT_@var{n} (@var{x}, @var{o}) @result{}
-SCM_SET_CELL_OBJECT (@var{x}, @var{n}, @var{o})
-@end itemize
-@end deftypefn
-
-@noindent
-Summary:
-@itemize @bullet
-@item
-For a non-immediate Scheme object @var{x} of unknown type, get the type
-information by using @code{SCM_CELL_TYPE (@var{x})}.
-@item
-As soon as the cell type information is available, only use the
-appropriate access methods to read and write data to the different cell
-entries.
-@end itemize
-
-
-@node Basic Rules for Accessing Cell Entries
-@subsubsection Basic Rules for Accessing Cell Entries
-
-For each cell type it is generally up to the implementation of that type
-which of the corresponding cell entries hold Scheme objects and which
-hold raw C values. However, there is one basic rule that has to be
-followed: Scheme pairs consist of exactly two cell entries, which both
-contain Scheme objects. Further, a cell which contains a Scheme object
-in it first entry has to be a Scheme pair. In other words, it is not
-allowed to store a Scheme object in the first cell entry and a non
-Scheme object in the second cell entry.
-
-@c Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
-@deftypefn Macro int SCM_CONSP (SCM @var{x})
-Determine, whether the Scheme object @var{x} is a Scheme pair,
-i.e. whether @var{x} references a heap cell consisting of exactly two
-entries, where both entries contain a Scheme object. In this case, both
-entries will have to be accessed using the @code{SCM_CELL_OBJECT}
-macros. On the contrary, if the @code{SCM_CONSP} predicate is not
-fulfilled, the first entry of the Scheme cell is guaranteed not to be a
-Scheme value and thus the first cell entry must be accessed using the
-@code{SCM_CELL_WORD_0} macro.
-@end deftypefn
-
-
-@node Defining New Types (Smobs)
-@section Defining New Types (Smobs)
-
-@dfn{Smobs} are Guile's mechanism for adding new non-immediate types to
-the system.@footnote{The term ``smob'' was coined by Aubrey Jaffer, who
-says it comes from ``small object'', referring to the fact that only the
-@sc{cdr} and part of the @sc{car} of a smob's cell are available for
-use.} To define a new smob type, the programmer provides Guile with
-some essential information about the type --- how to print it, how to
-garbage collect it, and so on --- and Guile returns a fresh type tag for
-use in the first word of new cells. The programmer can then use
-@code{scm_c_define_gsubr} to make a set of C functions that create and
-operate on these objects visible to Scheme code.
-
-(You can find a complete version of the example code used in this
-section in the Guile distribution, in @file{doc/example-smob}. That
-directory includes a makefile and a suitable @code{main} function, so
-you can build a complete interactive Guile shell, extended with the
-datatypes described here.)
-
-@menu
-* Describing a New Type::
-* Creating Instances::
-* Type checking::
-* Garbage Collecting Smobs::
-* A Common Mistake In Allocating Smobs::
-* Garbage Collecting Simple Smobs::
-* A Complete Example::
-@end menu
-
-@node Describing a New Type
-@subsection Describing a New Type
-
-To define a new type, the programmer must write four functions to
-manage instances of the type:
-
-@table @code
-@item mark
-Guile will apply this function to each instance of the new type it
-encounters during garbage collection. This function is responsible for
-telling the collector about any other non-immediate objects the object
-refers to. The default smob mark function is to not mark any data.
-@xref{Garbage Collecting Smobs}, for more details.
-
-@item free
-Guile will apply this function to each instance of the new type it could
-not find any live pointers to. The function should release all
-resources held by the object and return the number of bytes released.
-This is analogous to the Java finalization method-- it is invoked at
-an unspecified time (when garbage collection occurs) after the object
-is dead. The default free function frees the smob data (if the size
-of the struct passed to @code{scm_make_smob_type} is non-zero) using
-@code{scm_gc_free}. @xref{Garbage Collecting Smobs}, for more
-details.
-
-@item print
-@c GJB:FIXME:: @var{exp} and @var{port} need to refer to a prototype of
-@c the print function.... where is that, or where should it go?
-Guile will apply this function to each instance of the new type to print
-the value, as for @code{display} or @code{write}. The function should
-write a printed representation of @var{exp} on @var{port}, in accordance
-with the parameters in @var{pstate}. (For more information on print
-states, see @ref{Port Data}.) The default print function prints
-@code{#<NAME ADDRESS>} where @code{NAME} is the first argument passed to
-@code{scm_make_smob_type}.
-
-@item equalp
-If Scheme code asks the @code{equal?} function to compare two instances
-of the same smob type, Guile calls this function. It should return
-@code{SCM_BOOL_T} if @var{a} and @var{b} should be considered
-@code{equal?}, or @code{SCM_BOOL_F} otherwise. If @code{equalp} is
-@code{NULL}, @code{equal?} will assume that two instances of this type are
-never @code{equal?} unless they are @code{eq?}.
-
-@end table
-
-To actually register the new smob type, call @code{scm_make_smob_type}:
-
-@deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
-This function implements the standard way of adding a new smob type,
-named @var{name}, with instance size @var{size}, to the system. The
-return value is a tag that is used in creating instances of the type.
-If @var{size} is 0, then no memory will be allocated when instances of
-the smob are created, and nothing will be freed by the default free
-function. Default values are provided for mark, free, print, and,
-equalp, as described above. If you want to customize any of these
-functions, the call to @code{scm_make_smob_type} should be immediately
-followed by calls to one or several of @code{scm_set_smob_mark},
-@code{scm_set_smob_free}, @code{scm_set_smob_print}, and/or
-@code{scm_set_smob_equalp}.
-@end deftypefun
-
-Each of the below @code{scm_set_smob_XXX} functions registers a smob
-special function for a given type. Each function is intended to be used
-only zero or one time per type, and the call should be placed
-immediately following the call to @code{scm_make_smob_type}.
-
-@deftypefun void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM))
-This function sets the smob marking procedure for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-@deftypefun void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM))
-This function sets the smob freeing procedure for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-@deftypefun void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM, SCM, scm_print_state*))
-This function sets the smob printing procedure for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-@deftypefun void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
-This function sets the smob equality-testing predicate for the smob type specified by
-the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
-@end deftypefun
-
-In versions 1.4 and earlier, there was another way of creating smob
-types, using @code{scm_make_smob_type_mfpe}. This function is now
-deprecated and will be removed in a future version of Guile. You should
-use the mechanism described above for new code, and change old code not
-to use deprecated features.
-
-Instead of using @code{scm_make_smob_type} and calling each of the
-individual @code{scm_set_smob_XXX} functions to register each special
-function independently, you could use @code{scm_make_smob_type_mfpe} to
-register all of the special functions at once as you create the smob
-type
-
-@deftypefun long scm_make_smob_type_mfpe(const char *name, size_t size, SCM (*mark) (SCM), size_t (*free) (SCM), int (*print) (SCM, SCM, scm_print_state*), SCM (*equalp) (SCM, SCM))
-This function invokes @code{scm_make_smob_type} on its first two arguments
-to add a new smob type named @var{name}, with instance size @var{size} to the system.
-It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob
-special functions for that new type. Any of these parameters can be @code{NULL}
-to have that special function use the default behavior for guile.
-The return value is a tag that is used in creating instances of the type. If @var{size}
-is 0, then no memory will be allocated when instances of the smob are created, and
-nothing will be freed by the default free function.
-@end deftypefun
-
-For example, here is how one might declare and register a new type
-representing eight-bit gray-scale images:
-
-@example
-#include <libguile.h>
-
-static scm_t_bits image_tag;
-
-void
-init_image_type (void)
-@{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-@}
-@end example
-
-
-@node Creating Instances
-@subsection Creating Instances
-
-Like other non-immediate types, smobs start with a cell whose first word
-contains typing information, and whose remaining words are free for any
-use.
-
-After the header word containing the type code, smobs can have either
-one, two or three additional words of data. These words store either a
-pointer to the internal C structure holding the smob-specific data, or
-the smob data itself. To create an instance of a smob type following
-these standards, you should use @code{SCM_NEWSMOB}, @code{SCM_NEWSMOB2}
-or @code{SCM_NEWSMOB3}:@footnote{The @code{SCM_NEWSMOB2} and
-@code{SCM_NEWSMOB3} variants will allocate double cells and thus use
-twice as much memory as smobs created by @code{SCM_NEWSMOB}.}
-
-@deftypefn Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data)
-@deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, void *data2)
-@deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_t_bits tag, void *data1, void *data2, void *data3)
-Make @var{value} contain a smob instance of the type with tag @var{tag}
-and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}).
-@var{value} must be previously declared as C type @code{SCM}.
-@end deftypefn
-
-Since it is often the case (e.g., in smob constructors) that you will
-create a smob instance and return it, there is also a slightly specialized
-macro for this situation:
-
-@deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data)
-@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void *data1, void *data2)
-@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3)
-This macro expands to a block of code that creates a smob instance of
-the type with tag @var{tag} and smob data @var{data} (or @var{data1},
-@var{data2}, and @var{data3}), and causes the surrounding function to
-return that @code{SCM} value. It should be the last piece of code in
-a block.
-@end deftypefn
-
-Guile provides some functions for managing memory, which are often
-helpful when implementing smobs. @xref{Memory Blocks}.
-
-
-Continuing the above example, if the global variable @code{image_tag}
-contains a tag returned by @code{scm_make_smob_type}, here is how we
-could construct a smob whose @sc{cdr} contains a pointer to a freshly
-allocated @code{struct image}:
-
-@example
-struct image @{
- int width, height;
- char *pixels;
-
- /* The name of this image */
- SCM name;
-
- /* A function to call when this image is
- modified, e.g., to update the screen,
- or SCM_BOOL_F if no action necessary */
- SCM update_func;
-@};
-
-SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-@{
- struct image *image;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
- image->name = name;
- image->update_func = SCM_BOOL_F;
-
- SCM_RETURN_NEWSMOB (image_tag, image);
-@}
-@end example
-
-
-@node Type checking
-@subsection Type checking
-
-Functions that operate on smobs should aggressively check the types of
-their arguments, to avoid misinterpreting some other datatype as a smob,
-and perhaps causing a segmentation fault. Fortunately, this is pretty
-simple to do. The function need only verify that its argument is a
-non-immediate, whose first word is the type tag returned by
-@code{scm_make_smob_type}.
-
-For example, here is a simple function that operates on an image smob,
-and checks the type of its argument. We also present an expanded
-version of the @code{init_image_type} function, to make
-@code{clear_image} and the image constructor function @code{make_image}
-visible to Scheme code.
-
-@example
-SCM
-clear_image (SCM image_smob)
-@{
- int area;
- struct image *image;
-
- SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
- image_smob, SCM_ARG1, "clear-image");
-
- image = (struct image *) SCM_SMOB_DATA (image_smob);
- area = image->width * image->height;
- memset (image->pixels, 0, area);
-
- /* Invoke the image's update function. */
- if (image->update_func != SCM_BOOL_F)
- scm_apply (image->update_func, SCM_EOL, SCM_EOL);
-
- return SCM_UNSPECIFIED;
-@}
-
-
-void
-init_image_type (void)
-@{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-
- scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
- scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
-@}
-@end example
-
-@c GJB:FIXME:: should talk about guile-snarf somewhere!
-
-
-@node Garbage Collecting Smobs
-@subsection Garbage Collecting Smobs
-
-Once a smob has been released to the tender mercies of the Scheme
-system, it must be prepared to survive garbage collection. Guile calls
-the @code{mark} and @code{free} functions of the @code{scm_smobfuns}
-structure to manage this.
-
-As described before (@pxref{Conservative GC}), every object in the
-Scheme system has a @dfn{mark bit}, which the garbage collector uses to
-tell live objects from dead ones. When collection starts, every
-object's mark bit is clear. The collector traces pointers through the
-heap, starting from objects known to be live, and sets the mark bit on
-each object it encounters. When it can find no more unmarked objects,
-the collector walks all objects, live and dead, frees those whose mark
-bits are still clear, and clears the mark bit on the others.
-
-The two main portions of the collection are called the @dfn{mark phase},
-during which the collector marks live objects, and the @dfn{sweep
-phase}, during which the collector frees all unmarked objects.
-
-The mark bit of a smob lives in a special memory region. When the
-collector encounters a smob, it sets the smob's mark bit, and uses the
-smob's type tag to find the appropriate @code{mark} function for that
-smob: the one listed in that smob's @code{scm_smobfuns} structure. It
-then calls the @code{mark} function, passing it the smob as its only
-argument.
-
-The @code{mark} function is responsible for marking any other Scheme
-objects the smob refers to. If it does not do so, the objects' mark
-bits will still be clear when the collector begins to sweep, and the
-collector will free them. If this occurs, it will probably break, or at
-least confuse, any code operating on the smob; the smob's @code{SCM}
-values will have become dangling references.
-
-To mark an arbitrary Scheme object, the @code{mark} function may call
-this function:
-
-@deftypefun void scm_gc_mark (SCM @var{x})
-Mark the object @var{x}, and recurse on any objects @var{x} refers to.
-If @var{x}'s mark bit is already set, return immediately.
-@end deftypefun
-
-Thus, here is how we might write the @code{mark} function for the image
-smob type discussed above:
-
-@example
-@group
-SCM
-mark_image (SCM image_smob)
-@{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- scm_gc_mark (image->update_func);
-
- return SCM_BOOL_F;
-@}
-@end group
-@end example
-
-Note that, even though the image's @code{update_func} could be an
-arbitrarily complex structure (representing a procedure and any values
-enclosed in its environment), @code{scm_gc_mark} will recurse as
-necessary to mark all its components. Because @code{scm_gc_mark} sets
-an object's mark bit before it recurses, it is not confused by
-circular structures.
-
-As an optimization, the collector will mark whatever value is returned
-by the @code{mark} function; this helps limit depth of recursion during
-the mark phase. Thus, the code above could also be written as:
-@example
-@group
-SCM
-mark_image (SCM image_smob)
-@{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- return image->update_func;
-@}
-@end group
-@end example
-
-
-Finally, when the collector encounters an unmarked smob during the sweep
-phase, it uses the smob's tag to find the appropriate @code{free}
-function for the smob. It then calls the function, passing it the smob
-as its only argument.
-
-The @code{free} function must release any resources used by the smob.
-However, it need not free objects managed by the collector; the
-collector will take care of them. For historical reasons, the return
-type of the @code{free} function should be @code{size_t}, an unsigned
-integral type; the @code{free} function should always return zero.
-
-Here is how we might write the @code{free} function for the image smob
-type:
-@example
-size_t
-free_image (SCM image_smob)
-@{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_free (image->pixels, image->width * image->height, "image pixels");
- scm_gc_free (image, sizeof (struct image), "image");
-
- return 0;
-@}
-@end example
-
-During the sweep phase, the garbage collector will clear the mark bits
-on all live objects. The code which implements a smob need not do this
-itself.
-
-There is no way for smob code to be notified when collection is
-complete.
-
-It is usually a good idea to minimize the amount of processing done
-during garbage collection; keep @code{mark} and @code{free} functions
-very simple. Since collections occur at unpredictable times, it is easy
-for any unusual activity to interfere with normal code.
-
-
-@node A Common Mistake In Allocating Smobs, Garbage Collecting Simple Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)
-@subsection A Common Mistake In Allocating Smobs
-
-When constructing new objects, you must be careful that the garbage
-collector can always find any new objects you allocate. For example,
-suppose we wrote the @code{make_image} function this way:
-
-@example
-SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-@{
- struct image *image;
- SCM image_smob;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
-
- /* THESE TWO LINES HAVE CHANGED: */
- image->name = scm_string_copy (name);
- image->update_func = scm_c_define_gsubr (@dots{});
-
- SCM_NEWCELL (image_smob);
- SCM_SET_CELL_WORD_1 (image_smob, image);
- SCM_SET_CELL_TYPE (image_smob, image_tag);
-
- return image_smob;
-@}
-@end example
-
-This code is incorrect. The calls to @code{scm_string_copy} and
-@code{scm_c_define_gsubr} allocate fresh objects. Allocating any new object
-may cause the garbage collector to run. If @code{scm_c_define_gsubr}
-invokes a collection, the garbage collector has no way to discover that
-@code{image->name} points to the new string object; the @code{image}
-structure is not yet part of any Scheme object, so the garbage collector
-will not traverse it. Since the garbage collector cannot find any
-references to the new string object, it will free it, leaving
-@code{image} pointing to a dead object.
-
-A correct implementation might say, instead:
-
-@example
- image->name = SCM_BOOL_F;
- image->update_func = SCM_BOOL_F;
-
- SCM_NEWCELL (image_smob);
- SCM_SET_CELL_WORD_1 (image_smob, image);
- SCM_SET_CELL_TYPE (image_smob, image_tag);
-
- image->name = scm_string_copy (name);
- image->update_func = scm_c_define_gsubr (@dots{});
-
- return image_smob;
-@end example
-
-Now, by the time we allocate the new string and function objects,
-@code{image_smob} points to @code{image}. If the garbage collector
-scans the stack, it will find a reference to @code{image_smob} and
-traverse @code{image}, so any objects @code{image} points to will be
-preserved.
-
-
-@node Garbage Collecting Simple Smobs, A Complete Example, A Common Mistake In Allocating Smobs, Defining New Types (Smobs)
-@subsection Garbage Collecting Simple Smobs
-
-It is often useful to define very simple smob types --- smobs which have
-no data to mark, other than the cell itself, or smobs whose first data
-word is simply an ordinary Scheme object, to be marked recursively.
-Guile provides some functions to handle these common cases; you can use
-this function as your smob type's @code{mark} function, if your smob's
-structure is simple enough.
-
-If the smob refers to no other Scheme objects, then no action is
-necessary; the garbage collector has already marked the smob cell
-itself. In that case, you can use zero as your mark function.
-
-@deftypefun SCM scm_markcdr (SCM @var{x})
-Mark the references in the smob @var{x}, assuming that @var{x}'s first
-data word contains an ordinary Scheme object, and @var{x} refers to no
-other objects. This function simply returns @var{x}'s first data word.
-
-This is only useful for simple smobs created by @code{SCM_NEWSMOB} or
-@code{SCM_RETURN_NEWSMOB}, not for smobs allocated as double cells.
-@end deftypefun
-
-@deftypefun size_t scm_free0 (SCM @var{x})
-Do nothing; return zero. This function is appropriate for smobs that
-use either zero or @code{scm_markcdr} as their marking functions, and
-refer to no heap storage, including memory managed by @code{malloc},
-other than the smob's header cell.
-
-This function should not be needed anymore, because simply passing
-@code{NULL} as the free function does the same.
-@end deftypefun
-
-
-@node A Complete Example
-@subsection A Complete Example
-
-Here is the complete text of the implementation of the image datatype,
-as presented in the sections above. We also provide a definition for
-the smob's @code{print} function, and make some objects and functions
-static, to clarify exactly what the surrounding code is using.
-
-As mentioned above, you can find this code in the Guile distribution, in
-@file{doc/example-smob}. That directory includes a makefile and a
-suitable @code{main} function, so you can build a complete interactive
-Guile shell, extended with the datatypes described here.)
-
-@example
-/* file "image-type.c" */
-
-#include <stdlib.h>
-#include <libguile.h>
-
-static scm_t_bits image_tag;
-
-struct image @{
- int width, height;
- char *pixels;
-
- /* The name of this image */
- SCM name;
-
- /* A function to call when this image is
- modified, e.g., to update the screen,
- or SCM_BOOL_F if no action necessary */
- SCM update_func;
-@};
-
-static SCM
-make_image (SCM name, SCM s_width, SCM s_height)
-@{
- struct image *image;
- int width, height;
-
- SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
- SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
- SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
-
- width = SCM_INUM (s_width);
- height = SCM_INUM (s_height);
-
- image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
- image->width = width;
- image->height = height;
- image->pixels = scm_gc_malloc (width * height, "image pixels");
- image->name = name;
- image->update_func = SCM_BOOL_F;
-
- SCM_RETURN_NEWSMOB (image_tag, image);
-@}
-
-static SCM
-clear_image (SCM image_smob)
-@{
- int area;
- struct image *image;
-
- SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
- image_smob, SCM_ARG1, "clear-image");
-
- image = (struct image *) SCM_SMOB_DATA (image_smob);
- area = image->width * image->height;
- memset (image->pixels, 0, area);
-
- /* Invoke the image's update function. */
- if (image->update_func != SCM_BOOL_F)
- scm_apply (image->update_func, SCM_EOL, SCM_EOL);
-
- return SCM_UNSPECIFIED;
-@}
-
-static SCM
-mark_image (SCM image_smob)
-@{
- /* Mark the image's name and update function. */
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_mark (image->name);
- return image->update_func;
-@}
-
-static size_t
-free_image (SCM image_smob)
-@{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_gc_free (image->pixels, image->width * image->height, "image pixels");
- scm_gc_free (image, sizeof (struct image), "image");
-
- return 0;
-@}
-
-static int
-print_image (SCM image_smob, SCM port, scm_print_state *pstate)
-@{
- struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
-
- scm_puts ("#<image ", port);
- scm_display (image->name, port);
- scm_puts (">", port);
-
- /* non-zero means success */
- return 1;
-@}
-
-void
-init_image_type (void)
-@{
- image_tag = scm_make_smob_type ("image", sizeof (struct image));
- scm_set_smob_mark (image_tag, mark_image);
- scm_set_smob_free (image_tag, free_image);
- scm_set_smob_print (image_tag, print_image);
-
- scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
- scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
-@}
-@end example
-
-Here is a sample build and interaction with the code from the
-@file{example-smob} directory, on the author's machine:
-
-@example
-zwingli:example-smob$ make CC=gcc
-gcc `guile-config compile` -c image-type.c -o image-type.o
-gcc `guile-config compile` -c myguile.c -o myguile.o
-gcc image-type.o myguile.o `guile-config link` -o myguile
-zwingli:example-smob$ ./myguile
-guile> make-image
-#<primitive-procedure make-image>
-guile> (define i (make-image "Whistler's Mother" 100 100))
-guile> i
-#<image Whistler's Mother>
-guile> (clear-image i)
-guile> (clear-image 4)
-ERROR: In procedure clear-image in expression (clear-image 4):
-ERROR: Wrong type argument in position 1: 4
-ABORT: (wrong-type-arg)
-
-Type "(backtrace)" to get more information.
-guile>
-@end example
-
-@c essay @bye
diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi
deleted file mode 100644
index 06a61473d..000000000
--- a/doc/ref/debugging.texi
+++ /dev/null
@@ -1,115 +0,0 @@
-@page
-@node Debugging Features
-@chapter Debugging Features
-
-@c --- The title and introduction of this appendix need to
-@c distinguish this clearly from the chapter on the internal
-@c debugging interface.
-
-When debugging a program, programmers often find it helpful to examine
-the program's internal status while it runs: the values of internal
-variables, the choices made in @code{if} and @code{cond} statements, and
-so forth. Guile Scheme provides a debugging interface that programmers
-can use to single-step through Scheme functions and examine symbol
-bindings. This is different from the @ref{Debugging}, which permits
-programmers to debug the Guile interpreter itself. Most programmers
-will be more interested in debugging their own Scheme programs than the
-interpreter which evaluates them.
-
-[FIXME: should we include examples of traditional debuggers
-and explain why they can't be used to debug interpreted Scheme or Lisp?]
-
-@menu
-* Single-Step:: Execute a program or function one step at a time.
-* Trace:: Print a report each time a given function is called.
-* Backtrace:: See a list of the statements that caused an error.
-@end menu
-
-
-@node Single-Step
-@section Single-Step
-
-
-@node Trace
-@section Trace
-
-When a function is @dfn{traced}, it means that every call to that
-function is reported to the user during a program run. This can help a
-programmer determine whether a function is being called at the wrong
-time or with the wrong set of arguments.
-
-@defun trace function
-Enable debug tracing on @code{function}. While a program is being run, Guile
-will print a brief report at each call to a traced function,
-advising the user which function was called and the arguments that were
-passed to it.
-@end defun
-
-@defun untrace function
-Disable debug tracing for @code{function}.
-@end defun
-
-Example:
-
-@lisp
-(define (rev ls)
- (if (null? ls)
- '()
- (append (rev (cdr ls))
- (cons (car ls) '())))) @result{} rev
-
-(trace rev) @result{} (rev)
-
-(rev '(a b c d e))
-@result{} [rev (a b c d e)]
- | [rev (b c d e)]
- | | [rev (c d e)]
- | | | [rev (d e)]
- | | | | [rev (e)]
- | | | | | [rev ()]
- | | | | | ()
- | | | | (e)
- | | | (e d)
- | | (e d c)
- | (e d c b)
- (e d c b a)
- (e d c b a)
-@end lisp
-
-Note the way Guile indents the output, illustrating the depth of
-execution at each function call. This can be used to demonstrate, for
-example, that Guile implements self-tail-recursion properly:
-
-@lisp
-(define (rev ls sl)
- (if (null? ls)
- sl
- (rev (cdr ls)
- (cons (car ls) sl)))) @result{} rev
-
-(trace rev) @result{} (rev)
-
-(rev '(a b c d e) '())
-@result{} [rev (a b c d e) ()]
- [rev (b c d e) (a)]
- [rev (c d e) (b a)]
- [rev (d e) (c b a)]
- [rev (e) (d c b a)]
- [rev () (e d c b a)]
- (e d c b a)
- (e d c b a)
-@end lisp
-
-Since the tail call is effectively optimized to a @code{goto} statement,
-there is no need for Guile to create a new stack frame for each
-iteration. Using @code{trace} here helps us see why this is so.
-
-
-@node Backtrace
-@section Backtrace
-
-@deffn {Scheme Procedure} backtrace
-@deffnx {C Function} scm_backtrace ()
-Display a backtrace of the stack saved by the last error
-to the current output port.
-@end deffn
diff --git a/doc/ref/deprecated.texi b/doc/ref/deprecated.texi
deleted file mode 100644
index 8d335a936..000000000
--- a/doc/ref/deprecated.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@page
-@node Deprecated
-@chapter Deprecated
diff --git a/doc/ref/expect.texi b/doc/ref/expect.texi
deleted file mode 100644
index 7e169e428..000000000
--- a/doc/ref/expect.texi
+++ /dev/null
@@ -1,142 +0,0 @@
-@page
-@node Expect
-@chapter Expect
-
-The macros in this section are made available with:
-
-@smalllisp
-(use-modules (ice-9 expect))
-@end smalllisp
-
-@code{expect} is a macro for selecting actions based on the output from
-a port. The name comes from a tool of similar functionality by Don Libes.
-Actions can be taken when a particular string is matched, when a timeout
-occurs, or when end-of-file is seen on the port. The @code{expect} macro
-is described below; @code{expect-strings} is a front-end to @code{expect}
-based on regexec (see the regular expression documentation).
-
-@defmac expect-strings clause @dots{}
-By default, @code{expect-strings} will read from the current input port.
-The first term in each clause consists of an expression evaluating to
-a string pattern (regular expression). As characters
-are read one-by-one from the port, they are accumulated in a buffer string
-which is matched against each of the patterns. When a
-pattern matches, the remaining expression(s) in
-the clause are evaluated and the value of the last is returned. For example:
-
-@smalllisp
-(with-input-from-file "/etc/passwd"
- (lambda ()
- (expect-strings
- ("^nobody" (display "Got a nobody user.\n")
- (display "That's no problem.\n"))
- ("^daemon" (display "Got a daemon user.\n")))))
-@end smalllisp
-
-The regular expression is compiled with the @code{REG_NEWLINE} flag, so
-that the ^ and $ anchors will match at any newline, not just at the start
-and end of the string.
-
-There are two other ways to write a clause:
-
-The expression(s) to evaluate
-can be omitted, in which case the result of the regular expression match
-(converted to strings, as obtained from regexec with match-pick set to "")
-will be returned if the pattern matches.
-
-The symbol @code{=>} can be used to indicate that the expression is a
-procedure which will accept the result of a successful regular expression
-match. E.g.,
-
-@smalllisp
-("^daemon" => write)
-("^d\\(aemon\\)" => (lambda args (for-each write args)))
-("^da\\(em\\)on" => (lambda (all sub)
- (write all) (newline)
- (write sub) (newline)))
-@end smalllisp
-
-The order of the substrings corresponds to the order in which the
-opening brackets occur.
-
-A number of variables can be used to control the behaviour
-of @code{expect} (and @code{expect-strings}).
-Most have default top-level bindings to the value @code{#f},
-which produces the default behaviour.
-They can be redefined at the
-top level or locally bound in a form enclosing the expect expression.
-
-@table @code
-@item expect-port
-A port to read characters from, instead of the current input port.
-@item expect-timeout
-@code{expect} will terminate after this number of
-seconds, returning @code{#f} or the value returned by expect-timeout-proc.
-@item expect-timeout-proc
-A procedure called if timeout occurs. The procedure takes a single argument:
-the accumulated string.
-@item expect-eof-proc
-A procedure called if end-of-file is detected on the input port. The
-procedure takes a single argument: the accumulated string.
-@item expect-char-proc
-A procedure to be called every time a character is read from the
-port. The procedure takes a single argument: the character which was read.
-@item expect-strings-compile-flags
-Flags to be used when compiling a regular expression, which are passed
-to @code{make-regexp} @xref{Regexp Functions}. The default value
-is @code{regexp/newline}.
-@item expect-strings-exec-flags
-Flags to be used when executing a regular expression, which are
-passed to regexp-exec @xref{Regexp Functions}.
-The default value is @code{regexp/noteol}, which prevents @code{$}
-from matching the end of the string while it is still accumulating,
-but still allows it to match after a line break or at the end of file.
-@end table
-
-Here's an example using all of the variables:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd"))
- (expect-timeout 1)
- (expect-timeout-proc
- (lambda (s) (display "Times up!\n")))
- (expect-eof-proc
- (lambda (s) (display "Reached the end of the file!\n")))
- (expect-char-proc display)
- (expect-strings-compile-flags (logior regexp/newline regexp/icase))
- (expect-strings-exec-flags 0))
- (expect-strings
- ("^nobody" (display "Got a nobody user\n"))))
-@end smalllisp
-@end defmac
-
-@defmac expect clause @dots{}
-@code{expect} is used in the same way as @code{expect-strings},
-but tests are specified not as patterns, but as procedures. The
-procedures are called in turn after each character is read from the
-port, with two arguments: the value of the accumulated string and
-a flag to indicate whether end-of-file has been reached. The flag
-will usually be @code{#f}, but if end-of-file is reached, the procedures
-are called an additional time with the final accumulated string and
-@code{#t}.
-
-The test is successful if the procedure returns a non-false value.
-
-If the @code{=>} syntax is used, then if the test succeeds it must return
-a list containing the arguments to be provided to the corresponding
-expression.
-
-In the following example, a string will only be matched at the beginning
-of the file:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd")))
- (expect
- ((lambda (s eof?) (string=? s "fnord!"))
- (display "Got a nobody user!\n"))))
-@end smalllisp
-
-The control variables described for @code{expect-strings} also
-influence the behaviour of @code{expect}, with the exception of
-variables whose names begin with @code{expect-strings-}.
-@end defmac
diff --git a/doc/ref/extend.texi b/doc/ref/extend.texi
deleted file mode 100644
index 5c72bef33..000000000
--- a/doc/ref/extend.texi
+++ /dev/null
@@ -1,44 +0,0 @@
-@page
-@node Libguile Intro
-@chapter Using Guile as an Extension Language
-
-The chapters in this part of the manual explain how to use Guile as a
-powerful application extension language.
-
-An important change for the 1.6.x series of Guile releases is that the
-GH interface is now deprecated. For the reasoning behind this decision,
-see @xref{GH deprecation}. The GH interface will continue to be
-supported for the 1.6.x and 1.8.x release series, but will be dropped
-thereafter, so developers are encouraged to switch progressively to the
-scm interface. The last chapter in this part of the manual (@pxref{GH})
-documents both how to use GH and how to switch from GH to scm.
-
-The Guile developers believe that clarification of the GH vs. scm
-debate, and the consequent deprecation of the GH interface, are in the
-long term interests of the project. However it does create an
-unfortunate situation for developers who want to start a project using
-Guile and so read the manual to find out how to proceed. They will
-discover that the GH interface, although quite well documented, is
-deprecated, but that there is almost no adequate documentation for its
-theoretical replacement, the scm interface. Moreover, the scm interface
-still has the odd few rough edges which need smoothing down.
-
-Therefore, although deprecated, it is quite OK to continue to use the GH
-interface if you feel uncomfortable with the `scm_' interface as it
-stands today. By the time that support for GH is dropped, we plan to
-have thoroughly documented the `scm_' interface, and to have enhanced it
-such that conversion from GH to the `scm_' interface will be very
-straightforward, and probably mostly automated.
-
-As far as documentation of the scm interface is concerned, the current
-position is that it is a bit confused, but that the situation should
-improve rapidly once the 1.6.0 release is out. The plan is to refocus
-the bulk of Part II, currently ``Guile Scheme'', as the ``Guile API
-Reference'' so that it covers both Scheme and C interfaces. (This makes
-sense because almost all of Guile's primitive procedures on the Scheme
-level --- e.g. @code{memq} --- are also available as C level primitives
-in the scm interface --- e.g. @code{scm_memq}.) There will then remain
-a certain amount of Scheme-specific (such as the ``Basic Ideas''
-chapter) and C-specific documentation (such as SMOB usage and
-interaction with the garbage collector) to collect into corresponding
-chapters.
diff --git a/doc/ref/gh.texi b/doc/ref/gh.texi
deleted file mode 100644
index 1cadc168a..000000000
--- a/doc/ref/gh.texi
+++ /dev/null
@@ -1,1170 +0,0 @@
-@page
-@node GH
-@chapter GH: A Portable C to Scheme Interface
-@cindex libguile - gh
-@cindex gh
-@cindex gh - reference manual
-
-This chapter shows how to use the GH interface to call Guile from your
-application's C code, and to add new Scheme level procedures to Guile
-whose behaviour is specified by application specific code written in C.
-
-Note, however, that the GH interface is now deprecated, and developers
-are encouraged to switch to using the scm interface instead. Therefore,
-for each GH feature, this chapter should also document how to achieve
-the same result using the scm interface.
-
-@menu
-* GH deprecation:: Why the GH interface is now deprecated.
-* gh preliminaries::
-* Data types and constants defined by gh::
-* Starting and controlling the interpreter::
-* Error messages::
-* Executing Scheme code::
-* Defining new Scheme procedures in C::
-* Converting data between C and Scheme::
-* Type predicates::
-* Equality predicates::
-* Memory allocation and garbage collection::
-* Calling Scheme procedures from C::
-* Mixing gh and scm APIs::
-* scm transition summary::
-@end menu
-
-
-@node GH deprecation
-@section Why the GH Interface is Now Deprecated
-
-Historically, the GH interface was the product of a practical problem
-and a neat idea. The practical problem was that the interface of the
-@code{scm_} functions with which Guile itself was written (inherited
-from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
-details of the internal data representation that it was extremely
-difficult to write a Guile extension using these functions. The neat
-idea was to define a high level language extension interface in such a
-way that other extension language projects, not just Guile, would be
-able to provide an implementation of that interface; then applications
-using this interface could be compiled with whichever of the various
-available implementations they chose. So the GH interface was created,
-and advertised both as the recommended interface for application
-developers wishing to use Guile, and as a portable high level interface
-that could theoretically be implemented by other extension language
-projects.
-
-Time passed, and various things changed. Crucially, an enormous number
-of improvements were made to the @code{scm_} interface that Guile itself
-uses in its implementation, with the result that it is now both easy and
-comfortable to write a Guile extension with this interface. At the same
-time, the contents of the GH interface were somewhat neglected by the
-core Guile developers, such that some key operations --- such as smob
-creation and management --- are simply not possible using GH alone.
-Finally, the idea of multiple implementations of the GH interface did
-not really crystallize (apart, I believe, from a short lived
-implementation by the MzScheme project).
-
-For all these reasons, the Guile developers have decided to deprecate
-the GH interface --- which means that support for GH will be completely
-removed after the next few releases --- and to focus only on the
-@code{scm_} interface, with additions to ensure that it is as easy to
-use in all respects as GH was.
-
-It remains an open question whether a deep kind of interface portability
-would be useful for extension language-based applications, and it may
-still be an interesting project to attempt to define a corresponding
-GH-like interface, but the Guile developers no longer plan to try to do
-this as part of the core Guile project.
-
-
-@node gh preliminaries
-@section gh preliminaries
-
-To use gh, you must have the following toward the beginning of your C
-source:
-@smallexample
-#include <guile/gh.h>
-@end smallexample
-@cindex gh - headers
-
-When you link, you will have to add at least @code{-lguile} to the list
-of libraries. If you are using more of Guile than the basic Scheme
-interpreter, you will have to add more libraries.
-@cindex gh - linking
-
-
-@node Data types and constants defined by gh
-@section Data types and constants defined by gh
-@cindex libguile - data types
-
-The following C constants and data types are defined in gh:
-
-@deftp {Data type} SCM
-This is a C data type used to store all Scheme data, no matter what the
-Scheme type. Values are converted between C data types and the SCM type
-with utility functions described below (@pxref{Converting data between C
-and Scheme}). [FIXME: put in references to Jim's essay and so forth.]
-@end deftp
-@cindex SCM data type
-
-@defvr Constant SCM_BOOL_T
-@defvrx Constant SCM_BOOL_F
-The @emph{Scheme} values returned by many boolean procedures in
-libguile.
-
-This can cause confusion because they are different from 0 and 1. In
-testing a boolean function in libguile programming, you must always make
-sure that you check the spec: @code{gh_} and @code{scm_} functions will
-usually return @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, but other C
-functions usually can be tested against 0 and 1, so programmers' fingers
-tend to just type @code{if (boolean_function()) @{ ... @}}
-@end defvr
-
-@defvr Constant SCM_UNSPECIFIED
-This is a SCM value that is not the same as any legal Scheme value. It
-is the value that a Scheme function returns when its specification says
-that its return value is unspecified.
-@end defvr
-
-@defvr Constant SCM_UNDEFINED
-This is another SCM value that is not the same as any legal Scheme
-value. It is the value used to mark variables that do not yet have a
-value, and it is also used in C to terminate functions with variable
-numbers of arguments, such as @code{gh_list()}.
-@end defvr
-
-
-@node Starting and controlling the interpreter
-@section Starting and controlling the interpreter
-@cindex libguile - start interpreter
-
-In almost every case, your first @code{gh_} call will be:
-
-@deftypefun void gh_enter (int @var{argc}, char *@var{argv}[], void (*@var{main_prog})())
-Starts up a Scheme interpreter with all the builtin Scheme primitives.
-@code{gh_enter()} never exits, and the user's code should all be in the
-@code{@var{main_prog}()} function. @code{argc} and @code{argv} will be
-passed to @var{main_prog}.
-
-@deftypefun void main_prog (int @var{argc}, char *@var{argv}[])
-This is the user's main program. It will be invoked by
-@code{gh_enter()} after Guile has been started up.
-@end deftypefun
-
-Note that you can use @code{gh_repl} inside @code{gh_enter} (in other
-words, inside the code for @code{main-prog}) if you want the program to
-be controlled by a Scheme read-eval-print loop.
-@end deftypefun
-
-@cindex read eval print loop -- from the gh_ interface
-@cindex REPL -- from the gh_ interface
-A convenience routine which enters the Guile interpreter with the
-standard Guile read-eval-print loop (@dfn{REPL}) is:
-
-@deftypefun void gh_repl (int @var{argc}, char *@var{argv}[])
-Enters the Scheme interpreter giving control to the Scheme REPL.
-Arguments are processed as if the Guile program @file{guile} were being
-invoked.
-
-Note that @code{gh_repl} should be used @emph{inside} @code{gh_enter},
-since any Guile interpreter calls are meaningless unless they happen in
-the context of the interpreter.
-
-Also note that when you use @code{gh_repl}, your program will be
-controlled by Guile's REPL (which is written in Scheme and has many
-useful features). Use straight C code inside @code{gh_enter} if you
-want to maintain execution control in your C program.
-@end deftypefun
-
-You will typically use @code{gh_enter} and @code{gh_repl} when you
-want a Guile interpreter enhanced by your own libraries, but otherwise
-quite normal. For example, to build a Guile--derived program that
-includes some random number routines @dfn{GSL} (GNU Scientific Library),
-you would write a C program that looks like this:
-
-@smallexample
-#include <guile/gh.h>
-#include <gsl_ran.h>
-
-/* random number suite */
-SCM gw_ran_seed(SCM s)
-@{
- gsl_ran_seed(gh_scm2int(s));
- return SCM_UNSPECIFIED;
-@}
-
-SCM gw_ran_random()
-@{
- SCM x;
-
- x = gh_ulong2scm(gsl_ran_random());
- return x;
-@}
-
-SCM gw_ran_uniform()
-@{
- SCM x;
-
- x = gh_double2scm(gsl_ran_uniform());
- return x;
-@}
-SCM gw_ran_max()
-@{
- return gh_double2scm(gsl_ran_max());
-@}
-
-void
-init_gsl()
-@{
- /* random number suite */
- gh_new_procedure("gsl-ran-seed", gw_ran_seed, 1, 0, 0);
- gh_new_procedure("gsl-ran-random", gw_ran_random, 0, 0, 0);
- gh_new_procedure("gsl-ran-uniform", gw_ran_uniform, 0, 0, 0);
- gh_new_procedure("gsl-ran-max", gw_ran_max, 0, 0, 0);
-@}
-
-void
-main_prog (int argc, char *argv[])
-@{
- init_gsl();
-
- gh_repl(argc, argv);
-@}
-
-int
-main (int argc, char *argv[])
-@{
- gh_enter (argc, argv, main_prog);
-@}
-@end smallexample
-
-Then, supposing the C program is in @file{guile-gsl.c}, you could
-compile it with @kbd{gcc -o guile-gsl guile-gsl.c -lguile -lgsl}.
-
-The resulting program @file{guile-gsl} would have new primitive
-procedures @code{gsl-ran-random}, @code{gsl-ran-gaussian} and so forth.
-
-
-@node Error messages
-@section Error messages
-@cindex libguile - error messages
-@cindex error messages in libguile
-
-[FIXME: need to fill this based on Jim's new mechanism]
-
-
-@node Executing Scheme code
-@section Executing Scheme code
-@cindex libguile - executing Scheme
-@cindex executing Scheme
-
-Once you have an interpreter running, you can ask it to evaluate Scheme
-code. There are two calls that implement this:
-
-@deftypefun SCM gh_eval_str (char *@var{scheme_code})
-This asks the interpreter to evaluate a single string of Scheme code,
-and returns the result of the last expression evaluated.
-
-Note that the line of code in @var{scheme_code} must be a well formed
-Scheme expression. If you have many lines of code before you balance
-parentheses, you must either concatenate them into one string, or use
-@code{gh_eval_file()}.
-@end deftypefun
-
-@deftypefun SCM gh_eval_file (char *@var{fname})
-@deftypefunx SCM gh_load (char *@var{fname})
-@code{gh_eval_file} is completely analogous to @code{gh_eval_str()},
-except that a whole file is evaluated instead of a string.
-@code{gh_eval_file} returns @code{SCM_UNSPECIFIED}.
-
-@code{gh_load} is identical to @code{gh_eval_file} (it's a macro that
-calls @code{gh_eval_file} on its argument). It is provided to start
-making the @code{gh_} interface match the R5RS Scheme procedures
-closely.
-@end deftypefun
-
-
-@node Defining new Scheme procedures in C
-@section Defining new Scheme procedures in C
-@cindex libguile - new procedures
-@cindex new procedures
-@cindex procedures, new
-@cindex new primitives
-@cindex primitives, new
-
-The real interface between C and Scheme comes when you can write new
-Scheme procedures in C. This is done through the routine
-
-
-@deftypefn {Libguile high} SCM gh_new_procedure (char *@var{proc_name}, SCM (*@var{fn})(), int @var{n_required_args}, int @var{n_optional_args}, int @var{restp})
-@code{gh_new_procedure} defines a new Scheme procedure. Its Scheme name
-will be @var{proc_name}, it will be implemented by the C function
-(*@var{fn})(), it will take at least @var{n_required_args} arguments,
-and at most @var{n_optional_args} extra arguments.
-
-When the @var{restp} parameter is 1, the procedure takes a final
-argument: a list of remaining parameters.
-
-@code{gh_new_procedure} returns an SCM value representing the procedure.
-
-The C function @var{fn} should have the form
-@deftypefn {Libguile high} SCM fn (SCM @var{req1}, SCM @var{req2}, ..., SCM @var{opt1}, SCM @var{opt2}, ..., SCM @var{rest_args})
-The arguments are all passed as SCM values, so the user will have to use
-the conversion functions to convert to standard C types.
-
-Examples of C functions used as new Scheme primitives can be found in
-the sample programs @code{learn0} and @code{learn1}.
-@end deftypefn
-
-@end deftypefn
-
-@strong{Rationale:} this is the correct way to define new Scheme
-procedures in C. The ugly mess of arguments is required because of how
-C handles procedures with variable numbers of arguments.
-
-@strong{Note:} what about documentation strings?
-
-@cartouche
-There are several important considerations to be made when writing the C
-routine @code{(*fn)()}.
-
-First of all the C routine has to return type @code{SCM}.
-
-Second, all arguments passed to the C function will be of type
-@code{SCM}.
-
-Third: the C routine is now subject to Scheme flow control, which means
-that it could be interrupted at any point, and then reentered. This
-means that you have to be very careful with operations such as
-allocating memory, modifying static data @dots{}
-
-Fourth: to get around the latter issue, you can use
-@code{GH_DEFER_INTS} and @code{GH_ALLOW_INTS}.
-@end cartouche
-
-@defmac GH_DEFER_INTS
-@defmacx GH_ALLOW_INTS
-These macros disable and re-enable Scheme's flow control. They
-@end defmac
-
-
-@c [??? have to do this right; maybe using subsections, or maybe creating a
-@c section called Flow control issues...]
-
-@c [??? Go into exhaustive detail with examples of the various possible
-@c combinations of required and optional args...]
-
-
-@node Converting data between C and Scheme
-@section Converting data between C and Scheme
-@cindex libguile - converting data
-@cindex data conversion
-@cindex converting data
-
-Guile provides mechanisms to convert data between C and Scheme. This
-allows new builtin procedures to understand their arguments (which are
-of type @code{SCM}) and return values of type @code{SCM}.
-
-
-@menu
-* C to Scheme::
-* Scheme to C::
-@end menu
-
-@node C to Scheme
-@subsection C to Scheme
-
-@deftypefun SCM gh_bool2scm (int @var{x})
-Returns @code{#f} if @var{x} is zero, @code{#t} otherwise.
-@end deftypefun
-
-@deftypefun SCM gh_ulong2scm (unsigned long @var{x})
-@deftypefunx SCM gh_long2scm (long @var{x})
-@deftypefunx SCM gh_double2scm (double @var{x})
-@deftypefunx SCM gh_char2scm (char @var{x})
-Returns a Scheme object with the value of the C quantity @var{x}.
-@end deftypefun
-
-@deftypefun SCM gh_str2scm (char *@var{s}, int @var{len})
-Returns a new Scheme string with the (not necessarily null-terminated) C
-array @var{s} data.
-@end deftypefun
-
-@deftypefun SCM gh_str02scm (char *@var{s})
-Returns a new Scheme string with the null-terminated C string @var{s}
-data.
-@end deftypefun
-
-@deftypefun SCM gh_set_substr (char *@var{src}, SCM @var{dst}, int @var{start}, int @var{len})
-Copy @var{len} characters at @var{src} into the @emph{existing} Scheme
-string @var{dst}, starting at @var{start}. @var{start} is an index into
-@var{dst}; zero means the beginning of the string.
-
-If @var{start} + @var{len} is off the end of @var{dst}, signal an
-out-of-range error.
-@end deftypefun
-
-@deftypefun SCM gh_symbol2scm (char *@var{name})
-Given a null-terminated string @var{name}, return the symbol with that
-name.
-@end deftypefun
-
-@deftypefun SCM gh_ints2scm (int *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_doubles2scm (double *@var{dptr}, int @var{n})
-Make a scheme vector containing the @var{n} ints or doubles at memory
-location @var{dptr}.
-@end deftypefun
-
-@deftypefun SCM gh_chars2byvect (char *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_shorts2svect (short *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_longs2ivect (long *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_ulongs2uvect (ulong *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_floats2fvect (float *@var{dptr}, int @var{n})
-@deftypefunx SCM gh_doubles2dvect (double *@var{dptr}, int @var{n})
-Make a scheme uniform vector containing the @var{n} chars, shorts,
-longs, unsigned longs, floats or doubles at memory location @var{dptr}.
-@end deftypefun
-
-
-
-@node Scheme to C
-@subsection Scheme to C
-
-@deftypefun int gh_scm2bool (SCM @var{obj})
-@deftypefunx {unsigned long} gh_scm2ulong (SCM @var{obj})
-@deftypefunx long gh_scm2long (SCM @var{obj})
-@deftypefunx double gh_scm2double (SCM @var{obj})
-@deftypefunx int gh_scm2char (SCM @var{obj})
-These routines convert the Scheme object to the given C type.
-@end deftypefun
-
-@deftypefun char *gh_scm2newstr (SCM @var{str}, int *@var{lenp})
-Given a Scheme string @var{str}, return a pointer to a new copy of its
-contents, followed by a null byte. If @var{lenp} is non-null, set
-@code{*@var{lenp}} to the string's length.
-
-This function uses malloc to obtain storage for the copy; the caller is
-responsible for freeing it.
-
-Note that Scheme strings may contain arbitrary data, including null
-characters. This means that null termination is not a reliable way to
-determine the length of the returned value. However, the function
-always copies the complete contents of @var{str}, and sets @var{*lenp}
-to the true length of the string (when @var{lenp} is non-null).
-@end deftypefun
-
-
-@deftypefun void gh_get_substr (SCM str, char *return_str, int *lenp)
-Copy @var{len} characters at @var{start} from the Scheme string
-@var{src} to memory at @var{dst}. @var{start} is an index into
-@var{src}; zero means the beginning of the string. @var{dst} has
-already been allocated by the caller.
-
-If @var{start} + @var{len} is off the end of @var{src}, signal an
-out-of-range error.
-@end deftypefun
-
-@deftypefun char *gh_symbol2newstr (SCM @var{sym}, int *@var{lenp})
-Takes a Scheme symbol and returns a string of the form
-@code{"'symbol-name"}. If @var{lenp} is non-null, the string's length
-is returned in @code{*@var{lenp}}.
-
-This function uses malloc to obtain storage for the returned string; the
-caller is responsible for freeing it.
-@end deftypefun
-
-@deftypefun char *gh_scm2chars (SCM @var{vector}, chars *@var{result})
-@deftypefunx short *gh_scm2shorts (SCM @var{vector}, short *@var{result})
-@deftypefunx long *gh_scm2longs (SCM @var{vector}, long *@var{result})
-@deftypefunx float *gh_scm2floats (SCM @var{vector}, float *@var{result})
-@deftypefunx double *gh_scm2doubles (SCM @var{vector}, double *@var{result})
-Copy the numbers in @var{vector} to the array pointed to by @var{result}
-and return it. If @var{result} is NULL, allocate a double array large
-enough.
-
-@var{vector} can be an ordinary vector, a weak vector, or a signed or
-unsigned uniform vector of the same type as the result array. For
-chars, @var{vector} can be a string or substring. For floats and
-doubles, @var{vector} can contain a mix of inexact and integer values.
-
-If @var{vector} is of unsigned type and contains values too large to fit
-in the signed destination array, those values will be wrapped around,
-that is, data will be copied as if the destination array was unsigned.
-@end deftypefun
-
-
-@node Type predicates
-@section Type predicates
-
-These C functions mirror Scheme's type predicate procedures with one
-important difference. The C routines return C boolean values (0 and 1)
-instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
-
-The Scheme notational convention of putting a @code{?} at the end of
-predicate procedure names is mirrored in C by placing @code{_p} at the
-end of the procedure. For example, @code{(pair? ...)} maps to
-@code{gh_pair_p(...)}.
-
-@deftypefun int gh_boolean_p (SCM @var{val})
-Returns 1 if @var{val} is a boolean, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_symbol_p (SCM @var{val})
-Returns 1 if @var{val} is a symbol, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_char_p (SCM @var{val})
-Returns 1 if @var{val} is a char, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_vector_p (SCM @var{val})
-Returns 1 if @var{val} is a vector, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_pair_p (SCM @var{val})
-Returns 1 if @var{val} is a pair, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_procedure_p (SCM @var{val})
-Returns 1 if @var{val} is a procedure, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_list_p (SCM @var{val})
-Returns 1 if @var{val} is a list, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_inexact_p (SCM @var{val})
-Returns 1 if @var{val} is an inexact number, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_exact_p (SCM @var{val})
-Returns 1 if @var{val} is an exact number, 0 otherwise.
-@end deftypefun
-
-
-@node Equality predicates
-@section Equality predicates
-
-These C functions mirror Scheme's equality predicate procedures with one
-important difference. The C routines return C boolean values (0 and 1)
-instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}.
-
-The Scheme notational convention of putting a @code{?} at the end of
-predicate procedure names is mirrored in C by placing @code{_p} at the
-end of the procedure. For example, @code{(equal? ...)} maps to
-@code{gh_equal_p(...)}.
-
-@deftypefun int gh_eq_p (SCM x, SCM y)
-Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
-@code{eq?} predicate, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_eqv_p (SCM x, SCM y)
-Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
-@code{eqv?} predicate, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_equal_p (SCM x, SCM y)
-Returns 1 if @var{x} and @var{y} are equal in the sense of Scheme's
-@code{equal?} predicate, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_string_equal_p (SCM @var{s1}, SCM @var{s2})
-Returns 1 if the strings @var{s1} and @var{s2} are equal, 0 otherwise.
-@end deftypefun
-
-@deftypefun int gh_null_p (SCM @var{l})
-Returns 1 if @var{l} is an empty list or pair; 0 otherwise.
-@end deftypefun
-
-
-@node Memory allocation and garbage collection
-@section Memory allocation and garbage collection
-
-@c [FIXME: flesh this out with some description of garbage collection in
-@c scm/guile]
-
-@c @deftypefun SCM gh_mkarray (int size)
-@c Allocate memory for a Scheme object in a garbage-collector-friendly
-@c manner.
-@c @end deftypefun
-
-
-@node Calling Scheme procedures from C
-@section Calling Scheme procedures from C
-
-Many of the Scheme primitives are available in the @code{gh_}
-interface; they take and return objects of type SCM, and one could
-basically use them to write C code that mimics Scheme code.
-
-I will list these routines here without much explanation, since what
-they do is the same as documented in @ref{Standard procedures, R5RS, ,
-r5rs, R5RS}. But I will point out that when a procedure takes a
-variable number of arguments (such as @code{gh_list}), you should pass
-the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
-
-@deftypefun SCM gh_define (char *@var{name}, SCM @var{val})
-Corresponds to the Scheme @code{(define name val)}: it binds a value to
-the given name (which is a C string). Returns the new object.
-@end deftypefun
-
-@heading Pairs and lists
-
-@deftypefun SCM gh_cons (SCM @var{a}, SCM @var{b})
-@deftypefunx SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
-These correspond to the Scheme @code{(cons a b)} and @code{(list l0 l1
-...)} procedures. Note that @code{gh_list()} is a C macro that invokes
-@code{scm_listify()}.
-@end deftypefun
-
-@deftypefun SCM gh_car (SCM @var{obj})
-@deftypefunx SCM gh_cdr (SCM @var{obj})
-@dots{}
-
-@deftypefunx SCM gh_c[ad][ad][ad][ad]r (SCM @var{obj})
-These correspond to the Scheme @code{(caadar ls)} procedures etc @dots{}
-@end deftypefun
-
-@deftypefun SCM gh_set_car_x(SCM @var{pair}, SCM @var{value})
-Modifies the CAR of @var{pair} to be @var{value}. This is equivalent to
-the Scheme procedure @code{(set-car! ...)}.
-@end deftypefun
-
-@deftypefun SCM gh_set_cdr_x(SCM @var{pair}, SCM @var{value})
-Modifies the CDR of @var{pair} to be @var{value}. This is equivalent to
-the Scheme procedure @code{(set-cdr! ...)}.
-@end deftypefun
-
-@deftypefun {unsigned long} gh_length (SCM @var{ls})
-Returns the length of the list.
-@end deftypefun
-
-@deftypefun SCM gh_append (SCM @var{args})
-@deftypefunx SCM gh_append2 (SCM @var{l1}, SCM @var{l2})
-@deftypefunx SCM gh_append3 (SCM @var{l1}, SCM @var{l2}, @var{l3})
-@deftypefunx SCM gh_append4 (SCM @var{l1}, SCM @var{l2}, @var{l3}, @var{l4})
-@code{gh_append()} takes @var{args}, which is a list of lists
-@code{(list1 list2 ...)}, and returns a list containing all the elements
-of the individual lists.
-
-A typical invocation of @code{gh_append()} to append 5 lists together
-would be
-@smallexample
- gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));
-@end smallexample
-
-The functions @code{gh_append2()}, @code{gh_append2()},
-@code{gh_append3()} and @code{gh_append4()} are convenience routines to
-make it easier for C programs to form the list of lists that goes as an
-argument to @code{gh_append()}.
-@end deftypefun
-
-@deftypefun SCM gh_reverse (SCM @var{ls})
-Returns a new list that has the same elements as @var{ls} but in the
-reverse order. Note that this is implemented as a macro which calls
-@code{scm_reverse()}.
-@end deftypefun
-
-@deftypefun SCM gh_list_tail (SCM @var{ls}, SCM @var{k})
-Returns the sublist of @var{ls} with the last @var{k} elements.
-@end deftypefun
-
-@deftypefun SCM gh_list_ref (SCM @var{ls}, SCM @var{k})
-Returns the @var{k}th element of the list @var{ls}.
-@end deftypefun
-
-@deftypefun SCM gh_memq (SCM @var{x}, SCM @var{ls})
-@deftypefunx SCM gh_memv (SCM @var{x}, SCM @var{ls})
-@deftypefunx SCM gh_member (SCM @var{x}, SCM @var{ls})
-These functions return the first sublist of @var{ls} whose CAR is
-@var{x}. They correspond to @code{(memq x ls)}, @code{(memv x ls)} and
-@code{(member x ls)}, and hence use (respectively) @code{eq?},
-@code{eqv?} and @code{equal?} to do comparisons.
-
-If @var{x} does not appear in @var{ls}, the value @code{SCM_BOOL_F} (not
-the empty list) is returned.
-
-Note that these functions are implemented as macros which call
-@code{scm_memq()}, @code{scm_memv()} and @code{scm_member()}
-respectively.
-@end deftypefun
-
-@deftypefun SCM gh_assq (SCM @var{x}, SCM @var{alist})
-@deftypefunx SCM gh_assv (SCM @var{x}, SCM @var{alist})
-@deftypefunx SCM gh_assoc (SCM @var{x}, SCM @var{alist})
-These functions search an @dfn{association list} (list of pairs)
-@var{alist} for the first pair whose CAR is @var{x}, and they return
-that pair.
-
-If no pair in @var{alist} has @var{x} as its CAR, the value
-@code{SCM_BOOL_F} (not the empty list) is returned.
-
-Note that these functions are implemented as macros which call
-@code{scm_assq()}, @code{scm_assv()} and @code{scm_assoc()}
-respectively.
-@end deftypefun
-
-
-@heading Symbols
-
-@c @deftypefun SCM gh_symbol (SCM str, SCM len)
-@c @deftypefunx SCM gh_tmp_symbol (SCM str, SCM len)
-@c Takes the given string @var{str} of length @var{len} and returns a
-@c symbol corresponding to that string.
-@c @end deftypefun
-
-
-@heading Vectors
-
-@deftypefun SCM gh_make_vector (SCM @var{n}, SCM @var{fill})
-@deftypefunx SCM gh_vector (SCM @var{ls})
-@deftypefunx SCM gh_vector_ref (SCM @var{v}, SCM @var{i})
-@deftypefunx SCM gh_vector_set (SCM @var{v}, SCM @var{i}, SCM @var{val})
-@deftypefunx {unsigned long} gh_vector_length (SCM @var{v})
-@deftypefunx SCM gh_list_to_vector (SCM @var{ls})
-These correspond to the Scheme @code{(make-vector n fill)},
-@code{(vector a b c ...)} @code{(vector-ref v i)} @code{(vector-set v i
-value)} @code{(vector-length v)} @code{(list->vector ls)} procedures.
-
-The correspondence is not perfect for @code{gh_vector}: this routine
-takes a list @var{ls} instead of the individual list elements, thus
-making it identical to @code{gh_list_to_vector}.
-
-There is also a difference in gh_vector_length: the value returned is a
-C @code{unsigned long} instead of an SCM object.
-@end deftypefun
-
-
-@heading Procedures
-
-@c @deftypefun SCM gh_make_subr (SCM (*@var{fn})(), int @var{req}, int @var{opt}, int @var{restp}, char *@var{sym})
-@c Make the C function @var{fn} available to Scheme programs. The function
-@c will be bound to the symbol @var{sym}. The arguments @var{req},
-@c @var{opt} and @var{restp} describe @var{fn}'s calling conventions. The
-@c function must take @var{req} required arguments and may take @var{opt}
-@c optional arguments. Any optional arguments which are not supplied by
-@c the caller will be bound to @var{SCM_UNSPECIFIED}. If @var{restp} is
-@c non-zero, it means that @var{fn} may be called with an arbitrary number
-@c of arguments, and that any extra arguments supplied by the caller will
-@c be passed to @var{fn} as a list. The @var{restp} argument is exactly
-@c like Scheme's @code{(lambda (arg1 arg2 . arglist))} calling convention.
-@c
-@c For example, the procedure @code{read-line}, which takes optional
-@c @var{port} and @var{handle-delim} arguments, would be declared like so:
-@c
-@c @example
-@c SCM scm_read_line (SCM port, SCM handle_delim);
-@c gh_make_subr (scm_read_line, 0, 2, 0, "read-line");
-@c @end example
-@c
-@c The @var{req} argument to @code{gh_make_subr} is 0 to indicate that
-@c there are no required arguments, so @code{read-line} may be called
-@c without any arguments at all. The @var{opt} argument is 2, to indicate
-@c that both the @var{port} and @var{handle_delim} arguments to
-@c @code{scm_read_line} are optional, and will be bound to
-@c @code{SCM_UNSPECIFIED} if the calling program does not supply them.
-@c Because the @var{restp} argument is 0, this function may not be called
-@c with more than two arguments.
-@c @end deftypefun
-
-@deftypefun SCM gh_apply (SCM proc, SCM args)
-Call the Scheme procedure @var{proc}, with the elements of @var{args} as
-arguments. @var{args} must be a proper list.
-@end deftypefun
-
-@deftypefun SCM gh_call0 (SCM proc)
-@deftypefunx SCM gh_call1 (SCM proc, SCM arg)
-@deftypefunx SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
-@deftypefunx SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
-Call the Scheme procedure @var{proc} with no arguments
-(@code{gh_call0}), one argument (@code{gh_call1}), and so on. You can
-get the same effect by wrapping the arguments up into a list, and
-calling @code{gh_apply}; Guile provides these functions for convenience.
-@end deftypefun
-
-
-@deftypefun SCM gh_catch (SCM key, SCM thunk, SCM handler)
-@deftypefunx SCM gh_throw (SCM key, SCM args)
-Corresponds to the Scheme @code{catch} and @code{throw} procedures,
-which in Guile are provided as primitives.
-@end deftypefun
-
-@c [FIXME: must add the I/O section in gscm.h]
-
-@deftypefun SCM gh_is_eq (SCM a, SCM b)
-@deftypefunx SCM gh_is_eqv (SCM a, SCM b)
-@deftypefunx SCM gh_is_equal (SCM a, SCM b)
-These correspond to the Scheme @code{eq?}, @code{eqv?} and @code{equal?}
-predicates.
-@end deftypefun
-
-@deftypefun int gh_obj_length (SCM @var{obj})
-Returns the raw object length.
-@end deftypefun
-
-@heading Data lookup
-
-For now I just include Tim Pierce's comments from the @file{gh_data.c}
-file; it should be organized into a documentation of the two functions
-here.
-
-@smallexample
-/* Data lookups between C and Scheme
-
- Look up a symbol with a given name, and return the object to which
- it is bound. gh_lookup examines the Guile top level, and
- gh_module_lookup checks the module name space specified by the
- `vec' argument.
-
- The return value is the Scheme object to which SNAME is bound, or
- SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
- should this be SCM_UNSPECIFIED? Can a symbol ever legitimately be
- bound to SCM_UNDEFINED or SCM_UNSPECIFIED? What is the difference?
- -twp] */
-@end smallexample
-
-
-@node Mixing gh and scm APIs
-@section Mixing gh and scm APIs
-
-
-@node scm transition summary
-@section Transitioning to the scm Interface
-
-The following table summarizes the available information on how to
-transition from the GH to the scm interface. Where transitioning is not
-completely straightforward, the table includes a reference to more
-detailed documentation in the preceding sections.
-
-@table @asis
-@item Header file
-Use @code{#include <libguile.h>} instead of @code{#include
-<guile/gh.h>}.
-
-@item Compiling and Linking
-Use @code{guile-config} to pick up the flags required to compile C or
-C++ code that uses @code{libguile}, like so
-
-@smallexample
-$(CC) -o prog.o -c prog.c `guile-config compile`
-@end smallexample
-
-If you are using libtool to link your executables, just use
-@code{-lguile} in your link command. Libtool will expand this into
-the needed linker options automatically. If you are not using
-libtool, use the @code{guile-config} program to query the needed
-options explicitly. A linker command like
-
-@smallexample
-$(CC) -o prog prog.o `guile-config link`
-@end smallexample
-
-should be all that is needed. To link shared libraries that will be
-used as Guile Extensions, use libtool to control both the compilation
-and the link stage.
-
-@item The @code{SCM} type
-No change: the scm interface also uses this type to represent an
-arbitrary Scheme value.
-
-@item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
-No change.
-
-@item @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
-No change.
-
-@item @code{gh_enter}
-Use @code{scm_boot_guile} instead, but note that @code{scm_boot_guile}
-has a slightly different calling convention from @code{gh_enter}:
-@code{scm_boot_guile}, and the main program function that you specify
-for @code{scm_boot_guile} to call, both take an additional @var{closure}
-parameter. @ref{Guile Initialization Functions} for more details.
-
-@item @code{gh_repl}
-Use @code{scm_shell} instead.
-
-@item @code{gh_init}
-Use @code{scm_init_guile} instead.
-
-@item @code{gh_eval_str}
-Use @code{scm_c_eval_string} instead.
-
-@item @code{gh_eval_file} or @code{gh_load}
-Use @code{scm_c_primitive_load} instead.
-
-@item @code{gh_new_procedure}
-Use @code{scm_c_define_gsubr} instead, but note that the arguments are
-in a different order: for @code{scm_c_define_gsubr} the C function
-pointer is the last argument. @ref{A Sample Guile Extension} for an
-example.
-
-@item @code{gh_defer_ints} and @code{gh_allow_ints}
-Use @code{SCM_DEFER_INTS} and @code{SCM_ALLOW_INTS} instead. Note that
-these macros are used without parentheses, as in @code{SCM_DEFER_INTS;}.
-
-@item @code{gh_bool2scm}
-Use @code{SCM_BOOL} instead.
-
-@item @code{gh_ulong2scm}
-Use @code{scm_ulong2num} instead.
-
-@item @code{gh_long2scm}
-Use @code{scm_long2num} instead.
-
-@item @code{gh_double2scm}
-Use @code{scm_make_real} instead.
-
-@item @code{gh_char2scm}
-Use @code{SCM_MAKE_CHAR} instead.
-
-@item @code{gh_str2scm}
-Use @code{scm_mem2string} instead.
-
-@item @code{gh_str02scm}
-Use @code{scm_makfrom0str} instead.
-
-@item @code{gh_set_substr}
-No direct scm equivalent. [FIXME]
-
-@item @code{gh_symbol2scm}
-Use @code{scm_str2symbol} instead. [FIXME: inconsistent naming,
-should be @code{scm_str02symbol}.]
-
-@item @code{gh_ints2scm} and @code{gh_doubles2scm}
-Use @code{scm_c_ints2scm} and @code{scm_c_doubles2scm} instead.
-
-@item @code{gh_chars2byvect} and @code{gh_shorts2svect}
-Use @code{scm_c_chars2byvect} and @code{scm_c_shorts2svect} instead.
-
-@item @code{gh_longs2ivect} and @code{gh_ulongs2uvect}
-Use @code{scm_c_longs2ivect} and @code{scm_c_ulongs2uvect} instead.
-
-@item @code{gh_floats2fvect} and @code{gh_doubles2dvect}
-Use @code{scm_c_floats2fvect} and @code{scm_c_doubles2dvect} instead.
-
-@item @code{gh_scm2bool}
-Use @code{SCM_NFALSEP} instead.
-
-@item @code{gh_scm2int}
-Replace @code{gh_scm2int (@var{obj})} by
-@example
-scm_num2int (@var{obj}, SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2ulong}
-Replace @code{gh_scm2ulong (@var{obj})} by
-@example
-scm_num2ulong (@var{obj}, SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2long}
-Replace @code{gh_scm2long (@var{obj})} by
-@example
-scm_num2long (@var{obj}, SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2double}
-Replace @code{gh_scm2double (@var{obj})} by
-@example
-scm_num2dbl (@var{obj}, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_scm2char}
-Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR}
-does not check that its argument is actually a character. To check that
-a @code{SCM} value is a character before using @code{SCM_CHAR} to
-extract the character value, use the @code{SCM_VALIDATE_CHAR} macro.
-
-@item @code{gh_scm2newstr}
-Instead of @code{gh_scm2newstr (@var{obj}, @var{lenp})} use
-@code{scm_c_string2str (@var{obj}, @var{str}, @var{lenp})}. With the
-additional @var{str} argument the user can pass a pre-allocated memory
-chunk or leave it passing NULL.
-
-@item @code{gh_get_substr}
-Use the @code{scm_c_substring2str (@var{obj}, @var{str}, @var{start},
-@var{len})} function instead.
-
-@item @code{gh_symbol2newstr}
-Use the @code{scm_c_symbol2str (@var{obj}, @var{str}, @var{lenp})} function
-instead. With the additional @var{str} argument the user can pass a
-pre-allocated memory chunk or leave it passing NULL.
-
-@item @code{gh_scm2chars}
-Use @code{scm_c_scm2chars} instead.
-
-@item @code{gh_scm2shorts} and @code{gh_scm2longs}
-Use @code{scm_c_shorts2scm} and @code{scm_c_longs2scm} instead.
-
-@item @code{gh_scm2floats} and @code{gh_scm2doubles}
-Use @code{scm_c_floats2scm} and @code{scm_c_doubles2scm} instead.
-
-@item @code{gh_boolean_p}
-Use the @code{SCM_BOOLP} macro instead, or replace @code{gh_boolean_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_boolean_p (@var{obj}))
-@end example
-
-@item @code{gh_symbol_p}
-Use the @code{SCM_SYMBOLP} macro instead, or replace @code{gh_symbol_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_symbol_p (@var{obj}))
-@end example
-
-@item @code{gh_char_p}
-Use the @code{SCM_CHARP} macro instead, or replace @code{gh_char_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_char_p (@var{obj}))
-@end example
-
-@item @code{gh_vector_p}
-Use the @code{SCM_VECTORP} macro instead, or replace @code{gh_vector_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_vector_p (@var{obj}))
-@end example
-
-@item @code{gh_pair_p}
-Use the @code{SCM_CONSP} macro instead, or replace @code{gh_pair_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_pair_p (@var{obj}))
-@end example
-
-@item @code{gh_number_p}
-Use the @code{SCM_NUMBERP} macro instead, or replace @code{gh_number_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_number_p (@var{obj}))
-@end example
-
-@item @code{gh_string_p}
-Use the @code{SCM_STRINGP} macro instead, or replace @code{gh_string_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_string_p (@var{obj}))
-@end example
-
-@item @code{gh_procedure_p}
-Replace @code{gh_procedure_p (@var{obj})} by
-@example
-SCM_NFALSEP (scm_procedure_p (@var{obj}))
-@end example
-
-@item @code{gh_list_p}
-Replace @code{gh_list_p (@var{obj})} by
-@example
-SCM_NFALSEP (scm_list_p (@var{obj}))
-@end example
-
-@item @code{gh_inexact_p}
-Use the @code{SCM_INEXACTP} macro instead, or replace @code{gh_inexact_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_inexact_p (@var{obj}))
-@end example
-
-@item @code{gh_exact_p}
-Replace @code{gh_exact_p (@var{obj})} by
-@example
-SCM_NFALSEP (scm_exact_p (@var{obj}))
-@end example
-
-@item @code{gh_eq_p}
-Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p
-(@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_eq_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_eqv_p}
-Replace @code{gh_eqv_p (@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_equal_p}
-Replace @code{gh_equal_p (@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_equal_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_string_equal_p}
-Replace @code{gh_string_equal_p (@var{x}, @var{y})} by
-@example
-SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y}))
-@end example
-
-@item @code{gh_null_p}
-Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p
-(@var{obj})} by
-@example
-SCM_NFALSEP (scm_null_p (@var{obj}))
-@end example
-
-@item @code{gh_cons}
-Use @code{scm_cons} instead.
-
-@item @code{gh_car} and @code{gh_cdr}
-Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead.
-
-@item @code{gh_cxxr} and @code{gh_cxxxr}
-(Where each x is either @samp{a} or @samp{d}.) Use the corresponding
-@code{SCM_CXXR} or @code{SCM_CXXXR} macro instead.
-
-@item @code{gh_set_car_x} and @code{gh_set_cdr_x}
-Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
-
-@item @code{gh_list}
-Use @code{scm_listify} instead.
-
-@item @code{gh_length}
-Replace @code{gh_length (@var{lst})} by
-@example
-scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str})
-@end example
-where @var{str} is a C string that describes the context of the call.
-
-@item @code{gh_append}
-Use @code{scm_append} instead.
-
-@item @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
-Replace @code{gh_append@var{N} (@var{l1}, @dots{}, @var{lN})} by
-@example
-scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
-@end example
-
-@item @code{gh_reverse}
-Use @code{scm_reverse} instead.
-
-@item @code{gh_list_tail} and @code{gh_list_ref}
-Use @code{scm_list_tail} and @code{scm_list_ref} instead.
-
-@item @code{gh_memq}, @code{gh_memv} and @code{gh_member}
-Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
-
-@item @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
-Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
-
-@item @code{gh_make_vector}
-Use @code{scm_make_vector} instead.
-
-@item @code{gh_vector} or @code{gh_list_to_vector}
-Use @code{scm_vector} instead.
-
-@item @code{gh_vector_ref} and @code{gh_vector_set_x}
-Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
-
-@item @code{gh_vector_length}
-Use the @code{SCM_VECTOR_LENGTH} macro instead.
-
-@item @code{gh_apply}
-Use @code{scm_apply} instead, but note that @code{scm_apply} takes an
-additional third argument that you should set to @code{SCM_EOL}.
-
-@end table
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
deleted file mode 100644
index c819fb53d..000000000
--- a/doc/ref/guile.texi
+++ /dev/null
@@ -1,389 +0,0 @@
-\input texinfo
-@c -*-texinfo-*-
-@c %**start of header
-@setfilename guile.info
-@settitle Guile Reference Manual
-@set guile
-@set MANUAL_EDITION 1.1
-@c %**end of header
-
-@c Notes
-@c
-@c We no longer use the category "primitive" to distinguish C-defined
-@c Scheme procedures from those defined in Scheme. Instead, the
-@c reference manual now includes a C declaration as well as a Scheme
-@c declaration for each procedure that is available in both Scheme and
-@c C.
-@c
-@c When adding a new reference entry to the Guile manual, please
-@c document it with @deffn using one of the following categories:
-@c
-@c {Scheme Procedure}
-@c {Scheme Syntax}
-@c {C Function}
-@c {C Macro}
-@c
-@c If the entry is for a new primitive, it should have both a @deffn
-@c {Scheme Procedure} line and a @deffnx {C Function} line; see the
-@c manual source for plenty of existing examples of this.
-@c
-@c For {C Function} entries where the return type and all parameter
-@c types are SCM, we omit the SCMs. This is easier to read and also
-@c gets round the problem that Texinfo doesn't allow a @deftypefnx
-@c inside a @deffn.
-@c
-@c For a list of Guile primitives that are not yet incorporated into the
-@c reference manual, see the file `new-docstrings.texi', which holds all
-@c the docstrings snarfed from the libguile C sources for primitives
-@c that are not in the reference manual. If you have worked with some
-@c of these concepts, implemented them, or just happen to know what they
-@c do, please write up a little explanation -- it would be a big help.
-@c Alternatively, if you know of any reason why some of these should
-@c *not* go in the manual, please let the mailing list
-@c <guile-devel@gnu.org> know.
-
-@c Define indices that are used in the Guile Scheme part of the
-@c reference manual to group stuff according to whether it is R5RS or a
-@c Guile extension.
-@defcodeindex rn
-
-@include version.texi
-
-@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 @iftex
-@c @cropmarks
-@c @end iftex
-
-@dircategory The Algorithmic Language Scheme
-@direntry
-* Guile Reference: (guile). The Guile reference manual.
-@end direntry
-
-@setchapternewpage off
-
-@ifinfo
-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) 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.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@end ifinfo
-
-@titlepage
-@sp 10
-@comment The title is printed in a large font.
-@title Guile Reference Manual
-@subtitle Edition @value{MANUAL_EDITION}, for use with Guile @value{VERSION}
-@subtitle $Id: guile.texi,v 1.18 2002-04-20 19:26:40 ossau Exp $
-
-@c AUTHORS
-
-@c The Guile reference and tutorial manuals were written and edited
-@c largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the
-@c original tutorial on Guile's data representation and the C API for
-@c accessing Guile objects.
-
-@c Significant portions were contributed by Gary Houston (contributions
-@c to POSIX system calls and networking, expect, I/O internals and
-@c extensions, slib installation, error handling) and Tim Pierce
-@c (sections on script interpreter triggers, alists, function tracing).
-
-@c Tom Lord contributed a great deal of material with early Guile
-@c snapshots; although most of this text has been rewritten, all of it
-@c was important, and some of the structure remains.
-
-@c Aubrey Jaffer wrote the SCM Scheme implementation and manual upon
-@c which the Guile program and manual are based. Some portions of the
-@c SCM and SLIB manuals have been included here verbatim.
-
-@c Since Guile 1.4, Neil Jerram has been maintaining and improving the
-@c reference manual. Among other contributions, he wrote the Basic
-@c Ideas chapter, developed the tools for keeping the manual in sync
-@c with snarfed libguile docstrings, and reorganized the structure so as
-@c to accommodate docstrings for all Guile's primitives.
-
-@c Martin Grabmueller has made substantial contributions throughout the
-@c reference manual in preparation for the Guile 1.6 release, including
-@c filling out a lot of the documentation of Scheme data types, control
-@c mechanisms and procedures. In addition, he wrote the documentation
-@c for Guile's SRFI modules and modules associated with the Guile REPL.
-
-@author Mark Galassi
-@author Cygnus Solution and Los Alamos National Laboratory
-@author @email{rosalia@@cygnus.com}
-@author
-@author Jim Blandy
-@author Free Software Foundation and MIT AI Lab
-@author @email{jimb@@red-bean.com}
-@author
-@author Gary Houston
-@author @email{ghouston@@arglist.com}
-@author
-@author Tim Pierce
-@author @email{twp@@skepsis.com}
-@author
-@author Neil Jerram
-@author @email{neil@@ossau.uklinux.net}
-@author
-@author Martin Grabmueller
-@author @email{mgrabmue@@cs.tu-berlin.de}
-
-@c The following two commands start the copyright page.
-@page
-@vskip 0pt plus 1filll
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1996 Free Software Foundation
-
-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.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by Free Software Foundation.
-@end titlepage
-
-@c @smallbook
-@finalout
-@headings double
-
-@c Where to find Guile examples.
-@set example-dir doc/examples
-
-@ifnottex
-@node Top, Guile License, (dir), (dir)
-@top The Guile Reference Manual
-
-This reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions. It describes how to use Guile in many useful
-and interesting ways.
-
-This Info file contains edition @value{MANUAL_EDITION} of the reference
-manual, corresponding to Guile version @value{VERSION}.
-@end ifnottex
-
-@menu
-Preface
-
-* Guile License:: Conditions for copying and using Guile.
-* Manual Layout:: How to read the rest of this manual.
-* Manual Conventions:: Conventional terminology.
-
-Part I: Introduction to Guile
-
-* What is Guile?:: And what does it do?
-* Whirlwind Tour:: An introductory whirlwind tour.
-* Obtaining and Installing Guile::
-* Reporting Bugs:: Reporting bugs in Guile or this manual.
-
-Part II: Writing and Running Guile Scheme
-
-* Running Intro:: Introduction to this part.
-* Guile Scheme:: Guile's implementation of Scheme.
-* Guile Scripting:: How to write Guile scripts.
-* Command Line Handling:: Command line options and arguments.
-* Debugging Features:: Features for debugging errors.
-* Autoconf Support:: Guile-specific configure.in macros.
-* Miscellaneous Tools:: Snarfing, linting, etc.
-* Basic Ideas:: Basic ideas in Scheme.
-* Further Reading:: Where to find out more about Scheme.
-
-Part III: Guile as an Extension Language
-
-* Programming Intro:: Introduction to this part.
-* Libguile Intro:: Using Guile as an extension language.
-* Programming Overview:: An overview of Guile programming.
-* Data Representation:: Data representation in Guile.
-* GH:: The deprecated GH interface.
-
-Part IV: Guile API Reference
-
-* Reference Intro:: Introduction to the Guile API reference.
-* API Overview:: Overview of the Guile API.
-* Simple Data Types:: Numbers, strings, booleans and so on.
-* Compound Data Types:: Data types for holding other data.
-* Procedures and Macros:: Procedures and macros.
-* Utility Functions:: General utility functions.
-* Binding Constructs:: Definitions and variable bindings.
-* Control Mechanisms:: Controlling the flow of program execution.
-* Input and Output:: Ports, reading and writing.
-* Read/Load/Eval:: Reading and evaluating Scheme code.
-* Memory Management:: Memory management and garbage collection.
-* Objects:: Low level object orientation support.
-* Modules:: Designing reusable code libraries.
-* Scheduling:: Threads, mutexes, asyncs and dynamic roots.
-* Options and Config:: Runtime options and configuration.
-* Translation:: Support for translating other languages.
-* Debugging:: Internal debugging interface.
-* Deprecated:: Features that are planned to disappear.
-
-Part V: Guile Modules
-
-* SLIB:: Using the SLIB Scheme library.
-* POSIX:: POSIX system calls and networking.
-* SRFI Support:: Support for various SRFIs.
-* Readline Support:: Module for using the readline library.
-* Value History:: Maintaining a value history in the REPL.
-* Pretty Printing:: Nicely formatting Scheme objects for output.
-* Formatted Output:: The @code{format} procedure.
-* Rx Regexps:: The Rx regular expression library.
-* Expect:: Controlling interactive programs with Guile.
-* The Scheme shell (scsh):: Using scsh interfaces in Guile.
-
-Indices
-
-* Concept Index::
-* Procedure Index::
-* Variable Index::
-* Type Index::
-* R5RS Index::
-
-@end menu
-
-@include preface.texi
-
-@iftex
-@page
-@unnumbered{Part I: Introduction to Guile}
-@end iftex
-
-@include intro.texi
-
-@page
-@node Running Intro
-@unnumbered Part II: Writing and Running Guile Scheme
-
-Guile's core language is Scheme, and an awful lot can be achieved simply
-by using Guile to write and run Scheme programs. In this part of the
-manual, we explain how to use Guile in this mode, and describe the tools
-that Guile provides to help you with script writing, debugging and
-packaging your programs for distribution.
-
-For readers who are not yet familiar with the Scheme language, this part
-includes a chapter that presents the basic concepts of the language, and
-gives references to freely available Scheme tutorial material on the
-web.
-
-For detailed reference information on the variables, functions etc. that
-make up Guile's application programming interface (API), please refer to
-Part IV (@pxref{Reference Intro,,Part IV --- Guile API Reference}).
-
-@include scheme-intro.texi
-@include scripts.texi
-@include script-getopt.texi
-@include debugging.texi
-@include autoconf.texi
-@include tools.texi
-@include scheme-ideas.texi
-@include scheme-reading.texi
-
-@page
-@node Programming Intro
-@unnumbered Part III: Guile as an Extension Language
-
-In this part of the manual, we aim to present a wide ranging picture of
-what it means to use Guile as an application extension language, to
-provide guidance, practical guidelines and tips for @emph{how} to
-program in Guile, and to document the tools that are available to help
-you with your programming. For detailed reference information on the
-variables, functions etc. that make up Guile's application programming
-interface (API), please refer to Part IV (@pxref{Reference Intro,,Part
-IV --- Guile API Reference}).
-
-@include extend.texi
-@include program.texi
-@include data-rep.texi
-@include gh.texi
-
-@page
-@node Reference Intro
-@unnumbered Part IV: Guile API Reference
-
-Guile provides an application programming interface (@dfn{API}) to
-developers in two core languages: Scheme and C. This part of the manual
-contains reference documentation for all of the functionality that is
-available through both Scheme and C interfaces.
-
-@include scm.texi
-@include scheme-data.texi
-@include scheme-compound.texi
-@include scheme-procedures.texi
-@include scheme-utility.texi
-@include scheme-binding.texi
-@include scheme-control.texi
-@include scheme-io.texi
-@include scheme-evaluation.texi
-@include scheme-memory.texi
-@include scheme-modules.texi
-@include scheme-scheduling.texi
-@c object orientation support here
-@include scheme-options.texi
-@include scheme-translation.texi
-@include scheme-debug.texi
-@include deprecated.texi
-
-@iftex
-@page
-@unnumbered{Part V: Guile Modules}
-@end iftex
-
-@include slib.texi
-@include posix.texi
-@include srfi-modules.texi
-@include repl-modules.texi
-@include misc-modules.texi
-@include expect.texi
-@include scsh.texi
-
-@iftex
-@page
-@unnumbered{Indices}
-@end iftex
-
-@include indices.texi
-@include scheme-indices.texi
-
-@contents
-
-@bye
diff --git a/doc/ref/indices.texi b/doc/ref/indices.texi
deleted file mode 100644
index 11ab7476b..000000000
--- a/doc/ref/indices.texi
+++ /dev/null
@@ -1,52 +0,0 @@
-@page
-@node Concept Index
-@unnumbered Concept Index
-
-This index contains concepts, keywords and non-Schemey names for several
-features, to make it easier to locate the desired sections.
-
-@printindex cp
-
-
-@page
-@node Procedure Index
-@unnumbered Procedure Index
-
-@c FIXME::martin: Review me!
-
-This is an alphabetical list of all the procedures and macros in Guile.
-
-When looking for a particular procedure, please look under its Scheme
-name as well as under its C name. The C name can be constructed from
-the Scheme names by a simple transformation described in the section
-@xref{Transforming Scheme name to C name}.
-
-@printindex fn
-
-
-@page
-@node Variable Index
-@unnumbered Variable Index
-
-@c FIXME::martin: Review me!
-
-This is an alphabetical list of all the important variables and
-constants in Guile.
-
-When looking for a particular variable or constant, please look under
-its Scheme name as well as under its C name. The C name can be
-constructed from the Scheme names by a simple transformation described
-in the section @xref{Transforming Scheme name to C name}.
-
-@printindex vr
-
-
-@page
-@node Type Index
-@unnumbered Type Index
-
-This is an alphabetical list of all the important data types defined in
-the Guile Programmers Manual.
-
-@printindex tp
-
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
deleted file mode 100644
index af1b48d0e..000000000
--- a/doc/ref/intro.texi
+++ /dev/null
@@ -1,1128 +0,0 @@
-@page
-@node What is Guile?
-@chapter What is Guile?
-
-Guile is an interpreter for the Scheme programming language, packaged
-for use in a wide variety of environments. Guile implements Scheme as
-described in the
-@tex
-Revised$^5$
-@end tex
-@ifnottex
-Revised^5
-@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
-a module system, full access to POSIX system calls, networking support,
-multiple threads, dynamic linking, a foreign function call interface,
-powerful string processing, and many other features needed for
-programming in the real world.
-
-Like a shell, Guile can run interactively, reading expressions from the
-user, evaluating them, and displaying the results, or as a script
-interpreter, reading and executing Scheme code from a file. However,
-Guile is also packaged as an object library, allowing other applications
-to easily incorporate a complete Scheme interpreter. An application can
-use Guile as an extension language, a clean and powerful configuration
-language, or as multi-purpose ``glue'', connecting primitives provided
-by the application. It is easy to call Scheme code from C code and vice
-versa, giving the application designer full control of how and when to
-invoke the interpreter. Applications can add new functions, data types,
-control structures, and even syntax to Guile, creating a domain-specific
-language tailored to the task at hand, but based on a robust language
-design.
-
-Guile's module system allows one to break up a large program into
-manageable sections with well-defined interfaces between them. Modules
-may contain a mixture of interpreted and compiled code; Guile can use
-either static or dynamic linking to incorporate compiled code. Modules
-also encourage developers to package up useful collections of routines
-for general distribution; as of this writing, one can find Emacs
-interfaces, database access routines, compilers, GUI toolkit interfaces,
-and HTTP client functions, among others.
-
-In the future, we hope to expand Guile to support other languages like
-Tcl and Perl by translating them to Scheme code. This means that users
-can program applications which use Guile in the language of their
-choice, rather than having the tastes of the application's author
-imposed on them.
-
-
-@page
-@node Whirlwind Tour
-@chapter A Whirlwind Tour
-
-This chapter presents a quick tour of all the ways that Guile can be
-used.
-
-@menu
-* Running Guile Interactively::
-* Guile Scripts::
-* Linking Programs With Guile::
-* Writing Extensions for Guile::
-* Guile Modules::
-@end menu
-
-
-@node Running Guile Interactively
-@section Running Guile Interactively
-
-In its simplest form, Guile acts as an interactive interpreter for the
-Scheme programming language, reading and evaluating Scheme expressions
-the user enters from the terminal. Here is a sample interaction between
-Guile and a user; the user's input appears after the @code{$} and
-@code{guile>} prompts:
-
-@example
-$ guile
-guile> (+ 1 2 3) ; add some numbers
-6
-guile> (define (factorial n) ; define a function
- (if (zero? n) 1 (* n (factorial (- n 1)))))
-guile> (factorial 20)
-2432902008176640000
-guile> (getpwnam "jimb") ; find my entry in /etc/passwd
-#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> @kbd{C-d}
-$
-@end example
-
-@c [[When we get a fancier read-eval-print loop, with features for bouncing
-@c around among modules, referring to the value of the last expression,
-@c etc. then this section will get longer.]]
-
-
-@node Guile Scripts
-@section Guile Scripts
-
-Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-Before we present the details, here is a trivial Guile script:
-
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-
-@menu
-* The Top of a Script File:: How to start a Guile script.
-* Scripting Examples:: Simple Guile scripts, explained.
-@end menu
-
-
-@node The Top of a Script File
-@subsection The Top of a Script File
-
-The first line of a Guile script must tell the operating system to use
-Guile to evaluate the script, and then tell Guile how to go about doing
-that. Here is the simplest case:
-
-@itemize @bullet
-
-@item
-The first two characters of the file must be @samp{#!}.
-
-The operating system interprets this to mean that the rest of the line
-is the name of an executable that can interpret the script. Guile,
-however, interprets these characters as the beginning of a multi-line
-comment, terminated by the characters @samp{!#} on a line by themselves.
-(This is an extension to the syntax described in R5RS, added to support
-shell scripts.)
-
-@item
-Immediately after those two characters must come the full pathname to
-the Guile interpreter. On most systems, this would be
-@samp{/usr/local/bin/guile}.
-
-@item
-Then must come a space, followed by a command-line argument to pass to
-Guile; this should be @samp{-s}. This switch tells Guile to run a
-script, instead of soliciting the user for input from the terminal.
-There are more elaborate things one can do here; see @ref{The Meta
-Switch}.
-
-@item
-Follow this with a newline.
-
-@item
-The second line of the script should contain only the characters
-@samp{!#} --- just like the top of the file, but reversed. The
-operating system never reads this far, but Guile treats this as the end
-of the comment begun on the first line by the @samp{#!} characters.
-
-@item
-The rest of the file should be a Scheme program.
-
-@end itemize
-
-Guile reads the program, evaluating expressions in the order that they
-appear. Upon reaching the end of the file, Guile exits.
-
-The function @code{command-line} returns the name of the script file and
-any command-line arguments passed by the user, as a list of strings.
-
-For example, consider the following script file:
-@example
-#!/usr/local/bin/guile -s
-!#
-(write (command-line))
-(newline)
-@end example
-
-If you put that text in a file called @file{foo} in the current
-directory, then you could make it executable and try it out like this:
-@example
-$ chmod a+x foo
-$ ./foo
-("./foo")
-$ ./foo bar baz
-("./foo" "bar" "baz")
-$
-@end example
-
-As another example, here is a simple replacement for the POSIX
-@code{echo} command:
-@example
-#!/usr/local/bin/guile -s
-!#
-(for-each (lambda (s) (display s) (display " "))
- (cdr (command-line)))
-(newline)
-@end example
-
-@deffn {Scheme Procedure} command-line
-@deffnx {Scheme Procedure} program-arguments
-Return a list of the command-line arguments passed to the currently
-running program. If the program invoked Guile with the @samp{-s},
-@samp{-c} or @samp{--} switches, these procedures ignore everything up
-to and including those switches.
-@end deffn
-
-
-@node Scripting Examples
-@subsection Scripting Examples
-
-To start with, here are some examples of invoking Guile directly:
-
-@table @code
-
-@item guile -- a b c
-Run Guile interactively; @code{(command-line)} will return @*
-@code{("/usr/local/bin/guile" "a" "b" "c")}.
-
-@item guile -s /u/jimb/ex2 a b c
-Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
-@code{("/u/jimb/ex2" "a" "b" "c")}.
-
-@item guile -c '(write %load-path) (newline)'
-Write the value of the variable @code{%load-path}, print a newline,
-and exit.
-
-@item guile -e main -s /u/jimb/ex4 foo
-Load the file @file{/u/jimb/ex4}, and then call the function
-@code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
-
-@item guile -l first -ds -l last -s script
-Load the files @file{first}, @file{script}, and @file{last}, in that
-order. The @code{-ds} switch says when to process the @code{-s}
-switch. For a more motivated example, see the scripts below.
-
-@end table
-
-
-Here is a very simple Guile script:
-@example
-#!/usr/local/bin/guile -s
-!#
-(display "Hello, world!")
-(newline)
-@end example
-The first line marks the file as a Guile script. When the user invokes
-it, the system runs @file{/usr/local/bin/guile} to interpret the script,
-passing @code{-s}, the script's filename, and any arguments given to the
-script as command-line arguments. When Guile sees @code{-s
-@var{script}}, it loads @var{script}. Thus, running this program
-produces the output:
-@example
-Hello, world!
-@end example
-
-Here is a script which prints the factorial of its argument:
-@example
-#!/usr/local/bin/guile -s
-!#
-(define (fact n)
- (if (zero? n) 1
- (* n (fact (- n 1)))))
-
-(display (fact (string->number (cadr (command-line)))))
-(newline)
-@end example
-In action:
-@example
-$ fact 5
-120
-$
-@end example
-
-However, suppose we want to use the definition of @code{fact} in this
-file from another script. We can't simply @code{load} the script file,
-and then use @code{fact}'s definition, because the script will try to
-compute and display a factorial when we load it. To avoid this problem,
-we might write the script this way:
-
-@example
-#!/usr/local/bin/guile \
--e main -s
-!#
-(define (fact n)
- (if (zero? n) 1
- (* n (fact (- n 1)))))
-
-(define (main args)
- (display (fact (string->number (cadr args))))
- (newline))
-@end example
-This version packages the actions the script should perform in a
-function, @code{main}. This allows us to load the file purely for its
-definitions, without any extraneous computation taking place. Then we
-used the meta switch @code{\} and the entry point switch @code{-e} to
-tell Guile to call @code{main} after loading the script.
-@example
-$ fact 50
-30414093201713378043612608166064768844377641568960512000000000000
-@end example
-
-Suppose that we now want to write a script which computes the
-@code{choose} function: given a set of @var{m} distinct objects,
-@code{(choose @var{n} @var{m})} is the number of distinct subsets
-containing @var{n} objects each. It's easy to write @code{choose} given
-@code{fact}, so we might write the script this way:
-@example
-#!/usr/local/bin/guile \
--l fact -e main -s
-!#
-(define (choose n m)
- (/ (fact m) (* (fact (- m n)) (fact n))))
-
-(define (main args)
- (let ((n (string->number (cadr args)))
- (m (string->number (caddr args))))
- (display (choose n m))
- (newline)))
-@end example
-
-The command-line arguments here tell Guile to first load the file
-@file{fact}, and then run the script, with @code{main} as the entry
-point. In other words, the @code{choose} script can use definitions
-made in the @code{fact} script. Here are some sample runs:
-@example
-$ choose 0 4
-1
-$ choose 1 4
-4
-$ choose 2 4
-6
-$ choose 3 4
-4
-$ choose 4 4
-1
-$ choose 50 100
-100891344545564193334812497256
-@end example
-
-
-@node Linking Programs With Guile
-@section Linking Programs With Guile
-
-The Guile interpreter is available as an object library, to be linked
-into applications using Scheme as a configuration or extension
-language. This chapter covers the mechanics of linking your program
-with Guile on a typical POSIX system.
-
-Parts III and IV of this manual describe the C functions Guile provides.
-Furthermore, any Scheme function described in this manual as a
-``Primitive'' is also callable from C; see @ref{Primitives}.
-
-The header file @code{<libguile.h>} provides declarations for all of
-Guile's functions and constants. You should @code{#include} it at the
-head of any C source file that uses identifiers described in this
-manual. Once you've compiled your source files, you need to link them
-against the Guile object code library, @code{libguile}.
-
-On most systems, you should not need to tell the compiler and linker
-explicitly where they can find @file{libguile.h} and @file{libguile}.
-When Guile has been installed in a peculiar way, or when you are on a
-peculiar system, things might not be so easy and you might need to pass
-additional @code{-I} or @code{-L} options to the compiler. Guile
-provides the utility program @code{guile-config} to help you find the
-right values for these options. You would typically run
-@code{guile-config} during the configuration phase of your program and
-use the obtained information in the Makefile.
-
-@menu
-* Guile Initialization Functions:: What to call first.
-* A Sample Guile Main Program:: Sources and makefiles.
-@end menu
-
-
-@node Guile Initialization Functions
-@subsection Guile Initialization Functions
-
-To initialize Guile, you can use one of two functions. The first,
-@code{scm_boot_guile}, is the most portable way to initialize Guile. It
-should be used whenever you have control over the main function of your
-program because it never returns. The second function,
-@code{scm_init_guile}, does return and can thus be used in more
-situations. However, @code{scm_init_guile} is not as widely available
-as @code{scm_boot_guile} because it needs to rely on non-portable code
-to find the stack bounds. When Guile does not know how to find these
-bounds on your system, it will not provide @code{scm_init_guile}.
-
-When you can tolerate the limits of @code{scm_boot_guile}, you should
-use it in favor of @code{scm_init_guile} since that will make your
-program more portable.
-
-@deftypefun void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (), void *@var{closure})
-Initialize the Guile Scheme interpreter. Then call @var{main_func},
-passing it @var{closure}, @var{argc}, and @var{argv}. @var{main_func}
-should do all the work of the program (initializing other packages,
-defining application-specific functions, reading user input, and so on)
-before returning. When @var{main_func} returns, call @code{exit (0)};
-@code{scm_boot_guile} never returns. If you want some other exit value,
-have @var{main_func} call exit itself.
-
-@code{scm_boot_guile} arranges for the Scheme @code{command-line}
-function to return the strings given by @var{argc} and @var{argv}. If
-@var{main_func} modifies @var{argc} or @var{argv}, it should call
-@code{scm_set_program_arguments} with the final list, so Scheme code
-will know which arguments have been processed.
-
-Why must the caller do all the real work from @var{main_func}? Guile's
-garbage collector scans the stack to find all local variables that
-reference Scheme objects. To do this, it needs to know the bounds of
-the stack that might contain such references. Because there is no
-portable way in C to find the base of the stack, @code{scm_boot_guile}
-assumes that all references are above its own stack frame. If you try
-to manipulate Scheme objects after this function returns, it's the luck
-of the draw whether Guile's storage manager will be able to find the
-objects you allocate. So, @code{scm_boot_guile} function exits, rather
-than returning, to discourage you from making that mistake.
-
-See @code{scm_init_guile}, below, for a function that can find the real
-base of the stack, but not in a portable way.
-@end deftypefun
-
-@deftypefun void scm_init_guile ()
-Initialize the Guile Scheme interpreter.
-
-In contrast to @code{scm_boot_guile}, this function knows how to find
-the true base of the stack and thus does not need to usurp the control
-flow of your program. However, since finding the stack base can not be
-done portably, this function might not be available in all installations
-of Guile. If you can, you should use @code{scm_boot_guile} instead.
-
-Note that @code{scm_init_guile} does not inform Guile about the command
-line arguments that should be returned by the Scheme function
-@code{command-line}. You can use @code{scm_set_program_arguments} to do
-this.
-@end deftypefun
-
-One common way to use Guile is to write a set of C functions which
-perform some useful task, make them callable from Scheme, and then link
-the program with Guile. This yields a Scheme interpreter just like
-@code{guile}, but augmented with extra functions for some specific
-application --- a special-purpose scripting language.
-
-In this situation, the application should probably process its
-command-line arguments in the same manner as the stock Guile
-interpreter. To make that straightforward, Guile provides this
-function:
-
-@deftypefun void scm_shell (int @var{argc}, char **@var{argv})
-Process command-line arguments in the manner of the @code{guile}
-executable. This includes loading the normal Guile initialization
-files, interacting with the user or running any scripts or expressions
-specified by @code{-s} or @code{-e} options, and then exiting.
-@xref{Invoking Guile}, for more details.
-
-Since this function does not return, you must do all
-application-specific initialization before calling this function.
-@end deftypefun
-
-
-@node A Sample Guile Main Program
-@subsection A Sample Guile Main Program
-
-Here is @file{simple-guile.c}, source code for a @code{main} and an
-@code{inner_main} function that will produce a complete Guile
-interpreter.
-
-@example
-/* simple-guile.c --- how to start up the Guile
- interpreter from C code. */
-
-/* Get declarations for all the scm_ functions. */
-#include <libguile.h>
-
-static void
-inner_main (void *closure, int argc, char **argv)
-@{
- /* module initializations would go here */
- scm_shell (argc, argv);
-@}
-
-int
-main (int argc, char **argv)
-@{
- scm_boot_guile (argc, argv, inner_main, 0);
- return 0; /* never reached */
-@}
-@end example
-
-The @code{main} function calls @code{scm_boot_guile} to initialize
-Guile, passing it @code{inner_main}. Once @code{scm_boot_guile} is
-ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
-process the command-line arguments in the usual way.
-
-Here is a Makefile which you can use to compile the above program. It
-uses @code{guile-config} to learn about the necessary compiler and
-linker flags.
-@example
-# Use GCC, if you have it installed.
-CC=gcc
-
-# Tell the C compiler where to find <libguile.h>
-CFLAGS=`guile-config compile`
-
-# Tell the linker what libraries to use and where to find them.
-LIBS=`guile-config link`
-
-simple-guile: simple-guile.o
- $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
-
-simple-guile.o: simple-guile.c
- $@{CC@} -c $@{CFLAGS@} simple-guile.c
-@end example
-
-If you are using the GNU Autoconf package to make your application more
-portable, Autoconf will settle many of the details in the Makefile above
-automatically, making it much simpler and more portable; we recommend
-using Autoconf with Guile. Guile also provides the @code{GUILE_FLAGS}
-macro for autoconf that performs all necessary checks. Here is a
-@file{configure.in} file for @code{simple-guile} that uses this macro.
-Autoconf can use as this file as template to generate a @code{configure}
-script. In order for Autoconf to find the @code{GUILE_FLAGS} macro, you
-will need to run @code{aclocal} first. This is not really Guile
-specific, so you should refer to the Autoconf documentation REFFIXME
-when in doubt.
-@example
-AC_INIT(simple-guile.c)
-
-# Find a C compiler.
-AC_PROG_CC
-
-# Check for Guile
-GUILE_FLAGS
-
-# Generate a Makefile, based on the results.
-AC_OUTPUT(Makefile)
-@end example
-
-Here is a @code{Makefile.in} template, from which the @code{configure}
-script produces a Makefile customized for the host system:
-@example
-# The configure script fills in these values.
-CC=@@CC@@
-CFLAGS=@@GUILE_CFLAGS@@
-LIBS=@@GUILE_LDFLAGS@@
-
-simple-guile: simple-guile.o
- $@{CC@} simple-guile.o $@{LIBS@} -o simple-guile
-simple-guile.o: simple-guile.c
- $@{CC@} -c $@{CFLAGS@} simple-guile.c
-@end example
-
-The developer should use Autoconf to generate the @file{configure}
-script from the @file{configure.in} template, and distribute
-@file{configure} with the application. Here's how a user might go about
-building the application:
-
-@example
-$ ls
-Makefile.in configure* configure.in simple-guile.c
-$ ./configure
-creating cache ./config.cache
-checking for gcc... (cached) gcc
-checking whether the C compiler (gcc ) works... yes
-checking whether the C compiler (gcc ) is a cross-compiler... no
-checking whether we are using GNU C... (cached) yes
-checking whether gcc accepts -g... (cached) yes
-checking for Guile... yes
-creating ./config.status
-creating Makefile
-$ make
-gcc -c -I/usr/local/include simple-guile.c
-gcc simple-guile.o -L/usr/local/lib -lguile -lqthreads -lpthread -lm -o simple-guile
-$ ./simple-guile
-guile> (+ 1 2 3)
-6
-guile> (getpwnam "jimb")
-#("jimb" "83Z7d75W2tyJQ" 4008 10 "Jim Blandy" "/u/jimb"
- "/usr/local/bin/bash")
-guile> (exit)
-$
-@end example
-
-
-@node Writing Extensions for Guile
-@section Writing Extensions for Guile
-
-The previous sections have briefly explained how to write programs that
-make use of an embedded Guile interpreter. But sometimes, all you want
-to do is make new primitive procedures and data types available to the
-Scheme programmer. Writing a new version of @code{guile} is
-inconvenient in this case and it would in fact make the life of the
-users of your new features needlessly hard.
-
-@c [[ the following is probably a bit long-winded ]]
-
-For example, suppose that there is a program @code{guile-db} that is a
-version of Guile with additional features for accessing a database.
-People who want to write Scheme programs that use these features would
-have to use @code{guile-db} instead of the usual @code{guile} program.
-Now suppose that there is also a program @code{guile-gtk} that extends
-Guile with access to the popular Gtk+ toolkit for graphical user
-interfaces. People who want to write GUIs in Scheme would have to use
-@code{guile-gtk}. Now, what happens when you want to write a Scheme
-application that uses a GUI to let the user access a database? You
-would have to write a @emph{third} program that incorporates both the
-database stuff and the GUI stuff. This might not be easy (because
-@code{guile-gtk} might be a quite obscure program, say) and taking this
-example further makes it easy to see that this approach can not work in
-practice.
-
-It would have been much better if both the database features and the GUI
-feature had been provided as libraries that can just be linked with
-@code{guile}. Guile makes it easy to do just this, and we encourage you
-to make your extensions to Guile available as libraries whenever
-possible.
-
-You write the new primitive procedures and data types in the normal
-fashion, and link them into a shared library instead of into a
-stand-alone program. The shared library can then be loaded dynamically
-by Guile.
-
-@menu
-* A Sample Guile Extension::
-@end menu
-
-
-@node A Sample Guile Extension
-@subsection A Sample Guile Extension
-
-This section explains how to make the Bessel functions of the C library
-available to Scheme. First we need to write the appropriate glue code
-to convert the arguments and return values of the functions from Scheme
-to C and back. Additionally, we need a function that will add them to
-the set of Guile primitives. Because this is just an example, we will
-only implement this for the @code{j0} function.
-
-Consider the following file @file{bessel.c}.
-
-@smallexample
-#include <math.h>
-#include <libguile.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
- return scm_make_real (j0 (scm_num2dbl (x, "j0")));
-@}
-
-void
-init_bessel ()
-@{
- scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
-@}
-@end smallexample
-
-This C source file needs to be compiled into a shared library. Here is
-how to do it on GNU/Linux:
-
-@smallexample
-gcc -shared -o libguile-bessel.so -fPIC bessel.c
-@end smallexample
-
-For creating shared libraries portably, we recommend the use of
-@code{GNU Libtool}.
-
-A shared library can be loaded into a running Guile process with the
-function @code{load-extension}. In addition to the name of the
-library to load, this function also expects the name of function from
-that library that will be called to initialize it. For our example,
-we are going to call the function @code{init_bessel} which will make
-@code{j0_wrapper} available to Scheme programs with the name
-@code{j0}. Note that we do not specify a filename extension such as
-@file{.so} when invoking @code{load-extension}. The right extension for
-the host platform will be provided automatically.
-
-@smalllisp
-(load-extension "libguile-bessel" "init_bessel")
-(j0 2)
-@result{} 0.223890779141236
-@end smalllisp
-
-For this to work, @code{load-extension} must be able to find
-@file{libguile-bessel}, of course. It will look in the places that
-are usual for your operating system, and it will additionally look
-into the directories listed in the @code{LTDL_LIBRARY_PATH}
-environment variable.
-
-To see how these Guile extensions via shared libraries relate to the
-module system, see below @xref{Intro to Modules and Extensions}.
-
-
-@node Guile Modules
-@section Guile Modules
-
-Guile has support for dividing a program into @dfn{modules}. By using
-modules, you can group related code together and manage the
-composition of complete programs from largely independent parts.
-
-(Although the module system implementation is in flux, feel free to use it
-anyway. Guile will provide reasonable backwards compatibility.)
-
-Details on the module system beyond this introductory material can be found in
-@xref{Modules}.
-
-@menu
-* Intro to Using Guile Modules::
-* Intro to Writing New Modules::
-* Intro to Modules and Extensions::
-@end menu
-
-
-@node Intro to Using Guile Modules
-@subsection Intro to Using Existing Modules
-
-Guile comes with a lot of useful modules, for example for string
-processing or command line parsing. Additionally, there exist many
-Guile modules written by other Guile hackers, but which have to be
-installed manually.
-
-Existing modules have to be placed in places where Guile looks for them
-by default or in colon-separated directories in the environment variable
-@code{GUILE_LOAD_PATH}. When this variable is set, those directories
-are searched first, then the the default. The following command
-shows the complete list of directories searched:
-
-@smallexample
-guile -c '(write %load-path) (newline)'
-@end smallexample
-
-Suppose you want to use the procedures and variables exported by the
-module @code{(ice-9 popen)}, which provides the means for communicating
-with other processes over pipes. Add the following line to your
-currently running Guile REPL or the top of your script file.
-
-@lisp
-(use-modules (ice-9 popen))
-@end lisp
-
-This will load the module and make the procedures exported by
-@code{(ice-9 popen)} automatically available. The next step could be to
-open a pipe to @file{ls} and read the contents of the current directory,
-one line at a time.
-
-@lisp
-(define p (open-input-pipe "ls -l"))
-(read-line p)
-@result{}
-"total 30"
-(read-line p)
-@result{}
-"drwxr-sr-x 2 mgrabmue mgrabmue 1024 Mar 29 19:57 CVS"
-@end lisp
-
-
-@node Intro to Writing New Modules
-@subsection Intro to Writing New Modules
-
-Of course it is possible to write modules yourself. Using modules for
-structuring your programs makes them more readable and lets you
-distribute them more easily. Also, explicitly defining the procedures
-and variables which are exported from a module adds documentation to the
-source and specifies the interface a module provides.
-
-In Guile, you can create new modules and switch to existing modules in
-order to add bindings to them using the syntactic form
-@code{define-module}.
-
-@lisp
-(define-module (foo bar))
-
-(define (frob x) x)
-@end lisp
-
-Will create the module @code{(foo bar)}.@footnote{It is only convention
-that the module names in this section have two elements. One or more
-than two elements are perfectly fine, such as @code{(foo)} or @code{(foo
-bar braz)}} All definitions following this statement will add bindings
-to the module @code{(foo bar)}, and these bindings will not be visible
-outside of the module. To make the bindings accessible to other
-modules, you have to export them explicitly using one of the following
-means:
-
-@itemize @bullet
-@item
-Export them with the @code{export} form:
-@lisp
-(export frob)
-@end lisp
-
-@item
-Include them into the @code{define-module} form with the keyword
-@code{export}:
-@lisp
-(define-module (foo bar)
- #:export (frob))
-@end lisp
-
-@item
-Change the definition of @code{frob} to use @code{define-public}, which
-is a combination of @code{define} and @code{export}.
-@lisp
-(define-public (frob x) x)
-@end lisp
-@end itemize
-
-After exporting, other modules can access the exported items simply by
-using @code{use-modules} to load the module @code{(foo bar)}.
-
-
-@node Intro to Modules and Extensions
-@subsection Intro to Modules and Extensions
-
-In addition to Scheme code you can also put things that are defined in
-C into a module.
-
-You do this by writing a small Scheme file that defines the module.
-That Scheme file in turn invokes @code{load-extension} to make the
-features defined in C available. This works since all definitions
-made by @code{scm_c_define_gsubr} etc. go into the @emph{current
-module} and @code{define-module} causes the newly defined module to be
-current while the code that follows it is executed.
-
-Suppose we want to put the Bessel function @code{j0} from the example
-extension into a module called @code{(math bessel)}. We would have to
-write a Scheme file with this contents
-
-@smallexample
-(define-module (math bessel))
-
-(export j0)
-
-(load-extension "libguile-bessel" "init_bessel")
-@end smallexample
-
-This file should of course be saved in the right place for
-autoloading, for example as
-@file{/usr/local/share/guile/math/bessel.scm}.
-
-When @code{init_bessel} is called, the new @code{(math bessel)} module
-is the current one. Thus, the call to @code{scm_c_define_gsubr} will
-put the new definition for @code{j0} into it, just as we want it.
-
-The definitions made in the C code are not automatically exported from
-a module. You need to explicitly list the ones you want to export in
-@code{export} statements or with the @code{:export} option of
-@code{define-module}.
-
-There is also a way to manipulate the module system from C but only
-Scheme files can be autoloaded. Thus, we recommend that you define
-your modules in Scheme.
-
-
-@page
-@node Obtaining and Installing Guile
-@chapter Obtaining and Installing Guile
-
-Here is the information you will need to get and install Guile and extra
-packages and documentation you might need or find interesting.
-
-@menu
-* The Basic Guile Package::
-* Packages not shipped with Guile::
-@end menu
-
-
-@node The Basic Guile Package
-@section The Basic Guile Package
-
-Guile can be obtained from the main GNU archive site
-@url{ftp://prep.ai.mit.edu/pub/gnu} or any of its mirrors. The file
-will be named guile-version.tar.gz. The current version is
-@value{VERSION}, so the file you should grab is:
-
-@url{ftp://prep.ai.mit.edu/pub/gnu/guile-@value{VERSION}.tar.gz}
-
-To unbundle Guile use the instruction
-@example
-zcat guile-@value{VERSION}.tar.gz | tar xvf -
-@end example
-which will create a directory called @file{guile-@value{VERSION}} with
-all the sources. You can look at the file @file{INSTALL} for detailed
-instructions on how to build and install Guile, but you should be able
-to just do
-@example
-cd guile-@value{VERSION}
-./configure
-make install
-@end example
-
-This will install the Guile executable @file{guile}, the Guile library
-@file{libguile.a} and various associated header files and support
-libraries. It will also install the Guile tutorial and reference manual.
-
-@c [[include instructions for getting R5RS]]
-
-Since this manual frequently refers to the Scheme ``standard'', also
-known as R5RS, or the
-@iftex
-``Revised$^5$ Report on the Algorithmic Language Scheme'',
-@end iftex
-@ifnottex
-``Revised^5 Report on the Algorithmic Language Scheme'',
-@end ifnottex
-we have included the report in the Guile distribution;
-@xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
-Language Scheme}.
-This will also be installed in your info directory.
-
-
-@node Packages not shipped with Guile
-@section Packages not shipped with Guile
-
-We ship the Guile tutorial and reference manual with the Guile
-distribution. Since the Scheme standard (R5RS) is a stable document, we
-ship that too.
-
-Here are references (usually World Wide Web URLs) to some other freely
-redistributable documents and packages which you might find useful if
-you are using Guile.
-
-@table @strong
-@item SCSH
-the Scheme Shell. Gary Houston has ported SCSH to Guile. The relevant
-chapter (@pxref{The Scheme shell (scsh)}) has references to the SCSH web
-page with all its documentation.
-
-@item SLIB
-a portable Scheme library maintained by Aubrey Jaffer. SLIB can be
-obtained by ftp from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}.
-
-The SLIB package should be unpacked somewhere in Guile's load path. It
-will typically be unpacked in @file{/usr/local/share/guile/site}, so
-that it will be @file{/usr/local/share/guile/site/slib}.
-
-Guile might have been installed with a different prefix, in which case
-the load path can be checked from inside the interpreter with:
-
-@smalllisp
-guile> %load-path
-("/usr/local/share/guile/site" "/usr/local/share/guile/1.3a" "/usr/local/share/guile" ".")
-@end smalllisp
-
-The relevant chapter (@pxref{SLIB}) has details on how to use SLIB with
-Guile.
-
-@item JACAL
-a symbolic math package by Aubrey Jaffer. The latest version of Jacal
-can be obtained from @url{ftp://prep.ai.mit.edu/pub/gnu/jacal/}, and
-should be unpacked in @file{/usr/local/share/guile/site/slib} so that
-it will be in @file{/usr/local/share/guile/site/slib/jacal}.
-
-The relevant section (@pxref{JACAL}) has details on how to use Jacal.
-@end table
-
-
-@page
-@node Reporting Bugs
-@chapter Reporting Bugs
-
-Any problems with the installation should be reported to
-@email{bug-guile@@gnu.org}.
-
-Whenever you have found a bug in Guile you are encouraged to report it
-to the Guile developers, so they can fix it. They may also be able to
-suggest workarounds when it is not possible for you to apply the bug-fix
-or install a new version of Guile yourself.
-
-Before sending in bug reports, please check with the following list that
-you really have found a bug.
-
-@itemize @bullet
-@item
-Whenever documentation and actual behavior differ, you have certainly
-found a bug, either in the documentation or in the program.
-
-@item
-When Guile crashes, it is a bug.
-
-@item
-When Guile hangs or takes forever to complete a task, it is a bug.
-
-@item
-When calculations produce wrong results, it is a bug.
-
-@item
-When Guile signals an error for valid Scheme programs, it is a bug.
-
-@item
-When Guile does not signal an error for invalid Scheme programs, it may
-be a bug, unless this is explicitly documented.
-
-@item
-When some part of the documentation is not clear and does not make sense
-to you even after re-reading the section, it is a bug.
-@end itemize
-
-When you write a bug report, please make sure to include as much of the
-information described below in the report. If you can't figure out some
-of the items, it is not a problem, but the more information we get, the
-more likely we can diagnose and fix the bug.
-
-@itemize @bullet
-@item
-The version number of Guile. Without this, we won't know whether there
-is any point in looking for the bug in the current version of Guile.
-
-You can get the version number by invoking the command
-
-@example
-$ guile --version
-Guile 1.4.1
-Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
-Guile may be distributed under the terms of the GNU General Public License;
-certain other uses are permitted as well. For details, see the file
-`COPYING', which is included in the Guile distribution.
-There is no warranty, to the extent permitted by law.
-@end example
-
-@item
-The type of machine you are using, and the operating system name and
-version number. On GNU systems, you can get it with @file{uname}.
-
-@example
-$ uname -a
-Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown
-@end example
-
-@item
-The operands given to the @file{configure} command when Guile was
-installed. It's often useful to augment this with the output of the
-command @code{guile-config info}.
-
-@item
-A complete list of any modifications you have made to the Guile source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Guile. But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes. A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
-@item
-Details of any other deviations from the standard procedure for
-installing Guile.
-
-@item
-The complete text of any source files needed to reproduce the bug.
-
-If you can tell us a way to cause the problem without loading any source
-files, please do so. This makes it much easier to debug. If you do
-need files, make sure you arrange for us to see their exact contents.
-
-@item
-The precise Guile invocation command line we need to type to reproduce
-the bug.
-
-@item
-A description of what behavior you observe that you believe is
-incorrect. For example, "The Guile process gets a fatal signal," or,
-"The resulting output is as follows, which I think is wrong."
-
-Of course, if the bug is that Guile gets a fatal signal, then one can't
-miss it. But if the bug is incorrect results, the maintainer might fail
-to notice what is wrong. Why leave it to chance?
-
-If the manifestation of the bug is a Guile error message, it is
-important to report the precise text of the error message, and a
-backtrace showing how the Scheme program arrived at the error.
-
-This can be done using the procedure @code{backtrace} in the REPL.
-
-@item
-Check whether any programs you have loaded into Guile, including your
-@file{.guile} file, set any variables that may affect the functioning of
-Guile. Also, see whether the problem happens in a freshly started Guile
-without loading your @file{.guile} file (start Guile with the @code{-q}
-switch to prevent loading the init file). If the problem does
-@emph{not} occur then, you must report the precise contents of any
-programs that you must load into Guile in order to cause the problem to
-occur.
-
-@item
-If the problem does depend on an init file or other Scheme programs that
-are not part of the standard Guile distribution, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first. After they verify that they are using Guile in a way
-that is supposed to work, they should report the bug.
-
-@item
-If you wish to mention something in the Guile source, show the line of
-code with a few lines of context. Don't just give a line number.
-
-The line numbers in the development sources might not match those in your
-sources. It would take extra work for the maintainers to determine what
-code is in your version at a given line number, and we could not be
-certain.
-
-@item
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy. You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Guile distribution. To run Guile under GDB, you should
-switch to the @file{libguile} subdirectory in which Guile was compiled, then
-do @code{gdb guile} or @code{gdb .libs/guile} (if using GNU Libtool).
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-For example, many people send just a backtrace, but that is not very
-useful by itself. A simple backtrace with arguments often conveys
-little about what is happening inside Guile, because most of the
-arguments listed in the backtrace are pointers to Scheme objects. The
-numeric values of these pointers have no significance whatever; all that
-matters is the contents of the objects they point to (and most of the
-contents are themselves pointers).
-@end itemize
-
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
deleted file mode 100644
index 6f262701e..000000000
--- a/doc/ref/misc-modules.texi
+++ /dev/null
@@ -1,426 +0,0 @@
-@page
-@node Pretty Printing
-@chapter Pretty Printing
-
-@c FIXME::martin: Review me!
-
-@cindex pretty printing
-The module @code{(ice-9 pretty-print)} provides the procedure
-@code{pretty-print}, which provides nicely formatted output of Scheme
-objects. This is especially useful for deeply nested or complex data
-structures, such as lists and vectors.
-
-The module is loaded by simply saying.
-
-@lisp
-(use-modules (ice-9 pretty-print))
-@end lisp
-
-This makes the procedure @code{pretty-print} available. As an example
-how @code{pretty-print} will format the output, see the following:
-
-@lisp
-(pretty-print '(define (foo) (lambda (x)
-(cond ((zero? x) #t) ((negative? x) -x) (else (if (= x 1) 2 (* x x x)))))))
-@print{}
-(define (foo)
- (lambda (x)
- (cond ((zero? x) #t)
- ((negative? x) -x)
- (else (if (= x 1) 2 (* x x x))))))
-@end lisp
-
-@deffn {Scheme Procedure} pretty-print obj [port]
-Print the textual representation of the Scheme object @var{obj} to
-@var{port}. @var{port} defaults to the current output port, if not
-given.
-@end deffn
-
-Beware: Since @code{pretty-print} uses it's own write procedure, it's
-output will not be the same as for example the output of @code{write}.
-Consider the following example.
-
-@lisp
-(write (lambda (x) x))
-@print{}
-#<procedure #f (x)>
-
-(pretty-print (lambda (x) x))
-@print{}
-#[procedure]
-@end lisp
-
-The reason is that @code{pretty-print} does not know as much about
-Guile's object types as the builtin procedures. This is particularly
-important for smobs, for which a write procedure can be defined and be
-used by @code{write}, but not by @code{pretty-print}.
-
-
-@page
-@node Formatted Output
-@chapter Formatted Output
-
-@c FIXME::martin: Review me!
-
-@cindex format
-@cindex formatted output
-Outputting messages or other texts which are composed of literal
-strings, variable contents, newlines and other formatting can be
-cumbersome, when only the standard procedures like @code{display},
-@code{write} and @code{newline} are available. Additionally, one
-often wants to collect the output in strings. With the standard
-routines, the user is required to set up a string port, add this port
-as a parameter to the output procedure calls and then retrieve the
-resulting string from the string port.
-
-The @code{format} procedure, to be found in module @code{(ice-9
-format)}, can do all this, and even more. If you are a C programmer,
-you can think of this procedure as Guile's @code{fprintf}.
-
-@deffn {Scheme Procedure} format destination format-string args @dots{}
-The first parameter is the @var{destination}, it determines where the
-output of @code{format} will go.
-
-@table @asis
-@item @code{#t}
-Send the formatted output to the current output port and return
-@code{#t}.
-
-@item @code{#f}
-Return the formatted output as a string.
-
-@item Any number value
-Send the formatted output to the current error port and return
-@code{#t}.
-
-@item A valid output port
-Send the formatted output to the port @var{destination} and return
-@code{#t}.
-@end table
-
-The second parameter is the format string. It has a similar function
-to the format string in calls to @code{printf} or @code{fprintf} in C.
-It is output to the specified destination, but all escape sequences
-are replaced by the results of formatting the corresponding sequence.
-
-Note that escape sequences are marked with the character @code{~}
-(tilde), and not with a @code{%} (percent sign), as in C.
-
-The escape sequences in the following table are supported. When there
-appears ``corresponding @var{arg}', that means any of the additional
-arguments, after dropping all arguments which have been used up by
-escape sequences which have been processed earlier. Some of the
-format characters (the characters following the tilde) can be prefixed
-by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the
-format character. How the modified behaviour differs from the default
-behaviour is described for every character in the table where
-appropriate.
-
-@table @code
-@item ~~
-Output a single @code{~} (tilde) character.
-
-@item ~%
-Output a newline character, thus advancing to the next output line.
-
-@item ~&
-Start a new line, that is, output a newline character if not already
-at the start of a line.
-
-@item ~_
-Output a single space character.
-
-@item ~/
-Output a single tabulator character.
-
-@item ~|
-Output a page separator (formfeed) character.
-
-@item ~t
-Advance to the next tabulator position.
-
-@item ~y
-Pretty-print the corresponding @var{arg}.
-
-@item ~a
-Output the corresponding @var{arg} like @code{display}.
-
-@item ~s
-Output the corresponding @var{arg} like @code{write}.
-
-@item ~d
-Output the corresponding @var{arg} as a decimal number.
-
-@item ~x
-Output the corresponding @var{arg} as a hexadecimal number.
-
-@item ~o
-Output the corresponding @var{arg} as an octal number.
-
-@item ~b
-Output the corresponding @var{arg} as a binary number.
-
-@item ~r
-Output the corresponding @var{arg} as a number word, e.g. 10 prints as
-@code{ten}. If prefixed with @code{:}, @code{tenth} is printed, if
-prefixed with @code{:@@}, Roman numbers are printed.
-
-@item ~f
-Output the corresponding @var{arg} as a fixed format floating point
-number, such as @code{1.34}.
-
-@item ~e
-Output the corresponding @var{arg} in exponential notation, such as
-@code{1.34E+0}.
-
-@item ~g
-This works either like @code{~f} or like @code{~e}, whichever produces
-less characters to be written.
-
-@item ~$
-Like @code{~f}, but only with two digits after the decimal point.
-
-@item ~i
-Output the corresponding @var{arg} as a complex number.
-
-@item ~c
-Output the corresponding @var{arg} as a character. If prefixed with
-@code{@@}, it is printed like with @code{write}. If prefixed with
-@code{:}, control characters are treated specially, for example
-@code{#\newline} will be printed as @code{^J}.
-
-@item ~p
-``Plural''. If the corresponding @var{arg} is 1, nothing is printed
-(or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise
-@code{s} is printed (or @code{ies} if prefixed with @code{@@} or
-@code{:@@}).
-
-@item ~?, ~k
-Take the corresponding argument as a format string, and the following
-argument as a list of values. Then format the values with respect to
-the format string.
-
-@item ~!
-Flush the output to the output port.
-
-@item ~#\newline (tilde-newline)
-@c FIXME::martin: I don't understand this from the source.
-Continuation lines.
-
-@item ~*
-Argument jumping. Navigate in the argument list as specified by the
-corresponding argument. If prefixed with @code{:}, jump backwards in
-the argument list, if prefixed by @code{:@@}, jump to the parameter
-with the absolute index, otherwise jump forward in the argument list.
-
-@item ~(
-Case conversion begin. If prefixed by @code{:}, the following output
-string will be capitalized, if prefixed by @code{@@}, the first
-character will be capitalized, if prefixed by @code{:@@} it will be
-upcased and otherwise it will be downcased. Conversion stops when the
-``Case conversion end'' @code{~)}sequence is encountered.
-
-@item ~)
-Case conversion end. Stop any case conversion currently in effect.
-
-@item ~[
-@c FIXME::martin: I don't understand this from the source.
-Conditional begin.
-
-@item ~;
-@c FIXME::martin: I don't understand this from the source.
-Conditional separator.
-
-@item ~]
-@c FIXME::martin: I don't understand this from the source.
-Conditional end.
-
-@item ~@{
-@c FIXME::martin: I don't understand this from the source.
-Iteration begin.
-
-@item ~@}
-@c FIXME::martin: I don't understand this from the source.
-Iteration end.
-
-@item ~^
-@c FIXME::martin: I don't understand this from the source.
-Up and out.
-
-@item ~'
-@c FIXME::martin: I don't understand this from the source.
-Character parameter.
-
-@item ~0 @dots{} ~9, ~-, ~+
-@c FIXME::martin: I don't understand this from the source.
-Numeric parameter.
-
-@item ~v
-@c FIXME::martin: I don't understand this from the source.
-Variable parameter from next argument.
-
-@item ~#
-Parameter is number of remaining args. The number of the remaining
-arguments is prepended to the list of unprocessed arguments.
-
-@item ~,
-@c FIXME::martin: I don't understand this from the source.
-Parameter separators.
-
-@item ~q
-Inquiry message. Insert a copyright message into the output.
-@end table
-
-If any type conversions should fail (for example when using an escape
-sequence for number output, but the argument is a string), an error
-will be signalled.
-@end deffn
-
-You may have noticed that Guile contains a @code{format} procedure
-even when the module @code{(ice-9 format)} is not loaded. The default
-@code{format} procedure does not support all escape sequences
-documented in this chapter, and will signal an error if you try to use
-one of them. The reason for providing two versions of @code{format}
-is that the full-featured module is fairly large and requires some
-time to get loaded. So the Guile maintainers decided not to load the
-large version of @code{format} by default, so that the start-up time
-of the interpreter is not unnecessarily increased.
-
-
-@page
-@node Rx Regexps
-@chapter The Rx Regular Expression Library
-
-[FIXME: this is taken from Gary and Mark's quick summaries and should be
-reviewed and expanded. Rx is pretty stable, so could already be done!]
-
-@cindex rx
-@cindex finite automaton
-
-The @file{guile-lang-allover} package provides an interface to Tom
-Lord's Rx library (currently only to POSIX regular expressions). Use of
-the library requires a two step process: compile a regular expression
-into an efficient structure, then use the structure in any number of
-string comparisons.
-
-For example, given the regular expression @samp{abc.} (which matches any
-string containing @samp{abc} followed by any single character):
-
-@smalllisp
-guile> @kbd{(define r (regcomp "abc."))}
-guile> @kbd{r}
-#<rgx abc.>
-guile> @kbd{(regexec r "abc")}
-#f
-guile> @kbd{(regexec r "abcd")}
-#((0 . 4))
-guile>
-@end smalllisp
-
-The definitions of @code{regcomp} and @code{regexec} are as follows:
-
-@deffn {Scheme Procedure} regcomp pattern [flags]
-Compile the regular expression pattern using POSIX rules. Flags is
-optional and should be specified using symbolic names:
-@defvar REG_EXTENDED
-use extended POSIX syntax
-@end defvar
-@defvar REG_ICASE
-use case-insensitive matching
-@end defvar
-@defvar REG_NEWLINE
-allow anchors to match after newline characters in the
-string and prevents @code{.} or @code{[^...]} from matching newlines.
-@end defvar
-
-The @code{logior} procedure can be used to combine multiple flags.
-The default is to use
-POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
-and @code{\?}
-operators. Backslashes in @var{pattern} must be escaped if specified in a
-literal string e.g., @code{"\\(a\\)\\?"}.
-@end deffn
-
-@deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
-Match @var{string} against the compiled POSIX regular expression
-@var{regex}.
-@var{match-pick} and @var{flags} are optional. Possible flags (which can be
-combined using the logior procedure) are:
-
-@defvar REG_NOTBOL
-The beginning of line operator won't match the beginning of
-@var{string} (presumably because it's not the beginning of a line)
-@end defvar
-
-@defvar REG_NOTEOL
-Similar to REG_NOTBOL, but prevents the end of line operator
-from matching the end of @var{string}.
-@end defvar
-
-If no match is possible, regexec returns #f. Otherwise @var{match-pick}
-determines the return value:
-
-@code{#t} or unspecified: a newly-allocated vector is returned,
-containing pairs with the indices of the matched part of @var{string} and any
-substrings.
-
-@code{""}: a list is returned: the first element contains a nested list
-with the matched part of @var{string} surrounded by the the unmatched parts.
-Remaining elements are matched substrings (if any). All returned
-substrings share memory with @var{string}.
-
-@code{#f}: regexec returns #t if a match is made, otherwise #f.
-
-vector: the supplied vector is returned, with the first element replaced
-by a pair containing the indices of the matched portion of @var{string} and
-further elements replaced by pairs containing the indices of matched
-substrings (if any).
-
-list: a list will be returned, with each member of the list
-specified by a code in the corresponding position of the supplied list:
-
-a number: the numbered matching substring (0 for the entire match).
-
-@code{#\<}: the beginning of @var{string} to the beginning of the part matched
-by regex.
-
-@code{#\>}: the end of the matched part of @var{string} to the end of
-@var{string}.
-
-@code{#\c}: the "final tag", which seems to be associated with the "cut
-operator", which doesn't seem to be available through the posix
-interface.
-
-e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
-@var{string}.
-@end deffn
-
-Here are some other procedures that might be used when using regular
-expressions:
-
-@deffn {Scheme Procedure} compiled-regexp? obj
-Test whether obj is a compiled regular expression.
-@end deffn
-
-@deffn {Scheme Procedure} regexp->dfa regex [flags]
-@end deffn
-
-@deffn {Scheme Procedure} dfa-fork dfa
-@end deffn
-
-@deffn {Scheme Procedure} reset-dfa! dfa
-@end deffn
-
-@deffn {Scheme Procedure} dfa-final-tag dfa
-@end deffn
-
-@deffn {Scheme Procedure} dfa-continuable? dfa
-@end deffn
-
-@deffn {Scheme Procedure} advance-dfa! dfa string
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/new-docstrings.texi b/doc/ref/new-docstrings.texi
deleted file mode 100644
index 17aa45680..000000000
--- a/doc/ref/new-docstrings.texi
+++ /dev/null
@@ -1,701 +0,0 @@
-
-@c module (guile)
-
-@deffn {Scheme Procedure} environment? obj
-@deffnx {C Function} scm_environment_p (obj)
-Return @code{#t} if @var{obj} is an environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} environment-bound? env sym
-@deffnx {C Function} scm_environment_bound_p (env, sym)
-Return @code{#t} if @var{sym} is bound in @var{env}, or
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} environment-ref env sym
-@deffnx {C Function} scm_environment_ref (env, sym)
-Return the value of the location bound to @var{sym} in
-@var{env}. If @var{sym} is unbound in @var{env}, signal an
-@code{environment:unbound} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-fold env proc init
-@deffnx {C Function} scm_environment_fold (env, proc, init)
-Iterate over all the bindings in @var{env}, accumulating some
-value.
-For each binding in @var{env}, apply @var{proc} to the symbol
-bound, its value, and the result from the previous application
-of @var{proc}.
-Use @var{init} as @var{proc}'s third argument the first time
-@var{proc} is applied.
-If @var{env} contains no bindings, this function simply returns
-@var{init}.
-If @var{env} binds the symbol sym1 to the value val1, sym2 to
-val2, and so on, then this procedure computes:
-@lisp
- (proc sym1 val1
- (proc sym2 val2
- ...
- (proc symn valn
- init)))
-@end lisp
-Each binding in @var{env} will be processed exactly once.
-@code{environment-fold} makes no guarantees about the order in
-which the bindings are processed.
-Here is a function which, given an environment, constructs an
-association list representing that environment's bindings,
-using environment-fold:
-@lisp
- (define (environment->alist env)
- (environment-fold env
- (lambda (sym val tail)
- (cons (cons sym val) tail))
- '()))
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} environment-define env sym val
-@deffnx {C Function} scm_environment_define (env, sym, val)
-Bind @var{sym} to a new location containing @var{val} in
-@var{env}. If @var{sym} is already bound to another location
-in @var{env} and the binding is mutable, that binding is
-replaced. The new binding and location are both mutable. The
-return value is unspecified.
-If @var{sym} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-undefine env sym
-@deffnx {C Function} scm_environment_undefine (env, sym)
-Remove any binding for @var{sym} from @var{env}. If @var{sym}
-is unbound in @var{env}, do nothing. The return value is
-unspecified.
-If @var{sym} is already bound in @var{env}, and the binding is
-immutable, signal an @code{environment:immutable-binding} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-set! env sym val
-@deffnx {C Function} scm_environment_set_x (env, sym, val)
-If @var{env} binds @var{sym} to some location, change that
-location's value to @var{val}. The return value is
-unspecified.
-If @var{sym} is not bound in @var{env}, signal an
-@code{environment:unbound} error. If @var{env} binds @var{sym}
-to an immutable location, signal an
-@code{environment:immutable-location} error.
-@end deffn
-
-@deffn {Scheme Procedure} environment-cell env sym for_write
-@deffnx {C Function} scm_environment_cell (env, sym, for_write)
-Return the value cell which @var{env} binds to @var{sym}, or
-@code{#f} if the binding does not live in a value cell.
-The argument @var{for-write} indicates whether the caller
-intends to modify the variable's value by mutating the value
-cell. If the variable is immutable, then
-@code{environment-cell} signals an
-@code{environment:immutable-location} error.
-If @var{sym} is unbound in @var{env}, signal an
-@code{environment:unbound} error.
-If you use this function, you should consider using
-@code{environment-observe}, to be notified when @var{sym} gets
-re-bound to a new value cell, or becomes undefined.
-@end deffn
-
-@deffn {Scheme Procedure} environment-observe env proc
-@deffnx {C Function} scm_environment_observe (env, proc)
-Whenever @var{env}'s bindings change, apply @var{proc} to
-@var{env}.
-This function returns an object, token, which you can pass to
-@code{environment-unobserve} to remove @var{proc} from the set
-of procedures observing @var{env}. The type and value of
-token is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} environment-observe-weak env proc
-@deffnx {C Function} scm_environment_observe_weak (env, proc)
-This function is the same as environment-observe, except that
-the reference @var{env} retains to @var{proc} is a weak
-reference. This means that, if there are no other live,
-non-weak references to @var{proc}, it will be
-garbage-collected, and dropped from @var{env}'s
-list of observing procedures.
-@end deffn
-
-@deffn {Scheme Procedure} environment-unobserve token
-@deffnx {C Function} scm_environment_unobserve (token)
-Cancel the observation request which returned the value
-@var{token}. The return value is unspecified.
-If a call @code{(environment-observe env proc)} returns
-@var{token}, then the call @code{(environment-unobserve token)}
-will cause @var{proc} to no longer be called when @var{env}'s
-bindings change.
-@end deffn
-
-@deffn {Scheme Procedure} make-leaf-environment
-@deffnx {C Function} scm_make_leaf_environment ()
-Create a new leaf environment, containing no bindings.
-All bindings and locations created in the new environment
-will be mutable.
-@end deffn
-
-@deffn {Scheme Procedure} leaf-environment? object
-@deffnx {C Function} scm_leaf_environment_p (object)
-Return @code{#t} if object is a leaf environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} make-eval-environment local imported
-@deffnx {C Function} scm_make_eval_environment (local, imported)
-Return a new environment object eval whose bindings are the
-union of the bindings in the environments @var{local} and
-@var{imported}, with bindings from @var{local} taking
-precedence. Definitions made in eval are placed in @var{local}.
-Applying @code{environment-define} or
-@code{environment-undefine} to eval has the same effect as
-applying the procedure to @var{local}.
-Note that eval incorporates @var{local} and @var{imported} by
-reference:
-If, after creating eval, the program changes the bindings of
-@var{local} or @var{imported}, those changes will be visible
-in eval.
-Since most Scheme evaluation takes place in eval environments,
-they transparently cache the bindings received from @var{local}
-and @var{imported}. Thus, the first time the program looks up
-a symbol in eval, eval may make calls to @var{local} or
-@var{imported} to find their bindings, but subsequent
-references to that symbol will be as fast as references to
-bindings in finite environments.
-In typical use, @var{local} will be a finite environment, and
-@var{imported} will be an import environment
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment? object
-@deffnx {C Function} scm_eval_environment_p (object)
-Return @code{#t} if object is an eval environment, or @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-local env
-@deffnx {C Function} scm_eval_environment_local (env)
-Return the local environment of eval environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-set-local! env local
-@deffnx {C Function} scm_eval_environment_set_local_x (env, local)
-Change @var{env}'s local environment to @var{local}.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-imported env
-@deffnx {C Function} scm_eval_environment_imported (env)
-Return the imported environment of eval environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} eval-environment-set-imported! env imported
-@deffnx {C Function} scm_eval_environment_set_imported_x (env, imported)
-Change @var{env}'s imported environment to @var{imported}.
-@end deffn
-
-@deffn {Scheme Procedure} make-import-environment imports conflict_proc
-@deffnx {C Function} scm_make_import_environment (imports, conflict_proc)
-Return a new environment @var{imp} whose bindings are the union
-of the bindings from the environments in @var{imports};
-@var{imports} must be a list of environments. That is,
-@var{imp} binds a symbol to a location when some element of
-@var{imports} does.
-If two different elements of @var{imports} have a binding for
-the same symbol, the @var{conflict-proc} is called with the
-following parameters: the import environment, the symbol and
-the list of the imported environments that bind the symbol.
-If the @var{conflict-proc} returns an environment @var{env},
-the conflict is considered as resolved and the binding from
-@var{env} is used. If the @var{conflict-proc} returns some
-non-environment object, the conflict is considered unresolved
-and the symbol is treated as unspecified in the import
-environment.
-The checking for conflicts may be performed lazily, i. e. at
-the moment when a value or binding for a certain symbol is
-requested instead of the moment when the environment is
-created or the bindings of the imports change.
-All bindings in @var{imp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to
-@var{imp}, Guile will signal an
- @code{environment:immutable-binding} error. However,
-notice that the set of bindings in @var{imp} may still change,
-if one of its imported environments changes.
-@end deffn
-
-@deffn {Scheme Procedure} import-environment? object
-@deffnx {C Function} scm_import_environment_p (object)
-Return @code{#t} if object is an import environment, or
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} import-environment-imports env
-@deffnx {C Function} scm_import_environment_imports (env)
-Return the list of environments imported by the import
-environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} import-environment-set-imports! env imports
-@deffnx {C Function} scm_import_environment_set_imports_x (env, imports)
-Change @var{env}'s list of imported environments to
-@var{imports}, and check for conflicts.
-@end deffn
-
-@deffn {Scheme Procedure} make-export-environment private signature
-@deffnx {C Function} scm_make_export_environment (private, signature)
-Return a new environment @var{exp} containing only those
-bindings in private whose symbols are present in
-@var{signature}. The @var{private} argument must be an
-environment.
-
-The environment @var{exp} binds symbol to location when
-@var{env} does, and symbol is exported by @var{signature}.
-
-@var{signature} is a list specifying which of the bindings in
-@var{private} should be visible in @var{exp}. Each element of
-@var{signature} should be a list of the form:
- (symbol attribute ...)
-where each attribute is one of the following:
-@table @asis
-@item the symbol @code{mutable-location}
- @var{exp} should treat the
- location bound to symbol as mutable. That is, @var{exp}
- will pass calls to @code{environment-set!} or
- @code{environment-cell} directly through to private.
-@item the symbol @code{immutable-location}
- @var{exp} should treat
- the location bound to symbol as immutable. If the program
- applies @code{environment-set!} to @var{exp} and symbol, or
- calls @code{environment-cell} to obtain a writable value
- cell, @code{environment-set!} will signal an
- @code{environment:immutable-location} error. Note that, even
- if an export environment treats a location as immutable, the
- underlying environment may treat it as mutable, so its
- value may change.
-@end table
-It is an error for an element of signature to specify both
-@code{mutable-location} and @code{immutable-location}. If
-neither is specified, @code{immutable-location} is assumed.
-
-As a special case, if an element of signature is a lone
-symbol @var{sym}, it is equivalent to an element of the form
-@code{(sym)}.
-
-All bindings in @var{exp} are immutable. If you apply
-@code{environment-define} or @code{environment-undefine} to
-@var{exp}, Guile will signal an
-@code{environment:immutable-binding} error. However,
-notice that the set of bindings in @var{exp} may still change,
-if the bindings in private change.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment? object
-@deffnx {C Function} scm_export_environment_p (object)
-Return @code{#t} if object is an export environment, or
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-private env
-@deffnx {C Function} scm_export_environment_private (env)
-Return the private environment of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-set-private! env private
-@deffnx {C Function} scm_export_environment_set_private_x (env, private)
-Change the private environment of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-signature env
-@deffnx {C Function} scm_export_environment_signature (env)
-Return the signature of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} export-environment-set-signature! env signature
-@deffnx {C Function} scm_export_environment_set_signature_x (env, signature)
-Change the signature of export environment @var{env}.
-@end deffn
-
-@deffn {Scheme Procedure} %compute-slots class
-@deffnx {C Function} scm_sys_compute_slots (class)
-Return a list consisting of the names of all slots belonging to
-class @var{class}, i. e. the slots of @var{class} and of all of
-its superclasses.
-@end deffn
-
-@deffn {Scheme Procedure} get-keyword key l default_value
-@deffnx {C Function} scm_get_keyword (key, l, default_value)
-Determine an associated value for the keyword @var{key} from
-the list @var{l}. The list @var{l} has to consist of an even
-number of elements, where, starting with the first, every
-second element is a keyword, followed by its associated value.
-If @var{l} does not hold a value for @var{key}, the value
-@var{default_value} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} slot-ref-using-class class obj slot_name
-@deffnx {C Function} scm_slot_ref_using_class (class, obj, slot_name)
-
-@end deffn
-
-@deffn {Scheme Procedure} slot-set-using-class! class obj slot_name value
-@deffnx {C Function} scm_slot_set_using_class_x (class, obj, slot_name, value)
-
-@end deffn
-
-@deffn {Scheme Procedure} class-of x
-@deffnx {C Function} scm_class_of (x)
-Return the class of @var{x}.
-@end deffn
-
-@deffn {Scheme Procedure} %goops-loaded
-@deffnx {C Function} scm_sys_goops_loaded ()
-Announce that GOOPS is loaded and perform initialization
-on the C level which depends on the loaded GOOPS modules.
-@end deffn
-
-@deffn {Scheme Procedure} %method-more-specific? m1 m2 targs
-@deffnx {C Function} scm_sys_method_more_specific_p (m1, m2, targs)
-
-@end deffn
-
-@deffn {Scheme Procedure} find-method . l
-@deffnx {C Function} scm_find_method (l)
-
-@end deffn
-
-@deffn {Scheme Procedure} primitive-generic-generic subr
-@deffnx {C Function} scm_primitive_generic_generic (subr)
-
-@end deffn
-
-@deffn {Scheme Procedure} enable-primitive-generic! . subrs
-@deffnx {C Function} scm_enable_primitive_generic_x (subrs)
-
-@end deffn
-
-@deffn {Scheme Procedure} generic-capability? proc
-@deffnx {C Function} scm_generic_capability_p (proc)
-
-@end deffn
-
-@deffn {Scheme Procedure} %invalidate-method-cache! gf
-@deffnx {C Function} scm_sys_invalidate_method_cache_x (gf)
-
-@end deffn
-
-@deffn {Scheme Procedure} %invalidate-class class
-@deffnx {C Function} scm_sys_invalidate_class (class)
-
-@end deffn
-
-@deffn {Scheme Procedure} %modify-class old new
-@deffnx {C Function} scm_sys_modify_class (old, new)
-
-@end deffn
-
-@deffn {Scheme Procedure} %modify-instance old new
-@deffnx {C Function} scm_sys_modify_instance (old, new)
-
-@end deffn
-
-@deffn {Scheme Procedure} %set-object-setter! obj setter
-@deffnx {C Function} scm_sys_set_object_setter_x (obj, setter)
-
-@end deffn
-
-@deffn {Scheme Procedure} %allocate-instance class initargs
-@deffnx {C Function} scm_sys_allocate_instance (class, initargs)
-Create a new instance of class @var{class} and initialize it
-from the arguments @var{initargs}.
-@end deffn
-
-@deffn {Scheme Procedure} slot-exists? obj slot_name
-@deffnx {C Function} scm_slot_exists_p (obj, slot_name)
-Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
-@end deffn
-
-@deffn {Scheme Procedure} slot-bound? obj slot_name
-@deffnx {C Function} scm_slot_bound_p (obj, slot_name)
-Return @code{#t} if the slot named @var{slot_name} of @var{obj}
-is bound.
-@end deffn
-
-@deffn {Scheme Procedure} slot-set! obj slot_name value
-@deffnx {C Function} scm_slot_set_x (obj, slot_name, value)
-Set the slot named @var{slot_name} of @var{obj} to @var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} slot-exists-using-class? class obj slot_name
-@deffnx {C Function} scm_slot_exists_using_class_p (class, obj, slot_name)
-
-@end deffn
-
-@deffn {Scheme Procedure} slot-bound-using-class? class obj slot_name
-@deffnx {C Function} scm_slot_bound_using_class_p (class, obj, slot_name)
-
-@end deffn
-
-@deffn {Scheme Procedure} %fast-slot-set! obj index value
-@deffnx {C Function} scm_sys_fast_slot_set_x (obj, index, value)
-Set the slot with index @var{index} in @var{obj} to
-@var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} %fast-slot-ref obj index
-@deffnx {C Function} scm_sys_fast_slot_ref (obj, index)
-Return the slot value with index @var{index} from @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} @@assert-bound-ref obj index
-@deffnx {C Function} scm_at_assert_bound_ref (obj, index)
-Like @code{assert-bound}, but use @var{index} for accessing
-the value from @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} assert-bound value obj
-@deffnx {C Function} scm_assert_bound (value, obj)
-Return @var{value} if it is bound, and invoke the
-@var{slot-unbound} method of @var{obj} if it is not.
-@end deffn
-
-@deffn {Scheme Procedure} unbound? obj
-@deffnx {C Function} scm_unbound_p (obj)
-Return @code{#t} if @var{obj} is unbound.
-@end deffn
-
-@deffn {Scheme Procedure} make-unbound
-@deffnx {C Function} scm_make_unbound ()
-Return the unbound value.
-@end deffn
-
-@deffn {Scheme Procedure} accessor-method-slot-definition obj
-@deffnx {C Function} scm_accessor_method_slot_definition (obj)
-Return the slot definition of the accessor @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} method-procedure obj
-@deffnx {C Function} scm_method_procedure (obj)
-Return the procedure of the method @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} method-specializers obj
-@deffnx {C Function} scm_method_specializers (obj)
-Return specializers of the method @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} method-generic-function obj
-@deffnx {C Function} scm_method_generic_function (obj)
-Return the generic function for the method @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} generic-function-methods obj
-@deffnx {C Function} scm_generic_function_methods (obj)
-Return the methods of the generic function @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} generic-function-name obj
-@deffnx {C Function} scm_generic_function_name (obj)
-Return the name of the generic function @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-environment obj
-@deffnx {C Function} scm_class_environment (obj)
-Return the environment of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-slots obj
-@deffnx {C Function} scm_class_slots (obj)
-Return the slot list of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-precedence-list obj
-@deffnx {C Function} scm_class_precedence_list (obj)
-Return the class precedence list of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-methods obj
-@deffnx {C Function} scm_class_direct_methods (obj)
-Return the direct methods of the class @var{obj}
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-subclasses obj
-@deffnx {C Function} scm_class_direct_subclasses (obj)
-Return the direct subclasses of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-slots obj
-@deffnx {C Function} scm_class_direct_slots (obj)
-Return the direct slots of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-direct-supers obj
-@deffnx {C Function} scm_class_direct_supers (obj)
-Return the direct superclasses of the class @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} class-name obj
-@deffnx {C Function} scm_class_name (obj)
-Return the class name of @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} instance? obj
-@deffnx {C Function} scm_instance_p (obj)
-Return @code{#t} if @var{obj} is an instance.
-@end deffn
-
-@deffn {Scheme Procedure} %inherit-magic! class dsupers
-@deffnx {C Function} scm_sys_inherit_magic_x (class, dsupers)
-
-@end deffn
-
-@deffn {Scheme Procedure} %prep-layout! class
-@deffnx {C Function} scm_sys_prep_layout_x (class)
-
-@end deffn
-
-@deffn {Scheme Procedure} %initialize-object obj initargs
-@deffnx {C Function} scm_sys_initialize_object (obj, initargs)
-Initialize the object @var{obj} with the given arguments
-@var{initargs}.
-@end deffn
-
-@deffn {Scheme Procedure} make . args
-@deffnx {C Function} scm_make (args)
-Make a new object. @var{args} must contain the class and
-all necessary initialization information.
-@end deffn
-
-@deffn {Scheme Procedure} slot-ref obj slot_name
-@deffnx {C Function} scm_slot_ref (obj, slot_name)
-Return the value from @var{obj}'s slot with the name
-@var{slot_name}.
-@end deffn
-
-@deffn {Scheme Procedure} %tag-body body
-@deffnx {C Function} scm_sys_tag_body (body)
-Internal GOOPS magic---don't use this function!
-@end deffn
-
-@deffn {Scheme Procedure} list*
-implemented by the C function "scm_cons_star"
-@end deffn
-
-@deffn {Scheme Procedure} set-current-module module
-@deffnx {C Function} scm_set_current_module (module)
-Set the current module to @var{module} and return
-the previous current module.
-@end deffn
-
-@deffn {Scheme Procedure} current-module
-@deffnx {C Function} scm_current_module ()
-Return the current module.
-@end deffn
-
-@deffn {Scheme Procedure} c-clear-registered-modules
-Destroy the list of modules registered with the current Guile process.
-The return value is unspecified. @strong{Warning:} this function does
-not actually unlink or deallocate these modules, but only destroys the
-records of which modules have been loaded. It should therefore be used
-only by module bookkeeping operations.
-@end deffn
-
-@deffn {Scheme Procedure} c-registered-modules
-Return a list of the object code modules that have been imported into
-the current Guile process. Each element of the list is a pair whose
-car is the name of the module, and whose cdr is the function handle
-for that module's initializer function. The name is the string that
-has been passed to scm_register_module_xxx.
-@end deffn
-
-@deffn {Scheme Procedure} include-deprecated-features
-Return @code{#t} iff deprecated features should be included
-in public interfaces.
-@end deffn
-
-@deffn {Scheme Procedure} issue-deprecation-warning . msgs
-Output @var{msgs} to @code{(current-error-port)} when this
-is the first call to @code{issue-deprecation-warning} with
-this specific @var{msg}. Do nothing otherwise.
-The argument @var{msgs} should be a list of strings;
-they are printed in turn, each one followed by a newline.
-@end deffn
-
-@deffn {Scheme Procedure} valid-object-procedure? proc
-@deffnx {C Function} scm_valid_object_procedure_p (proc)
-Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}. It is always valid to use a closure constructed by @code{lambda}.
-@end deffn
-
-@deffn {Scheme Procedure} %get-pre-modules-obarray
-@deffnx {C Function} scm_get_pre_modules_obarray ()
-Return the obarray that is used for all new bindings before the module system is booted. The first call to @code{set-current-module} will boot the module system.
-@end deffn
-
-@deffn {Scheme Procedure} standard-interface-eval-closure module
-@deffnx {C Function} scm_standard_interface_eval_closure (module)
-Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
-@end deffn
-
-@deffn {Scheme Procedure} env-module env
-@deffnx {C Function} scm_env_module (env)
-Return the module of @var{ENV}, a lexical environment.
-@end deffn
-
-@deffn {Scheme Procedure} load-extension lib init
-@deffnx {C Function} scm_load_extension (lib, init)
-Load and initialize the extension designated by LIB and INIT.
-When there is no pre-registered function for LIB/INIT, this is
-equivalent to
-
-@lisp
-(dynamic-call INIT (dynamic-link LIB))
-@end lisp
-
-When there is a pre-registered function, that function is called
-instead.
-
-Normally, there is no pre-registered function. This option exists
-only for situations where dynamic linking is unavailable or unwanted.
-In that case, you would statically link your program with the desired
-library, and register its init function right after Guile has been
-initialized.
-
-LIB should be a string denoting a shared library without any file type
-suffix such as ".so". The suffix is provided automatically. It
-should also not contain any directory components. Libraries that
-implement Guile Extensions should be put into the normal locations for
-shared libraries. We recommend to use the naming convention
-libguile-bla-blum for a extension related to a module `(bla blum)'.
-
-The normal way for a extension to be used is to write a small Scheme
-file that defines a module, and to load the extension into this
-module. When the module is auto-loaded, the extension is loaded as
-well. For example,
-
-@lisp
-(define-module (bla blum))
-
-(load-extension "libguile-bla-blum" "bla_init_blum")
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} single-active-thread?
-implemented by the C function "scm_single_thread_p"
-@end deffn
-
-@deffn {Scheme Procedure} object-address obj
-@deffnx {C Function} scm_object_address (obj)
-Return an integer that for the lifetime of @var{obj} is uniquely
-returned by this function for @var{obj}
-@end deffn
-
-@deffn {Scheme Procedure} nan
-@deffnx {C Function} scm_nan ()
-Return NaN.
-@end deffn
-
-@deffn {Scheme Procedure} inf
-@deffnx {C Function} scm_inf ()
-Return Inf.
-@end deffn
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
deleted file mode 100644
index 8a9fc280e..000000000
--- a/doc/ref/posix.texi
+++ /dev/null
@@ -1,2490 +0,0 @@
-@node POSIX
-@chapter POSIX System Calls and Networking
-
-@menu
-* Conventions:: Conventions employed by the POSIX interface.
-* Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
- have different representations.
-* File System:: stat, chown, chmod, etc.
-* User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
-* Time:: gettimeofday, localtime, strftime, etc.
-* Runtime Environment:: Accessing and modifying Guile's environment.
-* Processes:: getuid, getpid, etc.
-* Signals:: sigaction, kill, pause, alarm, setitimer, etc.
-* Terminals and Ptys:: ttyname, tcsetpgrp, etc.
-* Pipes:: Communicating data between processes.
-* Networking:: gethostbyaddr, getnetent, socket, bind, listen.
-* System Identification:: Obtaining information about the system.
-* Locales:: setlocale, etc.
-* Encryption::
-@end menu
-
-@node Conventions
-@section POSIX Interface Conventions
-
-These interfaces provide access to operating system facilities.
-They provide a simple wrapping around the underlying C interfaces
-to make usage from Scheme more convenient. They are also used
-to implement the Guile port of @ref{The Scheme shell (scsh)}.
-
-Generally there is a single procedure for each corresponding Unix
-facility. There are some exceptions, such as procedures implemented for
-speed and convenience in Scheme with no primitive Unix equivalent,
-e.g., @code{copy-file}.
-
-The interfaces are intended as far as possible to be portable across
-different versions of Unix. In some cases procedures which can't be
-implemented on particular systems may become no-ops, or perform limited
-actions. In other cases they may throw errors.
-
-General naming conventions are as follows:
-
-@itemize @bullet
-@item
-The Scheme name is often identical to the name of the underlying Unix
-facility.
-@item
-Underscores in Unix procedure names are converted to hyphens.
-@item
-Procedures which destructively modify Scheme data have exclamation
-marks appended, e.g., @code{recv!}.
-@item
-Predicates (returning only @code{#t} or @code{#f}) have question marks
-appended, e.g., @code{access?}.
-@item
-Some names are changed to avoid conflict with dissimilar interfaces
-defined by scsh, e.g., @code{primitive-fork}.
-@item
-Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
-to Scheme variables of the same name (underscores are not replaced
-with hyphens).
-@end itemize
-
-Unexpected conditions are generally handled by raising exceptions.
-There are a few procedures which return a special value if they don't
-succeed, e.g., @code{getenv} returns @code{#f} if it the requested
-string is not found in the environment. These cases are noted in
-the documentation.
-
-For ways to deal with exceptions, @ref{Exceptions}.
-
-Errors which the C-library would report by returning a NULL pointer or
-through some other means are reported by raising a @code{system-error}
-exception. The value of the Unix @code{errno} variable is available
-in the data passed by the exception.
-
-It can be extracted with the function @code{system-error-errno}:
-
-@example
-(catch
- 'system-error
- (lambda ()
- (mkdir "/this-ought-to-fail-if-I'm-not-root"))
- (lambda stuff
- (let ((errno (system-error-errno stuff)))
- (cond
- ((= errno EACCES)
- (display "You're not allowed to do that."))
- ((= errno EEXIST)
- (display "Already exists."))
- (#t
- (display (strerror errno))))
- (newline))))
-@end example
-
-@node Ports and File Descriptors
-@section Ports and File Descriptors
-
-Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
-
-File ports are implemented using low-level operating system I/O
-facilities, with optional buffering to improve efficiency
-@pxref{File Ports}
-
-Note that some procedures (e.g., @code{recv!}) will accept ports as
-arguments, but will actually operate directly on the file descriptor
-underlying the port. Any port buffering is ignored, including the
-buffer which implements @code{peek-char} and @code{unread-char}.
-
-The @code{force-output} and @code{drain-input} procedures can be used
-to clear the buffers.
-
-Each open file port has an associated operating system file descriptor.
-File descriptors are generally not useful in Scheme programs; however
-they may be needed when interfacing with foreign code and the Unix
-environment.
-
-A file descriptor can be extracted from a port and a new port can be
-created from a file descriptor. However a file descriptor is just an
-integer and the garbage collector doesn't recognize it as a reference
-to the port. If all other references to the port were dropped, then
-it's likely that the garbage collector would free the port, with the
-side-effect of closing the file descriptor prematurely.
-
-To assist the programmer in avoiding this problem, each port has an
-associated "revealed count" which can be used to keep track of how many
-times the underlying file descriptor has been stored in other places.
-If a port's revealed count is greater than zero, the file descriptor
-will not be closed when the port is garbage collected. A programmer
-can therefore ensure that the revealed count will be greater than
-zero if the file descriptor is needed elsewhere.
-
-For the simple case where a file descriptor is "imported" once to become
-a port, it does not matter if the file descriptor is closed when the
-port is garbage collected. There is no need to maintain a revealed
-count. Likewise when "exporting" a file descriptor to the external
-environment, setting the revealed count is not required provided the
-port is kept open (i.e., is pointed to by a live Scheme binding) while
-the file descriptor is in use.
-
-To correspond with traditional Unix behaviour, the three file
-descriptors (0, 1 and 2) are automatically imported when a program
-starts up and assigned to the initial values of the current input,
-output and error ports. The revealed count for each is initially set to
-one, so that dropping references to one of these ports will not result
-in its garbage collection: it could be retrieved with fdopen or
-fdes->ports.
-
-@deffn {Scheme Procedure} port-revealed port
-@deffnx {C Function} scm_port_revealed (port)
-Return the revealed count for @var{port}.
-@end deffn
-
-@deffn {Scheme Procedure} set-port-revealed! port rcount
-@deffnx {C Function} scm_set_port_revealed_x (port, rcount)
-Sets the revealed count for a port to a given value.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} fileno port
-@deffnx {C Function} scm_fileno (port)
-Return the integer file descriptor underlying @var{port}. Does
-not change its revealed count.
-@end deffn
-
-@deffn {Scheme Procedure} port->fdes port
-Returns the integer file descriptor underlying @var{port}. As a
-side effect the revealed count of @var{port} is incremented.
-@end deffn
-
-@deffn {Scheme Procedure} fdopen fdes modes
-@deffnx {C Function} scm_fdopen (fdes, modes)
-Return a new port based on the file descriptor @var{fdes}.
-Modes are given by the string @var{modes}. The revealed count
-of the port is initialized to zero. The modes string is the
-same as that accepted by @ref{File Ports, open-file}.
-@end deffn
-
-@deffn {Scheme Procedure} fdes->ports fd
-@deffnx {C Function} scm_fdes_to_ports (fd)
-Return a list of existing ports which have @var{fdes} as an
-underlying file descriptor, without changing their revealed
-counts.
-@end deffn
-
-@deffn {Scheme Procedure} fdes->inport fdes
-Returns an existing input port which has @var{fdes} as its underlying file
-descriptor, if one exists, and increments its revealed count.
-Otherwise, returns a new input port with a revealed count of 1.
-@end deffn
-
-@deffn {Scheme Procedure} fdes->outport fdes
-Returns an existing output port which has @var{fdes} as its underlying file
-descriptor, if one exists, and increments its revealed count.
-Otherwise, returns a new output port with a revealed count of 1.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-move->fdes port fd
-@deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
-Moves the underlying file descriptor for @var{port} to the integer
-value @var{fdes} without changing the revealed count of @var{port}.
-Any other ports already using this descriptor will be automatically
-shifted to new descriptors and their revealed counts reset to zero.
-The return value is @code{#f} if the file descriptor already had the
-required value or @code{#t} if it was moved.
-@end deffn
-
-@deffn {Scheme Procedure} move->fdes port fdes
-Moves the underlying file descriptor for @var{port} to the integer
-value @var{fdes} and sets its revealed count to one. Any other ports
-already using this descriptor will be automatically
-shifted to new descriptors and their revealed counts reset to zero.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} release-port-handle port
-Decrements the revealed count for a port.
-@end deffn
-
-@deffn {Scheme Procedure} fsync object
-@deffnx {C Function} scm_fsync (object)
-Copies any unwritten data for the specified output file descriptor to disk.
-If @var{port/fd} is a port, its buffer is flushed before the underlying
-file descriptor is fsync'd.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} open path flags [mode]
-@deffnx {C Function} scm_open (path, flags, mode)
-Open the file named by @var{path} for reading and/or writing.
-@var{flags} is an integer specifying how the file should be opened.
-@var{mode} is an integer specifying the permission bits of the file, if
-it needs to be created, before the umask is applied. The default is 666
-(Unix itself has no default).
-
-@var{flags} can be constructed by combining variables using @code{logior}.
-Basic flags are:
-
-@defvar O_RDONLY
-Open the file read-only.
-@end defvar
-@defvar O_WRONLY
-Open the file write-only.
-@end defvar
-@defvar O_RDWR
-Open the file read/write.
-@end defvar
-@defvar O_APPEND
-Append to the file instead of truncating.
-@end defvar
-@defvar O_CREAT
-Create the file if it does not already exist.
-@end defvar
-
-See the Unix documentation of the @code{open} system call
-for additional flags.
-@end deffn
-
-@deffn {Scheme Procedure} open-fdes path flags [mode]
-@deffnx {C Function} scm_open_fdes (path, flags, mode)
-Similar to @code{open} but return a file descriptor instead of
-a port.
-@end deffn
-
-@deffn {Scheme Procedure} close fd_or_port
-@deffnx {C Function} scm_close (fd_or_port)
-Similar to close-port (@pxref{Closing, close-port}),
-but also works on file descriptors. A side
-effect of closing a file descriptor is that any ports using that file
-descriptor are moved to a different file descriptor and have
-their revealed counts set to zero.
-@end deffn
-
-@deffn {Scheme Procedure} close-fdes fd
-@deffnx {C Function} scm_close_fdes (fd)
-A simple wrapper for the @code{close} system call.
-Close file descriptor @var{fd}, which must be an integer.
-Unlike close (@pxref{Ports and File Descriptors, close}),
-the file descriptor will be closed even if a port is using it.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} unread-char char [port]
-@deffnx {C Function} scm_unread_char (char, port)
-Place @var{char} in @var{port} so that it will be read by the
-next read operation. If called multiple times, the unread characters
-will be read again in last-in first-out order. If @var{port} is
-not supplied, the current input port is used.
-@end deffn
-
-@deffn {Scheme Procedure} unread-string str port
-Place the string @var{str} in @var{port} so that its characters will be
-read in subsequent read operations. If called multiple times, the
-unread characters will be read again in last-in first-out order. If
-@var{port} is not supplied, the current-input-port is used.
-@end deffn
-
-@deffn {Scheme Procedure} pipe
-@deffnx {C Function} scm_pipe ()
-Return a newly created pipe: a pair of ports which are linked
-together on the local machine. The @emph{car} is the input
-port and the @emph{cdr} is the output port. Data written (and
-flushed) to the output port can be read from the input port.
-Pipes are commonly used for communication with a newly forked
-child process. The need to flush the output port can be
-avoided by making it unbuffered using @code{setvbuf}.
-
-Writes occur atomically provided the size of the data in bytes
-is not greater than the value of @code{PIPE_BUF}. Note that
-the output port is likely to block if too much data (typically
-equal to @code{PIPE_BUF}) has been written but not yet read
-from the input port.
-@end deffn
-
-The next group of procedures perform a @code{dup2}
-system call, if @var{newfd} (an
-integer) is supplied, otherwise a @code{dup}. The file descriptor to be
-duplicated can be supplied as an integer or contained in a port. The
-type of value returned varies depending on which procedure is used.
-
-All procedures also have the side effect when performing @code{dup2} that any
-ports using @var{newfd} are moved to a different file descriptor and have
-their revealed counts set to zero.
-
-@deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
-@deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
-Return a new integer file descriptor referring to the open file
-designated by @var{fd_or_port}, which must be either an open
-file port or a file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup->inport port/fd [newfd]
-Returns a new input port using the new file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup->outport port/fd [newfd]
-Returns a new output port using the new file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup port/fd [newfd]
-Returns a new port if @var{port/fd} is a port, with the same mode as the
-supplied port, otherwise returns an integer file descriptor.
-@end deffn
-
-@deffn {Scheme Procedure} dup->port port/fd mode [newfd]
-Returns a new port using the new file descriptor. @var{mode} supplies a
-mode string for the port (@pxref{File Ports, open-file}).
-@end deffn
-
-@deffn {Scheme Procedure} duplicate-port port modes
-Returns a new port which is opened on a duplicate of the file
-descriptor underlying @var{port}, with mode string @var{modes}
-as for @ref{File Ports, open-file}. The two ports
-will share a file position and file status flags.
-
-Unexpected behaviour can result if both ports are subsequently used
-and the original and/or duplicate ports are buffered.
-The mode string can include @code{0} to obtain an unbuffered duplicate
-port.
-
-This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
-@end deffn
-
-@deffn {Scheme Procedure} redirect-port old new
-@deffnx {C Function} scm_redirect_port (old, new)
-This procedure takes two ports and duplicates the underlying file
-descriptor from @var{old-port} into @var{new-port}. The
-current file descriptor in @var{new-port} will be closed.
-After the redirection the two ports will share a file position
-and file status flags.
-
-The return value is unspecified.
-
-Unexpected behaviour can result if both ports are subsequently used
-and the original and/or duplicate ports are buffered.
-
-This procedure does not have any side effects on other ports or
-revealed counts.
-@end deffn
-
-@deffn {Scheme Procedure} dup2 oldfd newfd
-@deffnx {C Function} scm_dup2 (oldfd, newfd)
-A simple wrapper for the @code{dup2} system call.
-Copies the file descriptor @var{oldfd} to descriptor
-number @var{newfd}, replacing the previous meaning
-of @var{newfd}. Both @var{oldfd} and @var{newfd} must
-be integers.
-Unlike for dup->fdes or primitive-move->fdes, no attempt
-is made to move away ports which are using @var{newfd}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} port-mode port
-Return the port modes associated with the open port @var{port}.
-These will not necessarily be identical to the modes used when
-the port was opened, since modes such as "append" which are
-used only during port creation are not retained.
-@end deffn
-
-@deffn {Scheme Procedure} port-for-each proc
-@deffnx {C Function} scm_port_for_each (proc)
-Apply @var{proc} to each port in the Guile port table
-in turn. The return value is unspecified. More specifically,
-@var{proc} is applied exactly once to every port that exists
-in the system at the time @var{port-for-each} is invoked.
-Changes to the port table while @var{port-for-each} is running
-have no effect as far as @var{port-for-each} is concerned.
-@end deffn
-
-@deffn {Scheme Procedure} setvbuf port mode [size]
-@deffnx {C Function} scm_setvbuf (port, mode, size)
-Set the buffering mode for @var{port}. @var{mode} can be:
-@table @code
-@item _IONBF
-non-buffered
-@item _IOLBF
-line buffered
-@item _IOFBF
-block buffered, using a newly allocated buffer of @var{size} bytes.
-If @var{size} is omitted, a default size will be used.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} fcntl object cmd [value]
-@deffnx {C Function} scm_fcntl (object, cmd, value)
-Apply @var{command} to the specified file descriptor or the underlying
-file descriptor of the specified port. @var{value} is an optional
-integer argument.
-
-Values for @var{command} are:
-
-@table @code
-@item F_DUPFD
-Duplicate a file descriptor
-@item F_GETFD
-Get flags associated with the file descriptor.
-@item F_SETFD
-Set flags associated with the file descriptor to @var{value}.
-@item F_GETFL
-Get flags associated with the open file.
-@item F_SETFL
-Set flags associated with the open file to @var{value}
-@item F_GETOWN
-Get the process ID of a socket's owner, for @code{SIGIO} signals.
-@item F_SETOWN
-Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
-@item FD_CLOEXEC
-The value used to indicate the "close on exec" flag with @code{F_GETFL} or
-@code{F_SETFL}.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} flock file operation
-@deffnx {C Function} scm_flock (file, operation)
-Apply or remove an advisory lock on an open file.
-@var{operation} specifies the action to be done:
-@table @code
-@item LOCK_SH
-Shared lock. More than one process may hold a shared lock
-for a given file at a given time.
-@item LOCK_EX
-Exclusive lock. Only one process may hold an exclusive lock
-for a given file at a given time.
-@item LOCK_UN
-Unlock the file.
-@item LOCK_NB
-Don't block when locking. May be specified by bitwise OR'ing
-it to one of the other operations.
-@end table
-The return value is not specified. @var{file} may be an open
-file descriptor or an open file descriptor port.
-@end deffn
-
-@deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
-@deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
-This procedure has a variety of uses: waiting for the ability
-to provide input, accept output, or the existence of
-exceptional conditions on a collection of ports or file
-descriptors, or waiting for a timeout to occur.
-It also returns if interrupted by a signal.
-
-@var{reads}, @var{writes} and @var{excepts} can be lists or
-vectors, with each member a port or a file descriptor.
-The value returned is a list of three corresponding
-lists or vectors containing only the members which meet the
-specified requirement. The ability of port buffers to
-provide input or accept output is taken into account.
-Ordering of the input lists or vectors is not preserved.
-
-The optional arguments @var{secs} and @var{usecs} specify the
-timeout. Either @var{secs} can be specified alone, as
-either an integer or a real number, or both @var{secs} and
-@var{usecs} can be specified as integers, in which case
-@var{usecs} is an additional timeout expressed in
-microseconds. If @var{secs} is omitted or is @code{#f} then
-select will wait for as long as it takes for one of the other
-conditions to be satisfied.
-
-The scsh version of @code{select} differs as follows:
-Only vectors are accepted for the first three arguments.
-The @var{usecs} argument is not supported.
-Multiple values are returned instead of a list.
-Duplicates in the input vectors appear only once in output.
-An additional @code{select!} interface is provided.
-@end deffn
-
-@node File System
-@section File System
-
-These procedures allow querying and setting file system attributes
-(such as owner,
-permissions, sizes and types of files); deleting, copying, renaming and
-linking files; creating and removing directories and querying their
-contents; syncing the file system and creating special files.
-
-@deffn {Scheme Procedure} access? path how
-@deffnx {C Function} scm_access (path, how)
-Return @code{#t} if @var{path} corresponds to an existing file
-and the current process has the type of access specified by
-@var{how}, otherwise @code{#f}. @var{how} should be specified
-using the values of the variables listed below. Multiple
-values can be combined using a bitwise or, in which case
-@code{#t} will only be returned if all accesses are granted.
-
-Permissions are checked using the real id of the current
-process, not the effective id, although it's the effective id
-which determines whether the access would actually be granted.
-
-@defvar R_OK
-test for read permission.
-@end defvar
-@defvar W_OK
-test for write permission.
-@end defvar
-@defvar X_OK
-test for execute permission.
-@end defvar
-@defvar F_OK
-test for existence of the file.
-@end defvar
-@end deffn
-
-@findex fstat
-@deffn {Scheme Procedure} stat object
-@deffnx {C Function} scm_stat (object)
-Return an object containing various information about the file
-determined by @var{obj}. @var{obj} can be a string containing
-a file name or a port or integer file descriptor which is open
-on a file (in which case @code{fstat} is used as the underlying
-system call).
-
-The object returned by @code{stat} can be passed as a single
-parameter to the following procedures, all of which return
-integers:
-
-@table @code
-@item stat:dev
-The device containing the file.
-@item stat:ino
-The file serial number, which distinguishes this file from all
-other files on the same device.
-@item stat:mode
-The mode of the file. This includes file type information and
-the file permission bits. See @code{stat:type} and
-@code{stat:perms} below.
-@item stat:nlink
-The number of hard links to the file.
-@item stat:uid
-The user ID of the file's owner.
-@item stat:gid
-The group ID of the file.
-@item stat:rdev
-Device ID; this entry is defined only for character or block
-special files.
-@item stat:size
-The size of a regular file in bytes.
-@item stat:atime
-The last access time for the file.
-@item stat:mtime
-The last modification time for the file.
-@item stat:ctime
-The last modification time for the attributes of the file.
-@item stat:blksize
-The optimal block size for reading or writing the file, in
-bytes.
-@item stat:blocks
-The amount of disk space that the file occupies measured in
-units of 512 byte blocks.
-@end table
-
-In addition, the following procedures return the information
-from stat:mode in a more convenient form:
-
-@table @code
-@item stat:type
-A symbol representing the type of file. Possible values are
-regular, directory, symlink, block-special, char-special, fifo,
-socket and unknown
-@item stat:perms
-An integer representing the access permission bits.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} lstat str
-@deffnx {C Function} scm_lstat (str)
-Similar to @code{stat}, but does not follow symbolic links, i.e.,
-it will return information about a symbolic link itself, not the
-file it points to. @var{path} must be a string.
-@end deffn
-
-@deffn {Scheme Procedure} readlink path
-@deffnx {C Function} scm_readlink (path)
-Return the value of the symbolic link named by @var{path} (a
-string), i.e., the file that the link points to.
-@end deffn
-
-@findex fchown
-@findex lchown
-@deffn {Scheme Procedure} chown object owner group
-@deffnx {C Function} scm_chown (object, owner, group)
-Change the ownership and group of the file referred to by @var{object} to
-the integer values @var{owner} and @var{group}. @var{object} can be
-a string containing a file name or, if the platform
-supports fchown, a port or integer file descriptor
-which is open on the file. The return value
-is unspecified.
-
-If @var{object} is a symbolic link, either the
-ownership of the link or the ownership of the referenced file will be
-changed depending on the operating system (lchown is
-unsupported at present). If @var{owner} or @var{group} is specified
-as @code{-1}, then that ID is not changed.
-@end deffn
-
-@findex fchmod
-@deffn {Scheme Procedure} chmod object mode
-@deffnx {C Function} scm_chmod (object, mode)
-Changes the permissions of the file referred to by @var{obj}.
-@var{obj} can be a string containing a file name or a port or integer file
-descriptor which is open on a file (in which case @code{fchmod} is used
-as the underlying system call).
-@var{mode} specifies
-the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} utime pathname [actime [modtime]]
-@deffnx {C Function} scm_utime (pathname, actime, modtime)
-@code{utime} sets the access and modification times for the
-file named by @var{path}. If @var{actime} or @var{modtime} is
-not supplied, then the current time is used. @var{actime} and
-@var{modtime} must be integer time values as returned by the
-@code{current-time} procedure.
-@lisp
-(utime "foo" (- (current-time) 3600))
-@end lisp
-will set the access time to one hour in the past and the
-modification time to the current time.
-@end deffn
-
-@findex unlink
-@deffn {Scheme Procedure} delete-file str
-@deffnx {C Function} scm_delete_file (str)
-Deletes (or "unlinks") the file specified by @var{path}.
-@end deffn
-
-@deffn {Scheme Procedure} copy-file oldfile newfile
-@deffnx {C Function} scm_copy_file (oldfile, newfile)
-Copy the file specified by @var{path-from} to @var{path-to}.
-The return value is unspecified.
-@end deffn
-
-@findex rename
-@deffn {Scheme Procedure} rename-file oldname newname
-@deffnx {C Function} scm_rename (oldname, newname)
-Renames the file specified by @var{oldname} to @var{newname}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} link oldpath newpath
-@deffnx {C Function} scm_link (oldpath, newpath)
-Creates a new name @var{newpath} in the file system for the
-file named by @var{oldpath}. If @var{oldpath} is a symbolic
-link, the link may or may not be followed depending on the
-system.
-@end deffn
-
-@deffn {Scheme Procedure} symlink oldpath newpath
-@deffnx {C Function} scm_symlink (oldpath, newpath)
-Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
-@var{path-from}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} mkdir path [mode]
-@deffnx {C Function} scm_mkdir (path, mode)
-Create a new directory named by @var{path}. If @var{mode} is omitted
-then the permissions of the directory file are set using the current
-umask. Otherwise they are set to the decimal value specified with
-@var{mode}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} rmdir path
-@deffnx {C Function} scm_rmdir (path)
-Remove the existing directory named by @var{path}. The directory must
-be empty for this to succeed. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} opendir dirname
-@deffnx {C Function} scm_opendir (dirname)
-Open the directory specified by @var{path} and return a directory
-stream.
-@end deffn
-
-@deffn {Scheme Procedure} directory-stream? obj
-@deffnx {C Function} scm_directory_stream_p (obj)
-Return a boolean indicating whether @var{object} is a directory
-stream as returned by @code{opendir}.
-@end deffn
-
-@deffn {Scheme Procedure} readdir port
-@deffnx {C Function} scm_readdir (port)
-Return (as a string) the next directory entry from the directory stream
-@var{stream}. If there is no remaining entry to be read then the
-end of file object is returned.
-@end deffn
-
-@deffn {Scheme Procedure} rewinddir port
-@deffnx {C Function} scm_rewinddir (port)
-Reset the directory port @var{stream} so that the next call to
-@code{readdir} will return the first directory entry.
-@end deffn
-
-@deffn {Scheme Procedure} closedir port
-@deffnx {C Function} scm_closedir (port)
-Close the directory stream @var{stream}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} sync
-@deffnx {C Function} scm_sync ()
-Flush the operating system disk buffers.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} mknod path type perms dev
-@deffnx {C Function} scm_mknod (path, type, perms, dev)
-Creates a new special file, such as a file corresponding to a device.
-@var{path} specifies the name of the file. @var{type} should
-be one of the following symbols:
-regular, directory, symlink, block-special, char-special,
-fifo, or socket. @var{perms} (an integer) specifies the file permissions.
-@var{dev} (an integer) specifies which device the special file refers
-to. Its exact interpretation depends on the kind of special file
-being created.
-
-E.g.,
-@lisp
-(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
-@end lisp
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} tmpnam
-@deffnx {C Function} scm_tmpnam ()
-Return a name in the file system that does not match any
-existing file. However there is no guarantee that another
-process will not create the file after @code{tmpnam} is called.
-Care should be taken if opening the file, e.g., use the
-@code{O_EXCL} open flag or use @code{mkstemp!} instead.
-@end deffn
-
-@deffn {Scheme Procedure} mkstemp! tmpl
-@deffnx {C Function} scm_mkstemp (tmpl)
-Create a new unique file in the file system and returns a new
-buffered port open for reading and writing to the file.
-@var{tmpl} is a string specifying where the file should be
-created: it must end with @code{XXXXXX} and will be changed in
-place to return the name of the temporary file.
-@end deffn
-
-@deffn {Scheme Procedure} dirname filename
-@deffnx {C Function} scm_dirname (filename)
-Return the directory name component of the file name
-@var{filename}. If @var{filename} does not contain a directory
-component, @code{.} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} basename filename [suffix]
-@deffnx {C Function} scm_basename (filename, suffix)
-Return the base name of the file name @var{filename}. The
-base name is the file name without any directory components.
-If @var{suffix} is provided, and is equal to the end of
-@var{basename}, it is removed also.
-@end deffn
-
-
-@node User Information
-@section User Information
-
-The facilities in this section provide an interface to the user and
-group database.
-They should be used with care since they are not reentrant.
-
-The following functions accept an object representing user information
-and return a selected component:
-
-@table @code
-@item passwd:name
-The name of the userid.
-@item passwd:passwd
-The encrypted passwd.
-@item passwd:uid
-The user id number.
-@item passwd:gid
-The group id number.
-@item passwd:gecos
-The full name.
-@item passwd:dir
-The home directory.
-@item passwd:shell
-The login shell.
-@end table
-
-@deffn {Scheme Procedure} getpwuid uid
-Look up an integer userid in the user database.
-@end deffn
-
-@deffn {Scheme Procedure} getpwnam name
-Look up a user name string in the user database.
-@end deffn
-
-@deffn {Scheme Procedure} setpwent
-Initializes a stream used by @code{getpwent} to read from the user database.
-The next use of @code{getpwent} will return the first entry. The
-return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} getpwent
-Return the next entry in the user database, using the stream set by
-@code{setpwent}.
-@end deffn
-
-@deffn {Scheme Procedure} endpwent
-Closes the stream used by @code{getpwent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setpw [arg]
-@deffnx {C Function} scm_setpwent (arg)
-If called with a true argument, initialize or reset the password data
-stream. Otherwise, close the stream. The @code{setpwent} and
-@code{endpwent} procedures are implemented on top of this.
-@end deffn
-
-@deffn {Scheme Procedure} getpw [user]
-@deffnx {C Function} scm_getpwuid (user)
-Look up an entry in the user database. @var{obj} can be an integer,
-a string, or omitted, giving the behaviour of getpwuid, getpwnam
-or getpwent respectively.
-@end deffn
-
-The following functions accept an object representing group information
-and return a selected component:
-
-@table @code
-@item group:name
-The group name.
-@item group:passwd
-The encrypted group password.
-@item group:gid
-The group id number.
-@item group:mem
-A list of userids which have this group as a supplementary group.
-@end table
-
-@deffn {Scheme Procedure} getgrgid gid
-Look up an integer group id in the group database.
-@end deffn
-
-@deffn {Scheme Procedure} getgrnam name
-Look up a group name in the group database.
-@end deffn
-
-@deffn {Scheme Procedure} setgrent
-Initializes a stream used by @code{getgrent} to read from the group database.
-The next use of @code{getgrent} will return the first entry.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} getgrent
-Return the next entry in the group database, using the stream set by
-@code{setgrent}.
-@end deffn
-
-@deffn {Scheme Procedure} endgrent
-Closes the stream used by @code{getgrent}.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setgr [arg]
-@deffnx {C Function} scm_setgrent (arg)
-If called with a true argument, initialize or reset the group data
-stream. Otherwise, close the stream. The @code{setgrent} and
-@code{endgrent} procedures are implemented on top of this.
-@end deffn
-
-@deffn {Scheme Procedure} getgr [name]
-@deffnx {C Function} scm_getgrgid (name)
-Look up an entry in the group database. @var{obj} can be an integer,
-a string, or omitted, giving the behaviour of getgrgid, getgrnam
-or getgrent respectively.
-@end deffn
-
-In addition to the accessor procedures for the user database, the
-following shortcut procedures are also available.
-
-@deffn {Scheme Procedure} cuserid
-@deffnx {C Function} scm_cuserid ()
-Return a string containing a user name associated with the
-effective user id of the process. Return @code{#f} if this
-information cannot be obtained.
-@end deffn
-
-@deffn {Scheme Procedure} getlogin
-@deffnx {C Function} scm_getlogin ()
-Return a string containing the name of the user logged in on
-the controlling terminal of the process, or @code{#f} if this
-information cannot be obtained.
-@end deffn
-
-
-@node Time
-@section Time
-
-@deffn {Scheme Procedure} current-time
-@deffnx {C Function} scm_current_time ()
-Return the number of seconds since 1970-01-01 00:00:00 UTC,
-excluding leap seconds.
-@end deffn
-
-@deffn {Scheme Procedure} gettimeofday
-@deffnx {C Function} scm_gettimeofday ()
-Return a pair containing the number of seconds and microseconds
-since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
-whether true microsecond resolution is available depends on the
-operating system.
-@end deffn
-
-The following procedures either accept an object representing a broken down
-time and return a selected component, or accept an object representing
-a broken down time and a value and set the component to the value.
-The numbers in parentheses give the usual range.
-
-@table @code
-@item tm:sec, set-tm:sec
-Seconds (0-59).
-@item tm:min, set-tm:min
-Minutes (0-59).
-@item tm:hour, set-tm:hour
-Hours (0-23).
-@item tm:mday, set-tm:mday
-Day of the month (1-31).
-@item tm:mon, set-tm:mon
-Month (0-11).
-@item tm:year, set-tm:year
-Year (70-), the year minus 1900.
-@item tm:wday, set-tm:wday
-Day of the week (0-6) with Sunday represented as 0.
-@item tm:yday, set-tm:yday
-Day of the year (0-364, 365 in leap years).
-@item tm:isdst, set-tm:isdst
-Daylight saving indicator (0 for "no", greater than 0 for "yes", less than
-0 for "unknown").
-@item tm:gmtoff, set-tm:gmtoff
-Time zone offset in seconds west of UTC (-46800 to 43200).
-@item tm:zone, set-tm:zone
-Time zone label (a string), not necessarily unique.
-@end table
-
-@deffn {Scheme Procedure} localtime time [zone]
-@deffnx {C Function} scm_localtime (time, zone)
-Return an object representing the broken down components of
-@var{time}, an integer like the one returned by
-@code{current-time}. The time zone for the calculation is
-optionally specified by @var{zone} (a string), otherwise the
-@code{TZ} environment variable or the system default is used.
-@end deffn
-
-@deffn {Scheme Procedure} gmtime time
-@deffnx {C Function} scm_gmtime (time)
-Return an object representing the broken down components of
-@var{time}, an integer like the one returned by
-@code{current-time}. The values are calculated for UTC.
-@end deffn
-
-@deffn {Scheme Procedure} mktime sbd_time [zone]
-@deffnx {C Function} scm_mktime (sbd_time, zone)
-@var{bd-time} is an object representing broken down time and @code{zone}
-is an optional time zone specifier (otherwise the TZ environment variable
-or the system default is used).
-
-Returns a pair: the car is a corresponding
-integer time value like that returned
-by @code{current-time}; the cdr is a broken down time object, similar to
-as @var{bd-time} but with normalized values.
-@end deffn
-
-@deffn {Scheme Procedure} tzset
-@deffnx {C Function} scm_tzset ()
-Initialize the timezone from the TZ environment variable
-or the system default. It's not usually necessary to call this procedure
-since it's done automatically by other procedures that depend on the
-timezone.
-@end deffn
-
-@deffn {Scheme Procedure} strftime format stime
-@deffnx {C Function} scm_strftime (format, stime)
-Formats a time specification @var{time} using @var{template}. @var{time}
-is an object with time components in the form returned by @code{localtime}
-or @code{gmtime}. @var{template} is a string which can include formatting
-specifications introduced by a @code{%} character. The formatting of
-month and day names is dependent on the current locale. The value returned
-is the formatted string.
-@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
-@end deffn
-
-@deffn {Scheme Procedure} strptime format string
-@deffnx {C Function} scm_strptime (format, string)
-Performs the reverse action to @code{strftime}, parsing
-@var{string} according to the specification supplied in
-@var{template}. The interpretation of month and day names is
-dependent on the current locale. The value returned is a pair.
-The car has an object with time components
-in the form returned by @code{localtime} or @code{gmtime},
-but the time zone components
-are not usefully set.
-The cdr reports the number of characters from @var{string}
-which were used for the conversion.
-@end deffn
-
-@defvar internal-time-units-per-second
-The value of this variable is the number of time units per second
-reported by the following procedures.
-@end defvar
-
-@deffn {Scheme Procedure} times
-@deffnx {C Function} scm_times ()
-Return an object with information about real and processor
-time. The following procedures accept such an object as an
-argument and return a selected component:
-
-@table @code
-@item tms:clock
-The current real time, expressed as time units relative to an
-arbitrary base.
-@item tms:utime
-The CPU time units used by the calling process.
-@item tms:stime
-The CPU time units used by the system on behalf of the calling
-process.
-@item tms:cutime
-The CPU time units used by terminated child processes of the
-calling process, whose status has been collected (e.g., using
-@code{waitpid}).
-@item tms:cstime
-Similarly, the CPU times units used by the system on behalf of
-terminated child processes.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} get-internal-real-time
-@deffnx {C Function} scm_get_internal_real_time ()
-Return the number of time units since the interpreter was
-started.
-@end deffn
-
-@deffn {Scheme Procedure} get-internal-run-time
-@deffnx {C Function} scm_get_internal_run_time ()
-Return the number of time units of processor time used by the
-interpreter. Both @emph{system} and @emph{user} time are
-included but subprocesses are not.
-@end deffn
-
-@node Runtime Environment
-@section Runtime Environment
-
-@deffn {Scheme Procedure} program-arguments
-@deffnx {Scheme Procedure} command-line
-@deffnx {C Function} scm_program_arguments ()
-Return the list of command line arguments passed to Guile, as a list of
-strings. The list includes the invoked program name, which is usually
-@code{"guile"}, but excludes switches and parameters for command line
-options like @code{-e} and @code{-l}.
-@end deffn
-
-@deffn {Scheme Procedure} getenv nam
-@deffnx {C Function} scm_getenv (nam)
-Looks up the string @var{name} in the current environment. The return
-value is @code{#f} unless a string of the form @code{NAME=VALUE} is
-found, in which case the string @code{VALUE} is returned.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "setenv")
-@deffn {Scheme Procedure} setenv name value
-Modifies the environment of the current process, which is
-also the default environment inherited by child processes.
-
-If @var{value} is @code{#f}, then @var{name} is removed from the
-environment. Otherwise, the string @var{name}=@var{value} is added
-to the environment, replacing any existing string with name matching
-@var{name}.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} environ [env]
-@deffnx {C Function} scm_environ (env)
-If @var{env} is omitted, return the current environment (in the
-Unix sense) as a list of strings. Otherwise set the current
-environment, which is also the default environment for child
-processes, to the supplied list of strings. Each member of
-@var{env} should be of the form @code{NAME=VALUE} and values of
-@code{NAME} should not be duplicated. If @var{env} is supplied
-then the return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} putenv str
-@deffnx {C Function} scm_putenv (str)
-Modifies the environment of the current process, which is
-also the default environment inherited by child processes.
-
-If @var{string} is of the form @code{NAME=VALUE} then it will be written
-directly into the environment, replacing any existing environment string
-with
-name matching @code{NAME}. If @var{string} does not contain an equal
-sign, then any existing string with name matching @var{string} will
-be removed.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setenv name value
-Give the environment variable @var{name} the value @var{value}. The
-name can not contain a @samp{=} character.
-@end deffn
-
-@deffn {Scheme Procedure} unsetenv name
-Remove variable @var{name} from the environment. The
-name can not contain a @samp{=} character.
-@end deffn
-
-@node Processes
-@section Processes
-
-@findex cd
-@deffn {Scheme Procedure} chdir str
-@deffnx {C Function} scm_chdir (str)
-Change the current working directory to @var{path}.
-The return value is unspecified.
-@end deffn
-
-@findex pwd
-@deffn {Scheme Procedure} getcwd
-@deffnx {C Function} scm_getcwd ()
-Return the name of the current working directory.
-@end deffn
-
-@deffn {Scheme Procedure} umask [mode]
-@deffnx {C Function} scm_umask (mode)
-If @var{mode} is omitted, returns a decimal number representing the current
-file creation mask. Otherwise the file creation mask is set to
-@var{mode} and the previous value is returned.
-
-E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
-@end deffn
-
-@deffn {Scheme Procedure} chroot path
-@deffnx {C Function} scm_chroot (path)
-Change the root directory to that specified in @var{path}.
-This directory will be used for path names beginning with
-@file{/}. The root directory is inherited by all children
-of the current process. Only the superuser may change the
-root directory.
-@end deffn
-
-@deffn {Scheme Procedure} getpid
-@deffnx {C Function} scm_getpid ()
-Return an integer representing the current process ID.
-@end deffn
-
-@deffn {Scheme Procedure} getgroups
-@deffnx {C Function} scm_getgroups ()
-Return a vector of integers representing the current
-supplementary group IDs.
-@end deffn
-
-@deffn {Scheme Procedure} getppid
-@deffnx {C Function} scm_getppid ()
-Return an integer representing the process ID of the parent
-process.
-@end deffn
-
-@deffn {Scheme Procedure} getuid
-@deffnx {C Function} scm_getuid ()
-Return an integer representing the current real user ID.
-@end deffn
-
-@deffn {Scheme Procedure} getgid
-@deffnx {C Function} scm_getgid ()
-Return an integer representing the current real group ID.
-@end deffn
-
-@deffn {Scheme Procedure} geteuid
-@deffnx {C Function} scm_geteuid ()
-Return an integer representing the current effective user ID.
-If the system does not support effective IDs, then the real ID
-is returned. @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-@end deffn
-
-@deffn {Scheme Procedure} getegid
-@deffnx {C Function} scm_getegid ()
-Return an integer representing the current effective group ID.
-If the system does not support effective IDs, then the real ID
-is returned. @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-@end deffn
-
-@deffn {Scheme Procedure} setuid id
-@deffnx {C Function} scm_setuid (id)
-Sets both the real and effective user IDs to the integer @var{id}, provided
-the process has appropriate privileges.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setgid id
-@deffnx {C Function} scm_setgid (id)
-Sets both the real and effective group IDs to the integer @var{id}, provided
-the process has appropriate privileges.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} seteuid id
-@deffnx {C Function} scm_seteuid (id)
-Sets the effective user ID to the integer @var{id}, provided the process
-has appropriate privileges. If effective IDs are not supported, the
-real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setegid id
-@deffnx {C Function} scm_setegid (id)
-Sets the effective group ID to the integer @var{id}, provided the process
-has appropriate privileges. If effective IDs are not supported, the
-real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
-system supports effective IDs.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} getpgrp
-@deffnx {C Function} scm_getpgrp ()
-Return an integer representing the current process group ID.
-This is the POSIX definition, not BSD.
-@end deffn
-
-@deffn {Scheme Procedure} setpgid pid pgid
-@deffnx {C Function} scm_setpgid (pid, pgid)
-Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
-@var{pgid} must be integers: they can be zero to indicate the ID of the
-current process.
-Fails on systems that do not support job control.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setsid
-@deffnx {C Function} scm_setsid ()
-Creates a new session. The current process becomes the session leader
-and is put in a new process group. The process will be detached
-from its controlling terminal if it has one.
-The return value is an integer representing the new process group ID.
-@end deffn
-
-@deffn {Scheme Procedure} waitpid pid [options]
-@deffnx {C Function} scm_waitpid (pid, options)
-This procedure collects status information from a child process which
-has terminated or (optionally) stopped. Normally it will
-suspend the calling process until this can be done. If more than one
-child process is eligible then one will be chosen by the operating system.
-
-The value of @var{pid} determines the behaviour:
-
-@table @r
-@item @var{pid} greater than 0
-Request status information from the specified child process.
-@item @var{pid} equal to -1 or WAIT_ANY
-Request status information for any child process.
-@item @var{pid} equal to 0 or WAIT_MYPGRP
-Request status information for any child process in the current process
-group.
-@item @var{pid} less than -1
-Request status information for any child process whose process group ID
-is -@var{PID}.
-@end table
-
-The @var{options} argument, if supplied, should be the bitwise OR of the
-values of zero or more of the following variables:
-
-@defvar WNOHANG
-Return immediately even if there are no child processes to be collected.
-@end defvar
-
-@defvar WUNTRACED
-Report status information for stopped processes as well as terminated
-processes.
-@end defvar
-
-The return value is a pair containing:
-
-@enumerate
-@item
-The process ID of the child process, or 0 if @code{WNOHANG} was
-specified and no process was collected.
-@item
-The integer status value.
-@end enumerate
-@end deffn
-
-The following three
-functions can be used to decode the process status code returned
-by @code{waitpid}.
-
-@deffn {Scheme Procedure} status:exit-val status
-@deffnx {C Function} scm_status_exit_val (status)
-Return the exit status value, as would be set if a process
-ended normally through a call to @code{exit} or @code{_exit},
-if any, otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} status:term-sig status
-@deffnx {C Function} scm_status_term_sig (status)
-Return the signal number which terminated the process, if any,
-otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} status:stop-sig status
-@deffnx {C Function} scm_status_stop_sig (status)
-Return the signal number which stopped the process, if any,
-otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} system [cmd]
-@deffnx {C Function} scm_system (cmd)
-Execute @var{cmd} using the operating system's "command
-processor". Under Unix this is usually the default shell
-@code{sh}. The value returned is @var{cmd}'s exit status as
-returned by @code{waitpid}, which can be interpreted using the
-functions above.
-
-If @code{system} is called without arguments, return a boolean
-indicating whether the command processor is available.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-exit [status]
-@deffnx {C Function} scm_primitive_exit (status)
-Terminate the current process without unwinding the Scheme stack.
-This is would typically be useful after a fork. The exit status
-is @var{status} if supplied, otherwise zero.
-@end deffn
-
-@deffn {Scheme Procedure} execl filename . args
-@deffnx {C Function} scm_execl (filename, args)
-Executes the file named by @var{path} as a new process image.
-The remaining arguments are supplied to the process; from a C program
-they are accessible as the @code{argv} argument to @code{main}.
-Conventionally the first @var{arg} is the same as @var{path}.
-All arguments must be strings.
-
-If @var{arg} is missing, @var{path} is executed with a null
-argument list, which may have system-dependent side-effects.
-
-This procedure is currently implemented using the @code{execv} system
-call, but we call it @code{execl} because of its Scheme calling interface.
-@end deffn
-
-@deffn {Scheme Procedure} execlp filename . args
-@deffnx {C Function} scm_execlp (filename, args)
-Similar to @code{execl}, however if
-@var{filename} does not contain a slash
-then the file to execute will be located by searching the
-directories listed in the @code{PATH} environment variable.
-
-This procedure is currently implemented using the @code{execvp} system
-call, but we call it @code{execlp} because of its Scheme calling interface.
-@end deffn
-
-@deffn {Scheme Procedure} execle filename env . args
-@deffnx {C Function} scm_execle (filename, env, args)
-Similar to @code{execl}, but the environment of the new process is
-specified by @var{env}, which must be a list of strings as returned by the
-@code{environ} procedure.
-
-This procedure is currently implemented using the @code{execve} system
-call, but we call it @code{execle} because of its Scheme calling interface.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-fork
-@deffnx {C Function} scm_fork ()
-Creates a new "child" process by duplicating the current "parent" process.
-In the child the return value is 0. In the parent the return value is
-the integer process ID of the child.
-
-This procedure has been renamed from @code{fork} to avoid a naming conflict
-with the scsh fork.
-@end deffn
-
-@deffn {Scheme Procedure} nice incr
-@deffnx {C Function} scm_nice (incr)
-Increment the priority of the current process by @var{incr}. A higher
-priority value means that the process runs less often.
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setpriority which who prio
-@deffnx {C Function} scm_setpriority (which, who, prio)
-Set the scheduling priority of the process, process group
-or user, as indicated by @var{which} and @var{who}. @var{which}
-is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
-or @code{PRIO_USER}, and @var{who} is interpreted relative to
-@var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
-identifier for @code{PRIO_USER}. A zero value of @var{who}
-denotes the current process, process group, or user.
-@var{prio} is a value in the range -20 and 20, the default
-priority is 0; lower priorities cause more favorable
-scheduling. Sets the priority of all of the specified
-processes. Only the super-user may lower priorities.
-The return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} getpriority which who
-@deffnx {C Function} scm_getpriority (which, who)
-Return the scheduling priority of the process, process group
-or user, as indicated by @var{which} and @var{who}. @var{which}
-is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
-or @code{PRIO_USER}, and @var{who} is interpreted relative to
-@var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
-identifier for @code{PRIO_USER}. A zero value of @var{who}
-denotes the current process, process group, or user. Return
-the highest priority (lowest numerical value) of any of the
-specified processes.
-@end deffn
-
-
-@node Signals
-@section Signals
-
-Procedures to raise, handle and wait for signals.
-
-@deffn {Scheme Procedure} kill pid sig
-@deffnx {C Function} scm_kill (pid, sig)
-Sends a signal to the specified process or group of processes.
-
-@var{pid} specifies the processes to which the signal is sent:
-
-@table @r
-@item @var{pid} greater than 0
-The process whose identifier is @var{pid}.
-@item @var{pid} equal to 0
-All processes in the current process group.
-@item @var{pid} less than -1
-The process group whose identifier is -@var{pid}
-@item @var{pid} equal to -1
-If the process is privileged, all processes except for some special
-system processes. Otherwise, all processes with the current effective
-user ID.
-@end table
-
-@var{sig} should be specified using a variable corresponding to
-the Unix symbolic name, e.g.,
-
-@defvar SIGHUP
-Hang-up signal.
-@end defvar
-
-@defvar SIGINT
-Interrupt signal.
-@end defvar
-@end deffn
-
-@deffn {Scheme Procedure} raise sig
-@deffnx {C Function} scm_raise (sig)
-Sends a specified signal @var{sig} to the current process, where
-@var{sig} is as described for the kill procedure.
-@end deffn
-
-@deffn {Scheme Procedure} sigaction signum [handler [flags]]
-@deffnx {C Function} scm_sigaction (signum, handler, flags)
-Install or report the signal handler for a specified signal.
-
-@var{signum} is the signal number, which can be specified using the value
-of variables such as @code{SIGINT}.
-
-If @var{action} is omitted, @code{sigaction} returns a pair: the
-CAR is the current
-signal hander, which will be either an integer with the value @code{SIG_DFL}
-(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
-handles the signal, or @code{#f} if a non-Scheme procedure handles the
-signal. The CDR contains the current @code{sigaction} flags for the handler.
-
-If @var{action} is provided, it is installed as the new handler for
-@var{signum}. @var{action} can be a Scheme procedure taking one
-argument, or the value of @code{SIG_DFL} (default action) or
-@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
-was installed before @code{sigaction} was first used. Flags can
-optionally be specified for the new handler (@code{SA_RESTART} will
-always be added if it's available and the system is using restartable
-system calls.) The return value is a pair with information about the
-old handler as described above.
-
-This interface does not provide access to the "signal blocking"
-facility. Maybe this is not needed, since the thread support may
-provide solutions to the problem of consistent access to data
-structures.
-@end deffn
-
-@deffn {Scheme Procedure} restore-signals
-@deffnx {C Function} scm_restore_signals ()
-Return all signal handlers to the values they had before any call to
-@code{sigaction} was made. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} alarm i
-@deffnx {C Function} scm_alarm (i)
-Set a timer to raise a @code{SIGALRM} signal after the specified
-number of seconds (an integer). It's advisable to install a signal
-handler for
-@code{SIGALRM} beforehand, since the default action is to terminate
-the process.
-
-The return value indicates the time remaining for the previous alarm,
-if any. The new value replaces the previous alarm. If there was
-no previous alarm, the return value is zero.
-@end deffn
-
-@deffn {Scheme Procedure} pause
-@deffnx {C Function} scm_pause ()
-Pause the current process (thread?) until a signal arrives whose
-action is to either terminate the current process or invoke a
-handler procedure. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} sleep i
-@deffnx {C Function} scm_sleep (i)
-Wait for the given number of seconds (an integer) or until a signal
-arrives. The return value is zero if the time elapses or the number
-of seconds remaining otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} usleep i
-@deffnx {C Function} scm_usleep (i)
-Sleep for I microseconds. @code{usleep} is not available on
-all platforms.
-@end deffn
-
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
-
-Return information about the timer's previous setting.
-Errors are handled as described in the guile info pages under ``POSIX
-Interface Conventions''.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
-@end deffn
-
-@deffn {Scheme Procedure} getitimer which_timer
-@deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{which_timer}
-Errors are handled as described in the guile info pages under ``POSIX
-Interface Conventions''.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
-@end deffn
-
-
-@node Terminals and Ptys
-@section Terminals and Ptys
-
-@deffn {Scheme Procedure} isatty? port
-@deffnx {C Function} scm_isatty_p (port)
-Return @code{#t} if @var{port} is using a serial non--file
-device, otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} ttyname port
-@deffnx {C Function} scm_ttyname (port)
-Return a string with the name of the serial terminal device
-underlying @var{port}.
-@end deffn
-
-@deffn {Scheme Procedure} ctermid
-@deffnx {C Function} scm_ctermid ()
-Return a string containing the file name of the controlling
-terminal for the current process.
-@end deffn
-
-@deffn {Scheme Procedure} tcgetpgrp port
-@deffnx {C Function} scm_tcgetpgrp (port)
-Return the process group ID of the foreground process group
-associated with the terminal open on the file descriptor
-underlying @var{port}.
-
-If there is no foreground process group, the return value is a
-number greater than 1 that does not match the process group ID
-of any existing process group. This can happen if all of the
-processes in the job that was formerly the foreground job have
-terminated, and no other job has yet been moved into the
-foreground.
-@end deffn
-
-@deffn {Scheme Procedure} tcsetpgrp port pgid
-@deffnx {C Function} scm_tcsetpgrp (port, pgid)
-Set the foreground process group ID for the terminal used by the file
-descriptor underlying @var{port} to the integer @var{pgid}.
-The calling process
-must be a member of the same session as @var{pgid} and must have the same
-controlling terminal. The return value is unspecified.
-@end deffn
-
-@node Pipes
-@section Pipes
-
-The following procedures provide an interface to the @code{popen} and
-@code{pclose} system routines. The code is in a separate "popen"
-module:
-
-@smalllisp
-(use-modules (ice-9 popen))
-@end smalllisp
-
-@findex popen
-@deffn {Scheme Procedure} open-pipe command modes
-Executes the shell command @var{command} (a string) in a subprocess.
-A pipe to the process is created and returned. @var{modes} specifies
-whether an input or output pipe to the process is created: it should
-be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
-@end deffn
-
-@deffn {Scheme Procedure} open-input-pipe command
-Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
-@end deffn
-
-@deffn {Scheme Procedure} open-output-pipe command
-Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
-@end deffn
-
-@findex pclose
-@deffn {Scheme Procedure} close-pipe port
-Closes the pipe created by @code{open-pipe}, then waits for the process
-to terminate and returns its status value, @xref{Processes, waitpid}, for
-information on how to interpret this value.
-
-@code{close-port} (@pxref{Closing, close-port}) can also be used to
-close a pipe, but doesn't return the status.
-@end deffn
-
-@node Networking
-@section Networking
-
-@menu
-* Network Address Conversion::
-* Network Databases::
-* Network Sockets and Communication::
-@end menu
-
-@node Network Address Conversion
-@subsection Network Address Conversion
-
-This section describes procedures which convert internet addresses
-between numeric and string formats.
-
-@subsubsection IPv4 Address Conversion
-
-@deffn {Scheme Procedure} inet-aton address
-@deffnx {C Function} scm_inet_aton (address)
-Convert an IPv4 Internet address from printable string
-(dotted decimal notation) to an integer. E.g.,
-
-@lisp
-(inet-aton "127.0.0.1") @result{} 2130706433
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-ntoa inetid
-@deffnx {C Function} scm_inet_ntoa (inetid)
-Convert an IPv4 Internet address to a printable
-(dotted decimal notation) string. E.g.,
-
-@lisp
-(inet-ntoa 2130706433) @result{} "127.0.0.1"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-netof address
-@deffnx {C Function} scm_inet_netof (address)
-Return the network number part of the given IPv4
-Internet address. E.g.,
-
-@lisp
-(inet-netof 2130706433) @result{} 127
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-lnaof address
-@deffnx {C Function} scm_lnaof (address)
-Return the local-address-with-network part of the given
-IPv4 Internet address, using the obsolete class A/B/C system.
-E.g.,
-
-@lisp
-(inet-lnaof 2130706433) @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-makeaddr net lna
-@deffnx {C Function} scm_inet_makeaddr (net, lna)
-Make an IPv4 Internet address by combining the network number
-@var{net} with the local-address-within-network number
-@var{lna}. E.g.,
-
-@lisp
-(inet-makeaddr 127 1) @result{} 2130706433
-@end lisp
-@end deffn
-
-@subsubsection IPv6 Address Conversion
-
-@deffn {Scheme Procedure} inet-ntop family address
-@deffnx {C Function} scm_inet_ntop (family, address)
-Convert a network address into a printable string.
-Note that unlike the C version of this function,
-the input is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
-
-@lisp
-(inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
-(inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} inet-pton family address
-@deffnx {C Function} scm_inet_pton (family, address)
-Convert a string containing a printable network address to
-an integer address. Note that unlike the C version of this
-function,
-the result is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
-
-@lisp
-(inet-pton AF_INET "127.0.0.1") @result{} 2130706433
-(inet-pton AF_INET6 "::1") @result{} 1
-@end lisp
-@end deffn
-
-
-@node Network Databases
-@subsection Network Databases
-
-This section describes procedures which query various network databases.
-Care should be taken when using the database routines since they are not
-reentrant.
-
-@subsubsection The Host Database
-
-A @dfn{host object} is a structure that represents what is known about a
-network host, and is the usual way of representing a system's network
-identity inside software.
-
-The following functions accept a host object and return a selected
-component:
-
-@deffn {Scheme Procedure} hostent:name host
-The "official" hostname for @var{host}.
-@end deffn
-@deffn {Scheme Procedure} hostent:aliases host
-A list of aliases for @var{host}.
-@end deffn
-@deffn {Scheme Procedure} hostent:addrtype host
-The host address type. For hosts with Internet addresses, this will
-return @code{AF_INET}.
-@end deffn
-@deffn {Scheme Procedure} hostent:length host
-The length of each address for @var{host}, in bytes.
-@end deffn
-@deffn {Scheme Procedure} hostent:addr-list host
-The list of network addresses associated with @var{host}.
-@end deffn
-
-The following procedures are used to search the host database:
-
-@deffn {Scheme Procedure} gethost [host]
-@deffnx {Scheme Procedure} gethostbyname hostname
-@deffnx {Scheme Procedure} gethostbyaddr address
-@deffnx {C Function} scm_gethost (host)
-Look up a host by name or address, returning a host object. The
-@code{gethost} procedure will accept either a string name or an integer
-address; if given no arguments, it behaves like @code{gethostent} (see
-below). If a name or address is supplied but the address can not be
-found, an error will be thrown to one of the keys:
-@code{host-not-found}, @code{try-again}, @code{no-recovery} or
-@code{no-data}, corresponding to the equivalent @code{h_error} values.
-Unusual conditions may result in errors thrown to the
-@code{system-error} or @code{misc_error} keys.
-@end deffn
-
-The following procedures may be used to step through the host
-database from beginning to end.
-
-@deffn {Scheme Procedure} sethostent [stayopen]
-Initialize an internal stream from which host objects may be read. This
-procedure must be called before any calls to @code{gethostent}, and may
-also be called afterward to reset the host entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} gethostent
-Return the next host object from the host database, or @code{#f} if
-there are no more hosts to be found (or an error has been encountered).
-This procedure may not be used before @code{sethostent} has been called.
-@end deffn
-
-@deffn {Scheme Procedure} endhostent
-Close the stream used by @code{gethostent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} sethost [stayopen]
-@deffnx {C Function} scm_sethost (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
-Otherwise it is equivalent to @code{sethostent stayopen}.
-@end deffn
-@subsubsection The Network Database
-
-The following functions accept an object representing a network
-and return a selected component:
-
-@deffn {Scheme Procedure} netent:name net
-The "official" network name.
-@end deffn
-@deffn {Scheme Procedure} netent:aliases net
-A list of aliases for the network.
-@end deffn
-@deffn {Scheme Procedure} netent:addrtype net
-The type of the network number. Currently, this returns only
-@code{AF_INET}.
-@end deffn
-@deffn {Scheme Procedure} netent:net net
-The network number.
-@end deffn
-
-The following procedures are used to search the network database:
-
-@deffn {Scheme Procedure} getnet [net]
-@deffnx {Scheme Procedure} getnetbyname net-name
-@deffnx {Scheme Procedure} getnetbyaddr net-number
-@deffnx {C Function} scm_getnet (net)
-Look up a network by name or net number in the network database. The
-@var{net-name} argument must be a string, and the @var{net-number}
-argument must be an integer. @code{getnet} will accept either type of
-argument, behaving like @code{getnetent} (see below) if no arguments are
-given.
-@end deffn
-
-The following procedures may be used to step through the network
-database from beginning to end.
-
-@deffn {Scheme Procedure} setnetent [stayopen]
-Initialize an internal stream from which network objects may be read. This
-procedure must be called before any calls to @code{getnetent}, and may
-also be called afterward to reset the net entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} getnetent
-Return the next entry from the network database.
-@end deffn
-
-@deffn {Scheme Procedure} endnetent
-Close the stream used by @code{getnetent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setnet [stayopen]
-@deffnx {C Function} scm_setnet (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
-Otherwise it is equivalent to @code{setnetent stayopen}.
-@end deffn
-
-@subsubsection The Protocol Database
-
-The following functions accept an object representing a protocol
-and return a selected component:
-
-@deffn {Scheme Procedure} protoent:name protocol
-The "official" protocol name.
-@end deffn
-@deffn {Scheme Procedure} protoent:aliases protocol
-A list of aliases for the protocol.
-@end deffn
-@deffn {Scheme Procedure} protoent:proto protocol
-The protocol number.
-@end deffn
-
-The following procedures are used to search the protocol database:
-
-@deffn {Scheme Procedure} getproto [protocol]
-@deffnx {Scheme Procedure} getprotobyname name
-@deffnx {Scheme Procedure} getprotobynumber number
-@deffnx {C Function} scm_getproto (protocol)
-Look up a network protocol by name or by number. @code{getprotobyname}
-takes a string argument, and @code{getprotobynumber} takes an integer
-argument. @code{getproto} will accept either type, behaving like
-@code{getprotoent} (see below) if no arguments are supplied.
-@end deffn
-
-The following procedures may be used to step through the protocol
-database from beginning to end.
-
-@deffn {Scheme Procedure} setprotoent [stayopen]
-Initialize an internal stream from which protocol objects may be read. This
-procedure must be called before any calls to @code{getprotoent}, and may
-also be called afterward to reset the protocol entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} getprotoent
-Return the next entry from the protocol database.
-@end deffn
-
-@deffn {Scheme Procedure} endprotoent
-Close the stream used by @code{getprotoent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setproto [stayopen]
-@deffnx {C Function} scm_setproto (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
-Otherwise it is equivalent to @code{setprotoent stayopen}.
-@end deffn
-
-@subsubsection The Service Database
-
-The following functions accept an object representing a service
-and return a selected component:
-
-@deffn {Scheme Procedure} servent:name serv
-The "official" name of the network service.
-@end deffn
-@deffn {Scheme Procedure} servent:aliases serv
-A list of aliases for the network service.
-@end deffn
-@deffn {Scheme Procedure} servent:port serv
-The Internet port used by the service.
-@end deffn
-@deffn {Scheme Procedure} servent:proto serv
-The protocol used by the service. A service may be listed many times
-in the database under different protocol names.
-@end deffn
-
-The following procedures are used to search the service database:
-
-@deffn {Scheme Procedure} getserv [name [protocol]]
-@deffnx {Scheme Procedure} getservbyname name protocol
-@deffnx {Scheme Procedure} getservbyport port protocol
-@deffnx {C Function} scm_getserv (name, protocol)
-Look up a network service by name or by service number, and return a
-network service object. The @var{protocol} argument specifies the name
-of the desired protocol; if the protocol found in the network service
-database does not match this name, a system error is signalled.
-
-The @code{getserv} procedure will take either a service name or number
-as its first argument; if given no arguments, it behaves like
-@code{getservent} (see below).
-@end deffn
-
-The following procedures may be used to step through the service
-database from beginning to end.
-
-@deffn {Scheme Procedure} setservent [stayopen]
-Initialize an internal stream from which service objects may be read. This
-procedure must be called before any calls to @code{getservent}, and may
-also be called afterward to reset the service entry stream. If
-@var{stayopen} is supplied and is not @code{#f}, the database is not
-closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
-possibly giving an efficiency gain.
-@end deffn
-
-@deffn {Scheme Procedure} getservent
-Return the next entry from the services database.
-@end deffn
-
-@deffn {Scheme Procedure} endservent
-Close the stream used by @code{getservent}. The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} setserv [stayopen]
-@deffnx {C Function} scm_setserv (stayopen)
-If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
-Otherwise it is equivalent to @code{setservent stayopen}.
-@end deffn
-
-@node Network Sockets and Communication
-@subsection Network Sockets and Communication
-
-Socket ports can be created using @code{socket} and @code{socketpair}.
-The ports are initially unbuffered, to make reading and writing to the
-same port more reliable. A buffer can be added to the port using
-@code{setvbuf}, @xref{Ports and File Descriptors}.
-
-The convention used for "host" vs "network" addresses is that addresses
-are always held in host order at the Scheme level. The procedures in
-this section automatically convert between host and network order when
-required. The arguments and return values are thus in host order.
-
-@deffn {Scheme Procedure} socket family style proto
-@deffnx {C Function} scm_socket (family, style, proto)
-Return a new socket port of the type specified by @var{family},
-@var{style} and @var{proto}. All three parameters are
-integers. Supported values for @var{family} are
-@code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
-Typical values for @var{style} are @code{SOCK_STREAM},
-@code{SOCK_DGRAM} and @code{SOCK_RAW}.
-
-@var{proto} can be obtained from a protocol name using
-@code{getprotobyname}. A value of zero specifies the default
-protocol, which is usually right.
-
-A single socket port cannot by used for communication until it
-has been connected to another socket.
-@end deffn
-
-@deffn {Scheme Procedure} socketpair family style proto
-@deffnx {C Function} scm_socketpair (family, style, proto)
-Return a pair of connected (but unnamed) socket ports of the
-type specified by @var{family}, @var{style} and @var{proto}.
-Many systems support only socket pairs of the @code{AF_UNIX}
-family. Zero is likely to be the only meaningful value for
-@var{proto}.
-@end deffn
-
-@deffn {Scheme Procedure} getsockopt sock level optname
-@deffnx {C Function} scm_getsockopt (sock, level, optname)
-Return the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of
-option being requested, e.g., @code{SOL_SOCKET} for
-socket-level options. @var{optname} is an integer code for the
-option required and should be specified using one of the
-symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-
-The returned value is typically an integer but @code{SO_LINGER}
-returns a pair of integers.
-@end deffn
-
-@deffn {Scheme Procedure} setsockopt sock level optname value
-@deffnx {C Function} scm_setsockopt (sock, level, optname, value)
-Set the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of option
-being set, e.g., @code{SOL_SOCKET} for socket-level options.
-@var{optname} is an
-integer code for the option to set and should be specified using one of
-the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-@var{value} is the value to which the option should be set. For
-most options this must be an integer, but for @code{SO_LINGER} it must
-be a pair.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} shutdown sock how
-@deffnx {C Function} scm_shutdown (sock, how)
-Sockets can be closed simply by using @code{close-port}. The
-@code{shutdown} procedure allows reception or transmission on a
-connection to be shut down individually, according to the parameter
-@var{how}:
-
-@table @asis
-@item 0
-Stop receiving data for this socket. If further data arrives, reject it.
-@item 1
-Stop trying to transmit data from this socket. Discard any
-data waiting to be sent. Stop looking for acknowledgement of
-data already sent; don't retransmit it if it is lost.
-@item 2
-Stop both reception and transmission.
-@end table
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} connect sock fam address . args
-@deffnx {C Function} scm_connect (sock, fam, address, args)
-Initiate a connection from a socket using a specified address
-family to the address
-specified by @var{address} and possibly @var{args}.
-The format required for @var{address}
-and @var{args} depends on the family of the socket.
-
-For a socket of family @code{AF_UNIX},
-only @var{address} is specified and must be a string with the
-filename where the socket is to be created.
-
-For a socket of family @code{AF_INET},
-@var{address} must be an integer IPv4 host address and
-@var{args} must be a single integer port number.
-
-For a socket of family @code{AF_INET6},
-@var{address} must be an integer IPv6 host address and
-@var{args} may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} bind sock fam address . args
-@deffnx {C Function} scm_bind (sock, fam, address, args)
-Assign an address to the socket port @var{sock}.
-Generally this only needs to be done for server sockets,
-so they know where to look for incoming connections. A socket
-without an address will be assigned one automatically when it
-starts communicating.
-
-The format of @var{address} and @var{args} depends
-on the family of the socket.
-
-For a socket of family @code{AF_UNIX}, only @var{address}
-is specified and must be a string with the filename where
-the socket is to be created.
-
-For a socket of family @code{AF_INET}, @var{address}
-must be an integer IPv4 address and @var{args}
-must be a single integer port number.
-
-The values of the following variables can also be used for
-@var{address}:
-
-@defvar INADDR_ANY
-Allow connections from any address.
-@end defvar
-
-@defvar INADDR_LOOPBACK
-The address of the local host using the loopback device.
-@end defvar
-
-@defvar INADDR_BROADCAST
-The broadcast address on the local network.
-@end defvar
-
-@defvar INADDR_NONE
-No address.
-@end defvar
-
-For a socket of family @code{AF_INET6}, @var{address}
-must be an integer IPv6 address and @var{args}
-may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} listen sock backlog
-@deffnx {C Function} scm_listen (sock, backlog)
-Enable @var{sock} to accept connection
-requests. @var{backlog} is an integer specifying
-the maximum length of the queue for pending connections.
-If the queue fills, new clients will fail to connect until
-the server calls @code{accept} to accept a connection from
-the queue.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} accept sock
-@deffnx {C Function} scm_accept (sock)
-Accept a connection on a bound, listening socket.
-If there
-are no pending connections in the queue, wait until
-one is available unless the non-blocking option has been
-set on the socket.
-
-The return value is a
-pair in which the @emph{car} is a new socket port for the
-connection and
-the @emph{cdr} is an object with address information about the
-client which initiated the connection.
-
-@var{sock} does not become part of the
-connection and will continue to accept new requests.
-@end deffn
-
-The following functions take a socket address object, as returned
-by @code{accept} and other procedures, and return a selected component.
-
-@table @code
-@item sockaddr:fam
-The socket family, typically equal to the value of @code{AF_UNIX} or
-@code{AF_INET}.
-@item sockaddr:path
-If the socket family is @code{AF_UNIX}, returns the path of the
-filename the socket is based on.
-@item sockaddr:addr
-If the socket family is @code{AF_INET}, returns the Internet host
-address.
-@item sockaddr:port
-If the socket family is @code{AF_INET}, returns the Internet port
-number.
-@end table
-
-@deffn {Scheme Procedure} getsockname sock
-@deffnx {C Function} scm_getsockname (sock)
-Return the address of @var{sock}, in the same form as the
-object returned by @code{accept}. On many systems the address
-of a socket in the @code{AF_FILE} namespace cannot be read.
-@end deffn
-
-@deffn {Scheme Procedure} getpeername sock
-@deffnx {C Function} scm_getpeername (sock)
-Return the address that @var{sock}
-is connected to, in the same form as the object returned by
-@code{accept}. On many systems the address of a socket in the
-@code{AF_FILE} namespace cannot be read.
-@end deffn
-
-@deffn {Scheme Procedure} recv! sock buf [flags]
-@deffnx {C Function} scm_recv (sock, buf, flags)
-Receive data from a socket port.
-@var{sock} must already
-be bound to the address from which data is to be received.
-@var{buf} is a string into which
-the data will be written. The size of @var{buf} limits
-the amount of
-data which can be received: in the case of packet
-protocols, if a packet larger than this limit is encountered
-then some data
-will be irrevocably lost.
-
-The optional @var{flags} argument is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-The value returned is the number of bytes read from the
-socket.
-
-Note that the data is read directly from the socket file
-descriptor:
-any unread buffered port data is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} send sock message [flags]
-@deffnx {C Function} scm_send (sock, message, flags)
-Transmit the string @var{message} on a socket port @var{sock}.
-@var{sock} must already be bound to a destination address. The
-value returned is the number of bytes transmitted --
-it's possible for
-this to be less than the length of @var{message}
-if the socket is
-set to be non-blocking. The optional @var{flags} argument
-is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-Note that the data is written directly to the socket
-file descriptor:
-any unflushed buffered port data is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
-@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
-Return data from the socket port @var{sock} and also
-information about where the data was received from.
-@var{sock} must already be bound to the address from which
-data is to be received. @code{str}, is a string into which the
-data will be written. The size of @var{str} limits the amount
-of data which can be received: in the case of packet protocols,
-if a packet larger than this limit is encountered then some
-data will be irrevocably lost.
-
-The optional @var{flags} argument is a value or bitwise OR of
-@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-
-The value returned is a pair: the @emph{car} is the number of
-bytes read from the socket and the @emph{cdr} an address object
-in the same form as returned by @code{accept}. The address
-will given as @code{#f} if not available, as is usually the
-case for stream sockets.
-
-The @var{start} and @var{end} arguments specify a substring of
-@var{str} to which the data should be written.
-
-Note that the data is read directly from the socket file
-descriptor: any unread buffered port data is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
-@deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
-Transmit the string @var{message} on the socket port
-@var{sock}. The
-destination address is specified using the @var{fam},
-@var{address} and
-@var{args_and_flags} arguments, in a similar way to the
-@code{connect} procedure. @var{args_and_flags} contains
-the usual connection arguments optionally followed by
-a flags argument, which is a value or
-bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
-
-The value returned is the number of bytes transmitted --
-it's possible for
-this to be less than the length of @var{message} if the
-socket is
-set to be non-blocking.
-Note that the data is written directly to the socket
-file descriptor:
-any unflushed buffered port data is ignored.
-@end deffn
-
-The following functions can be used to convert short and long integers
-between "host" and "network" order. Although the procedures above do
-this automatically for addresses, the conversion will still need to
-be done when sending or receiving encoded integer data from the network.
-
-@deffn {Scheme Procedure} htons value
-@deffnx {C Function} scm_htons (value)
-Convert a 16 bit quantity from host to network byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohs value
-@deffnx {C Function} scm_ntohs (value)
-Convert a 16 bit quantity from network to host byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} htonl value
-@deffnx {C Function} scm_htonl (value)
-Convert a 32 bit quantity from host to network byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohl value
-@deffnx {C Function} scm_ntohl (value)
-Convert a 32 bit quantity from network to host byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-These procedures are inconvenient to use at present, but consider:
-
-@example
-(define write-network-long
- (lambda (value port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-set! v 0 (htonl value))
- (uniform-vector-write v port))))
-
-(define read-network-long
- (lambda (port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-read! v port)
- (ntohl (uniform-vector-ref v 0)))))
-@end example
-
-@node System Identification
-@section System Identification
-
-This section lists the various procedures Guile provides for accessing
-information about the system it runs on.
-
-@deffn {Scheme Procedure} uname
-@deffnx {C Function} scm_uname ()
-Return an object with some information about the computer
-system the program is running on.
-@end deffn
-
-The following procedures accept an object as returned by @code{uname}
-and return a selected component.
-
-@table @code
-@item utsname:sysname
-The name of the operating system.
-@item utsname:nodename
-The network name of the computer.
-@item utsname:release
-The current release level of the operating system implementation.
-@item utsname:version
-The current version level within the release of the operating system.
-@item utsname:machine
-A description of the hardware.
-@end table
-
-@deffn {Scheme Procedure} gethostname
-@deffnx {C Function} scm_gethostname ()
-Return the host name of the current processor.
-@end deffn
-
-@deffn {Scheme Procedure} sethostname name
-@deffnx {C Function} scm_sethostname (name)
-Set the host name of the current processor to @var{name}. May
-only be used by the superuser. The return value is not
-specified.
-@end deffn
-
-@c FIXME::martin: Not in libguile!
-@deffn {Scheme Procedure} software-type
-Return a symbol describing the current platform's operating system.
-This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2,
-THINKC, AMIGA, ATARIST, MACH, or ACORN.
-
-Note that most varieties of Unix are considered to be simply "UNIX".
-That is because when a program depends on features that are not present
-on every operating system, it is usually better to test for the presence
-or absence of that specific feature. The return value of
-@code{software-type} should only be used for this purpose when there is
-no other easy or unambiguous way of detecting such features.
-@end deffn
-
-@node Locales
-@section Locales
-
-@deffn {Scheme Procedure} setlocale category [locale]
-@deffnx {C Function} scm_setlocale (category, locale)
-If @var{locale} is omitted, return the current value of the
-specified locale category as a system-dependent string.
-@var{category} should be specified using the values
-@code{LC_COLLATE}, @code{LC_ALL} etc.
-
-Otherwise the specified locale category is set to the string
-@var{locale} and the new value is returned as a
-system-dependent string. If @var{locale} is an empty string,
-the locale will be set using environment variables.
-@end deffn
-
-@node Encryption
-@section Encryption
-
-Please note that the procedures in this section are not suited for
-strong encryption, they are only interfaces to the well-known and
-common system library functions of the same name. They are just as good
-(or bad) as the underlying functions, so you should refer to your system
-documentation before using them.
-
-@deffn {Scheme Procedure} crypt key salt
-@deffnx {C Function} scm_crypt (key, salt)
-Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call.
-@end deffn
-
-Although @code{getpass} is not an encryption procedure per se, it
-appears here because it is often used in combination with @code{crypt}:
-
-@deffn {Scheme Procedure} getpass prompt
-@deffnx {C Function} scm_getpass (prompt)
-Display @var{prompt} to the standard error output and read
-a password from @file{/dev/tty}. If this file is not
-accessible, it reads from standard input. The password may be
-up to 127 characters in length. Additional characters and the
-terminating newline character are discarded. While reading
-the password, echoing and the generation of signals by special
-characters is disabled.
-@end deffn
diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi
deleted file mode 100644
index bcabb411a..000000000
--- a/doc/ref/preface.texi
+++ /dev/null
@@ -1,200 +0,0 @@
-@iftex
-@page
-@unnumbered Preface
-
-This reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions. It describes how to use Guile in many useful
-and interesting ways.
-
-This is edition @value{MANUAL_EDITION} of the reference manual, and
-corresponds to Guile version @value{VERSION}.
-@end iftex
-
-
-@iftex
-@section The Guile License
-@end iftex
-
-@ifnottex
-@node Guile License
-@chapter The Guile License
-@end ifnottex
-
-The license of Guile consists of the GNU GPL plus a special statement
-giving blanket permission to link with non-free software. This is the
-license statement as found in any individual file that it applies to:
-
-@quotation
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation; either version 2, or (at your option) any
-later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License along
-with this software; see the file COPYING. If not, write to the Free
-Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307 USA
-
-As a special exception, the Free Software Foundation gives permission
-for additional uses of the text contained in its release of GUILE.
-
-The exception is that, if you link the GUILE library with other files to
-produce an executable, this does not by itself cause the resulting
-executable to be covered by the GNU General Public License. Your use of
-that executable is in no way restricted on account of linking the GUILE
-library code into it.
-
-This exception does not however invalidate any other reasons why the
-executable file might be covered by the GNU General Public License.
-
-This exception applies only to the code released by the Free Software
-Foundation under the name GUILE. If you copy code from other Free
-Software Foundation releases into a copy of GUILE, as the General Public
-License permits, the exception does not apply to the code that you add
-in this way. To avoid misleading anyone as to the status of such
-modified files, you must delete this exception notice from them.
-
-If you write modifications of your own for GUILE, it is your choice
-whether to permit this exception to apply to your modifications. If you
-do not wish that, delete this exception notice.
-@end quotation
-
-
-@iftex
-@section Layout of this Manual
-@end iftex
-
-@ifnottex
-@node Manual Layout
-@chapter Layout of this Manual
-@end ifnottex
-
-The manual is divided into five parts.
-
-@strong{Part I: Introduction to Guile} provides an overview of what
-Guile is and how you can use it. A whirlwind tour shows how Guile can
-be used interactively and as a script interpreter, how to link Guile
-into your own applications, and how to write modules of interpreted and
-compiled code for use with Guile. Everything introduced here is
-documented again and in full by the later parts of the manual. This
-part also explains how to obtain and install new versions of Guile, and
-how to report bugs effectively.
-
-@strong{Part II: Writing and Running Guile Scheme} and @strong{Part III:
-Programming with Guile} document all aspects of practical programming
-using Guile. This covers both the Scheme level --- where we provide an
-introduction to the key ideas of the Scheme language --- and use of
-Guile's @code{scm} interface to write new primitives and objects in C,
-and to incorporate Guile into a C application. It also covers the use
-of Guile as a POSIX compliant script interpreter, and how to use the
-Guile debugger.
-
-@c @strong{Part V: Extending Applications Using Guile} explains the options
-@c available for using Guile as a application extension language. At the
-@c simpler end of the scale, an application might use Guile to define some
-@c application-specific primitives in C and then load an application Scheme
-@c file. In this case most of the application code is written on the
-@c Scheme level, and uses the application-specific primitives as an
-@c extension to standard Scheme. At the other end of the scale, an
-@c application might be predominantly written in C --- with its main
-@c control loop implemented in C --- but make occasional forays into Scheme
-@c to, say, read configuration data or run user-defined customization code.
-@c This part of the manual covers the complete range of application
-@c extension options.
-
-@strong{Part IV: Guile API Reference} documents Guile's core API. Most
-of the variables and procedures in Guile's core programming interface
-are available in both Scheme and C, and are related systematically such
-that the C interface can be inferred from the Scheme interface and vice
-versa. Therefore this part of the manual documents the Guile API in
-functionality-based groups with the Scheme and C interfaces presented
-side by side. Where the Scheme and C interfaces for a particular
-functional area do differ --- which is sometimes inevitable, given the
-differences in the structure of the two languages --- this is pointed
-out and explained. In all cases the overriding principle is that all
-the reference documentation for a given functional area is grouped
-together.
-
-@c the core Scheme language and features that Guile implements. Although
-@c the basis for this is the Scheme language described in R5RS, this part
-@c of the manual does not assume any prior familiarity with R5RS in
-@c particular, or with Scheme in general. Basic Scheme concepts, standard
-@c aspects of the Scheme language and Guile extensions on top of R5RS are
-@c all documented from scratch, and organized by functionality rather than
-@c by the defining standards.
-
-@strong{Part V: Guile Modules} describes some important modules,
-distributed as part of the Guile distribution, that extend the
-functionality provided by the Guile Scheme core. Two important examples
-are:
-
-@itemize @bullet
-@item
-the POSIX module, which provides Scheme level procedures for system and
-network programming that conform to the POSIX standard
-
-@item
-the SLIB module, which makes Aubrey Jaffer's portable Scheme library
-available for use in Guile.
-@end itemize
-
-
-@iftex
-@section Manual Conventions
-@end iftex
-
-@ifnottex
-@node Manual Conventions
-@chapter Conventions used in this Manual
-@end ifnottex
-
-We use some conventions in this manual.
-
-@itemize @bullet
-
-@item
-For some procedures, notably type predicates, we use @dfn{iff} to
-mean `if and only if'. The construct is usually something like:
-`Return @var{val} iff @var{condition}', where @var{val} is usually
-`@code{#t}' or `non-@code{#f}'. This typically means that @var{val}
-is returned if @var{condition} holds, and that @samp{#f} is returned
-otherwise.
-@cindex iff
-
-@item
-In examples and procedure descriptions and all other places where the
-evaluation of Scheme expression is shown, we use some notation for
-denoting the output and evaluation results of expressions.
-
-The symbol @code{@result{}} is used to tell which value is returned by
-an evaluation:
-
-@lisp
-(+ 1 2)
-@result{}
-3
-@end lisp
-
-Some procedures produce some output besides returning a value. This
-is denoted by the symbol @code{@print{}}.
-
-@lisp
-(begin (display 1) (newline) 'hooray)
-@print{} 1
-@result{}
-hooray
-@end lisp
-
-@c Add other conventions here.
-
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/program.texi b/doc/ref/program.texi
deleted file mode 100644
index eba3fdf83..000000000
--- a/doc/ref/program.texi
+++ /dev/null
@@ -1,776 +0,0 @@
-@page
-@node Programming Overview
-@chapter An Overview of Guile Programming
-
-Guile is designed as an extension language interpreter that is
-straightforward to integrate with applications written in C (and C++).
-The big win here for the application developer is that Guile
-integration, as the Guile web page says, ``lowers your project's
-hacktivation energy.'' Lowering the hacktivation energy means that you,
-as the application developer, @emph{and your users}, reap the benefits
-that flow from being able to extend the application in a high level
-extension language rather than in plain old C.
-
-In abstract terms, it's difficult to explain what this really means and
-what the integration process involves, so instead let's begin by jumping
-straight into an example of how you might integrate Guile into an
-existing program, and what you could expect to gain by so doing. With
-that example under our belts, we'll then return to a more general
-analysis of the arguments involved and the range of programming options
-available.
-
-@menu
-* Extending Dia:: How one might extend Dia using Guile.
-* Scheme vs C:: Why Scheme is more hackable than C.
-* Testbed Example:: Example: using Guile in a testbed.
-* Programming Options:: Options for Guile programming.
-* User Programming:: How about application users?
-@end menu
-
-
-@node Extending Dia
-@section How One Might Extend Dia Using Guile
-
-Dia is a free software program for drawing schematic diagrams like flow
-charts and floor plans (REFFIXME). This section conducts the thought
-experiment of adding Guile to Dia. In so doing, it aims to illustrate
-several of the steps and considerations involved in adding Guile to
-applications in general.
-
-@menu
-* Dia Objective:: Deciding why you want to add Guile.
-* Dia Steps:: Four steps required to add Guile.
-* Dia Smobs:: How to represent Dia data in Scheme.
-* Dia Primitives:: Writing Guile primitives for Dia.
-* Dia Hook:: Providing a hook for Scheme evaluation.
-* Dia Structure:: Overall structure for adding Guile.
-* Dia Advanced:: Going further with Dia and Guile.
-@end menu
-
-
-@node Dia Objective
-@subsection Deciding Why You Want to Add Guile
-
-First off, you should understand why you want to add Guile to Dia at
-all, and that means forming a picture of what Dia does and how it does
-it. So, what are the constituents of the Dia application?
-
-@itemize @bullet
-@item
-Most importantly, the @dfn{application domain objects} --- in other
-words, the concepts that differentiate Dia from another application such
-as a word processor or spreadsheet: shapes, templates, connectors,
-pages, plus the properties of all these things.
-
-@item
-The code that manages the graphical face of the application, including
-the layout and display of the objects above.
-
-@item
-The code that handles input events, which indicate that the application
-user is wanting to do something.
-@end itemize
-
-@noindent
-(In other words, a textbook example of the @dfn{model - view -
-controller} paradigm.)
-
-Next question: how will Dia benefit once the Guile integration is
-complete? Several (positive!) answers are possible here, and the choice
-is obviously up to the application developers. Still, one answer is
-that the main benefit will be the ability to manipulate Dia's
-application domain objects from Scheme.
-
-Suppose that Dia made a set of procedures available in Scheme,
-representing the most basic operations on objects such as shapes,
-connectors, and so on. Using Scheme, the application user could then
-write code that builds upon these basic operations to create more
-complex procedures. For example, given basic procedures to enumerate
-the objects on a page, to determine whether an object is a square, and
-to change the fill pattern of a single shape, the user can write a
-Scheme procedure to change the fill pattern of all squares on the
-current page:
-
-@lisp
-(define (change-squares'-fill-pattern new-pattern)
- (for-each-shape current-page
- (lambda (shape)
- (if (square? shape)
- (change-fill-pattern shape new-pattern)))))
-@end lisp
-
-
-@node Dia Steps
-@subsection Four Steps Required to Add Guile
-
-Assuming this objective, four steps are needed to achieve it.
-
-First, you need a way of representing your application-specific objects
---- such as @code{shape} in the previous example --- when they are
-passed into the Scheme world. Unless your objects are so simple that
-they map naturally into builtin Scheme data types like numbers and
-strings, you will probably want to use Guile's @dfn{SMOB} interface to
-create a new Scheme data type for your objects.
-
-Second, you need to write code for the basic operations like
-@code{for-each-shape} and @code{square?} such that they access and
-manipulate your existing data structures correctly, and then make these
-operations available as @dfn{primitives} on the Scheme level.
-
-Third, you need to provide some mechanism within the Dia application
-that a user can hook into to cause arbitrary Scheme code to be
-evaluated.
-
-Finally, you need to restructure your top-level application C code a
-little so that it initializes the Guile interpreter correctly and
-declares your @dfn{SMOBs} and @dfn{primitives} to the Scheme world.
-
-The following subsections expand on these four points in turn.
-
-
-@node Dia Smobs
-@subsection How to Represent Dia Data in Scheme
-
-For all but the most trivial applications, you will probably want to
-allow some representation of your domain objects to exist on the Scheme
-level. This is where the idea of SMOBs comes in, and with it issues of
-lifetime management and garbage collection.
-
-To get more concrete about this, let's look again at the example we gave
-earlier of how application users can use Guile to build higher-level
-functions from the primitives that Dia itself provides.
-
-@lisp
-(define (change-squares'-fill-pattern new-pattern)
- (for-each-shape current-page
- (lambda (shape)
- (if (square? shape)
- (change-fill-pattern shape new-pattern)))))
-@end lisp
-
-Consider what is stored here in the variable @code{shape}. For each
-shape on the current page, the @code{for-each-shape} primitive calls
-@code{(lambda (shape) @dots{})} with an argument representing that
-shape. Question is: how is that argument represented on the Scheme
-level? The issues are as follows.
-
-@itemize @bullet
-@item
-Whatever the representation, it has to be decodable again by the C code
-for the @code{square?} and @code{change-fill-pattern} primitives. In
-other words, a primitive like @code{square?} has somehow to be able to
-turn the value that it receives back into something that points to the
-underlying C structure describing a shape.
-
-@item
-The representation must also cope with Scheme code holding on to the
-value for later use. What happens if the Scheme code stores
-@code{shape} in a global variable, but then that shape is deleted (in a
-way that the Scheme code is not aware of), and later on some other
-Scheme code uses that global variable again in a call to, say,
-@code{square?}?
-
-@item
-The lifetime and memory allocation of objects that exist @emph{only} in
-the Scheme world is managed automatically by Guile's garbage collector
-using one simple rule: when there are no remaining references to an
-object, the object is considered dead and so its memory is freed. But
-for objects that exist in both C and Scheme, the picture is more
-complicated; in the case of Dia, where the @code{shape} argument passes
-transiently in and out of the Scheme world, it would be quite wrong the
-@strong{delete} the underlying C shape just because the Scheme code has
-finished evaluation. How do we avoid this happening?
-@end itemize
-
-One resolution of these issues is for the Scheme-level representation of
-a shape to be a new, Scheme-specific C structure wrapped up as a SMOB.
-The SMOB is what is passed into and out of Scheme code, and the
-Scheme-specific C structure inside the SMOB points to Dia's underlying C
-structure so that the code for primitives like @code{square?} can get at
-it.
-
-To cope with an underlying shape being deleted while Scheme code is
-still holding onto a Scheme shape value, the underlying C structure
-should have a new field that points to the Scheme-specific SMOB. When a
-shape is deleted, the relevant code chains through to the
-Scheme-specific structure and sets its pointer back to the underlying
-structure to NULL. Thus the SMOB value for the shape continues to
-exist, but any primitive code that tries to use it will detect that the
-underlying shape has been deleted because the underlying structure
-pointer is NULL.
-
-So, to summarize the steps involved in this resolution of the problem
-(and assuming that the underlying C structure for a shape is
-@code{struct dia_shape}):
-
-@itemize @bullet
-@item
-Define a new Scheme-specific structure that @emph{points} to the
-underlying C structure:
-
-@lisp
-struct dia_guile_shape
-@{
- struct dia_shape * c_shape; /* NULL => deleted */
-@}
-@end lisp
-
-@item
-Add a field to @code{struct dia_shape} that points to its @code{struct
-dia_guile_shape} if it has one ---
-
-@lisp
-struct dia_shape
-@{
- @dots{}
- struct dia_guile_shape * guile_shape;
-@}
-@end lisp
-
-@noindent
---- so that C code can set @code{guile_shape->c_shape} to NULL when the
-underlying shape is deleted.
-
-@item
-Wrap @code{struct dia_guile_shape} as a SMOB type.
-
-@item
-Whenever you need to represent a C shape onto the Scheme level, create a
-SMOB instance for it, and pass that.
-
-@item
-In primitive code that receives a shape SMOB instance, check the
-@code{c_shape} field when decoding it, to find out whether the
-underlying C shape is still there.
-@end itemize
-
-As far as memory management is concerned, the SMOB values and their
-Scheme-specific structures are under the control of the garbage
-collector, whereas the underlying C structures are explicitly managed in
-exactly the same way that Dia managed them before we thought of adding
-Guile.
-
-When the garbage collector decides to free a shape SMOB value, it calls
-the @dfn{SMOB free} function that was specified when defining the shape
-SMOB type. To maintain the correctness of the @code{guile_shape} field
-in the underlying C structure, this function should chain through to the
-underlying C structure (if it still exists) and set its
-@code{guile_shape} field to NULL.
-
-For full documentation on defining and using SMOB types, see
-@ref{Defining New Types (Smobs)}.
-
-
-@node Dia Primitives
-@subsection Writing Guile Primitives for Dia
-
-Once the details of object representation are decided, writing the
-primitive function code that you need is usually straightforward.
-
-A primitive is simply a C function whose arguments and return value are
-all of type @code{SCM}, and whose body does whatever you want it to do.
-As an example, here is a possible implementation of the @code{square?}
-primitive:
-
-@lisp
-#define FUNC_NAME "square?"
-static SCM square_p (SCM shape)
-@{
- struct dia_guile_shape * guile_shape;
-
- /* Check that arg is really a shape SMOB. */
- SCM_VALIDATE_SHAPE (SCM_ARG1, shape);
-
- /* Access Scheme-specific shape structure. */
- guile_shape = SCM_SMOB_DATA (shape);
-
- /* Find out if underlying shape exists and is a
- square; return answer as a Scheme boolean. */
- return SCM_BOOL (guile_shape->c_shape &&
- (guile_shape->c_shape->type == DIA_SQUARE));
-@}
-#undef FUNC_NAME
-@end lisp
-
-Notice how easy it is to chain through from the @code{SCM shape}
-parameter that @code{square_p} receives --- which is a SMOB --- to the
-Scheme-specific structure inside the SMOB, and thence to the underlying
-C structure for the shape.
-
-In this code, @code{SCM_SMOB_DATA} and @code{SCM_BOOL} are macros from
-the standard Guile API. @code{SCM_VALIDATE_SHAPE} is a macro that you
-should define as part of your SMOB definition: it checks that the passed
-parameter is of the expected type. This is needed to guard against
-Scheme code using the @code{square?} procedure incorrectly, as in
-@code{(square? "hello")}; Scheme's latent typing means that usage errors
-like this must be caught at run time.
-
-Having written the C code for your primitives, you need to make them
-available as Scheme procedures by calling the @code{scm_c_define_gsubr}
-function. @code{scm_c_define_gsubr} (REFFIXME) takes arguments that
-specify the Scheme-level name for the primitive and how many required,
-optional and rest arguments it can accept. The @code{square?} primitive
-always requires exactly one argument, so the call to make it available
-in Scheme reads like this:
-
-@lisp
-scm_c_define_gsubr ("square?", 1, 0, 0, square_p);
-@end lisp
-
-For where to put this call, see the subsection after next on the
-structure of Guile-enabled code (@pxref{Dia Structure}).
-
-
-@node Dia Hook
-@subsection Providing a Hook for the Evaluation of Scheme Code
-
-To make the Guile integration useful, you have to design some kind of
-hook into your application that application users can use to cause their
-Scheme code to be evaluated.
-
-Technically, this is straightforward; you just have to decide on a
-mechanism that is appropriate for your application. Think of Emacs, for
-example: when you type @kbd{@key{ESC} :}, you get a prompt where you can
-type in any Elisp code, which Emacs will then evaluate. Or, again like
-Emacs, you could provide a mechanism (such as an init file) to allow
-Scheme code to be associated with a particular key sequence, and
-evaluate the code when that key sequence is entered.
-
-In either case, once you have the Scheme code that you want to evaluate,
-as a null terminated string, you can tell Guile to evaluate it by
-calling the @code{scm_c_eval_string} function.
-
-
-@node Dia Structure
-@subsection Top-level Structure of Guile-enabled Dia
-
-Let's assume that the pre-Guile Dia code looks structurally like this:
-
-@itemize @bullet
-@item
-@code{main ()}
-
-@itemize @bullet
-@item
-do lots of initialization and setup stuff
-@item
-enter Gtk main loop
-@end itemize
-@end itemize
-
-When you add Guile to a program, one (rather technical) requirement is
-that Guile's garbage collector needs to know where the bottom of the C
-stack is. The easiest way to ensure this is to use
-@code{scm_boot_guile} like this:
-
-@itemize @bullet
-@item
-@code{main ()}
-
-@itemize @bullet
-@item
-do lots of initialization and setup stuff
-@item
-@code{scm_boot_guile (argc, argv, inner_main, NULL)}
-@end itemize
-
-@item
-@code{inner_main ()}
-
-@itemize @bullet
-@item
-define all SMOB types
-@item
-export primitives to Scheme using @code{scm_c_define_gsubr}
-@item
-enter Gtk main loop
-@end itemize
-@end itemize
-
-In other words, you move the guts of what was previously in your
-@code{main} function into a new function called @code{inner_main}, and
-then add a @code{scm_boot_guile} call, with @code{inner_main} as a
-parameter, to the end of @code{main}.
-
-Assuming that you are using SMOBs and have written primitive code as
-described in the preceding subsections, you also need to insert calls to
-declare your new SMOBs and export the primitives to Scheme. These
-declarations must happen @emph{inside} the dynamic scope of the
-@code{scm_boot_guile} call, but also @emph{before} any code is run that
-could possibly use them --- the beginning of @code{inner_main} is an
-ideal place for this.
-
-
-@node Dia Advanced
-@subsection Going Further with Dia and Guile
-
-The steps described so far implement an initial Guile integration that
-already gives a lot of additional power to Dia application users. But
-there are further steps that you could take, and it's interesting to
-consider a few of these.
-
-In general, you could progressively move more of Dia's source code from
-C into Scheme. This might make the code more maintainable and
-extensible, and it could open the door to new programming paradigms that
-are tricky to effect in C but straightforward in Scheme.
-
-A specific example of this is that you could use the guile-gtk package,
-which provides Scheme-level procedures for most of the Gtk+ library, to
-move the code that lays out and displays Dia objects from C to Scheme.
-
-As you follow this path, it naturally becomes less useful to maintain a
-distinction between Dia's original non-Guile-related source code, and
-its later code implementing SMOBs and primitives for the Scheme world.
-
-For example, suppose that the original source code had a
-@code{dia_change_fill_pattern} function:
-
-@lisp
-void dia_change_fill_pattern (struct dia_shape * shape,
- struct dia_pattern * pattern)
-@{
- /* real pattern change work */
-@}
-@end lisp
-
-During initial Guile integration, you add a @code{change_fill_pattern}
-primitive for Scheme purposes, which accesses the underlying structures
-from its SMOB values and uses @code{dia_change_fill_pattern} to do the
-real work:
-
-@lisp
-SCM change_fill_pattern (SCM shape, SCM pattern)
-@{
- struct dia_shape * d_shape;
- struct dia_pattern * d_pattern;
-
- @dots{}
-
- dia_change_fill_pattern (d_shape, d_pattern);
-
- return SCM_UNSPECIFIED;
-@}
-@end lisp
-
-At this point, it makes sense to keep @code{dia_change_fill_pattern} and
-@code{change_fill_pattern} separate, because
-@code{dia_change_fill_pattern} can also be called without going through
-Scheme at all, say because the user clicks a button which causes a
-C-registered Gtk+ callback to be called.
-
-But, if the code for creating buttons and registering their callbacks is
-moved into Scheme (using guile-gtk), it may become true that
-@code{dia_change_fill_pattern} can no longer be called other than
-through Scheme. In which case, it makes sense to abolish it and move
-its contents directly into @code{change_fill_pattern}, like this:
-
-@lisp
-SCM change_fill_pattern (SCM shape, SCM pattern)
-@{
- struct dia_shape * d_shape;
- struct dia_pattern * d_pattern;
-
- @dots{}
-
- /* real pattern change work */
-
- return SCM_UNSPECIFIED;
-@}
-@end lisp
-
-So further Guile integration progressively @emph{reduces} the amount of
-functional C code that you have to maintain over the long term.
-
-A similar argument applies to data representation. In the discussion of
-SMOBs earlier, issues arose because of the different memory management
-and lifetime models that normally apply to data structures in C and in
-Scheme. However, with further Guile integration, you can resolve this
-issue in a more radical way by allowing all your data structures to be
-under the control of the garbage collector, and kept alive by references
-from the Scheme world. Instead of maintaining an array or linked list
-of shapes in C, you would instead maintain a list in Scheme.
-
-Rather like the coalescing of @code{dia_change_fill_pattern} and
-@code{change_fill_pattern}, the practical upshot of such a change is
-that you would no longer have to keep the @code{dia_shape} and
-@code{dia_guile_shape} structures separate, and so wouldn't need to
-worry about the pointers between them. Instead, you could change the
-SMOB definition to wrap the @code{dia_shape} structure directly, and
-send @code{dia_guile_shape} off to the scrap yard. Cut out the middle
-man!
-
-Finally, we come to the holy grail of Guile's free software / extension
-language approach. Once you have a Scheme representation for
-interesting Dia data types like shapes, and a handy bunch of primitives
-for manipulating them, it suddenly becomes clear that you have a bundle
-of functionality that could have far-ranging use beyond Dia itself. In
-other words, the data types and primitives could now become a library,
-and Dia becomes just one of the many possible applications using that
-library --- albeit, at this early stage, a rather important one!
-
-In this model, Guile becomes just the glue that binds everything
-together. Imagine an application that usefully combined functionality
-from Dia, Gnumeric and GnuCash --- it's tricky right now, because no
-such application yet exists; but it'll happen some day @dots{}
-
-
-@node Scheme vs C
-@section Why Scheme is More Hackable Than C
-
-Underlying Guile's value proposition is the assumption that programming
-in a high level language, specifically Guile's implementation of Scheme,
-is necessarily better in some way than programming in C. What do we
-mean by this claim, and how can we be so sure?
-
-One class of advantages applies not only to Scheme, but more generally
-to any interpretable, high level, scripting language, such as Emacs
-Lisp, Python, Ruby, or @TeX{}'s macro language. Common features of all
-such languages, when compared to C, are that:
-
-@itemize @bullet
-@item
-They lend themselves to rapid and experimental development cycles,
-owing usually to a combination of their interpretability and the
-integrated development environment in which they are used.
-
-@item
-They free developers from some of the low level bookkeeping tasks
-associated with C programming, notably memory management.
-
-@item
-They provide high level features such as container objects and exception
-handling that make common programming tasks easier.
-@end itemize
-
-In the case of Scheme, particular features that make programming easier
---- and more fun! --- are its powerful mechanisms for abstracting parts
-of programs (closures --- @pxref{About Closure}) and for iteration
-(@pxref{while do}).
-
-The evidence in support of this argument is empirical: the huge amount
-of code that has been written in extension languages for applications
-that support this mechanism. Most notable are extensions written in
-Emacs Lisp for GNU Emacs, in @TeX{}'s macro language for @TeX{}, and in
-Script-Fu for the Gimp, but there is increasingly now a significant code
-eco-system for Guile-based applications as well, such as Lilypond and
-GnuCash. It is close to inconceivable that similar amounts of
-functionality could have been added to these applications just by
-writing new code in their base implementation languages.
-
-
-@node Testbed Example
-@section Example: Using Guile for an Application Testbed
-
-As an example of what this means in practice, imagine writing a testbed
-for an application that is tested by submitting various requests (via a
-C interface) and validating the output received. Suppose further that
-the application keeps an idea of its current state, and that the
-``correct'' output for a given request may depend on the current
-application state. A complete ``white box''@footnote{A @dfn{white box}
-test plan is one that incorporates knowledge of the internal design of
-the application under test.} test plan for this application would aim to
-submit all possible requests in each distinguishable state, and validate
-the output for all request/state combinations.
-
-To write all this test code in C would be very tedious. Suppose instead
-that the testbed code adds a single new C function, to submit an
-arbitrary request and return the response, and then uses Guile to export
-this function as a Scheme procedure. The rest of the testbed can then
-be written in Scheme, and so benefits from all the advantages of
-programming in Scheme that were described in the previous section.
-
-(In this particular example, there is an additional benefit of writing
-most of the testbed in Scheme. A common problem for white box testing
-is that mistakes and mistaken assumptions in the application under test
-can easily be reproduced in the testbed code. It is more difficult to
-copy mistakes like this when the testbed is written in a different
-language from the application.)
-
-
-@node Programming Options
-@section A Choice of Programming Options
-
-The preceding arguments and example point to a model of Guile
-programming that is applicable in many cases. According to this model,
-Guile programming involves a balance between C and Scheme programming,
-with the aim being to extract the greatest possible Scheme level benefit
-from the least amount of C level work.
-
-The C level work required in this model usually consists of packaging
-and exporting functions and application objects such that they can be
-seen and manipulated on the Scheme level. To help with this, Guile's C
-language interface includes utility features that aim to make this kind
-of integration very easy for the application developer. These features
-are documented later in this part of the manual: see REFFIXME.
-
-This model, though, is really just one of a range of possible
-programming options. If all of the functionality that you need is
-available from Scheme, you could choose instead to write your whole
-application in Scheme (or one of the other high level languages that
-Guile supports through translation), and simply use Guile as an
-interpreter for Scheme. (In the future, we hope that Guile will also be
-able to compile Scheme code, so lessening the performance gap between C
-and Scheme code.) Or, at the other end of the C--Scheme scale, you
-could write the majority of your application in C, and only call out to
-Guile occasionally for specific actions such as reading a configuration
-file or executing a user-specified extension. The choices boil down to
-two basic questions:
-
-@itemize @bullet
-@item
-Which parts of the application do you write in C, and which in Scheme
-(or another high level translated language)?
-
-@item
-How do you design the interface between the C and Scheme parts of your
-application?
-@end itemize
-
-These are of course design questions, and the right design for any given
-application will always depend upon the particular requirements that you
-are trying to meet. In the context of Guile, however, there are some
-generally applicable considerations that can help you when designing
-your answers.
-
-@menu
-* Available Functionality:: What functionality is already available?
-* Basic Constraints:: Functional and performance constraints.
-* Style Choices:: Your preferred programming style.
-* Program Control:: What controls program execution?
-@end menu
-
-
-@node Available Functionality
-@subsection What Functionality is Already Available?
-
-Suppose, for the sake of argument, that you would prefer to write your
-whole application in Scheme. Then the API available to you consists of:
-
-@itemize @bullet
-@item
-standard Scheme
-
-@item
-plus the extensions to standard Scheme provided by
-Guile in its core distribution
-
-@item
-plus any additional functionality that you or others have packaged so
-that it can be loaded as a Guile Scheme module.
-@end itemize
-
-A module in the last category can either be a pure Scheme module --- in
-other words a collection of utility procedures coded in Scheme --- or a
-module that provides a Scheme interface to an extension library coded in
-C --- in other words a nice package where someone else has done the work
-of wrapping up some useful C code for you. The set of available modules
-is growing quickly and already includes such useful examples as
-@code{(gtk gtk)}, which makes Gtk+ drawing functions available in
-Scheme, and @code{(database postgres)}, which provides SQL access to a
-Postgres database.
-
-Given the growing collection of pre-existing modules, it is quite
-feasible that your application could be implemented by combining a
-selection of these modules together with new application code written in
-Scheme.
-
-If this approach is not enough, because the functionality that your
-application needs is not already available in this form, and it is
-impossible to write the new functionality in Scheme, you will need to
-write some C code. If the required function is already available in C
-(e.g. in a library), all you need is a little glue to connect it to the
-world of Guile. If not, you need both to write the basic code and to
-plumb it into Guile.
-
-In either case, two general considerations are important. Firstly, what
-is the interface by which the functionality is presented to the Scheme
-world? Does the interface consist only of function calls (for example,
-a simple drawing interface), or does it need to include @dfn{objects} of
-some kind that can be passed between C and Scheme and manipulated by
-both worlds. Secondly, how does the lifetime and memory management of
-objects in the C code relate to the garbage collection governed approach
-of Scheme objects? In the case where the basic C code is not already
-written, most of the difficulties of memory management can be avoided by
-using Guile's C interface features from the start.
-
-For the full documentation on writing C code for Guile and connecting
-existing C code to the Guile world, see REFFIXME.
-
-
-@node Basic Constraints
-@subsection Functional and Performance Constraints
-
-
-@node Style Choices
-@subsection Your Preferred Programming Style
-
-
-@node Program Control
-@subsection What Controls Program Execution?
-
-
-@node User Programming
-@section How About Application Users?
-
-So far we have considered what Guile programming means for an
-application developer. But what if you are instead @emph{using} an
-existing Guile-based application, and want to know what your
-options are for programming and extending this application?
-
-The answer to this question varies from one application to another,
-because the options available depend inevitably on whether the
-application developer has provided any hooks for you to hang your own
-code on and, if there are such hooks, what they allow you to
-do.@footnote{Of course, in the world of free software, you always have
-the freedom to modify the application's source code to your own
-requirements. Here we are concerned with the extension options that the
-application has provided for without your needing to modify its source
-code.} For example@dots{}
-
-@itemize @bullet
-@item
-If the application permits you to load and execute any Guile code, the
-world is your oyster. You can extend the application in any way that
-you choose.
-
-@item
-A more cautious application might allow you to load and execute Guile
-code, but only in a @dfn{safe} environment, where the interface
-available is restricted by the application from the standard Guile API.
-
-@item
-Or a really fearful application might not provide a hook to really
-execute user code at all, but just use Scheme syntax as a convenient way
-for users to specify application data or configuration options.
-@end itemize
-
-In the last two cases, what you can do is, by definition, restricted by
-the application, and you should refer to the application's own manual to
-find out your options.
-
-The most well known example of the first case is Emacs, with its
-extension language Emacs Lisp: as well as being a text editor, Emacs
-supports the loading and execution of arbitrary Emacs Lisp code. The
-result of such openness has been dramatic: Emacs now benefits from
-user-contributed Emacs Lisp libraries that extend the basic editing
-function to do everything from reading news to psychoanalysis and
-playing adventure games. The only limitation is that extensions are
-restricted to the functionality provided by Emacs's built-in set of
-primitive operations. For example, you can interact and display data by
-manipulating the contents of an Emacs buffer, but you can't pop-up and
-draw a window with a layout that is totally different to the Emacs
-standard.
-
-This situation with a Guile application that supports the loading of
-arbitrary user code is similar, except perhaps even more so, because
-Guile also supports the loading of extension libraries written in C.
-This last point enables user code to add new primitive operations to
-Guile, and so to bypass the limitation present in Emacs Lisp.
-
-At this point, the distinction between an application developer and an
-application user becomes rather blurred. Instead of seeing yourself as
-a user extending an application, you could equally well say that you are
-developing a new application of your own using some of the primitive
-functionality provided by the original application. As such, all the
-discussions of the preceding sections of this chapter are relevant to
-how you can proceed with developing your extension.
diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi
deleted file mode 100644
index b136bd865..000000000
--- a/doc/ref/repl-modules.texi
+++ /dev/null
@@ -1,131 +0,0 @@
-@page
-@node Readline Support
-@chapter Readline Support
-
-@c FIXME::martin: Review me!
-
-@cindex readline
-@cindex command line history
-Guile comes with an interface module to the readline library. This
-makes interactive use much more convenient, because of the command-line
-editing features of readline. Using @code{(ice-9 readline)}, you can
-navigate through the current input line with the cursor keys, retrieve
-older command lines from the input history and even search through the
-history entries.
-
-@menu
-* Loading Readline Support:: How to load readline support into Guile.
-* Readline Options:: How to modify readline's behaviour.
-@end menu
-
-
-@node Loading Readline Support
-@section Loading Readline Support
-
-The module is not loaded by default and so has to be loaded and
-activated explicitly. This is done with two simple lines of code:
-
-@lisp
-(use-modules (ice-9 readline))
-(activate-readline)
-@end lisp
-
-@c FIXME::martin: Review me!
-
-The first line will load the necessary code, and the second will
-activate readline's features for the REPL. If you plan to use this
-module often, you should save these to lines to your @file{.guile}
-personal startup file.
-
-You will notice that the REPL's behaviour changes a bit when you have
-loaded the readline module. For example, when you press Enter before
-typing in the closing parentheses of a list, you will see the
-@dfn{continuation} prompt, three dots: @code{...} This gives you a nice
-visual feedback when trying to match parentheses. To make this even
-easier, @dfn{bouncing parentheses} are implemented. That means that
-when you type in a closing parentheses, the cursor will jump to the
-corresponding opening parenthesis for a short time, making it trivial to make
-them match.
-
-Once the readline module is activated, all lines entered interactively
-will be stored in a history and can be recalled later using the
-cursor-up and -down keys. Readline also understands the Emacs keys for
-navigating through the command line and history.
-
-When you quit your Guile session by evaluating @code{(quit)} or pressing
-Ctrl-D, the history will be saved to the file @file{.guile_history} and
-read in when you start Guile for the next time. Thus you can start a
-new Guile session and still have the (probably long-winded) definition
-expressions available.
-
-
-@node Readline Options
-@section Readline Options
-
-@c FIXME::martin: Review me!
-
-@cindex readline options
-The readline interface module can be configured in several ways to
-better suit the user's needs. Configuration is done via the readline
-module's options interface, in a similar way to the evaluator and
-debugging options (@pxref{General option interface}.)
-
-Here is the list of readline options generated by typing
-@code{(readline-options 'full)} in Guile. You can also see the
-default values.
-
-@smalllisp
-bounce-parens 500 Time (ms) to show matching opening parenthesis (0 = off).
-history-length 200 History length.
-history-file yes Use history file.
-@end smalllisp
-
-The history length specifies how many input lines will be remembered.
-If the history contains that many lines and additional lines are
-entered, the oldest lines will be lost. You can switch on/off the
-usage of the history file using the following call.
-
-@lisp
-(readline-disable 'history)
-@end lisp
-
-The readline options interface can only be used @emph{after} loading
-the readline module, because it is defined in that module.
-
-
-@page
-@node Value History
-@chapter Value History
-
-@c FIXME::martin: Review me!
-
-@cindex value history
-Another module which makes command line usage more convenient is
-@code{(ice-9 history)}. This module will change the REPL so that each
-value which is evaluated and printed will be remembered under a name
-constructed from the dollar character (@code{$}) and the number of the
-evaluated expression.
-
-Consider an example session.
-
-@example
-guile> (use-modules (ice-9 history))
-guile> 1
-$1 = 1
-guile> (+ $1 $1)
-$2 = 2
-guile> (* $2 $2)
-$3 = 4
-@end example
-
-After loading the value history module @code{(ice-9 history)}, one
-(trivial) expression is evaluated. The result is stored into the
-variable @code{$1}. This fact is indicated by the output @code{$1 = },
-which is also caused by @code{(ice-9 history)}. In the next line, this
-variable is used two times, to produce the value @code{$2}, which in
-turn is used in the calculation for @code{$3}.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-binding.texi b/doc/ref/scheme-binding.texi
deleted file mode 100644
index 23786b3bf..000000000
--- a/doc/ref/scheme-binding.texi
+++ /dev/null
@@ -1,279 +0,0 @@
-@page
-@node Binding Constructs
-@chapter Definitions and Variable Bindings
-
-@c FIXME::martin: Review me!
-
-Scheme supports the definition of variables in different contexts.
-Variables can be defined at the top level, so that they are visible in
-the entire program, and variables can be defined locally to procedures
-and expressions. This is important for modularity and data abstraction.
-
-@menu
-* Top Level:: Top level variable definitions.
-* Local Bindings:: Local variable bindings.
-* Internal Definitions:: Internal definitions.
-* Binding Reflection:: Querying variable bindings.
-@end menu
-
-
-@node Top Level
-@section Top Level Variable Definitions
-
-@cindex variable definition
-
-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 @var{value})
-@end lisp
-
-@noindent
-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 @var{value})
-@end lisp
-
-@noindent
-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.
-
-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
-@section Local Variable Bindings
-
-@c FIXME::martin: Review me!
-
-@cindex local bindings
-@cindex local variables
-
-As opposed to definitions at the top level, which are visible in the
-whole program (or current module, when Guile modules are used), it is
-also possible to define variables which are only visible in a
-well-defined part of the program. Normally, this part of a program
-will be a procedure or a subexpression of a procedure.
-
-With the constructs for local binding (@code{let}, @code{let*} and
-@code{letrec}), the Scheme language has a block structure like most
-other programming languages since the days of @sc{Algol 60}. Readers
-familiar to languages like C or Java should already be used to this
-concept, but the family of @code{let} expressions has a few properties
-which are well worth knowing.
-
-The first local binding construct is @code{let}. The other constructs
-@code{let*} and @code{letrec} are specialized versions for usage where
-using plain @code{let} is a bit inconvenient.
-
-@deffn syntax let bindings body
-@var{bindings} has the form
-
-@lisp
-((@var{variable1} @var{init1}) @dots{})
-@end lisp
-
-that is zero or more two-element lists of a variable and an arbitrary
-expression each. All @var{variable} names must be distinct.
-
-A @code{let} expression is evaluated as follows.
-
-@itemize @bullet
-@item
-All @var{init} expressions are evaluated.
-
-@item
-New storage is allocated for the @var{variables}.
-
-@item
-The values of the @var{init} expressions are stored into the variables.
-
-@item
-The expressions in @var{body} are evaluated in order, and the value of
-the last expression is returned as the value of the @code{let}
-expression.
-
-@item
-The storage for the @var{variables} is freed.
-@end itemize
-
-The @var{init} expressions are not allowed to refer to any of the
-@var{variables}.
-@end deffn
-
-@deffn syntax let* bindings body
-Similar to @code{let}, but the variable bindings are performed
-sequentially, that means that all @var{init} expression are allowed to
-use the variables defined on their left in the binding list.
-
-A @code{let*} expression can always be expressed with nested @code{let}
-expressions.
-
-@lisp
-(let* ((a 1) (b a))
- b)
-@equiv{}
-(let ((a 1))
- (let ((b a))
- b))
-@end lisp
-@end deffn
-
-@deffn syntax letrec bindings body
-Similar to @code{let}, but it is possible to refer to the @var{variable}
-from lambda expression created in any of the @var{inits}. That is,
-procedures created in the @var{init} expression can recursively refer to
-the defined variables.
-
-@lisp
-(letrec ((even?
- (lambda (n)
- (if (zero? n)
- #t
- (odd? (- n 1)))))
- (odd?
- (lambda (n)
- (if (zero? n)
- #f
- (even? (- n 1))))))
- (even? 88))
-@result{}
-#t
-@end lisp
-@end deffn
-
-There is also an alternative form of the @code{let} form, which is used
-for expressing iteration. Because of the use as a looping construct,
-this form (the @dfn{named let}) is documented in the section about
-iteration (@pxref{while do, Iteration})
-
-@node Internal Definitions
-@section Internal definitions
-
-@c FIXME::martin: Review me!
-
-A @code{define} form which appears inside the body of a @code{lambda},
-@code{let}, @code{let*}, @code{letrec} or equivalent expression is
-called an @dfn{internal definition}. An internal definition differs
-from a top level definition (@pxref{Top Level}), because the definition
-is only visible inside the complete body of the enclosing form. Let us
-examine the following example.
-
-@lisp
-(let ((frumble "froz"))
- (define banana (lambda () (apple 'peach)))
- (define apple (lambda (x) x))
- (banana))
-@result{}
-peach
-@end lisp
-
-Here the enclosing form is a @code{let}, so the @code{define}s in the
-@code{let}-body are internal definitions. Because the scope of the
-internal definitions is the @strong{complete} body of the
-@code{let}-expression, the @code{lambda}-expression which gets bound
-to the variable @code{banana} may refer to the variable @code{apple},
-even though it's definition appears lexically @emph{after} the definition
-of @code{banana}. This is because a sequence of internal definition
-acts as if it were a @code{letrec} expression.
-
-@lisp
-(let ()
- (define a 1)
- (define b 2)
- (+ a b))
-@end lisp
-
-@noindent
-is equivalent to
-
-@lisp
-(let ()
- (letrec ((a 1) (b 2))
- (+ a b)))
-@end lisp
-
-Another noteworthy difference to top level definitions is that within
-one group of internal definitions all variable names must be distinct.
-That means where on the top level a second define for a given variable
-acts like a @code{set!}, an exception is thrown for internal definitions
-with duplicate bindings.
-
-@c FIXME::martin: The following is required by R5RS, but Guile does not
-@c signal an error. Document it anyway, saying that Guile is sloppy?
-
-@c Internal definitions are only allowed at the beginning of the body of an
-@c enclosing expression. They may not be mixed with other expressions.
-
-@c @lisp
-@c (let ()
-@c (define a 1)
-@c a
-@c (define b 2)
-@c b)
-@c @end lisp
-
-@node Binding Reflection
-@section Querying variable bindings
-
-Guile provides a procedure for checking whether a symbol is bound in the
-top level environment. If you want to test whether a symbol is locally
-bound in expression, you can use the @code{bound?} macro from the module
-@code{(ice-9 optargs)}, documented in @ref{Optional Arguments}.
-
-@c NJFIXME explain [env]
-@deffn {Scheme Procedure} defined? sym [env]
-@deffnx {C Function} scm_definedp (sym, env)
-Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-compound.texi b/doc/ref/scheme-compound.texi
deleted file mode 100644
index b39ea76ca..000000000
--- a/doc/ref/scheme-compound.texi
+++ /dev/null
@@ -1,2431 +0,0 @@
-@page
-@node Compound Data Types
-@chapter Compound Data Types
-
-This chapter describes Guile's compound data types. By @dfn{compound}
-we mean that the primary purpose of these data types is to act as
-containers for other kinds of data (including other compound objects).
-For instance, a (non-uniform) vector with length 5 is a container that
-can hold five arbitrary Scheme objects.
-
-The various kinds of container object differ from each other in how
-their memory is allocated, how they are indexed, and how particular
-values can be looked up within them.
-
-@menu
-* Pairs:: Scheme's basic building block.
-* Lists:: Special list functions supported by Guile.
-* Vectors:: One-dimensional arrays of Scheme objects.
-* Records::
-* Structures::
-* Arrays:: Arrays of values.
-* Association Lists and Hash Tables:: Dictionary data types.
-@end menu
-
-
-@node Pairs
-@section Pairs
-@tpindex Pairs
-
-Pairs are used to combine two Scheme objects into one compound object.
-Hence the name: A pair stores a pair of objects.
-
-The data type @dfn{pair} is extremely important in Scheme, just like in
-any other Lisp dialect. The reason is that pairs are not only used to
-make two values available as one object, but that pairs are used for
-constructing lists of values. Because lists are so important in Scheme,
-they are described in a section of their own (@pxref{Lists}).
-
-Pairs can literally get entered in source code or at the REPL, in the
-so-called @dfn{dotted list} syntax. This syntax consists of an opening
-parentheses, the first element of the pair, a dot, the second element
-and a closing parentheses. The following example shows how a pair
-consisting of the two numbers 1 and 2, and a pair containing the symbols
-@code{foo} and @code{bar} can be entered. It is very important to write
-the whitespace before and after the dot, because otherwise the Scheme
-parser would not be able to figure out where to split the tokens.
-
-@lisp
-(1 . 2)
-(foo . bar)
-@end lisp
-
-But beware, if you want to try out these examples, you have to
-@dfn{quote} the expressions. More information about quotation is
-available in the section (REFFIXME). The correct way to try these
-examples is as follows.
-
-@lisp
-'(1 . 2)
-@result{}
-(1 . 2)
-'(foo . bar)
-@result{}
-(foo . bar)
-@end lisp
-
-A new pair is made by calling the procedure @code{cons} with two
-arguments. Then the argument values are stored into a newly allocated
-pair, and the pair is returned. The name @code{cons} stands for
-"construct". Use the procedure @code{pair?} to test whether a
-given Scheme object is a pair or not.
-
-@rnindex cons
-@deffn {Scheme Procedure} cons x y
-@deffnx {C Function} scm_cons (x, y)
-Return a newly allocated pair whose car is @var{x} and whose
-cdr is @var{y}. The pair is guaranteed to be different (in the
-sense of @code{eq?}) from every previously existing object.
-@end deffn
-
-@rnindex pair?
-@deffn {Scheme Procedure} pair? x
-@deffnx {C Function} scm_pair_p (x)
-Return @code{#t} if @var{x} is a pair; otherwise return
-@code{#f}.
-@end deffn
-
-The two parts of a pair are traditionally called @dfn{car} and
-@dfn{cdr}. They can be retrieved with procedures of the same name
-(@code{car} and @code{cdr}), and can be modified with the procedures
-@code{set-car!} and @code{set-cdr!}. Since a very common operation in
-Scheme programs is to access the car of a pair, or the car of the cdr of
-a pair, etc., the procedures called @code{caar}, @code{cadr} and so on
-are also predefined.
-
-@rnindex car
-@rnindex cdr
-@deffn {Scheme Procedure} car pair
-@deffnx {Scheme Procedure} cdr pair
-Return the car or the cdr of @var{pair}, respectively.
-@end deffn
-
-@deffn {Scheme Procedure} caar pair
-@deffnx {Scheme Procedure} cadr pair @dots{}
-@deffnx {Scheme Procedure} cdddar pair
-@deffnx {Scheme Procedure} cddddr pair
-These procedures are compositions of @code{car} and @code{cdr}, where
-for example @code{caddr} could be defined by
-
-@lisp
-(define caddr (lambda (x) (car (cdr (cdr x)))))
-@end lisp
-@end deffn
-
-@rnindex set-car!
-@deffn {Scheme Procedure} set-car! pair value
-@deffnx {C Function} scm_set_car_x (pair, value)
-Stores @var{value} in the car field of @var{pair}. The value returned
-by @code{set-car!} is unspecified.
-@end deffn
-
-@rnindex set-cdr!
-@deffn {Scheme Procedure} set-cdr! pair value
-@deffnx {C Function} scm_set_cdr_x (pair, value)
-Stores @var{value} in the cdr field of @var{pair}. The value returned
-by @code{set-cdr!} is unspecified.
-@end deffn
-
-
-@node Lists
-@section Lists
-@tpindex Lists
-
-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
-@dfn{chained pairs}, and only exist by definition---a list is a chain
-of pairs which looks like a list.}
-
-This is the short definition of what a list is:
-
-@itemize @bullet
-@item
-Either the empty list @code{()},
-
-@item
-or a pair which has a list in its cdr.
-@end itemize
-
-@c FIXME::martin: Describe the pair chaining in more detail.
-
-@c FIXME::martin: What is a proper, what an improper list?
-@c What is a circular list?
-
-@c FIXME::martin: Maybe steal some graphics from the Elisp reference
-@c manual?
-
-@menu
-* List Syntax:: Writing literal lists.
-* List Predicates:: Testing lists.
-* List Constructors:: Creating new lists.
-* List Selection:: Selecting from lists, getting their length.
-* Append/Reverse:: Appending and reversing lists.
-* List Modification:: Modifying existing lists.
-* List Searching:: Searching for list elements
-* List Mapping:: Applying procedures to lists.
-@end menu
-
-@node List Syntax
-@subsection List Read Syntax
-
-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
-the list elements, like a comma or a semicolon.}.
-
-@lisp
-(1 2 3) ; @r{a list of the numbers 1, 2 and 3}
-("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
-() ; @r{the empty list}
-@end lisp
-
-The last example needs a bit more explanation. A list with no elements,
-called the @dfn{empty list}, is special in some ways. It is used for
-terminating lists by storing it into the cdr of the last pair that makes
-up a list. An example will clear that up:
-
-@lisp
-(car '(1))
-@result{}
-1
-(cdr '(1))
-@result{}
-()
-@end lisp
-
-This example also shows that lists have to be quoted (REFFIXME) when
-written, because they would otherwise be mistakingly taken as procedure
-applications (@pxref{Simple Invocation}).
-
-
-@node List Predicates
-@subsection List Predicates
-
-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
-depending on the datatype of their arguments.
-
-@rnindex list?
-@deffn {Scheme Procedure} list? x
-@deffnx {C Function} scm_list_p (x)
-Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
-@end deffn
-
-The predicate @code{null?} is often used in list-processing code to
-tell whether a given list has run out of elements. That is, a loop
-somehow deals with the elements of a list until the list satisfies
-@code{null?}. Then, the algorithm terminates.
-
-@rnindex null?
-@deffn {Scheme Procedure} null? x
-@deffnx {C Function} scm_null_p (x)
-Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
-@end deffn
-
-@node List Constructors
-@subsection List Constructors
-
-This section describes the procedures for constructing new lists.
-@code{list} simply returns a list where the elements are the arguments,
-@code{cons*} is similar, but the last argument is stored in the cdr of
-the last pair of the list.
-
-@rnindex list
-@deffn {Scheme Procedure} list . objs
-@deffnx {C Function} scm_list (objs)
-Return a list containing @var{objs}, the arguments to
-@code{list}.
-@end deffn
-
-@deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
-@deffnx {C Function} scm_cons_star (arg1, rest)
-Like @code{list}, but the last arg provides the tail of the
-constructed list, returning @code{(cons @var{arg1} (cons
-@var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
-argument. If given one argument, that argument is returned as
-result. This function is called @code{list*} in some other
-Schemes and in Common LISP.
-@end deffn
-
-@deffn {Scheme Procedure} list-copy lst
-@deffnx {C Function} scm_list_copy (lst)
-Return a (newly-created) copy of @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} make-list n [init]
-Create a list containing of @var{n} elements, where each element is
-initialized to @var{init}. @var{init} defaults to the empty list
-@code{()} if not given.
-@end deffn
-
-Note that @code{list-copy} only makes a copy of the pairs which make up
-the spine of the lists. The list elements are not copied, which means
-that modifying the elements of the new list also modifies the elements
-of the old list. On the other hand, applying procedures like
-@code{set-cdr!} or @code{delv!} to the new list will not alter the old
-list. If you also need to copy the list elements (making a deep copy),
-use the procedure @code{copy-tree} (@pxref{Copying}).
-
-@node List Selection
-@subsection List Selection
-
-These procedures are used to get some information about a list, or to
-retrieve one or more elements of a list.
-
-@rnindex length
-@deffn {Scheme Procedure} length lst
-@deffnx {C Function} scm_length (lst)
-Return the number of elements in list @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} last-pair lst
-@deffnx {C Function} scm_last_pair (lst)
-Return a pointer to the last pair in @var{lst}, signalling an error if
-@var{lst} is circular.
-@end deffn
-
-@rnindex list-ref
-@deffn {Scheme Procedure} list-ref list k
-@deffnx {C Function} scm_list_ref (list, k)
-Return the @var{k}th element from @var{list}.
-@end deffn
-
-@rnindex list-tail
-@deffn {Scheme Procedure} list-tail lst k
-@deffnx {Scheme Procedure} list-cdr-ref lst k
-@deffnx {C Function} scm_list_tail (lst, k)
-Return the "tail" of @var{lst} beginning with its @var{k}th element.
-The first element of the list is considered to be element 0.
-
-@code{list-tail} and @code{list-cdr-ref} are identical. It may help to
-think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
-or returning the results of cdring @var{k} times down @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} list-head lst k
-@deffnx {C Function} scm_list_head (lst, k)
-Copy the first @var{k} elements from @var{lst} into a new list, and
-return it.
-@end deffn
-
-@node Append/Reverse
-@subsection Append and Reverse
-
-@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
-order. The procedure variants with an @code{!} directly modify the
-pairs which form the list, whereas the other procedures create new
-pairs. This is why you should be careful when using the side-effecting
-variants.
-
-@rnindex append
-@deffn {Scheme Procedure} append . args
-@deffnx {C Function} scm_append (args)
-Return a list consisting of the elements the lists passed as
-arguments.
-@lisp
-(append '(x) '(y)) @result{} (x y)
-(append '(a) '(b c d)) @result{} (a b c d)
-(append '(a (b)) '((c))) @result{} (a (b) (c))
-@end lisp
-The resulting list is always newly allocated, except that it
-shares structure with the last list argument. The last
-argument may actually be any object; an improper list results
-if the last argument is not a proper list.
-@lisp
-(append '(a b) '(c . d)) @result{} (a b c . d)
-(append '() 'a) @result{} a
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} append! . lists
-@deffnx {C Function} scm_append_x (lists)
-A destructive version of @code{append} (@pxref{Pairs and
-lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field
-of each list's final pair is changed to point to the head of
-the next list, so no consing is performed. Return a pointer to
-the mutated list.
-@end deffn
-
-@rnindex reverse
-@deffn {Scheme Procedure} reverse lst
-@deffnx {C Function} scm_reverse (lst)
-Return a new list that contains the elements of @var{lst} but
-in reverse order.
-@end deffn
-
-@c NJFIXME explain new_tail
-@deffn {Scheme Procedure} reverse! lst [new_tail]
-@deffnx {C Function} scm_reverse_x (lst, new_tail)
-A destructive version of @code{reverse} (@pxref{Pairs and lists,,,r5rs,
-The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is
-modified to point to the previous list element. Return a pointer to the
-head of the reversed list.
-
-Caveat: because the list is modified in place, the tail of the original
-list now becomes its head, and the head of the original list now becomes
-the tail. Therefore, the @var{lst} symbol to which the head of the
-original list was bound now points to the tail. To ensure that the head
-of the modified list is not lost, it is wise to save the return value of
-@code{reverse!}
-@end deffn
-
-@node List Modification
-@subsection List Modification
-
-The following procedures modify an existing list, either by changing
-elements of the list, or by changing the list structure itself.
-
-@deffn {Scheme Procedure} list-set! list k val
-@deffnx {C Function} scm_list_set_x (list, k, val)
-Set the @var{k}th element of @var{list} to @var{val}.
-@end deffn
-
-@deffn {Scheme Procedure} list-cdr-set! list k val
-@deffnx {C Function} scm_list_cdr_set_x (list, k, val)
-Set the @var{k}th cdr of @var{list} to @var{val}.
-@end deffn
-
-@deffn {Scheme Procedure} delq item lst
-@deffnx {C Function} scm_delq (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{eq?} to @var{item} removed. This procedure mirrors
-@code{memq}: @code{delq} compares elements of @var{lst} against
-@var{item} with @code{eq?}.
-@end deffn
-
-@deffn {Scheme Procedure} delv item lst
-@deffnx {C Function} scm_delv (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{eqv?} to @var{item} removed. This procedure mirrors
-@code{memv}: @code{delv} compares elements of @var{lst} against
-@var{item} with @code{eqv?}.
-@end deffn
-
-@deffn {Scheme Procedure} delete item lst
-@deffnx {C Function} scm_delete (item, lst)
-Return a newly-created copy of @var{lst} with elements
-@code{equal?} to @var{item} removed. This procedure mirrors
-@code{member}: @code{delete} compares elements of @var{lst}
-against @var{item} with @code{equal?}.
-@end deffn
-
-@deffn {Scheme Procedure} delq! item lst
-@deffnx {Scheme Procedure} delv! item lst
-@deffnx {Scheme Procedure} delete! item lst
-@deffnx {C Function} scm_delq_x (item, lst)
-@deffnx {C Function} scm_delv_x (item, lst)
-@deffnx {C Function} scm_delete_x (item, lst)
-These procedures are destructive versions of @code{delq}, @code{delv}
-and @code{delete}: they modify the pointers in the existing @var{lst}
-rather than creating a new list. Caveat evaluator: Like other
-destructive list functions, these functions cannot modify the binding of
-@var{lst}, and so cannot be used to delete the first element of
-@var{lst} destructively.
-@end deffn
-
-@deffn {Scheme Procedure} delq1! item lst
-@deffnx {C Function} scm_delq1_x (item, lst)
-Like @code{delq!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{eq?}. See also @code{delv1!} and @code{delete1!}.
-@end deffn
-
-@deffn {Scheme Procedure} delv1! item lst
-@deffnx {C Function} scm_delv1_x (item, lst)
-Like @code{delv!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{eqv?}. See also @code{delq1!} and @code{delete1!}.
-@end deffn
-
-@deffn {Scheme Procedure} delete1! item lst
-@deffnx {C Function} scm_delete1_x (item, lst)
-Like @code{delete!}, but only deletes the first occurrence of
-@var{item} from @var{lst}. Tests for equality using
-@code{equal?}. See also @code{delq1!} and @code{delv1!}.
-@end deffn
-
-@node List Searching
-@subsection List Searching
-
-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
-they return the sublist whose car is equal to the search object, where
-equality depends on the equality predicate used.
-
-@rnindex memq
-@deffn {Scheme Procedure} memq x lst
-@deffnx {C Function} scm_memq (x, lst)
-Return the first sublist of @var{lst} whose car is @code{eq?}
-to @var{x} where the sublists of @var{lst} are the non-empty
-lists returned by @code{(list-tail @var{lst} @var{k})} for
-@var{k} less than the length of @var{lst}. If @var{x} does not
-occur in @var{lst}, then @code{#f} (not the empty list) is
-returned.
-@end deffn
-
-@rnindex memv
-@deffn {Scheme Procedure} memv x lst
-@deffnx {C Function} scm_memv (x, lst)
-Return the first sublist of @var{lst} whose car is @code{eqv?}
-to @var{x} where the sublists of @var{lst} are the non-empty
-lists returned by @code{(list-tail @var{lst} @var{k})} for
-@var{k} less than the length of @var{lst}. If @var{x} does not
-occur in @var{lst}, then @code{#f} (not the empty list) is
-returned.
-@end deffn
-
-@rnindex member
-@deffn {Scheme Procedure} member x lst
-@deffnx {C Function} scm_member (x, lst)
-Return the first sublist of @var{lst} whose car is
-@code{equal?} to @var{x} where the sublists of @var{lst} are
-the non-empty lists returned by @code{(list-tail @var{lst}
-@var{k})} for @var{k} less than the length of @var{lst}. If
-@var{x} does not occur in @var{lst}, then @code{#f} (not the
-empty list) is returned.
-@end deffn
-
-
-@node List Mapping
-@subsection List Mapping
-
-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
-lists. They take a procedure and one or more lists as arguments, and
-apply the procedure to each element of the list. They differ in their
-return value.
-
-@rnindex map
-@c begin (texi-doc-string "guile" "map")
-@deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
-@deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
-@deffnx {C Function} scm_map (proc, arg1, args)
-Apply @var{proc} to each element of the list @var{arg1} (if only two
-arguments are given), or to the corresponding elements of the argument
-lists (if more than two arguments are given). The result(s) of the
-procedure applications are saved and returned in a list. For
-@code{map}, the order of procedure applications is not specified,
-@code{map-in-order} applies the procedure from left to right to the list
-elements.
-@end deffn
-
-@rnindex for-each
-@c begin (texi-doc-string "guile" "for-each")
-@deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
-Like @code{map}, but the procedure is always applied from left to right,
-and the result(s) of the procedure applications are thrown away. The
-return value is not specified.
-@end deffn
-
-
-@node Vectors
-@section Vectors
-@tpindex Vectors
-
-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
-given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
-is constant, whereas lists have an access time linear to the position of the
-accessed element in the list.
-
-Vectors can contain any kind of Scheme object; it is even possible to have
-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}).
-
-@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
-is as follows: A sharp sign (@code{#}), followed by an opening
-parentheses, all elements of the vector in their respective read syntax,
-and finally a closing parentheses. The following are examples of the
-read syntax for vectors; where the first vector only contains numbers
-and the second three different object types: a string, a symbol and a
-number in hexadecimal notation.
-
-@lisp
-#(1 2 3)
-#("Hello" foo #xdeadbeef)
-@end lisp
-
-
-@node Vector Creation
-@subsection Dynamic Vector Creation and Validation
-
-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
-@deffn {Scheme Procedure} vector . l
-@deffnx {Scheme Procedure} list->vector l
-@deffnx {C Function} scm_vector (l)
-Return a newly allocated vector composed of the
-given arguments. Analogous to @code{list}.
-
-@lisp
-(vector 'a 'b 'c) @result{} #(a b c)
-@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)
-Return a newly allocated list composed of the elements of @var{v}.
-
-@lisp
-(vector->list '#(dah dah didah)) @result{} (dah dah didah)
-(list->vector '(dididit dah)) @result{} #(dididit dah)
-@end lisp
-@end deffn
-
-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):
-
-@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
-
-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.
-@lisp
-(let ((vec (vector 0 '(2 2 2 2) "Anna")))
- (vector-set! vec 1 '("Sue" "Sue"))
- vec) @result{} #(0 ("Sue" "Sue") "Anna")
-@end lisp
-@end deffn
-
-@rnindex vector-fill!
-@deffn {Scheme Procedure} vector-fill! v fill
-@deffnx {C Function} scm_vector_fill_x (v, fill)
-Store @var{fill} in every position of @var{vector}. The value
-returned by @code{vector-fill!} is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
-@deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
-Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
-to @var{vec2} starting at position @var{start2}. @var{start1} and
-@var{start2} are inclusive indices; @var{end1} is exclusive.
-
-@code{vector-move-left!} copies elements in leftmost order.
-Therefore, in the case where @var{vec1} and @var{vec2} refer to the
-same vector, @code{vector-move-left!} is usually appropriate when
-@var{start1} is greater than @var{start2}.
-@end deffn
-
-@deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
-@deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
-Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
-to @var{vec2} starting at position @var{start2}. @var{start1} and
-@var{start2} are inclusive indices; @var{end1} is exclusive.
-
-@code{vector-move-right!} copies elements in rightmost order.
-Therefore, in the case where @var{vec1} and @var{vec2} refer to the
-same vector, @code{vector-move-right!} is usually appropriate when
-@var{start1} is less than @var{start2}.
-@end deffn
-
-
-@node Records
-@section Records
-
-A @dfn{record type} is a first class object representing a user-defined
-data type. A @dfn{record} is an instance of a record type.
-
-@deffn {Scheme Procedure} record? obj
-Return @code{#t} if @var{obj} is a record of any type and @code{#f}
-otherwise.
-
-Note that @code{record?} may be true of any Scheme value; there is no
-promise that records are disjoint with other Scheme types.
-@end deffn
-
-@deffn {Scheme Procedure} make-record-type type-name field-names
-Return a @dfn{record-type descriptor}, a value representing a new data
-type disjoint from all others. The @var{type-name} argument must be a
-string, but is only used for debugging purposes (such as the printed
-representation of a record of the new type). The @var{field-names}
-argument is a list of symbols naming the @dfn{fields} of a record of the
-new type. It is an error if the list contains any duplicates. It is
-unspecified how record-type descriptors are represented.
-@end deffn
-
-@deffn {Scheme Procedure} record-constructor rtd [field-names]
-Return a procedure for constructing new members of the type represented
-by @var{rtd}. The returned procedure accepts exactly as many arguments
-as there are symbols in the given list, @var{field-names}; these are
-used, in order, as the initial values of those fields in a new record,
-which is returned by the constructor procedure. The values of any
-fields not named in that list are unspecified. The @var{field-names}
-argument defaults to the list of field names in the call to
-@code{make-record-type} that created the type represented by @var{rtd};
-if the @var{field-names} argument is provided, it is an error if it
-contains any duplicates or any symbols not in the default list.
-@end deffn
-
-@deffn {Scheme Procedure} record-predicate rtd
-Return a procedure for testing membership in the type represented by
-@var{rtd}. The returned procedure accepts exactly one argument and
-returns a true value if the argument is a member of the indicated record
-type; it returns a false value otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} record-accessor rtd field-name
-Return a procedure for reading the value of a particular field of a
-member of the type represented by @var{rtd}. The returned procedure
-accepts exactly one argument which must be a record of the appropriate
-type; it returns the current value of the field named by the symbol
-@var{field-name} in that record. The symbol @var{field-name} must be a
-member of the list of field-names in the call to @code{make-record-type}
-that created the type represented by @var{rtd}.
-@end deffn
-
-@deffn {Scheme Procedure} record-modifier rtd field-name
-Return a procedure for writing the value of a particular field of a
-member of the type represented by @var{rtd}. The returned procedure
-accepts exactly two arguments: first, a record of the appropriate type,
-and second, an arbitrary Scheme value; it modifies the field named by
-the symbol @var{field-name} in that record to contain the given value.
-The returned value of the modifier procedure is unspecified. The symbol
-@var{field-name} must be a member of the list of field-names in the call
-to @code{make-record-type} that created the type represented by
-@var{rtd}.
-@end deffn
-
-@deffn {Scheme Procedure} record-type-descriptor record
-Return a record-type descriptor representing the type of the given
-record. That is, for example, if the returned descriptor were passed to
-@code{record-predicate}, the resulting predicate would return a true
-value when passed the given record. Note that it is not necessarily the
-case that the returned descriptor is the one that was passed to
-@code{record-constructor} in the call that created the constructor
-procedure that created the given record.
-@end deffn
-
-@deffn {Scheme Procedure} record-type-name rtd
-Return the type-name associated with the type represented by rtd. The
-returned value is @code{eqv?} to the @var{type-name} argument given in
-the call to @code{make-record-type} that created the type represented by
-@var{rtd}.
-@end deffn
-
-@deffn {Scheme Procedure} record-type-fields rtd
-Return a list of the symbols naming the fields in members of the type
-represented by @var{rtd}. The returned value is @code{equal?} to the
-field-names argument given in the call to @code{make-record-type} that
-created the type represented by @var{rtd}.
-@end deffn
-
-
-@node Structures
-@section Structures
-@tpindex Structures
-
-[FIXME: this is pasted in from Tom Lord's original guile.texi and should
-be reviewed]
-
-A @dfn{structure type} is a first class user-defined data type. A
-@dfn{structure} is an instance of a structure type. A structure type is
-itself a structure.
-
-Structures are less abstract and more general than traditional records.
-In fact, in Guile Scheme, records are implemented using structures.
-
-@menu
-* Structure Concepts:: The structure of Structures
-* Structure Layout:: Defining the layout of structure types
-* Structure Basics:: make-, -ref and -set! procedures for structs
-* Vtables:: Accessing type-specific data
-@end menu
-
-@node Structure Concepts
-@subsection Structure Concepts
-
-A structure object consists of a handle, structure data, and a vtable.
-The handle is a Scheme value which points to both the vtable and the
-structure's data. Structure data is a dynamically allocated region of
-memory, private to the structure, divided up into typed fields. A
-vtable is another structure used to hold type-specific data. Multiple
-structures can share a common vtable.
-
-Three concepts are key to understanding structures.
-
-@itemize @bullet{}
-@item @dfn{layout specifications}
-
-Layout specifications determine how memory allocated to structures is
-divided up into fields. Programmers must write a layout specification
-whenever a new type of structure is defined.
-
-@item @dfn{structural accessors}
-
-Structure access is by field number. There is only one set of
-accessors common to all structure objects.
-
-@item @dfn{vtables}
-
-Vtables, themselves structures, are first class representations of
-disjoint sub-types of structures in general. In most cases, when a
-new structure is created, programmers must specify a vtable for the
-new structure. Each vtable has a field describing the layout of its
-instances. Vtables can have additional, user-defined fields as well.
-@end itemize
-
-
-
-@node Structure Layout
-@subsection Structure Layout
-
-When a structure is created, a region of memory is allocated to hold its
-state. The @dfn{layout} of the structure's type determines how that
-memory is divided into fields.
-
-Each field has a specified type. There are only three types allowed, each
-corresponding to a one letter code. The allowed types are:
-
-@itemize @bullet{}
-@item 'u' -- unprotected
-
-The field holds binary data that is not GC protected.
-
-@item 'p' -- protected
-
-The field holds a Scheme value and is GC protected.
-
-@item 's' -- self
-
-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'd data.
-@end itemize
-
-
-Each field also has an associated access protection. There are only
-three kinds of protection, each corresponding to a one letter code.
-The allowed protections are:
-
-@itemize @bullet{}
-@item 'w' -- writable
-
-The field can be read and written.
-
-@item 'r' -- readable
-
-The field can be read, but not written.
-
-@item 'o' -- opaque
-
-The field can be neither read nor written. This kind
-of protection is for fields useful only to built-in routines.
-@end itemize
-
-A layout specification is described by stringing together pairs
-of letters: one to specify a field type and one to specify a field
-protection. For example, a traditional cons pair type object could
-be described as:
-
-@example
-; cons pairs have two writable fields of Scheme data
-"pwpw"
-@end example
-
-A pair object in which the first field is held constant could be:
-
-@example
-"prpw"
-@end example
-
-Binary fields, (fields of type "u"), hold one @dfn{word} each. The
-size of a word is a machine dependent value defined to be equal to the
-value of the C expression: @code{sizeof (long)}.
-
-The last field of a structure layout may specify a tail array.
-A tail array is indicated by capitalizing the field's protection
-code ('W', 'R' or 'O'). A tail-array field is replaced by
-a read-only binary data field containing an array size. The array
-size is determined at the time the structure is created. It is followed
-by a corresponding number of fields of the type specified for the
-tail array. For example, a conventional Scheme vector can be
-described as:
-
-@example
-; A vector is an arbitrary number of writable fields holding Scheme
-; values:
-"pW"
-@end example
-
-In the above example, field 0 contains the size of the vector and
-fields beginning at 1 contain the vector elements.
-
-A kind of tagged vector (a constant tag followed by conventional
-vector elements) might be:
-
-@example
-"prpW"
-@end example
-
-
-Structure layouts are represented by specially interned symbols whose
-name is a string of type and protection codes. To create a new
-structure layout, use this procedure:
-
-@deffn {Scheme Procedure} make-struct-layout fields
-@deffnx {C Function} scm_make_struct_layout (fields)
-Return a new structure layout object.
-
-@var{fields} must be a string made up of pairs of characters
-strung together. The first character of each pair describes a field
-type, the second a field protection. Allowed types are 'p' for
-GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
-a field that points to the structure itself. Allowed protections
-are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
-fields. The last field protection specification may be capitalized to
-indicate that the field is a tail-array.
-@end deffn
-
-
-
-@node Structure Basics
-@subsection Structure Basics
-
-This section describes the basic procedures for creating and accessing
-structures.
-
-@deffn {Scheme Procedure} make-struct vtable tail_array_size . init
-@deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
-Create a new structure.
-
-@var{type} must be a vtable structure (@pxref{Vtables}).
-
-@var{tail-elts} must be a non-negative integer. If the layout
-specification indicated by @var{type} includes a tail-array,
-this is the number of elements allocated to that array.
-
-The @var{init1}, @dots{} are optional arguments describing how
-successive fields of the structure should be initialized. Only fields
-with protection 'r' or 'w' can be initialized, except for fields of
-type 's', which are automatically initialized to point to the new
-structure itself; fields with protection 'o' can not be initialized by
-Scheme programs.
-
-If fewer optional arguments than initializable fields are supplied,
-fields of type 'p' get default value #f while fields of type 'u' are
-initialized to 0.
-
-Structs are currently the basic representation for record-like data
-structures in Guile. The plan is to eventually replace them with a
-new representation which will at the same time be easier to use and
-more powerful.
-
-For more information, see the documentation for @code{make-vtable-vtable}.
-@end deffn
-
-@deffn {Scheme Procedure} struct? x
-@deffnx {C Function} scm_struct_p (x)
-Return @code{#t} iff @var{x} is a structure object, else
-@code{#f}.
-@end deffn
-
-
-@deffn {Scheme Procedure} struct-ref handle pos
-@deffnx {Scheme Procedure} struct-set! struct n value
-@deffnx {C Function} scm_struct_ref (handle, pos)
-@deffnx {C Function} scm_struct_set_x (struct, n, value)
-Access (or modify) the @var{n}th field of @var{struct}.
-
-If the field is of type 'p', then it can be set to an arbitrary value.
-
-If the field is of type 'u', then it can only be set to a non-negative
-integer value small enough to fit in one machine word.
-@end deffn
-
-
-
-@node Vtables
-@subsection Vtables
-
-Vtables are structures that are used to represent structure types. Each
-vtable contains a layout specification in field
-@code{vtable-index-layout} -- instances of the type are laid out
-according to that specification. Vtables contain additional fields
-which are used only internally to libguile. The variable
-@code{vtable-offset-user} is bound to a field number. Vtable fields
-at that position or greater are user definable.
-
-@deffn {Scheme Procedure} struct-vtable handle
-@deffnx {C Function} scm_struct_vtable (handle)
-Return the vtable structure that describes the type of @var{struct}.
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable? x
-@deffnx {C Function} scm_struct_vtable_p (x)
-Return @code{#t} iff @var{x} is a vtable structure.
-@end deffn
-
-If you have a vtable structure, @code{V}, you can create an instance of
-the type it describes by using @code{(make-struct V ...)}. But where
-does @code{V} itself come from? One possibility is that @code{V} is an
-instance of a user-defined vtable type, @code{V'}, so that @code{V} is
-created by using @code{(make-struct V' ...)}. Another possibility is
-that @code{V} is an instance of the type it itself describes. Vtable
-structures of the second sort are created by this procedure:
-
-@deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
-@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
-Return a new, self-describing vtable structure.
-
-@var{user-fields} is a string describing user defined fields of the
-vtable beginning at index @code{vtable-offset-user}
-(see @code{make-struct-layout}).
-
-@var{tail-size} specifies the size of the tail-array (if any) of
-this vtable.
-
-@var{init1}, @dots{} are the optional initializers for the fields of
-the vtable.
-
-Vtables have one initializable system field---the struct printer.
-This field comes before the user fields in the initializers passed
-to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
-a third optional argument to @code{make-vtable-vtable} and a fourth to
-@code{make-struct} when creating vtables:
-
-If the value is a procedure, it will be called instead of the standard
-printer whenever a struct described by this vtable is printed.
-The procedure will be called with arguments STRUCT and PORT.
-
-The structure of a struct is described by a vtable, so the vtable is
-in essence the type of the struct. The vtable is itself a struct with
-a vtable. This could go on forever if it weren't for the
-vtable-vtables which are self-describing vtables, and thus terminate
-the chain.
-
-There are several potential ways of using structs, but the standard
-one is to use three kinds of structs, together building up a type
-sub-system: one vtable-vtable working as the root and one or several
-"types", each with a set of "instances". (The vtable-vtable should be
-compared to the class <class> which is the class of itself.)
-
-@lisp
-(define ball-root (make-vtable-vtable "pr" 0))
-
-(define (make-ball-type ball-color)
- (make-struct ball-root 0
- (make-struct-layout "pw")
- (lambda (ball port)
- (format port "#<a ~A ball owned by ~A>"
- (color ball)
- (owner ball)))
- ball-color))
-(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
-(define (owner ball) (struct-ref ball 0))
-
-(define red (make-ball-type 'red))
-(define green (make-ball-type 'green))
-
-(define (make-ball type owner) (make-struct type 0 owner))
-
-(define ball (make-ball green 'Nisse))
-ball @result{} #<a green ball owned by Nisse>
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable-name vtable
-@deffnx {C Function} scm_struct_vtable_name (vtable)
-Return the name of the vtable @var{vtable}.
-@end deffn
-
-@deffn {Scheme Procedure} set-struct-vtable-name! vtable name
-@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
-Set the name of the vtable @var{vtable} to @var{name}.
-@end deffn
-
-@deffn {Scheme Procedure} struct-vtable-tag handle
-@deffnx {C Function} scm_struct_vtable_tag (handle)
-Return the vtable tag of the structure @var{handle}.
-@end deffn
-
-
-@node Arrays
-@section Arrays
-@tpindex Arrays
-
-@menu
-* Conventional Arrays:: Arrays with arbitrary data.
-* Array Mapping:: Applying a procedure to the contents of an array.
-* Uniform Arrays:: Arrays with data of a single type.
-* Bit Vectors:: Vectors of bits.
-@end menu
-
-@node Conventional Arrays
-@subsection Conventional Arrays
-
-@dfn{Conventional arrays} are a collection of cells organized into an
-arbitrary number of dimensions. Each cell can hold any kind of Scheme
-value and can be accessed in constant time by supplying an index for
-each dimension. This contrasts with uniform arrays, which use memory
-more efficiently but can hold data of only a single type, and lists
-where inserting and deleting cells is more efficient, but more time
-is usually required to access a particular cell.
-
-A conventional array is displayed as @code{#} followed by the @dfn{rank}
-(number of dimensions) followed by the cells, organized into dimensions
-using parentheses. The nesting depth of the parentheses is equal to
-the rank.
-
-When an array is created, the number of dimensions and range of each
-dimension must be specified, e.g., to create a 2x3 array with a
-zero-based index:
-
-@example
-(make-array 'ho 2 3) @result{}
-#2((ho ho ho) (ho ho ho))
-@end example
-
-The range of each dimension can also be given explicitly, e.g., another
-way to create the same array:
-
-@example
-(make-array 'ho '(0 1) '(0 2)) @result{}
-#2((ho ho ho) (ho ho ho))
-@end example
-
-A conventional array with one dimension based at zero is identical to
-a vector:
-
-@example
-(make-array 'ho 3) @result{}
-#(ho ho ho)
-@end example
-
-The following procedures can be used with conventional arrays (or vectors).
-
-@deffn {Scheme Procedure} array? v [prot]
-@deffnx {C Function} scm_array_p (v, prot)
-Return @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.
-@end deffn
-
-@deffn {Scheme Procedure} make-array initial-value bound1 bound2 @dots{}
-Create and return an array that has as many dimensions as there are
-@var{bound}s and fill it with @var{initial-value}. Each @var{bound}
-may be a positive non-zero integer @var{N}, in which case the index for
-that dimension can range from 0 through @var{N-1}; or an explicit index
-range specifier in the form @code{(LOWER UPPER)}, where both @var{lower}
-and @var{upper} are integers, possibly less than zero, and possibly the
-same number (however, @var{lower} cannot be greater than @var{upper}).
-@end deffn
-
-@c array-ref's type is `compiled-closure'. There's some weird stuff
-@c going on in array.c, too. Let's call it a primitive. -twp
-
-@deffn {Scheme Procedure} uniform-vector-ref v args
-@deffnx {Scheme Procedure} array-ref v . args
-@deffnx {C Function} scm_uniform_vector_ref (v, args)
-Return the element at the @code{(index1, index2)} element in
-@var{array}.
-@end deffn
-
-@deffn {Scheme Procedure} array-in-bounds? v . args
-@deffnx {C Function} scm_array_in_bounds_p (v, args)
-Return @code{#t} if its arguments would be acceptable to
-@code{array-ref}.
-@end deffn
-
-@c fixme: why do these sigs differ? -ttn 2001/07/19 01:14:12
-@deffn {Scheme Procedure} array-set! v obj . args
-@deffnx {Scheme Procedure} uniform-array-set1! v obj args
-@deffnx {C Function} scm_array_set_x (v, obj, args)
-Set the element at the @code{(index1, index2)} element in @var{array} to
-@var{new-value}. The value returned by array-set! is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
-@deffnx {C Function} scm_make_shared_array (oldra, mapfunc, 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:
-@lisp
-(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 lisp
-@end deffn
-
-@deffn {Scheme Procedure} shared-array-increments ra
-@deffnx {C Function} scm_shared_array_increments (ra)
-For each dimension, return the distance between elements in the root vector.
-@end deffn
-
-@deffn {Scheme Procedure} shared-array-offset ra
-@deffnx {C Function} scm_shared_array_offset (ra)
-Return the root vector index of the first element in the array.
-@end deffn
-
-@deffn {Scheme Procedure} shared-array-root ra
-@deffnx {C Function} scm_shared_array_root (ra)
-Return the root vector of a shared array.
-@end deffn
-
-@deffn {Scheme Procedure} transpose-array ra . args
-@deffnx {C Function} scm_transpose_array (ra, args)
-Return 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}.
-
-@lisp
-(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 lisp
-@end deffn
-
-@deffn {Scheme Procedure} enclose-array ra . axes
-@deffnx {C Function} scm_enclose_array (ra, 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:
-@lisp
-(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 lisp
-@end deffn
-
-@deffn {Scheme Procedure} array-shape array
-Return a list of inclusive bounds of integers.
-@example
-(array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
-@end example
-@end deffn
-
-@deffn {Scheme Procedure} array-dimensions ra
-@deffnx {C Function} scm_array_dimensions (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:
-@lisp
-(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} array-rank ra
-@deffnx {C Function} scm_array_rank (ra)
-Return the number of dimensions of @var{obj}. If @var{obj} is
-not an array, @code{0} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} array->list v
-@deffnx {C Function} scm_array_to_list (v)
-Return a list consisting of all the elements, in order, of
-@var{array}.
-@end deffn
-
-@deffn {Scheme Procedure} array-copy! src dst
-@deffnx {Scheme Procedure} array-copy-in-order! src dst
-@deffnx {C Function} scm_array_copy_x (src, dst)
-Copy every element from vector or array @var{source} to the
-corresponding element of @var{destination}. @var{destination} must have
-the same rank as @var{source}, and be at least as large in each
-dimension. The order is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} array-fill! ra fill
-@deffnx {C Function} scm_array_fill_x (ra, fill)
-Store @var{fill} in every element of @var{array}. The value returned
-is unspecified.
-@end deffn
-
-@c begin (texi-doc-string "guile" "array-equal?")
-@deffn {Scheme Procedure} array-equal? ra0 ra1
-Return @code{#t} iff all arguments are arrays with the same shape, the
-same type, and have corresponding elements which are either
-@code{equal?} or @code{array-equal?}. This function differs from
-@code{equal?} in that a one dimensional shared array may be
-@var{array-equal?} but not @var{equal?} to a vector or uniform vector.
-@end deffn
-
-@deffn {Scheme Procedure} array-contents array [strict]
-@deffnx {C Function} scm_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.
-@end deffn
-
-@node Array Mapping
-@subsection Array Mapping
-
-@deffn {Scheme Procedure} array-map! ra0 proc . lra
-@deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra
-@deffnx {C Function} scm_array_map_x (ra0, proc, lra)
-@var{array1}, @dots{} must have the same number of dimensions as
-@var{array0} and have a range for each index which includes the range
-for the corresponding index in @var{array0}. @var{proc} is applied to
-each tuple of elements of @var{array1} @dots{} and the result is stored
-as the corresponding element in @var{array0}. The value returned is
-unspecified. The order of application is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} array-for-each proc ra0 . lra
-@deffnx {C Function} scm_array_for_each (proc, ra0, lra)
-Apply @var{proc} to each tuple of elements of @var{array0} @dots{}
-in row-major order. The value returned is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} array-index-map! ra proc
-@deffnx {C Function} scm_array_index_map_x (ra, proc)
-Apply @var{proc} to the indices of each element of @var{array} in
-turn, storing the result in the corresponding element. The value
-returned and the order of application are unspecified.
-
-One can implement @var{array-indexes} as
-@lisp
-(define (array-indexes array)
- (let ((ra (apply make-array #f (array-shape array))))
- (array-index-map! ra (lambda x x))
- ra))
-@end lisp
-Another example:
-@lisp
-(define (apl:index-generator n)
- (let ((v (make-uniform-vector n 1)))
- (array-index-map! v (lambda (i) i))
- v))
-@end lisp
-@end deffn
-
-@node Uniform Arrays
-@subsection Uniform Arrays
-@tpindex Uniform Arrays
-
-@noindent
-@dfn{Uniform arrays} have elements all of the
-same type and occupy less storage than conventional
-arrays. Uniform arrays with a single zero-based dimension
-are also known as @dfn{uniform vectors}. The procedures in
-this section can also be used on conventional arrays, vectors,
-bit-vectors and strings.
-
-@noindent
-When creating a uniform array, the type of data to be stored
-is indicated with a @var{prototype} argument. The following table
-lists the types available and example prototypes:
-
-@example
-prototype type printing character
-
-#t boolean (bit-vector) b
-#\a char (string) a
-#\nul byte (integer) y
-'s short (integer) h
-1 unsigned long (integer) u
--1 signed long (integer) e
-'l signed long long (integer) l
-1.0 float (single precision) s
-1/3 double (double precision float) i
-0+i complex (double precision) c
-() conventional vector
-@end example
-
-@noindent
-Unshared uniform arrays of characters with a single zero-based dimension
-are identical to strings:
-
-@example
-(make-uniform-array #\a 3) @result{}
-"aaa"
-@end example
-
-@noindent
-Unshared uniform arrays of booleans with a single zero-based dimension
-are identical to @ref{Bit Vectors, bit-vectors}.
-
-@example
-(make-uniform-array #t 3) @result{}
-#*111
-@end example
-
-@noindent
-Other uniform vectors are written in a form similar to that of vectors,
-except that a single character from the above table is put between
-@code{#} and @code{(}. For example, a uniform vector of signed
-long integers is displayed in the form @code{'#e(3 5 9)}.
-
-@deffn {Scheme Procedure} array? v [prot]
-Return @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.
-@end deffn
-
-@deffn {Scheme Procedure} make-uniform-array prototype bound1 bound2 @dots{}
-Create and return a uniform array of type corresponding to
-@var{prototype} that has as many dimensions as there are @var{bound}s
-and fill it with @var{prototype}.
-@end deffn
-
-@deffn {Scheme Procedure} array-prototype ra
-@deffnx {C Function} scm_array_prototype (ra)
-Return 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}.
-@end deffn
-
-@deffn {Scheme Procedure} list->uniform-array ndim prot lst
-@deffnx {Scheme Procedure} list->uniform-vector prot lst
-@deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
-Return 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.
-@end deffn
-
-@deffn {Scheme Procedure} uniform-vector-fill! uve fill
-Store @var{fill} in every element of @var{uve}. The value returned is
-unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} uniform-vector-length v
-@deffnx {C Function} scm_uniform_vector_length (v)
-Return the number of elements in @var{uve}.
-@end deffn
-
-@deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
-@deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
-@deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
-Create and return 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.
-@end deffn
-
-@c Another compiled-closure. -twp
-
-@deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
-@deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]
-@deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
-Attempt 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,
-the objects up to that point 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)}.
-@end deffn
-
-@deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
-@deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]
-@deffnx {C Function} scm_uniform_array_write (v, port_or_fd, 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)}.
-@end deffn
-
-@node Bit Vectors
-@subsection Bit Vectors
-
-@noindent
-Bit vectors are a specific type of uniform array: an array of booleans
-with a single zero-based index.
-
-@noindent
-They are displayed as a sequence of @code{0}s and
-@code{1}s prefixed by @code{#*}, e.g.,
-
-@example
-(make-uniform-vector 8 #t #f) @result{}
-#*00000000
-
-#b(#t #f #t) @result{}
-#*101
-@end example
-
-@deffn {Scheme Procedure} bit-count b bitvector
-@deffnx {C Function} scm_bit_count (b, bitvector)
-Return the number of occurrences of the boolean @var{b} in
-@var{bitvector}.
-@end deffn
-
-@deffn {Scheme Procedure} bit-position item v k
-@deffnx {C Function} scm_bit_position (item, v, k)
-Return 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.
-@end deffn
-
-@deffn {Scheme Procedure} bit-invert! v
-@deffnx {C Function} scm_bit_invert_x (v)
-Modify @var{bv} by replacing each element with its negation.
-@end deffn
-
-@deffn {Scheme Procedure} bit-set*! v kv obj
-@deffnx {C Function} scm_bit_set_star_x (v, kv, 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 long 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.
-@end deffn
-
-@deffn {Scheme Procedure} bit-count* v kv obj
-@deffnx {C Function} scm_bit_count_star (v, kv, obj)
-Return
-@lisp
-(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
-@end lisp
-@var{bv} is not modified.
-@end deffn
-
-
-@node Association Lists and Hash Tables
-@section Association Lists and Hash Tables
-
-This chapter discusses dictionary objects: data structures that are
-useful for organizing and indexing large bodies of information.
-
-@menu
-* Dictionary Types:: About dictionary types; what they're good for.
-* Association Lists:: List-based dictionaries.
-* Hash Tables:: Table-based dictionaries.
-@end menu
-
-@node Dictionary Types
-@subsection Dictionary Types
-
-A @dfn{dictionary} object is a data structure used to index
-information in a user-defined way. In standard Scheme, the main
-aggregate data types are lists and vectors. Lists are not really
-indexed at all, and vectors are indexed only by number
-(e.g. @code{(vector-ref foo 5)}). Often you will find it useful
-to index your data on some other type; for example, in a library
-catalog you might want to look up a book by the name of its
-author. Dictionaries are used to help you organize information in
-such a way.
-
-An @dfn{association list} (or @dfn{alist} for short) is a list of
-key-value pairs. Each pair represents a single quantity or
-object; the @code{car} of the pair is a key which is used to
-identify the object, and the @code{cdr} is the object's value.
-
-A @dfn{hash table} also permits you to index objects with
-arbitrary keys, but in a way that makes looking up any one object
-extremely fast. A well-designed hash system makes hash table
-lookups almost as fast as conventional array or vector references.
-
-Alists are popular among Lisp programmers because they use only
-the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
-and the equality primitives). No changes to the language core are
-necessary. Therefore, with Scheme's built-in list manipulation
-facilities, it is very convenient to handle data stored in an
-association list. Also, alists are highly portable and can be
-easily implemented on even the most minimal Lisp systems.
-
-However, alists are inefficient, especially for storing large
-quantities of data. Because we want Guile to be useful for large
-software systems as well as small ones, Guile provides a rich set
-of tools for using either association lists or hash tables.
-
-@node Association Lists
-@subsection Association Lists
-@tpindex Association Lists
-@tpindex Alist
-
-@cindex Association List
-@cindex Alist
-@cindex Database
-
-An association list is a conventional data structure that is often used
-to implement simple key-value databases. It consists of a list of
-entries in which each entry is a pair. The @dfn{key} of each entry is
-the @code{car} of the pair and the @dfn{value} of each entry is the
-@code{cdr}.
-
-@example
-ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
- (KEY2 . VALUE2)
- (KEY3 . VALUE3)
- @dots{}
- )
-@end example
-
-@noindent
-Association lists are also known, for short, as @dfn{alists}.
-
-The structure of an association list is just one example of the infinite
-number of possible structures that can be built using pairs and lists.
-As such, the keys and values in an association list can be manipulated
-using the general list structure procedures @code{cons}, @code{car},
-@code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
-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::
-@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 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.
-
-@itemize @bullet
-@item
-Procedures with @dfn{assq} in their name use @code{eq?} to determine key
-equality.
-
-@item
-Procedures with @dfn{assv} in their name use @code{eqv?} to determine
-key equality.
-
-@item
-Procedures with @dfn{assoc} in their name use @code{equal?} to
-determine key equality.
-@end itemize
-
-@code{acons} is an exception because it is used to build association
-lists which do not require their entries' keys to be unique.
-
-@node Adding or Setting Alist Entries
-@subsubsection Adding or Setting Alist Entries
-
-@code{acons} adds a new entry to an association list and returns the
-combined association list. The combined alist is formed by consing the
-new entry onto the head of the alist specified in the @code{acons}
-procedure call. So the specified alist is not modified, but its
-contents become shared with the tail of the combined alist that
-@code{acons} returns.
-
-In the most common usage of @code{acons}, a variable holding the
-original association list is updated with the combined alist:
-
-@example
-(set! address-list (acons name address address-list))
-@end example
-
-In such cases, it doesn't matter that the old and new values of
-@code{address-list} share some of their contents, since the old value is
-usually no longer independently accessible.
-
-Note that @code{acons} adds the specified new entry regardless of
-whether the alist may already contain entries with keys that are, in
-some sense, the same as that of the new entry. Thus @code{acons} is
-ideal for building alists where there is no concept of key uniqueness.
-
-@example
-(set! task-list (acons 3 "pay gas bill" '()))
-task-list
-@result{}
-((3 . "pay gas bill"))
-
-(set! task-list (acons 3 "tidy bedroom" task-list))
-task-list
-@result{}
-((3 . "tidy bedroom") (3 . "pay gas bill"))
-@end example
-
-@code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
-or replace an entry in an association list where there @emph{is} a
-concept of key uniqueness. If the specified association list already
-contains an entry whose key is the same as that specified in the
-procedure call, the existing entry is replaced by the new one.
-Otherwise, the new entry is consed onto the head of the old association
-list to create the combined alist. In all cases, these procedures
-return the combined alist.
-
-@code{assq-set!} and friends @emph{may} destructively modify the
-structure of the old association list in such a way that an existing
-variable is correctly updated without having to @code{set!} it to the
-value returned:
-
-@example
-address-list
-@result{}
-(("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
-
-(assoc-set! address-list "james" "1a London Road")
-@result{}
-(("mary" . "34 Elm Road") ("james" . "1a London Road"))
-
-address-list
-@result{}
-(("mary" . "34 Elm Road") ("james" . "1a London Road"))
-@end example
-
-Or they may not:
-
-@example
-(assoc-set! address-list "bob" "11 Newington Avenue")
-@result{}
-(("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
- ("james" . "1a London Road"))
-
-address-list
-@result{}
-(("mary" . "34 Elm Road") ("james" . "1a London Road"))
-@end example
-
-The only safe way to update an association list variable when adding or
-replacing an entry like this is to @code{set!} the variable to the
-returned value:
-
-@example
-(set! address-list
- (assoc-set! address-list "bob" "11 Newington Avenue"))
-address-list
-@result{}
-(("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
- ("james" . "1a London Road"))
-@end example
-
-Because of this slight inconvenience, you may find it more convenient to
-use hash tables to store dictionary data. If your application will not
-be modifying the contents of an alist very often, this may not make much
-difference to you.
-
-If you need to keep the old value of an association list in a form
-independent from the list that results from modification by
-@code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
-use @code{list-copy} to copy the old association list before modifying
-it.
-
-@deffn {Scheme Procedure} acons key value alist
-@deffnx {C Function} scm_acons (key, value, alist)
-Add a new key-value pair to @var{alist}. A new pair is
-created whose car is @var{key} and whose cdr is @var{value}, and the
-pair is consed onto @var{alist}, and the new list is returned. This
-function is @emph{not} destructive; @var{alist} is not modified.
-@end deffn
-
-@deffn {Scheme Procedure} assq-set! alist key val
-@deffnx {Scheme Procedure} assv-set! alist key value
-@deffnx {Scheme Procedure} assoc-set! alist key value
-@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)
-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.
-
-These functions do not attempt to verify the structure of @var{alist},
-and so may cause unusual results if passed an object that is not an
-association list.
-@end deffn
-
-@node Retrieving Alist Entries
-@subsubsection Retrieving Alist Entries
-@rnindex assq
-@rnindex assv
-@rnindex assoc
-
-@code{assq}, @code{assv} and @code{assoc} take an alist and a key as
-arguments and return the entry for that key if an entry exists, or
-@code{#f} if there is no entry for that key. Note that, in the cases
-where an entry exists, these procedures return the complete entry, that
-is @code{(KEY . VALUE)}, not just the value.
-
-@deffn {Scheme Procedure} assq key alist
-@deffnx {Scheme Procedure} assv key alist
-@deffnx {Scheme Procedure} assoc key alist
-@deffnx {C Function} scm_assq (key, alist)
-@deffnx {C Function} scm_assv (key, alist)
-@deffnx {C Function} scm_assoc (key, alist)
-Fetch the entry in @var{alist} that is associated with @var{key}. To
-decide whether the argument @var{key} matches a particular entry in
-@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
-uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
-cannot be found in @var{alist} (according to whichever equality
-predicate is in use), then return @code{#f}. These functions
-return the entire alist entry found (i.e. both the key and the value).
-@end deffn
-
-@code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
-hand, take an alist and a key and return @emph{just the value} for that
-key, if an entry exists. If there is no entry for the specified key,
-these procedures return @code{#f}.
-
-This creates an ambiguity: if the return value is @code{#f}, it means
-either that there is no entry with the specified key, or that there
-@emph{is} an entry for the specified key, with value @code{#f}.
-Consequently, @code{assq-ref} and friends should only be used where it
-is known that an entry exists, or where the ambiguity doesn't matter
-for some other reason.
-
-@deffn {Scheme Procedure} assq-ref alist key
-@deffnx {Scheme Procedure} assv-ref alist key
-@deffnx {Scheme Procedure} assoc-ref alist key
-@deffnx {C Function} scm_assq_ref (alist, key)
-@deffnx {C Function} scm_assv_ref (alist, key)
-@deffnx {C Function} scm_assoc_ref (alist, key)
-Like @code{assq}, @code{assv} and @code{assoc}, except that only the
-value associated with @var{key} in @var{alist} is returned. These
-functions are equivalent to
-
-@lisp
-(let ((ent (@var{associator} @var{key} @var{alist})))
- (and ent (cdr ent)))
-@end lisp
-
-where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
-@end deffn
-
-@node Removing Alist Entries
-@subsubsection Removing Alist Entries
-
-To remove the element from an association list whose key matches a
-specified key, use @code{assq-remove!}, @code{assv-remove!} or
-@code{assoc-remove!} (depending, as usual, on the level of equality
-required between the key that you specify and the keys in the
-association list).
-
-As with @code{assq-set!} and friends, the specified alist may or may not
-be modified destructively, and the only safe way to update a variable
-containing the alist is to @code{set!} it to the value that
-@code{assq-remove!} and friends return.
-
-@example
-address-list
-@result{}
-(("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
- ("james" . "1a London Road"))
-
-(set! address-list (assoc-remove! address-list "mary"))
-address-list
-@result{}
-(("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
-@end example
-
-Note that, when @code{assq/v/oc-remove!} is used to modify an
-association list that has been constructed only using the corresponding
-@code{assq/v/oc-set!}, there can be at most one matching entry in the
-alist, so the question of multiple entries being removed in one go does
-not arise. If @code{assq/v/oc-remove!} is applied to an association
-list that has been constructed using @code{acons}, or an
-@code{assq/v/oc-set!} with a different level of equality, or any mixture
-of these, it removes only the first matching entry from the alist, even
-if the alist might contain further matching entries. For example:
-
-@example
-(define address-list '())
-(set! address-list (assq-set! address-list "mary" "11 Elm Street"))
-(set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
-address-list
-@result{}
-(("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
-
-(set! address-list (assoc-remove! address-list "mary"))
-address-list
-@result{}
-(("mary" . "11 Elm Street"))
-@end example
-
-In this example, the two instances of the string "mary" are not the same
-when compared using @code{eq?}, so the two @code{assq-set!} calls add
-two distinct entries to @code{address-list}. When compared using
-@code{equal?}, both "mary"s in @code{address-list} are the same as the
-"mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
-after removing the first matching entry that it finds, and so one of the
-"mary" entries is left in place.
-
-@deffn {Scheme Procedure} assq-remove! alist key
-@deffnx {Scheme Procedure} assv-remove! alist key
-@deffnx {Scheme Procedure} assoc-remove! alist key
-@deffnx {C Function} scm_assq_remove_x (alist, key)
-@deffnx {C Function} scm_assv_remove_x (alist, key)
-@deffnx {C Function} scm_assoc_remove_x (alist, key)
-Delete the first entry in @var{alist} associated with @var{key}, and return
-the resulting alist.
-@end deffn
-
-@node Sloppy Alist Functions
-@subsubsection Sloppy Alist Functions
-
-@code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
-like the corresponding non-@code{sloppy-} procedures, except that they
-return @code{#f} when the specified association list is not well-formed,
-where the non-@code{sloppy-} versions would signal an error.
-
-Specifically, there are two conditions for which the non-@code{sloppy-}
-procedures signal an error, which the @code{sloppy-} procedures handle
-instead by returning @code{#f}. Firstly, if the specified alist as a
-whole is not a proper list:
-
-@example
-(assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
-@result{}
-ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
-ERROR: Wrong type argument in position 2 (expecting NULLP): "open sesame"
-ABORT: (wrong-type-arg)
-
-(sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
-@result{}
-#f
-@end example
-
-@noindent
-Secondly, if one of the entries in the specified alist is not a pair:
-
-@example
-(assoc 2 '((1 . 1) 2 (3 . 9)))
-@result{}
-ERROR: In procedure assoc in expression (assoc 2 (quote #)):
-ERROR: Wrong type argument in position 2 (expecting CONSP): 2
-ABORT: (wrong-type-arg)
-
-(sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
-@result{}
-#f
-@end example
-
-Unless you are explicitly working with badly formed association lists,
-it is much safer to use the non-@code{sloppy-} procedures, because they
-help to highlight coding and data errors that the @code{sloppy-}
-versions would silently cover up.
-
-@deffn {Scheme Procedure} sloppy-assq key alist
-@deffnx {C Function} scm_sloppy_assq (key, alist)
-Behaves like @code{assq} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-assv key alist
-@deffnx {C Function} scm_sloppy_assv (key, alist)
-Behaves like @code{assv} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-assoc key alist
-@deffnx {C Function} scm_sloppy_assoc (key, alist)
-Behaves like @code{assoc} but does not do any error checking.
-Recommended only for use in Guile internals.
-@end deffn
-
-@node Alist Example
-@subsubsection Alist Example
-
-Here is a longer example of how alists may be used in practice.
-
-@lisp
-(define capitals '(("New York" . "Albany")
- ("Oregon" . "Salem")
- ("Florida" . "Miami")))
-
-;; What's the capital of Oregon?
-(assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
-(assoc-ref capitals "Oregon") @result{} "Salem"
-
-;; We left out South Dakota.
-(set! capitals
- (assoc-set! capitals "South Dakota" "Pierre"))
-capitals
-@result{} (("South Dakota" . "Pierre")
- ("New York" . "Albany")
- ("Oregon" . "Salem")
- ("Florida" . "Miami"))
-
-;; And we got Florida wrong.
-(set! capitals
- (assoc-set! capitals "Florida" "Tallahassee"))
-capitals
-@result{} (("South Dakota" . "Pierre")
- ("New York" . "Albany")
- ("Oregon" . "Salem")
- ("Florida" . "Tallahassee"))
-
-;; After Oregon secedes, we can remove it.
-(set! capitals
- (assoc-remove! capitals "Oregon"))
-capitals
-@result{} (("South Dakota" . "Pierre")
- ("New York" . "Albany")
- ("Florida" . "Tallahassee"))
-@end lisp
-
-@node Hash Tables
-@subsection Hash Tables
-@tpindex Hash Tables
-
-@c FIXME::martin: Review me!
-
-Hash tables are dictionaries which offer similar functionality as
-association lists: They provide a mapping from keys to values. The
-difference is that association lists need time linear in the size of
-elements when searching for entries, whereas hash tables can normally
-search in constant time. The drawback is that hash tables require a
-little bit more memory, and that you can not use the normal list
-procedures (@pxref{Lists}) for working with them.
-
-@menu
-* Hash Table Examples:: Demonstration of hash table usage.
-* Hash Table Reference:: Hash table procedure descriptions.
-@end menu
-
-
-@node Hash Table Examples
-@subsubsection Hash Table Examples
-
-@c FIXME::martin: Review me!
-
-For demonstration purposes, this section gives a few usage examples of
-some hash table procedures, together with some explanation what they do.
-
-First we start by creating a new hash table with 31 slots, and
-populate it with two key/value pairs.
-
-@lisp
-(define h (make-hash-table 31))
-
-(hashq-create-handle! h 'foo "bar")
-@result{}
-(foo . "bar")
-
-(hashq-create-handle! h 'braz "zonk")
-@result{}
-(braz . "zonk")
-
-(hashq-create-handle! h 'frob #f)
-@result{}
-(frob . #f)
-@end lisp
-
-You can get the value for a given key with the procedure
-@code{hashq-ref}, but the problem with this procedure is that you
-cannot reliably determine whether a key does exists in the table. The
-reason is that the procedure returns @code{#f} if the key is not in
-the table, but it will return the same value if the key is in the
-table and just happens to have the value @code{#f}, as you can see in
-the following examples.
-
-@lisp
-(hashq-ref h 'foo)
-@result{}
-"bar"
-
-(hashq-ref h 'frob)
-@result{}
-#f
-
-(hashq-ref h 'not-there)
-@result{}
-#f
-@end lisp
-
-Better is to use the procedure @code{hashq-get-handle}, which makes a
-distinction between the two cases. Just like @code{assq}, this
-procedure returns a key/value-pair on success, and @code{#f} if the
-key is not found.
-
-@lisp
-(hashq-get-handle h 'foo)
-@result{}
-(foo . "bar")
-
-(hashq-get-handle h 'not-there)
-@result{}
-#f
-@end lisp
-
-There is no procedure for calculating the number of key/value-pairs in
-a hash table, but @code{hash-fold} can be used for doing exactly that.
-
-@lisp
-(hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
-@result{}
-3
-@end lisp
-
-@node Hash Table Reference
-@subsubsection Hash Table Reference
-
-Like the association list functions, the hash table functions come
-in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
-The @code{hashq} functions use @code{eq?} to determine whether two
-keys match. The @code{hashv} functions use @code{eqv?}, and the
-@code{hash} functions use @code{equal?}.
-
-In each of the functions that follow, the @var{table} argument
-must be a vector. The @var{key} and @var{value} arguments may be
-any Scheme object.
-
-@deffn {Scheme Procedure} make-hash-table size
-Create a new hash table of @var{size} slots. Note that the number of
-slots does not limit the size of the table, it just tells how large
-the underlying vector will be. The @var{size} should be similar to
-the expected number of elements which will be added to the table, but
-they need not match. For good performance, it might be a good idea to
-use a prime number as the @var{size}.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-ref table key [dflt]
-@deffnx {C Function} scm_hashq_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eq?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-ref table key [dflt]
-@deffnx {C Function} scm_hashv_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{eqv?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hash-ref table key [dflt]
-@deffnx {C Function} scm_hash_ref (table, key, dflt)
-Look up @var{key} in the hash table @var{table}, and return the
-value (if any) associated with it. If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument
-is supplied). Uses @code{equal?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-set! table key val
-@deffnx {C Function} scm_hashq_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eq?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-set! table key val
-@deffnx {C Function} scm_hashv_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{eqv?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hash-set! table key val
-@deffnx {C Function} scm_hash_set_x (table, key, val)
-Find the entry in @var{table} associated with @var{key}, and
-store @var{value} there. Uses @code{equal?} for equality
-testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-remove! table key
-@deffnx {C Function} scm_hashq_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eq?} for equality tests.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-remove! table key
-@deffnx {C Function} scm_hashv_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{eqv?} for equality tests.
-@end deffn
-
-@deffn {Scheme Procedure} hash-remove! table key
-@deffnx {C Function} scm_hash_remove_x (table, key)
-Remove @var{key} (and any value associated with it) from
-@var{table}. Uses @code{equal?} for equality tests.
-@end deffn
-
-The standard hash table functions may be too limited for some
-applications. For example, you may want a hash table to store
-strings in a case-insensitive manner, so that references to keys
-named ``foobar'', ``FOOBAR'' and ``FooBaR'' will all yield the
-same item. Guile provides you with @dfn{extended} hash tables
-that permit you to specify a hash function and associator function
-of your choosing. The functions described in the rest of this section
-can be used to implement such custom hash table structures.
-
-If you are unfamiliar with the inner workings of hash tables, then
-this facility will probably be a little too abstract for you to
-use comfortably. If you are interested in learning more, see an
-introductory textbook on data structures or algorithms for an
-explanation of how hash tables are implemented.
-
-@deffn {Scheme Procedure} hashq key size
-@deffnx {C Function} scm_hashq (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{eq?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{hashq} may use internal addresses. Thus two calls to
-hashq where the keys are @code{eq?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
-@deffn {Scheme Procedure} hashv key size
-@deffnx {C Function} scm_hashv (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{eqv?} is
-used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1. Note that
-@code{(hashv key)} may use internal addresses. Thus two calls
-to hashv where the keys are @code{eqv?} are not guaranteed to
-deliver the same value if the key object gets garbage collected
-in between. This can happen, for example with symbols:
-@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
-different values, since @code{foo} will be garbage collected.
-@end deffn
-
-@deffn {Scheme Procedure} hash key size
-@deffnx {C Function} scm_hash (key, size)
-Determine a hash value for @var{key} that is suitable for
-lookups in a hash table of size @var{size}, where @code{equal?}
-is used as the equality predicate. The function returns an
-integer in the range 0 to @var{size} - 1.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-ref hash assoc table key [dflt]
-@deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
-This behaves the same way as the corresponding @code{ref}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
-By way of illustration, @code{hashq-ref table key} is
-equivalent to @code{hashx-ref hashq assq table key}.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-set! hash assoc table key val
-@deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
-This behaves the same way as the corresponding @code{set!}
-function, but uses @var{hash} as a hash function and
-@var{assoc} to compare keys. @code{hash} must be a function
-that takes two arguments, a key to be hashed and a table size.
-@code{assoc} must be an associator function, like @code{assoc},
-@code{assq} or @code{assv}.
-
- By way of illustration, @code{hashq-set! table key} is
-equivalent to @code{hashx-set! hashq assq table key}.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-get-handle table key
-@deffnx {C Function} scm_hashq_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eq?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-get-handle table key
-@deffnx {C Function} scm_hashv_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{eqv?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hash-get-handle table key
-@deffnx {C Function} scm_hash_get_handle (table, key)
-This procedure returns the @code{(key . value)} pair from the
-hash table @var{table}. If @var{table} does not hold an
-associated value for @var{key}, @code{#f} is returned.
-Uses @code{equal?} for equality testing.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-get-handle hash assoc table key
-@deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
-This behaves the same way as the corresponding
-@code{-get-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
-@end deffn
-
-@deffn {Scheme Procedure} hashq-create-handle! table key init
-@deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hashv-create-handle! table key init
-@deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hash-create-handle! table key init
-@deffnx {C Function} scm_hash_create_handle_x (table, key, init)
-This function looks up @var{key} in @var{table} and returns its handle.
-If @var{key} is not already present, a new handle is created which
-associates @var{key} with @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} hashx-create-handle! hash assoc table key init
-@deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
-This behaves the same way as the corresponding
-@code{-create-handle} function, but uses @var{hash} as a hash
-function and @var{assoc} to compare keys. @code{hash} must be
-a function that takes two arguments, a key to be hashed and a
-table size. @code{assoc} must be an associator function, like
-@code{assoc}, @code{assq} or @code{assv}.
-@end deffn
-
-@deffn {Scheme Procedure} hash-fold proc init table
-@deffnx {C Function} scm_hash_fold (proc, init, table)
-An iterator over hash-table elements.
-Accumulates and returns a result by applying PROC successively.
-The arguments to PROC are "(key value prior-result)" where key
-and value are successive pairs from the hash table TABLE, and
-prior-result is either INIT (for the first application of PROC)
-or the return value of the previous application of PROC.
-For example, @code{(hash-fold acons '() tab)} will convert a hash
-table into an a-list of key-value pairs.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-control.texi b/doc/ref/scheme-control.texi
deleted file mode 100644
index 184ccae9d..000000000
--- a/doc/ref/scheme-control.texi
+++ /dev/null
@@ -1,979 +0,0 @@
-@page
-@node Control Mechanisms
-@chapter Controlling the Flow of Program Execution
-
-@menu
-* begin:: Evaluating a sequence of expressions.
-* if cond case:: Simple conditional evaluation.
-* and or:: Conditional evaluation of a sequence.
-* while do:: Iteration mechanisms.
-* Continuations:: Continuations.
-* Multiple Values:: Returning and accepting multiple values.
-* Exceptions:: Throwing and catching exceptions.
-* Error Reporting:: Procedures for signaling errors.
-* Dynamic Wind:: Guarding against non-local entrance/exit.
-* Handling Errors:: How to handle errors in C code.
-@end menu
-
-
-@node begin
-@section Evaluating a Sequence of Expressions
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@cindex begin
-@cindex sequencing
-@cindex expression sequencing
-
-@code{begin} is used for grouping several expression together so that
-they syntactically are treated as if they were one expression. This is
-particularly important when syntactic expressions are used which only
-allow one expression, but the programmer wants to use more than one
-expression in that place. As an example, consider the conditional
-expression below:
-
-@lisp
-(if (> x 0)
- (begin (display "greater") (newline)))
-@end lisp
-
-If the two calls to @code{display} and @code{newline} were not embedded
-in a @code{begin}-statement, the call to @code{newline} would get
-misinterpreted as the else-branch of the @code{if}-expression.
-
-@deffn syntax begin expr1 expr2 @dots{}
-The expression(s) are evaluated in left-to-right order and the value
-of the last expression is returned as the value of the
-@code{begin}-expression. This expression type is used when the
-expressions before the last one are evaluated for their side effects.
-@end deffn
-
-@node if cond case
-@section Simple Conditional Evaluation
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@cindex conditional evaluation
-@cindex if
-@cindex case
-@cindex cond
-
-Guile provides three syntactic constructs for conditional evaluation.
-@code{if} is the normal if-then-else expression (with an optional else
-branch), @code{cond} is a conditional expression with multiple branches
-and @code{case} branches if an expression has one of a set of constant
-values.
-
-@deffn syntax if test consequent [alternate]
-All arguments may be arbitrary expressions. First, @var{test} is
-evaluated. If it returns a true value, the expression @var{consequent}
-is evaluated and @var{alternate} is ignored. If @var{test} evaluates to
-@code{#f}, @var{alternate} is evaluated instead. The value of the
-evaluated branch (@var{consequent} or @var{alternate}) is returned as
-the value of the @code{if} expression.
-
-When @var{alternate} is omitted and the @var{test} evaluates to
-@code{#f}, the value of the expression is not specified.
-@end deffn
-
-@deffn syntax cond clause1 clause2 @dots{}
-Each @code{cond}-clause must look like this:
-
-@lisp
-(@var{test} @var{expression} @dots{})
-@end lisp
-
-where @var{test} and @var{expression} are arbitrary expression, or like
-this
-
-@lisp
-(@var{test} => @var{expression}
-@end lisp
-
-where @var{expression} must evaluate to a procedure.
-
-The @var{test}s of the clauses are evaluated in order and as soon as one
-of them evaluates to a true values, the corresponding @var{expression}s
-are evaluated in order and the last value is returned as the value of
-the @code{cond}-expression. For the @code{=>} clause type,
-@var{expression} is evaluated and the resulting procedure is applied to
-the value of @var{test}. The result of this procedure application is
-then the result of the @code{cond}-expression.
-
-The @var{test} of the last @var{clause} may be the keyword @code{else}.
-Then, if none of the preceding @var{test}s is true, the @var{expression}s following the @code{else} are evaluated to produce the result of the @code{cond}-expression.
-@end deffn
-
-@deffn syntax case key clause1 clause2 @dots{}
-@var{key} may be any expression, the @var{clause}s must have the form
-
-@lisp
-((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
-@end lisp
-
-and the last @var{clause} may have the form
-
-@lisp
-(else @var{expr1} @var{expr2} @dots{})
-@end lisp
-
-All @var{datum}s must be distinct. First, @var{key} is evaluated. The
-the result of this evaluation is compared against all @var{datum}s using
-@code{eqv?}. When this comparison succeeds, the expression(s) following
-the @var{datum} are evaluated from left to right, returning the value of
-the last expression as the result of the @code{case} expression.
-
-If the @var{key} matches no @var{datum} and there is an
-@code{else}-clause, the expressions following the @code{else} are
-evaluated. If there is no such clause, the result of the expression is
-unspecified.
-@end deffn
-
-
-@node and or
-@section Conditional Evaluation of a Sequence of Expressions
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@code{and} and @code{or} evaluate all their arguments, similar to
-@code{begin}, but evaluation stops as soon as one of the expressions
-evaluates to false or true, respectively.
-
-@deffn syntax and expr @dots{}
-Evaluate the @var{expr}s from left to right and stop evaluation as soon
-as one expression evaluates to @code{#f}; the remaining expressions are
-not evaluated. The value of the last evaluated expression is returned.
-If no expression evaluates to @code{#f}, the value of the last
-expression is returned.
-
-If used without expressions, @code{#t} is returned.
-@end deffn
-
-@deffn syntax or expr @dots{}
-Evaluate the @var{expr}s from left to right and stop evaluation as soon
-as one expression evaluates to a true value (that is, a value different
-from @code{#f}); the remaining expressions are not evaluated. The value
-of the last evaluated expression is returned. If all expressions
-evaluate to @code{#f}, @code{#f} is returned.
-
-If used without expressions, @code{#f} is returned.
-@end deffn
-
-
-@node while do
-@section Iteration mechanisms
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Maybe add examples?
-
-@cindex iteration
-@cindex looping
-@cindex named let
-
-Scheme has only few iteration mechanisms, mainly because iteration in
-Scheme programs is normally expressed using recursion. Nevertheless,
-R5RS defines a construct for programming loops, calling @code{do}. In
-addition, Guile has an explicit looping syntax called @code{while}.
-
-@deffn syntax do ((variable1 init1 step1) @dots{}) (test expr @dots{}) command @dots{}
-The @var{init} expressions are evaluated and the @var{variables} are
-bound to their values. Then looping starts with testing the @var{test}
-expression. If @var{test} evaluates to a true value, the @var{expr}
-following the @var{test} are evaluated and the value of the last
-@var{expr} is returned as the value of the @code{do} expression. If
-@var{test} evaluates to false, the @var{command}s are evaluated in
-order, the @var{step}s are evaluated and stored into the @var{variables}
-and the next iteration starts.
-
-Any of the @var{step} expressions may be omitted, so that the
-corresponding variable is not changed during looping.
-@end deffn
-
-@deffn syntax while cond body @dots{}
-Evaluate all expressions in @var{body} in order, as long as @var{cond}
-evaluates to a true value. The @var{cond} expression is tested before
-every iteration, so that the body is not evaluated at all if @var{cond}
-is @code{#f} right from the start.
-@end deffn
-
-@cindex named let
-Another very common way of expressing iteration in Scheme programs is
-the use of the so-called @dfn{named let}.
-
-Named let is a variant of @code{let} which creates a procedure and calls
-it in one step. Because of the newly created procedure, named let is
-more powerful than @code{do}--it can be used for iteration, but also
-for arbitrary recursion.
-
-@deffn syntax let variable bindings body
-For the definition of @var{bindings} see the documentation about
-@code{let} (@pxref{Local Bindings}).
-
-Named @code{let} works as follows:
-
-@itemize @bullet
-@item
-A new procedure which accepts as many arguments as are in @var{bindings}
-is created and bound locally (using @code{let}) to @var{variable}. The
-new procedure's formal argument names are the name of the
-@var{variables}.
-
-@item
-The @var{body} expressions are inserted into the newly created procedure.
-
-@item
-The procedure is called with the @var{init} expressions as the formal
-arguments.
-@end itemize
-
-The next example implements a loop which iterates (by recursion) 1000
-times.
-
-@lisp
-(let lp ((x 1000))
- (if (positive? x)
- (lp (- x 1))
- x))
-@result{}
-0
-@end lisp
-@end deffn
-
-
-@node Continuations
-@section Continuations
-
-@cindex call/cc
-@cindex call-with-current-continuation
-The ability to explicitly capture continuations using
-@code{call-with-current-continuation} (also often called @code{call/cc}
-for short), and to invoke such continuations later any number of times,
-and from any other point in a program, provides maybe the most powerful
-control structure known. All other control structures, such as loops
-and coroutines, can be emulated using continuations.
-
-@c NJFIXME - need a little something here about what continuations are
-@c and what they do for you.
-
-The implementation of continuations in Guile is not as efficient as one
-might hope, because it is constrained by the fact that Guile is designed
-to cooperate with programs written in other languages, such as C, which
-do not know about continuations. So continuations should be used when
-there is no other simple way of achieving the desired behaviour, or
-where the advantages of the elegant continuation mechanism outweigh the
-need for optimum performance. If you find yourself using @code{call/cc}
-for escape procedures and your program is running too slow, you might
-want to use exceptions (@pxref{Exceptions}) instead.
-
-@rnindex call-with-current-continuation
-@deffn {Scheme Procedure} call-with-current-continuation proc
-Capture the current continuation and call @var{proc} with the captured
-continuation as the single argument. This continuation can then be
-called with arbitrarily many arguments. Such a call will work like a
-goto to the invocation location of
-@code{call-with-current-continuation}, passing the arguments in a way
-that they are returned by the call to
-@code{call-with-current-continuation}. Since it is legal to store the
-captured continuation in a variable or to pass it to other procedures,
-it is possible that a procedure returns more than once, even if it is
-called only one time. This can be confusing at times.
-@end deffn
-
-@c FIXME::martin: Better example needed.
-@lisp
-(define kont #f)
-(call-with-current-continuation
- (lambda (k)
- (set! kont k)
- 1))
-@result{}
-1
-
-(kont 2)
-@result{}
-2
-@end lisp
-
-
-@node Multiple Values
-@section Returning and Accepting Multiple Values
-
-@c FIXME::martin: Review me!
-@cindex multiple values
-@cindex receive
-
-Scheme allows a procedure to return more than one value to its caller.
-This is quite different to other languages which only allow
-single-value returns. Returning multiple values is different from
-returning a list (or pair or vector) of values to the caller, because
-conceptually not @emph{one} compound object is returned, but several
-distinct values.
-
-The primitive procedures for handling multiple values are @code{values}
-and @code{call-with-values}. @code{values} is used for returning
-multiple values from a procedure. This is done by placing a call to
-@code{values} with zero or more arguments in tail position in a
-procedure body. @code{call-with-values} combines a procedure returning
-multiple values with a procedure which accepts these values as
-parameters.
-
-@rnindex values
-@deffn {Scheme Procedure} values . args
-@deffnx {C Function} scm_values (args)
-Delivers all of its arguments to its continuation. Except for
-continuations created by the @code{call-with-values} procedure,
-all continuations take exactly one value. The effect of
-passing no value or more than one value to continuations that
-were not created by @code{call-with-values} is unspecified.
-@end deffn
-
-@rnindex call-with-values
-@deffn {Scheme Procedure} call-with-values producer consumer
-Calls its @var{producer} argument with no values and a
-continuation that, when passed some values, calls the
-@var{consumer} procedure with those values as arguments. The
-continuation for the call to @var{consumer} is the continuation
-of the call to @code{call-with-values}.
-
-@example
-(call-with-values (lambda () (values 4 5))
- (lambda (a b) b))
- ==> 5
-
-@end example
-@example
-(call-with-values * -) ==> -1
-@end example
-@end deffn
-
-In addition to the fundamental procedures described above, Guile has a
-module which exports a syntax called @code{receive}, which is much more
-convenient. If you want to use it in your programs, you have to load
-the module @code{(ice-9 receive)} with the statement
-
-@lisp
-(use-modules (ice-9 receive))
-@end lisp
-
-@deffn {library syntax} receive formals expr body @dots{}
-Evaluate the expression @var{expr}, and bind the result values (zero or
-more) to the formal arguments in the formal argument list @var{formals}.
-@var{formals} must have the same syntax like the formal argument list
-used in @code{lambda} (@pxref{Lambda}). After binding the variables,
-the expressions in @var{body} @dots{} are evaluated in order.
-@end deffn
-
-
-@node Exceptions
-@section Exceptions
-@cindex error handling
-@cindex exception handling
-
-A common requirement in applications is to want to jump
-@dfn{non-locally} from the depths of a computation back to, say, the
-application's main processing loop. Usually, the place that is the
-target of the jump is somewhere in the calling stack of procedures that
-called the procedure that wants to jump back. For example, typical
-logic for a key press driven application might look something like this:
-
-@example
-main-loop:
- read the next key press and call dispatch-key
-
-dispatch-key:
- lookup the key in a keymap and call an appropriate procedure,
- say find-file
-
-find-file:
- interactively read the required file name, then call
- find-specified-file
-
-find-specified-file:
- check whether file exists; if not, jump back to main-loop
- @dots{}
-@end example
-
-The jump back to @code{main-loop} could be achieved by returning through
-the stack one procedure at a time, using the return value of each
-procedure to indicate the error condition, but Guile (like most modern
-programming languages) provides an additional mechanism called
-@dfn{exception handling} that can be used to implement such jumps much
-more conveniently.
-
-@menu
-* Exception Terminology:: Different ways to say the same thing.
-* Catch:: Setting up to catch exceptions.
-* Throw:: Throwing an exception.
-* Lazy Catch:: Catch without unwinding the stack.
-* Exception Implementation:: How Guile implements exceptions.
-@end menu
-
-
-@node Exception Terminology
-@subsection Exception Terminology
-
-There are several variations on the terminology for dealing with
-non-local jumps. It is useful to be aware of them, and to realize
-that they all refer to the same basic mechanism.
-
-@itemize @bullet
-@item
-Actually making a non-local jump may be called @dfn{raising an
-exception}, @dfn{raising a signal}, @dfn{throwing an exception} or
-@dfn{doing a long jump}. When the jump indicates an error condition,
-people may talk about @dfn{signalling}, @dfn{raising} or @dfn{throwing}
-@dfn{an error}.
-
-@item
-Handling the jump at its target may be referred to as @dfn{catching} or
-@dfn{handling} the @dfn{exception}, @dfn{signal} or, where an error
-condition is involved, @dfn{error}.
-@end itemize
-
-Where @dfn{signal} and @dfn{signalling} are used, special care is needed
-to avoid the risk of confusion with POSIX signals. (Especially
-considering that Guile handles POSIX signals by throwing a corresponding
-kind of exception: REFFIXME.)
-
-This manual prefers to speak of throwing and catching exceptions, since
-this terminology matches the corresponding Guile primitives.
-
-
-@node Catch
-@subsection Catching Exceptions
-
-@code{catch} is used to set up a target for a possible non-local jump.
-The arguments of a @code{catch} expression are a @dfn{key}, which
-restricts the set of exceptions to which this @code{catch} applies, a
-thunk that specifies the @dfn{normal case} code --- i.e. what should
-happen if no exceptions are thrown --- and a @dfn{handler} procedure
-that says what to do if an exception is thrown. Note that if the
-@dfn{normal case} thunk executes @dfn{normally}, which means without
-throwing any exceptions, the handler procedure is not executed at all.
-
-When an exception is thrown using the @code{throw} primitive, the first
-argument of the @code{throw} is a symbol that indicates the type of the
-exception. For example, Guile throws an exception using the symbol
-@code{numerical-overflow} to indicate numerical overflow errors such as
-division by zero:
-
-@lisp
-(/ 1 0)
-@result{}
-ABORT: (numerical-overflow)
-@end lisp
-
-The @var{key} argument in a @code{catch} expression corresponds to this
-symbol. @var{key} may be a specific symbol, such as
-@code{numerical-overflow}, in which case the @code{catch} applies
-specifically to exceptions of that type; or it may be @code{#t}, which
-means that the @code{catch} applies to all exceptions, irrespective of
-their type.
-
-The second argument of a @code{catch} expression should be a thunk
-(i.e. a procedure that accepts no arguments) that specifies the normal
-case code. The @code{catch} is active for the execution of this thunk,
-including any code called directly or indirectly by the thunk's body.
-Evaluation of the @code{catch} expression activates the catch and then
-calls this thunk.
-
-The third argument of a @code{catch} expression is a handler procedure.
-If an exception is thrown, this procedure is called with exactly the
-arguments specified by the @code{throw}. Therefore, the handler
-procedure must be designed to accept a number of arguments that
-corresponds to the number of arguments in all @code{throw} expressions
-that can be caught by this @code{catch}.
-
-@deffn {Scheme Procedure} catch key thunk handler
-@deffnx {C Function} scm_catch (key, thunk, handler)
-Invoke @var{thunk} in the dynamic context of @var{handler} for
-exceptions matching @var{key}. If thunk throws to the symbol
-@var{key}, then @var{handler} is invoked this way:
-@lisp
-(handler key args ...)
-@end lisp
-
-@var{key} is a symbol or @code{#t}.
-
-@var{thunk} takes no arguments. If @var{thunk} returns
-normally, that is the return value of @code{catch}.
-
-Handler is invoked outside the scope of its own @code{catch}.
-If @var{handler} again throws to the same key, a new handler
-from further up the call chain is invoked.
-
-If the key is @code{#t}, then a throw to @emph{any} symbol will
-match this call to @code{catch}.
-@end deffn
-
-If the handler procedure needs to match a variety of @code{throw}
-expressions with varying numbers of arguments, you should write it like
-this:
-
-@lisp
-(lambda (key . args)
- @dots{})
-@end lisp
-
-@noindent
-The @var{key} argument is guaranteed always to be present, because a
-@code{throw} without a @var{key} is not valid. The number and
-interpretation of the @var{args} varies from one type of exception to
-another, but should be specified by the documentation for each exception
-type.
-
-Note that, once the handler procedure is invoked, the catch that led to
-the handler procedure being called is no longer active. Therefore, if
-the handler procedure itself throws an exception, that exception can
-only be caught by another active catch higher up the call stack, if
-there is one.
-
-
-@node Throw
-@subsection Throwing Exceptions
-
-The @code{throw} primitive is used to throw an exception. One argument,
-the @var{key}, is mandatory, and must be a symbol; it indicates the type
-of exception that is being thrown. Following the @var{key},
-@code{throw} accepts any number of additional arguments, whose meaning
-depends on the exception type. The documentation for each possible type
-of exception should specify the additional arguments that are expected
-for that kind of exception.
-
-@deffn {Scheme Procedure} throw key . args
-@deffnx {C Function} scm_throw (key, args)
-Invoke the catch form matching @var{key}, passing @var{args} to the
-@var{handler}.
-
-@var{key} is a symbol. It will match catches of the same symbol or of
-@code{#t}.
-
-If there is no handler at all, Guile prints an error and then exits.
-@end deffn
-
-When an exception is thrown, it will be caught by the innermost
-@code{catch} expression that applies to the type of the thrown
-exception; in other words, the innermost @code{catch} whose @var{key} is
-@code{#t} or is the same symbol as that used in the @code{throw}
-expression. Once Guile has identified the appropriate @code{catch}, it
-handles the exception by applying that @code{catch} expression's handler
-procedure to the arguments of the @code{throw}.
-
-If there is no appropriate @code{catch} for a thrown exception, Guile
-prints an error to the current error port indicating an uncaught
-exception, and then exits. In practice, it is quite difficult to
-observe this behaviour, because Guile when used interactively installs a
-top level @code{catch} handler that will catch all exceptions and print
-an appropriate error message @emph{without} exiting. For example, this
-is what happens if you try to throw an unhandled exception in the
-standard Guile REPL; note that Guile's command loop continues after the
-error message:
-
-@lisp
-guile> (throw 'badex)
-<unnamed port>:3:1: In procedure gsubr-apply @dots{}
-<unnamed port>:3:1: unhandled-exception: badex
-ABORT: (misc-error)
-guile>
-@end lisp
-
-The default uncaught exception behaviour can be observed by evaluating a
-@code{throw} expression from the shell command line:
-
-@example
-$ guile -c "(begin (throw 'badex) (display \"here\\n\"))"
-guile: uncaught throw to badex: ()
-$
-@end example
-
-@noindent
-That Guile exits immediately following the uncaught exception
-is shown by the absence of any output from the @code{display}
-expression, because Guile never gets to the point of evaluating that
-expression.
-
-
-@node Lazy Catch
-@subsection Catch Without Unwinding
-
-A @dfn{lazy catch} is used in the same way as a normal @code{catch},
-with @var{key}, @var{thunk} and @var{handler} arguments specifying the
-exception type, normal case code and handler procedure, but differs in
-one important respect: the handler procedure is executed without
-unwinding the call stack from the context of the @code{throw} expression
-that caused the handler to be invoked.
-
-@deffn {Scheme Procedure} lazy-catch key thunk handler
-@deffnx {C Function} scm_lazy_catch (key, thunk, handler)
-This behaves exactly like @code{catch}, except that it does
-not unwind the stack before invoking @var{handler}.
-The @var{handler} procedure is not allowed to return:
-it must throw to another catch, or otherwise exit non-locally.
-@end deffn
-
-Typically, @var{handler} should save any desired state associated with
-the stack at the point where the corresponding @code{throw} occurred,
-and then throw an exception itself --- usually the same exception as the
-one it caught. If @var{handler} is invoked and does @emph{not} throw an
-exception, Guile itself throws an exception with key @code{misc-error}.
-
-Not unwinding the stack means that throwing an exception that is caught
-by a @code{lazy-catch} is @emph{almost} equivalent to calling the
-@code{lazy-catch}'s handler inline instead of each @code{throw}, and
-then omitting the surrounding @code{lazy-catch}. In other words,
-
-@lisp
-(lazy-catch 'key
- (lambda () @dots{} (throw 'key args @dots{}) @dots{})
- handler)
-@end lisp
-
-@noindent
-is @emph{almost} equivalent to
-
-@lisp
-((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
-@end lisp
-
-@noindent
-But why only @emph{almost}? The difference is that with
-@code{lazy-catch} (as with normal @code{catch}), the dynamic context is
-unwound back to just outside the @code{lazy-catch} expression before
-invoking the handler. (For an introduction to what is meant by dynamic
-context, @xref{Dynamic Wind}.)
-
-Then, when the handler @emph{itself} throws an exception, that exception
-must be caught by some kind of @code{catch} (including perhaps another
-@code{lazy-catch}) higher up the call stack.
-
-The dynamic context also includes @code{with-fluids} blocks (REFFIXME),
-so the effect of unwinding the dynamic context can also be seen in fluid
-variable values. This is illustrated by the following code, in which
-the normal case thunk uses @code{with-fluids} to temporarily change the
-value of a fluid:
-
-@lisp
-(define f (make-fluid))
-(fluid-set! f "top level value")
-
-(define (handler . args)
- (cons (fluid-ref f) args))
-
-(lazy-catch 'foo
- (lambda ()
- (with-fluids ((f "local value"))
- (throw 'foo)))
- handler)
-@result{}
-("top level value" foo)
-
-((lambda ()
- (with-fluids ((f "local value"))
- (handler 'foo))))
-@result{}
-("local value" foo)
-@end lisp
-
-@noindent
-In the @code{lazy-catch} version, the unwinding of dynamic context
-restores @code{f} to its value outside the @code{with-fluids} block
-before the handler is invoked, so the handler's @code{(fluid-ref f)}
-returns the external value.
-
-@code{lazy-catch} is useful because it permits the implementation of
-debuggers and other reflective programming tools that need to access the
-state of the call stack at the exact point where an exception or an
-error is thrown. For an example of this, see REFFIXME:stack-catch.
-
-
-@node Exception Implementation
-@subsection How Guile Implements Exceptions
-
-It is traditional in Scheme to implement exception systems using
-@code{call-with-current-continuation}. Continuations
-(@pxref{Continuations}) are such a powerful concept that any other
-control mechanism --- including @code{catch} and @code{throw} --- can be
-implemented in terms of them.
-
-Guile does not implement @code{catch} and @code{throw} like this,
-though. Why not? Because Guile is specifically designed to be easy to
-integrate with applications written in C. In a mixed Scheme/C
-environment, the concept of @dfn{continuation} must logically include
-``what happens next'' in the C parts of the application as well as the
-Scheme parts, and it turns out that the only reasonable way of
-implementing continuations like this is to save and restore the complete
-C stack.
-
-So Guile's implementation of @code{call-with-current-continuation} is a
-stack copying one. This allows it to interact well with ordinary C
-code, but means that creating and calling a continuation is slowed down
-by the time that it takes to copy the C stack.
-
-The more targeted mechanism provided by @code{catch} and @code{throw}
-does not need to save and restore the C stack because the @code{throw}
-always jumps to a location higher up the stack of the code that executes
-the @code{throw}. Therefore Guile implements the @code{catch} and
-@code{throw} primitives independently of
-@code{call-with-current-continuation}, in a way that takes advantage of
-this @emph{upwards only} nature of exceptions.
-
-
-@node Error Reporting
-@section Procedures for Signaling Errors
-
-Guile provides a set of convenience procedures for signaling error
-conditions that are implemented on top of the exception primitives just
-described.
-
-@deffn {Scheme Procedure} error msg args @dots{}
-Raise an error with key @code{misc-error} and a message constructed by
-displaying @var{msg} and writing @var{args}.
-@end deffn
-
-@deffn {Scheme Procedure} scm-error key subr message args data
-@deffnx {C Function} scm_error_scm (key, subr, message, args, data)
-Raise an error with key @var{key}. @var{subr} can be a string
-naming the procedure associated with the error, or @code{#f}.
-@var{message} is the error message string, possibly containing
-@code{~S} and @code{~A} escapes. When an error is reported,
-these are replaced by formatting the corresponding members of
-@var{args}: @code{~A} (was @code{%s} in older versions of
-Guile) formats using @code{display} and @code{~S} (was
-@code{%S}) formats using @code{write}. @var{data} is a list or
-@code{#f} depending on @var{key}: if @var{key} is
-@code{system-error} then it should be a list containing the
-Unix @code{errno} value; If @var{key} is @code{signal} then it
-should be a list containing the Unix signal number; otherwise
-it will usually be @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} strerror err
-@deffnx {C Function} scm_strerror (err)
-Return the Unix error message corresponding to @var{err}, which
-must be an integer value.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "false-if-exception")
-@deffn syntax false-if-exception expr
-Returns the result of evaluating its argument; however
-if an exception occurs then @code{#f} is returned instead.
-@end deffn
-@c end
-
-
-@node Dynamic Wind
-@section Dynamic Wind
-
-[FIXME: this is pasted in from Tom Lord's original guile.texi and should
-be reviewed]
-
-@rnindex dynamic-wind
-@deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
-@deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
-All three arguments must be 0-argument procedures.
-@var{in_guard} is called, then @var{thunk}, then
-@var{out_guard}.
-
-If, any time during the execution of @var{thunk}, the
-continuation of the @code{dynamic_wind} expression is escaped
-non-locally, @var{out_guard} is called. If the continuation of
-the dynamic-wind is re-entered, @var{in_guard} is called. Thus
-@var{in_guard} and @var{out_guard} may be called any number of
-times.
-@lisp
-(define x 'normal-binding)
-@result{} x
-(define a-cont (call-with-current-continuation
- (lambda (escape)
- (let ((old-x x))
- (dynamic-wind
- ;; in-guard:
- ;;
- (lambda () (set! x 'special-binding))
-
- ;; thunk
- ;;
- (lambda () (display x) (newline)
- (call-with-current-continuation escape)
- (display x) (newline)
- x)
-
- ;; out-guard:
- ;;
- (lambda () (set! x old-x)))))))
-
-;; Prints:
-special-binding
-;; Evaluates to:
-@result{} a-cont
-x
-@result{} normal-binding
-(a-cont #f)
-;; Prints:
-special-binding
-;; Evaluates to:
-@result{} a-cont ;; the value of the (define a-cont...)
-x
-@result{} normal-binding
-a-cont
-@result{} special-binding
-@end lisp
-@end deffn
-
-
-@node Handling Errors
-@section How to Handle Errors in C Code
-
-Error handling is based on @code{catch} and @code{throw}. Errors are
-always thrown with a @var{key} and four arguments:
-
-@itemize @bullet
-@item
-@var{key}: a symbol which indicates the type of error. The symbols used
-by libguile are listed below.
-
-@item
-@var{subr}: the name of the procedure from which the error is thrown, or
-@code{#f}.
-
-@item
-@var{message}: a string (possibly language and system dependent)
-describing the error. The tokens @code{~A} and @code{~S} can be
-embedded within the message: they will be replaced with members of the
-@var{args} list when the message is printed. @code{~A} indicates an
-argument printed using @code{display}, while @code{~S} indicates an
-argument printed using @code{write}. @var{message} can also be
-@code{#f}, to allow it to be derived from the @var{key} by the error
-handler (may be useful if the @var{key} is to be thrown from both C and
-Scheme).
-
-@item
-@var{args}: a list of arguments to be used to expand @code{~A} and
-@code{~S} tokens in @var{message}. Can also be @code{#f} if no
-arguments are required.
-
-@item
-@var{rest}: a list of any additional objects required. e.g., when the
-key is @code{'system-error}, this contains the C errno value. Can also
-be @code{#f} if no additional objects are required.
-@end itemize
-
-In addition to @code{catch} and @code{throw}, the following Scheme
-facilities are available:
-
-@deffn {Scheme Procedure} scm-error key subr message args rest
-Throw an error, with arguments
-as described above.
-@end deffn
-
-@deffn {Scheme Procedure} error msg arg @dots{}
-Throw an error using the key @code{'misc-error}. The error
-message is created by displaying @var{msg} and writing the @var{args}.
-@end deffn
-
-@deffn {Scheme Procedure} display-error stack port subr message args rest
-@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
-Display an error message to the output port @var{port}.
-@var{stack} is the saved stack for the error, @var{subr} is
-the name of the procedure in which the error occurred and
-@var{message} is the actual error message, which may contain
-formatting instructions. These will format the arguments in
-the list @var{args} accordingly. @var{rest} is currently
-ignored.
-@end deffn
-
-The following are the error keys defined by libguile and the situations
-in which they are used:
-
-@itemize @bullet
-@item
-@code{error-signal}: thrown after receiving an unhandled fatal signal
-such as SIGSEGV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw
-contains the coded signal number (at present this is not the same as the
-usual Unix signal number).
-
-@item
-@code{system-error}: thrown after the operating system indicates an
-error condition. The @var{rest} argument in the throw contains the
-errno value.
-
-@item
-@code{numerical-overflow}: numerical overflow.
-
-@item
-@code{out-of-range}: the arguments to a procedure do not fall within the
-accepted domain.
-
-@item
-@code{wrong-type-arg}: an argument to a procedure has the wrong type.
-
-@item
-@code{wrong-number-of-args}: a procedure was called with the wrong number
-of arguments.
-
-@item
-@code{memory-allocation-error}: memory allocation error.
-
-@item
-@code{stack-overflow}: stack overflow error.
-
-@item
-@code{regex-error}: errors generated by the regular expression library.
-
-@item
-@code{misc-error}: other errors.
-@end itemize
-
-
-@subsection C Support
-
-SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
-
-Throws an error, after converting the char * arguments to Scheme strings.
-subr is the Scheme name of the procedure, NULL is converted to #f.
-Likewise a NULL message is converted to #f.
-
-The following procedures invoke scm_error with various error keys and
-arguments. The first three call scm_error with the system-error key
-and automatically supply errno in the "rest" argument: scm_syserror
-generates messages using strerror, scm_sysmissing is used when
-facilities are not available. Care should be taken that the errno
-value is not reset (e.g. due to an interrupt).
-
-@itemize @bullet
-@item
-void scm_syserror (char *subr);
-@item
-void scm_syserror_msg (char *subr, char *message, SCM args);
-@item
-void scm_sysmissing (char *subr);
-@item
-void scm_num_overflow (char *subr);
-@item
-void scm_out_of_range (char *subr, SCM bad_value);
-@item
-void scm_wrong_num_args (SCM proc);
-@item
-void scm_wrong_type_arg (char *subr, int pos, SCM bad_value);
-@item
-void scm_memory_error (char *subr);
-@item
-static void scm_regex_error (char *subr, int code); (only used in rgx.c).
-@end itemize
-
-Exception handlers can also be installed from C, using
-scm_internal_catch, scm_lazy_catch, or scm_stack_catch from
-libguile/throw.c. These have not yet been documented, however the
-source contains some useful comments.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
deleted file mode 100755
index fc4a84afd..000000000
--- a/doc/ref/scheme-data.texi
+++ /dev/null
@@ -1,3086 +0,0 @@
-@page
-@node Simple Data Types
-@chapter Simple Generic Data Types
-
-This chapter describes those of Guile's simple data types which are
-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
-@ref{Compound Data Types}.
-
-One of the great strengths of Scheme is that there is no straightforward
-distinction between ``data'' and ``functionality''. For example,
-Guile's support for dynamic linking could be described
-
-@itemize @bullet
-@item
-either in a ``data-centric'' way, as the behaviour and properties of the
-``dynamically linked object'' data type, and the operations that may be
-applied to instances of this type
-
-@item
-or in a ``functionality-centric'' way, as the set of procedures that
-constitute Guile's support for dynamic linking, in the context of the
-module system.
-@end itemize
-
-The contents of this chapter are, therefore, a matter of judgment. By
-@dfn{generic}, we mean to select those data types whose typical use as
-@emph{data} in a wide variety of programming contexts is more important
-than their use in the implementation of a particular piece of
-@emph{functionality}. The last section of this chapter provides
-references for all the data types that are documented not here but in a
-``functionality-centric'' way elsewhere in the manual.
-
-@menu
-* Booleans:: True/false values.
-* Numbers:: Numerical data types.
-* Characters:: New character names.
-* Strings:: Special things about strings.
-* Regular Expressions:: Pattern matching and substitution.
-* Symbols:: Symbols.
-* Keywords:: Self-quoting, customizable display keywords.
-* Other Types:: "Functionality-centric" data types.
-@end menu
-
-
-@node Booleans
-@section Booleans
-@tpindex Booleans
-
-The two boolean values are @code{#t} for true and @code{#f} for false.
-
-Boolean values are returned by predicate procedures, such as the general
-equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
-(@pxref{Equality}) and numerical and string comparison operators like
-@code{string=?} (@pxref{String Comparison}) and @code{<=}
-(@pxref{Comparison}).
-
-@lisp
-(<= 3 8)
-@result{}
-#t
-
-(<= 3 -3)
-@result{}
-#f
-
-(equal? "house" "houses")
-@result{}
-#f
-
-(eq? #f #f)
-@result{}
-#t
-@end lisp
-
-In test condition contexts like @code{if} and @code{cond} (@pxref{if
-cond case}), where a group of subexpressions will be evaluated only if a
-@var{condition} expression evaluates to ``true'', ``true'' means any
-value at all except @code{#f}.
-
-@lisp
-(if #t "yes" "no")
-@result{}
-"yes"
-
-(if 0 "yes" "no")
-@result{}
-"yes"
-
-(if #f "yes" "no")
-@result{}
-"no"
-@end lisp
-
-A result of this asymmetry is that typical Scheme source code more often
-uses @code{#f} explicitly than @code{#t}: @code{#f} is necessary to
-represent an @code{if} or @code{cond} false value, whereas @code{#t} is
-not necessary to represent an @code{if} or @code{cond} true value.
-
-It is important to note that @code{#f} is @strong{not} equivalent to any
-other Scheme value. In particular, @code{#f} is not the same as the
-number 0 (like in C and C++), and not the same as the ``empty list''
-(like in some Lisp dialects).
-
-The @code{not} procedure returns the boolean inverse of its argument:
-
-@rnindex not
-@deffn {Scheme Procedure} not x
-@deffnx {C Function} scm_not (x)
-Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}.
-@end deffn
-
-The @code{boolean?} procedure is a predicate that returns @code{#t} if
-its argument is one of the boolean values, otherwise @code{#f}.
-
-@rnindex boolean?
-@deffn {Scheme Procedure} boolean? obj
-@deffnx {C Function} scm_boolean_p (obj)
-Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}.
-@end deffn
-
-
-@node Numbers
-@section Numerical data types
-@tpindex Numbers
-
-Guile supports a rich ``tower'' of numerical types --- integer,
-rational, real and complex --- and provides an extensive set of
-mathematical and scientific functions for operating on numerical
-data. This section of the manual documents those types and functions.
-
-You may also find it illuminating to read R5RS's presentation of numbers
-in Scheme, which is particularly clear and accessible: see
-@xref{Numbers,,,r5rs}.
-
-@menu
-* Numerical Tower:: Scheme's numerical "tower".
-* Integers:: Whole numbers.
-* Reals and Rationals:: Real and rational numbers.
-* Complex Numbers:: Complex numbers.
-* Exactness:: Exactness and inexactness.
-* Number Syntax:: Read syntax for numerical data.
-* Integer Operations:: Operations on integer values.
-* Comparison:: Comparison predicates.
-* Conversion:: Converting numbers to and from strings.
-* Complex:: Complex number operations.
-* Arithmetic:: Arithmetic functions.
-* Scientific:: Scientific functions.
-* Primitive Numerics:: Primitive numeric functions.
-* Bitwise Operations:: Logical AND, OR, NOT, and so on.
-* Random:: Random number generation.
-@end menu
-
-
-@node Numerical Tower
-@subsection Scheme's Numerical ``Tower''
-@rnindex number?
-
-Scheme's numerical ``tower'' consists of the following categories of
-numbers:
-
-@itemize @bullet
-@item
-integers (whole numbers)
-
-@item
-rationals (the set of numbers that can be expressed as P/Q where P and Q
-are integers)
-
-@item
-real numbers (the set of numbers that describes all possible positions
-along a one dimensional line)
-
-@item
-complex numbers (the set of numbers that describes all possible
-positions in a two dimensional space)
-@end itemize
-
-It is called a tower because each category ``sits on'' the one that
-follows it, in the sense that every integer is also a rational, every
-rational is also real, and every real number is also a complex number
-(but with zero imaginary part).
-
-Of these, Guile implements integers, reals and complex numbers as
-distinct types. Rationals are implemented as regards the read syntax
-for rational numbers that is specified by R5RS, but are immediately
-converted by Guile to the corresponding real number.
-
-The @code{number?} predicate may be applied to any Scheme value to
-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, else @code{#f}.
-@end deffn
-
-For example:
-
-@lisp
-(number? 3)
-@result{}
-#t
-
-(number? "hello there!")
-@result{}
-#f
-
-(define pi 3.141592654)
-(number? pi)
-@result{}
-#t
-@end lisp
-
-The next few subsections document each of Guile's numerical data types
-in detail.
-
-@node Integers
-@subsection Integers
-
-@tpindex Integer numbers
-
-@rnindex integer?
-
-Integers are whole numbers, that is numbers with no fractional part,
-such as 2, 83 and -3789.
-
-Integers in Guile can be arbitrarily big, as shown by the following
-example.
-
-@lisp
-(define (factorial n)
- (let loop ((n n) (product 1))
- (if (= n 0)
- product
- (loop (- n 1) (* product n)))))
-
-(factorial 3)
-@result{}
-6
-
-(factorial 20)
-@result{}
-2432902008176640000
-
-(- (factorial 45))
-@result{}
--119622220865480194561963161495657715064383733760000000000
-@end lisp
-
-Readers whose background is in programming languages where integers are
-limited by the need to fit into just 4 or 8 bytes of memory may find
-this surprising, or suspect that Guile's representation of integers is
-inefficient. In fact, Guile achieves a near optimal balance of
-convenience and efficiency by using the host computer's native
-representation of integers where possible, and a more general
-representation where the required number does not fit in the native
-form. Conversion between these two representations is automatic and
-completely invisible to the Scheme level programmer.
-
-The infinities @code{+inf.0} and @code{-inf.0} are considered to be
-inexact integers. They are explained in detail in the next section,
-together with reals and rationals.
-
-@c REFFIXME Maybe point here to discussion of handling immediates/bignums
-@c on the C level, where the conversion is not so automatic - NJ
-
-@deffn {Scheme Procedure} integer? x
-@deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an integer number, else @code{#f}.
-
-@lisp
-(integer? 487)
-@result{}
-#t
-
-(integer? -3.4)
-@result{}
-#f
-
-(integer? +inf.0)
-@result{}
-#t
-@end lisp
-@end deffn
-
-
-@node Reals and Rationals
-@subsection Real and Rational Numbers
-@tpindex Real numbers
-@tpindex Rational numbers
-
-@rnindex real?
-@rnindex rational?
-
-Mathematically, the real numbers are the set of numbers that describe
-all possible points along a continuous, infinite, one-dimensional line.
-The rational numbers are the set of all numbers that can be written as
-fractions P/Q, where P and Q are integers. All rational numbers are
-also real, but there are real numbers that are not rational, for example
-the square root of 2, and pi.
-
-Guile represents both real and rational numbers approximately using a
-floating point encoding with limited precision. Even though the actual
-encoding is in binary, it may be helpful to think of it as a decimal
-number with a limited number of significant figures and a decimal point
-somewhere, since this corresponds to the standard notation for non-whole
-numbers. For example:
-
-@lisp
-0.34
--0.00000142857931198
--5648394822220000000000.0
-4.0
-@end lisp
-
-The limited precision of Guile's encoding means that any ``real'' number
-in Guile can be written in a rational form, by multiplying and then dividing
-by sufficient powers of 10 (or in fact, 2). For example,
-@code{-0.00000142857931198} is the same as @code{142857931198} divided by
-@code{100000000000000000}. In Guile's current incarnation, therefore,
-the @code{rational?} and @code{real?} predicates are equivalent.
-
-Another aspect of this equivalence is that Guile currently does not
-preserve the exactness that is possible with rational arithmetic.
-If such exactness is needed, it is of course possible to implement
-exact rational arithmetic at the Scheme level using Guile's arbitrary
-size integers.
-
-A planned future revision of Guile's numerical tower will make it
-possible to implement exact representations and arithmetic for both
-rational numbers and real irrational numbers such as square roots,
-and in such a way that the new kinds of number integrate seamlessly
-with those that are already implemented.
-
-Dividing by an exact zero leads to a error message, as one might
-expect. However, dividing by an inexact zero does not produce an
-error. Instead, the result of the division is either plus or minus
-infinity, depending on the sign of the divided number.
-
-The infinities are written @samp{+inf.0} and @samp{-inf.0},
-respectibly. This syntax is also recognized by @code{read} as an
-extension to the usual Scheme syntax.
-
-Dividing zero by zero yields something that is not a number at all:
-@samp{+nan.0}. This is the special 'not a number' value.
-
-On platforms that follow IEEE 754 for their floating point arithmetic,
-the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values are
-implemented using the corresponding IEEE 754 values. They behave in
-arithmetic operations like IEEE 754 describes it, i.e., @code{(=
-+nan.0 +nan.0) @result{#f}}.
-
-The infinities are inexact integers and are considered to be both even
-and odd. While @samp{+nan.0} is not @code{=} to itself, it is
-@code{eqv?} to itself.
-
-To test for the special values, use the functions @code{inf?} and
-@code{nan?}.
-
-@deffn {Scheme Procedure} real? obj
-@deffnx {C Function} scm_real_p (obj)
-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.
-@end deffn
-
-@deffn {Scheme Procedure} rational? x
-@deffnx {C Function} scm_real_p (x)
-Return @code{#t} if @var{x} is a rational number, @code{#f}
-otherwise. Note that the set of integer values forms a subset of
-the set of rational numbers, i. e. the predicate will also be
-fulfilled if @var{x} is an integer number. Real numbers
-will also satisfy this predicate, because of their limited
-precision.
-@end deffn
-
-@deffn {Scheme Procedure} inf? x
-Return @code{#t} if @var{x} is either @samp{+inf.0} or @samp{-inf.0},
-@code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} nan? x
-Return @code{#t} if @var{x} is @samp{+nan.0}, @code{#f} otherwise.
-@end deffn
-
-@node Complex Numbers
-@subsection Complex Numbers
-@tpindex Complex numbers
-
-@rnindex complex?
-
-Complex numbers are the set of numbers that describe all possible points
-in a two-dimensional space. The two coordinates of a particular point
-in this space are known as the @dfn{real} and @dfn{imaginary} parts of
-the complex number that describes that point.
-
-In Guile, complex numbers are written in rectangular form as the sum of
-their real and imaginary parts, using the symbol @code{i} to indicate
-the imaginary part.
-
-@lisp
-3+4i
-@result{}
-3.0+4.0i
-
-(* 3-8i 2.3+0.3i)
-@result{}
-9.3-17.5i
-@end lisp
-
-Guile represents a complex number as a pair of numbers both of which are
-real, so the real and imaginary parts of a complex number have the same
-properties of inexactness and limited precision as single real numbers.
-
-@deffn {Scheme Procedure} complex? x
-@deffnx {C Function} scm_number_p (x)
-Return @code{#t} if @var{x} is a complex number, @code{#f}
-otherwise. Note that the sets of real, rational and integer
-values form subsets of the set of complex numbers, i. e. the
-predicate will also be fulfilled if @var{x} is a real,
-rational or integer number.
-@end deffn
-
-
-@node Exactness
-@subsection Exact and Inexact Numbers
-@tpindex Exact numbers
-@tpindex Inexact numbers
-
-@rnindex exact?
-@rnindex inexact?
-@rnindex exact->inexact
-@rnindex inexact->exact
-
-R5RS requires that a calculation involving inexact numbers always
-produces an inexact result. To meet this requirement, Guile
-distinguishes between an exact integer value such as @code{5} and the
-corresponding inexact real value which, to the limited precision
-available, has no fractional part, and is printed as @code{5.0}. Guile
-will only convert the latter value to the former when forced to do so by
-an invocation of the @code{inexact->exact} procedure.
-
-@deffn {Scheme Procedure} exact? x
-@deffnx {C Function} scm_exact_p (x)
-Return @code{#t} if @var{x} is an exact number, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} inexact? x
-@deffnx {C Function} scm_inexact_p (x)
-Return @code{#t} if @var{x} is an inexact number, @code{#f}
-else.
-@end deffn
-
-@deffn {Scheme Procedure} inexact->exact z
-@deffnx {C Function} scm_inexact_to_exact (z)
-Return an exact number that is numerically closest to @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "exact->inexact")
-@deffn {Scheme Procedure} exact->inexact z
-Convert the number @var{z} to its inexact representation.
-@end deffn
-
-
-@node Number Syntax
-@subsection Read Syntax for Numerical Data
-
-The read syntax for integers is a string of digits, optionally
-preceded by a minus or plus character, a code indicating the
-base in which the integer is encoded, and a code indicating whether
-the number is exact or inexact. The supported base codes are:
-
-@itemize @bullet
-@item
-@code{#b}, @code{#B} --- the integer is written in binary (base 2)
-
-@item
-@code{#o}, @code{#O} --- the integer is written in octal (base 8)
-
-@item
-@code{#d}, @code{#D} --- the integer is written in decimal (base 10)
-
-@item
-@code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16).
-@end itemize
-
-If the base code is omitted, the integer is assumed to be decimal. The
-following examples show how these base codes are used.
-
-@lisp
--13
-@result{}
--13
-
-#d-13
-@result{}
--13
-
-#x-13
-@result{}
--19
-
-#b+1101
-@result{}
-13
-
-#o377
-@result{}
-255
-@end lisp
-
-The codes for indicating exactness (which can, incidentally, be applied
-to all numerical values) are:
-
-@itemize @bullet
-@item
-@code{#e}, @code{#E} --- the number is exact
-
-@item
-@code{#i}, @code{#I} --- the number is inexact.
-@end itemize
-
-If the exactness indicator is omitted, the integer is assumed to be exact,
-since Guile's internal representation for integers is always exact.
-Real numbers have limited precision similar to the precision of the
-@code{double} type in C. A consequence of the limited precision is that
-all real numbers in Guile are also rational, since any number R with a
-limited number of decimal places, say N, can be made into an integer by
-multiplying by 10^N.
-
-Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
-plus and minus infinity, respectively. The value must be written
-exactly as shown, that is, the always must have a sign and exactly one
-zero digit after the decimal point. It also understands @samp{+nan.0}
-and @samp{-nan.0} for the special 'not-a-number' value. The sign is
-ignored for 'not-a-number' and the value is always printed as @samp{+nan.0}.
-
-@node Integer Operations
-@subsection Operations on Integer Values
-@rnindex odd?
-@rnindex even?
-@rnindex quotient
-@rnindex remainder
-@rnindex modulo
-@rnindex gcd
-@rnindex lcm
-
-@deffn {Scheme Procedure} odd? n
-@deffnx {C Function} scm_odd_p (n)
-Return @code{#t} if @var{n} is an odd number, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} even? n
-@deffnx {C Function} scm_even_p (n)
-Return @code{#t} if @var{n} is an even number, @code{#f}
-otherwise.
-@end deffn
-
-@c begin (texi-doc-string "guile" "quotient")
-@deffn {Scheme Procedure} quotient
-Return the quotient of the numbers @var{x} and @var{y}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "remainder")
-@deffn {Scheme Procedure} remainder
-Return the remainder of the numbers @var{x} and @var{y}.
-@lisp
-(remainder 13 4) @result{} 1
-(remainder -13 4) @result{} -1
-@end lisp
-@end deffn
-
-@c begin (texi-doc-string "guile" "modulo")
-@deffn {Scheme Procedure} modulo
-Return the modulo of the numbers @var{x} and @var{y}.
-@lisp
-(modulo 13 4) @result{} 1
-(modulo -13 4) @result{} 3
-@end lisp
-@end deffn
-
-@c begin (texi-doc-string "guile" "gcd")
-@deffn {Scheme Procedure} gcd
-Return the greatest common divisor of all arguments.
-If called without arguments, 0 is returned.
-@end deffn
-
-@c begin (texi-doc-string "guile" "lcm")
-@deffn {Scheme Procedure} lcm
-Return the least common multiple of the arguments.
-If called without arguments, 1 is returned.
-@end deffn
-
-
-@node Comparison
-@subsection Comparison Predicates
-@rnindex zero?
-@rnindex positive?
-@rnindex negative?
-
-@c begin (texi-doc-string "guile" "=")
-@deffn {Scheme Procedure} =
-Return @code{#t} if all parameters are numerically equal.
-@end deffn
-
-@c begin (texi-doc-string "guile" "<")
-@deffn {Scheme Procedure} <
-Return @code{#t} if the list of parameters is monotonically
-increasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" ">")
-@deffn {Scheme Procedure} >
-Return @code{#t} if the list of parameters is monotonically
-decreasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" "<=")
-@deffn {Scheme Procedure} <=
-Return @code{#t} if the list of parameters is monotonically
-non-decreasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" ">=")
-@deffn {Scheme Procedure} >=
-Return @code{#t} if the list of parameters is monotonically
-non-increasing.
-@end deffn
-
-@c begin (texi-doc-string "guile" "zero?")
-@deffn {Scheme Procedure} zero?
-Return @code{#t} if @var{z} is an exact or inexact number equal to
-zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "positive?")
-@deffn {Scheme Procedure} positive?
-Return @code{#t} if @var{x} is an exact or inexact number greater than
-zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "negative?")
-@deffn {Scheme Procedure} negative?
-Return @code{#t} if @var{x} is an exact or inexact number less than
-zero.
-@end deffn
-
-
-@node Conversion
-@subsection Converting Numbers To and From Strings
-@rnindex number->string
-@rnindex string->number
-
-@deffn {Scheme Procedure} number->string n [radix]
-@deffnx {C Function} scm_number_to_string (n, radix)
-Return a string holding the external representation of the
-number @var{n} in the given @var{radix}. If @var{n} is
-inexact, a radix of 10 will be used.
-@end deffn
-
-@deffn {Scheme Procedure} string->number string [radix]
-@deffnx {C Function} scm_string_to_number (string, radix)
-Return a number of the maximally precise representation
-expressed by the given @var{string}. @var{radix} must be an
-exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
-is a default radix that may be overridden by an explicit radix
-prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
-supplied, then the default radix is 10. If string is not a
-syntactically valid notation for a number, then
-@code{string->number} returns @code{#f}.
-@end deffn
-
-
-@node Complex
-@subsection Complex Number Operations
-@rnindex make-rectangular
-@rnindex make-polar
-@rnindex real-part
-@rnindex imag-part
-@rnindex magnitude
-@rnindex angle
-
-@deffn {Scheme Procedure} make-rectangular real imaginary
-@deffnx {C Function} scm_make_rectangular (real, imaginary)
-Return a complex number constructed of the given @var{real} and
-@var{imaginary} parts.
-@end deffn
-
-@deffn {Scheme Procedure} make-polar x y
-@deffnx {C Function} scm_make_polar (x, y)
-Return the complex number @var{x} * e^(i * @var{y}).
-@end deffn
-
-@c begin (texi-doc-string "guile" "real-part")
-@deffn {Scheme Procedure} real-part
-Return the real part of the number @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "imag-part")
-@deffn {Scheme Procedure} imag-part
-Return the imaginary part of the number @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "magnitude")
-@deffn {Scheme Procedure} magnitude
-Return the magnitude of the number @var{z}. This is the same as
-@code{abs} for real arguments, but also allows complex numbers.
-@end deffn
-
-@c begin (texi-doc-string "guile" "angle")
-@deffn {Scheme Procedure} angle
-Return the angle of the complex number @var{z}.
-@end deffn
-
-
-@node Arithmetic
-@subsection Arithmetic Functions
-@rnindex max
-@rnindex min
-@rnindex +
-@rnindex *
-@rnindex -
-@rnindex /
-@rnindex abs
-@rnindex floor
-@rnindex ceiling
-@rnindex truncate
-@rnindex round
-
-@c begin (texi-doc-string "guile" "+")
-@deffn {Scheme Procedure} + z1 @dots{}
-Return the sum of all parameter values. Return 0 if called without any
-parameters.
-@end deffn
-
-@c begin (texi-doc-string "guile" "-")
-@deffn {Scheme Procedure} - z1 z2 @dots{}
-If called with one argument @var{z1}, -@var{z1} is returned. Otherwise
-the sum of all but the first argument are subtracted from the first
-argument.
-@end deffn
-
-@c begin (texi-doc-string "guile" "*")
-@deffn {Scheme Procedure} * z1 @dots{}
-Return the product of all arguments. If called without arguments, 1 is
-returned.
-@end deffn
-
-@c begin (texi-doc-string "guile" "/")
-@deffn {Scheme Procedure} / z1 z2 @dots{}
-Divide the first argument by the product of the remaining arguments. If
-called with one argument @var{z1}, 1/@var{z1} is returned.
-@end deffn
-
-@c begin (texi-doc-string "guile" "abs")
-@deffn {Scheme Procedure} abs x
-@deffnx {C Function} scm_abs (x)
-Return the absolute value of @var{x}.
-
-@var{x} must be a number with zero imaginary part. To calculate the
-magnitude of a complex number, use @code{magnitude} instead.
-@end deffn
-
-@c begin (texi-doc-string "guile" "max")
-@deffn {Scheme Procedure} max x1 x2 @dots{}
-Return the maximum of all parameter values.
-@end deffn
-
-@c begin (texi-doc-string "guile" "min")
-@deffn {Scheme Procedure} min x1 x2 @dots{}
-Return the minimum of all parameter values.
-@end deffn
-
-@c begin (texi-doc-string "guile" "truncate")
-@deffn {Scheme Procedure} truncate
-Round the inexact number @var{x} towards zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "round")
-@deffn {Scheme Procedure} round x
-Round the inexact number @var{x} towards zero.
-@end deffn
-
-@c begin (texi-doc-string "guile" "floor")
-@deffn {Scheme Procedure} floor x
-Round the number @var{x} towards minus infinity.
-@end deffn
-
-@c begin (texi-doc-string "guile" "ceiling")
-@deffn {Scheme Procedure} ceiling x
-Round the number @var{x} towards infinity.
-@end deffn
-
-For the @code{truncate} and @code{round} procedures, the Guile library
-exports equivalent C functions, but taking and returning arguments of
-type @code{double} rather than the usual @code{SCM}.
-
-@deftypefn {C Function} double scm_truncate (double x)
-@deftypefnx {C Function} double scm_round (double x)
-@end deftypefn
-
-For @code{floor} and @code{ceiling}, the equivalent C functions are
-@code{floor} and @code{ceil} from the standard mathematics library
-(which also take and return @code{double} arguments).
-
-
-@node Scientific
-@subsection Scientific Functions
-
-The following procedures accept any kind of number as arguments,
-including complex numbers.
-
-@rnindex sqrt
-@c begin (texi-doc-string "guile" "sqrt")
-@deffn {Scheme Procedure} sqrt z
-Return the square root of @var{z}.
-@end deffn
-
-@rnindex expt
-@c begin (texi-doc-string "guile" "expt")
-@deffn {Scheme Procedure} expt z1 z2
-Return @var{z1} raised to the power of @var{z2}.
-@end deffn
-
-@rnindex sin
-@c begin (texi-doc-string "guile" "sin")
-@deffn {Scheme Procedure} sin z
-Return the sine of @var{z}.
-@end deffn
-
-@rnindex cos
-@c begin (texi-doc-string "guile" "cos")
-@deffn {Scheme Procedure} cos z
-Return the cosine of @var{z}.
-@end deffn
-
-@rnindex tan
-@c begin (texi-doc-string "guile" "tan")
-@deffn {Scheme Procedure} tan z
-Return the tangent of @var{z}.
-@end deffn
-
-@rnindex asin
-@c begin (texi-doc-string "guile" "asin")
-@deffn {Scheme Procedure} asin z
-Return the arcsine of @var{z}.
-@end deffn
-
-@rnindex acos
-@c begin (texi-doc-string "guile" "acos")
-@deffn {Scheme Procedure} acos z
-Return the arccosine of @var{z}.
-@end deffn
-
-@rnindex atan
-@c begin (texi-doc-string "guile" "atan")
-@deffn {Scheme Procedure} atan z
-Return the arctangent of @var{z}.
-@end deffn
-
-@rnindex exp
-@c begin (texi-doc-string "guile" "exp")
-@deffn {Scheme Procedure} exp z
-Return e to the power of @var{z}, where e is the base of natural
-logarithms (2.71828@dots{}).
-@end deffn
-
-@rnindex log
-@c begin (texi-doc-string "guile" "log")
-@deffn {Scheme Procedure} log z
-Return the natural logarithm of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "log10")
-@deffn {Scheme Procedure} log10 z
-Return the base 10 logarithm of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "sinh")
-@deffn {Scheme Procedure} sinh z
-Return the hyperbolic sine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "cosh")
-@deffn {Scheme Procedure} cosh z
-Return the hyperbolic cosine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "tanh")
-@deffn {Scheme Procedure} tanh z
-Return the hyperbolic tangent of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "asinh")
-@deffn {Scheme Procedure} asinh z
-Return the hyperbolic arcsine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "acosh")
-@deffn {Scheme Procedure} acosh z
-Return the hyperbolic arccosine of @var{z}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "atanh")
-@deffn {Scheme Procedure} atanh z
-Return the hyperbolic arctangent of @var{z}.
-@end deffn
-
-
-@node Primitive Numerics
-@subsection Primitive Numeric Functions
-
-Many of Guile's numeric procedures which accept any kind of numbers as
-arguments, including complex numbers, are implemented as Scheme
-procedures that use the following real number-based primitives. These
-primitives signal an error if they are called with complex arguments.
-
-@c begin (texi-doc-string "guile" "$abs")
-@deffn {Scheme Procedure} $abs x
-Return the absolute value of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$sqrt")
-@deffn {Scheme Procedure} $sqrt x
-Return the square root of @var{x}.
-@end deffn
-
-@deffn {Scheme Procedure} $expt x y
-@deffnx {C Function} scm_sys_expt (x, y)
-Return @var{x} raised to the power of @var{y}. This
-procedure does not accept complex arguments.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$sin")
-@deffn {Scheme Procedure} $sin x
-Return the sine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$cos")
-@deffn {Scheme Procedure} $cos x
-Return the cosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$tan")
-@deffn {Scheme Procedure} $tan x
-Return the tangent of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$asin")
-@deffn {Scheme Procedure} $asin x
-Return the arcsine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$acos")
-@deffn {Scheme Procedure} $acos x
-Return the arccosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$atan")
-@deffn {Scheme Procedure} $atan x
-Return the arctangent of @var{x} in the range -PI/2 to PI/2.
-@end deffn
-
-@deffn {Scheme Procedure} $atan2 x y
-@deffnx {C Function} scm_sys_atan2 (x, y)
-Return the arc tangent of the two arguments @var{x} and
-@var{y}. This is similar to calculating the arc tangent of
-@var{x} / @var{y}, except that the signs of both arguments
-are used to determine the quadrant of the result. This
-procedure does not accept complex arguments.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$exp")
-@deffn {Scheme Procedure} $exp x
-Return e to the power of @var{x}, where e is the base of natural
-logarithms (2.71828@dots{}).
-@end deffn
-
-@c begin (texi-doc-string "guile" "$log")
-@deffn {Scheme Procedure} $log x
-Return the natural logarithm of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$sinh")
-@deffn {Scheme Procedure} $sinh x
-Return the hyperbolic sine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$cosh")
-@deffn {Scheme Procedure} $cosh x
-Return the hyperbolic cosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$tanh")
-@deffn {Scheme Procedure} $tanh x
-Return the hyperbolic tangent of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$asinh")
-@deffn {Scheme Procedure} $asinh x
-Return the hyperbolic arcsine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$acosh")
-@deffn {Scheme Procedure} $acosh x
-Return the hyperbolic arccosine of @var{x}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "$atanh")
-@deffn {Scheme Procedure} $atanh x
-Return the hyperbolic arctangent of @var{x}.
-@end deffn
-
-For the hyperbolic arc-functions, the Guile library exports C functions
-corresponding to these Scheme procedures, but taking and returning
-arguments of type @code{double} rather than the usual @code{SCM}.
-
-@deftypefn {C Function} double scm_asinh (double x)
-@deftypefnx {C Function} double scm_acosh (double x)
-@deftypefnx {C Function} double scm_atanh (double x)
-Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
-respectively.
-@end deftypefn
-
-For all the other Scheme procedures above, except @code{expt} and
-@code{atan2} (whose entries specifically mention an equivalent C
-function), the equivalent C functions are those provided by the standard
-mathematics library. The mapping is as follows.
-
-@multitable {xx} {Scheme Procedure} {C Function}
-@item @tab Scheme Procedure @tab C Function
-
-@item @tab @code{$abs} @tab @code{fabs}
-@item @tab @code{$sqrt} @tab @code{sqrt}
-@item @tab @code{$sin} @tab @code{sin}
-@item @tab @code{$cos} @tab @code{cos}
-@item @tab @code{$tan} @tab @code{tan}
-@item @tab @code{$asin} @tab @code{asin}
-@item @tab @code{$acos} @tab @code{acos}
-@item @tab @code{$atan} @tab @code{atan}
-@item @tab @code{$exp} @tab @code{exp}
-@item @tab @code{$log} @tab @code{log}
-@item @tab @code{$sinh} @tab @code{sinh}
-@item @tab @code{$cosh} @tab @code{cosh}
-@item @tab @code{$tanh} @tab @code{tanh}
-@end multitable
-
-@noindent
-Naturally, these C functions expect and return @code{double} arguments.
-
-
-@node Bitwise Operations
-@subsection Bitwise Operations
-
-@deffn {Scheme Procedure} logand n1 n2
-Return the bitwise AND of the integer arguments.
-
-@lisp
-(logand) @result{} -1
-(logand 7) @result{} 7
-(logand #b111 #b011 #b001) @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logior n1 n2
-Return the bitwise OR of the integer arguments.
-
-@lisp
-(logior) @result{} 0
-(logior 7) @result{} 7
-(logior #b000 #b001 #b011) @result{} 3
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logxor n1 n2
-Return the bitwise XOR of the integer arguments. A bit is
-set in the result if it is set in an odd number of arguments.
-@lisp
-(logxor) @result{} 0
-(logxor 7) @result{} 7
-(logxor #b000 #b001 #b011) @result{} 2
-(logxor #b000 #b001 #b011 #b011) @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} lognot n
-@deffnx {C Function} scm_lognot (n)
-Return the integer which is the 2s-complement of the integer
-argument.
-
-@lisp
-(number->string (lognot #b10000000) 2)
- @result{} "-10000001"
-(number->string (lognot #b0) 2)
- @result{} "-1"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logtest j k
-@deffnx {C Function} scm_logtest (j, k)
-@lisp
-(logtest j k) @equiv{} (not (zero? (logand j k)))
-
-(logtest #b0100 #b1011) @result{} #f
-(logtest #b0100 #b0111) @result{} #t
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logbit? index j
-@deffnx {C Function} scm_logbit_p (index, j)
-@lisp
-(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)
-
-(logbit? 0 #b1101) @result{} #t
-(logbit? 1 #b1101) @result{} #f
-(logbit? 2 #b1101) @result{} #t
-(logbit? 3 #b1101) @result{} #t
-(logbit? 4 #b1101) @result{} #f
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} ash n cnt
-@deffnx {C Function} scm_ash (n, cnt)
-The function ash performs an arithmetic shift left by @var{cnt}
-bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
-means, that the function does not guarantee to keep the bit
-structure of @var{n}, but rather guarantees that the result
-will always be rounded towards minus infinity. Therefore, the
-results of ash and a corresponding bitwise shift will differ if
-@var{n} is negative.
-
-Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
-
-@lisp
-(number->string (ash #b1 3) 2) @result{} "1000"
-(number->string (ash #b1010 -1) 2) @result{} "101"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} logcount n
-@deffnx {C Function} scm_logcount (n)
-Return the number of bits in integer @var{n}. If integer is
-positive, the 1-bits in its binary representation are counted.
-If negative, the 0-bits in its two's-complement binary
-representation are counted. If 0, 0 is returned.
-
-@lisp
-(logcount #b10101010)
- @result{} 4
-(logcount 0)
- @result{} 0
-(logcount -2)
- @result{} 1
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} integer-length n
-@deffnx {C Function} scm_integer_length (n)
-Return the number of bits necessary to represent @var{n}.
-
-@lisp
-(integer-length #b10101010)
- @result{} 8
-(integer-length 0)
- @result{} 0
-(integer-length #b1111)
- @result{} 4
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} integer-expt n k
-@deffnx {C Function} scm_integer_expt (n, k)
-Return @var{n} raised to the non-negative integer exponent
-@var{k}.
-
-@lisp
-(integer-expt 2 5)
- @result{} 32
-(integer-expt -3 3)
- @result{} -27
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} bit-extract n start end
-@deffnx {C Function} scm_bit_extract (n, start, end)
-Return the integer composed of the @var{start} (inclusive)
-through @var{end} (exclusive) bits of @var{n}. The
-@var{start}th bit becomes the 0-th bit in the result.
-
-@lisp
-(number->string (bit-extract #b1101101010 0 4) 2)
- @result{} "1010"
-(number->string (bit-extract #b1101101010 4 9) 2)
- @result{} "10110"
-@end lisp
-@end deffn
-
-
-@node Random
-@subsection Random Number Generation
-
-@deffn {Scheme Procedure} copy-random-state [state]
-@deffnx {C Function} scm_copy_random_state (state)
-Return a copy of the random state @var{state}.
-@end deffn
-
-@deffn {Scheme Procedure} random n [state]
-@deffnx {C Function} scm_random (n, state)
-Return a number in [0,N).
-
-Accepts a positive integer or real n and returns a
-number of the same type between zero (inclusive) and
-N (exclusive). The values returned have a uniform
-distribution.
-
-The optional argument @var{state} must be of the type produced
-by @code{seed->random-state}. It defaults to the value of the
-variable @var{*random-state*}. This object is used to maintain
-the state of the pseudo-random-number generator and is altered
-as a side effect of the random operation.
-@end deffn
-
-@deffn {Scheme Procedure} random:exp [state]
-@deffnx {C Function} scm_random_exp (state)
-Return an inexact real in an exponential distribution with mean
-1. For an exponential distribution with mean u use (* u
-(random:exp)).
-@end deffn
-
-@deffn {Scheme Procedure} random:hollow-sphere! v [state]
-@deffnx {C Function} scm_random_hollow_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is equal to 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed over the surface of the
-unit n-sphere.
-@end deffn
-
-@deffn {Scheme Procedure} random:normal [state]
-@deffnx {C Function} scm_random_normal (state)
-Return an inexact real in a normal distribution. The
-distribution used has mean 0 and standard deviation 1. For a
-normal distribution with mean m and standard deviation d use
-@code{(+ m (* d (random:normal)))}.
-@end deffn
-
-@deffn {Scheme Procedure} random:normal-vector! v [state]
-@deffnx {C Function} scm_random_normal_vector_x (v, state)
-Fills vect with inexact real random numbers that are
-independent and standard normally distributed
-(i.e., with mean 0 and variance 1).
-@end deffn
-
-@deffn {Scheme Procedure} random:solid-sphere! v [state]
-@deffnx {C Function} scm_random_solid_sphere_x (v, state)
-Fills vect with inexact real random numbers
-the sum of whose squares is less than 1.0.
-Thinking of vect as coordinates in space of
-dimension n = (vector-length vect), the coordinates
-are uniformly distributed within the unit n-sphere.
-The sum of the squares of the numbers is returned.
-@end deffn
-
-@deffn {Scheme Procedure} random:uniform [state]
-@deffnx {C Function} scm_random_uniform (state)
-Return a uniformly distributed inexact real random number in
-[0,1).
-@end deffn
-
-@deffn {Scheme Procedure} seed->random-state seed
-@deffnx {C Function} scm_seed_to_random_state (seed)
-Return a new random state using @var{seed}.
-@end deffn
-
-
-@node Characters
-@section Characters
-@tpindex Characters
-
-Most of the characters in the ASCII character set may be referred to by
-name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on.
-The following table describes the ASCII names for each character.
-
-@multitable @columnfractions .25 .25 .25 .25
-@item 0 = @code{#\nul}
- @tab 1 = @code{#\soh}
- @tab 2 = @code{#\stx}
- @tab 3 = @code{#\etx}
-@item 4 = @code{#\eot}
- @tab 5 = @code{#\enq}
- @tab 6 = @code{#\ack}
- @tab 7 = @code{#\bel}
-@item 8 = @code{#\bs}
- @tab 9 = @code{#\ht}
- @tab 10 = @code{#\nl}
- @tab 11 = @code{#\vt}
-@item 12 = @code{#\np}
- @tab 13 = @code{#\cr}
- @tab 14 = @code{#\so}
- @tab 15 = @code{#\si}
-@item 16 = @code{#\dle}
- @tab 17 = @code{#\dc1}
- @tab 18 = @code{#\dc2}
- @tab 19 = @code{#\dc3}
-@item 20 = @code{#\dc4}
- @tab 21 = @code{#\nak}
- @tab 22 = @code{#\syn}
- @tab 23 = @code{#\etb}
-@item 24 = @code{#\can}
- @tab 25 = @code{#\em}
- @tab 26 = @code{#\sub}
- @tab 27 = @code{#\esc}
-@item 28 = @code{#\fs}
- @tab 29 = @code{#\gs}
- @tab 30 = @code{#\rs}
- @tab 31 = @code{#\us}
-@item 32 = @code{#\sp}
-@end multitable
-
-The @code{delete} character (octal 177) may be referred to with the name
-@code{#\del}.
-
-Several characters have more than one name:
-
-@itemize @bullet
-@item
-@code{#\space}, @code{#\sp}
-@item
-@code{#\newline}, @code{#\nl}
-@item
-@code{#\tab}, @code{#\ht}
-@item
-@code{#\backspace}, @code{#\bs}
-@item
-@code{#\return}, @code{#\cr}
-@item
-@code{#\page}, @code{#\np}
-@item
-@code{#\null}, @code{#\nul}
-@end itemize
-
-@rnindex char?
-@deffn {Scheme Procedure} char? x
-@deffnx {C Function} scm_char_p (x)
-Return @code{#t} iff @var{x} is a character, else @code{#f}.
-@end deffn
-
-@rnindex char=?
-@deffn {Scheme Procedure} char=? x y
-Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
-@end deffn
-
-@rnindex char<?
-@deffn {Scheme Procedure} char<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence,
-else @code{#f}.
-@end deffn
-
-@rnindex char<=?
-@deffn {Scheme Procedure} char<=? x y
-Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
-@end deffn
-
-@rnindex char>?
-@deffn {Scheme Procedure} char>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
-sequence, else @code{#f}.
-@end deffn
-
-@rnindex char>=?
-@deffn {Scheme Procedure} char>=? x y
-Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence, else @code{#f}.
-@end deffn
-
-@rnindex char-ci=?
-@deffn {Scheme Procedure} char-ci=? x y
-Return @code{#t} iff @var{x} is the same character as @var{y} ignoring
-case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci<?
-@deffn {Scheme Procedure} char-ci<? x y
-Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence
-ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci<=?
-@deffn {Scheme Procedure} char-ci<=? x y
-Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci>?
-@deffn {Scheme Procedure} char-ci>? x y
-Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII
-sequence ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-ci>=?
-@deffn {Scheme Procedure} char-ci>=? x y
-Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
-ASCII sequence ignoring case, else @code{#f}.
-@end deffn
-
-@rnindex char-alphabetic?
-@deffn {Scheme Procedure} char-alphabetic? chr
-@deffnx {C Function} scm_char_alphabetic_p (chr)
-Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
-Alphabetic means the same thing as the isalpha C library function.
-@end deffn
-
-@rnindex char-numeric?
-@deffn {Scheme Procedure} char-numeric? chr
-@deffnx {C Function} scm_char_numeric_p (chr)
-Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
-Numeric means the same thing as the isdigit C library function.
-@end deffn
-
-@rnindex char-whitespace?
-@deffn {Scheme Procedure} char-whitespace? chr
-@deffnx {C Function} scm_char_whitespace_p (chr)
-Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
-Whitespace means the same thing as the isspace C library function.
-@end deffn
-
-@rnindex char-upper-case?
-@deffn {Scheme Procedure} char-upper-case? chr
-@deffnx {C Function} scm_char_upper_case_p (chr)
-Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
-Uppercase means the same thing as the isupper C library function.
-@end deffn
-
-@rnindex char-lower-case?
-@deffn {Scheme Procedure} char-lower-case? chr
-@deffnx {C Function} scm_char_lower_case_p (chr)
-Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
-Lowercase means the same thing as the islower C library function.
-@end deffn
-
-@deffn {Scheme Procedure} char-is-both? chr
-@deffnx {C Function} scm_char_is_both_p (chr)
-Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
-Uppercase and lowercase are as defined by the isupper and islower
-C library functions.
-@end deffn
-
-@rnindex char->integer
-@deffn {Scheme Procedure} char->integer chr
-@deffnx {C Function} scm_char_to_integer (chr)
-Return the number corresponding to ordinal position of @var{chr} in the
-ASCII sequence.
-@end deffn
-
-@rnindex integer->char
-@deffn {Scheme Procedure} integer->char n
-@deffnx {C Function} scm_integer_to_char (n)
-Return the character at position @var{n} in the ASCII sequence.
-@end deffn
-
-@rnindex char-upcase
-@deffn {Scheme Procedure} char-upcase chr
-@deffnx {C Function} scm_char_upcase (chr)
-Return the uppercase character version of @var{chr}.
-@end deffn
-
-@rnindex char-downcase
-@deffn {Scheme Procedure} char-downcase chr
-@deffnx {C Function} scm_char_downcase (chr)
-Return the lowercase character version of @var{chr}.
-@end deffn
-
-
-@node Strings
-@section Strings
-@tpindex Strings
-
-Strings are fixed-length sequences of characters. They can be created
-by calling constructor procedures, but they can also literally get
-entered at the REPL or in Scheme source files.
-
-Guile provides a rich set of string processing procedures, because text
-handling is very important when Guile is used as a scripting language.
-
-Strings always carry the information about how many characters they are
-composed of with them, so there is no special end-of-string character,
-like in C. That means that Scheme strings can contain any character,
-even the NUL character @code{'\0'}. But note: Since most operating
-system calls dealing with strings (such as for file operations) expect
-strings to be zero-terminated, they might do unexpected things when
-called with string containing unusual characters.
-
-@menu
-* String Syntax:: Read syntax for strings.
-* String Predicates:: Testing strings for certain properties.
-* String Constructors:: Creating new string objects.
-* List/String Conversion:: Converting from/to lists of characters.
-* String Selection:: Select portions from strings.
-* String Modification:: Modify parts or whole strings.
-* String Comparison:: Lexicographic ordering predicates.
-* String Searching:: Searching in strings.
-* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
-* Appending Strings:: Appending strings to form a new string.
-@end menu
-
-@node String Syntax
-@subsection String Read Syntax
-
-The read syntax for strings is an arbitrarily long sequence of
-characters enclosed in double quotes (@code{"}). @footnote{Actually, the
-current implementation restricts strings to a length of 2^24
-characters.} If you want to insert a double quote character into a
-string literal, it must be prefixed with a backslash @code{\} character
-(called an @dfn{escape character}).
-
-The following are examples of string literals:
-
-@lisp
-"foo"
-"bar plonk"
-"Hello World"
-"\"Hi\", he said."
-@end lisp
-
-@c FIXME::martin: What about escape sequences like \r, \n etc.?
-
-@node String Predicates
-@subsection String Predicates
-
-The following procedures can be used to check whether a given string
-fulfills some specified property.
-
-@rnindex string?
-@deffn {Scheme Procedure} string? obj
-@deffnx {C Function} scm_string_p (obj)
-Return @code{#t} if @var{obj} is a string, else @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} string-null? str
-@deffnx {C Function} scm_string_null_p (str)
-Return @code{#t} if @var{str}'s length is zero, and
-@code{#f} otherwise.
-@lisp
-(string-null? "") @result{} #t
-y @result{} "foo"
-(string-null? y) @result{} #f
-@end lisp
-@end deffn
-
-@node String Constructors
-@subsection String Constructors
-
-The string constructor procedures create new string objects, possibly
-initializing them with some specified character data.
-
-@c FIXME::martin: list->string belongs into `List/String Conversion'
-
-@rnindex string
-@rnindex list->string
-@deffn {Scheme Procedure} string . chrs
-@deffnx {Scheme Procedure} list->string chrs
-@deffnx {C Function} scm_string (chrs)
-Return a newly allocated string composed of the arguments,
-@var{chrs}.
-@end deffn
-
-@rnindex make-string
-@deffn {Scheme Procedure} make-string k [chr]
-@deffnx {C Function} scm_make_string (k, chr)
-Return a newly allocated string of
-length @var{k}. If @var{chr} is given, then all elements of
-the string are initialized to @var{chr}, otherwise the contents
-of the @var{string} are unspecified.
-@end deffn
-
-@node List/String Conversion
-@subsection List/String conversion
-
-When processing strings, it is often convenient to first convert them
-into a list representation by using the procedure @code{string->list},
-work with the resulting list, and then convert it back into a string.
-These procedures are useful for similar tasks.
-
-@rnindex string->list
-@deffn {Scheme Procedure} string->list str
-@deffnx {C Function} scm_string_to_list (str)
-Return a newly allocated list of the characters that make up
-the given string @var{str}. @code{string->list} and
-@code{list->string} are inverses as far as @samp{equal?} is
-concerned.
-@end deffn
-
-@deffn {Scheme Procedure} string-split str chr
-@deffnx {C Function} scm_string_split (str, chr)
-Split the string @var{str} into the a list of the substrings delimited
-by appearances of the character @var{chr}. Note that an empty substring
-between separator characters will result in an empty string in the
-result list.
-
-@lisp
-(string-split "root:x:0:0:root:/root:/bin/bash" #\:)
-@result{}
-("root" "x" "0" "0" "root" "/root" "/bin/bash")
-
-(string-split "::" #\:)
-@result{}
-("" "" "")
-
-(string-split "" #\:)
-@result{}
-("")
-@end lisp
-@end deffn
-
-
-@node String Selection
-@subsection String Selection
-
-Portions of strings can be extracted by these procedures.
-@code{string-ref} delivers individual characters whereas
-@code{substring} can be used to extract substrings from longer strings.
-
-@rnindex string-length
-@deffn {Scheme Procedure} string-length string
-@deffnx {C Function} scm_string_length (string)
-Return the number of characters in @var{string}.
-@end deffn
-
-@rnindex string-ref
-@deffn {Scheme Procedure} string-ref str k
-@deffnx {C Function} scm_string_ref (str, k)
-Return character @var{k} of @var{str} using zero-origin
-indexing. @var{k} must be a valid index of @var{str}.
-@end deffn
-
-@rnindex string-copy
-@deffn {Scheme Procedure} string-copy str
-@deffnx {C Function} scm_string_copy (str)
-Return a newly allocated copy of the given @var{string}.
-@end deffn
-
-@rnindex substring
-@deffn {Scheme Procedure} substring str start [end]
-@deffnx {C Function} scm_substring (str, start, end)
-Return a newly allocated string formed from the characters
-of @var{str} beginning with index @var{start} (inclusive) and
-ending with index @var{end} (exclusive).
-@var{str} must be a string, @var{start} and @var{end} must be
-exact integers satisfying:
-
-0 <= @var{start} <= @var{end} <= (string-length @var{str}).
-@end deffn
-
-@node String Modification
-@subsection String Modification
-
-These procedures are for modifying strings in-place. This means that the
-result of the operation is not a new string; instead, the original string's
-memory representation is modified.
-
-@rnindex string-set!
-@deffn {Scheme Procedure} string-set! str k chr
-@deffnx {C Function} scm_string_set_x (str, k, chr)
-Store @var{chr} in element @var{k} of @var{str} and return
-an unspecified value. @var{k} must be a valid index of
-@var{str}.
-@end deffn
-
-@rnindex string-fill!
-@deffn {Scheme Procedure} string-fill! str chr
-@deffnx {C Function} scm_string_fill_x (str, chr)
-Store @var{char} in every element of the given @var{string} and
-return an unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} substring-fill! str start end fill
-@deffnx {C Function} scm_substring_fill_x (str, start, end, fill)
-Change every character in @var{str} between @var{start} and
-@var{end} to @var{fill}.
-
-@lisp
-(define y "abcdefg")
-(substring-fill! y 1 3 #\r)
-y
-@result{} "arrdefg"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} substring-move! str1 start1 end1 str2 start2
-@deffnx {C Function} scm_substring_move_x (str1, start1, end1, str2, start2)
-Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}
-into @var{str2} beginning at position @var{start2}.
-@var{str1} and @var{str2} can be the same string.
-@end deffn
-
-
-@node String Comparison
-@subsection String Comparison
-
-The procedures in this section are similar to the character ordering
-predicates (@pxref{Characters}), but are defined on character sequences.
-They all return @code{#t} on success and @code{#f} on failure. The
-predicates ending in @code{-ci} ignore the character case when comparing
-strings.
-
-
-@rnindex string=?
-@deffn {Scheme Procedure} string=? s1 s2
-Lexicographic equality predicate; return @code{#t} if the two
-strings are the same length and contain the same characters in
-the same positions, otherwise return @code{#f}.
-
-The procedure @code{string-ci=?} treats upper and lower case
-letters as though they were the same character, but
-@code{string=?} treats upper and lower case as distinct
-characters.
-@end deffn
-
-@rnindex string<?
-@deffn {Scheme Procedure} string<? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than @var{s2}.
-@end deffn
-
-@rnindex string<=?
-@deffn {Scheme Procedure} string<=? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically less than or equal to @var{s2}.
-@end deffn
-
-@rnindex string>?
-@deffn {Scheme Procedure} string>? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than @var{s2}.
-@end deffn
-
-@rnindex string>=?
-@deffn {Scheme Procedure} string>=? s1 s2
-Lexicographic ordering predicate; return @code{#t} if @var{s1}
-is lexicographically greater than or equal to @var{s2}.
-@end deffn
-
-@rnindex string-ci=?
-@deffn {Scheme Procedure} string-ci=? s1 s2
-Case-insensitive string equality predicate; return @code{#t} if
-the two strings are the same length and their component
-characters match (ignoring case) at each position; otherwise
-return @code{#f}.
-@end deffn
-
-@rnindex string-ci<
-@deffn {Scheme Procedure} string-ci<? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than @var{s2}
-regardless of case.
-@end deffn
-
-@rnindex string<=?
-@deffn {Scheme Procedure} string-ci<=? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically less than or equal
-to @var{s2} regardless of case.
-@end deffn
-
-@rnindex string-ci>?
-@deffn {Scheme Procedure} string-ci>? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than
-@var{s2} regardless of case.
-@end deffn
-
-@rnindex string-ci>=?
-@deffn {Scheme Procedure} string-ci>=? s1 s2
-Case insensitive lexicographic ordering predicate; return
-@code{#t} if @var{s1} is lexicographically greater than or
-equal to @var{s2} regardless of case.
-@end deffn
-
-
-@node String Searching
-@subsection String Searching
-
-When searching for the index of a character in a string, these
-procedures can be used.
-
-@deffn {Scheme Procedure} string-index str chr [frm [to]]
-@deffnx {C Function} scm_string_index (str, chr, frm, to)
-Return the index of the first occurrence of @var{chr} in
-@var{str}. The optional integer arguments @var{frm} and
-@var{to} limit the search to a portion of the string. This
-procedure essentially implements the @code{index} or
-@code{strchr} functions from the C library.
-
-@lisp
-(string-index "weiner" #\e)
-@result{} 1
-
-(string-index "weiner" #\e 2)
-@result{} 4
-
-(string-index "weiner" #\e 2 4)
-@result{} #f
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} string-rindex str chr [frm [to]]
-@deffnx {C Function} scm_string_rindex (str, chr, frm, to)
-Like @code{string-index}, but search from the right of the
-string rather than from the left. This procedure essentially
-implements the @code{rindex} or @code{strrchr} functions from
-the C library.
-
-@lisp
-(string-rindex "weiner" #\e)
-@result{} 4
-
-(string-rindex "weiner" #\e 2 4)
-@result{} #f
-
-(string-rindex "weiner" #\e 2 5)
-@result{} 4
-@end lisp
-@end deffn
-
-@node Alphabetic Case Mapping
-@subsection Alphabetic Case Mapping
-
-These are procedures for mapping strings to their upper- or lower-case
-equivalents, respectively, or for capitalizing strings.
-
-@deffn {Scheme Procedure} string-upcase str
-@deffnx {C Function} scm_string_upcase (str)
-Return a freshly allocated string containing the characters of
-@var{str} in upper case.
-@end deffn
-
-@deffn {Scheme Procedure} string-upcase! str
-@deffnx {C Function} scm_string_upcase_x (str)
-Destructively upcase every character in @var{str} and return
-@var{str}.
-@lisp
-y @result{} "arrdefg"
-(string-upcase! y) @result{} "ARRDEFG"
-y @result{} "ARRDEFG"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} string-downcase str
-@deffnx {C Function} scm_string_downcase (str)
-Return a freshly allocation string containing the characters in
-@var{str} in lower case.
-@end deffn
-
-@deffn {Scheme Procedure} string-downcase! str
-@deffnx {C Function} scm_string_downcase_x (str)
-Destructively downcase every character in @var{str} and return
-@var{str}.
-@lisp
-y @result{} "ARRDEFG"
-(string-downcase! y) @result{} "arrdefg"
-y @result{} "arrdefg"
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} string-capitalize str
-@deffnx {C Function} scm_string_capitalize (str)
-Return a freshly allocated string with the characters in
-@var{str}, where the first character of every word is
-capitalized.
-@end deffn
-
-@deffn {Scheme Procedure} string-capitalize! str
-@deffnx {C Function} scm_string_capitalize_x (str)
-Upcase the first character of every word in @var{str}
-destructively and return @var{str}.
-
-@lisp
-y @result{} "hello world"
-(string-capitalize! y) @result{} "Hello World"
-y @result{} "Hello World"
-@end lisp
-@end deffn
-
-
-@node Appending Strings
-@subsection Appending Strings
-
-The procedure @code{string-append} appends several strings together to
-form a longer result string.
-
-@rnindex string-append
-@deffn {Scheme Procedure} string-append . args
-@deffnx {C Function} scm_string_append (args)
-Return a newly allocated string whose characters form the
-concatenation of the given strings, @var{args}.
-@end deffn
-
-
-@node Regular Expressions
-@section Regular Expressions
-@tpindex Regular expressions
-
-@cindex regular expressions
-@cindex regex
-@cindex emacs regexp
-
-A @dfn{regular expression} (or @dfn{regexp}) is a pattern that
-describes a whole class of strings. A full description of regular
-expressions and their syntax is beyond the scope of this manual;
-an introduction can be found in the Emacs manual (@pxref{Regexps,
-, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}), or
-in many general Unix reference books.
-
-If your system does not include a POSIX regular expression library, and
-you have not linked Guile with a third-party regexp library such as Rx,
-these functions will not be available. You can tell whether your Guile
-installation includes regular expression support by checking whether the
-@code{*features*} list includes the @code{regex} symbol.
-
-@menu
-* Regexp Functions:: Functions that create and match regexps.
-* Match Structures:: Finding what was matched by a regexp.
-* Backslash Escapes:: Removing the special meaning of regexp
- meta-characters.
-@end menu
-
-[FIXME: it may be useful to include an Examples section. Parts of this
-interface are bewildering on first glance.]
-
-@node Regexp Functions
-@subsection Regexp Functions
-
-By default, Guile supports POSIX extended regular expressions.
-That means that the characters @samp{(}, @samp{)}, @samp{+} and
-@samp{?} are special, and must be escaped if you wish to match the
-literal characters.
-
-This regular expression interface was modeled after that
-implemented by SCSH, the Scheme Shell. It is intended to be
-upwardly compatible with SCSH regular expressions.
-
-@c begin (scm-doc-string "regex.scm" "string-match")
-@deffn {Scheme Procedure} string-match pattern str [start]
-Compile the string @var{pattern} into a regular expression and compare
-it with @var{str}. The optional numeric argument @var{start} specifies
-the position of @var{str} at which to begin matching.
-
-@code{string-match} returns a @dfn{match structure} which
-describes what, if anything, was matched by the regular
-expression. @xref{Match Structures}. If @var{str} does not match
-@var{pattern} at all, @code{string-match} returns @code{#f}.
-@end deffn
-
-Each time @code{string-match} is called, it must compile its
-@var{pattern} argument into a regular expression structure. This
-operation is expensive, which makes @code{string-match} inefficient if
-the same regular expression is used several times (for example, in a
-loop). For better performance, you can compile a regular expression in
-advance and then match strings against the compiled regexp.
-
-@deffn {Scheme Procedure} make-regexp pat . flags
-@deffnx {C Function} scm_make_regexp (pat, flags)
-Compile the regular expression described by @var{pat}, and
-return the compiled regexp structure. If @var{pat} does not
-describe a legal regular expression, @code{make-regexp} throws
-a @code{regular-expression-syntax} error.
-
-The @var{flags} arguments change the behavior of the compiled
-regular expression. The following flags may be supplied:
-
-@table @code
-@item regexp/icase
-Consider uppercase and lowercase letters to be the same when
-matching.
-@item regexp/newline
-If a newline appears in the target string, then permit the
-@samp{^} and @samp{$} operators to match immediately after or
-immediately before the newline, respectively. Also, the
-@samp{.} and @samp{[^...]} operators will never match a newline
-character. The intent of this flag is to treat the target
-string as a buffer containing many lines of text, and the
-regular expression as a pattern that may match a single one of
-those lines.
-@item regexp/basic
-Compile a basic (``obsolete'') regexp instead of the extended
-(``modern'') regexps that are the default. Basic regexps do
-not consider @samp{|}, @samp{+} or @samp{?} to be special
-characters, and require the @samp{@{...@}} and @samp{(...)}
-metacharacters to be backslash-escaped (@pxref{Backslash
-Escapes}). There are several other differences between basic
-and extended regular expressions, but these are the most
-significant.
-@item regexp/extended
-Compile an extended regular expression rather than a basic
-regexp. This is the default behavior; this flag will not
-usually be needed. If a call to @code{make-regexp} includes
-both @code{regexp/basic} and @code{regexp/extended} flags, the
-one which comes last will override the earlier one.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} regexp-exec rx str [start [flags]]
-@deffnx {C Function} scm_regexp_exec (rx, str, start, flags)
-Match the compiled regular expression @var{rx} against
-@code{str}. If the optional integer @var{start} argument is
-provided, begin matching from that position in the string.
-Return a match structure describing the results of the match,
-or @code{#f} if no match could be found.
-
-The @var{flags} arguments change the matching behavior.
-The following flags may be supplied:
-
-@table @code
-@item regexp/notbol
-Operator @samp{^} always fails (unless @code{regexp/newline}
-is used). Use this when the beginning of the string should
-not be considered the beginning of a line.
-@item regexp/noteol
-Operator @samp{$} always fails (unless @code{regexp/newline}
-is used). Use this when the end of the string should not be
-considered the end of a line.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} regexp? obj
-@deffnx {C Function} scm_regexp_p (obj)
-Return @code{#t} if @var{obj} is a compiled regular expression,
-or @code{#f} otherwise.
-@end deffn
-
-Regular expressions are commonly used to find patterns in one string and
-replace them with the contents of another string.
-
-@c begin (scm-doc-string "regex.scm" "regexp-substitute")
-@deffn {Scheme Procedure} regexp-substitute port match [item@dots{}]
-Write to the output port @var{port} selected contents of the match
-structure @var{match}. Each @var{item} specifies what should be
-written, and may be one of the following arguments:
-
-@itemize @bullet
-@item
-A string. String arguments are written out verbatim.
-
-@item
-An integer. The submatch with that number is written.
-
-@item
-The symbol @samp{pre}. The portion of the matched string preceding
-the regexp match is written.
-
-@item
-The symbol @samp{post}. The portion of the matched string following
-the regexp match is written.
-@end itemize
-
-@var{port} may be @code{#f}, in which case nothing is written; instead,
-@code{regexp-substitute} constructs a string from the specified
-@var{item}s and returns that.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "regexp-substitute")
-@deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}]
-Similar to @code{regexp-substitute}, but can be used to perform global
-substitutions on @var{str}. Instead of taking a match structure as an
-argument, @code{regexp-substitute/global} takes two string arguments: a
-@var{regexp} string describing a regular expression, and a @var{target}
-string which should be matched against this regular expression.
-
-Each @var{item} behaves as in @var{regexp-substitute}, with the
-following exceptions:
-
-@itemize @bullet
-@item
-A function may be supplied. When this function is called, it will be
-passed one argument: a match structure for a given regular expression
-match. It should return a string to be written out to @var{port}.
-
-@item
-The @samp{post} symbol causes @code{regexp-substitute/global} to recurse
-on the unmatched portion of @var{str}. This @emph{must} be supplied in
-order to perform global search-and-replace on @var{str}; if it is not
-present among the @var{item}s, then @code{regexp-substitute/global} will
-return after processing a single match.
-@end itemize
-@end deffn
-
-@node Match Structures
-@subsection Match Structures
-
-@cindex match structures
-
-A @dfn{match structure} is the object returned by @code{string-match} and
-@code{regexp-exec}. It describes which portion of a string, if any,
-matched the given regular expression. Match structures include: a
-reference to the string that was checked for matches; the starting and
-ending positions of the regexp match; and, if the regexp included any
-parenthesized subexpressions, the starting and ending positions of each
-submatch.
-
-In each of the regexp match functions described below, the @code{match}
-argument must be a match structure returned by a previous call to
-@code{string-match} or @code{regexp-exec}. Most of these functions
-return some information about the original target string that was
-matched against a regular expression; we will call that string
-@var{target} for easy reference.
-
-@c begin (scm-doc-string "regex.scm" "regexp-match?")
-@deffn {Scheme Procedure} regexp-match? obj
-Return @code{#t} if @var{obj} is a match structure returned by a
-previous call to @code{regexp-exec}, or @code{#f} otherwise.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:substring")
-@deffn {Scheme Procedure} match:substring match [n]
-Return the portion of @var{target} matched by subexpression number
-@var{n}. Submatch 0 (the default) represents the entire regexp match.
-If the regular expression as a whole matched, but the subexpression
-number @var{n} did not match, return @code{#f}.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:start")
-@deffn {Scheme Procedure} match:start match [n]
-Return the starting position of submatch number @var{n}.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:end")
-@deffn {Scheme Procedure} match:end match [n]
-Return the ending position of submatch number @var{n}.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:prefix")
-@deffn {Scheme Procedure} match:prefix match
-Return the unmatched portion of @var{target} preceding the regexp match.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:suffix")
-@deffn {Scheme Procedure} match:suffix match
-Return the unmatched portion of @var{target} following the regexp match.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:count")
-@deffn {Scheme Procedure} match:count match
-Return the number of parenthesized subexpressions from @var{match}.
-Note that the entire regular expression match itself counts as a
-subexpression, and failed submatches are included in the count.
-@end deffn
-
-@c begin (scm-doc-string "regex.scm" "match:string")
-@deffn {Scheme Procedure} match:string match
-Return the original @var{target} string.
-@end deffn
-
-@node Backslash Escapes
-@subsection Backslash Escapes
-
-Sometimes you will want a regexp to match characters like @samp{*} or
-@samp{$} exactly. For example, to check whether a particular string
-represents a menu entry from an Info node, it would be useful to match
-it against a regexp like @samp{^* [^:]*::}. However, this won't work;
-because the asterisk is a metacharacter, it won't match the @samp{*} at
-the beginning of the string. In this case, we want to make the first
-asterisk un-magic.
-
-You can do this by preceding the metacharacter with a backslash
-character @samp{\}. (This is also called @dfn{quoting} the
-metacharacter, and is known as a @dfn{backslash escape}.) When Guile
-sees a backslash in a regular expression, it considers the following
-glyph to be an ordinary character, no matter what special meaning it
-would ordinarily have. Therefore, we can make the above example work by
-changing the regexp to @samp{^\* [^:]*::}. The @samp{\*} sequence tells
-the regular expression engine to match only a single asterisk in the
-target string.
-
-Since the backslash is itself a metacharacter, you may force a regexp to
-match a backslash in the target string by preceding the backslash with
-itself. For example, to find variable references in a @TeX{} program,
-you might want to find occurrences of the string @samp{\let\} followed
-by any number of alphabetic characters. The regular expression
-@samp{\\let\\[A-Za-z]*} would do this: the double backslashes in the
-regexp each match a single backslash in the target string.
-
-@c begin (scm-doc-string "regex.scm" "regexp-quote")
-@deffn {Scheme Procedure} regexp-quote str
-Quote each special character found in @var{str} with a backslash, and
-return the resulting string.
-@end deffn
-
-@strong{Very important:} Using backslash escapes in Guile source code
-(as in Emacs Lisp or C) can be tricky, because the backslash character
-has special meaning for the Guile reader. For example, if Guile
-encounters the character sequence @samp{\n} in the middle of a string
-while processing Scheme code, it replaces those characters with a
-newline character. Similarly, the character sequence @samp{\t} is
-replaced by a horizontal tab. Several of these @dfn{escape sequences}
-are processed by the Guile reader before your code is executed.
-Unrecognized escape sequences are ignored: if the characters @samp{\*}
-appear in a string, they will be translated to the single character
-@samp{*}.
-
-This translation is obviously undesirable for regular expressions, since
-we want to be able to include backslashes in a string in order to
-escape regexp metacharacters. Therefore, to make sure that a backslash
-is preserved in a string in your Guile program, you must use @emph{two}
-consecutive backslashes:
-
-@lisp
-(define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
-@end lisp
-
-The string in this example is preprocessed by the Guile reader before
-any code is executed. The resulting argument to @code{make-regexp} is
-the string @samp{^\* [^:]*}, which is what we really want.
-
-This also means that in order to write a regular expression that matches
-a single backslash character, the regular expression string in the
-source code must include @emph{four} backslashes. Each consecutive pair
-of backslashes gets translated by the Guile reader to a single
-backslash, and the resulting double-backslash is interpreted by the
-regexp engine as matching a single backslash character. Hence:
-
-@lisp
-(define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
-@end lisp
-
-The reason for the unwieldiness of this syntax is historical. Both
-regular expression pattern matchers and Unix string processing systems
-have traditionally used backslashes with the special meanings
-described above. The POSIX regular expression specification and ANSI C
-standard both require these semantics. Attempting to abandon either
-convention would cause other kinds of compatibility problems, possibly
-more severe ones. Therefore, without extending the Scheme reader to
-support strings with different quoting conventions (an ungainly and
-confusing extension when implemented in other languages), we must adhere
-to this cumbersome escape syntax.
-
-
-@node Symbols
-@section Symbols
-@tpindex Symbols
-
-Symbols in Scheme are widely used in three ways: as items of discrete
-data, as lookup keys for alists and hash tables, and to denote variable
-references.
-
-A @dfn{symbol} is similar to a string in that it is defined by a
-sequence of characters. The sequence of characters is known as the
-symbol's @dfn{name}. In the usual case --- that is, where the symbol's
-name doesn't include any characters that could be confused with other
-elements of Scheme syntax --- a symbol is written in a Scheme program by
-writing the sequence of characters that make up the name, @emph{without}
-any quotation marks or other special syntax. For example, the symbol
-whose name is ``multiply-by-2'' is written, simply:
-
-@lisp
-multiply-by-2
-@end lisp
-
-Notice how this differs from a @emph{string} with contents
-``multiply-by-2'', which is written with double quotation marks, like
-this:
-
-@lisp
-"multiply-by-2"
-@end lisp
-
-Looking beyond how they are written, symbols are different from strings
-in two important respects.
-
-The first important difference is uniqueness. If the same-looking
-string is read twice from two different places in a program, the result
-is two @emph{different} string objects whose contents just happen to be
-the same. If, on the other hand, the same-looking symbol is read twice
-from two different places in a program, the result is the @emph{same}
-symbol object both times.
-
-Given two read symbols, you can use @code{eq?} to test whether they are
-the same (that is, have the same name). @code{eq?} is the most
-efficient comparison operator in Scheme, and comparing two symbols like
-this is as fast as comparing, for example, two numbers. Given two
-strings, on the other hand, you must use @code{equal?} or
-@code{string=?}, which are much slower comparison operators, to
-determine whether the strings have the same contents.
-
-@lisp
-(define sym1 (quote hello))
-(define sym2 (quote hello))
-(eq? sym1 sym2) @result{} #t
-
-(define str1 "hello")
-(define str2 "hello")
-(eq? str1 str2) @result{} #f
-(equal? str1 str2) @result{} #t
-@end lisp
-
-The second important difference is that symbols, unlike strings, are not
-self-evaluating. This is why we need the @code{(quote @dots{})}s in the
-example above: @code{(quote hello)} evaluates to the symbol named
-"hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
-symbol named "hello" and evaluated as a variable reference @dots{} about
-which more below (@pxref{Symbol Variables}).
-
-@menu
-* Symbol Data:: Symbols as discrete data.
-* Symbol Keys:: Symbols as lookup keys.
-* Symbol Variables:: Symbols as denoting variables.
-* Symbol Primitives:: Operations related to symbols.
-* Symbol Props:: Function slots and property lists.
-* Symbol Read Syntax:: Extended read syntax for symbols.
-* Symbol Uninterned:: Uninterned symbols.
-@end menu
-
-
-@node Symbol Data
-@subsection Symbols as Discrete Data
-
-Numbers and symbols are similar to the extent that they both lend
-themselves to @code{eq?} comparison. But symbols are more descriptive
-than numbers, because a symbol's name can be used directly to describe
-the concept for which that symbol stands.
-
-For example, imagine that you need to represent some colours in a
-computer program. Using numbers, you would have to choose arbitrarily
-some mapping between numbers and colours, and then take care to use that
-mapping consistently:
-
-@lisp
-;; 1=red, 2=green, 3=purple
-
-(if (eq? (colour-of car) 1)
- ...)
-@end lisp
-
-@noindent
-You can make the mapping more explicit and the code more readable by
-defining constants:
-
-@lisp
-(define red 1)
-(define green 2)
-(define purple 3)
-
-(if (eq? (colour-of car) red)
- ...)
-@end lisp
-
-@noindent
-But the simplest and clearest approach is not to use numbers at all, but
-symbols whose names specify the colours that they refer to:
-
-@lisp
-(if (eq? (colour-of car) 'red)
- ...)
-@end lisp
-
-The descriptive advantages of symbols over numbers increase as the set
-of concepts that you want to describe grows. Suppose that a car object
-can have other properties as well, such as whether it has or uses:
-
-@itemize @bullet
-@item
-automatic or manual transmission
-@item
-leaded or unleaded fuel
-@item
-power steering (or not).
-@end itemize
-
-@noindent
-Then a car's combined property set could be naturally represented and
-manipulated as a list of symbols:
-
-@lisp
-(properties-of car1)
-@result{}
-(red manual unleaded power-steering)
-
-(if (memq 'power-steering (properties-of car1))
- (display "Unfit people can drive this car.\n")
- (display "You'll need strong arms to drive this car!\n"))
-@print{}
-Unfit people can drive this car.
-@end lisp
-
-Remember, the fundamental property of symbols that we are relying on
-here is that an occurrence of @code{'red} in one part of a program is an
-@emph{indistinguishable} symbol from an occurrence of @code{'red} in
-another part of a program; this means that symbols can usefully be
-compared using @code{eq?}. At the same time, symbols have naturally
-descriptive names. This combination of efficiency and descriptive power
-makes them ideal for use as discrete data.
-
-
-@node Symbol Keys
-@subsection Symbols as Lookup Keys
-
-Given their efficiency and descriptive power, it is natural to use
-symbols as the keys in an association list or hash table.
-
-To illustrate this, consider a more structured representation of the car
-properties example from the preceding subsection. Rather than
-mixing all the properties up together in a flat list, we could use an
-association list like this:
-
-@lisp
-(define car1-properties '((colour . red)
- (transmission . manual)
- (fuel . unleaded)
- (steering . power-assisted)))
-@end lisp
-
-Notice how this structure is more explicit and extensible than the flat
-list. For example it makes clear that @code{manual} refers to the
-transmission rather than, say, the windows or the locking of the car.
-It also allows further properties to use the same symbols among their
-possible values without becoming ambiguous:
-
-@lisp
-(define car1-properties '((colour . red)
- (transmission . manual)
- (fuel . unleaded)
- (steering . power-assisted)
- (seat-colour . red)
- (locking . manual)))
-@end lisp
-
-With a representation like this, it is easy to use the efficient
-@code{assq-XXX} family of procedures (@pxref{Association Lists}) to
-extract or change individual pieces of information:
-
-@lisp
-(assq-ref car1-properties 'fuel) @result{} unleaded
-(assq-ref car1-properties 'transmission) @result{} manual
-
-(assq-set! car1-properties 'seat-colour 'black)
-@result{}
-((colour . red)
- (transmission . manual)
- (fuel . unleaded)
- (steering . power-assisted)
- (seat-colour . black)
- (locking . manual)))
-@end lisp
-
-Hash tables also have keys, and exactly the same arguments apply to the
-use of symbols in hash tables as in association lists. The hash value
-that Guile uses to decide where to add a symbol-keyed entry to a hash
-table can be obtained by calling the @code{symbol-hash} procedure:
-
-@deffn {Scheme Procedure} symbol-hash symbol
-@deffnx {C Function} scm_symbol_hash (symbol)
-Return a hash value for @var{symbol}.
-@end deffn
-
-See @ref{Hash Tables} for information about hash tables in general, and
-for why you might choose to use a hash table rather than an association
-list.
-
-
-@node Symbol Variables
-@subsection Symbols as Denoting Variables
-
-When an unquoted symbol in a Scheme program is evaluated, it is
-interpreted as a variable reference, and the result of the evaluation is
-the appropriate variable's value.
-
-For example, when the expression @code{(string-length "abcd")} is read
-and evaluated, the sequence of characters @code{string-length} is read
-as the symbol whose name is "string-length". This symbol is associated
-with a variable whose value is the procedure that implements string
-length calculation. Therefore evaluation of the @code{string-length}
-symbol results in that procedure.
-
-The details of the connection between an unquoted symbol and the
-variable to which it refers are explained elsewhere. See @ref{Binding
-Constructs}, for how associations between symbols and variables are
-created, and @ref{Modules}, for how those associations are affected by
-Guile's module system.
-
-
-@node Symbol Primitives
-@subsection Operations Related to Symbols
-
-Given any Scheme value, you can determine whether it is a symbol using
-the @code{symbol?} primitive:
-
-@rnindex symbol?
-@deffn {Scheme Procedure} symbol? obj
-@deffnx {C Function} scm_symbol_p (obj)
-Return @code{#t} if @var{obj} is a symbol, otherwise return
-@code{#f}.
-@end deffn
-
-Once you know that you have a symbol, you can obtain its name as a
-string by calling @code{symbol->string}. Note that Guile differs by
-default from R5RS on the details of @code{symbol->string} as regards
-case-sensitivity:
-
-@rnindex symbol->string
-@deffn {Scheme Procedure} symbol->string s
-@deffnx {C Function} scm_symbol_to_string (s)
-Return the name of symbol @var{s} as a string. By default, Guile reads
-symbols case-sensitively, so the string returned will have the same case
-variation as the sequence of characters that caused @var{s} to be
-created.
-
-If Guile is set to read symbols case-insensitively (as specified by
-R5RS), and @var{s} comes into being as part of a literal expression
-(@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
-by a call to the @code{read} or @code{string-ci->symbol} procedures,
-Guile converts any alphabetic characters in the symbol's name to
-lower case before creating the symbol object, so the string returned
-here will be in lower case.
-
-If @var{s} was created by @code{string->symbol}, the case of characters
-in the string returned will be the same as that in the string that was
-passed to @code{string->symbol}, regardless of Guile's case-sensitivity
-setting at the time @var{s} was created.
-
-It is an error to apply mutation procedures like @code{string-set!} to
-strings returned by this procedure.
-@end deffn
-
-Most symbols are created by writing them literally in code. However it
-is also possible to create symbols programmatically using the following
-@code{string->symbol} and @code{string-ci->symbol} procedures:
-
-@rnindex string->symbol
-@deffn {Scheme Procedure} string->symbol string
-@deffnx {C Function} scm_string_to_symbol (string)
-Return the symbol whose name is @var{string}. This procedure can create
-symbols with names containing special characters or letters in the
-non-standard case, but it is usually a bad idea to create such symbols
-because in some implementations of Scheme they cannot be read as
-themselves.
-@end deffn
-
-@deffn {Scheme Procedure} string-ci->symbol str
-@deffnx {C Function} scm_string_ci_to_symbol (str)
-Return the symbol whose name is @var{str}. If Guile is currently
-reading symbols case-insensitively, @var{str} is converted to lowercase
-before the returned symbol is looked up or created.
-@end deffn
-
-The following examples illustrate Guile's detailed behaviour as regards
-the case-sensitivity of symbols:
-
-@lisp
-(read-enable 'case-insensitive) ; R5RS compliant behaviour
-
-(symbol->string 'flying-fish) @result{} "flying-fish"
-(symbol->string 'Martin) @result{} "martin"
-(symbol->string
- (string->symbol "Malvina")) @result{} "Malvina"
-
-(eq? 'mISSISSIppi 'mississippi) @result{} #t
-(string->symbol "mISSISSIppi") @result{} mISSISSIppi
-(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-(eq? 'LolliPop
- (string->symbol (symbol->string 'LolliPop))) @result{} #t
-(string=? "K. Harper, M.D."
- (symbol->string
- (string->symbol "K. Harper, M.D."))) @result{} #t
-
-(read-disable 'case-insensitive) ; Guile default behaviour
-
-(symbol->string 'flying-fish) @result{} "flying-fish"
-(symbol->string 'Martin) @result{} "Martin"
-(symbol->string
- (string->symbol "Malvina")) @result{} "Malvina"
-
-(eq? 'mISSISSIppi 'mississippi) @result{} #f
-(string->symbol "mISSISSIppi") @result{} mISSISSIppi
-(eq? 'bitBlt (string->symbol "bitBlt")) @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
-@end lisp
-
-Finally, some applications, especially those that generate new Scheme
-code dynamically, need to generate symbols for use in the generated
-code. The @code{gensym} primitive meets this need:
-
-@deffn {Scheme Procedure} gensym [prefix]
-@deffnx {C Function} scm_gensym (prefix)
-Create a new symbol with a name constructed from a prefix and a counter
-value. The string @var{prefix} can be specified as an optional
-argument. Default prefix is @samp{ g}. The counter is increased by 1
-at each call. There is no provision for resetting the counter.
-@end deffn
-
-The symbols generated by @code{gensym} are @emph{likely} to be unique,
-since their names begin with a space and it is only otherwise possible
-to generate such symbols if a programmer goes out of their way to do
-so. The 1.8 release of Guile will include a way of creating
-symbols that are @emph{guaranteed} to be unique.
-
-
-@node Symbol Props
-@subsection Function Slots and Property Lists
-
-In traditional Lisp dialects, symbols are often understood as having
-three kinds of value at once:
-
-@itemize @bullet
-@item
-a @dfn{variable} value, which is used when the symbol appears in
-code in a variable reference context
-
-@item
-a @dfn{function} value, which is used when the symbol appears in
-code in a function name position (i.e. as the first element in an
-unquoted list)
-
-@item
-a @dfn{property list} value, which is used when the symbol is given as
-the first argument to Lisp's @code{put} or @code{get} functions.
-@end itemize
-
-Although Scheme (as one of its simplifications with respect to Lisp)
-does away with the distinction between variable and function namespaces,
-Guile currently retains some elements of the traditional structure in
-case they turn out to be useful when implementing translators for other
-languages, in particular Emacs Lisp.
-
-Specifically, Guile symbols have two extra slots. for a symbol's
-property list, and for its ``function value.'' The following procedures
-are provided to access these slots.
-
-@deffn {Scheme Procedure} symbol-fref symbol
-@deffnx {C Function} scm_symbol_fref (symbol)
-Return the contents of @var{symbol}'s @dfn{function slot}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-fset! symbol value
-@deffnx {C Function} scm_symbol_fset_x (symbol, value)
-Set the contents of @var{symbol}'s function slot to @var{value}.
-@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}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-pset! symbol value
-@deffnx {C Function} scm_symbol_pset_x (symbol, value)
-Set @var{symbol}'s property list to @var{value}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-property sym prop
-From @var{sym}'s property list, return the value for property
-@var{prop}. The assumption is that @var{sym}'s property list is an
-association list whose keys are distinguished from each other using
-@code{equal?}; @var{prop} should be one of the keys in that list. If
-the property list has no entry for @var{prop}, @code{symbol-property}
-returns @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} set-symbol-property sym prop val
-In @var{sym}'s property list, set the value for property @var{prop} to
-@var{val}, or add a new entry for @var{prop}, with value @var{val}, if
-none already exists. For the structure of the property list, see
-@code{symbol-property}.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-property-remove! sym prop
-From @var{sym}'s property list, remove the entry for property
-@var{prop}, if there is one. For the structure of the property list,
-see @code{symbol-property}.
-@end deffn
-
-Support for these extra slots may be removed in a future release, and it
-is probably better to avoid using them. (In release 1.6, Guile itself
-uses the property list slot sparingly, and the function slot not at
-all.) For a more modern and Schemely approach to properties, see
-@ref{Object Properties}.
-
-
-@node Symbol Read Syntax
-@subsection Extended Read Syntax for Symbols
-
-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
-begin with @code{+}, @code{-} or @code{.}.
-
-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
-from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
-Scheme})), Guile provides an extended symbol read syntax that allows the
-inclusion of unusual characters such as space characters, newlines and
-parentheses. If (for whatever reason) you need to write a symbol
-containing characters not mentioned above, you can do so as follows.
-
-@itemize @bullet
-@item
-Begin the symbol with the characters @code{#@{},
-
-@item
-write the characters of the symbol and
-
-@item
-finish the symbol with the characters @code{@}#}.
-@end itemize
-
-Here are a few examples of this form of read syntax. The first symbol
-needs to use extended syntax because it contains a space character, the
-second because it contains a line break, and the last because it looks
-like a number.
-
-@lisp
-#@{foo bar@}#
-
-#@{what
-ever@}#
-
-#@{4242@}#
-@end lisp
-
-Although Guile provides this extended read syntax for symbols,
-widespread usage of it is discouraged because it is not portable and not
-very readable.
-
-
-@node Symbol Uninterned
-@subsection Uninterned Symbols
-
-What makes symbols useful is that they are automatically kept unique.
-There are no two symbols that are distinct objects but have the same
-name. But of course, there is no rule without exception. In addition
-to the normal symbols that have been discussed up to now, you can also
-create special @dfn{uninterned} symbols that behave slightly
-differently.
-
-To understand what is different about them and why they might be useful,
-we look at how normal symbols are actually kept unique.
-
-Whenever Guile wants to find the symbol with a specific name, for
-example during @code{read} or when executing @code{string->symbol}, it
-first looks into a table of all existing symbols to find out whether a
-symbol with the given name already exists. When this is the case, Guile
-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
-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 people's code.
-
-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
-@emph{are} in the table are called @dfn{interned}.
-
-You create new uninterned symbols with the function @code{make-symbol}.
-You can test whether a symbol is interned or not with
-@code{symbol-interned?}.
-
-Uninterned symbols break the rule that the name of a symbol uniquely
-identifies the symbol object. Because of this, they can not be written
-out and read back in like interned symbols. Currently, Guile has no
-support for reading uninterned symbols. Note that the function
-@code{gensym} does not return uninterned symbols for this reason.
-
-@deffn {Scheme Procedure} make-symbol name
-@deffnx {C Function} scm_make_symbol (name)
-Return a new uninterned symbol with the name @var{name}. The returned
-symbol is guaranteed to be unique and future calls to
-@code{string->symbol} will not return it.
-@end deffn
-
-@deffn {Scheme Procedure} symbol-interned? symbol
-@deffnx {C Function} scm_symbol_interned_p (symbol)
-Return @code{#t} if @var{symbol} is interned, otherwise return
-@code{#f}.
-@end deffn
-
-For example:
-
-@lisp
-(define foo-1 (string->symbol "foo"))
-(define foo-2 (string->symbol "foo"))
-(define foo-3 (make-symbol "foo"))
-(define foo-4 (make-symbol "foo"))
-
-(eq? foo-1 foo-2)
-@result{} #t
-; Two interned symbols with the same name are the same object,
-
-(eq? foo-1 foo-3)
-@result{} #f
-; but a call to make-symbol with the same name returns a
-; distinct object.
-
-(eq? foo-3 foo-4)
-@result{} #f
-; A call to make-symbol always returns a new object, even for
-; the same name.
-
-foo-3
-@result{} #<uninterned-symbol foo 8085290>
-; Uninterned symbols print differently from interned symbols,
-
-(symbol? foo-3)
-@result{} #t
-; but they are still symbols,
-
-(symbol-interned? foo-3)
-@result{} #f
-; just not interned.
-@end lisp
-
-
-@node Keywords
-@section Keywords
-@tpindex Keywords
-
-Keywords are self-evaluating objects with a convenient read syntax that
-makes them easy to type.
-
-Guile's keyword support conforms to R5RS, and adds a (switchable) read
-syntax extension to permit keywords to begin with @code{:} as well as
-@code{#:}.
-
-@menu
-* Why Use Keywords?:: Motivation for keyword usage.
-* Coding With Keywords:: How to use keywords.
-* Keyword Read Syntax:: Read syntax for keywords.
-* Keyword Procedures:: Procedures for dealing with keywords.
-* Keyword Primitives:: The underlying primitive procedures.
-@end menu
-
-@node Why Use Keywords?
-@subsection Why Use Keywords?
-
-Keywords are useful in contexts where a program or procedure wants to be
-able to accept a large number of optional arguments without making its
-interface unmanageable.
-
-To illustrate this, consider a hypothetical @code{make-window}
-procedure, which creates a new window on the screen for drawing into
-using some graphical toolkit. There are many parameters that the caller
-might like to specify, but which could also be sensibly defaulted, for
-example:
-
-@itemize @bullet
-@item
-color depth -- Default: the color depth for the screen
-
-@item
-background color -- Default: white
-
-@item
-width -- Default: 600
-
-@item
-height -- Default: 400
-@end itemize
-
-If @code{make-window} did not use keywords, the caller would have to
-pass in a value for each possible argument, remembering the correct
-argument order and using a special value to indicate the default value
-for that argument:
-
-@lisp
-(make-window 'default ;; Color depth
- 'default ;; Background color
- 800 ;; Width
- 100 ;; Height
- @dots{}) ;; More make-window arguments
-@end lisp
-
-With keywords, on the other hand, defaulted arguments are omitted, and
-non-default arguments are clearly tagged by the appropriate keyword. As
-a result, the invocation becomes much clearer:
-
-@lisp
-(make-window #:width 800 #:height 100)
-@end lisp
-
-On the other hand, for a simpler procedure with few arguments, the use
-of keywords would be a hindrance rather than a help. The primitive
-procedure @code{cons}, for example, would not be improved if it had to
-be invoked as
-
-@lisp
-(cons #:car x #:cdr y)
-@end lisp
-
-So the decision whether to use keywords or not is purely pragmatic: use
-them if they will clarify the procedure invocation at point of call.
-
-@node Coding With Keywords
-@subsection Coding With Keywords
-
-If a procedure wants to support keywords, it should take a rest argument
-and then use whatever means is convenient to extract keywords and their
-corresponding arguments from the contents of that rest argument.
-
-The following example illustrates the principle: the code for
-@code{make-window} uses a helper procedure called
-@code{get-keyword-value} to extract individual keyword arguments from
-the rest argument.
-
-@lisp
-(define (get-keyword-value args keyword default)
- (let ((kv (memq keyword args)))
- (if (and kv (>= (length kv) 2))
- (cadr kv)
- default)))
-
-(define (make-window . args)
- (let ((depth (get-keyword-value args #:depth screen-depth))
- (bg (get-keyword-value args #:bg "white"))
- (width (get-keyword-value args #:width 800))
- (height (get-keyword-value args #:height 100))
- @dots{})
- @dots{}))
-@end lisp
-
-But you don't need to write @code{get-keyword-value}. The @code{(ice-9
-optargs)} module provides a set of powerful macros that you can use to
-implement keyword-supporting procedures like this:
-
-@lisp
-(use-modules (ice-9 optargs))
-
-(define (make-window . args)
- (let-keywords args #f ((depth screen-depth)
- (bg "white")
- (width 800)
- (height 100))
- ...))
-@end lisp
-
-@noindent
-Or, even more economically, like this:
-
-@lisp
-(use-modules (ice-9 optargs))
-
-(define* (make-window #:key (depth screen-depth)
- (bg "white")
- (width 800)
- (height 100))
- ...)
-@end lisp
-
-For further details on @code{let-keywords}, @code{define*} and other
-facilities provided by the @code{(ice-9 optargs)} module, see
-@ref{Optional Arguments}.
-
-
-@node Keyword Read Syntax
-@subsection Keyword Read Syntax
-
-Guile, by default, only recognizes the keyword syntax specified by R5RS.
-A token of the form @code{#:NAME}, where @code{NAME} has the same syntax
-as a Scheme symbol (@pxref{Symbol Read Syntax}), is the external
-representation of the keyword named @code{NAME}. Keyword objects print
-using this syntax as well, so values containing keyword objects can be
-read back into Guile. When used in an expression, keywords are
-self-quoting objects.
-
-If the @code{keyword} read option is set to @code{'prefix}, Guile also
-recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens
-of the form @code{:NAME} are read as symbols, as required by R5RS.
-
-To enable and disable the alternative non-R5RS keyword syntax, you use
-the @code{read-options} procedure documented in @ref{General option
-interface} and @ref{Reader options}.
-
-@smalllisp
-(read-set! keywords 'prefix)
-
-#:type
-@result{}
-#:type
-
-:type
-@result{}
-#:type
-
-(read-set! keywords #f)
-
-#:type
-@result{}
-#:type
-
-:type
-@print{}
-ERROR: In expression :type:
-ERROR: Unbound variable: :type
-ABORT: (unbound-variable)
-@end smalllisp
-
-@node Keyword Procedures
-@subsection Keyword Procedures
-
-The following procedures can be used for converting symbols to keywords
-and back.
-
-@deffn {Scheme Procedure} symbol->keyword sym
-Return a keyword with the same characters as in @var{sym}.
-@end deffn
-
-@deffn {Scheme Procedure} keyword->symbol kw
-Return a symbol with the same characters as in @var{kw}.
-@end deffn
-
-
-@node Keyword Primitives
-@subsection Keyword Primitives
-
-Internally, a keyword is implemented as something like a tagged symbol,
-where the tag identifies the keyword as being self-evaluating, and the
-symbol, known as the keyword's @dfn{dash symbol} has the same name as
-the keyword name but prefixed by a single dash. For example, the
-keyword @code{#:name} has the corresponding dash symbol @code{-name}.
-
-Most keyword objects are constructed automatically by the reader when it
-reads a token beginning with @code{#:}. However, if you need to
-construct a keyword object programmatically, you can do so by calling
-@code{make-keyword-from-dash-symbol} with the corresponding dash symbol
-(as the reader does). The dash symbol for a keyword object can be
-retrieved using the @code{keyword-dash-symbol} procedure.
-
-@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
-@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
-Make a keyword object from a @var{symbol} that starts with a dash.
-@end deffn
-
-@deffn {Scheme Procedure} keyword? obj
-@deffnx {C Function} scm_keyword_p (obj)
-Return @code{#t} if the argument @var{obj} is a keyword, else
-@code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} keyword-dash-symbol keyword
-@deffnx {C Function} scm_keyword_dash_symbol (keyword)
-Return the dash symbol for @var{keyword}.
-This is the inverse of @code{make-keyword-from-dash-symbol}.
-@end deffn
-
-
-@node Other Types
-@section ``Functionality-Centric'' Data Types
-
-Procedures and macros are documented in their own chapter: see
-@ref{Procedures and Macros}.
-
-Variable objects are documented as part of the description of Guile's
-module system: see @ref{Variables}.
-
-Asyncs, dynamic roots and fluids are described in the chapter on
-scheduling: see @ref{Scheduling}.
-
-Hooks are documented in the chapter on general utility functions: see
-@ref{Hooks}.
-
-Ports are described in the chapter on I/O: see @ref{Input and Output}.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi
deleted file mode 100644
index 670bd0884..000000000
--- a/doc/ref/scheme-debug.texi
+++ /dev/null
@@ -1,206 +0,0 @@
-@page
-@node Debugging
-@chapter Debugging Infrastructure
-
-@deffn {Scheme Procedure} debug-options-interface [setting]
-@deffnx {C Function} scm_debug_options (setting)
-Option interface for the debug options. Instead of using
-this procedure directly, use the procedures @code{debug-enable},
-@code{debug-disable}, @code{debug-set!} and @code{debug-options}.
-@end deffn
-
-
-@section Using Traps
-
-@deffn {Scheme Procedure} with-traps thunk
-@deffnx {C Function} scm_with_traps (thunk)
-Call @var{thunk} with traps enabled.
-@end deffn
-
-@deffn {Scheme Procedure} debug-object? obj
-@deffnx {C Function} scm_debug_object_p (obj)
-Return @code{#t} if @var{obj} is a debug object.
-@end deffn
-
-
-@section Capturing the Stack or Innermost Stack Frame
-
-When an error occurs in a running program, or the program hits a
-breakpoint, its state at that point can be represented by a @dfn{stack}
-of all the evaluations and procedure applications that are logically in
-progress at that time, each of which is known as a @dfn{frame}. The
-programmer can learn more about the program's state at the point of
-interruption or error by inspecting the stack and its frames.
-
-@deffn {Scheme Procedure} make-stack obj . args
-@deffnx {C Function} scm_make_stack (obj, args)
-Create a new stack. If @var{obj} is @code{#t}, the current
-evaluation stack is used for creating the stack frames,
-otherwise the frames are taken from @var{obj} (which must be
-either a debug object or a continuation).
-
-@var{args} should be a list containing any combination of
-integer, procedure and @code{#t} values.
-
-These values specify various ways of cutting away uninteresting
-stack frames from the top and bottom of the stack that
-@code{make-stack} returns. They come in pairs like this:
-@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
-@var{outer_cut_2} @dots{})}.
-
-Each @var{inner_cut_N} can be @code{#t}, an integer, or a
-procedure. @code{#t} means to cut away all frames up to but
-excluding the first user module frame. An integer means to cut
-away exactly that number of frames. A procedure means to cut
-away all frames up to but excluding the application frame whose
-procedure matches the specified one.
-
-Each @var{outer_cut_N} can be an integer or a procedure. An
-integer means to cut away that number of frames. A procedure
-means to cut away frames down to but excluding the application
-frame whose procedure matches the specified one.
-
-If the @var{outer_cut_N} of the last pair is missing, it is
-taken as 0.
-@end deffn
-
-@deffn {Scheme Procedure} last-stack-frame obj
-@deffnx {C Function} scm_last_stack_frame (obj)
-Return a stack which consists of a single frame, which is the
-last stack frame for @var{obj}. @var{obj} must be either a
-debug object or a continuation.
-@end deffn
-
-
-@section Examining the Stack
-
-@deffn {Scheme Procedure} stack? obj
-@deffnx {C Function} scm_stack_p (obj)
-Return @code{#t} if @var{obj} is a calling stack.
-@end deffn
-
-@deffn {Scheme Procedure} stack-id stack
-@deffnx {C Function} scm_stack_id (stack)
-Return the identifier given to @var{stack} by @code{start-stack}.
-@end deffn
-
-@deffn {Scheme Procedure} stack-length stack
-@deffnx {C Function} scm_stack_length (stack)
-Return the length of @var{stack}.
-@end deffn
-
-@deffn {Scheme Procedure} stack-ref stack index
-@deffnx {C Function} scm_stack_ref (stack, index)
-Return the @var{index}'th frame from @var{stack}.
-@end deffn
-
-@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
-@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
-Display a backtrace to the output port @var{port}. @var{stack}
-is the stack to take the backtrace from, @var{first} specifies
-where in the stack to start and @var{depth} how much frames
-to display. Both @var{first} and @var{depth} can be @code{#f},
-which means that default values will be used.
-@end deffn
-
-
-@section Examining Stack Frames
-
-@deffn {Scheme Procedure} frame? obj
-@deffnx {C Function} scm_frame_p (obj)
-Return @code{#t} if @var{obj} is a stack frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-number frame
-@deffnx {C Function} scm_frame_number (frame)
-Return the frame number of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-previous frame
-@deffnx {C Function} scm_frame_previous (frame)
-Return the previous frame of @var{frame}, or @code{#f} if
-@var{frame} is the first frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-next frame
-@deffnx {C Function} scm_frame_next (frame)
-Return the next frame of @var{frame}, or @code{#f} if
-@var{frame} is the last frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-source frame
-@deffnx {C Function} scm_frame_source (frame)
-Return the source of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure? frame
-@deffnx {C Function} scm_frame_procedure_p (frame)
-Return @code{#t} if a procedure is associated with @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure frame
-@deffnx {C Function} scm_frame_procedure (frame)
-Return the procedure for @var{frame}, or @code{#f} if no
-procedure is associated with @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-arguments frame
-@deffnx {C Function} scm_frame_arguments (frame)
-Return the arguments of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-evaluating-args? frame
-@deffnx {C Function} scm_frame_evaluating_args_p (frame)
-Return @code{#t} if @var{frame} contains evaluated arguments.
-@end deffn
-
-@deffn {Scheme Procedure} frame-overflow? frame
-@deffnx {C Function} scm_frame_overflow_p (frame)
-Return @code{#t} if @var{frame} is an overflow frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-real? frame
-@deffnx {C Function} scm_frame_real_p (frame)
-Return @code{#t} if @var{frame} is a real frame.
-@end deffn
-
-@deffn {Scheme Procedure} display-application frame [port [indent]]
-@deffnx {C Function} scm_display_application (frame, port, indent)
-Display a procedure application @var{frame} to the output port
-@var{port}. @var{indent} specifies the indentation of the
-output.
-@end deffn
-
-
-@section Decoding Memoized Source Expressions
-
-@deffn {Scheme Procedure} memoized? obj
-@deffnx {C Function} scm_memoized_p (obj)
-Return @code{#t} if @var{obj} is memoized.
-@end deffn
-
-@deffn {Scheme Procedure} unmemoize m
-@deffnx {C Function} scm_unmemoize (m)
-Unmemoize the memoized expression @var{m},
-@end deffn
-
-@deffn {Scheme Procedure} memoized-environment m
-@deffnx {C Function} scm_memoized_environment (m)
-Return the environment of the memoized expression @var{m}.
-@end deffn
-
-
-@section Starting a New Stack
-
-@deffn {Scheme Syntax} start-stack id exp
-Evaluate @var{exp} on a new calling stack with identity @var{id}. If
-@var{exp} is interrupted during evaluation, backtraces will not display
-frames farther back than @var{exp}'s top-level form. This macro is a
-way of artificially limiting backtraces and stack procedures, largely as
-a convenience to the user.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi
deleted file mode 100644
index b73f8316d..000000000
--- a/doc/ref/scheme-evaluation.texi
+++ /dev/null
@@ -1,426 +0,0 @@
-@page
-@node Read/Load/Eval
-@chapter Reading and Evaluating Scheme Code
-
-This chapter describes Guile functions that are concerned with reading,
-loading and evaluating Scheme code at run time.
-
-@menu
-* Scheme Syntax:: Standard and extended Scheme syntax.
-* Scheme Read:: Reading Scheme code.
-* Fly Evaluation:: Procedures for on the fly evaluation.
-* Loading:: Loading Scheme code from file.
-* Delayed Evaluation:: Postponing evaluation until it is needed.
-* Local Evaluation:: Evaluation in a local environment.
-* Evaluator Behaviour:: Modifying Guile's evaluator.
-@end menu
-
-
-@node Scheme Syntax
-@section Scheme Syntax: Standard and Guile Extensions
-
-@menu
-* Expression Syntax::
-* Comments::
-* Block Comments::
-* Case Sensitivity::
-* Keyword Syntax::
-* Reader Extensions::
-@end menu
-
-
-@node Expression Syntax
-@subsection Expression Syntax
-
-
-@node Comments
-@subsection Comments
-
-@c FIXME::martin: Review me!
-
-Comments in Scheme source files are written by starting them with a
-semicolon character (@code{;}). The comment then reaches up to the end
-of the line. Comments can begin at any column, and the may be inserted
-on the same line as Scheme code.
-
-@lisp
-; Comment
-;; Comment too
-(define x 1) ; Comment after expression
-(let ((y 1))
- ;; Display something.
- (display y)
-;;; Comment at left margin.
- (display (+ y 1)))
-@end lisp
-
-It is common to use a single semicolon for comments following
-expressions on a line, to use two semicolons for comments which are
-indented like code, and three semicolons for comments which start at
-column 0, even if they are inside an indented code block. This
-convention is used when indenting code in Emacs' Scheme mode.
-
-
-@node Block Comments
-@subsection Block Comments
-
-@c FIXME::martin: Review me!
-
-@cindex multiline comments
-In addition to the standard line comments defined by R5RS, Guile has
-another comment type for multiline comments, called @dfn{block
-comments}. This type of comment begins with the character sequence
-@code{#!} and ends with the characters @code{!#}, which must appear on a
-line of their own. These comments are compatible with the block
-comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
-(scsh)}). The characters @code{#!} were chosen because they are the
-magic characters used in shell scripts for indicating that the name of
-the program for executing the script follows on the same line.
-
-Thus a Guile script often starts like this.
-
-@lisp
-#! /usr/local/bin/guile -s
-!#
-@end lisp
-
-More details on Guile scripting can be found in the scripting section
-(@pxref{Guile Scripting}).
-
-
-@node Case Sensitivity
-@subsection Case Sensitivity
-
-@c FIXME::martin: Review me!
-
-Scheme as defined in R5RS is not case sensitive when reading symbols.
-Guile, on the contrary is case sensitive by default, so the identifiers
-
-@lisp
-guile-whuzzy
-Guile-Whuzzy
-@end lisp
-
-are the same in R5RS Scheme, but are different in Guile.
-
-It is possible to turn off case sensitivity in Guile by setting the
-reader option @code{case-insensitive}. More on reader options can be
-found at (@pxref{Reader options}).
-
-@lisp
-(read-enable 'case-insensitive)
-@end lisp
-
-Note that this is seldom a problem, because Scheme programmers tend not
-to use uppercase letters in their identifiers anyway.
-
-
-@node Keyword Syntax
-@subsection Keyword Syntax
-
-
-@node Reader Extensions
-@subsection Reader Extensions
-
-@deffn {Scheme Procedure} read-hash-extend chr proc
-@deffnx {C Function} scm_read_hash_extend (chr, proc)
-Install the procedure @var{proc} for reading expressions
-starting with the character sequence @code{#} and @var{chr}.
-@var{proc} will be called with two arguments: the character
-@var{chr} and the port to read further data from. The object
-returned will be the return value of @code{read}.
-@end deffn
-
-
-@node Scheme Read
-@section Reading Scheme Code
-
-@rnindex read
-@deffn {Scheme Procedure} read [port]
-@deffnx {C Function} scm_read (port)
-Read an s-expression from the input port @var{port}, or from
-the current input port if @var{port} is not specified.
-Any whitespace before the next token is discarded.
-@end deffn
-
-The behaviour of Guile's Scheme reader can be modified by manipulating
-its read options. For more information about options, @xref{General
-option interface}. If you want to know which reader options are
-available, @xref{Reader options}.
-
-@c FIXME::martin: This is taken from libguile/options.c. Is there
-@c actually a difference between 'help and 'full?
-
-@deffn {Scheme Procedure} read-options [setting]
-Display the current settings of the read options. If @var{setting} is
-omitted, only a short form of the current read options is printed.
-Otherwise, @var{setting} should be one of the following symbols:
-@table @code
-@item help
-Display the complete option settings.
-@item full
-Like @code{help}, but also print programmer options.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} read-enable option-name
-@deffnx {Scheme Procedure} read-disable option-name
-@deffnx {Scheme Procedure} read-set! option-name value
-Modify the read options. @code{read-enable} should be used with boolean
-options and switches them on, @code{read-disable} switches them off.
-@code{read-set!} can be used to set an option to a specific value.
-@end deffn
-
-@deffn {Scheme Procedure} read-options-interface [setting]
-@deffnx {C Function} scm_read_options (setting)
-Option interface for the read options. Instead of using
-this procedure directly, use the procedures @code{read-enable},
-@code{read-disable}, @code{read-set!} and @code{read-options}.
-@end deffn
-
-
-@node Fly Evaluation
-@section Procedures for On the Fly Evaluation
-
-@xref{Environments}.
-
-@rnindex eval
-@c ARGFIXME environment/environment specifier
-@deffn {Scheme Procedure} eval exp module
-@deffnx {C Function} scm_eval (exp, module)
-Evaluate @var{exp}, a list representing a Scheme expression,
-in the top-level environment specified by @var{module}.
-While @var{exp} is evaluated (using @code{primitive-eval}),
-@var{module} is made the current module. The current module
-is reset to its previous value when @var{eval} returns.
-@end deffn
-
-@rnindex interaction-environment
-@deffn {Scheme Procedure} interaction-environment
-@deffnx {C Function} scm_interaction_environment ()
-Return a specifier for the environment that contains
-implementation--defined bindings, typically a superset of those
-listed in the report. The intent is that this procedure will
-return the environment in which the implementation would
-evaluate expressions dynamically typed by the user.
-@end deffn
-
-@deffn {Scheme Procedure} eval-string string
-@deffnx {C Function} scm_eval_string (string)
-Evaluate @var{string} as the text representation of a Scheme
-form or forms, and return whatever value they produce.
-Evaluation takes place in the environment returned by the
-procedure @code{interaction-environment}.
-@end deffn
-
-@deffn {Scheme Procedure} apply:nconc2last lst
-@deffnx {C Function} scm_nconc2last (lst)
-Given a list (@var{arg1} @dots{} @var{args}), this function
-conses the @var{arg1} @dots{} arguments onto the front of
-@var{args}, and returns the resulting list. Note that
-@var{args} is a list; thus, the argument to this function is
-a list whose last element is a list.
-Note: Rather than do new consing, @code{apply:nconc2last}
-destroys its argument, so use with care.
-@end deffn
-
-@rnindex apply
-@deffn {Scheme Procedure} apply proc arg1 @dots{} args
-@var{proc} must be a procedure and @var{args} must be a list. Call
-@var{proc} with the elements of the list @code{(append (list @var{arg1}
-@dots{}) @var{args})} as the actual arguments.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-eval exp
-@deffnx {C Function} scm_primitive_eval (exp)
-Evaluate @var{exp} in the top-level environment specified by
-the current module.
-@end deffn
-
-
-@node Loading
-@section Loading Scheme Code from File
-
-@rnindex load
-@deffn {Scheme Procedure} load filename
-Load @var{filename} and evaluate its contents in the top-level
-environment. The load paths are not searched. If the variable
-@code{%load-hook} is defined, it should be bound to a procedure that
-will be called before any code is loaded. See documentation for
-@code{%load-hook} later in this section.
-@end deffn
-
-@deffn {Scheme Procedure} load-from-path filename
-Similar to @code{load}, but searches for @var{filename} in the load
-paths.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-load filename
-@deffnx {C Function} scm_primitive_load (filename)
-Load the file named @var{filename} and evaluate its contents in
-the top-level environment. The load paths are not searched;
-@var{filename} must either be a full pathname or be a pathname
-relative to the current directory. If the variable
-@code{%load-hook} is defined, it should be bound to a procedure
-that will be called before any code is loaded. See the
-documentation for @code{%load-hook} later in this section.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-load-path filename
-@deffnx {C Function} scm_primitive_load_path (filename)
-Search @var{%load-path} for the file named @var{filename} and
-load it into the top-level environment. If @var{filename} is a
-relative pathname and is not found in the list of search paths,
-an error is signalled.
-@end deffn
-
-@deffn {Scheme Procedure} %search-load-path filename
-@deffnx {C Function} scm_sys_search_load_path (filename)
-Search @var{%load-path} for the file named @var{filename},
-which must be readable by the current user. If @var{filename}
-is found in the list of paths to search or is an absolute
-pathname, return its full pathname. Otherwise, return
-@code{#f}. Filenames may have any of the optional extensions
-in the @code{%load-extensions} list; @code{%search-load-path}
-will try each extension automatically.
-@end deffn
-
-@defvar %load-hook
-A procedure to be run whenever @code{primitive-load} is called. If this
-procedure is defined, it will be called with the filename argument that
-was passed to @code{primitive-load}.
-
-@example
-(define %load-hook (lambda (file)
- (display "Loading ")
- (display file)
- (write-line "...."))) @result{} undefined
-(load-from-path "foo.scm")
-@print{} Loading /usr/local/share/guile/site/foo.scm....
-@end example
-
-@end defvar
-
-@deffn {Scheme Procedure} current-load-port
-@deffnx {C Function} scm_current_load_port ()
-Return the current-load-port.
-The load port is used internally by @code{primitive-load}.
-@end deffn
-
-@defvar %load-extensions
-A list of default file extensions for files containing Scheme code.
-@code{%search-load-path} tries each of these extensions when looking for
-a file to load. By default, @code{%load-extensions} is bound to the
-list @code{("" ".scm")}.
-@end defvar
-
-
-@node Delayed Evaluation
-@section Delayed Evaluation
-
-[delay]
-
-@deffn {Scheme Procedure} promise? obj
-@deffnx {C Function} scm_promise_p (obj)
-Return true if @var{obj} is a promise, i.e. a delayed computation
-(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
-@end deffn
-
-@rnindex force
-@deffn {Scheme Procedure} force x
-@deffnx {C Function} scm_force (x)
-If the promise @var{x} has not been computed yet, compute and
-return @var{x}, otherwise just return the previously computed
-value.
-@end deffn
-
-
-@node Local Evaluation
-@section Local Evaluation
-
-[the-environment]
-
-@deffn {Scheme Procedure} local-eval exp [env]
-@deffnx {C Function} scm_local_eval (exp, env)
-Evaluate @var{exp} in its environment. If @var{env} is supplied,
-it is the environment in which to evaluate @var{exp}. Otherwise,
-@var{exp} must be a memoized code object (in which case, its environment
-is implicit).
-@end deffn
-
-
-@node Evaluator Behaviour
-@section Evaluator Behaviour
-
-@c FIXME::martin: Maybe this node name is bad, but the old name clashed with
-@c `Evaluator options' under `Options and Config'.
-
-The behaviour of Guile's evaluator can be modified by manipulating the
-evaluator options. For more information about options, @xref{General
-option interface}. If you want to know which evaluator options are
-available, @xref{Evaluator options}.
-
-@c FIXME::martin: This is taken from libguile/options.c. Is there
-@c actually a difference between 'help and 'full?
-
-@deffn {Scheme Procedure} eval-options [setting]
-Display the current settings of the evaluator options. If @var{setting}
-is omitted, only a short form of the current evaluator options is
-printed. Otherwise, @var{setting} should be one of the following
-symbols:
-@table @code
-@item help
-Display the complete option settings.
-@item full
-Like @code{help}, but also print programmer options.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} eval-enable option-name
-@deffnx {Scheme Procedure} eval-disable option-name
-@deffnx {Scheme Procedure} eval-set! option-name value
-Modify the evaluator options. @code{eval-enable} should be used with boolean
-options and switches them on, @code{eval-disable} switches them off.
-@code{eval-set!} can be used to set an option to a specific value.
-@end deffn
-
-@deffn {Scheme Procedure} eval-options-interface [setting]
-@deffnx {C Function} scm_eval_options_interface (setting)
-Option interface for the evaluation options. Instead of using
-this procedure directly, use the procedures @code{eval-enable},
-@code{eval-disable}, @code{eval-set!} and @code{eval-options}.
-@end deffn
-
-@c FIXME::martin: Why aren't these procedure named like the other options
-@c procedures?
-
-@deffn {Scheme Procedure} traps [setting]
-Display the current settings of the evaluator traps options. If
-@var{setting} is omitted, only a short form of the current evaluator
-traps options is printed. Otherwise, @var{setting} should be one of the
-following symbols:
-@table @code
-@item help
-Display the complete option settings.
-@item full
-Like @code{help}, but also print programmer options.
-@end table
-@end deffn
-
-@deffn {Scheme Procedure} trap-enable option-name
-@deffnx {Scheme Procedure} trap-disable option-name
-@deffnx {Scheme Procedure} trap-set! option-name value
-Modify the evaluator options. @code{trap-enable} should be used with boolean
-options and switches them on, @code{trap-disable} switches them off.
-@code{trap-set!} can be used to set an option to a specific value.
-@end deffn
-
-@deffn {Scheme Procedure} evaluator-traps-interface [setting]
-@deffnx {C Function} scm_evaluator_traps (setting)
-Option interface for the evaluator trap options.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-ideas.texi b/doc/ref/scheme-ideas.texi
deleted file mode 100644
index 98ed953e8..000000000
--- a/doc/ref/scheme-ideas.texi
+++ /dev/null
@@ -1,1459 +0,0 @@
-@page
-@node Basic Ideas
-@chapter Basic Ideas in Scheme
-
-In this chapter, we introduce the basic concepts that underpin the
-elegance and power of the Scheme language.
-
-Readers who already possess a background knowledge of Scheme may happily
-skip this chapter. For the reader who is new to the language, however,
-the following discussions on data, procedures, expressions and closure
-are designed to provide a minimum level of Scheme understanding that is
-more or less assumed by the reference chapters that follow.
-
-The style of this introductory material aims about halfway between the
-terse precision of R5RS and the discursive randomness of a Scheme
-tutorial.
-
-@menu
-* About Data:: Latent typing, types, values and variables.
-* About Procedures:: The representation and use of procedures.
-* About Expressions:: All kinds of expressions and their meaning.
-* About Closure:: Closure, scoping and environments.
-@end menu
-
-
-@node About Data
-@section Data Types, Values and Variables
-
-This section discusses the representation of data types and values, what
-it means for Scheme to be a @dfn{latently typed} language, and the role
-of variables. We conclude by introducing the Scheme syntaxes for
-defining a new variable, and for changing the value of an existing
-variable.
-
-@menu
-* Latent Typing:: Scheme as a "latently typed" language.
-* Values and Variables:: About data types, values and variables.
-* Definition:: Defining variables and setting their values.
-@end menu
-
-
-@node Latent Typing
-@subsection Latent Typing
-
-The term @dfn{latent typing} is used to describe a computer language,
-such as Scheme, for which you cannot, @emph{in general}, simply look at
-a program's source code and determine what type of data will be
-associated with a particular variable, or with the result of a
-particular expression.
-
-Sometimes, of course, you @emph{can} tell from the code what the type of
-an expression will be. If you have a line in your program that sets the
-variable @code{x} to the numeric value 1, you can be certain that,
-immediately after that line has executed (and in the absence of multiple
-threads), @code{x} has the numeric value 1. Or if you write a procedure
-that is designed to concatenate two strings, it is likely that the rest
-of your application will always invoke this procedure with two string
-parameters, and quite probable that the procedure would go wrong in some
-way if it was ever invoked with parameters that were not both strings.
-
-Nevertheless, the point is that there is nothing in Scheme which
-requires the procedure parameters always to be strings, or @code{x}
-always to hold a numeric value, and there is no way of declaring in your
-program that such constraints should always be obeyed. In the same
-vein, there is no way to declare the expected type of a procedure's
-return value.
-
-Instead, the types of variables and expressions are only known -- in
-general -- at run time. If you @emph{need} to check at some point that
-a value has the expected type, Scheme provides run time procedures that
-you can invoke to do so. But equally, it can be perfectly valid for two
-separate invocations of the same procedure to specify arguments with
-different types, and to return values with different types.
-
-The next subsection explains what this means in practice, for the ways
-that Scheme programs use data types, values and variables.
-
-
-@node Values and Variables
-@subsection Values and Variables
-
-Scheme provides many data types that you can use to represent your data.
-Primitive types include characters, strings, numbers and procedures.
-Compound types, which allow a group of primitive and compound values to
-be stored together, include lists, pairs, vectors and multi-dimensional
-arrays. In addition, Guile allows applications to define their own data
-types, with the same status as the built-in standard Scheme types.
-
-As a Scheme program runs, values of all types pop in and out of
-existence. Sometimes values are stored in variables, but more commonly
-they pass seamlessly from being the result of one computation to being
-one of the parameters for the next.
-
-Consider an example. A string value is created because the interpreter
-reads in a literal string from your program's source code. Then a
-numeric value is created as the result of calculating the length of the
-string. A second numeric value is created by doubling the calculated
-length. Finally the program creates a list with two elements -- the
-doubled length and the original string itself -- and stores this list in
-a program variable.
-
-All of the values involved here -- in fact, all values in Scheme --
-carry their type with them. In other words, every value ``knows,'' at
-runtime, what kind of value it is. A number, a string, a list,
-whatever.
-
-A variable, on the other hand, has no fixed type. A variable --
-@code{x}, say -- is simply the name of a location -- a box -- in which
-you can store any kind of Scheme value. So the same variable in a
-program may hold a number at one moment, a list of procedures the next,
-and later a pair of strings. The ``type'' of a variable -- insofar as
-the idea is meaningful at all -- is simply the type of whatever value
-the variable happens to be storing at a particular moment.
-
-
-@node Definition
-@subsection Defining and Setting Variables
-
-To define a new variable, you use Scheme's @code{define} syntax like
-this:
-
-@lisp
-(define @var{variable-name} @var{value})
-@end lisp
-
-This makes a new variable called @var{variable-name} and stores
-@var{value} in it as the variable's initial value. For example:
-
-@lisp
-;; Make a variable `x' with initial numeric value 1.
-(define x 1)
-
-;; Make a variable `organization' with an initial string value.
-(define organization "Free Software Foundation")
-@end lisp
-
-(In Scheme, a semicolon marks the beginning of a comment that continues
-until the end of the line. So the lines beginning @code{;;} are
-comments.)
-
-Changing the value of an already existing variable is very similar,
-except that @code{define} is replaced by the Scheme syntax @code{set!},
-like this:
-
-@lisp
-(set! @var{variable-name} @var{new-value})
-@end lisp
-
-Remember that variables do not have fixed types, so @var{new-value} may
-have a completely different type from whatever was previously stored in
-the location named by @var{variable-name}. Both of the following
-examples are therefore correct.
-
-@lisp
-;; Change the value of `x' to 5.
-(set! x 5)
-
-;; Change the value of `organization' to the FSF's street number.
-(set! organization 545)
-@end lisp
-
-In these examples, @var{value} and @var{new-value} are literal numeric
-or string values. In general, however, @var{value} and @var{new-value}
-can be any Scheme expression. Even though we have not yet covered the
-forms that Scheme expressions can take (@pxref{About Expressions}), you
-can probably guess what the following @code{set!} example does@dots{}
-
-@lisp
-(set! x (+ x 1))
-@end lisp
-
-(Note: this is not a complete description of @code{define} and
-@code{set!}, because we need to introduce some other aspects of Scheme
-before the missing pieces can be filled in. If, however, you are
-already familiar with the structure of Scheme, you may like to read
-about those missing pieces immediately by jumping ahead to the following
-references.
-
-@itemize @bullet
-@item
-@ref{Lambda Alternatives}, to read about an alternative form of the
-@code{define} syntax that can be used when defining new procedures.
-
-@item
-@ref{Procedures with Setters}, to read about an alternative form of the
-@code{set!} syntax that helps with changing a single value in the depths
-of a compound data structure.)
-
-@item
-@xref{Internal Definitions}, to read about using @code{define} other
-than at top level in a Scheme program, including a discussion of when it
-works to use @code{define} rather than @code{set!} to change the value
-of an existing variable.
-@end itemize
-
-
-@node About Procedures
-@section The Representation and Use of Procedures
-
-This section introduces the basics of using and creating Scheme
-procedures. It discusses the representation of procedures as just
-another kind of Scheme value, and shows how procedure invocation
-expressions are constructed. We then explain how @code{lambda} is used
-to create new procedures, and conclude by presenting the various
-shorthand forms of @code{define} that can be used instead of writing an
-explicit @code{lambda} expression.
-
-@menu
-* Procedures as Values:: Procedures are values like everything else.
-* Simple Invocation:: How to write a simple procedure invocation.
-* Creating a Procedure:: How to create your own procedures.
-* Lambda Alternatives:: Other ways of writing procedure definitions.
-@end menu
-
-
-@node Procedures as Values
-@subsection Procedures as Values
-
-One of the great simplifications of Scheme is that a procedure is just
-another type of value, and that procedure values can be passed around
-and stored in variables in exactly the same way as, for example, strings
-and lists. When we talk about a built-in standard Scheme procedure such
-as @code{open-input-file}, what we actually mean is that there is a
-pre-defined top level variable called @code{open-input-file}, whose
-value is a procedure that implements what R5RS says that
-@code{open-input-file} should do.
-
-Note that this is quite different from many dialects of Lisp ---
-including Emacs Lisp --- in which a program can use the same name with
-two quite separate meanings: one meaning identifies a Lisp function,
-while the other meaning identifies a Lisp variable, whose value need
-have nothing to do with the function that is associated with the first
-meaning. In these dialects, functions and variables are said to live in
-different @dfn{namespaces}.
-
-In Scheme, on the other hand, all names belong to a single unified
-namespace, and the variables that these names identify can hold any kind
-of Scheme value, including procedure values.
-
-One consequence of the ``procedures as values'' idea is that, if you
-don't happen to like the standard name for a Scheme procedure, you can
-change it.
-
-For example, @code{call-with-current-continuation} is a very important
-standard Scheme procedure, but it also has a very long name! So, many
-programmers use the following definition to assign the same procedure
-value to the more convenient name @code{call/cc}.
-
-@lisp
-(define call/cc call-with-current-continuation)
-@end lisp
-
-Let's understand exactly how this works. The definition creates a new
-variable @code{call/cc}, and then sets its value to the value of the
-variable @code{call-with-current-continuation}; the latter value is a
-procedure that implements the behaviour that R5RS specifies under the
-name ``call-with-current-continuation''. So @code{call/cc} ends up
-holding this value as well.
-
-Now that @code{call/cc} holds the required procedure value, you could
-choose to use @code{call-with-current-continuation} for a completely
-different purpose, or just change its value so that you will get an
-error if you accidentally use @code{call-with-current-continuation} as a
-procedure in your program rather than @code{call/cc}. For example:
-
-@lisp
-(set! call-with-current-continuation "Not a procedure any more!")
-@end lisp
-
-Or you could just leave @code{call-with-current-continuation} as it was.
-It's perfectly fine for more than one variable to hold the same
-procedure value.
-
-
-@node Simple Invocation
-@subsection Simple Procedure Invocation
-
-A procedure invocation in Scheme is written like this:
-
-@lisp
-(@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
-@end lisp
-
-In this expression, @var{procedure} can be any Scheme expression whose
-value is a procedure. Most commonly, however, @var{procedure} is simply
-the name of a variable whose value is a procedure.
-
-For example, @code{string-append} is a standard Scheme procedure whose
-behaviour is to concatenate together all the arguments, which are
-expected to be strings, that it is given. So the expression
-
-@lisp
-(string-append "/home" "/" "andrew")
-@end lisp
-
-@noindent
-is a procedure invocation whose result is the string value
-@code{"/home/andrew"}.
-
-Similarly, @code{string-length} is a standard Scheme procedure that
-returns the length of a single string argument, so
-
-@lisp
-(string-length "abc")
-@end lisp
-
-@noindent
-is a procedure invocation whose result is the numeric value 3.
-
-Each of the parameters in a procedure invocation can itself be any
-Scheme expression. Since a procedure invocation is itself a type of
-expression, we can put these two examples together to get
-
-@lisp
-(string-length (string-append "/home" "/" "andrew"))
-@end lisp
-
-@noindent
---- a procedure invocation whose result is the numeric value 12.
-
-(You may be wondering what happens if the two examples are combined the
-other way round. If we do this, we can make a procedure invocation
-expression that is @emph{syntactically} correct:
-
-@lisp
-(string-append "/home" (string-length "abc"))
-@end lisp
-
-@noindent
-but when this expression is executed, it will cause an error, because
-the result of @code{(string-length "abc")} is a numeric value, and
-@code{string-append} is not designed to accept a numeric value as one of
-its arguments.)
-
-
-@node Creating a Procedure
-@subsection Creating and Using a New Procedure
-
-Scheme has lots of standard procedures, and Guile provides all of these
-via predefined top level variables. All of these standard procedures
-are documented in the later chapters of this reference manual.
-
-Before very long, though, you will want to create new procedures that
-encapsulate aspects of your own applications' functionality. To do
-this, you can use the famous @code{lambda} syntax.
-
-For example, the value of the following Scheme expression
-
-@lisp
-(lambda (name address) @var{expression} @dots{})
-@end lisp
-
-@noindent
-is a newly created procedure that takes two arguments:
-@code{name} and @code{address}. The behaviour of the
-new procedure is determined by the sequence of @var{expression}s in the
-@dfn{body} of the procedure definition. (Typically, these
-@var{expression}s would use the arguments in some way, or else there
-wouldn't be any point in giving them to the procedure.) When invoked,
-the new procedure returns a value that is the value of the last
-@var{expression} in the procedure body.
-
-To make things more concrete, let's suppose that the two arguments are
-both strings, and that the purpose of this procedure is to form a
-combined string that includes these arguments. Then the full lambda
-expression might look like this:
-
-@lisp
-(lambda (name address)
- (string-append "Name=" name ":Address=" address))
-@end lisp
-
-We noted in the previous subsection that the @var{procedure} part of a
-procedure invocation expression can be any Scheme expression whose value
-is a procedure. But that's exactly what a lambda expression is! So we
-can use a lambda expression directly in a procedure invocation, like
-this:
-
-@lisp
-((lambda (name address)
- (string-append "Name=" name ":Address=" address))
- "FSF"
- "Cambridge")
-@end lisp
-
-@noindent
-This is a valid procedure invocation expression, and its result is the
-string @code{"Name=FSF:Address=Cambridge"}.
-
-It it more common, though, to store the procedure value in a variable ---
-
-@lisp
-(define make-combined-string
- (lambda (name address)
- (string-append "Name=" name ":Address=" address)))
-@end lisp
-
-@noindent
---- and then to use the variable name in the procedure invocation:
-
-@lisp
-(make-combined-string "FSF" "Cambridge")
-@end lisp
-
-@noindent
-Which has exactly the same result.
-
-It's important to note that procedures created using @code{lambda} have
-exactly the same status as the standard built in Scheme procedures, and
-can be invoked, passed around, and stored in variables in exactly the
-same ways.
-
-
-@node Lambda Alternatives
-@subsection Lambda Alternatives
-
-Since it is so common in Scheme programs to want to create a procedure
-and then store it in a variable, there is an alternative form of the
-@code{define} syntax that allows you to do just that.
-
-A @code{define} expression of the form
-
-@lisp
-(define (@var{name} [@var{arg1} [@var{arg2} @dots{}]])
- @var{expression} @dots{})
-@end lisp
-
-@noindent
-is exactly equivalent to the longer form
-
-@lisp
-(define @var{name}
- (lambda ([@var{arg1} [@var{arg2} @dots{}]])
- @var{expression} @dots{}))
-@end lisp
-
-So, for example, the definition of @code{make-combined-string} in the
-previous subsection could equally be written:
-
-@lisp
-(define (make-combined-string name address)
- (string-append "Name=" name ":Address=" address))
-@end lisp
-
-This kind of procedure definition creates a procedure that requires
-exactly the expected number of arguments. There are two further forms
-of the @code{lambda} expression, which create a procedure that can
-accept a variable number of arguments:
-
-@lisp
-(lambda (@var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
-
-(lambda @var{args} @var{expression} @dots{})
-@end lisp
-
-@noindent
-The corresponding forms of the alternative @code{define} syntax are:
-
-@lisp
-(define (@var{name} @var{arg1} @dots{} . @var{args}) @var{expression} @dots{})
-
-(define (@var{name} . @var{args}) @var{expression} @dots{})
-@end lisp
-
-@noindent
-For details on how these forms work, see @xref{Lambda}.
-
-(It could be argued that the alternative @code{define} forms are rather
-confusing, especially for newcomers to the Scheme language, as they hide
-both the role of @code{lambda} and the fact that procedures are values
-that are stored in variables in the some way as any other kind of value.
-On the other hand, they are very convenient, and they are also a good
-example of another of Scheme's powerful features: the ability to specify
-arbitrary syntactic transformations at run time, which can be applied to
-subsequently read input.)
-
-
-@node About Expressions
-@section Expressions and Evaluation
-
-So far, we have met expressions that @emph{do} things, such as the
-@code{define} expressions that create and initialize new variables, and
-we have also talked about expressions that have @emph{values}, for
-example the value of the procedure invocation expression:
-
-@lisp
-(string-append "/home" "/" "andrew")
-@end lisp
-
-@noindent
-but we haven't yet been precise about what causes an expression like
-this procedure invocation to be reduced to its ``value'', or how the
-processing of such expressions relates to the execution of a Scheme
-program as a whole.
-
-This section clarifies what we mean by an expression's value, by
-introducing the idea of @dfn{evaluation}. It discusses the side effects
-that evaluation can have, explains how each of the various types of
-Scheme expression is evaluated, and describes the behaviour and use of
-the Guile REPL as a mechanism for exploring evaluation. The section
-concludes with a very brief summary of Scheme's common syntactic
-expressions.
-
-@menu
-* Evaluating:: How a Scheme program is executed.
-* The REPL:: Interacting with the Guile interpreter.
-* Syntax Summary:: Common syntactic expressions -- in brief.
-@end menu
-
-
-@node Evaluating
-@subsection Evaluating Expressions and Executing Programs
-
-In Scheme, the process of executing an expression is known as
-@dfn{evaluation}. Evaluation has two kinds of result:
-
-@itemize @bullet
-@item
-the @dfn{value} of the evaluated expression
-
-@item
-the @dfn{side effects} of the evaluation, which consist of any effects of
-evaluating the expression that are not represented by the value.
-@end itemize
-
-Of the expressions that we have met so far, @code{define} and
-@code{set!} expressions have side effects --- the creation or
-modification of a variable --- but no value; @code{lambda} expressions
-have values --- the newly constructed procedures --- but no side
-effects; and procedure invocation expressions, in general, have either
-values, or side effects, or both.
-
-It is tempting to try to define more intuitively what we mean by
-``value'' and ``side effects'', and what the difference between them is.
-In general, though, this is extremely difficult. It is also
-unnecessary; instead, we can quite happily define the behaviour of a
-Scheme program by specifying how Scheme executes a program as a whole,
-and then by describing the value and side effects of evaluation for each
-type of expression individually.
-
-@noindent
-So, some@footnote{These definitions are approximate. For the whole and
-detailed truth, see @xref{Formal syntax and semantics,R5RS
-syntax,,r5rs}.} definitions@dots{}
-
-@itemize @bullet
-
-@item
-A Scheme program consists of a sequence of expressions.
-
-@item
-A Scheme interpreter executes the program by evaluating these
-expressions in order, one by one.
-
-@item
-An expression can be
-
-@itemize @bullet
-@item
-a piece of literal data, such as a number @code{2.3} or a string
-@code{"Hello world!"}
-@item
-a variable name
-@item
-a procedure invocation expression
-@item
-one of Scheme's special syntactic expressions.
-@end itemize
-@end itemize
-
-@noindent
-The following subsections describe how each of these types of expression
-is evaluated.
-
-@menu
-* Eval Literal:: Evaluating literal data.
-* Eval Variable:: Evaluating variable references.
-* Eval Procedure:: Evaluating procedure invocation expressions.
-* Eval Special:: Evaluating special syntactic expressions.
-@end menu
-
-@node Eval Literal
-@subsubsection Evaluating Literal Data
-
-When a literal data expression is evaluated, the value of the expression
-is simply the value that the expression describes. The evaluation of a
-literal data expression has no side effects.
-
-@noindent
-So, for example,
-
-@itemize @bullet
-@item
-the value of the expression @code{"abc"} is the string value
-@code{"abc"}
-
-@item
-the value of the expression @code{3+4i} is the complex number 3 + 4i
-
-@item
-the value of the expression @code{#(1 2 3)} is a three-element vector
-containing the numeric values 1, 2 and 3.
-@end itemize
-
-For any data type which can be expressed literally like this, the syntax
-of the literal data expression for that data type --- in other words,
-what you need to write in your code to indicate a literal value of that
-type --- is known as the data type's @dfn{read syntax}. This manual
-specifies the read syntax for each such data type in the section that
-describes that data type.
-
-Some data types do not have a read syntax. Procedures, for example,
-cannot be expressed as literal data; they must be created using a
-@code{lambda} expression (@pxref{Creating a Procedure}) or implicitly
-using the shorthand form of @code{define} (@pxref{Lambda Alternatives}).
-
-
-@node Eval Variable
-@subsubsection Evaluating a Variable Reference
-
-When an expression that consists simply of a variable name is evaluated,
-the value of the expression is the value of the named variable. The
-evaluation of a variable reference expression has no side effects.
-
-So, after
-
-@lisp
-(define key "Paul Evans")
-@end lisp
-
-@noindent
-the value of the expression @code{key} is the string value @code{"Paul
-Evans"}. If @var{key} is then modified by
-
-@lisp
-(set! key 3.74)
-@end lisp
-
-@noindent
-the value of the expression @code{key} is the numeric value 3.74.
-
-If there is no variable with the specified name, evaluation of the
-variable reference expression signals an error.
-
-
-@node Eval Procedure
-@subsubsection Evaluating a Procedure Invocation Expression
-
-This is where evaluation starts getting interesting! As already noted,
-a procedure invocation expression has the form
-
-@lisp
-(@var{procedure} [@var{arg1} [@var{arg2} @dots{}]])
-@end lisp
-
-@noindent
-where @var{procedure} must be an expression whose value, when evaluated,
-is a procedure.
-
-The evaluation of a procedure invocation expression like this proceeds
-by
-
-@itemize @bullet
-@item
-evaluating individually the expressions @var{procedure}, @var{arg1},
-@var{arg2}, and so on
-
-@item
-calling the procedure that is the value of the @var{procedure}
-expression with the list of values obtained from the evaluations of
-@var{arg1}, @var{arg2} etc. as its parameters.
-@end itemize
-
-For a procedure defined in Scheme, ``calling the procedure with the list
-of values as its parameters'' means binding the values to the
-procedure's formal parameters and then evaluating the sequence of
-expressions that make up the body of the procedure definition. The
-value of the procedure invocation expression is the value of the last
-evaluated expression in the procedure body. The side effects of calling
-the procedure are the combination of the side effects of the sequence of
-evaluations of expressions in the procedure body.
-
-For a built-in procedure, the value and side-effects of calling the
-procedure are best described by that procedure's documentation.
-
-Note that the complete side effects of evaluating a procedure invocation
-expression consist not only of the side effects of the procedure call,
-but also of any side effects of the preceding evaluation of the
-expressions @var{procedure}, @var{arg1}, @var{arg2}, and so on.
-
-To illustrate this, let's look again at the procedure invocation
-expression:
-
-@lisp
-(string-length (string-append "/home" "/" "andrew"))
-@end lisp
-
-In the outermost expression, @var{procedure} is @code{string-length} and
-@var{arg1} is @code{(string-append "/home" "/" "andrew")}.
-
-@itemize @bullet
-@item
-Evaluation of @code{string-length}, which is a variable, gives a
-procedure value that implements the expected behaviour for
-``string-length''.
-
-@item
-Evaluation of @code{(string-append "/home" "/" "andrew")}, which is
-another procedure invocation expression, means evaluating each of
-
-@itemize @bullet
-@item
-@code{string-append}, which gives a procedure value that implements the
-expected behaviour for ``string-append''
-
-@item
-@code{"/home"}, which gives the string value @code{"/home"}
-
-@item
-@code{"/"}, which gives the string value @code{"/"}
-
-@item
-@code{"andrew"}, which gives the string value @code{"andrew"}
-@end itemize
-
-and then invoking the procedure value with this list of string values as
-its arguments. The resulting value is a single string value that is the
-concatenation of all the arguments, namely @code{"/home/andrew"}.
-@end itemize
-
-In the evaluation of the outermost expression, the interpreter can now
-invoke the procedure value obtained from @var{procedure} with the value
-obtained from @var{arg1} as its arguments. The resulting value is a
-numeric value that is the length of the argument string, which is 12.
-
-
-@node Eval Special
-@subsubsection Evaluating Special Syntactic Expressions
-
-When a procedure invocation expression is evaluated, the procedure and
-@emph{all} the argument expressions must be evaluated before the
-procedure can be invoked. Special syntactic expressions are special
-because they are able to manipulate their arguments in an unevaluated
-form, and can choose whether to evaluate any or all of the argument
-expressions.
-
-Why is this needed? Consider a program fragment that asks the user
-whether or not to delete a file, and then deletes the file if the user
-answers yes.
-
-@lisp
-(if (string=? (read-answer "Should I delete this file?")
- "yes")
- (delete-file file))
-@end lisp
-
-If the outermost @code{(if @dots{})} expression here was a procedure
-invocation expression, the expression @code{(delete-file file)}, whose
-side effect is to actually delete a file, would already have been
-evaluated before the @code{if} procedure even got invoked! Clearly this
-is no use --- the whole point of an @code{if} expression is that the
-@dfn{consequent} expression is only evaluated if the condition of the
-@code{if} expression is ``true''.
-
-Therefore @code{if} must be special syntax, not a procedure. Other
-special syntaxes that we have already met are @code{define}, @code{set!}
-and @code{lambda}. @code{define} and @code{set!} are syntax because
-they need to know the variable @emph{name} that is given as the first
-argument in a @code{define} or @code{set!} expression, not that
-variable's value. @code{lambda} is syntax because it does not
-immediately evaluate the expressions that define the procedure body;
-instead it creates a procedure object that incorporates these
-expressions so that they can be evaluated in the future, when that
-procedure is invoked.
-
-The rules for evaluating each special syntactic expression are specified
-individually for each special syntax. For a summary of standard special
-syntax, see @xref{Syntax Summary}.
-
-
-@node The REPL
-@subsection Using the Guile REPL
-
-If you start Guile without specifying a particular program for it to
-execute, Guile enters its standard Read Evaluate Print Loop --- or
-@dfn{REPL} for short. In this mode, Guile repeatedly reads in the next
-Scheme expression that the user types, evaluates it, and prints the
-resulting value.
-
-The REPL is a useful mechanism for exploring the evaluation behaviour
-described in the previous subsection. If you type @code{string-append},
-for example, the REPL replies @code{#<primitive-procedure
-string-append>}, illustrating the relationship between the variable
-@code{string-append} and the procedure value stored in that variable.
-
-In this manual, the notation @result{} is used to mean ``evaluates
-to''. Wherever you see an example of the form
-
-@lisp
-@var{expression}
-@result{}
-@var{result}
-@end lisp
-
-@noindent
-feel free to try it out yourself by typing @var{expression} into the
-REPL and checking that it gives the expected @var{result}.
-
-
-@node Syntax Summary
-@subsection Summary of Common Syntax
-
-This subsection lists the most commonly used Scheme syntactic
-expressions, simply so that you will recognize common special syntax
-when you see it. For a full description of each of these syntaxes,
-follow the appropriate reference.
-
-@code{lambda} (@pxref{Lambda}) is used to construct procedure objects.
-
-@code{define} (@pxref{Top Level}) is used to create a new variable and
-set its initial value.
-
-@code{set!} (@pxref{Top Level}) is used to modify an existing variable's
-value.
-
-@code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
-create an inner lexical environment for the evaluation of a sequence of
-expressions, in which a specified set of local variables is bound to the
-values of a corresponding set of expressions. For an introduction to
-environments, see @xref{About Closure}.
-
-@code{begin} (@pxref{begin}) executes a sequence of expressions in order
-and returns the value of the last expression. Note that this is not the
-same as a procedure which returns its last argument, because the
-evaluation of a procedure invocation expression does not guarantee to
-evaluate the arguments in order.
-
-@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
-evaluation of argument expressions depending on whether one or more
-conditions evaluate to ``true'' or ``false''.
-
-@code{case} (@pxref{if cond case}) provides conditional evaluation of
-argument expressions depending on whether a variable has one of a
-specified group of values.
-
-@code{and} (@pxref{and or}) executes a sequence of expressions in order
-until either there are no expressions left, or one of them evaluates to
-``false''.
-
-@code{or} (@pxref{and or}) executes a sequence of expressions in order
-until either there are no expressions left, or one of them evaluates to
-``true''.
-
-
-@node About Closure
-@section The Concept of Closure
-
-@cindex closure
-
-The concept of @dfn{closure} is the idea that a lambda expression
-``captures'' the variable bindings that are in lexical scope at the
-point where the lambda expression occurs. The procedure created by the
-lambda expression can refer to and mutate the captured bindings, and the
-values of those bindings persist between procedure calls.
-
-This section explains and explores the various parts of this idea in
-more detail.
-
-@menu
-* About Environments:: Names, locations, values and environments.
-* Local Variables:: Local variables and local environments.
-* Chaining:: Environment chaining.
-* Lexical Scope:: The meaning of lexical scoping.
-* Closure:: Explaining the concept of closure.
-* Serial Number:: Example 1: a serial number generator.
-* Shared Variable:: Example 2: a shared persistent variable.
-* Callback Closure:: Example 3: the callback closure problem.
-* OO Closure:: Example 4: object orientation.
-@end menu
-
-@node About Environments
-@subsection Names, Locations, Values and Environments
-
-@cindex location
-@cindex environment
-@cindex vcell
-@cindex top level environment
-@cindex environment, top level
-
-We said earlier that a variable name in a Scheme program is associated
-with a location in which any kind of Scheme value may be stored.
-(Incidentally, the term ``vcell'' is often used in Lisp and Scheme
-circles as an alternative to ``location''.) Thus part of what we mean
-when we talk about ``creating a variable'' is in fact establishing an
-association between a name, or identifier, that is used by the Scheme
-program code, and the variable location to which that name refers.
-Although the value that is stored in that location may change, the
-location to which a given name refers is always the same.
-
-We can illustrate this by breaking down the operation of the
-@code{define} syntax into three parts: @code{define}
-
-@itemize @bullet
-@item
-creates a new location
-
-@item
-establishes an association between that location and the name specified
-as the first argument of the @code{define} expression
-
-@item
-stores in that location the value obtained by evaluating the second
-argument of the @code{define} expression.
-@end itemize
-
-A collection of associations between names and locations is called an
-@dfn{environment}. When you create a top level variable in a program
-using @code{define}, the name-location association for that variable is
-added to the ``top level'' environment. The ``top level'' environment
-also includes name-location associations for all the procedures that are
-supplied by standard Scheme.
-
-It is also possible to create environments other than the top level one,
-and to create variable bindings, or name-location associations, in those
-environments. This ability is a key ingredient in the concept of
-closure; the next subsection shows how it is done.
-
-
-@node Local Variables
-@subsection Local Variables and Environments
-
-@cindex local variable
-@cindex variable, local
-@cindex local environment
-@cindex environment, local
-
-We have seen how to create top level variables using the @code{define}
-syntax (@pxref{Definition}). It is often useful to create variables
-that are more limited in their scope, typically as part of a procedure
-body. In Scheme, this is done using the @code{let} syntax, or one of
-its modified forms @code{let*} and @code{letrec}. These syntaxes are
-described in full later in the manual (@pxref{Local Bindings}). Here
-our purpose is to illustrate their use just enough that we can see how
-local variables work.
-
-For example, the following code uses a local variable @code{s} to
-simplify the computation of the area of a triangle given the lengths of
-its three sides.
-
-@lisp
-(define a 5.3)
-(define b 4.7)
-(define c 2.8)
-
-(define area
- (let ((s (/ (+ a b c) 2)))
- (sqrt (* s (- s a) (- s b) (- s c)))))
-@end lisp
-
-The effect of the @code{let} expression is to create a new environment
-and, within this environment, an association between the name @code{s}
-and a new location whose initial value is obtained by evaluating
-@code{(/ (+ a b c) 2)}. The expressions in the body of the @code{let},
-namely @code{(sqrt (* s (- s a) (- s b) (- s c)))}, are then evaluated
-in the context of the new environment, and the value of the last
-expression evaluated becomes the value of the whole @code{let}
-expression, and therefore the value of the variable @code{area}.
-
-
-@node Chaining
-@subsection Environment Chaining
-
-@cindex shadowing an imported variable binding
-@cindex chaining environments
-
-In the example of the previous subsection, we glossed over an important
-point. The body of the @code{let} expression in that example refers not
-only to the local variable @code{s}, but also to the top level variables
-@code{a}, @code{b}, @code{c} and @code{sqrt}. (@code{sqrt} is the
-standard Scheme procedure for calculating a square root.) If the body
-of the @code{let} expression is evaluated in the context of the
-@emph{local} @code{let} environment, how does the evaluation get at the
-values of these top level variables?
-
-The answer is that the local environment created by a @code{let}
-expression automatically has a reference to its containing environment
---- in this case the top level environment --- and that the Scheme
-interpreter automatically looks for a variable binding in the containing
-environment if it doesn't find one in the local environment. More
-generally, every environment except for the top level one has a
-reference to its containing environment, and the interpreter keeps
-searching back up the chain of environments --- from most local to top
-level --- until it either finds a variable binding for the required
-identifier or exhausts the chain.
-
-This description also determines what happens when there is more than
-one variable binding with the same name. Suppose, continuing the
-example of the previous subsection, that there was also a pre-existing
-top level variable @code{s} created by the expression:
-
-@lisp
-(define s "Some beans, my lord!")
-@end lisp
-
-Then both the top level environment and the local @code{let} environment
-would contain bindings for the name @code{s}. When evaluating code
-within the @code{let} body, the interpreter looks first in the local
-@code{let} environment, and so finds the binding for @code{s} created by
-the @code{let} syntax. Even though this environment has a reference to
-the top level environment, which also has a binding for @code{s}, the
-interpreter doesn't get as far as looking there. When evaluating code
-outside the @code{let} body, the interpreter looks up variable names in
-the top level environment, so the name @code{s} refers to the top level
-variable.
-
-Within the @code{let} body, the binding for @code{s} in the local
-environment is said to @dfn{shadow} the binding for @code{s} in the top
-level environment.
-
-
-@node Lexical Scope
-@subsection Lexical Scope
-
-The rules that we have just been describing are the details of how
-Scheme implements ``lexical scoping''. This subsection takes a brief
-diversion to explain what lexical scope means in general and to present
-an example of non-lexical scoping.
-
-``Lexical scope'' in general is the idea that
-
-@itemize @bullet
-@item
-an identifier at a particular place in a program always refers to the
-same variable location --- where ``always'' means ``every time that the
-containing expression is executed'', and that
-
-@item
-the variable location to which it refers can be determined by static
-examination of the source code context in which that identifier appears,
-without having to consider the flow of execution through the program as
-a whole.
-@end itemize
-
-In practice, lexical scoping is the norm for most programming languages,
-and probably corresponds to what you would intuitively consider to be
-``normal''. You may even be wondering how the situation could possibly
---- and usefully --- be otherwise. To demonstrate that another kind of
-scoping is possible, therefore, and to compare it against lexical
-scoping, the following subsection presents an example of non-lexical
-scoping and examines in detail how its behavior differs from the
-corresponding lexically scoped code.
-
-@menu
-* Scoping Example:: An example of non-lexical scoping.
-@end menu
-
-
-@node Scoping Example
-@subsubsection An Example of Non-Lexical Scoping
-
-To demonstrate that non-lexical scoping does exist and can be useful, we
-present the following example from Emacs Lisp, which is a ``dynamically
-scoped'' language.
-
-@lisp
-(defvar currency-abbreviation "USD")
-
-(defun currency-string (units hundredths)
- (concat currency-abbreviation
- (number-to-string units)
- "."
- (number-to-string hundredths)))
-
-(defun french-currency-string (units hundredths)
- (let ((currency-abbreviation "FRF"))
- (currency-string units hundredths)))
-@end lisp
-
-The question to focus on here is: what does the identifier
-@code{currency-abbreviation} refer to in the @code{currency-string}
-function? The answer, in Emacs Lisp, is that all variable bindings go
-onto a single stack, and that @code{currency-abbreviation} refers to the
-topmost binding from that stack which has the name
-``currency-abbreviation''. The binding that is created by the
-@code{defvar} form, to the value @code{"USD"}, is only relevant if none
-of the code that calls @code{currency-string} rebinds the name
-``currency-abbreviation'' in the meanwhile.
-
-The second function @code{french-currency-string} works precisely by
-taking advantage of this behaviour. It creates a new binding for the
-name ``currency-abbreviation'' which overrides the one established by
-the @code{defvar} form.
-
-@lisp
-;; Note! This is Emacs Lisp evaluation, not Scheme!
-(french-currency-string 33 44)
-@result{}
-"FRF33.44"
-@end lisp
-
-Now let's look at the corresponding, @emph{lexically scoped} Scheme
-code:
-
-@lisp
-(define currency-abbreviation "USD")
-
-(define (currency-string units hundredths)
- (string-append currency-abbreviation
- (number->string units)
- "."
- (number->string hundredths)))
-
-(define (french-currency-string units hundredths)
- (let ((currency-abbreviation "FRF"))
- (currency-string units hundredths)))
-@end lisp
-
-According to the rules of lexical scoping, the
-@code{currency-abbreviation} in @code{currency-string} refers to the
-variable location in the innermost environment at that point in the code
-which has a binding for @code{currency-abbreviation}, which is the
-variable location in the top level environment created by the preceding
-@code{(define currency-abbreviation @dots{})} expression.
-
-In Scheme, therefore, the @code{french-currency-string} procedure does
-not work as intended. The variable binding that it creates for
-``currency-abbreviation'' is purely local to the code that forms the
-body of the @code{let} expression. Since this code doesn't directly use
-the name ``currency-abbreviation'' at all, the binding is pointless.
-
-@lisp
-(french-currency-string 33 44)
-@result{}
-"USD33.44"
-@end lisp
-
-This begs the question of how the Emacs Lisp behaviour can be
-implemented in Scheme. In general, this is a design question whose
-answer depends upon the problem that is being addressed. In this case,
-the best answer may be that @code{currency-string} should be
-redesigned so that it can take an optional third argument. This third
-argument, if supplied, is interpreted as a currency abbreviation that
-overrides the default.
-
-It is possible to change @code{french-currency-string} so that it mostly
-works without changing @code{currency-string}, but the fix is inelegant,
-and susceptible to interrupts that could leave the
-@code{currency-abbreviation} variable in the wrong state:
-
-@lisp
-(define (french-currency-string units hundredths)
- (set! currency-abbreviation "FRF")
- (let ((result (currency-string units hundredths)))
- (set! currency-abbreviation "USD")
- result))
-@end lisp
-
-The key point here is that the code does not create any local binding
-for the identifier @code{currency-abbreviation}, so all occurrences of
-this identifier refer to the top level variable.
-
-
-@node Closure
-@subsection Closure
-
-Consider a @code{let} expression that doesn't contain any
-@code{lambda}s:
-
-@lisp
-(let ((s (/ (+ a b c) 2)))
- (sqrt (* s (- s a) (- s b) (- s c))))
-@end lisp
-
-@noindent
-When the Scheme interpreter evaluates this, it
-
-@itemize @bullet
-@item
-creates a new environment with a reference to the environment that was
-current when it encountered the @code{let}
-
-@item
-creates a variable binding for @code{s} in the new environment, with
-value given by @code{(/ (+ a b c) 2)}
-
-@item
-evaluates the expression in the body of the @code{let} in the context of
-the new local environment, and remembers the value @code{V}
-
-@item
-forgets the local environment
-
-@item
-continues evaluating the expression that contained the @code{let}, using
-the value @code{V} as the value of the @code{let} expression, in the
-context of the containing environment.
-@end itemize
-
-After the @code{let} expression has been evaluated, the local
-environment that was created is simply forgotten, and there is no longer
-any way to access the binding that was created in this environment. If
-the same code is evaluated again, it will follow the same steps again,
-creating a second new local environment that has no connection with the
-first, and then forgetting this one as well.
-
-If the @code{let} body contains a @code{lambda} expression, however, the
-local environment is @emph{not} forgotten. Instead, it becomes
-associated with the procedure that is created by the @code{lambda}
-expression, and is reinstated every time that that procedure is called.
-In detail, this works as follows.
-
-@itemize @bullet
-@item
-When the Scheme interpreter evaluates a @code{lambda} expression, to
-create a procedure object, it stores the current environment as part of
-the procedure definition.
-
-@item
-Then, whenever that procedure is called, the interpreter reinstates the
-environment that is stored in the procedure definition and evaluates the
-procedure body within the context of that environment.
-@end itemize
-
-The result is that the procedure body is always evaluated in the context
-of the environment that was current when the procedure was created.
-
-This is what is meant by @dfn{closure}. The next few subsections
-present examples that explore the usefulness of this concept.
-
-
-@node Serial Number
-@subsection Example 1: A Serial Number Generator
-
-This example uses closure to create a procedure with a variable binding
-that is private to the procedure, like a local variable, but whose value
-persists between procedure calls.
-
-@lisp
-(define (make-serial-number-generator)
- (let ((current-serial-number 0))
- (lambda ()
- (set! current-serial-number (+ current-serial-number 1))
- current-serial-number)))
-
-(define entry-sn-generator (make-serial-number-generator))
-
-(entry-sn-generator)
-@result{}
-1
-
-(entry-sn-generator)
-@result{}
-2
-@end lisp
-
-When @code{make-serial-number-generator} is called, it creates a local
-environment with a binding for @code{current-serial-number} whose
-initial value is 0, then, within this environment, creates a procedure.
-The local environment is stored within the created procedure object and
-so persists for the lifetime of the created procedure.
-
-Every time the created procedure is invoked, it increments the value of
-the @code{current-serial-number} binding in the captured environment and
-then returns the current value.
-
-Note that @code{make-serial-number-generator} can be called again to
-create a second serial number generator that is independent of the
-first. Every new invocation of @code{make-serial-number-generator}
-creates a new local @code{let} environment and returns a new procedure
-object with an association to this environment.
-
-
-@node Shared Variable
-@subsection Example 2: A Shared Persistent Variable
-
-This example uses closure to create two procedures, @code{get-balance}
-and @code{deposit}, that both refer to the same captured local
-environment so that they can both access the @code{balance} variable
-binding inside that environment. The value of this variable binding
-persists between calls to either procedure.
-
-Note that the captured @code{balance} variable binding is private to
-these two procedures: it is not directly accessible to any other code.
-It can only be accessed indirectly via @code{get-balance} or
-@code{deposit}, as illustrated by the @code{withdraw} procedure.
-
-@lisp
-(define get-balance #f)
-(define deposit #f)
-
-(let ((balance 0))
- (set! get-balance
- (lambda ()
- balance))
- (set! deposit
- (lambda (amount)
- (set! balance (+ balance amount))
- balance)))
-
-(define (withdraw amount)
- (deposit (- amount)))
-
-(get-balance)
-@result{}
-0
-
-(deposit 50)
-@result{}
-50
-
-(withdraw 75)
-@result{}
--25
-@end lisp
-
-An important detail here is that the @code{get-balance} and
-@code{deposit} variables must be set up by @code{define}ing them at top
-level and then @code{set!}ing their values inside the @code{let} body.
-Using @code{define} within the @code{let} body would not work: this
-would create variable bindings within the local @code{let} environment
-that would not be accessible at top level.
-
-
-@node Callback Closure
-@subsection Example 3: The Callback Closure Problem
-
-A frequently used programming model for library code is to allow an
-application to register a callback function for the library to call when
-some particular event occurs. It is often useful for the application to
-make several such registrations using the same callback function, for
-example if several similar library events can be handled using the same
-application code, but the need then arises to distinguish the callback
-function calls that are associated with one callback registration from
-those that are associated with different callback registrations.
-
-In languages without the ability to create functions dynamically, this
-problem is usually solved by passing a @code{user_data} parameter on the
-registration call, and including the value of this parameter as one of
-the parameters on the callback function. Here is an example of
-declarations using this solution in C:
-
-@example
-typedef void (event_handler_t) (int event_type,
- void *user_data);
-
-void register_callback (int event_type,
- event_handler_t *handler,
- void *user_data);
-@end example
-
-In Scheme, closure can be used to achieve the same functionality without
-requiring the library code to store a @code{user-data} for each callback
-registration.
-
-@lisp
-;; In the library:
-
-(define (register-callback event-type handler-proc)
- @dots{})
-
-;; In the application:
-
-(define (make-handler event-type user-data)
- (lambda ()
- @dots{}
- <code referencing event-type and user-data>
- @dots{}))
-
-(register-callback event-type
- (make-handler event-type @dots{}))
-@end lisp
-
-As far as the library is concerned, @code{handler-proc} is a procedure
-with no arguments, and all the library has to do is call it when the
-appropriate event occurs. From the application's point of view, though,
-the handler procedure has used closure to capture an environment that
-includes all the context that the handler code needs ---
-@code{event-type} and @code{user-data} --- to handle the event
-correctly.
-
-
-@node OO Closure
-@subsection Example 4: Object Orientation
-
-Closure is the capture of an environment, containing persistent variable
-bindings, within the definition of a procedure or a set of related
-procedures. This is rather similar to the idea in some object oriented
-languages of encapsulating a set of related data variables inside an
-``object'', together with a set of ``methods'' that operate on the
-encapsulated data. The following example shows how closure can be used
-to emulate the ideas of objects, methods and encapsulation in Scheme.
-
-@lisp
-(define (make-account)
- (let ((balance 0))
- (define (get-balance)
- balance)
- (define (deposit amount)
- (set! balance (+ balance amount))
- balance)
- (define (withdraw amount)
- (deposit (- amount)))
-
- (lambda args
- (apply
- (case (car args)
- ((get-balance) get-balance)
- ((deposit) deposit)
- ((withdraw) withdraw)
- (else (error "Invalid method!")))
- (cdr args)))))
-@end lisp
-
-Each call to @code{make-account} creates and returns a new procedure,
-created by the expression in the example code that begins ``(lambda
-args''.
-
-@lisp
-(define my-account (make-account))
-
-my-account
-@result{}
-#<procedure args>
-@end lisp
-
-This procedure acts as an account object with methods
-@code{get-balance}, @code{deposit} and @code{withdraw}. To apply one of
-the methods to the account, you call the procedure with a symbol
-indicating the required method as the first parameter, followed by any
-other parameters that are required by that method.
-
-@lisp
-(my-account 'get-balance)
-@result{}
-0
-
-(my-account 'withdraw 5)
-@result{}
--5
-
-(my-account 'deposit 396)
-@result{}
-391
-
-(my-account 'get-balance)
-@result{}
-391
-@end lisp
-
-Note how, in this example, both the current balance and the helper
-procedures @code{get-balance}, @code{deposit} and @code{withdraw}, used
-to implement the guts of the account object's methods, are all stored in
-variable bindings within the private local environment captured by the
-@code{lambda} expression that creates the account object procedure.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-indices.texi b/doc/ref/scheme-indices.texi
deleted file mode 100644
index acecb3ff4..000000000
--- a/doc/ref/scheme-indices.texi
+++ /dev/null
@@ -1,10 +0,0 @@
-@page
-@node R5RS Index
-@unnumbered R5RS Index
-
-@printindex rn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-intro.texi b/doc/ref/scheme-intro.texi
deleted file mode 100644
index 22e875339..000000000
--- a/doc/ref/scheme-intro.texi
+++ /dev/null
@@ -1,36 +0,0 @@
-@page
-@node Guile Scheme
-@chapter Guile's Implementation of Scheme
-
-Guile's core language is Scheme, which is specified and described in the
-series of reports known as @dfn{RnRS}. @dfn{RnRS} is shorthand for the
-@iftex
-@dfn{Revised$^n$ Report on the Algorithmic Language Scheme}.
-@end iftex
-@ifnottex
-@dfn{Revised^n Report on the Algorithmic Language Scheme}.
-@end ifnottex
-The current latest revision of RnRS is version 5
-(@pxref{Top,R5RS,,r5rs}), and Guile 1.4 is fully compliant with the
-Scheme specification in this revision.
-
-But Guile, like most Scheme implementations, also goes beyond R5RS in
-many ways, because R5RS does not give specifications (or even
-recommendations) regarding many issues that are important in practical
-programming. Some of the areas where Guile extends R5RS are:
-
-@itemize @bullet
-@item
-Guile's interactive documentation system
-
-@item
-Guile's support for POSIX-compliant network programming
-
-@item
-GOOPS -- Guile's framework for object oriented programming.
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-io.texi b/doc/ref/scheme-io.texi
deleted file mode 100644
index 3df790051..000000000
--- a/doc/ref/scheme-io.texi
+++ /dev/null
@@ -1,1116 +0,0 @@
-@page
-@node Input and Output
-@chapter Input and Output
-
-@menu
-* Ports:: The idea of the port abstraction.
-* Reading:: Procedures for reading from a port.
-* Writing:: Procedures for writing to a port.
-* Closing:: Procedures to close a port.
-* Random Access:: Moving around a random access port.
-* Line/Delimited:: Read and write lines or delimited text.
-* Block Reading and Writing:: Reading and writing blocks of text.
-* Default Ports:: Defaults for input, output and errors.
-* Port Types:: Types of port and how to make them.
-* I/O Extensions:: Using and extending ports in C.
-@end menu
-
-
-@node Ports
-@section Ports
-
-[Concept of the port abstraction.]
-
-Sequential input/output in Scheme is represented by operations on a
-@dfn{port}. Characters can be read from an input port and
-written to an output port. This chapter explains the operations
-that Guile provides for working with ports.
-
-The formal definition of a port is very generic: an input port is
-simply ``an object which can deliver characters on command,'' and
-an output port is ``an object which can accept characters.''
-Because this definition is so loose, it is easy to write functions
-that simulate ports in software. @dfn{Soft ports} and @dfn{string
-ports} are two interesting and powerful examples of this technique.
-
-@rnindex input-port?
-@deffn {Scheme Procedure} input-port? x
-@deffnx {C Function} scm_input_port_p (x)
-Return @code{#t} if @var{x} is an input port, otherwise return
-@code{#f}. Any object satisfying this predicate also satisfies
-@code{port?}.
-@end deffn
-
-@rnindex output-port?
-@deffn {Scheme Procedure} output-port? x
-@deffnx {C Function} scm_output_port_p (x)
-Return @code{#t} if @var{x} is an output port, otherwise return
-@code{#f}. Any object satisfying this predicate also satisfies
-@code{port?}.
-@end deffn
-
-@deffn {Scheme Procedure} port? x
-@deffnx {C Function} scm_port_p (x)
-Return a boolean indicating whether @var{x} is a port.
-Equivalent to @code{(or (input-port? @var{x}) (output-port?
-@var{x}))}.
-@end deffn
-
-
-@node Reading
-@section Reading
-
-[Generic procedures for reading from ports.]
-
-@rnindex eof-object?
-@deffn {Scheme Procedure} eof-object? x
-@deffnx {C Function} scm_eof_object_p (x)
-Return @code{#t} if @var{x} is an end-of-file object; otherwise
-return @code{#f}.
-@end deffn
-
-@rnindex char-ready?
-@deffn {Scheme Procedure} char-ready? [port]
-@deffnx {C Function} scm_char_ready_p (port)
-Return @code{#t} if a character is ready on input @var{port}
-and return @code{#f} otherwise. If @code{char-ready?} returns
-@code{#t} then the next @code{read-char} operation on
-@var{port} is guaranteed not to hang. If @var{port} is a file
-port at end of file then @code{char-ready?} returns @code{#t}.
-@footnote{@code{char-ready?} exists to make it possible for a
-program to accept characters from interactive ports without
-getting stuck waiting for input. Any input editors associated
-with such ports must make sure that characters whose existence
-has been asserted by @code{char-ready?} cannot be rubbed out.
-If @code{char-ready?} were to return @code{#f} at end of file,
-a port at end of file would be indistinguishable from an
-interactive port that has no ready characters.}
-@end deffn
-
-@rnindex read-char?
-@deffn {Scheme Procedure} read-char [port]
-@deffnx {C Function} scm_read_char (port)
-Return the next character available from @var{port}, updating
-@var{port} to point to the following character. If no more
-characters are available, the end-of-file object is returned.
-@end deffn
-
-@rnindex peek-char?
-@deffn {Scheme Procedure} peek-char [port]
-@deffnx {C Function} scm_peek_char (port)
-Return the next character available from @var{port},
-@emph{without} updating @var{port} to point to the following
-character. If no more characters are available, the
-end-of-file object is returned.@footnote{The value returned by
-a call to @code{peek-char} is the same as the value that would
-have been returned by a call to @code{read-char} on the same
-port. The only difference is that the very next call to
-@code{read-char} or @code{peek-char} on that @var{port} will
-return the value returned by the preceding call to
-@code{peek-char}. In particular, a call to @code{peek-char} on
-an interactive port will hang waiting for input whenever a call
-to @code{read-char} would have hung.}
-@end deffn
-
-@deffn {Scheme Procedure} unread-char cobj [port]
-@deffnx {C Function} scm_unread_char (cobj, port)
-Place @var{char} in @var{port} so that it will be read by the
-next read operation. If called multiple times, the unread characters
-will be read again in last-in first-out order. If @var{port} is
-not supplied, the current input port is used.
-@end deffn
-
-@deffn {Scheme Procedure} unread-string str port
-@deffnx {C Function} scm_unread_string (str, port)
-Place the string @var{str} in @var{port} so that its characters will be
-read in subsequent read operations. If called multiple times, the
-unread characters will be read again in last-in first-out order. If
-@var{port} is not supplied, the current-input-port is used.
-@end deffn
-
-@deffn {Scheme Procedure} drain-input port
-@deffnx {C Function} scm_drain_input (port)
-This procedure clears a port's input buffers, similar
-to the way that force-output clears the output buffer. The
-contents of the buffers are returned as a single string, e.g.,
-
-@lisp
-(define p (open-input-file ...))
-(drain-input p) => empty string, nothing buffered yet.
-(unread-char (read-char p) p)
-(drain-input p) => initial chars from p, up to the buffer size.
-@end lisp
-
-Draining the buffers may be useful for cleanly finishing
-buffered I/O so that the file descriptor can be used directly
-for further input.
-@end deffn
-
-@deffn {Scheme Procedure} port-column port
-@deffnx {Scheme Procedure} port-line port
-@deffnx {C Function} scm_port_column (port)
-@deffnx {C Function} scm_port_line (port)
-Return the current column number or line number of @var{port},
-using the current input port if none is specified. If the number is
-unknown, the result is #f. Otherwise, the result is a 0-origin integer
-- i.e. the first character of the first line is line 0, column 0.
-(However, when you display a file position, for example in an error
-message, we recommend you add 1 to get 1-origin integers. This is
-because lines and column numbers traditionally start with 1, and that is
-what non-programmers will find most natural.)
-@end deffn
-
-@deffn {Scheme Procedure} set-port-column! port column
-@deffnx {Scheme Procedure} set-port-line! port line
-@deffnx {C Function} scm_set_port_column_x (port, column)
-@deffnx {C Function} scm_set_port_line_x (port, line)
-Set the current column or line number of @var{port}, using the
-current input port if none is specified.
-@end deffn
-
-@node Writing
-@section Writing
-
-[Generic procedures for writing to ports.]
-
-@deffn {Scheme Procedure} get-print-state port
-@deffnx {C Function} scm_get_print_state (port)
-Return the print state of the port @var{port}. If @var{port}
-has no associated print state, @code{#f} is returned.
-@end deffn
-
-@rnindex display
-@deffn {Scheme Procedure} display obj [port]
-Send a representation of @var{obj} to @var{current-output-port}.
-Optional second arg @var{port} specifies an alternative output port.
-The representation is similar to that produced by @code{write} (REFFIXME),
-the differences being strings are not quoted (and their characters are not
-escaped), and characters are rendered as if with @code{write-char}.
-@end deffn
-
-@rnindex newline
-@deffn {Scheme Procedure} newline [port]
-@deffnx {C Function} scm_newline (port)
-Send a newline to @var{port}.
-If @var{port} is omitted, send to the current output port.
-@end deffn
-
-@deffn {Scheme Procedure} port-with-print-state port pstate
-@deffnx {C Function} scm_port_with_print_state (port, pstate)
-Create a new port which behaves like @var{port}, but with an
-included print state @var{pstate}.
-@end deffn
-
-@deffn {Scheme Procedure} print-options-interface [setting]
-@deffnx {C Function} scm_print_options (setting)
-Option interface for the print options. Instead of using
-this procedure directly, use the procedures
-@code{print-enable}, @code{print-disable}, @code{print-set!}
-and @code{print-options}.
-@end deffn
-
-@deffn {Scheme Procedure} simple-format destination message . args
-@deffnx {C Function} scm_simple_format (destination, message, args)
-Write @var{message} to @var{destination}, defaulting to
-the current output port.
-@var{message} can contain @code{~A} (was @code{%s}) and
-@code{~S} (was @code{%S}) escapes. When printed,
-the escapes are replaced with corresponding members of
-@var{ARGS}:
-@code{~A} formats using @code{display} and @code{~S} formats
-using @code{write}.
-If @var{destination} is @code{#t}, then use the current output
-port, if @var{destination} is @code{#f}, then return a string
-containing the formatted text. Does not add a trailing newline.
-@end deffn
-
-@rnindex write-char
-@deffn {Scheme Procedure} write-char chr [port]
-@deffnx {C Function} scm_write_char (chr, port)
-Send character @var{chr} to @var{port}.
-@end deffn
-
-@findex fflush
-@deffn {Scheme Procedure} force-output [port]
-@deffnx {C Function} scm_force_output (port)
-Flush the specified output port, or the current output port if @var{port}
-is omitted. The current output buffer contents are passed to the
-underlying port implementation (e.g., in the case of fports, the
-data will be written to the file and the output buffer will be cleared.)
-It has no effect on an unbuffered port.
-
-The return value is unspecified.
-@end deffn
-
-@deffn {Scheme Procedure} flush-all-ports
-@deffnx {C Function} scm_flush_all_ports ()
-Equivalent to calling @code{force-output} on
-all open output ports. The return value is unspecified.
-@end deffn
-
-
-@node Closing
-@section Closing
-
-@deffn {Scheme Procedure} close-port port
-@deffnx {C Function} scm_close_port (port)
-Close the specified port object. Return @code{#t} if it
-successfully closes a port or @code{#f} if it was already
-closed. An exception may be raised if an error occurs, for
-example when flushing buffered output. See also @ref{Ports and
-File Descriptors, close}, for a procedure which can close file
-descriptors.
-@end deffn
-
-@rnindex close-input-port
-@deffn {Scheme Procedure} close-input-port port
-@deffnx {C Function} scm_close_input_port (port)
-Close the specified input port object. The routine has no effect if
-the file has already been closed. An exception may be raised if an
-error occurs. The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
-@rnindex close-output-port
-@deffn {Scheme Procedure} close-output-port port
-@deffnx {C Function} scm_close_output_port (port)
-Close the specified output port object. The routine has no effect if
-the file has already been closed. An exception may be raised if an
-error occurs. The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
-@deffn {Scheme Procedure} port-closed? port
-@deffnx {C Function} scm_port_closed_p (port)
-Return @code{#t} if @var{port} is closed or @code{#f} if it is
-open.
-@end deffn
-
-
-@node Random Access
-@section Random Access
-
-@deffn {Scheme Procedure} seek fd_port offset whence
-@deffnx {C Function} scm_seek (fd_port, offset, whence)
-Sets the current position of @var{fd/port} to the integer
-@var{offset}, which is interpreted according to the value of
-@var{whence}.
-
-One of the following variables should be supplied for
-@var{whence}:
-@defvar SEEK_SET
-Seek from the beginning of the file.
-@end defvar
-@defvar SEEK_CUR
-Seek from the current position.
-@end defvar
-@defvar SEEK_END
-Seek from the end of the file.
-@end defvar
-If @var{fd/port} is a file descriptor, the underlying system
-call is @code{lseek}. @var{port} may be a string port.
-
-The value returned is the new position in the file. This means
-that the current position of a port can be obtained using:
-@lisp
-(seek port 0 SEEK_CUR)
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} ftell fd_port
-@deffnx {C Function} scm_ftell (fd_port)
-Return an integer representing the current position of
-@var{fd/port}, measured from the beginning. Equivalent to:
-
-@lisp
-(seek port 0 SEEK_CUR)
-@end lisp
-@end deffn
-
-@findex truncate
-@findex ftruncate
-@deffn {Scheme Procedure} truncate-file object [length]
-@deffnx {C Function} scm_truncate_file (object, length)
-Truncates the object referred to by @var{object} to at most
-@var{length} bytes. @var{object} can be a string containing a
-file name or an integer file descriptor or a port.
-@var{length} may be omitted if @var{object} is not a file name,
-in which case the truncation occurs at the current port.
-position. The return value is unspecified.
-@end deffn
-
-@node Line/Delimited
-@section Line Oriented and Delimited Text
-
-The delimited-I/O module can be accessed with:
-
-@smalllisp
-(use-modules (ice-9 rdelim))
-@end smalllisp
-
-It can be used to read or write lines of text, or read text delimited by
-a specified set of characters. It's similar to the @code{(scsh rdelim)}
-module from guile-scsh, but does not use multiple values or character
-sets and has an extra procedure @code{write-line}.
-
-@c begin (scm-doc-string "rdelim.scm" "read-line")
-@deffn {Scheme Procedure} read-line [port] [handle-delim]
-Return a line of text from @var{port} if specified, otherwise from the
-value returned by @code{(current-input-port)}. Under Unix, a line of text
-is terminated by the first end-of-line character or by end-of-file.
-
-If @var{handle-delim} is specified, it should be one of the following
-symbols:
-@table @code
-@item trim
-Discard the terminating delimiter. This is the default, but it will
-be impossible to tell whether the read terminated with a delimiter or
-end-of-file.
-@item concat
-Append the terminating delimiter (if any) to the returned string.
-@item peek
-Push the terminating delimiter (if any) back on to the port.
-@item split
-Return a pair containing the string read from the port and the
-terminating delimiter or end-of-file object.
-@end table
-@end deffn
-
-@c begin (scm-doc-string "rdelim.scm" "read-line!")
-@deffn {Scheme Procedure} read-line! buf [port]
-Read a line of text into the supplied string @var{buf} and return the
-number of characters added to @var{buf}. If @var{buf} is filled, then
-@code{#f} is returned.
-Read from @var{port} if
-specified, otherwise from the value returned by @code{(current-input-port)}.
-@end deffn
-
-@c begin (scm-doc-string "rdelim.scm" "read-delimited")
-@deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
-Read text until one of the characters in the string @var{delims} is found
-or end-of-file is reached. Read from @var{port} if supplied, otherwise
-from the value returned by @code{(current-input-port)}.
-@var{handle-delim} takes the same values as described for @code{read-line}.
-@end deffn
-
-@c begin (scm-doc-string "rdelim.scm" "read-delimited!")
-@deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
-Read text into the supplied string @var{buf} and return the number of
-characters added to @var{buf} (subject to @var{handle-delim}, which takes
-the same values specified for @code{read-line}. If @var{buf} is filled,
-@code{#f} is returned for both the number of characters read and the
-delimiter. Also terminates if one of the characters in the string
-@var{delims} is found
-or end-of-file is reached. Read from @var{port} if supplied, otherwise
-from the value returned by @code{(current-input-port)}.
-@end deffn
-
-@deffn {Scheme Procedure} write-line obj [port]
-@deffnx {C Function} scm_write_line (obj, port)
-Display @var{obj} and a newline character to @var{port}. If
-@var{port} is not specified, @code{(current-output-port)} is
-used. This function is equivalent to:
-@lisp
-(display obj [port])
-(newline [port])
-@end lisp
-@end deffn
-
-Some of the abovementioned I/O functions rely on the following C
-primitives. These will mainly be of interest to people hacking Guile
-internals.
-
-@deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
-@deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
-Read characters from @var{port} into @var{str} until one of the
-characters in the @var{delims} string is encountered. If
-@var{gobble} is true, discard the delimiter character;
-otherwise, leave it in the input stream for the next read. If
-@var{port} is not specified, use the value of
-@code{(current-input-port)}. If @var{start} or @var{end} are
-specified, store data only into the substring of @var{str}
-bounded by @var{start} and @var{end} (which default to the
-beginning and end of the string, respectively).
-
- Return a pair consisting of the delimiter that terminated the
-string and the number of characters read. If reading stopped
-at the end of file, the delimiter returned is the
-@var{eof-object}; if the string was filled without encountering
-a delimiter, this value is @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} %read-line [port]
-@deffnx {C Function} scm_read_line (port)
-Read a newline-terminated line from @var{port}, allocating storage as
-necessary. The newline terminator (if any) is removed from the string,
-and a pair consisting of the line and its delimiter is returned. The
-delimiter may be either a newline or the @var{eof-object}; if
-@code{%read-line} is called at the end of file, it returns the pair
-@code{(#<eof> . #<eof>)}.
-@end deffn
-
-@node Block Reading and Writing
-@section Block reading and writing
-
-The Block-string-I/O module can be accessed with:
-
-@smalllisp
-(use-modules (ice-9 rw))
-@end smalllisp
-
-It currently contains procedures that help to implement the
-@code{(scsh rw)} module in guile-scsh.
-
-@deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
-@deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
-Read characters from a port or file descriptor into a
-string @var{str}. A port must have an underlying file
-descriptor --- a so-called fport. This procedure is
-scsh-compatible and can efficiently read large strings.
-It will:
-
-@itemize
-@item
-attempt to fill the entire string, unless the @var{start}
-and/or @var{end} arguments are supplied. i.e., @var{start}
-defaults to 0 and @var{end} defaults to
-@code{(string-length str)}
-@item
-use the current input port if @var{port_or_fdes} is not
-supplied.
-@item
-return fewer than the requested number of characters in some
-cases, e.g., on end of file, if interrupted by a signal, or if
-not all the characters are immediately available.
-@item
-wait indefinitely for some input if no characters are
-currently available,
-unless the port is in non-blocking mode.
-@item
-read characters from the port's input buffers if available,
-instead from the underlying file descriptor.
-@item
-return @code{#f} if end-of-file is encountered before reading
-any characters, otherwise return the number of characters
-read.
-@item
-return 0 if the port is in non-blocking mode and no characters
-are immediately available.
-@item
-return 0 if the request is for 0 bytes, with no
-end-of-file check.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
-@deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
-Write characters from a string @var{str} to a port or file
-descriptor. A port must have an underlying file descriptor
---- a so-called fport. This procedure is
-scsh-compatible and can efficiently write large strings.
-It will:
-
-@itemize
-@item
-attempt to write the entire string, unless the @var{start}
-and/or @var{end} arguments are supplied. i.e., @var{start}
-defaults to 0 and @var{end} defaults to
-@code{(string-length str)}
-@item
-use the current output port if @var{port_of_fdes} is not
-supplied.
-@item
-in the case of a buffered port, store the characters in the
-port's output buffer, if all will fit. If they will not fit
-then any existing buffered characters will be flushed
-before attempting
-to write the new characters directly to the underlying file
-descriptor. If the port is in non-blocking mode and
-buffered characters can not be flushed immediately, then an
-@code{EAGAIN} system-error exception will be raised (Note:
-scsh does not support the use of non-blocking buffered ports.)
-@item
-write fewer than the requested number of
-characters in some cases, e.g., if interrupted by a signal or
-if not all of the output can be accepted immediately.
-@item
-wait indefinitely for at least one character
-from @var{str} to be accepted by the port, unless the port is
-in non-blocking mode.
-@item
-return the number of characters accepted by the port.
-@item
-return 0 if the port is in non-blocking mode and can not accept
-at least one character from @var{str} immediately
-@item
-return 0 immediately if the request size is 0 bytes.
-@end itemize
-@end deffn
-
-@node Default Ports
-@section Default Ports for Input, Output and Errors
-
-@rnindex current-input-port
-@deffn {Scheme Procedure} current-input-port
-@deffnx {C Function} scm_current_input_port ()
-Return the current input port. This is the default port used
-by many input procedures. Initially, @code{current-input-port}
-returns the @dfn{standard input} in Unix and C terminology.
-@end deffn
-
-@rnindex current-output-port
-@deffn {Scheme Procedure} current-output-port
-@deffnx {C Function} scm_current_output_port ()
-Return the current output port. This is the default port used
-by many output procedures. Initially,
-@code{current-output-port} returns the @dfn{standard output} in
-Unix and C terminology.
-@end deffn
-
-@deffn {Scheme Procedure} current-error-port
-@deffnx {C Function} scm_current_error_port ()
-Return the port to which errors and warnings should be sent (the
-@dfn{standard error} in Unix and C terminology).
-@end deffn
-
-@deffn {Scheme Procedure} set-current-input-port port
-@deffnx {Scheme Procedure} set-current-output-port port
-@deffnx {Scheme Procedure} set-current-error-port port
-@deffnx {C Function} scm_set_current_input_port (port)
-@deffnx {C Function} scm_set_current_output_port (port)
-@deffnx {C Function} scm_set_current_error_port (port)
-Change the ports returned by @code{current-input-port},
-@code{current-output-port} and @code{current-error-port}, respectively,
-so that they use the supplied @var{port} for input or output.
-@end deffn
-
-@deffn {Scheme Procedure} set-current-output-port port
-Set the current default output port to PORT.
-@end deffn
-
-@deffn {Scheme Procedure} set-current-error-port port
-Set the current default error port to PORT.
-@end deffn
-
-
-@node Port Types
-@section Types of Port
-
-[Types of port; how to make them.]
-
-@menu
-* File Ports:: Ports on an operating system file.
-* String Ports:: Ports on a Scheme string.
-* Soft Ports:: Ports on arbitrary Scheme procedures.
-* Void Ports:: Ports on nothing at all.
-@end menu
-
-
-@node File Ports
-@subsection File Ports
-
-The following procedures are used to open file ports.
-See also @ref{Ports and File Descriptors, open}, for an interface
-to the Unix @code{open} system call.
-
-@deffn {Scheme Procedure} open-file filename mode
-@deffnx {C Function} scm_open_file (filename, mode)
-Open the file whose name is @var{filename}, and return a port
-representing that file. The attributes of the port are
-determined by the @var{mode} string. The way in which this is
-interpreted is similar to C stdio. The first character must be
-one of the following:
-@table @samp
-@item r
-Open an existing file for input.
-@item w
-Open a file for output, creating it if it doesn't already exist
-or removing its contents if it does.
-@item a
-Open a file for output, creating it if it doesn't already
-exist. All writes to the port will go to the end of the file.
-The "append mode" can be turned off while the port is in use
-@pxref{Ports and File Descriptors, fcntl}
-@end table
-The following additional characters can be appended:
-@table @samp
-@item +
-Open the port for both input and output. E.g., @code{r+}: open
-an existing file for both input and output.
-@item 0
-Create an "unbuffered" port. In this case input and output
-operations are passed directly to the underlying port
-implementation without additional buffering. This is likely to
-slow down I/O operations. The buffering mode can be changed
-while a port is in use @pxref{Ports and File Descriptors,
-setvbuf}
-@item l
-Add line-buffering to the port. The port output buffer will be
-automatically flushed whenever a newline character is written.
-@end table
-In theory we could create read/write ports which were buffered
-in one direction only. However this isn't included in the
-current interfaces. If a file cannot be opened with the access
-requested, @code{open-file} throws an exception.
-@end deffn
-
-@rnindex open-input-file
-@deffn {Scheme Procedure} open-input-file filename
-Open @var{filename} for input. Equivalent to
-@smalllisp
-(open-file @var{filename} "r")
-@end smalllisp
-@end deffn
-
-@rnindex open-output-file
-@deffn {Scheme Procedure} open-output-file filename
-Open @var{filename} for output. Equivalent to
-@smalllisp
-(open-file @var{filename} "w")
-@end smalllisp
-@end deffn
-
-@rnindex call-with-input-file
-@deffn {Scheme Procedure} call-with-input-file file proc
-@var{proc} should be a procedure of one argument, and @var{file} should
-be a string naming a file. The file must already exist. These
-procedures call @var{proc} with one argument: the port obtained by
-opening the named file for input or output. If the file cannot be
-opened, an error is signalled. If the procedure returns, then the port
-is closed automatically and the value yielded by the procedure is
-returned. If the procedure does not return, then the port will not be
-closed automatically unless it is possible to prove that the port will
-never again be used for a read or write operation.
-@end deffn
-
-@rnindex call-with-output-file
-@deffn {Scheme Procedure} call-with-output-file file proc
-@var{proc} should be a procedure of one argument, and @var{file} should
-be a string naming a file. The behaviour is unspecified if the file
-already exists. These procedures call @var{proc} with one argument: the
-port obtained by opening the named file for input or output. If the
-file cannot be opened, an error is signalled. If the procedure returns,
-then the port is closed automatically and the value yielded by the
-procedure is returned. If the procedure does not return, then the port
-will not be closed automatically unless it is possible to prove that the
-port will never again be used for a read or write operation.
-@end deffn
-
-@rnindex with-input-from-file
-@deffn {Scheme Procedure} with-input-from-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file. The file must already exist. The file is opened
-for input, an input port connected to it is made the default value
-returned by @code{current-input-port}, and the @var{thunk} is called
-with no arguments. When the @var{thunk} returns, the port is closed and
-the previous default is restored. Returns the value yielded by
-@var{thunk}. If an escape procedure is used to escape from the
-continuation of these procedures, their behavior is implementation
-dependent.
-@end deffn
-
-@rnindex with-output-to-file
-@deffn {Scheme Procedure} with-output-to-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file. The effect is unspecified if the file already
-exists. The file is opened for output, an output port connected to it
-is made the default value returned by @code{current-output-port}, and
-the @var{thunk} is called with no arguments. When the @var{thunk}
-returns, the port is closed and the previous default is restored.
-Returns the value yielded by @var{thunk}. If an escape procedure is
-used to escape from the continuation of these procedures, their behavior
-is implementation dependent.
-@end deffn
-
-@deffn {Scheme Procedure} with-error-to-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file. The effect is unspecified if the file already
-exists. The file is opened for output, an output port connected to it
-is made the default value returned by @code{current-error-port}, and the
-@var{thunk} is called with no arguments. When the @var{thunk} returns,
-the port is closed and the previous default is restored. Returns the
-value yielded by @var{thunk}. If an escape procedure is used to escape
-from the continuation of these procedures, their behavior is
-implementation dependent.
-@end deffn
-
-@deffn {Scheme Procedure} port-mode port
-@deffnx {C Function} scm_port_mode (port)
-Return the port modes associated with the open port @var{port}.
-These will not necessarily be identical to the modes used when
-the port was opened, since modes such as "append" which are
-used only during port creation are not retained.
-@end deffn
-
-@deffn {Scheme Procedure} port-filename port
-@deffnx {C Function} scm_port_filename (port)
-Return the filename associated with @var{port}. This function returns
-the strings "standard input", "standard output" and "standard error"
-when called on the current input, output and error ports respectively.
-@end deffn
-
-@deffn {Scheme Procedure} set-port-filename! port filename
-@deffnx {C Function} scm_set_port_filename_x (port, filename)
-Change the filename associated with @var{port}, using the current input
-port if none is specified. Note that this does not change the port's
-source of data, but only the value that is returned by
-@code{port-filename} and reported in diagnostic output.
-@end deffn
-
-@deffn {Scheme Procedure} file-port? obj
-@deffnx {C Function} scm_file_port_p (obj)
-Determine whether @var{obj} is a port that is related to a file.
-@end deffn
-
-
-@node String Ports
-@subsection String Ports
-
-The following allow string ports to be opened by analogy to R4R*
-file port facilities:
-
-@deffn {Scheme Procedure} call-with-output-string proc
-@deffnx {C Function} scm_call_with_output_string (proc)
-Calls the one-argument procedure @var{proc} with a newly created output
-port. When the function returns, the string composed of the characters
-written into the port is returned.
-@end deffn
-
-@deffn {Scheme Procedure} call-with-input-string string proc
-@deffnx {C Function} scm_call_with_input_string (string, proc)
-Calls the one-argument procedure @var{proc} with a newly
-created input port from which @var{string}'s contents may be
-read. The value yielded by the @var{proc} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} with-output-to-string thunk
-Calls the zero-argument procedure @var{thunk} with the current output
-port set temporarily to a new string port. It returns a string
-composed of the characters written to the current output.
-@end deffn
-
-@deffn {Scheme Procedure} with-input-from-string string thunk
-Calls the zero-argument procedure @var{thunk} with the current input
-port set temporarily to a string port opened on the specified
-@var{string}. The value yielded by @var{thunk} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} open-input-string str
-@deffnx {C Function} scm_open_input_string (str)
-Take a string and return an input port that delivers characters
-from the string. The port can be closed by
-@code{close-input-port}, though its storage will be reclaimed
-by the garbage collector if it becomes inaccessible.
-@end deffn
-
-@deffn {Scheme Procedure} open-output-string
-@deffnx {C Function} scm_open_output_string ()
-Return an output port that will accumulate characters for
-retrieval by @code{get-output-string}. The port can be closed
-by the procedure @code{close-output-port}, though its storage
-will be reclaimed by the garbage collector if it becomes
-inaccessible.
-@end deffn
-
-@deffn {Scheme Procedure} get-output-string port
-@deffnx {C Function} scm_get_output_string (port)
-Given an output port created by @code{open-output-string},
-return a string consisting of the characters that have been
-output to the port so far.
-@end deffn
-
-A string port can be used in many procedures which accept a port
-but which are not dependent on implementation details of fports.
-E.g., seeking and truncating will work on a string port,
-but trying to extract the file descriptor number will fail.
-
-
-@node Soft Ports
-@subsection Soft Ports
-
-A @dfn{soft-port} is a port based on a vector of procedures capable of
-accepting or delivering characters. It allows emulation of I/O ports.
-
-@deffn {Scheme Procedure} make-soft-port pv modes
-@deffnx {C Function} scm_make_soft_port (pv, modes)
-Return a port capable of receiving or delivering characters as
-specified by the @var{modes} string (@pxref{File Ports,
-open-file}). @var{pv} must be a vector of length 5. Its
-components are as follows:
-
-@enumerate 0
-@item
-procedure accepting one character for output
-@item
-procedure accepting a string for output
-@item
-thunk for flushing output
-@item
-thunk for getting one character
-@item
-thunk for closing port (not by garbage collection)
-@end enumerate
-
-For an output-only port only elements 0, 1, 2, and 4 need be
-procedures. For an input-only port only elements 3 and 4 need
-be procedures. Thunks 2 and 4 can instead be @code{#f} if
-there is no useful operation for them to perform.
-
-If thunk 3 returns @code{#f} or an @code{eof-object}
-(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
-Scheme}) it indicates that the port has reached end-of-file.
-For example:
-
-@lisp
-(define stdout (current-output-port))
-(define p (make-soft-port
- (vector
- (lambda (c) (write c stdout))
- (lambda (s) (display s stdout))
- (lambda () (display "." stdout))
- (lambda () (char-upcase (read-char)))
- (lambda () (display "@@" stdout)))
- "rw"))
-
-(write p p) @result{} #<input-output: soft 8081e20>
-@end lisp
-@end deffn
-
-
-@node Void Ports
-@subsection Void Ports
-
-This kind of port causes any data to be discarded when written to, and
-always returns the end-of-file object when read from.
-
-@deffn {Scheme Procedure} %make-void-port mode
-@deffnx {C Function} scm_sys_make_void_port (mode)
-Create and return a new void port. A void port acts like
-@file{/dev/null}. The @var{mode} argument
-specifies the input/output modes for this port: see the
-documentation for @code{open-file} in @ref{File Ports}.
-@end deffn
-
-
-@node I/O Extensions
-@section Using and Extending Ports in C
-
-@menu
-* C Port Interface:: Using ports from C.
-* Port Implementation:: How to implement a new port type in C.
-@end menu
-
-
-@node C Port Interface
-@subsection C Port Interface
-
-This section describes how to use Scheme ports from C.
-
-@subsubsection Port basics
-
-There are two main data structures. A port type object (ptob) is of
-type @code{scm_ptob_descriptor}. A port instance is of type
-@code{scm_port}. Given an @code{SCM} variable which points to a port,
-the corresponding C port object can be obtained using the
-@code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
-@code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
-global array.
-
-@subsubsection Port buffers
-
-An input port always has a read buffer and an output port always has a
-write buffer. However the size of these buffers is not guaranteed to be
-more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
-which is used when no other buffer is allocated). The way in which the
-buffers are allocated depends on the implementation of the ptob. For
-example in the case of an fport, buffers may be allocated with malloc
-when the port is created, but in the case of an strport the underlying
-string is used as the buffer.
-
-@subsubsection The @code{rw_random} flag
-
-Special treatment is required for ports which can be seeked at random.
-Before various operations, such as seeking the port or changing from
-input to output on a bidirectional port or vice versa, the port
-implementation must be given a chance to update its state. The write
-buffer is updated by calling the @code{flush} ptob procedure and the
-input buffer is updated by calling the @code{end_input} ptob procedure.
-In the case of an fport, @code{flush} causes buffered output to be
-written to the file descriptor, while @code{end_input} causes the
-descriptor position to be adjusted to account for buffered input which
-was never read.
-
-The special treatment must be performed if the @code{rw_random} flag in
-the port is non-zero.
-
-@subsubsection The @code{rw_active} variable
-
-The @code{rw_active} variable in the port is only used if
-@code{rw_random} is set. It's defined as an enum with the following
-values:
-
-@table @code
-@item SCM_PORT_READ
-the read buffer may have unread data.
-
-@item SCM_PORT_WRITE
-the write buffer may have unwritten data.
-
-@item SCM_PORT_NEITHER
-neither the write nor the read buffer has data.
-@end table
-
-@subsubsection Reading from a port.
-
-To read from a port, it's possible to either call existing libguile
-procedures such as @code{scm_getc} and @code{scm_read_line} or to read
-data from the read buffer directly. Reading from the buffer involves
-the following steps:
-
-@enumerate
-@item
-Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
-
-@item
-Fill the read buffer, if it's empty, using @code{scm_fill_input}.
-
-@item Read the data from the buffer and update the read position in
-the buffer. Steps 2) and 3) may be repeated as many times as required.
-
-@item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
-
-@item update the port's line and column counts.
-@end enumerate
-
-@subsubsection Writing to a port.
-
-To write data to a port, calling @code{scm_lfwrite} should be sufficient for
-most purposes. This takes care of the following steps:
-
-@enumerate
-@item
-End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
-
-@item
-Pass the data to the ptob implementation using the @code{write} ptob
-procedure. The advantage of using the ptob @code{write} instead of
-manipulating the write buffer directly is that it allows the data to be
-written in one operation even if the port is using the single-byte
-@code{shortbuf}.
-
-@item
-Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
-is set.
-@end enumerate
-
-
-@node Port Implementation
-@subsection Port Implementation
-
-This section describes how to implement a new port type in C.
-
-As described in the previous section, a port type object (ptob) is
-a structure of type @code{scm_ptob_descriptor}. A ptob is created by
-calling @code{scm_make_port_type}.
-
-All of the elements of the ptob, apart from @code{name}, are procedures
-which collectively implement the port behaviour. Creating a new port
-type mostly involves writing these procedures.
-
-@code{scm_make_port_type} initializes three elements of the structure
-(@code{name}, @code{fill_input} and @code{write}) from its arguments.
-The remaining elements are initialized with default values and can be
-set later if required.
-
-@table @code
-@item name
-A pointer to a NUL terminated string: the name of the port type. This
-is the only element of @code{scm_ptob_descriptor} which is not
-a procedure. Set via the first argument to @code{scm_make_port_type}.
-
-@item mark
-Called during garbage collection to mark any SCM objects that a port
-object may contain. It doesn't need to be set unless the port has
-@code{SCM} components. Set using @code{scm_set_port_mark}.
-
-@item free
-Called when the port is collected during gc. It
-should free any resources used by the port.
-Set using @code{scm_set_port_free}.
-
-@item print
-Called when @code{write} is called on the port object, to print a
-port description. e.g., for an fport it may produce something like:
-@code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}.
-
-@item equalp
-Not used at present. Set using @code{scm_set_port_equalp}.
-
-@item close
-Called when the port is closed, unless it was collected during gc. It
-should free any resources used by the port.
-Set using @code{scm_set_port_close}.
-
-@item write
-Accept data which is to be written using the port. The port implementation
-may choose to buffer the data instead of processing it directly.
-Set via the third argument to @code{scm_make_port_type}.
-
-@item flush
-Complete the processing of buffered output data. Reset the value of
-@code{rw_active} to @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_flush}.
-
-@item end_input
-Perform any synchronization required when switching from input to output
-on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_end_input}.
-
-@item fill_input
-Read new data into the read buffer and return the first character. It
-can be assumed that the read buffer is empty when this procedure is called.
-Set via the second argument to @code{scm_make_port_type}.
-
-@item input_waiting
-Return a lower bound on the number of bytes that could be read from the
-port without blocking. It can be assumed that the current state of
-@code{rw_active} is @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_input_waiting}.
-
-@item seek
-Set the current position of the port. The procedure can not make
-any assumptions about the value of @code{rw_active} when it's
-called. It can reset the buffers first if desired by using something
-like:
-
-@example
- if (pt->rw_active == SCM_PORT_READ)
- scm_end_input (object);
- else if (pt->rw_active == SCM_PORT_WRITE)
- ptob->flush (object);
-@end example
-
-However note that this will have the side effect of discarding any data
-in the unread-char buffer, in addition to any side effects from the
-@code{end_input} and @code{flush} ptob procedures. This is undesirable
-when seek is called to measure the current position of the port, i.e.,
-@code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
-implementations take care to avoid this problem.
-
-The procedure is set using @code{scm_set_port_seek}.
-
-@item truncate
-Truncate the port data to be specified length. It can be assumed that the
-current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_truncate}.
-
-@end table
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-memory.texi b/doc/ref/scheme-memory.texi
deleted file mode 100644
index d6f0584c6..000000000
--- a/doc/ref/scheme-memory.texi
+++ /dev/null
@@ -1,396 +0,0 @@
-@page
-@node Memory Management
-@chapter Memory Management and Garbage Collection
-
-@menu
-* Garbage Collection::
-* Memory Blocks::
-* Weak References::
-* Guardians::
-@end menu
-
-
-@node Garbage Collection
-@section Garbage Collection
-
-@deffn {Scheme Procedure} gc
-@deffnx {C Function} scm_gc ()
-Scans all of SCM objects and reclaims for further use those that are
-no longer accessible. You normally don't need to call this function
-explicitely. It is called automatically when appropriate.
-@end deffn
-
-@deffn {Scheme Procedure} gc-stats
-@deffnx {C Function} scm_gc_stats ()
-Return an association list of statistics about Guile's current
-use of storage.
-@end deffn
-
-
-@node Memory Blocks
-@section Memory Blocks
-
-In C programs, dynamic management of memory blocks is normally done
-with the functions malloc, realloc, and free. Guile has additional
-functions for dynamic memory allocation that are integrated into the
-garbage collector and the error reporting system.
-
-Memory blocks that are associated with Scheme objects (for example a
-smob) should be allocated and freed with @code{scm_gc_malloc} and
-@code{scm_gc_free}. The function @code{scm_gc_malloc} will either
-return a valid pointer or signal an error. It will also assume that
-the new memory can be freed by a garbage collection. The garbage
-collector uses this information to decide when to try to actually
-collect some garbage. Memory blocks allocated with
-@code{scm_gc_malloc} must be freed with @code{scm_gc_free}.
-
-For memory that is not associated with a Scheme object, you can use
-@code{scm_malloc} instead of @code{malloc}. Like
-@code{scm_gc_malloc}, it will either return a valid pointer or signal
-an error. However, it will not assume that the new memory block can
-be freed by a garbage collection. The memory can be freed with
-@code{free}.
-
-There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
-in place of @code{realloc} when appropriate.
-
-For really specialized needs, take at look at
-@code{scm_gc_register_collectable_memory} and
-@code{scm_gc_unregister_collectable_memory}.
-
-@deftypefn {C Function} void *scm_malloc (size_t @var{size})
-Allocate @var{size} bytes of memory and return a pointer to it. When
-@var{size} is 0, return @code{NULL}. When not enough memory is
-available, signal an error. This function runs the GC to free up some
-memory when it deems it appropriate.
-
-The memory is allocated by the libc @code{malloc} function and can be
-freed with @code{free}. There is no @code{scm_free} function to go
-with @code{scm_malloc} to make it easier to pass memory back and forth
-between different modules.
-@end deftypefn
-
-@deftypefn {C Function} void *scm_realloc (void *@var{mem}, size_t @var{new_size})
-Change the size of the memory block at @var{mem} to @var{new_size} and
-return its new location. When @var{new_size} is 0, this is the same
-as calling @code{free} on @var{mem} and @code{NULL} is returned. When
-@var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
-and allocates a new block of size @var{new_size}.
-
-When not enough memory is available, signal an error. This function
-runs the GC to free up some memory when it deems it appropriate.
-@end deftypefn
-
-@deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
-Informs the GC that the memory at @var{mem} of size @var{size} can
-potentially be freed during a GC. That is, announce that @var{mem} is
-part of a GC controlled object and when the GC happens to free that
-object, @var{size} bytes will be freed along with it. The GC will
-@strong{not} free the memory itself, it will just know that so-and-so
-much bytes of memory are associated with GC controlled objects and the
-memory system figures this into its decisions when to run a GC.
-
-@var{mem} does not need to come from @code{scm_malloc}. You can only
-call this function once for every memory block.
-
-The @var{what} argument is used for statistical purposes. It should
-describe the type of object that the memory will be used for so that
-users can identify just what strange objects are eating up their
-memory.
-@end deftypefn
-
-@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
-Informs the GC that the memory at @var{mem} of size @var{size} is no
-longer associated with a GC controlled object. You must take care to
-match up every call to @code{scm_gc_register_collectable_memory} with
-a call to @code{scm_gc_unregister_collectable_memory}. If you don't do
-this, the GC might have a wrong impression of what is going on and run
-much less efficiently than it could.
-@end deftypefn
-
-@deftypefn {C Function} void *scm_gc_malloc (size_t @var{size}, const char *@var{what})
-@deftypefnx {C Function} void *scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
-Like @code{scm_malloc} or @code{scm_realloc}, but also call
-@code{scm_gc_register_collectable_memory}. Note that you need to pass
-the old size of a reallocated memory block as well. See below for a
-motivation.
-@end deftypefn
-
-@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
-Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
-
-Note that you need to explicitely pass the @var{size} parameter. This
-is done since it should normally be easy to provide this parameter
-(for memory that is associated with GC controlled objects) and this
-frees us from tracking this value in the GC itself, which will keep
-the memory management overhead very low.
-@end deftypefn
-
-@deffn {Scheme Procedure} malloc-stats
-Return an alist ((@var{what} . @var{n}) ...) describing number
-of malloced objects.
-@var{what} is the second argument to @code{scm_gc_malloc},
-@var{n} is the number of objects of that type currently
-allocated.
-@end deffn
-
-
-@subsection Upgrading from scm_must_malloc et al.
-
-Version 1.6 of Guile and earlier did not have the functions from the
-previous section. In their place, it had the functions
-@code{scm_must_malloc}, @code{scm_must_realloc} and
-@code{scm_must_free}. This section explains why we want you to stop
-using them, and how to do this.
-
-The functions @code{scm_must_malloc} and @code{scm_must_realloc}
-behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
-respectively. They would inform the GC about the newly allocated
-memory via the internal equivalent of
-@code{scm_gc_register_collectable_memory}. However,
-@code{scm_must_free} did not unregister the memory it was about to
-free. The usual way to unregister memory was to return its size from
-a smob free function.
-
-This disconnectedness of the actual freeing of memory and reporting
-this to the GC proved to be bad in practice. It was easy to make
-mistakes and report the wrong size because allocating and freeing was
-not done with symmetric code, and because it is cumbersome to compute
-the total size of nested data structures that were freed with multiple
-calls to @code{scm_must_free}. Additionally, there was no equivalent
-to @code{scm_malloc}, and it was tempting to just use
-@code{scm_must_malloc} and never to tell the GC that the memory has
-been freed.
-
-The effect was that the internal statistics kept by the GC drifted out
-of sync with reality and could even overflow in long running programs.
-When this happened, the result was a dramatic increase in (senseless)
-GC activity which would effectively stop the program dead.
-
-The functions @code{scm_done_malloc} and @code{scm_done_free} were
-introduced to help restore balance to the force, but existing bugs did
-not magically disappear, of course.
-
-Therefore we decided to force everybody to review their code by
-deprecating the existing functions and introducing new ones in their
-place that are hopefully easier to use correctly.
-
-For every use of @code{scm_must_malloc} you need to decide whether to
-use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the
-memory block is not part of a smob or some other Scheme object whose
-lifetime is ultimately managed by the garbage collector, use
-@code{scm_malloc} and @code{free}. When it is part of a smob, use
-@code{scm_gc_malloc} and change the smob free function to use
-@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
-make it return zero.
-
-The important thing is to always pair @code{scm_malloc} with
-@code{free}; and to always pair @code{scm_gc_malloc} with
-@code{scm_gc_free}.
-
-The same reasoning applies to @code{scm_must_realloc} and
-@code{scm_realloc} versus @code{scm_gc_realloc}.
-
-
-@node Weak References
-@section Weak References
-
-[FIXME: This chapter is based on Mikael Djurfeldt's answer to a
-question by Michael Livshin. Any mistakes are not theirs, of course. ]
-
-Weak references let you attach bookkeeping information to data so that
-the additional information automatically disappears when the original
-data is no longer in use and gets garbage collected. In a weak key hash,
-the hash entry for that key disappears as soon as the key is no longer
-referenced from anywhere else. For weak value hashes, the same happens
-as soon as the value is no longer in use. Entries in a doubly weak hash
-disappear when either the key or the value are not used anywhere else
-anymore.
-
-Object properties offer the same kind of functionality as weak key
-hashes in many situations. (@pxref{Object Properties})
-
-Here's an example (a little bit strained perhaps, but one of the
-examples is actually used in Guile):
-
-Assume that you're implementing a debugging system where you want to
-associate information about filename and position of source code
-expressions with the expressions themselves.
-
-Hashtables can be used for that, but if you use ordinary hash tables
-it will be impossible for the scheme interpreter to "forget" old
-source when, for example, a file is reloaded.
-
-To implement the mapping from source code expressions to positional
-information it is necessary to use weak-key tables since we don't want
-the expressions to be remembered just because they are in our table.
-
-To implement a mapping from source file line numbers to source code
-expressions you would use a weak-value table.
-
-To implement a mapping from source code expressions to the procedures
-they constitute a doubly-weak table has to be used.
-
-@menu
-* Weak key hashes::
-* Weak vectors::
-@end menu
-
-
-@node Weak key hashes
-@subsection Weak key hashes
-
-@deffn {Scheme Procedure} make-weak-key-hash-table size
-@deffnx {Scheme Procedure} make-weak-value-hash-table size
-@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
-@deffnx {C Function} scm_make_weak_key_hash_table (size)
-@deffnx {C Function} scm_make_weak_value_hash_table (size)
-@deffnx {C Function} scm_make_doubly_weak_hash_table (size)
-Return a weak hash table with @var{size} buckets. As with any
-hash table, choosing a good size for the table requires some
-caution.
-
-You can modify weak hash tables in exactly the same way you
-would modify regular hash tables. (@pxref{Hash Tables})
-@end deffn
-
-@deffn {Scheme Procedure} weak-key-hash-table? obj
-@deffnx {Scheme Procedure} weak-value-hash-table? obj
-@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
-@deffnx {C Function} scm_weak_key_hash_table_p (obj)
-@deffnx {C Function} scm_weak_value_hash_table_p (obj)
-@deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
-Return @code{#t} if @var{obj} is the specified weak hash
-table. Note that a doubly weak hash table is neither a weak key
-nor a weak value hash table.
-@end deffn
-
-@deffn {Scheme Procedure} make-weak-value-hash-table k
-@end deffn
-
-@deffn {Scheme Procedure} weak-value-hash-table? x
-@end deffn
-
-@deffn {Scheme Procedure} make-doubly-weak-hash-table k
-@end deffn
-
-@deffn {Scheme Procedure} doubly-weak-hash-table? x
-@end deffn
-
-
-@node Weak vectors
-@subsection Weak vectors
-
-Weak vectors are mainly useful in Guile's implementation of weak hash
-tables.
-
-@deffn {Scheme Procedure} make-weak-vector size [fill]
-@deffnx {C Function} scm_make_weak_vector (size, fill)
-Return a weak vector with @var{size} elements. If the optional
-argument @var{fill} is given, all entries in the vector will be
-set to @var{fill}. The default value for @var{fill} is the
-empty list.
-@end deffn
-
-@deffn {Scheme Procedure} weak-vector . l
-@deffnx {Scheme Procedure} list->weak-vector l
-@deffnx {C Function} scm_weak_vector (l)
-Construct a weak vector from a list: @code{weak-vector} uses
-the list of its arguments while @code{list->weak-vector} uses
-its only argument @var{l} (a list) to construct a weak vector
-the same way @code{list->vector} would.
-@end deffn
-
-@deffn {Scheme Procedure} weak-vector? obj
-@deffnx {C Function} scm_weak_vector_p (obj)
-Return @code{#t} if @var{obj} is a weak vector. Note that all
-weak hashes are also weak vectors.
-@end deffn
-
-
-@node Guardians
-@section Guardians
-
-@deffn {Scheme Procedure} make-guardian [greedy?]
-@deffnx {C Function} scm_make_guardian (greedy_p)
-Create a new guardian.
-A guardian protects a set of objects from garbage collection,
-allowing a program to apply cleanup or other actions.
-
-@code{make-guardian} returns a procedure representing the guardian.
-Calling the guardian procedure with an argument adds the
-argument to the guardian's set of protected objects.
-Calling the guardian procedure without an argument returns
-one of the protected objects which are ready for garbage
-collection, or @code{#f} if no such object is available.
-Objects which are returned in this way are removed from
-the guardian.
-
-@code{make-guardian} takes one optional argument that says whether the
-new guardian should be greedy or sharing. If there is any chance
-that any object protected by the guardian may be resurrected,
-then you should make the guardian greedy (this is the default).
-
-See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
-"Guardians in a Generation-Based Garbage Collector".
-ACM SIGPLAN Conference on Programming Language Design
-and Implementation, June 1993.
-
-(the semantics are slightly different at this point, but the
-paper still (mostly) accurately describes the interface).
-@end deffn
-
-@deffn {Scheme Procedure} destroy-guardian! guardian
-@deffnx {C Function} scm_destroy_guardian_x (guardian)
-Destroys @var{guardian}, by making it impossible to put any more
-objects in it or get any objects from it. It also unguards any
-objects guarded by @var{guardian}.
-@end deffn
-
-@deffn {Scheme Procedure} guardian-greedy? guardian
-@deffnx {C Function} scm_guardian_greedy_p (guardian)
-Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} guardian-destroyed? guardian
-@deffnx {C Function} scm_guardian_destroyed_p (guardian)
-Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
-@end deffn
-
-
-@page
-@node Objects
-@chapter Objects
-
-@deffn {Scheme Procedure} entity? obj
-@deffnx {C Function} scm_entity_p (obj)
-Return @code{#t} if @var{obj} is an entity.
-@end deffn
-
-@deffn {Scheme Procedure} operator? obj
-@deffnx {C Function} scm_operator_p (obj)
-Return @code{#t} if @var{obj} is an operator.
-@end deffn
-
-@deffn {Scheme Procedure} set-object-procedure! obj proc
-@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
-Set the object procedure of @var{obj} to @var{proc}.
-@var{obj} must be either an entity or an operator.
-@end deffn
-
-@deffn {Scheme Procedure} make-class-object metaclass layout
-@deffnx {C Function} scm_make_class_object (metaclass, layout)
-Create a new class object of class @var{metaclass}, with the
-slot layout specified by @var{layout}.
-@end deffn
-
-@deffn {Scheme Procedure} make-subclass-object class layout
-@deffnx {C Function} scm_make_subclass_object (class, layout)
-Create a subclass object of @var{class}, with the slot layout
-specified by @var{layout}.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi
deleted file mode 100644
index c9279258c..000000000
--- a/doc/ref/scheme-modules.texi
+++ /dev/null
@@ -1,909 +0,0 @@
-@page
-@node Modules
-@chapter Modules
-@cindex modules
-
-When programs become large, naming conflicts can occur when a function
-or global variable defined in one file has the same name as a function
-or global variable in another file. Even just a @emph{similarity}
-between function names can cause hard-to-find bugs, since a programmer
-might type the wrong function name.
-
-The approach used to tackle this problem is called @emph{information
-encapsulation}, which consists of packaging functional units into a
-given name space that is clearly separated from other name spaces.
-@cindex encapsulation
-@cindex information encapsulation
-@cindex name space
-
-The language features that allow this are usually called @emph{the
-module system} because programs are broken up into modules that are
-compiled separately (or loaded separately in an interpreter).
-
-Older languages, like C, have limited support for name space
-manipulation and protection. In C a variable or function is public by
-default, and can be made local to a module with the @code{static}
-keyword. But you cannot reference public variables and functions from
-another module with different names.
-
-More advanced module systems have become a common feature in recently
-designed languages: ML, Python, Perl, and Modula 3 all allow the
-@emph{renaming} of objects from a foreign module, so they will not
-clutter the global name space.
-@cindex name space - private
-
-In addition, Guile offers variables as first-class objects. They can
-be used for interacting with the module system.
-
-@menu
-* provide and require:: The SLIB feature mechanism.
-* Environments:: R5RS top-level environments.
-* The Guile module system:: How Guile does it.
-* Dynamic Libraries:: Loading libraries of compiled code at run time.
-* Variables:: First-class variables.
-@end menu
-
-@node provide and require
-@section provide and require
-
-Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
-implemented a provide/require mechanism for many Scheme implementations.
-Library files in SLIB @emph{provide} a feature, and when user programs
-@emph{require} that feature, the library file is loaded in.
-
-For example, the file @file{random.scm} in the SLIB package contains the
-line
-
-@smalllisp
-(provide 'random)
-@end smalllisp
-
-so to use its procedures, a user would type
-
-@smalllisp
-(require 'random)
-@end smalllisp
-
-and they would magically become available, @emph{but still have the same
-names!} So this method is nice, but not as good as a full-featured
-module system.
-
-When SLIB is used with Guile, provide and require can be used to access
-its facilities.
-
-@node Environments
-@section Environments
-@cindex environment
-
-Scheme, as defined in R5RS, does @emph{not} have a full module system.
-However it does define the concept of a top-level @dfn{environment}.
-Such an environment maps identifiers (symbols) to Scheme objects such
-as procedures and lists: @ref{About Closure}. In other words, it
-implements a set of @dfn{bindings}.
-
-Environments in R5RS can be passed as the second argument to
-@code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to
-return environments: @code{scheme-report-environment},
-@code{null-environment} and @code{interaction-environment} (@pxref{Fly
-Evaluation}).
-
-In addition, in Guile any module can be used as an R5RS environment,
-i.e., passed as the second argument to @code{eval}.
-
-@deffn {Scheme Procedure} scheme-report-environment version
-@deffnx {Scheme Procedure} null-environment version
-@var{version} must be the exact integer `5', corresponding to revision
-5 of the Scheme report (the Revised^5 Report on Scheme).
-@code{scheme-report-environment} returns a specifier for an
-environment that is empty except for all bindings defined in the
-report that are either required or both optional and supported by the
-implementation. @code{null-environment} returns a specifier for an
-environment that is empty except for the (syntactic) bindings for all
-syntactic keywords defined in the report that are either required or
-both optional and supported by the implementation.
-
-Currently Guile does not support values of @var{version} for other
-revisions of the report.
-
-The effect of assigning (through the use of @code{eval}) a variable
-bound in a @code{scheme-report-environment} (for example @code{car})
-is unspecified. Currently the environments specified by
-@code{scheme-report-environment} are not immutable in Guile.
-@end deffn
-
-@node The Guile module system
-@section The Guile module system
-
-The Guile module system extends the concept of environments, discussed
-in the previous section, with mechanisms to define, use and customise
-sets of bindings.
-
-In 1996 Tom Lord implemented a full-featured module system for Guile which
-allows loading Scheme source files into a private name space. This system has
-been in available since at least Guile version 1.1.
-
-For Guile version 1.5.0 and later, the system has been improved to have better
-integration from C code, more fine-grained user control over interfaces, and
-documentation.
-
-Although it is anticipated that the module system implementation will
-change in the future, the Scheme programming interface described in this
-manual should be considered stable. The C programming interface is
-considered relatively stable, although at the time of this writing,
-there is still some flux.
-@c fixme: Review: Need better C code interface commentary.
-
-@menu
-* General Information about Modules:: Guile module basics.
-* Using Guile Modules:: How to use existing modules.
-* Creating Guile Modules:: How to package your code into modules.
-* More Module Procedures:: Low-level module code.
-* Module System Quirks:: Strange things to be aware of.
-* Included Guile Modules:: Which modules come with Guile?
-@end menu
-
-@node General Information about Modules
-@subsection General Information about Modules
-
-A Guile module can be thought of as a collection of named procedures,
-variables and macros. More precisely, it is a set of @dfn{bindings}
-of symbols (names) to Scheme objects.
-
-An environment is a mapping from identifiers (or symbols) to locations,
-i.e., a set of bindings.
-There are top-level environments and lexical environments.
-Environment in which a lambda is excuted is remembered as part of its
-definition.
-
-Within a module, all bindings are visible. Certain bindings
-can be declared @dfn{public}, in which case they are added to the
-module's so-called @dfn{export list}; this set of public bindings is
-called the module's @dfn{public interface} (@pxref{Creating Guile
-Modules}).
-
-A client module @dfn{uses} a providing module's bindings by either
-accessing the providing module's public interface, or by building a
-custom interface (and then accessing that). In a custom interface, the
-client module can @dfn{select} which bindings to access and can also
-algorithmically @dfn{rename} bindings. In contrast, when using the
-providing module's public interface, the entire export list is available
-without renaming (@pxref{Using Guile Modules}).
-
-To use a module, it must be found and loaded. All Guile modules have
-a unique @dfn{module name}, which is a list of one or more symbols.
-Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When
-Guile searches for the code of a module, it constructs the name of the
-file to load by concatenating the name elements with slashes between
-the elements and appending a number of file name extensions from the
-list @code{%load-extensions} (@pxref{Loading}). The resulting file
-name is then searched in all directories in the variable
-@code{%load-path} (@pxref{Install Config}). For example, the
-@code{(ice-9 popen)} module would result in the filename
-@code{ice-9/popen.scm} and searched in the installation directories of
-Guile and in all other directories in the load path.
-
-@c FIXME::martin: Not sure about this, maybe someone knows better?
-Every module has a so-called syntax transformer associated with it.
-This is a procedure which performs all syntax transformation for the
-time the module is read in and evaluated. When working with modules,
-you can manipulate the current syntax transformer using the
-@code{use-syntax} syntactic form or the @code{#:use-syntax} module
-definition option (@pxref{Creating Guile Modules}).
-
-Please note that there are some problems with the current module system
-you should keep in mind (@pxref{Module System Quirks}). We hope to
-address these eventually.
-
-
-@node Using Guile Modules
-@subsection Using Guile Modules
-
-To use a Guile module is to access either its public interface or a
-custom interface (@pxref{General Information about Modules}). Both
-types of access are handled by the syntactic form @code{use-modules},
-which accepts one or more interface specifications and, upon
-evaluation, arranges for those interfaces to be available to the
-current module. This process may include locating and loading code
-for a given module if that code has not yet been loaded, following
-%load-path (@pxref{Install Config}).
-
-An @dfn{interface specification} has one of two forms. The first
-variation is simply to name the module, in which case its public
-interface is the one accessed. For example:
-
-@smalllisp
-(use-modules (ice-9 popen))
-@end smalllisp
-
-Here, the interface specification is @code{(ice-9 popen)}, and the
-result is that the current module now has access to @code{open-pipe},
-@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included
-Guile Modules}).
-
-Note in the previous example that if the current module had already
-defined @code{open-pipe}, that definition would be overwritten by the
-definition in @code{(ice-9 popen)}. For this reason (and others), there
-is a second variation of interface specification that not only names a
-module to be accessed, but also selects bindings from it and renames
-them to suit the current module's needs. For example:
-
-@smalllisp
-(use-modules ((ice-9 popen)
- :select ((open-pipe . pipe-open) close-pipe)
- :renamer (symbol-prefix-proc 'unixy:)))
-@end smalllisp
-
-Here, the interface specification is more complex than before, and the
-result is that a custom interface with only two bindings is created and
-subsequently accessed by the current module. The mapping of old to new
-names is as follows:
-
-@c Use `smallexample' since `table' is ugly. --ttn
-@smallexample
-(ice-9 popen) sees: current module sees:
-open-pipe unixy:pipe-open
-close-pipe unixy:close-pipe
-@end smallexample
-
-This example also shows how to use the convenience procedure
-@code{symbol-prefix-proc}.
-
-@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
-@deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
-Return a procedure that prefixes its arg (a symbol) with
-@var{prefix-sym}.
-@c Insert gratuitous C++ slam here. --ttn
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "use-modules")
-@deffn syntax use-modules spec @dots{}
-Resolve each interface specification @var{spec} into an interface and
-arrange for these to be accessible by the current module. The return
-value is unspecified.
-
-@var{spec} can be a list of symbols, in which case it names a module
-whose public interface is found and used.
-
-@var{spec} can also be of the form:
-
-@smalllisp
- (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
-@end smalllisp
-
-in which case a custom interface is newly created and used.
-@var{module-name} is a list of symbols, as above; @var{selection} is a
-list of selection-specs; and @var{renamer} is a procedure that takes a
-symbol and returns its new name. A selection-spec is either a symbol or
-a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
-the used module and @var{seen} is the name in the using module. Note
-that @var{seen} is also passed through @var{renamer}.
-
-The @code{:select} and @code{:renamer} clauses are optional. If both are
-omitted, the returned interface has no bindings. If the @code{:select}
-clause is omitted, @var{renamer} operates on the used module's public
-interface.
-
-Signal error if module name is not resolvable.
-@end deffn
-
-
-@c FIXME::martin: Is this correct, and is there more to say?
-@c FIXME::martin: Define term and concept `system transformer' somewhere.
-
-@deffn syntax use-syntax module-name
-Load the module @code{module-name} and use its system
-transformer as the system transformer for the currently defined module,
-as well as installing it as the current system transformer.
-@end deffn
-
-
-@node Creating Guile Modules
-@subsection Creating Guile Modules
-
-When you want to create your own modules, you have to take the following
-steps:
-
-@itemize @bullet
-@item
-Create a Scheme source file and add all variables and procedures you wish
-to export, or which are required by the exported procedures.
-
-@item
-Add a @code{define-module} form at the beginning.
-
-@item
-Export all bindings which should be in the public interface, either
-by using @code{define-public} or @code{export} (both documented below).
-@end itemize
-
-@c begin (scm-doc-string "boot-9.scm" "define-module")
-@deffn syntax define-module module-name [options @dots{}]
-@var{module-name} is of the form @code{(hierarchy file)}. One
-example of this is
-
-@smalllisp
-(define-module (ice-9 popen))
-@end smalllisp
-
-@code{define-module} makes this module available to Guile programs under
-the given @var{module-name}.
-
-The @var{options} are keyword/value pairs which specify more about the
-defined module. The recognized options and their meaning is shown in
-the following table.
-
-@c fixme: Should we use "#:" or ":"?
-
-@table @code
-@item #:use-module @var{interface-specification}
-Equivalent to a @code{(use-modules @var{interface-specification})}
-(@pxref{Using Guile Modules}).
-
-@item #:use-syntax @var{module}
-Use @var{module} when loading the currently defined module, and install
-it as the syntax transformer.
-
-@item #:autoload @var{module} @var{symbol}
-Load @var{module} whenever @var{symbol} is accessed.
-
-@item #:export @var{list}
-Export all identifiers in @var{list}, which must be a list of symbols.
-This is equivalent to @code{(export @var{list})} in the module body.
-
-@item #:no-backtrace
-Tell Guile not to record information for procedure backtraces when
-executing the procedures in this module.
-
-@item #:pure
-Create a @dfn{pure} module, that is a module which does not contain any
-of the standard procedure bindings except for the syntax forms. This is
-useful if you want to create @dfn{safe} modules, that is modules which
-do not know anything about dangerous procedures.
-@end table
-
-@end deffn
-@c end
-
-@deffn syntax export variable @dots{}
-Add all @var{variable}s (which must be symbols) to the list of exported
-bindings of the current module.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "define-public")
-@deffn syntax define-public @dots{}
-Equivalent to @code{(begin (define foo ...) (export foo))}.
-@end deffn
-@c end
-
-
-@node More Module Procedures
-@subsection More Module Procedures
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Should this procedure be documented and supported
-@c at all?
-
-The procedures in this section are useful if you want to dig into the
-innards of Guile's module system. If you don't know precisely what you
-do, you should probably avoid using any of them.
-
-@deffn {Scheme Procedure} standard-eval-closure module
-@deffnx {C Function} scm_standard_eval_closure (module)
-Return an eval closure for the module @var{module}.
-@end deffn
-
-
-@node Module System Quirks
-@subsection Module System Quirks
-
-Although the programming interfaces are relatively stable, the Guile
-module system itself is still evolving. Here are some situations where
-usage surpasses design.
-
-@itemize @bullet
-
-@item
-When using a module which exports a macro definition, the other module
-must export all bindings the macro expansion uses, too, because the
-expanded code would otherwise not be able to see these definitions and
-issue a ``variable unbound'' error, or worse, would use another binding
-which might be present in the scope of the expansion.
-
-@item
-When two or more used modules export bindings with the same names, the
-last accessed module wins, and the exported binding of that last module
-will silently be used. This might lead to hard-to-find errors because
-wrong procedures or variables are used. To avoid this kind of
-@dfn{name-clash} situation, use a custom interface specification
-(@pxref{Using Guile Modules}). (We include this entry for the possible
-benefit of users of Guile versions previous to 1.5.0, when custom
-interfaces were added to the module system.)
-
-@item
-[Add other quirks here.]
-
-@end itemize
-
-
-@node Included Guile Modules
-@subsection Included Guile Modules
-
-@c FIXME::martin: Review me!
-
-Some modules are included in the Guile distribution; here are references
-to the entries in this manual which describe them in more detail:
-
-@table @strong
-@item boot-9
-boot-9 is Guile's initialization module, and it is always loaded when
-Guile starts up.
-
-@item (ice-9 debug)
-Mikael Djurfeldt's source-level debugging support for Guile
-(@pxref{Debugging Features}).
-
-@item (ice-9 threads)
-Guile's support for multi threaded execution (@pxref{Scheduling}).
-
-@item (ice-9 rdelim)
-Line- and character-delimited input (@pxref{Line/Delimited}).
-
-@item (ice-9 rw)
-Block string input/output (@pxref{Block Reading and Writing}).
-
-@item (ice-9 documentation)
-Online documentation (REFFIXME).
-
-@item (srfi srfi-1)
-A library providing a lot of useful list and pair processing
-procedures (@pxref{SRFI-1}).
-
-@item (srfi srfi-2)
-Support for @code{and-let*} (@pxref{SRFI-2}).
-
-@item (srfi srfi-4)
-Support for homogeneous numeric vectors (@pxref{SRFI-4}).
-
-@item (srfi srfi-6)
-Support for some additional string port procedures (@pxref{SRFI-6}).
-
-@item (srfi srfi-8)
-Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
-
-@item (srfi srfi-9)
-Record definition with @code{define-record-type} (@pxref{SRFI-9}).
-
-@item (srfi srfi-10)
-Read hash extension @code{#,()} (@pxref{SRFI-10}).
-
-@item (srfi srfi-11)
-Multiple-value handling with @code{let-values} and @code{let-values*}
-(@pxref{SRFI-11}).
-
-@item (srfi srfi-13)
-String library (@pxref{SRFI-13}).
-
-@item (srfi srfi-14)
-Character-set library (@pxref{SRFI-14}).
-
-@item (srfi srfi-17)
-Getter-with-setter support (@pxref{SRFI-17}).
-
-@item (ice-9 slib)
-This module contains hooks for using Aubrey Jaffer's portable Scheme
-library SLIB from Guile (@pxref{SLIB}).
-
-@c FIXME::martin: This module is not in the distribution. Remove it
-@c from here?
-@item (ice-9 jacal)
-This module contains hooks for using Aubrey Jaffer's symbolic math
-package Jacal from Guile (@pxref{JACAL}).
-@end table
-
-
-@node Dynamic Libraries
-@section Dynamic Libraries
-
-Most modern Unices have something called @dfn{shared libraries}. This
-ordinarily means that they have the capability to share the executable
-image of a library between several running programs to save memory and
-disk space. But generally, shared libraries give a lot of additional
-flexibility compared to the traditional static libraries. In fact,
-calling them `dynamic' libraries is as correct as calling them `shared'.
-
-Shared libraries really give you a lot of flexibility in addition to the
-memory and disk space savings. When you link a program against a shared
-library, that library is not closely incorporated into the final
-executable. Instead, the executable of your program only contains
-enough information to find the needed shared libraries when the program
-is actually run. Only then, when the program is starting, is the final
-step of the linking process performed. This means that you need not
-recompile all programs when you install a new, only slightly modified
-version of a shared library. The programs will pick up the changes
-automatically the next time they are run.
-
-Now, when all the necessary machinery is there to perform part of the
-linking at run-time, why not take the next step and allow the programmer
-to explicitly take advantage of it from within his program? Of course,
-many operating systems that support shared libraries do just that, and
-chances are that Guile will allow you to access this feature from within
-your Scheme programs. As you might have guessed already, this feature
-is called @dfn{dynamic linking}@footnote{Some people also refer to the
-final linking stage at program startup as `dynamic linking', so if you
-want to make yourself perfectly clear, it is probably best to use the
-more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
-in his libtool documentation.}
-
-As with many aspects of Guile, there is a low-level way to access the
-dynamic linking apparatus, and a more high-level interface that
-integrates dynamically linked libraries into the module system.
-
-@menu
-* Low level dynamic linking::
-* Compiled Code Modules::
-* Dynamic Linking and Compiled Code Modules::
-@end menu
-
-@node Low level dynamic linking
-@subsection Low level dynamic linking
-
-When using the low level procedures to do your dynamic linking, you have
-complete control over which library is loaded when and what gets done
-with it.
-
-@deffn {Scheme Procedure} dynamic-link filename
-@deffnx {C Function} scm_dynamic_link (filename)
-Find the shared object (shared library) denoted by
-@var{filename} and link it into the running Guile
-application. The returned
-scheme object is a ``handle'' for the library which can
-be passed to @code{dynamic-func}, @code{dynamic-call} etc.
-
-Searching for object files is system dependent. Normally,
-if @var{filename} does have an explicit directory it will
-be searched for in locations
-such as @file{/usr/lib} and @file{/usr/local/lib}.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-object? obj
-@deffnx {C Function} scm_dynamic_object_p (obj)
-Return @code{#t} if @var{obj} is a dynamic object handle,
-or @code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-unlink dobj
-@deffnx {C Function} scm_dynamic_unlink (dobj)
-Unlink a dynamic object from the application, if possible. The
-object must have been linked by @code{dynamic-link}, with
-@var{dobj} the corresponding handle. After this procedure
-is called, the handle can no longer be used to access the
-object.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-func name dobj
-@deffnx {C Function} scm_dynamic_func (name, dobj)
-Return a ``handle'' for the function @var{name} in the
-shared object referred to by @var{dobj}. The handle
-can be passed to @code{dynamic-call} to actually
-call the function.
-
-Regardless whether your C compiler prepends an underscore
-@samp{_} to the global names in a program, you should
-@strong{not} include this underscore in @var{name}
-since it will be added automatically when necessary.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-call func dobj
-@deffnx {C Function} scm_dynamic_call (func, dobj)
-Call a C function in a dynamic object. Two styles of
-invocation are supported:
-
-@itemize @bullet
-@item @var{func} can be a function handle returned by
-@code{dynamic-func}. In this case @var{dobj} is
-ignored
-@item @var{func} can be a string with the name of the
-function to call, with @var{dobj} the handle of the
-dynamic object in which to find the function.
-This is equivalent to
-@smallexample
-
-(dynamic-call (dynamic-func @var{func} @var{dobj}) #f)
-@end smallexample
-@end itemize
-
-In either case, the function is passed no arguments
-and its return value is ignored.
-@end deffn
-
-@deffn {Scheme Procedure} dynamic-args-call func dobj args
-@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
-Call the C function indicated by @var{func} and @var{dobj},
-just like @code{dynamic-call}, but pass it some arguments and
-return its return value. The C function is expected to take
-two arguments and return an @code{int}, just like @code{main}:
-@smallexample
-int c_func (int argc, char **argv);
-@end smallexample
-
-The parameter @var{args} must be a list of strings and is
-converted into an array of @code{char *}. The array is passed
-in @var{argv} and its size in @var{argc}. The return value is
-converted to a Scheme number and returned from the call to
-@code{dynamic-args-call}.
-@end deffn
-
-Here is a small example that may work on GNU/Linux:
-
-@smallexample
-(define libc-obj (dynamic-link "libc.so"))
-libc-obj
-@result{} #<dynamic-object "libc.so">
-(dynamic-args-call 'rand libc-obj '())
-@result{} 269167349
-(dynamic-unlink libc-obj)
-libc-obj
-@result{} #<dynamic-object "libc.so" (unlinked)>
-@end smallexample
-
-As you can see, after calling @code{dynamic-unlink} on a dynamically
-linked library, it is marked as @samp{(unlinked)} and you are no longer
-able to use it with @code{dynamic-call}, etc. Whether the library is
-really removed from you program is system-dependent and will generally
-not happen when some other parts of your program still use it. In the
-example above, @code{libc} is almost certainly not removed from your
-program because it is badly needed by almost everything.
-
-The functions to call a function from a dynamically linked library,
-@code{dynamic-call} and @code{dynamic-args-call}, are not very powerful.
-They are mostly intended to be used for calling specially written
-initialization functions that will then add new primitives to Guile.
-For example, we do not expect that you will dynamically link
-@file{libX11} with @code{dynamic-link} and then construct a beautiful
-graphical user interface just by using @code{dynamic-call} and
-@code{dynamic-args-call}. Instead, the usual way would be to write a
-special Guile<->X11 glue library that has intimate knowledge about both
-Guile and X11 and does whatever is necessary to make them inter-operate
-smoothly. This glue library could then be dynamically linked into a
-vanilla Guile interpreter and activated by calling its initialization
-function. That function would add all the new types and primitives to
-the Guile interpreter that it has to offer.
-
-From this setup the next logical step is to integrate these glue
-libraries into the module system of Guile so that you can load new
-primitives into a running system just as you can load new Scheme code.
-
-There is, however, another possibility to get a more thorough access to
-the functions contained in a dynamically linked library. Anthony Green
-has written @file{libffi}, a library that implements a @dfn{foreign
-function interface} for a number of different platforms. With it, you
-can extend the Spartan functionality of @code{dynamic-call} and
-@code{dynamic-args-call} considerably. There is glue code available in
-the Guile contrib archive to make @file{libffi} accessible from Guile.
-
-@node Compiled Code Modules
-@subsection Putting Compiled Code into Modules
-
-@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
-
-The new primitives that you add to Guile with @code{gh_new_procedure}
-or with any of the other mechanisms are normally placed into the same
-module as all the other builtin procedures (like @code{display}).
-However, it is also possible to put new primitives into their own
-module.
-
-The mechanism for doing so is not very well thought out and is likely to
-change when the module system of Guile itself is revised, but it is
-simple and useful enough to document it as it stands.
-
-What @code{gh_new_procedure} and the functions used by the snarfer
-really do is to add the new primitives to whatever module is the
-@emph{current module} when they are called. This is analogous to the
-way Scheme code is put into modules: the @code{define-module} expression
-at the top of a Scheme source file creates a new module and makes it the
-current module while the rest of the file is evaluated. The
-@code{define} expressions in that file then add their new definitions to
-this current module.
-
-Therefore, all we need to do is to make sure that the right module is
-current when calling @code{gh_new_procedure} for our new primitives.
-
-@node Dynamic Linking and Compiled Code Modules
-@subsection Dynamic Linking and Compiled Code Modules
-
-The most interesting application of dynamically linked libraries is
-probably to use them for providing @emph{compiled code modules} to
-Scheme programs. As much fun as programming in Scheme is, every now and
-then comes the need to write some low-level C stuff to make Scheme even
-more fun.
-
-Not only can you put these new primitives into their own module (see the
-previous section), you can even put them into a shared library that is
-only then linked to your running Guile image when it is actually
-needed.
-
-An example will hopefully make everything clear. Suppose we want to
-make the Bessel functions of the C library available to Scheme in the
-module @samp{(math bessel)}. First we need to write the appropriate
-glue code to convert the arguments and return values of the functions
-from Scheme to C and back. Additionally, we need a function that will
-add them to the set of Guile primitives. Because this is just an
-example, we will only implement this for the @code{j0} function.
-
-@c FIXME::martin: Change all gh_ references to their scm_ equivalents.
-
-@smallexample
-#include <math.h>
-#include <guile/gh.h>
-
-SCM
-j0_wrapper (SCM x)
-@{
- return gh_double2scm (j0 (gh_scm2double (x)));
-@}
-
-void
-init_math_bessel ()
-@{
- gh_new_procedure1_0 ("j0", j0_wrapper);
-@}
-@end smallexample
-
-We can already try to bring this into action by manually calling the low
-level functions for performing dynamic linking. The C source file needs
-to be compiled into a shared library. Here is how to do it on
-GNU/Linux, please refer to the @code{libtool} documentation for how to
-create dynamically linkable libraries portably.
-
-@smallexample
-gcc -shared -o libbessel.so -fPIC bessel.c
-@end smallexample
-
-Now fire up Guile:
-
-@smalllisp
-(define bessel-lib (dynamic-link "./libbessel.so"))
-(dynamic-call "init_math_bessel" bessel-lib)
-(j0 2)
-@result{} 0.223890779141236
-@end smalllisp
-
-The filename @file{./libbessel.so} should be pointing to the shared
-library produced with the @code{gcc} command above, of course. The
-second line of the Guile interaction will call the
-@code{init_math_bessel} function which in turn will register the C
-function @code{j0_wrapper} with the Guile interpreter under the name
-@code{j0}. This function becomes immediately available and we can call
-it from Scheme.
-
-Fun, isn't it? But we are only half way there. This is what
-@code{apropos} has to say about @code{j0}:
-
-@smallexample
-(apropos 'j0)
-@print{} the-root-module: j0 #<primitive-procedure j0>
-@end smallexample
-
-As you can see, @code{j0} is contained in the root module, where all
-the other Guile primitives like @code{display}, etc live. In general,
-a primitive is put into whatever module is the @dfn{current module} at
-the time @code{gh_new_procedure} is called.
-
-A compiled module should have a specially named @dfn{module init
-function}. Guile knows about this special name and will call that
-function automatically after having linked in the shared library. For
-our example, we add the following code to @file{bessel.c}:
-
-@smallexample
-void scm_init_math_bessel_module ()
-@{
- /* contents currently unavailable. */
-@}
-@end smallexample
-
-The general pattern for the name of a module init function is:
-@samp{scm_init_}, followed by the name of the module where the
-individual hierarchical components are concatenated with underscores,
-followed by @samp{_module}.
-
-After @file{libbessel.so} has been rebuild, we need to place the shared
-library into the right place.
-
-Once the module has been correctly installed, it should be possible to
-use it like this:
-
-@smallexample
-guile> (use-modules (math bessel))
-guile> (j0 2)
-0.223890779141236
-guile> (apropos 'j0)
-@print{} bessel: j0 #<primitive-procedure j0>
-@end smallexample
-
-That's it!
-
-@node Variables
-@section Variables
-@tpindex Variables
-
-Each module has its own hash table, sometimes known as an @dfn{obarray},
-that maps the names defined in that module to their corresponding
-variable objects.
-
-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}.
-
-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.
-
-(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} make-undefined-variable
-@deffnx {C Function} scm_make_undefined_variable ()
-Return a variable that is initially unbound.
-@end deffn
-
-@deffn {Scheme Procedure} make-variable init
-@deffnx {C Function} scm_make_variable (init)
-Return a variable initialized to value @var{init}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-bound? var
-@deffnx {C Function} scm_variable_bound_p (var)
-Return @code{#t} iff @var{var} is bound to a value.
-Throws an error if @var{var} is not a variable object.
-@end deffn
-
-@deffn {Scheme Procedure} variable-ref var
-@deffnx {C Function} scm_variable_ref (var)
-Dereference @var{var} and return its value.
-@var{var} must be a variable object; see @code{make-variable}
-and @code{make-undefined-variable}.
-@end deffn
-
-@deffn {Scheme Procedure} variable-set! var val
-@deffnx {C Function} scm_variable_set_x (var, val)
-Set the value of the variable @var{var} to @var{val}.
-@var{var} must be a variable object, @var{val} can be any
-value. Return an unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} variable? obj
-@deffnx {C Function} scm_variable_p (obj)
-Return @code{#t} iff @var{obj} is a variable object, else
-return @code{#f}.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi
deleted file mode 100644
index 63b7a2c57..000000000
--- a/doc/ref/scheme-options.texi
+++ /dev/null
@@ -1,651 +0,0 @@
-@page
-@node Options and Config
-@chapter Runtime Options and Configuration
-
-Guile's behaviour can be modified by setting options. For example, is
-the language that Guile accepts case sensitive, or should the debugger
-automatically show a backtrace on error?
-
-Guile has two levels of interface for managing options: a low-level
-control interface, and a user-level interface which allows the enabling
-or disabling of options.
-
-Moreover, the options are classified in groups according to whether they
-configure @emph{reading}, @emph{printing}, @emph{debugging} or
-@emph{evaluating}.
-
-@menu
-* General option interface::
-* Reader options::
-* Printing options::
-* Debugger options::
-* Evaluator options::
-* Evaluator trap options::
-* Examples of option use::
-* Install Config:: Installation and configuration data.
-* Feature Tracking:: Available features in the Guile process.
-@end menu
-
-@node General option interface
-@section General option interface
-
-We will use the expression @code{<group>} to represent @code{read},
-@code{print}, @code{debug} or @code{evaluator}.
-
-@subheading Low level
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-options-interface
-@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
-@deffnx {Scheme Procedure} print-options-interface [SOME-INT]
-@deffnx {Scheme Procedure} evaluator-traps-interface [SOME-INT]
-@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
-[FIXME: I have just taken the comments for C routine scm_options that
-implements all of these. It needs to be presented better.]
-
-If scm_options is called without arguments, the current option setting
-is returned. If the argument is an option setting, options are altered
-and the old setting is returned. If the argument isn't a list, a list
-of sublists is returned, where each sublist contains option name, value
-and documentation string.
-@end deffn
-
-
-@subheading User level
-
-@c @deftp {Data type} scm_option
-@c @code{scm_option} is used to represent run time options. It can be a
-@c @emph{boolean} type, in which case the option will be set by the strings
-@c @code{"yes"} and @code{"no"}. It can be a
-@c @end deftp
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-options [arg]
-@deffnx {Scheme Procedure} read-options [arg]
-@deffnx {Scheme Procedure} print-options [arg]
-@deffnx {Scheme Procedure} debug-options [arg]
-@deffnx {Scheme Procedure} traps [arg]
-These functions list the options in their group. The optional argument
-@var{arg} is a symbol which modifies the form in which the options are
-presented.
-
-With no arguments, @code{<group>-options} returns the values of the
-options in that particular group. If @var{arg} is @code{'help}, a
-description of each option is given. If @var{arg} is @code{'full},
-programmers' options are also shown.
-
-@var{arg} can also be a list representing the state of all options. In
-this case, the list contains single symbols (for enabled boolean
-options) and symbols followed by values.
-@end deffn
-[FIXME: I don't think 'full is ever any different from 'help. What's
-up?]
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-enable option-symbol
-@deffnx {Scheme Procedure} read-enable option-symbol
-@deffnx {Scheme Procedure} print-enable option-symbol
-@deffnx {Scheme Procedure} debug-enable option-symbol
-@deffnx {Scheme Procedure} trap-enable option-symbol
-These functions set the specified @var{option-symbol} in their options
-group. They only work if the option is boolean, and throw an error
-otherwise.
-@end deffn
-
-@c NJFIXME
-@deffn {Scheme Procedure} <group>-disable option-symbol
-@deffnx {Scheme Procedure} read-disable option-symbol
-@deffnx {Scheme Procedure} print-disable option-symbol
-@deffnx {Scheme Procedure} debug-disable option-symbol
-@deffnx {Scheme Procedure} trap-disable option-symbol
-These functions turn off the specified @var{option-symbol} in their
-options group. They only work if the option is boolean, and throw an
-error otherwise.
-@end deffn
-
-@c NJFIXME
-@deffn syntax <group>-set! option-symbol value
-@deffnx syntax read-set! option-symbol value
-@deffnx syntax print-set! option-symbol value
-@deffnx syntax debug-set! option-symbol value
-@deffnx syntax trap-set! option-symbol value
-These functions set a non-boolean @var{option-symbol} to the specified
-@var{value}.
-@end deffn
-
-
-@node Reader options
-@section Reader options
-@cindex options - read
-@cindex read options
-
-Here is the list of reader options generated by typing
-@code{(read-options 'full)} in Guile. You can also see the default
-values.
-
-@smalllisp
-keywords #f Style of keyword recognition: #f or 'prefix
-case-insensitive no Convert symbols to lower case.
-positions yes Record positions of source code expressions.
-copy no Copy source code expressions.
-@end smalllisp
-
-Notice that while Standard Scheme is case insensitive, to ease
-translation of other Lisp dialects, notably Emacs Lisp, into Guile,
-Guile is case-sensitive by default.
-
-To make Guile case insensitive, you can type
-
-@smalllisp
-(read-enable 'case-insensitive)
-@end smalllisp
-
-@node Printing options
-@section Printing options
-
-Here is the list of print options generated by typing
-@code{(print-options 'full)} in Guile. You can also see the default
-values.
-
-@smallexample
-source no Print closures with source.
-closure-hook #f Hook for printing closures.
-@end smallexample
-
-
-@node Evaluator options
-@section Evaluator options
-
-These are the evaluator options with their default values, as they are
-printed by typing @code{(eval-options 'full)} in Guile.
-
-@smallexample
-stack 22000 Size of thread stacks (in machine words).
-@end smallexample
-
-@node Evaluator trap options
-@section Evaluator trap options
-[FIXME: These flags, together with their corresponding handlers, are not
-user level options. Probably this entire section should be moved to the
-documentation about the low-level programmer debugging interface.]
-
-Here is the list of evaluator trap options generated by typing
-@code{(traps 'full)} in Guile. You can also see the default values.
-
-@smallexample
-exit-frame no Trap when exiting eval or apply.
-apply-frame no Trap when entering apply.
-enter-frame no Trap when eval enters new frame.
-traps yes Enable evaluator traps.
-@end smallexample
-
-@deffn apply-frame-handler key cont tailp
-Called when a procedure is being applied.
-
-Called if:
-
-@itemize @bullet
-@item
-evaluator traps are enabled [traps interface], and
-@item
-either
-@itemize @minus
-@item
-@code{apply-frame} is enabled [traps interface], or
-@item
-trace mode is on [debug-options interface], and the procedure being
-called has the trace property enabled.
-@end itemize
-@end itemize
-
-If cheap traps are enabled [debug-options interface], @var{cont} is a
-debug object, otherwise it is a restartable continuation.
-
-@var{tailp} is true if this is a tail call
-@end deffn
-
-@deffn exit-frame-handler key cont retval
-Called when a value is returned from a procedure.
-
-Called if:
-
-@itemize @bullet
-@item
-evaluator traps are enabled [traps interface], and
-@item
-either
-@itemize @minus
-@item
- @code{exit-frame} is enabled [traps interface], or
-@item
-trace mode is on [debug-options interface], and the procedure being
-called has the trace property enabled.
-@end itemize
-@end itemize
-
-If cheap traps are enabled [debug-options interface], @var{cont} is a
-debug object, otherwise it is a restartable continuation.
-
-@var{retval} is the return value.
-@end deffn
-
-@node Debugger options
-@section Debugger options
-
-Here is the list of print options generated by typing
-@code{(debug-options 'full)} in Guile. You can also see the default
-values.
-
-@smallexample
-stack 20000 Stack size limit (0 = no check).
-debug yes Use the debugging evaluator.
-backtrace no Show backtrace on error.
-depth 20 Maximal length of printed backtrace.
-maxdepth 1000 Maximal number of stored backtrace frames.
-frames 3 Maximum number of tail-recursive frames in backtrace.
-indent 10 Maximal indentation in backtrace.
-backwards no Display backtrace in anti-chronological order.
-procnames yes Record procedure names at definition.
-trace no *Trace mode.
-breakpoints no *Check for breakpoints.
-cheap yes *Flyweight representation of the stack at traps.
-@end smallexample
-
-@subsection Stack overflow
-
-@cindex overflow, stack
-@cindex stack overflow
-Stack overflow errors are caused by a computation trying to use more
-stack space than has been enabled by the @code{stack} option. They are
-reported like this:
-
-@lisp
-(non-tail-recursive-factorial 500)
-@print{}
-ERROR: Stack overflow
-ABORT: (stack-overflow)
-@end lisp
-
-If you get an error like this, you can either try rewriting your code to
-use less stack space, or increase the maximum stack size. To increase
-the maximum stack size, use @code{debug-set!}, for example:
-
-@lisp
-(debug-set! stack 200000)
-@result{}
-(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
-
-(non-tail-recursive-factorial 500)
-@result{}
-122013682599111006870123878542304692625357434@dots{}
-@end lisp
-
-If you prefer to try rewriting your code, you may be able to save stack
-space by making some of your procedures @dfn{tail recursive}. For a
-description of what this means, see @ref{Proper tail
-recursion,,,r5rs,The Revised^5 Report on Scheme}.
-
-
-@node Examples of option use
-@section Examples of option use
-
-Here is an example of a session in which some read and debug option
-handling procedures are used. In this example, the user
-
-@enumerate
-@item
-Notices that the symbols @code{abc} and @code{aBc} are not the same
-@item
-Examines the @code{read-options}, and sees that @code{case-insensitive}
-is set to ``no''.
-@item
-Enables @code{case-insensitive}
-@item
-Verifies that now @code{aBc} and @code{abc} are the same
-@item
-Disables @code{case-insensitive} and enables debugging @code{backtrace}
-@item
-Reproduces the error of displaying @code{aBc} with backtracing enabled
-[FIXME: this last example is lame because there is no depth in the
-backtrace. Need to give a better example, possibly putting debugging
-option examples in a separate session.]
-@end enumerate
-
-
-@smalllisp
-guile> (define abc "hello")
-guile> abc
-"hello"
-guile> aBc
-ERROR: In expression aBc:
-ERROR: Unbound variable: aBc
-ABORT: (misc-error)
-
-Type "(backtrace)" to get more information.
-guile> (read-options 'help)
-keywords #f Style of keyword recognition: #f or 'prefix
-case-insensitive no Convert symbols to lower case.
-positions yes Record positions of source code expressions.
-copy no Copy source code expressions.
-guile> (debug-options 'help)
-stack 20000 Stack size limit (0 = no check).
-debug yes Use the debugging evaluator.
-backtrace no Show backtrace on error.
-depth 20 Maximal length of printed backtrace.
-maxdepth 1000 Maximal number of stored backtrace frames.
-frames 3 Maximum number of tail-recursive frames in backtrace.
-indent 10 Maximal indentation in backtrace.
-backwards no Display backtrace in anti-chronological order.
-procnames yes Record procedure names at definition.
-trace no *Trace mode.
-breakpoints no *Check for breakpoints.
-cheap yes *Flyweight representation of the stack at traps.
-guile> (read-enable 'case-insensitive)
-(keywords #f case-insensitive positions)
-guile> aBc
-"hello"
-guile> (read-disable 'case-insensitive)
-(keywords #f positions)
-guile> (debug-enable 'backtrace)
-(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
-guile> aBc
-
-Backtrace:
-0* aBc
-
-ERROR: In expression aBc:
-ERROR: Unbound variable: aBc
-ABORT: (misc-error)
-guile>
-@end smalllisp
-
-
-@node Install Config
-@section Installation and Configuration Data
-
-It is often useful to have site-specific information about the current
-Guile installation. This chapter describes how to find out about
-Guile's configuration at run time.
-
-@deffn {Scheme Procedure} version
-@deffnx {Scheme Procedure} major-version
-@deffnx {Scheme Procedure} minor-version
-@deffnx {Scheme Procedure} micro-version
-@deffnx {C Function} scm_version ()
-@deffnx {C Function} scm_major_version ()
-@deffnx {C Function} scm_minor_version ()
-@deffnx {C Function} scm_micro_version ()
-Return a string describing Guile's version number, or its major, minor
-or micro version number, respectively.
-
-@lisp
-(version) @result{} "1.6.0"
-(major-version) @result{} "1"
-(minor-version) @result{} "6"
-(micro-version) @result{} "0"
-@end lisp
-@end deffn
-
-@c NJFIXME not in libguile!
-@deffn {Scheme Procedure} libguile-config-stamp
-Return a string describing the date on which @code{libguile} was
-configured. This is used to determine whether the Guile core
-interpreter and the ice-9 runtime have grown out of date with one
-another.
-@end deffn
-
-@deffn {Scheme Procedure} %package-data-dir
-@deffnx {C Function} scm_sys_package_data_dir ()
-Return the name of the directory where Scheme packages, modules and
-libraries are kept. On most Unix systems, this will be
-@samp{/usr/local/share/guile}.
-@end deffn
-
-@deffn {Scheme Procedure} %library-dir
-@deffnx {C Function} scm_sys_library_dir ()
-Return the directory where the Guile Scheme library files are installed.
-E.g., may return "/usr/share/guile/1.3.5".
-@end deffn
-
-@deffn {Scheme Procedure} %site-dir
-@deffnx {C Function} scm_sys_site_dir ()
-Return the directory where the Guile site files are installed.
-E.g., may return "/usr/share/guile/site".
-@end deffn
-
-@deffn {Scheme Procedure} parse-path path [tail]
-@deffnx {C Function} scm_parse_path (path, tail)
-Parse @var{path}, which is expected to be a colon-separated
-string, into a list and return the resulting list with
-@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
-is returned.
-@end deffn
-
-@deffn {Scheme Procedure} search-path path filename [extensions]
-@deffnx {C Function} scm_search_path (path, filename, extensions)
-Search @var{path} for a directory containing a file named
-@var{filename}. The file must be readable, and not a directory.
-If we find one, return its full filename; otherwise, return
-@code{#f}. If @var{filename} is absolute, return it unchanged.
-If given, @var{extensions} is a list of strings; for each
-directory in @var{path}, we search for @var{filename}
-concatenated with each @var{extension}.
-@end deffn
-
-@defvar %load-path
-List of directories which should be searched for Scheme
-modules and libraries.
-@end defvar
-
-@defvar %guile-build-info
-Alist of information collected during the building of a particular
-@code{guile} program. Entries can be grouped into one of several
-categories: directories, env vars, and versioning info.
-
-Briefly, here are the keys in @code{%guile-build-info}, by group:
-@itemize @bullet
-@item directories
-srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
-datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
-mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
-@item env vars
-LIBS
-@item versioning info
-guileversion, libguileinterface, buildstamp
-@end itemize
-
-Values are all strings. The value for @code{LIBS} is typically found also as
-a part of "guile-config link" output. The value for @code{guileversion} has
-form X.Y.Z, and should be the same as returned by @code{version}. The value
-for @code{libguileinterface} is libtool compatible and has form
-CURRENT:REVISION:AGE. The value for @code{buildstamp} is the output of the
-date(1) command.
-
-In the source, @code{%guile-build-info} is initialized from
-libguile/libpath.h, which is completely generated, so deleting this file
-before a build guarantees up-to-date values for that build.
-@end defvar
-
-
-@node Feature Tracking
-@section Feature Tracking
-
-Guile has a Scheme level variable @code{*features*} that keeps track to
-some extent of the features that are available in a running Guile.
-@code{*features*} is a list of symbols, for example @code{threads}, each
-of which describes a feature of the running Guile process.
-
-@defvar *features*
-A list of symbols describing available features of the Guile process.
-@end defvar
-
-You shouldn't modify the @code{*features*} variable directly using
-@code{set!}. Instead, see the procedures that are provided for this
-purpose in the following subsection.
-
-@menu
-* Feature Manipulation:: Checking for and advertising features.
-* Common Feature Symbols:: Commonly available features.
-@end menu
-
-
-@node Feature Manipulation
-@subsection Feature Manipulation
-
-To check whether a particular feature is available, use the
-@code{provided?} procedure:
-
-@deffn {Scheme Procedure} provided? feature
-@deffnx {Deprecated Scheme Procedure} feature? feature
-Return @code{#t} if the specified @var{feature} is available, otherwise
-@code{#f}.
-@end deffn
-
-To advertise a feature from your own Scheme code, you can use the
-@code{provide} procedure:
-
-@deffn {Scheme Procedure} provide feature
-Add @var{feature} to the list of available features in this Guile
-process.
-@end deffn
-
-For C code, the equivalent function takes its feature name as a
-@code{char *} argument for convenience:
-
-@deftypefn {C Function} void scm_add_feature (const char *str)
-Add a symbol with name @var{str} to the list of available features in
-this Guile process.
-@end deftypefn
-
-
-@node Common Feature Symbols
-@subsection Common Feature Symbols
-
-In general, a particular feature may be available for one of two
-reasons. Either because the Guile library was configured and compiled
-with that feature enabled --- i.e. the feature is built into the library
-on your system. Or because some C or Scheme code that was dynamically
-loaded by Guile has added that feature to the list.
-
-In the first category, here are the features that the current version of
-Guile may define (depending on how it is built), and what they mean.
-
-@table @code
-@item array
-Indicates support for arrays (@pxref{Arrays}).
-
-@item array-for-each
-Indicates availability of @code{array-for-each} and other array mapping
-procedures (@pxref{Array Mapping}).
-
-@item char-ready?
-Indicates that the @code{char-ready?} function is available
-(@pxref{Reading}).
-
-@item complex
-Indicates support for complex numbers.
-
-@item current-time
-Indicates availability of time-related functions: @code{times},
-@code{get-internal-run-time} and so on (@pxref{Time}).
-
-@item debug-extensions
-Indicates that the debugging evaluator is available, together with the
-options for controlling it.
-
-@item delay
-Indicates support for promises (@pxref{Delayed Evaluation}).
-
-@item EIDs
-Indicates that the @code{geteuid} and @code{getegid} really return
-effective user and group IDs (@pxref{Processes}).
-
-@item inexact
-Indicates support for inexact numbers.
-
-@item i/o-extensions
-Indicates availability of the following extended I/O procedures:
-@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
-@code{fileno}, @code{isatty?}, @code{fdopen},
-@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
-File Descriptors}).
-
-@item net-db
-Indicates availability of network database functions:
-@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
-@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
-@code{scm_setserv}, and their `byXXX' variants (@pxref{Network
-Databases}).
-
-@item posix
-Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
-@code{kill}, @code{execl} and so on (@pxref{POSIX}).
-
-@item random
-Indicates availability of random number generation functions:
-@code{random}, @code{copy-random-state}, @code{random-uniform} and so on
-(@pxref{Random}).
-
-@item reckless
-Indicates that Guile was built with important checks omitted --- you
-should never see this!
-
-@item regex
-Indicates support for POSIX regular expressions using
-@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
-Functions}).
-
-@item socket
-Indicates availability of socket-related functions: @code{socket},
-@code{bind}, @code{connect} and so on (@pxref{Network Sockets and
-Communication}).
-
-@item sort
-Indicates availability of sorting and merging functions
-(@pxref{Sorting}).
-
-@item system
-Indicates that the @code{system} function is available
-(@pxref{Processes}).
-
-@item threads
-Indicates support for multithreading (@pxref{Threads}).
-
-@item values
-Indicates support for multiple return values using @code{values} and
-@code{call-with-values} (@pxref{Multiple Values}).
-@end table
-
-Available features in the second category depend, by definition, on what
-additional code your Guile process has loaded in. The following table
-lists features that you might encounter for this reason.
-
-@table @code
-@item defmacro
-Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
-
-@item describe
-Indicates that the @code{(oop goops describe)} module has been loaded,
-which provides a procedure for describing the contents of GOOPS
-instances.
-
-@item readline
-Indicates that Guile has loaded in Readline support, for command line
-editing (@pxref{Readline Support}).
-
-@item record
-Indicates support for record definition using @code{make-record-type}
-and friends (@pxref{Records}).
-@end table
-
-Although these tables may seem exhaustive, it is probably unwise in
-practice to rely on them, as the correspondences between feature symbols
-and available procedures/behaviour are not strictly defined. If you are
-writing code that needs to check for the existence of some procedure, it
-is probably safer to do so directly using the @code{defined?} procedure
-than to test for the corresponding feature using @code{feature?}.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-procedures.texi b/doc/ref/scheme-procedures.texi
deleted file mode 100644
index 36f840ecc..000000000
--- a/doc/ref/scheme-procedures.texi
+++ /dev/null
@@ -1,816 +0,0 @@
-@page
-@node Procedures and Macros
-@chapter Procedures and Macros
-
-@menu
-* Lambda:: Basic procedure creation using lambda.
-* Optional Arguments:: Handling keyword, optional and rest arguments.
-* Procedure Properties:: Procedure properties and meta-information.
-* Procedures with Setters:: Procedures with setters.
-* Macros:: Lisp style macro definitions.
-* Syntax Rules:: Support for R5RS @code{syntax-rules}.
-* Syntax Case:: Support for the @code{syntax-case} system.
-* Internal Macros:: Guile's internal representation.
-@end menu
-
-
-@node Lambda
-@section Lambda: Basic Procedure Creation
-
-@c FIXME::martin: Review me!
-
-A @code{lambda} expression evaluates to a procedure. The environment
-which is in effect when a @code{lambda} expression is evaluated is
-enclosed in the newly created procedure, this is referred to as a
-@dfn{closure} (@pxref{About Closure}).
-
-When a procedure created by @code{lambda} is called with some actual
-arguments, the environment enclosed in the procedure is extended by
-binding the variables named in the formal argument list to new locations
-and storing the actual arguments into these locations. Then the body of
-the @code{lambda} expression is evaluation sequentially. The result of
-the last expression in the procedure body is then the result of the
-procedure invocation.
-
-The following examples will show how procedures can be created using
-@code{lambda}, and what you can do with these procedures.
-
-@lisp
-(lambda (x) (+ x x)) @result{} @r{a procedure}
-((lambda (x) (+ x x)) 4) @result{} 8
-@end lisp
-
-The fact that the environment in effect when creating a procedure is
-enclosed in the procedure is shown with this example:
-
-@lisp
-(define add4
- (let ((x 4))
- (lambda (y) (+ x y))))
-(add4 6) @result{} 10
-@end lisp
-
-
-@deffn syntax lambda formals body
-@var{formals} should be a formal argument list as described in the
-following table.
-
-@table @code
-@item (@var{variable1} @dots{})
-The procedure takes a fixed number of arguments; when the procedure is
-called, the arguments will be stored into the newly created location for
-the formal variables.
-@item @var{variable}
-The procedure takes any number of arguments; when the procedure is
-called, the sequence of actual arguments will converted into a list and
-stored into the newly created location for the formal variable.
-@item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
-If a space-delimited period precedes the last variable, then the
-procedure takes @var{n} or more variables where @var{n} is the number
-of formal arguments before the period. There must be at least one
-argument before the period. The first @var{n} actual arguments will be
-stored into the newly allocated locations for the first @var{n} formal
-arguments and the sequence of the remaining actual arguments is
-converted into a list and the stored into the location for the last
-formal argument. If there are exactly @var{n} actual arguments, the
-empty list is stored into the location of the last formal argument.
-@end table
-
-@var{body} is a sequence of Scheme expressions which are evaluated in
-order when the procedure is invoked.
-@end deffn
-
-
-@node Optional Arguments
-@section Optional Arguments
-
-@c FIXME::martin: Review me!
-
-Scheme procedures, as defined in R5RS, can either handle a fixed number
-of actual arguments, or a fixed number of actual arguments followed by
-arbitrarily many additional arguments. Writing procedures of variable
-arity can be useful, but unfortunately, the syntactic means for handling
-argument lists of varying length is a bit inconvenient. It is possible
-to give names to the fixed number of argument, but the remaining
-(optional) arguments can be only referenced as a list of values
-(@pxref{Lambda}).
-
-Guile comes with the module @code{(ice-9 optargs)}, which makes using
-optional arguments much more convenient. In addition, this module
-provides syntax for handling keywords in argument lists
-(@pxref{Keywords}).
-
-Before using any of the procedures or macros defined in this section,
-you have to load the module @code{(ice-9 optargs)} with the statement:
-
-@lisp
-(use-modules (ice-9 optargs))
-@end lisp
-
-@menu
-* let-optional Reference:: Locally binding optional arguments.
-* let-keywords Reference:: Locally binding keywords arguments.
-* lambda* Reference:: Creating advanced argument handling procedures.
-* define* Reference:: Defining procedures and macros.
-@end menu
-
-
-@node let-optional Reference
-@subsection let-optional Reference
-
-@c FIXME::martin: Review me!
-
-The syntax @code{let-optional} and @code{let-optional*} are for
-destructuring rest argument lists and giving names to the various list
-elements. @code{let-optional} binds all variables simultaneously, while
-@code{let-optional*} binds them sequentially, consistent with @code{let}
-and @code{let*} (@pxref{Local Bindings}).
-
-@deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
-These two macros give you an optional argument interface that is very
-@dfn{Schemey} and introduces no fancy syntax. They are compatible with
-the scsh macros of the same name, but are slightly extended. Each of
-@var{binding} may be of one of the forms @var{var} or @code{(@var{var}
-@var{default-value})}. @var{rest-arg} should be the rest-argument of the
-procedures these are used from. The items in @var{rest-arg} are
-sequentially bound to the variable names are given. When @var{rest-arg}
-runs out, the remaining vars are bound either to the default values or
-left unbound if no default value was specified. @var{rest-arg} remains
-bound to whatever may have been left of @var{rest-arg}.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
-@end deffn
-
-
-@node let-keywords Reference
-@subsection let-keywords Reference
-
-@c FIXME::martin: Review me!
-
-@code{let-keywords} and @code{let-keywords*} are used for extracting
-values from argument lists which use keywords instead of argument
-position for binding local variables to argument values.
-
-@code{let-keywords} binds all variables simultaneously, while
-@code{let-keywords*} binds them sequentially, consistent with @code{let}
-and @code{let*} (@pxref{Local Bindings}).
-
-@deffn {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
-These macros pick out keyword arguments from @var{rest-arg}, but do not
-modify it. This is consistent at least with Common Lisp, which
-duplicates keyword arguments in the rest argument. More explanation of what
-keyword arguments in a lambda list look like can be found below in
-the documentation for @code{lambda*}
- (@pxref{lambda* Reference}). @var{binding}s can have the same form as
-for @code{let-optional}. If @var{allow-other-keys?} is false, an error
-will be thrown if anything that looks like a keyword argument but does
-not match a known keyword parameter will result in an error.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
-@end deffn
-
-
-@node lambda* Reference
-@subsection lambda* Reference
-
-@c FIXME::martin: Review me!
-
-When using optional and keyword argument lists, using @code{lambda} for
-creating procedures and using @code{let-optional} or @code{let-keywords}
-is a bit lengthy. Therefore, @code{lambda*} is provided, which combines
-the features of those macros into a single convenient syntax.
-
-For quick reference, here is the syntax of the formal argument list for
-@code{lambda*} (brackets are used to indicate grouping only):
-
-@example
-ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]?
- [#:key [ext-var-decl]+ [#:allow-other-keys]?]?
- [[#:rest identifier]|[. identifier]]?
-
-ext-var-decl ::= identifier | ( identifier expression )
-@end example
-
-The characters `*', `+' and `?' are not to be taken literally; they mean
-respectively, zero or more occurrences, one or more occurrences, and one
-or zero occurrences.
-
-@deffn {library syntax} lambda* formals body
-@code{lambda*} creates a procedure that takes optional arguments. These
-are specified by putting them inside brackets at the end of the
-parameter list, but before any dotted rest argument. For example,
-
-@lisp
-(lambda* (a b #:optional c d . e) '())
-@end lisp
-
-creates a procedure with fixed arguments @var{a} and @var{b}, optional
-arguments @var{c} and @var{d}, and rest argument @var{e}. If the
-optional arguments are omitted in a call, the variables for them are
-unbound in the procedure. This can be checked with the @code{bound?}
-macro (documented below).
-
-@code{lambda*} can also take keyword arguments. For example, a procedure
-defined like this:
-
-@lisp
-(lambda* (#:key xyzzy larch) '())
-@end lisp
-
-can be called with any of the argument lists @code{(#:xyzzy 11)}
-@code{(#:larch 13)} @code{(#:larch 42 #:xyzzy 19)} @code{()}. Whichever
-arguments are given as keywords are bound to values.
-
-Optional and keyword arguments can also be given default values
-which they take on when they are not present in a call, by giving a
-two-item list in place of an optional argument, for example in:
-
-@lisp
-(lambda* (foo #:optional (bar 42) #:key (baz 73))
- (list foo bar baz))
-@end lisp
-
-@var{foo} is a fixed argument, @var{bar} is an optional argument with
-default value 42, and baz is a keyword argument with default value 73.
-Default value expressions are not evaluated unless they are needed and
-until the procedure is called.
-
-@code{lambda*} also supports two more special parameter list keywords.
-
-@code{lambda*}-defined procedures now throw an error by default if a
-keyword other than one of those specified is found in the actual
-passed arguments. However, specifying @code{#:allow-other-keys}
-immediately after the keyword argument declarations restores the
-previous behavior of ignoring unknown keywords. @code{lambda*} also now
-guarantees that if the same keyword is passed more than once, the
-last one passed is the one that takes effect. For example,
-
-@lisp
-((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails)))
- #:heads 37 #:tails 42 #:heads 99)
-@end lisp
-
-would result in (99 47) being displayed.
-
-@code{#:rest} is also now provided as a synonym for the dotted syntax
-rest argument. The argument lists @code{(a . b)} and @code{(a #:rest b)}
-are equivalent in all respects to @code{lambda*}. This is provided for
-more similarity to DSSSL, MIT-Scheme and Kawa among others, as well as
-for refugees from other Lisp dialects.
-@end deffn
-
-@deffn {library syntax} bound? variable
-Check if a variable is bound in the current environment.
-
-The procedure @code{defined?} doesn't quite cut it as it stands, since
-it only checks bindings in the top-level environment, not those in local
-scope only.
-@end deffn
-
-
-@node define* Reference
-@subsection define* Reference
-
-@c FIXME::martin: Review me!
-
-Just like @code{define} has a shorthand notation for defining procedures
-(@pxref{Lambda Alternatives}), @code{define*} is provided as an
-abbreviation of the combination of @code{define} and @code{lambda*}.
-
-@code{define*-public} is the @code{lambda*} version of
-@code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
-for defining macros with the improved argument list handling
-possibilities. The @code{-public} versions not only define the
-procedures/macros, but also export them from the current module.
-
-@deffn {library syntax} define* formals body
-@deffnx {library syntax} define*-public formals body
-@code{define*} and @code{define*-public} support optional arguments with
-a similar syntax to @code{lambda*}. They also support arbitrary-depth
-currying, just like Guile's define. Some examples:
-
-@lisp
-(define* (x y #:optional a (z 3) #:key w . u)
- (display (list y z u)))
-@end lisp
-defines a procedure @code{x} with a fixed argument @var{y}, an optional
-argument @var{a}, another optional argument @var{z} with default value 3,
-a keyword argument @var{w}, and a rest argument @var{u}.
-
-@lisp
-(define-public* ((foo #:optional bar) #:optional baz) '())
-@end lisp
-
-This illustrates currying. A procedure @code{foo} is defined, which,
-when called with an optional argument @var{bar}, returns a procedure
-that takes an optional argument @var{baz}.
-
-Of course, @code{define*[-public]} also supports @code{#:rest} and
-@code{#:allow-other-keys} in the same way as @code{lambda*}.
-@end deffn
-
-@deffn {library syntax} defmacro* name formals body
-@deffnx {library syntax} defmacro*-public name formals body
-These are just like @code{defmacro} and @code{defmacro-public} except that they
-take @code{lambda*}-style extended parameter lists, where @code{#:optional},
-@code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
-semantics. Here is an example of a macro with an optional argument:
-
-@lisp
-(defmacro* transmorgify (a #:optional b)
- (a 1))
-@end lisp
-@end deffn
-
-
-@node Procedure Properties
-@section Procedure Properties and Meta-information
-
-@c FIXME::martin: Review me!
-
-Procedures always have attached the environment in which they were
-created and information about how to apply them to actual arguments. In
-addition to that, properties and meta-information can be stored with
-procedures. The procedures in this section can be used to test whether
-a given procedure satisfies a condition; and to access and set a
-procedure's property.
-
-The first group of procedures are predicates to test whether a Scheme
-object is a procedure, or a special procedure, respectively.
-@code{procedure?} is the most general predicates, it returns @code{#t}
-for any kind of procedure. @code{closure?} does not return @code{#t}
-for primitive procedures, and @code{thunk?} only returns @code{#t} for
-procedures which do not accept any arguments.
-
-@rnindex procedure?
-@deffn {Scheme Procedure} procedure? obj
-@deffnx {C Function} scm_procedure_p (obj)
-Return @code{#t} if @var{obj} is a procedure.
-@end deffn
-
-@deffn {Scheme Procedure} closure? obj
-@deffnx {C Function} scm_closure_p (obj)
-Return @code{#t} if @var{obj} is a closure.
-@end deffn
-
-@deffn {Scheme Procedure} thunk? obj
-@deffnx {C Function} scm_thunk_p (obj)
-Return @code{#t} if @var{obj} is a thunk.
-@end deffn
-
-@c FIXME::martin: Is that true?
-@cindex procedure properties
-Procedure properties are general properties to be attached to
-procedures. These can be the name of a procedure or other relevant
-information, such as debug hints.
-
-@deffn {Scheme Procedure} procedure-name proc
-@deffnx {C Function} scm_procedure_name (proc)
-Return the name of the procedure @var{proc}
-@end deffn
-
-@deffn {Scheme Procedure} procedure-source proc
-@deffnx {C Function} scm_procedure_source (proc)
-Return the source of the procedure @var{proc}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-environment proc
-@deffnx {C Function} scm_procedure_environment (proc)
-Return the environment of the procedure @var{proc}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-properties proc
-@deffnx {C Function} scm_procedure_properties (proc)
-Return @var{obj}'s property list.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-property obj key
-@deffnx {C Function} scm_procedure_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
-@deffn {Scheme Procedure} set-procedure-properties! proc alist
-@deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
-@deffn {Scheme Procedure} set-procedure-property! obj key value
-@deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key} to
-@var{value}.
-@end deffn
-
-@cindex procedure documentation
-Documentation for a procedure can be accessed with the procedure
-@code{procedure-documentation}.
-
-@deffn {Scheme Procedure} procedure-documentation proc
-@deffnx {C Function} scm_procedure_documentation (proc)
-Return the documentation string associated with @code{proc}. By
-convention, if a procedure contains more than one expression and the
-first expression is a string constant, that string is assumed to contain
-documentation for that procedure.
-@end deffn
-
-@cindex source properties
-@c FIXME::martin: Is the following true?
-Source properties are properties which are related to the source code of
-a procedure, such as the line and column numbers, the file name etc.
-
-@deffn {Scheme Procedure} set-source-properties! obj plist
-@deffnx {C Function} scm_set_source_properties_x (obj, plist)
-Install the association list @var{plist} as the source property
-list for @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} set-source-property! obj key datum
-@deffnx {C Function} scm_set_source_property_x (obj, key, datum)
-Set the source property of object @var{obj}, which is specified by
-@var{key} to @var{datum}. Normally, the key will be a symbol.
-@end deffn
-
-@deffn {Scheme Procedure} source-properties obj
-@deffnx {C Function} scm_source_properties (obj)
-Return the source property association list of @var{obj}.
-@end deffn
-
-
-@deffn {Scheme Procedure} source-property obj key
-@deffnx {C Function} scm_source_property (obj, key)
-Return the source property specified by @var{key} from
-@var{obj}'s source property list.
-@end deffn
-
-
-@node Procedures with Setters
-@section Procedures with Setters
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Document `operator struct'.
-
-@cindex procedure with setter
-@cindex setter
-A @dfn{procedure with setter} is a special kind of procedure which
-normally behaves like any accessor procedure, that is a procedure which
-accesses a data structure. The difference is that this kind of
-procedure has a so-called @dfn{setter} attached, which is a procedure
-for storing something into a data structure.
-
-Procedures with setters are treated specially when the procedure appears
-in the special form @code{set!} (REFFIXME). How it works is best shown
-by example.
-
-Suppose we have a procedure called @code{foo-ref}, which accepts two
-arguments, a value of type @code{foo} and an integer. The procedure
-returns the value stored at the given index in the @code{foo} object.
-Let @code{f} be a variable containing such a @code{foo} data
-structure.@footnote{Working definitions would be:
-@lisp
-(define foo-ref vector-ref)
-(define foo-set! vector-set!)
-(define f (make-vector 2 #f))
-@end lisp
-}
-
-@lisp
-(foo-ref f 0) @result{} bar
-(foo-ref f 1) @result{} braz
-@end lisp
-
-Also suppose that a corresponding setter procedure called
-@code{foo-set!} does exist.
-
-@lisp
-(foo-set! f 0 'bla)
-(foo-ref f 0) @result{} bla
-@end lisp
-
-Now we could create a new procedure called @code{foo}, which is a
-procedure with setter, by calling @code{make-procedure-with-setter} with
-the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
-Let us call this new procedure @code{foo}.
-
-@lisp
-(define foo (make-procedure-with-setter foo-ref foo-set!))
-@end lisp
-
-@code{foo} can from now an be used to either read from the data
-structure stored in @code{f}, or to write into the structure.
-
-@lisp
-(set! (foo f 0) 'dum)
-(foo f 0) @result{} dum
-@end lisp
-
-@deffn {Scheme Procedure} make-procedure-with-setter procedure setter
-@deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
-Create a new procedure which behaves like @var{procedure}, but
-with the associated setter @var{setter}.
-@end deffn
-
-@deffn {Scheme Procedure} procedure-with-setter? obj
-@deffnx {C Function} scm_procedure_with_setter_p (obj)
-Return @code{#t} if @var{obj} is a procedure with an
-associated setter procedure.
-@end deffn
-
-@deffn {Scheme Procedure} procedure proc
-@deffnx {C Function} scm_procedure (proc)
-Return the procedure of @var{proc}, which must be either a
-procedure with setter, or an operator struct.
-@end deffn
-
-@deffn {Scheme Procedure} setter proc
-Return the setter of @var{proc}, which must be either a procedure with
-setter or an operator struct.
-@end deffn
-
-
-@node Macros
-@section Lisp Style Macro Definitions
-
-@cindex macros
-@cindex transformation
-Macros are objects which cause the expression that they appear in to be
-transformed in some way @emph{before} being evaluated. In expressions
-that are intended for macro transformation, the identifier that names
-the relevant macro must appear as the first element, like this:
-
-@lisp
-(@var{macro-name} @var{macro-args} @dots{})
-@end lisp
-
-In Lisp-like languages, the traditional way to define macros is very
-similar to procedure definitions. The key differences are that the
-macro definition body should return a list that describes the
-transformed expression, and that the definition is marked as a macro
-definition (rather than a procedure definition) by the use of a
-different definition keyword: in Lisp, @code{defmacro} rather than
-@code{defun}, and in Scheme, @code{define-macro} rather than
-@code{define}.
-
-@fnindex defmacro
-@fnindex define-macro
-Guile supports this style of macro definition using both @code{defmacro}
-and @code{define-macro}. The only difference between them is how the
-macro name and arguments are grouped together in the definition:
-
-@lisp
-(defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-is the same as
-
-@lisp
-(define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-The difference is analogous to the corresponding difference between
-Lisp's @code{defun} and Scheme's @code{define}.
-
-@code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
-distribution, is a good example of macro definition using
-@code{defmacro}:
-
-@lisp
-(defmacro false-if-exception (expr)
- `(catch #t
- (lambda () ,expr)
- (lambda args #f)))
-@end lisp
-
-@noindent
-The effect of this definition is that expressions beginning with the
-identifier @code{false-if-exception} are automatically transformed into
-a @code{catch} expression following the macro definition specification.
-For example:
-
-@lisp
-(false-if-exception (open-input-file "may-not-exist"))
-@equiv{}
-(catch #t
- (lambda () (open-input-file "may-not-exist"))
- (lambda args #f))
-@end lisp
-
-
-@node Syntax Rules
-@section The R5RS @code{syntax-rules} System
-@cindex R5RS syntax-rules system
-
-R5RS defines an alternative system for macro and syntax transformations
-using the keywords @code{define-syntax}, @code{let-syntax},
-@code{letrec-syntax} and @code{syntax-rules}.
-
-The main difference between the R5RS system and the traditional macros
-of the previous section is how the transformation is specified. In
-R5RS, rather than permitting a macro definition to return an arbitrary
-expression, the transformation is specified in a pattern language that
-
-@itemize @bullet
-@item
-does not require complicated quoting and extraction of components of the
-source expression using @code{caddr} etc.
-
-@item
-is designed such that the bindings associated with identifiers in the
-transformed expression are well defined, and such that it is impossible
-for the transformed expression to construct new identifiers.
-@end itemize
-
-@noindent
-The last point is commonly referred to as being @dfn{hygienic}: the R5RS
-@code{syntax-case} system provides @dfn{hygienic macros}.
-
-For example, the R5RS pattern language for the @code{false-if-exception}
-example of the previous section looks like this:
-
-@lisp
-(syntax-rules ()
- ((_ expr)
- (catch #t
- (lambda () expr)
- (lambda args #f))))
-@end lisp
-
-In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
-syncase)} module. To make these facilities available in your code,
-include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
-Guile Modules}) before the first usage of @code{define-syntax} etc. If
-you are writing a Scheme module, you can alternatively include the form
-@code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
-declaration (@pxref{Creating Guile Modules}).
-
-@menu
-* Pattern Language:: The @code{syntax-rules} pattern language.
-* Define-Syntax:: Top level syntax definitions.
-* Let-Syntax:: Local syntax definitions.
-@end menu
-
-
-@node Pattern Language
-@subsection The @code{syntax-rules} Pattern Language
-
-
-@node Define-Syntax
-@subsection Top Level Syntax Definitions
-
-define-syntax: The gist is
-
- (define-syntax <keyword> <transformer-spec>)
-
-makes the <keyword> into a macro so that
-
- (<keyword> ...)
-
-expands at _compile_ or _read_ time (i.e. before any
-evaluation begins) into some expression that is
-given by the <transformer-spec>.
-
-
-@node Let-Syntax
-@subsection Local Syntax Definitions
-
-
-@node Syntax Case
-@section Support for the @code{syntax-case} System
-
-
-
-@node Internal Macros
-@section Internal Representation of Macros and Syntax
-
-Internally, Guile uses three different flavors of macros. The three
-flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
-@dfn{mmacro}.
-
-Given the expression
-
-@lisp
-(foo @dots{})
-@end lisp
-
-@noindent
-with @code{foo} being some flavor of macro, one of the following things
-will happen when the expression is evaluated.
-
-@itemize @bullet
-@item
-When @code{foo} has been defined to be an @dfn{acro}, the procedure used
-in the acro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-the value of evaluating the expression. You can think of this a
-procedure that receives its argument as an unevaluated expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{macro}, the procedure used
-in the macro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-evaluated again. That is, the procedure should return a valid Scheme
-expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
-used in the mmacro definition of `foo' is passed the whole expression
-and the current lexical environment, and whatever that procedure returns
-replaces the original expression. Evaluation then starts over from the
-new expression that has just been returned.
-@end itemize
-
-The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
-expression returned by a @dfn{mmacro} procedure is remembered (or
-@dfn{memoized}) so that the expansion does not need to be done again
-next time the containing code is evaluated.
-
-The primitives @code{procedure->syntax}, @code{procedure->macro} and
-@code{procedure->memoizing-macro} are used to construct acros, macros
-and mmacros respectively. However, if you do not have a very special
-reason to use one of these primitives, you should avoid them: they are
-very specific to Guile's current implementation and therefore likely to
-change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
-@code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
-terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
-all implemented as mmacros.)
-
-@deffn {Scheme Procedure} procedure->syntax code
-@deffnx {C Function} scm_makacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, returns the result of applying @var{code}
-to the expression and the environment.
-@end deffn
-
-@deffn {Scheme Procedure} procedure->macro code
-@deffnx {C Function} scm_makmacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment. For example:
-
-@lisp
-(define trace
- (procedure->macro
- (lambda (x env)
- `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
-
-(trace @i{foo})
-@equiv{}
-(set! @i{foo} (tracef @i{foo} '@i{foo})).
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} procedure->memoizing-macro code
-@deffnx {C Function} scm_makmmacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment.
-@code{procedure->memoizing-macro} is the same as
-@code{procedure->macro}, except that the expression returned by
-@var{code} replaces the original macro expression in the memoized form
-of the containing code.
-@end deffn
-
-In the following primitives, @dfn{acro} flavor macros are referred to
-as @dfn{syntax transformers}.
-
-@deffn {Scheme Procedure} macro? obj
-@deffnx {C Function} scm_macro_p (obj)
-Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
-syntax transformer.
-@end deffn
-
-@deffn {Scheme Procedure} macro-type m
-@deffnx {C Function} scm_macro_type (m)
-Return one of the symbols @code{syntax}, @code{macro} or
-@code{macro!}, depending on whether @var{m} is a syntax
-transformer, a regular macro, or a memoizing macro,
-respectively. If @var{m} is not a macro, @code{#f} is
-returned.
-@end deffn
-
-@deffn {Scheme Procedure} macro-name m
-@deffnx {C Function} scm_macro_name (m)
-Return the name of the macro @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} macro-transformer m
-@deffnx {C Function} scm_macro_transformer (m)
-Return the transformer of the macro @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} cons-source xorig x y
-@deffnx {C Function} scm_cons_source (xorig, x, y)
-Create and return a new pair whose car and cdr are @var{x} and @var{y}.
-Any source properties associated with @var{xorig} are also associated
-with the new pair.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-reading.texi b/doc/ref/scheme-reading.texi
deleted file mode 100644
index eea049d2d..000000000
--- a/doc/ref/scheme-reading.texi
+++ /dev/null
@@ -1,27 +0,0 @@
-@page
-@node Further Reading
-@chapter Further Reading
-
-@itemize @bullet
-@item
-Dorai Sitaram's online Scheme tutorial, @dfn{Teach Yourself Scheme in
-Fixnum Days}, at
-@url{http://www.cs.rice.edu/~dorai/t-y-scheme/t-y-scheme.html}.
-Includes a nice explanation of continuations.
-
-@item
-@url{http://wombat.doc.ic.ac.uk/foldoc/}.
-
-@item
-The complete text of @dfn{Structure and Interpretation of Computer
-Programs}, the classic introduction to computer science and Scheme by
-Hal Abelson, Jerry Sussman and Julie Sussman, is now available online at
-@url{http://mitpress.mit.edu/sicp/sicp.html}. This site also provides
-teaching materials related to the book, and all the source code used in
-the book, in a form suitable for loading and running.
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-scheduling.texi b/doc/ref/scheme-scheduling.texi
deleted file mode 100644
index 920a73029..000000000
--- a/doc/ref/scheme-scheduling.texi
+++ /dev/null
@@ -1,453 +0,0 @@
-@page
-@node Scheduling
-@chapter Threads, Mutexes, Asyncs and Dynamic Roots
-
-[FIXME: This is pasted in from Tom Lord's original guile.texi chapter
-plus the Cygnus programmer's manual; it should be *very* carefully
-reviewed and largely reorganized.]
-
-@menu
-* Arbiters:: Synchronization primitives.
-* Asyncs:: Asynchronous procedure invocation.
-* Dynamic Roots:: Root frames of execution.
-* Threads:: Multiple threads of execution.
-* Fluids:: Dynamically scoped variables.
-@end menu
-
-
-@node Arbiters
-@section Arbiters
-
-@cindex arbiters
-
-@c FIXME::martin: Review me!
-
-Arbiters are synchronization objects. They are created with
-@code{make-arbiter}. Two or more threads can synchronize on an arbiter
-by trying to lock it using @code{try-arbiter}. This call will succeed
-if no other thread has called @code{try-arbiter} on the arbiter yet,
-otherwise it will fail and return @code{#f}. Once an arbiter is
-successfully locked, it cannot be locked by another thread until the
-thread holding the arbiter calls @code{release-arbiter} to unlock it.
-
-@deffn {Scheme Procedure} make-arbiter name
-@deffnx {C Function} scm_make_arbiter (name)
-Return an object of type arbiter and name @var{name}. Its
-state is initially unlocked. Arbiters are a way to achieve
-process synchronization.
-@end deffn
-
-@deffn {Scheme Procedure} try-arbiter arb
-@deffnx {C Function} scm_try_arbiter (arb)
-Return @code{#t} and lock the arbiter @var{arb} if the arbiter
-was unlocked. Otherwise, return @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} release-arbiter arb
-@deffnx {C Function} scm_release_arbiter (arb)
-Return @code{#t} and unlock the arbiter @var{arb} if the
-arbiter was locked. Otherwise, return @code{#f}.
-@end deffn
-
-
-@node Asyncs
-@section Asyncs
-
-@cindex asyncs
-@cindex system asyncs
-
-@c FIXME::martin: Review me!
-
-An async is a pair of one thunk (a parameterless procedure) and a mark.
-Setting the mark on an async guarantees that the thunk will be executed
-somewhen in the future (@dfn{asynchronously}). Setting the mark more
-than once is satisfied by one execution of the thunk.
-
-Guile supports two types of asyncs: Normal asyncs and system asyncs.
-They differ in that marked system asyncs are executed implicitly as soon
-as possible, whereas normal asyncs have to be invoked explicitly.
-System asyncs are held in an internal data structure and are maintained
-by Guile.
-
-Normal asyncs are created with @code{async}, system asyncs with
-@code{system-async}. They are marked with @code{async-mark} or
-@code{system-async-mark}, respectively.
-
-@deffn {Scheme Procedure} async thunk
-@deffnx {C Function} scm_async (thunk)
-Create a new async for the procedure @var{thunk}.
-@end deffn
-
-@deffn {Scheme Procedure} system-async thunk
-@deffnx {C Function} scm_system_async (thunk)
-Create a new async for the procedure @var{thunk}. Also
-add it to the system's list of active async objects.
-@end deffn
-
-@deffn {Scheme Procedure} async-mark a
-@deffnx {C Function} scm_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
-@deffn {Scheme Procedure} system-async-mark a
-@deffnx {C Function} scm_system_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
-As already mentioned above, system asyncs are executed automatically.
-Normal asyncs have to be explicitly invoked by storing one or more of
-them into a list and passing them to @code{run-asyncs}.
-
-@deffn {Scheme Procedure} run-asyncs list_of_a
-@deffnx {C Function} scm_run_asyncs (list_of_a)
-Execute all thunks from the asyncs of the list @var{list_of_a}.
-@end deffn
-
-Automatic invocation of system asyncs can be temporarily disabled by
-calling @code{mask-signals} and @code{unmask-signals}. Setting the mark
-while async execution is disabled will nevertheless cause the async to
-run once execution is enabled again. Please note that calls to these
-procedures should always be paired, and they must not be nested, e.g. no
-@code{mask-signals} is allowed if another one is still active.
-
-@deffn {Scheme Procedure} mask-signals
-@deffnx {C Function} scm_mask_signals ()
-Mask signals. The returned value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} unmask-signals
-@deffnx {C Function} scm_unmask_signals ()
-Unmask signals. The returned value is not specified.
-@end deffn
-
-@c FIXME::martin: Find an example for usage of `noop'. What is that
-@c procedure for anyway?
-
-@deffn {Scheme Procedure} noop . args
-@deffnx {C Function} scm_noop (args)
-Do nothing. When called without arguments, return @code{#f},
-otherwise return the first argument.
-@end deffn
-
-
-@node Dynamic Roots
-@section Dynamic Roots
-@cindex dynamic roots
-
-A @dfn{dynamic root} is a root frame of Scheme evaluation.
-The top-level repl, for example, is an instance of a dynamic root.
-
-Each dynamic root has its own chain of dynamic-wind information. Each
-has its own set of continuations, jump-buffers, and pending CATCH
-statements which are inaccessible from the dynamic scope of any
-other dynamic root.
-
-In a thread-based system, each thread has its own dynamic root. Therefore,
-continuations created by one thread may not be invoked by another.
-
-Even in a single-threaded system, it is sometimes useful to create a new
-dynamic root. For example, if you want to apply a procedure, but to
-not allow that procedure to capture the current continuation, calling
-the procedure under a new dynamic root will do the job.
-
-@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
-@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
-Evaluate @code{(thunk)} in a new dynamic context, returning its value.
-
-If an error occurs during evaluation, apply @var{handler} to the
-arguments to the throw, just as @code{throw} would. If this happens,
-@var{handler} is called outside the scope of the new root -- it is
-called in the same dynamic context in which
-@code{call-with-dynamic-root} was evaluated.
-
-If @var{thunk} captures a continuation, the continuation is rooted at
-the call to @var{thunk}. In particular, the call to
-@code{call-with-dynamic-root} is not captured. Therefore,
-@code{call-with-dynamic-root} always returns at most one time.
-
-Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
-the root and a new chain started for @var{thunk}. Therefore, this call
-may not do what you expect:
-
-@lisp
-;; Almost certainly a bug:
-(with-output-to-port
- some-port
-
- (lambda ()
- (call-with-dynamic-root
- (lambda ()
- (display 'fnord)
- (newline))
- (lambda (errcode) errcode))))
-@end lisp
-
-The problem is, on what port will @samp{fnord} be displayed? You
-might expect that because of the @code{with-output-to-port} that
-it will be displayed on the port bound to @code{some-port}. But it
-probably won't -- before evaluating the thunk, dynamic winds are
-unwound, including those created by @code{with-output-to-port}.
-So, the standard output port will have been re-set to its default value
-before @code{display} is evaluated.
-
-(This function was added to Guile mostly to help calls to functions in C
-libraries that can not tolerate non-local exits or calls that return
-multiple times. If such functions call back to the interpreter, it should
-be under a new dynamic root.)
-@end deffn
-
-
-@deffn {Scheme Procedure} dynamic-root
-@deffnx {C Function} scm_dynamic_root ()
-Return an object representing the current dynamic root.
-
-These objects are only useful for comparison using @code{eq?}.
-They are currently represented as numbers, but your code should
-in no way depend on this.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "quit")
-@deffn {Scheme Procedure} quit [exit_val]
-Throw back to the error handler of the current dynamic root.
-
-If integer @var{exit_val} is specified and if Guile is being used
-stand-alone and if quit is called from the initial dynamic-root,
-@var{exit_val} becomes the exit status of the Guile process and the
-process exits.
-@end deffn
-
-When Guile is run interactively, errors are caught from within the
-read-eval-print loop. An error message will be printed and @code{abort}
-called. A default set of signal handlers is installed, e.g., to allow
-user interrupt of the interpreter.
-
-It is possible to switch to a "batch mode", in which the interpreter
-will terminate after an error and in which all signals cause their
-default actions. Switching to batch mode causes any handlers installed
-from Scheme code to be removed. An example of where this is useful is
-after forking a new process intended to run non-interactively.
-
-@c begin (scm-doc-string "boot-9.scm" "batch-mode?")
-@deffn {Scheme Procedure} batch-mode?
-Returns a boolean indicating whether the interpreter is in batch mode.
-@end deffn
-
-@c begin (scm-doc-string "boot-9.scm" "set-batch-mode?!")
-@deffn {Scheme Procedure} set-batch-mode?! arg
-If @var{arg} is true, switches the interpreter to batch mode.
-The @code{#f} case has not been implemented.
-@end deffn
-
-@node Threads
-@section Threads
-@cindex threads
-@cindex Guile threads
-
-@strong{[NOTE: this chapter was written for Cygnus Guile and has not yet
-been updated for the Guile 1.x release.]}
-
-Here is a the reference for Guile's threads. In this chapter I simply
-quote verbatim Tom Lord's description of the low-level primitives
-written in C (basically an interface to the POSIX threads library) and
-Anthony Green's description of the higher-level thread procedures
-written in scheme.
-@cindex posix threads
-@cindex Lord, Tom
-@cindex Green, Anthony
-
-When using Guile threads, keep in mind that each guile thread is
-executed in a new dynamic root.
-
-@menu
-* Low level thread primitives::
-* Higher level thread procedures::
-@end menu
-
-
-@node Low level thread primitives
-@subsection Low level thread primitives
-
-@c NJFIXME no current mechanism for making sure that these docstrings
-@c are in sync.
-
-@c begin (texi-doc-string "guile" "call-with-new-thread")
-@deffn {Scheme Procedure} call-with-new-thread thunk error-handler
-Evaluate @code{(thunk)} in a new thread, and new dynamic context,
-returning a new thread object representing the thread.
-
-If an error occurs during evaluation, call error-handler, passing it an
-error code describing the condition. [Error codes are currently
-meaningless integers. In the future, real values will be specified.]
-If this happens, the error-handler is called outside the scope of the new
-root -- it is called in the same dynamic context in which
-with-new-thread was evaluated, but not in the caller's thread.
-
-All the evaluation rules for dynamic roots apply to threads.
-@end deffn
-
-@c begin (texi-doc-string "guile" "join-thread")
-@deffn {Scheme Procedure} join-thread thread
-Suspend execution of the calling thread until the target @var{thread}
-terminates, unless the target @var{thread} has already terminated.
-@end deffn
-
-@c begin (texi-doc-string "guile" "yield")
-@deffn {Scheme Procedure} yield
-If one or more threads are waiting to execute, calling yield forces an
-immediate context switch to one of them. Otherwise, yield has no effect.
-@end deffn
-
-@c begin (texi-doc-string "guile" "make-mutex")
-@deffn {Scheme Procedure} make-mutex
-Create a new mutex object.
-@end deffn
-
-@c begin (texi-doc-string "guile" "lock-mutex")
-@deffn {Scheme Procedure} lock-mutex mutex
-Lock @var{mutex}. If the mutex is already locked, the calling thread
-blocks until the mutex becomes available. The function returns when
-the calling thread owns the lock on @var{mutex}.
-@end deffn
-
-@c begin (texi-doc-string "guile" "unlock-mutex")
-@deffn {Scheme Procedure} unlock-mutex mutex
-Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}.
-Calling unlock-mutex on a mutex not owned by the current thread results
-in undefined behaviour. Once a mutex has been unlocked, one thread
-blocked on @var{mutex} is awakened and grabs the mutex lock.
-@end deffn
-
-@c begin (texi-doc-string "guile" "make-condition-variable")
-@deffn {Scheme Procedure} make-condition-variable
-@end deffn
-
-@c begin (texi-doc-string "guile" "wait-condition-variable")
-@deffn {Scheme Procedure} wait-condition-variable cond-var mutex
-@end deffn
-
-@c begin (texi-doc-string "guile" "signal-condition-variable")
-@deffn {Scheme Procedure} signal-condition-variable cond-var
-@end deffn
-
-
-@node Higher level thread procedures
-@subsection Higher level thread procedures
-
-@c new by ttn, needs review
-
-Higher level thread procedures are available by loading the
-@code{(ice-9 threads)} module. These provide standardized
-thread creation and mutex interaction.
-
-@deffn {Scheme Procedure} %thread-handler tag args@dots{}
-
-This procedure is specified as the standard error-handler for
-@code{make-thread} and @code{begin-thread}. If the number of @var{args}
-is three or more, use @code{display-error}, otherwise display a message
-"uncaught throw to @var{tag}". All output is sent to the port specified
-by @code{current-error-port}.
-
-Before display, global var @code{the-last-stack} is set to @code{#f}
-and signals are unmasked with @code{unmask-signals}.
-
-[FIXME: Why distinguish based on number of args?! Cue voodoo music here.]
-@end deffn
-
-@deffn macro make-thread proc [args@dots{}]
-Apply @var{proc} to @var{args} in a new thread formed by
-@code{call-with-new-thread} using @code{%thread-handler} as the error
-handler.
-@end deffn
-
-@deffn macro begin-thread first [rest@dots{}]
-Evaluate forms @var{first} and @var{rest} in a new thread formed by
-@code{call-with-new-thread} using @code{%thread-handler} as the error
-handler.
-@end deffn
-
-@deffn macro with-mutex m [body@dots{}]
-Lock mutex @var{m}, evaluate @var{body}, and then unlock @var{m}.
-These sub-operations form the branches of a @code{dynamic-wind}.
-@end deffn
-
-@deffn macro monitor first [rest@dots{}]
-Evaluate forms @var{first} and @var{rest} under a newly created
-anonymous mutex, using @code{with-mutex}.
-
-[FIXME: Is there any way to access the mutex?]
-@end deffn
-
-
-@node Fluids
-@section Fluids
-
-@cindex fluids
-
-@c FIXME::martin: Review me!
-
-Fluids are objects to store values in. They have a few properties which
-make them useful in certain situations: Fluids can have one value per
-dynamic root (@pxref{Dynamic Roots}), so that changes to the value in a
-fluid are only visible in the same dynamic root. Since threads are
-executed in separate dynamic roots, fluids can be used for thread local
-storage (@pxref{Threads}).
-
-Fluids can be used to simulate dynamically scoped variables. These are
-used in several (especially in older) dialects of lisp, such as in Emacs
-Lisp, and they work a bit like global variables in that they can be
-modified by the caller of a procedure, and the called procedure will see
-the changes. With lexically scoped variables---which are normally used
-in Scheme---this cannot happen. See the description of
-@code{with-fluids*} below for details.
-
-New fluids are created with @code{make-fluid} and @code{fluid?} is used
-for testing whether an object is actually a fluid.
-
-@deffn {Scheme Procedure} make-fluid
-@deffnx {C Function} scm_make_fluid ()
-Return a newly created fluid.
-Fluids are objects of a certain type (a smob) that can hold one SCM
-value per dynamic root. That is, modifications to this value are
-only visible to code that executes within the same dynamic root as
-the modifying code. When a new dynamic root is constructed, it
-inherits the values from its parent. Because each thread executes
-in its own dynamic root, you can use fluids for thread local storage.
-@end deffn
-
-@deffn {Scheme Procedure} fluid? obj
-@deffnx {C Function} scm_fluid_p (obj)
-Return @code{#t} iff @var{obj} is a fluid; otherwise, return
-@code{#f}.
-@end deffn
-
-The values stored in a fluid can be accessed with @code{fluid-ref} and
-@code{fluid-set!}.
-
-@deffn {Scheme Procedure} fluid-ref fluid
-@deffnx {C Function} scm_fluid_ref (fluid)
-Return the value associated with @var{fluid} in the current
-dynamic root. If @var{fluid} has not been set, then return
-@code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} fluid-set! fluid value
-@deffnx {C Function} scm_fluid_set_x (fluid, value)
-Set the value associated with @var{fluid} in the current dynamic root.
-@end deffn
-
-@code{with-fluids*} temporarily changes the values of one or more fluids,
-so that the given procedure and each procedure called by it access the
-given values. After the procedure returns, the old values are restored.
-
-@deffn {Scheme Procedure} with-fluids* fluids values thunk
-@deffnx {C Function} scm_with_fluids (fluids, values, thunk)
-Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
-@var{fluids} must be a list of fluids and @var{values} must be the same
-number of their values to be applied. Each substitution is done
-one after another. @var{thunk} must be a procedure with no argument.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-translation.texi b/doc/ref/scheme-translation.texi
deleted file mode 100644
index 4d398c60f..000000000
--- a/doc/ref/scheme-translation.texi
+++ /dev/null
@@ -1,48 +0,0 @@
-@page
-@node Translation
-@chapter Support for Translating Other Languages
-
-[Describe translation framework.]
-
-@menu
-* Emacs Lisp Support:: Helper primitives for Emacs Lisp.
-@end menu
-
-
-@node Emacs Lisp Support
-@section Emacs Lisp Support
-
-@deffn {Scheme Procedure} nil-car x
-@deffnx {C Function} scm_nil_car (x)
-Return the car of @var{x}, but convert it to LISP nil if it
-is Scheme's end-of-list.
-@end deffn
-
-@deffn {Scheme Procedure} nil-cdr x
-@deffnx {C Function} scm_nil_cdr (x)
-Return the cdr of @var{x}, but convert it to LISP nil if it
-is Scheme's end-of-list.
-@end deffn
-
-@deffn {Scheme Procedure} nil-cons x y
-@deffnx {C Function} scm_nil_cons (x, y)
-Create a new cons cell with @var{x} as the car and @var{y} as
-the cdr, but convert @var{y} to Scheme's end-of-list if it is
-a Lisp nil.
-@end deffn
-
-@deffn {Scheme Procedure} nil-eq x y
-Compare @var{x} and @var{y} and return Lisp's t if they are
-@code{eq?}, return Lisp's nil otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} null x
-@deffnx {C Function} scm_null (x)
-Return Lisp's @code{t} if @var{x} is nil in the LISP sense,
-return Lisp's nil otherwise.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scheme-utility.texi b/doc/ref/scheme-utility.texi
deleted file mode 100644
index f544ac0da..000000000
--- a/doc/ref/scheme-utility.texi
+++ /dev/null
@@ -1,731 +0,0 @@
-@page
-@node Utility Functions
-@chapter General Utility Functions
-
-@c FIXME::martin: Review me!
-
-This chapter contains information about procedures which are not cleanly
-tied to a specific data type. Because of their wide range of
-applications, they are collected in a @dfn{utility} chapter.
-
-@menu
-* Equality:: When are two values `the same'?
-* Object Properties:: A modern interface to object properties.
-* Sorting:: Sort utility procedures.
-* Copying:: Copying deep structures.
-* General Conversion:: Converting objects to strings.
-* Hooks:: User-customizable event lists.
-@end menu
-
-
-@node Equality
-@section Equality
-
-@c FIXME::martin: Review me!
-
-@cindex sameness
-@cindex equality
-
-Three different kinds of @dfn{sameness} are defined in Scheme.
-
-@itemize @bullet
-@item
-Two values can refer to exactly the same object.
-
-@item
-Two objects can have the same @dfn{value}.
-
-@item
-Two objects can be structurally equivalent.
-@end itemize
-
-The differentiation between these three kinds is important, because
-determining whether two values are the same objects is very efficient,
-while determining structural equivalence can be quite expensive
-(consider comparing two very long lists). Therefore, three different
-procedures for testing for equality are provided, which correspond to
-the three kinds of @dfn{sameness} defined above.
-
-@rnindex eq?
-@deffn {Scheme Procedure} eq? x y
-Return @code{#t} iff @var{x} references the same object as @var{y}.
-@code{eq?} is similar to @code{eqv?} except that in some cases it is
-capable of discerning distinctions finer than those detectable by
-@code{eqv?}.
-@end deffn
-
-@rnindex eqv?
-@deffn {Scheme Procedure} eqv? x y
-The @code{eqv?} procedure defines a useful equivalence relation on objects.
-Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
-regarded as the same object. This relation is left slightly open to
-interpretation, but works for comparing immediate integers, characters,
-and inexact numbers.
-@end deffn
-
-@rnindex equal?
-@deffn {Scheme Procedure} equal? x y
-Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
-@code{equal?} recursively compares the contents of pairs,
-vectors, and strings, applying @code{eqv?} on other objects such as
-numbers and symbols. A rule of thumb is that objects are generally
-@code{equal?} if they print the same. @code{equal?} may fail to
-terminate if its arguments are circular data structures.
-@end deffn
-
-
-@node Object Properties
-@section Object Properties
-
-It's often useful to associate a piece of additional information with a
-Scheme object even though that object does not have a dedicated slot
-available in which the additional information could be stored. Object
-properties allow you to do just that.
-
-An object property is most commonly used to associate one kind of
-additional information with each instance of a class of similar Scheme
-objects. For example, all procedures have a `name' property, which
-stores the name of the variable in which the procedure was stored by a
-@code{define} expression, or @code{#f} if the procedure wasn't created
-by that kind of expression.
-
-Guile's representation of an object property is a procedure-with-setter
-(@pxref{Procedures with Setters}) that can be used with the generalized
-form of @code{set!} (REFFIXME) to set and retrieve that property for any
-Scheme object. So, setting a property looks like this:
-
-@lisp
-(set! (my-property obj1) value-for-obj1)
-(set! (my-property obj2) value-for-obj2)
-@end lisp
-
-@noindent
-And retrieving values of the same property looks like this:
-
-@lisp
-(my-property obj1)
-@result{}
-value-for-obj1
-
-(my-property obj2)
-@result{}
-value-for-obj2
-@end lisp
-
-To create an object property in the first place, use the
-@code{make-object-property} procedure:
-
-@lisp
-(define my-property (make-object-property))
-@end lisp
-
-@deffn {Scheme Procedure} make-object-property
-Create and return an object property. An object property is a
-procedure-with-setter that can be called in two ways. @code{(set!
-(@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
-to @var{val}. @code{(@var{property} @var{obj})} returns the current
-setting of @var{obj}'s @var{property}.
-@end deffn
-
-A single object property created by @code{make-object-property} can
-associate distinct property values with all Scheme values that are
-distinguishable by @code{eq?} (including, for example, integers).
-
-Internally, object properties are implemented using a weak key hash
-table. This means that, as long as a Scheme value with property values
-is protected from garbage collection, its property values are also
-protected. When the Scheme value is collected, its entry in the
-property table is removed and so the (ex-) property values are no longer
-protected by the table.
-
-@menu
-* Property Primitives:: Low level property implementation.
-* Old-fashioned Properties:: An older approach to properties.
-@end menu
-
-
-@node Property Primitives
-@subsection Low Level Property Implementation.
-
-@deffn {Scheme Procedure} primitive-make-property not_found_proc
-@deffnx {C Function} scm_primitive_make_property (not_found_proc)
-Create a @dfn{property token} that can be used with
-@code{primitive-property-ref} and @code{primitive-property-set!}.
-See @code{primitive-property-ref} for the significance of
-@var{not_found_proc}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-ref prop obj
-@deffnx {C Function} scm_primitive_property_ref (prop, obj)
-Return the property @var{prop} of @var{obj}. When no value
-has yet been associated with @var{prop} and @var{obj}, call
-@var{not-found-proc} instead (see @code{primitive-make-property})
-and use its return value. That value is also associated with
-@var{obj} via @code{primitive-property-set!}. When
-@var{not-found-proc} is @code{#f}, use @code{#f} as the
-default value of @var{prop}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-set! prop obj val
-@deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
-Associate @var{code} with @var{prop} and @var{obj}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-del! prop obj
-@deffnx {C Function} scm_primitive_property_del_x (prop, obj)
-Remove any value associated with @var{prop} and @var{obj}.
-@end deffn
-
-
-@node Old-fashioned Properties
-@subsection An Older Approach to Properties
-
-Traditionally, Lisp systems provide a different object property
-interface to that provided by @code{make-object-property}, in which the
-object property that is being set or retrieved is indicated by a symbol.
-
-Guile includes this older kind of interface as well, but it may well be
-removed in a future release, as it is less powerful than
-@code{make-object-property} and so increases the size of the Guile
-library for no benefit. (And it is trivial to write a compatibility
-layer in Scheme.)
-
-@deffn {Scheme Procedure} object-properties obj
-@deffnx {C Function} scm_object_properties (obj)
-Return @var{obj}'s property list.
-@end deffn
-
-@deffn {Scheme Procedure} set-object-properties! obj alist
-@deffnx {C Function} scm_set_object_properties_x (obj, alist)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
-@deffn {Scheme Procedure} object-property obj key
-@deffnx {C Function} scm_object_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
-@deffn {Scheme Procedure} set-object-property! obj key value
-@deffnx {C Function} scm_set_object_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key}
-to @var{value}.
-@end deffn
-
-
-@node Sorting
-@section Sorting
-
-@c FIXME::martin: Review me!
-
-@cindex sorting
-@cindex sorting lists
-@cindex sorting vectors
-
-Sorting is very important in computer programs. Therefore, Guile comes
-with several sorting procedures built-in. As always, procedures with
-names ending in @code{!} are side-effecting, that means that they may
-modify their parameters in order to produce their results.
-
-The first group of procedures can be used to merge two lists (which must
-be already sorted on their own) and produce sorted lists containing
-all elements of the input lists.
-
-@deffn {Scheme Procedure} merge alist blist less
-@deffnx {C Function} scm_merge (alist, blist, less)
-Merge two already sorted lists into one.
-Given two lists @var{alist} and @var{blist}, such that
-@code{(sorted? alist less?)} and @code{(sorted? blist less?)},
-return a new list in which the elements of @var{alist} and
-@var{blist} have been stably interleaved so that
-@code{(sorted? (merge alist blist less?) less?)}.
-Note: this does _not_ accept vectors.
-@end deffn
-
-@deffn {Scheme Procedure} merge! alist blist less
-@deffnx {C Function} scm_merge_x (alist, blist, less)
-Takes two lists @var{alist} and @var{blist} such that
-@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
-returns a new list in which the elements of @var{alist} and
-@var{blist} have been stably interleaved so that
- @code{(sorted? (merge alist blist less?) less?)}.
-This is the destructive variant of @code{merge}
-Note: this does _not_ accept vectors.
-@end deffn
-
-The following procedures can operate on sequences which are either
-vectors or list. According to the given arguments, they return sorted
-vectors or lists, respectively. The first of the following procedures
-determines whether a sequence is already sorted, the other sort a given
-sequence. The variants with names starting with @code{stable-} are
-special in that they maintain a special property of the input sequences:
-If two or more elements are the same according to the comparison
-predicate, they are left in the same order as they appeared in the
-input.
-
-@deffn {Scheme Procedure} sorted? items less
-@deffnx {C Function} scm_sorted_p (items, less)
-Return @code{#t} iff @var{items} is a list or a vector such that
-for all 1 <= i <= m, the predicate @var{less} returns true when
-applied to all elements i - 1 and i
-@end deffn
-
-@deffn {Scheme Procedure} sort items less
-@deffnx {C Function} scm_sort (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. This is not a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} sort! items less
-@deffnx {C Function} scm_sort_x (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. The sorting is destructive, that means that the
-input sequence is modified to produce the sorted result.
-This is not a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} stable-sort items less
-@deffnx {C Function} scm_stable_sort (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-This is a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} stable-sort! items less
-@deffnx {C Function} scm_stable_sort_x (items, less)
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-The sorting is destructive, that means that the input sequence
-is modified to produce the sorted result.
-This is a stable sort.
-@end deffn
-
-The procedures in the last group only accept lists or vectors as input,
-as their names indicate.
-
-@deffn {Scheme Procedure} sort-list items less
-@deffnx {C Function} scm_sort_list (items, less)
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. This is a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} sort-list! items less
-@deffnx {C Function} scm_sort_list_x (items, less)
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. The sorting is destructive, that means that the
-input list is modified to produce the sorted result.
-This is a stable sort.
-@end deffn
-
-@deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
-@deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
-Sort the vector @var{vec}, using @var{less} for comparing
-the vector elements. @var{startpos} and @var{endpos} delimit
-the range of the vector which gets sorted. The return value
-is not specified.
-@end deffn
-
-
-@node Copying
-@section Copying Deep Structures
-
-@c FIXME::martin: Review me!
-
-The procedures for copying lists (@pxref{Lists}) only produce a flat
-copy of the input list, and currently Guile does not even contain
-procedures for copying vectors. @code{copy-tree} can be used for these
-application, as it does not only copy the spine of a list, but also
-copies any pairs in the cars of the input lists.
-
-@deffn {Scheme Procedure} copy-tree obj
-@deffnx {C Function} scm_copy_tree (obj)
-Recursively copy the data tree that is bound to @var{obj}, and return a
-pointer to the new data structure. @code{copy-tree} recurses down the
-contents of both pairs and vectors (since both cons cells and vector
-cells may point to arbitrary objects), and stops recursing when it hits
-any other object.
-@end deffn
-
-
-@node General Conversion
-@section General String Conversion
-
-@c FIXME::martin: Review me!
-
-When debugging Scheme programs, but also for providing a human-friendly
-interface, a procedure for converting any Scheme object into string
-format is very useful. Conversion from/to strings can of course be done
-with specialized procedures when the data type of the object to convert
-is known, but with this procedure, it is often more comfortable.
-
-@code{object->string} converts an object by using a print procedure for
-writing to a string port, and then returning the resulting string.
-Converting an object back from the string is only possible if the object
-type has a read syntax and the read syntax is preserved by the printing
-procedure.
-
-@deffn {Scheme Procedure} object->string obj [printer]
-@deffnx {C Function} scm_object_to_string (obj, printer)
-Return a Scheme string obtained by printing @var{obj}.
-Printing function can be specified by the optional second
-argument @var{printer} (default: @code{write}).
-@end deffn
-
-
-@node Hooks
-@section Hooks
-@tpindex Hooks
-
-A hook is a list of procedures to be called at well defined points in
-time. Typically, an application provides a hook @var{h} and promises
-its users that it will call all of the procedures in @var{h} at a
-defined point in the application's processing. By adding its own
-procedure to @var{h}, an application user can tap into or even influence
-the progress of the application.
-
-Guile itself provides several such hooks for debugging and customization
-purposes: these are listed in a subsection below.
-
-When an application first creates a hook, it needs to know how many
-arguments will be passed to the hook's procedures when the hook is run.
-The chosen number of arguments (which may be none) is declared when the
-hook is created, and all the procedures that are added to that hook must
-be capable of accepting that number of arguments.
-
-A hook is created using @code{make-hook}. A procedure can be added to
-or removed from a hook using @code{add-hook!} or @code{remove-hook!},
-and all of a hook's procedures can be removed together using
-@code{reset-hook!}. When an application wants to run a hook, it does so
-using @code{run-hook}.
-
-@menu
-* Hook Example:: Hook usage by example.
-* Hook Reference:: Reference of all hook procedures.
-* C Hooks:: Hooks for use from C code.
-* Guile Hooks:: Hooks provided by Guile.
-@end menu
-
-
-@node Hook Example
-@subsection Hook Usage by Example
-
-Hook usage is shown by some examples in this section. First, we will
-define a hook of arity 2 --- that is, the procedures stored in the hook
-will have to accept two arguments.
-
-@lisp
-(define hook (make-hook 2))
-hook
-@result{} #<hook 2 40286c90>
-@end lisp
-
-Now we are ready to add some procedures to the newly created hook with
-@code{add-hook!}. In the following example, two procedures are added,
-which print different messages and do different things with their
-arguments.
-
-@lisp
-(add-hook! hook (lambda (x y)
- (display "Foo: ")
- (display (+ x y))
- (newline)))
-(add-hook! hook (lambda (x y)
- (display "Bar: ")
- (display (* x y))
- (newline)))
-@end lisp
-
-Once the procedures have been added, we can invoke the hook using
-@code{run-hook}.
-
-@lisp
-(run-hook hook 3 4)
-@print{} Bar: 12
-@print{} Foo: 7
-@end lisp
-
-Note that the procedures are called in the reverse of the order with
-which they were added. This is because the default behaviour of
-@code{add-hook!} is to add its procedure to the @emph{front} of the
-hook's procedure list. You can force @code{add-hook!} to add its
-procedure to the @emph{end} of the list instead by providing a third
-@code{#t} argument on the second call to @code{add-hook!}.
-
-@lisp
-(add-hook! hook (lambda (x y)
- (display "Foo: ")
- (display (+ x y))
- (newline)))
-(add-hook! hook (lambda (x y)
- (display "Bar: ")
- (display (* x y))
- (newline))
- #t) ; @r{<- Change here!}
-
-(run-hook hook 3 4)
-@print{} Foo: 7
-@print{} Bar: 12
-@end lisp
-
-
-@node Hook Reference
-@subsection Hook Reference
-
-When you create a hook with @code{make-hook}, you must specify the arity
-of the procedures which can be added to the hook. If the arity is not
-given explicitly as an argument to @code{make-hook}, it defaults to
-zero. All procedures of a given hook must have the same arity, and when
-the procedures are invoked using @code{run-hook}, the number of
-arguments passed must match the arity specified at hook creation time.
-
-The order in which procedures are added to a hook matters. If the third
-parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
-procedure is added in front of the procedures which might already be on
-that hook, otherwise the procedure is added at the end. The procedures
-are always called from the front to the end of the list when they are
-invoked via @code{run-hook}.
-
-The ordering of the list of procedures returned by @code{hook->list}
-matches the order in which those procedures would be called if the hook
-was run using @code{run-hook}.
-
-@deffn {Scheme Procedure} make-hook [n_args]
-@deffnx {C Function} scm_make_hook (n_args)
-Create a hook for storing procedure of arity @var{n_args}.
-@var{n_args} defaults to zero. The returned value is a hook
-object to be used with the other hook procedures.
-@end deffn
-
-@deffn {Scheme Procedure} hook? x
-@deffnx {C Function} scm_hook_p (x)
-Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} hook-empty? hook
-@deffnx {C Function} scm_hook_empty_p (hook)
-Return @code{#t} if @var{hook} is an empty hook, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} add-hook! hook proc [append_p]
-@deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
-Add the procedure @var{proc} to the hook @var{hook}. The
-procedure is added to the end if @var{append_p} is true,
-otherwise it is added to the front. The return value of this
-procedure is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} remove-hook! hook proc
-@deffnx {C Function} scm_remove_hook_x (hook, proc)
-Remove the procedure @var{proc} from the hook @var{hook}. The
-return value of this procedure is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} reset-hook! hook
-@deffnx {C Function} scm_reset_hook_x (hook)
-Remove all procedures from the hook @var{hook}. The return
-value of this procedure is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} hook->list hook
-@deffnx {C Function} scm_hook_to_list (hook)
-Convert the procedure list of @var{hook} to a list.
-@end deffn
-
-@deffn {Scheme Procedure} run-hook hook . args
-@deffnx {C Function} scm_run_hook (hook, args)
-Apply all procedures from the hook @var{hook} to the arguments
-@var{args}. The order of the procedure application is first to
-last. The return value of this procedure is not specified.
-@end deffn
-
-If, in C code, you are certain that you have a hook object and well
-formed argument list for that hook, you can also use
-@code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
-does no type checking.
-
-@deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
-The same as @code{scm_run_hook} but without any type checking to confirm
-that @var{hook} is actually a hook object and that @var{args} is a
-well-formed list matching the arity of the hook.
-@end deftypefn
-
-
-@node C Hooks
-@subsection Hooks For C Code.
-
-The hooks already described are intended to be populated by Scheme-level
-procedures. In addition to this, the Guile library provides an
-independent set of interfaces for the creation and manipulation of hooks
-that are designed to be populated by functions implemented in C.
-
-The original motivation here was to provide a kind of hook that could
-safely be invoked at various points during garbage collection.
-Scheme-level hooks are unsuitable for this purpose as running them could
-itself require memory allocation, which would then invoke garbage
-collection recursively @dots{} However, it is also the case that these
-hooks are easier to work with than the Scheme-level ones if you only
-want to register C functions with them. So if that is mainly what your
-code needs to do, you may prefer to use this interface.
-
-To create a C hook, you should allocate storage for a structure of type
-@code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
-
-@deftp {C Type} scm_t_c_hook
-Data type for a C hook. The internals of this type should be treated as
-opaque.
-@end deftp
-
-@deftp {C Enum} scm_t_c_hook_type
-Enumeration of possible hook types, which are:
-
-@table @code
-@item SCM_C_HOOK_NORMAL
-@vindex SCM_C_HOOK_NORMAL
-Type of hook for which all the registered functions will always be called.
-@item SCM_C_HOOK_OR
-@vindex SCM_C_HOOK_OR
-Type of hook for which the sequence of registered functions will be
-called only until one of them returns C true (a non-NULL pointer).
-@item SCM_C_HOOK_AND
-@vindex SCM_C_HOOK_AND
-Type of hook for which the sequence of registered functions will be
-called only until one of them returns C false (a NULL pointer).
-@end table
-@end deftp
-
-@deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
-Initialize the C hook at memory pointed to by @var{hook}. @var{type}
-should be one of the values of the @code{scm_t_c_hook_type} enumeration,
-and controls how the hook functions will be called. @var{hook_data} is
-a closure parameter that will be passed to all registered hook functions
-when they are called.
-@end deftypefn
-
-To add or remove a C function from a C hook, use @code{scm_c_hook_add}
-or @code{scm_c_hook_remove}. A hook function must expect three
-@code{void *} parameters which are, respectively:
-
-@table @var
-@item hook_data
-The hook closure data that was specified at the time the hook was
-initialized by @code{scm_c_hook_init}.
-
-@item func_data
-The function closure data that was specified at the time that that
-function was registered with the hook by @code{scm_c_hook_add}.
-
-@item data
-The call closure data specified by the @code{scm_c_hook_run} call that
-runs the hook.
-@end table
-
-@deftp {C Type} scm_t_c_hook_function
-Function type for a C hook function: takes three @code{void *}
-parameters and returns a @code{void *} result.
-@end deftp
-
-@deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
-Add function @var{func}, with function closure data @var{func_data}, to
-the C hook @var{hook}. The new function is appended to the hook's list
-of functions if @var{appendp} is non-zero, otherwise prepended.
-@end deftypefn
-
-@deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
-Remove function @var{func}, with function closure data @var{func_data},
-from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
-@var{func} and @var{func_data} so as to allow for the same @var{func}
-being registered multiple times with different closure data.
-@end deftypefn
-
-Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
-specifying the hook and the call closure data for this run:
-
-@deftypefn {C Function} void * scm_c_hook_run (scm_t_c_hook *hook, void *data)
-Run the C hook @var{hook} will call closure data @var{data}. Subject to
-the variations for hook types @code{SCM_C_HOOK_OR} and
-@code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
-registered functions in turn, passing them the hook's closure data, each
-function's closure data, and the call closure data.
-
-@code{scm_c_hook_run}'s return value is the return value of the last
-function to be called.
-@end deftypefn
-
-
-@node Guile Hooks
-@subsection Hooks Provided by Guile
-
-@menu
-* GC Hooks:: Garbage collection hooks.
-* REPL Hooks:: Hooks into the Guile REPL.
-@end menu
-
-
-@node GC Hooks
-@subsubsection Hooks for Garbage Collection
-
-Whenever Guile performs a garbage collection, it calls the following
-hooks in the order shown.
-
-@defvr {C Hook} scm_before_gc_c_hook
-C hook called at the very start of a garbage collection, after setting
-@code{scm_gc_running_p} to 1, but before entering the GC critical
-section.
-
-If garbage collection is blocked because @code{scm_block_gc} is
-non-zero, GC exits early soon after calling this hook, and no further
-hooks will be called.
-@end defvr
-
-@defvr {C Hook} scm_before_mark_c_hook
-C hook called before beginning the mark phase of garbage collection,
-after the GC thread has entered a critical section.
-@end defvr
-
-@defvr {C Hook} scm_before_sweep_c_hook
-C hook called before beginning the sweep phase of garbage collection.
-This is the same as at the end of the mark phase, since nothing else
-happens between marking and sweeping.
-@end defvr
-
-@defvr {C Hook} scm_after_sweep_c_hook
-C hook called after the end of the sweep phase of garbage collection,
-but while the GC thread is still inside its critical section.
-@end defvr
-
-@defvr {C Hook} scm_after_gc_c_hook
-C hook called at the very end of a garbage collection, after the GC
-thread has left its critical section.
-@end defvr
-
-@defvr {Scheme Hook} after-gc-hook
-@vindex scm_after_gc_hook
-Scheme hook with arity 0. This hook is run asynchronously
-(@pxref{Asyncs}) soon after the GC has completed and any other events
-that were deferred during garbage collection have been processed. (Also
-accessible from C with the name @code{scm_after_gc_hook}.)
-@end defvr
-
-All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
-initialized with hook closure data NULL, are are invoked by
-@code{scm_c_hook_run} with call closure data NULL.
-
-@cindex guardians, testing for GC'd objects
-The Scheme hook @code{after-gc-hook} is particularly useful in
-conjunction with guardians (@pxref{Guardians}). Typically, if you are
-using a guardian, you want to call the guardian after garbage collection
-to see if any of the objects added to the guardian have been collected.
-By adding a thunk that performs this call to @code{after-gc-hook}, you
-can ensure that your guardian is tested after every garbage collection
-cycle.
-
-
-@node REPL Hooks
-@subsubsection Hooks into the Guile REPL
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scm.texi b/doc/ref/scm.texi
deleted file mode 100644
index d4a634eb9..000000000
--- a/doc/ref/scm.texi
+++ /dev/null
@@ -1,181 +0,0 @@
-@page
-@node API Overview
-@chapter Overview of the Guile API
-
-Guile's application programming interface (@dfn{API}) makes
-functionality available that an application developer can use in either
-C or Scheme programming. The interface consists of @dfn{elements} that
-may be macros, functions or variables in C, and procedures, variables,
-syntax or other types of object in Scheme. Broadly speaking, the
-interface as a whole can be divided into three groups.
-
-@enumerate
-@item
-Elements that are available equivalently as C functions or Scheme
-procedures.
-
-@item
-Elements that are only available as macros, functions or variables for C
-programming.
-
-@item
-Elements that are only available as procedures or other objects in
-Scheme.
-@end enumerate
-
-Functions/procedures in the first group are often known as
-@dfn{primitives}, @dfn{subrs} or @dfn{builtins}. An example is the
-@code{assq} Scheme procedure, which is also available as @code{scm_assq}
-in C.
-
-Elements in the second and third groups exist because they provide
-additional language-specific benefits in either Scheme or C. Examples
-are the C macro @code{SCM_CONSP}, which is faster and more convenient in
-C programming than the primitive @code{scm_pair_p}, and the
-procedure-with-setter @code{make-object-property}, which provides a
-more convenient property handling interface in Scheme than the
-primitives on which it is based.
-
-@menu
-* Primitives:: Identical function for Scheme and C.
-* C Only:: Elements only available in C.
-* Scheme Only:: Elements only available in Scheme.
-* Reference Layout:: The layout of this part of the manual.
-@end menu
-
-
-@node Primitives
-@section Identical Function in both Scheme and C
-
-They form the majority of the API, and allow both C and Scheme
-programmers to perform identical operations.
-
-@c @node Scheme Primitives
-@c @chapter Writing Scheme primitives in C
-@c - according to the menu in guile.texi - NJ 2001/1/26
-@c @chapter Relationship between Scheme and C functions
-
-@c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
-
-Scheme procedures marked "primitive functions" have a regular interface
-when calling from C, reflected in two areas: the name of a C function, and
-the convention for passing non-required arguments to this function.
-
-@c Although the vast majority of functions support these relationships,
-@c there are some exceptions.
-
-@menu
-* Transforming Scheme name to C name::
-* Structuring argument lists for C functions::
-@c * Exceptions to the regularity::
-@end menu
-
-
-@node Transforming Scheme name to C name
-@subsection Transforming Scheme name to C name
-
-Normally, the name of a C function can be derived given its Scheme name,
-using some simple textual transformations:
-
-@itemize @bullet
-
-@item
-Replace @code{-} (hyphen) with @code{_} (underscore).
-
-@item
-Replace @code{?} (question mark) with "_p".
-
-@item
-Replace @code{!} (exclamation point) with "_x".
-
-@item
-Replace internal @code{->} with "_to_".
-
-@item
-Replace @code{<=} (less than or equal) with "_leq".
-
-@item
-Replace @code{>=} (greater than or equal) with "_geq".
-
-@item
-Replace @code{<} (less than) with "_less".
-
-@item
-Replace @code{>} (greater than) with "_gr".
-
-@item
-Replace @code{@@} with "at". [Omit?]
-
-@item
-Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).
-
-@item
-[Anything else? --ttn, 2000/01/16 15:17:28]
-
-@end itemize
-
-Here is an Emacs Lisp command that prompts for a Scheme function name and
-inserts the corresponding C function name into the buffer.
-
-@example
-(defun insert-scheme-to-C (name &optional use-gh)
- "Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
-Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
- (interactive "sScheme name: \nP")
- (let ((transforms '(("-" . "_")
- ("?" . "_p")
- ("!" . "_x")
- ("->" . "_to_")
- ("<=" . "_leq")
- (">=" . "_geq")
- ("<" . "_less")
- (">" . "_gr")
- ("@@" . "at"))))
- (while transforms
- (let ((trigger (concat "\\(.*\\)"
- (regexp-quote (caar transforms))
- "\\(.*\\)"))
- (sub (cdar transforms))
- (m nil))
- (while (setq m (string-match trigger name))
- (setq name (concat (match-string 1 name)
- sub
- (match-string 2 name)))))
- (setq transforms (cdr transforms))))
- (insert (if use-gh "gh_" "scm_") name))
-@end example
-
-
-@node Structuring argument lists for C functions
-@subsection Structuring argument lists for C functions
-
-The C function's arguments will be all of the Scheme procedure's
-arguments, both required and optional; if the Scheme procedure takes a
-``rest'' argument, that will be a final argument to the C function. The
-C function's arguments, as well as its return type, will be @code{SCM}.
-
-
-@node C Only
-@section Elements Available Only in C
-
-For C this is usually a matter of better performance (e.g. the
-@code{SCM_CONSP} macro) or of accepting C language types rather than the
-generic @code{SCM}.
-
-
-@node Scheme Only
-@section Elements Available Only in Scheme
-
-
-@node Reference Layout
-@section Reference Material Layout
-
-This part of the reference manual documents all of Guile's core
-Scheme-level language and features in functionally-related groups.
-Where a particular section of the manual includes both R5RS-compliant
-parts and Guile-specific extensions, the text indicates which parts of
-the documentation describe R5RS behaviour and which parts describe Guile
-extensions.
-
-For a quick way of identifying the parts of Guile that implement
-R5RS-compliant features, see the R5RS index: @ref{R5RS Index}.
diff --git a/doc/ref/script-getopt.texi b/doc/ref/script-getopt.texi
deleted file mode 100644
index c71dbd205..000000000
--- a/doc/ref/script-getopt.texi
+++ /dev/null
@@ -1,435 +0,0 @@
-@page
-@node Command Line Handling
-@chapter Handling Command Line Options and Arguments
-
-@c This chapter was written and contributed by Martin Grabmueller.
-
-The ability to accept and handle command line arguments is very
-important when writing Guile scripts to solve particular problems, such
-as extracting information from text files or interfacing with existing
-command line applications. This chapter describes how Guile makes
-command line arguments available to a Guile script, and the utilities
-that Guile provides to help with the processing of command line
-arguments.
-
-@menu
-* Command Line Args:: Using command line arguments.
-* getopt-long:: The (ice-9 getopt-long) module.
-@end menu
-
-
-@node Command Line Args
-@section Using Command Line Arguments
-
-When a Guile script is invoked, Guile makes the command line arguments
-accessible via the procedure @code{command-line}, which returns the
-arguments as a list of strings.
-
-For example, if the script
-
-@example
-#! /usr/local/bin/guile -s
-!#
-(write (command-line))
-(newline)
-@end example
-
-@noindent
-is saved in a file @file{cmdline-test.scm} and invoked using the command
-line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
-is
-
-@example
-("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
-@end example
-
-If the script invocation includes a @code{-e} option, specifying a
-procedure to call after loading the script, Guile will call that
-procedure with @code{(command-line)} as its argument. So a script that
-uses @code{-e} doesn't need to refer explicitly to @code{command-line}
-in its code. For example, the script above would have identical
-behaviour if it was written instead like this:
-
-@example
-#! /usr/local/bin/guile \
--e main -s
-!#
-(define (main args)
- (write args)
- (newline))
-@end example
-
-(Note the use of the meta switch @code{\} so that the script invocation
-can include more than one Guile option: @xref{The Meta Switch}.)
-
-These scripts use the @code{#!} POSIX convention so that they can be
-executed using their own file names directly, as in the example command
-line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they
-can also be executed by typing out the implied Guile command line in
-full, as in:
-
-@example
-$ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
-@end example
-
-@noindent
-or
-
-@example
-$ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
-@end example
-
-Even when a script is invoked using this longer form, the arguments that
-the script receives are the same as if it had been invoked using the
-short form. Guile ensures that the @code{(command-line)} or @code{-e}
-arguments are independent of how the script is invoked, by stripping off
-the arguments that Guile itself processes.
-
-
-@node getopt-long
-@section The (ice-9 getopt-long) Module
-
-A script is free to parse and handle its command line arguments in any
-way that it chooses. Where the set of possible options and arguments is
-complex, however, it can get tricky to extract all the options, check
-the validity of given arguments, and so on. This task can be greatly
-simplified by taking advantage of the module @code{(ice-9 getopt-long)},
-which is distributed with Guile.
-
-The @code{(ice-9 getopt-long)} module exports two procedures:
-@code{getopt-long} and @code{option-ref}.
-
-@itemize @bullet
-@item
-@code{getopt-long} takes a list of strings --- the command line
-arguments --- and an @dfn{option specification}. It parses the command
-line arguments according to the option specification and returns a data
-structure that encapsulates the results of the parsing.
-
-@item
-@code{option-ref} then takes the parsed data structure and a specific
-option's name, and returns information about that option in particular.
-@end itemize
-
-To make these procedures available to your Guile script, include the
-expression @code{(use-modules (ice-9 getopt-long))} somewhere near the
-top, before the first usage of @code{getopt-long} or @code{option-ref}.
-
-@menu
-* getopt-long Example:: A short getopt-long example.
-* Option Specification:: How to write an option specification.
-* Command Line Format:: The expected command line format.
-* getopt-long Reference:: Full documentation for @code{getopt-long}.
-* option-ref Reference:: Full documentation for @code{option-ref}.
-@end menu
-
-
-@node getopt-long Example
-@subsection A Short getopt-long Example
-
-This subsection illustrates how @code{getopt-long} is used by presenting
-and dissecting a simple example. The first thing that we need is an
-@dfn{option specification} that tells @code{getopt-long} how to parse
-the command line. This specification is an association list with the
-long option name as the key. Here is how such a specification might
-look:
-
-@lisp
-(define option-spec
- '((version (single-char #\v) (value #f))
- (help (single-char #\h) (value #f))))
-@end lisp
-
-This alist tells @code{getopt-long} that it should accept two long
-options, called @emph{version} and @emph{help}, and that these options
-can also be selected by the single-letter abbreviations @emph{v} and
-@emph{h}, respectively. The @code{(value #f)} clauses indicate that
-neither of the options accepts a value.
-
-With this specification we can use @code{getopt-long} to parse a given
-command line:
-
-@lisp
-(define options (getopt-long (command-line) option-spec))
-@end lisp
-
-After this call, @code{options} contains the parsed command line and is
-ready to be examined by @code{option-ref}. @code{option-ref} is called
-like this:
-
-@lisp
-(option-ref options 'help #f)
-@end lisp
-
-@noindent
-It expects the parsed command line, a symbol indicating the option to
-examine, and a default value. The default value is returned if the
-option was not present in the command line, or if the option was present
-but without a value; otherwise the value from the command line is
-returned. Usually @code{option-ref} is called once for each possible
-option that a script supports.
-
-The following example shows a main program which puts all this together
-to parse its command line and figure out what the user wanted.
-
-@lisp
-(define (main args)
- (let* ((option-spec '((version (single-char #\v) (value #f))
- (help (single-char #\h) (value #f))))
- (options (getopt-long args option-spec))
- (help-wanted (option-ref options 'help #f))
- (version-wanted (option-ref options 'version #f)))
- (if (or version-wanted help-wanted)
- (begin
- (if version-wanted
- (display "getopt-long-example version 0.3\n"))
- (if help-wanted
- (display "\
-getopt-long-example [options]
- -v, --version Display version
- -h, --help Display this help
-")))
- (begin
- (display "Hello, World!") (newline)))))
-@end lisp
-
-
-@node Option Specification
-@subsection How to Write an Option Specification
-
-An option specification is an association list (@pxref{Association
-Lists}) with one list element for each supported option. The key of each
-list element is a symbol that names the option, while the value is a
-list of option properties:
-
-@lisp
-OPTION-SPEC ::= '( (OPT-NAME1 (PROP-NAME PROP-VALUE) @dots{})
- (OPT-NAME2 (PROP-NAME PROP-VALUE) @dots{})
- (OPT-NAME3 (PROP-NAME PROP-VALUE) @dots{})
- @dots{}
- )
-@end lisp
-
-Each @var{opt-name} specifies the long option name for that option. For
-example, a list element with @var{opt-name} @code{background} specifies
-an option that can be specified on the command line using the long
-option @code{--background}. Further information about the option ---
-whether it takes a value, whether it is required to be present in the
-command line, and so on --- is specified by the option properties.
-
-In the example of the preceding subsection, we already saw that a long
-option name can have a equivalent @dfn{short option} character. The
-equivalent short option character can be set for an option by specifying
-a @code{single-char} property in that option's property list. For
-example, a list element like @code{'(output (single-char #\o) @dots{})}
-specifies an option with long name @code{--output} that can also be
-specified by the equivalent short name @code{-o}.
-
-The @code{value} property specifies whether an option requires or
-accepts a value. If the @code{value} property is set to @code{#t}, the
-option requires a value: @code{getopt-long} will signal an error if the
-option name is present without a corresponding value. If set to
-@code{#f}, the option does not take a value; in this case, a non-option
-word that follows the option name in the command line will be treated as
-a non-option argument. If set to the symbol @code{optional}, the option
-accepts a value but does not require one: a non-option word that follows
-the option name in the command line will be interpreted as that option's
-value. If the option name for an option with @code{'(value optional)}
-is immediately followed in the command line by @emph{another} option
-name, the value for the first option is implicitly @code{#t}.
-
-The @code{required?} property indicates whether an option is required to
-be present in the command line. If the @code{required?} property is
-set to @code{#t}, @code{getopt-long} will signal an error if the option
-is not specified.
-
-Finally, the @code{predicate} property can be used to constrain the
-possible values of an option. If used, the @code{predicate} property
-should be set to a procedure that takes one argument --- the proposed
-option value as a string --- and returns either @code{#t} or @code{#f}
-according as the proposed value is or is not acceptable. If the
-predicate procedure returns @code{#f}, @code{getopt-long} will signal an
-error.
-
-By default, options do not have single-character equivalents, are not
-required, and do not take values. Where the list element for an option
-includes a @code{value} property but no @code{predicate} property, the
-option values are unconstrained.
-
-
-@node Command Line Format
-@subsection Expected Command Line Format
-
-In order for @code{getopt-long} to correctly parse a command line, that
-command line must conform to a standard set of rules for how command
-line options are specified. This subsection explains what those rules
-are.
-
-@code{getopt-long} splits a given command line into several pieces. All
-elements of the argument list are classified to be either options or
-normal arguments. Options consist of two dashes and an option name
-(so-called @dfn{long} options), or of one dash followed by a single
-letter (@dfn{short} options).
-
-Options can behave as switches, when they are given without a value, or
-they can be used to pass a value to the program. The value for an
-option may be specified using an equals sign, or else is simply the next
-word in the command line, so the following two invocations are
-equivalent:
-
-@example
-$ ./foo.scm --output=bar.txt
-$ ./foo.scm --output bar.txt
-@end example
-
-Short options can be used instead of their long equivalents and can be
-grouped together after a single dash. For example, the following
-commands are equivalent.
-
-@example
-$ ./foo.scm --version --help
-$ ./foo.scm -v --help
-$ ./foo.scm -vh
-@end example
-
-If an option requires a value, it can only be grouped together with other
-short options if it is the last option in the group; the value is the
-next argument. So, for example, with the following option
-specification ---
-
-@lisp
-((apples (single-char #\a))
- (blimps (single-char #\b) (value #t))
- (catalexis (single-char #\c) (value #t)))
-@end lisp
-
-@noindent
---- the following command lines would all be acceptable:
-
-@example
-$ ./foo.scm -a -b bang -c couth
-$ ./foo.scm -ab bang -c couth
-$ ./foo.scm -ac couth -b bang
-@end example
-
-But the next command line is an error, because @code{-b} is not the last
-option in its combination, and because a group of short options cannot
-include two options that both require values:
-
-@example
-$ ./foo.scm -abc couth bang
-@end example
-
-If an option's value is optional, @code{getopt-long} decides whether the
-option has a value by looking at what follows it in the argument list.
-If the next element is a string, and it does not appear to be an option
-itself, then that string is the option's value.
-
-If the option @code{--} appears in the argument list, argument parsing
-stops there and subsequent arguments are returned as ordinary arguments,
-even if they resemble options. So, with the command line
-
-@example
-$ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear
-@end example
-
-@noindent
-@code{getopt-long} will recognize the @code{--apples} option as having
-the value "Granny Smith", but will not treat @code{--blimp} as an
-option. The strings @code{--blimp} and @code{Goodyear} will be returned
-as ordinary argument strings.
-
-
-@node getopt-long Reference
-@subsection Reference Documentation for @code{getopt-long}
-
-@deffn {Scheme Procedure} getopt-long args grammar
-Parse the command line given in @var{args} (which must be a list of
-strings) according to the option specification @var{grammar}.
-
-The @var{grammar} argument is expected to be a list of this form:
-
-@code{((@var{option} (@var{property} @var{value}) @dots{}) @dots{})}
-
-where each @var{option} is a symbol denoting the long option, but
-without the two leading dashes (e.g. @code{version} if the option is
-called @code{--version}).
-
-For each option, there may be list of arbitrarily many property/value
-pairs. The order of the pairs is not important, but every property may
-only appear once in the property list. The following table lists the
-possible properties:
-
-@table @asis
-@item @code{(single-char @var{char})}
-Accept @code{-@var{char}} as a single-character equivalent to
-@code{--@var{option}}. This is how to specify traditional Unix-style
-flags.
-@item @code{(required? @var{bool})}
-If @var{bool} is true, the option is required. @code{getopt-long} will
-raise an error if it is not found in @var{args}.
-@item @code{(value @var{bool})}
-If @var{bool} is @code{#t}, the option accepts a value; if it is
-@code{#f}, it does not; and if it is the symbol @code{optional}, the
-option may appear in @var{args} with or without a value.
-@item @code{(predicate @var{func})}
-If the option accepts a value (i.e. you specified @code{(value #t)} for
-this option), then @code{getopt-long} will apply @var{func} to the
-value, and throw an exception if it returns @code{#f}. @var{func}
-should be a procedure which accepts a string and returns a boolean
-value; you may need to use quasiquotes to get it into @var{grammar}.
-@end table
-@end deffn
-
-@code{getopt-long}'s @var{args} parameter is expected to be a list of
-strings like the one returned by @code{command-line}, with the first
-element being the name of the command. Therefore @code{getopt-long}
-ignores the first element in @var{args} and starts argument
-interpretation with the second element.
-
-@code{getopt-long} signals an error if any of the following conditions
-hold.
-
-@itemize @bullet
-@item
-The option grammar has an invalid syntax.
-
-@item
-One of the options in the argument list was not specified by the
-grammar.
-
-@item
-A required option is omitted.
-
-@item
-An option which requires an argument did not get one.
-
-@item
-An option that doesn't accept an argument does get one (this can only
-happen using the long option @code{--opt=@var{value}} syntax).
-
-@item
-An option predicate fails.
-@end itemize
-
-
-@node option-ref Reference
-@subsection Reference Documentation for @code{option-ref}
-
-@deffn {Scheme Procedure} option-ref options key default
-Search @var{options} for a command line option named @var{key} and
-return its value, if found. If the option has no value, but was given,
-return @code{#t}. If the option was not given, return @var{default}.
-@var{options} must be the result of a call to @code{getopt-long}.
-@end deffn
-
-@code{option-ref} always succeeds, either by returning the requested
-option value from the command line, or the default value.
-
-The special key @code{'()} can be used to get a list of all
-non-option arguments.
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/scripts.texi b/doc/ref/scripts.texi
deleted file mode 100644
index 10549dc12..000000000
--- a/doc/ref/scripts.texi
+++ /dev/null
@@ -1,225 +0,0 @@
-@page
-@node Guile Scripting
-@chapter Guile Scripting
-
-Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
-script is simply a file of Scheme code with some extra information at
-the beginning which tells the operating system how to invoke Guile, and
-then tells Guile how to handle the Scheme code.
-
-@menu
-* Invoking Guile:: How to start a Guile script.
-* The Meta Switch:: Passing complex argument lists to Guile
- from shell scripts.
-@end menu
-
-@node Invoking Guile
-@section Invoking Guile
-
-Here we describe Guile's command-line processing in detail. Guile
-processes its arguments from left to right, recognizing the switches
-described below. For examples, see @ref{Scripting Examples}.
-
-@table @code
-
-@item -s @var{script} @var{arg...}
-Read and evaluate Scheme source code from the file @var{script}, as the
-@code{load} function would. After loading @var{script}, exit. Any
-command-line arguments @var{arg...} following @var{script} become the
-script's arguments; the @code{command-line} function returns a list of
-strings of the form @code{(@var{script} @var{arg...})}.
-
-@item -c @var{expr} @var{arg...}
-Evaluate @var{expr} as Scheme code, and then exit. Any command-line
-arguments @var{arg...} following @var{expr} become command-line arguments; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -- @var{arg...}
-Run interactively, prompting the user for expressions and evaluating
-them. Any command-line arguments @var{arg...} following the @code{--}
-become command-line arguments for the interactive session; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -l @var{file}
-Load Scheme source code from @var{file}, and continue processing the
-command line.
-
-@item -e @var{function}
-Make @var{function} the @dfn{entry point} of the script. After loading
-the script file (with @code{-s}) or evaluating the expression (with
-@code{-c}), apply @var{function} to a list containing the program name
-and the command-line arguments --- the list provided by the
-@code{command-line} function.
-
-A @code{-e} switch can appear anywhere in the argument list, but Guile
-always invokes the @var{function} as the @emph{last} action it performs.
-This is weird, but because of the way script invocation works under
-POSIX, the @code{-s} option must always come last in the list.
-
-@xref{Scripting Examples}.
-
-@item -ds
-Treat a final @code{-s} option as if it occurred at this point in the
-command line; load the script here.
-
-This switch is necessary because, although the POSIX script invocation
-mechanism effectively requires the @code{-s} option to appear last, the
-programmer may well want to run the script before other actions
-requested on the command line. For examples, see @ref{Scripting
-Examples}.
-
-@item \
-Read more command-line arguments, starting from the second line of the
-script file. @xref{The Meta Switch}.
-
-@item --emacs
-Assume Guile is running as an inferior process of Emacs, and use a
-special protocol to communicate with Emacs's Guile interaction mode.
-This switch sets the global variable use-emacs-interface to @code{#t}.
-
-This switch is still experimental.
-
-@item --use-srfi=@var{list}
-The option @code{--use-srfi} expects a comma-separated list of numbers,
-each representing a SRFI number to be loaded into the interpreter
-before starting evaluating a script file or the REPL. Additionally,
-the feature identifier for the loaded SRFIs is recognized by
-`cond-expand' when using this option.
-
-@example
-guile --use-srfi=8,13
-@end example
-
-@item --debug
-Start with the debugging evaluator and enable backtraces. Using the
-debugging evaluator will give you better error messages but it will
-slow down execution. By default, the debugging evaluator is only used
-when entering an interactive session. When executing a script with
-@code{-s} or @code{-c}, the normal, faster evaluator is used by default.
-
-@vnew{1.8}
-@item --no-debug
-Do not use the debugging evaluator, even when entering an interactive
-session.
-
-@item -h@r{, }--help
-Display help on invoking Guile, and then exit.
-
-@item -v@r{, }--version
-Display the current version of Guile, and then exit.
-
-@end table
-
-
-@node The Meta Switch
-@section The Meta Switch
-
-Guile's command-line switches allow the programmer to describe
-reasonably complicated actions in scripts. Unfortunately, the POSIX
-script invocation mechanism only allows one argument to appear on the
-@samp{#!} line after the path to the Guile executable, and imposes
-arbitrary limits on that argument's length. Suppose you wrote a script
-starting like this:
-@example
-#!/usr/local/bin/guile -e main -s
-!#
-(define (main args)
- (map (lambda (arg) (display arg) (display " "))
- (cdr args))
- (newline))
-@end example
-The intended meaning is clear: load the file, and then call @code{main}
-on the command-line arguments. However, the system will treat
-everything after the Guile path as a single argument --- the string
-@code{"-e main -s"} --- which is not what we want.
-
-As a workaround, the meta switch @code{\} allows the Guile programmer to
-specify an arbitrary number of options without patching the kernel. If
-the first argument to Guile is @code{\}, Guile will open the script file
-whose name follows the @code{\}, parse arguments starting from the
-file's second line (according to rules described below), and substitute
-them for the @code{\} switch.
-
-Working in concert with the meta switch, Guile treats the characters
-@samp{#!} as the beginning of a comment which extends through the next
-line containing only the characters @samp{!#}. This sort of comment may
-appear anywhere in a Guile program, but it is most useful at the top of
-a file, meshing magically with the POSIX script invocation mechanism.
-
-Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
-@example
-#!/usr/local/bin/guile \
--e main -s
-!#
-(define (main args)
- (map (lambda (arg) (display arg) (display " "))
- (cdr args))
- (newline))
-@end example
-
-Suppose a user invokes this script as follows:
-@example
-$ /u/jimb/ekko a b c
-@end example
-
-Here's what happens:
-@itemize @bullet
-
-@item
-the operating system recognizes the @samp{#!} token at the top of the
-file, and rewrites the command line to:
-@example
-/usr/local/bin/guile \ /u/jimb/ekko a b c
-@end example
-This is the usual behavior, prescribed by POSIX.
-
-@item
-When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
-@file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
-and @code{-s} from it, and substitutes them for the @code{\} switch.
-Thus, Guile's command line now reads:
-@example
-/usr/local/bin/guile -e main -s /u/jimb/ekko a b c
-@end example
-
-@item
-Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
-file of Scheme code (treating the first three lines as a comment), and
-then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
-
-@end itemize
-
-
-When Guile sees the meta switch @code{\}, it parses command-line
-argument from the script file according to the following rules:
-@itemize @bullet
-
-@item
-Each space character terminates an argument. This means that two
-spaces in a row introduce an argument @code{""}.
-
-@item
-The tab character is not permitted (unless you quote it with the
-backslash character, as described below), to avoid confusion.
-
-@item
-The newline character terminates the sequence of arguments, and will
-also terminate a final non-empty argument. (However, a newline
-following a space will not introduce a final empty-string argument;
-it only terminates the argument list.)
-
-@item
-The backslash character is the escape character. It escapes backslash,
-space, tab, and newline. The ANSI C escape sequences like @code{\n} and
-@code{\t} are also supported. These produce argument constituents; the
-two-character combination @code{\n} doesn't act like a terminating
-newline. The escape sequence @code{\@var{NNN}} for exactly three octal
-digits reads as the character whose ASCII code is @var{NNN}. As above,
-characters produced this way are argument constituents. Backslash
-followed by other characters is not allowed.
-
-@end itemize
diff --git a/doc/ref/scsh.texi b/doc/ref/scsh.texi
deleted file mode 100644
index 56177e78f..000000000
--- a/doc/ref/scsh.texi
+++ /dev/null
@@ -1,18 +0,0 @@
-@page
-@node The Scheme shell (scsh)
-@chapter The Scheme shell (scsh)
-
-An incomplete port of the Scheme shell (scsh) is available for Guile
-as a separate package. The current status of guile-scsh can be found at
-@url{http://arglist.com/guile/}.
-
-For information about scsh see
-@url{http://www-swiss.ai.mit.edu/ftpdir/scsh/}.
-
-The closest emulation of scsh can be obtained by running:
-
-@smalllisp
-(load-from-path "scsh/init")
-@end smalllisp
-
-See the USAGE file supplied with guile-scsh for more details.
diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi
deleted file mode 100644
index 4d9e8c14c..000000000
--- a/doc/ref/slib.texi
+++ /dev/null
@@ -1,105 +0,0 @@
-@page
-@node SLIB
-@chapter SLIB
-
-Before the the SLIB facilities can be used, the following Scheme
-expression must be executed:
-
-@smalllisp
-(use-modules (ice-9 slib))
-@end smalllisp
-
-@code{require} can then be used as described in
-@ref{Top, , SLIB, slib, The SLIB Manual}.
-
-For example:
-
-@smalllisp
-guile> (use-modules (ice-9 slib))
-guile> (require 'primes)
-guile> (probably-prime? 13)
-@end smalllisp
-
-@menu
-* SLIB installation::
-* JACAL::
-@end menu
-
-@node SLIB installation
-@section SLIB installation
-
-The following seems to work (e.g., with slib versions 2c7 and 2d2):
-
-@enumerate
-@item
-Unpack slib somewhere, e.g., /usr/local/share/slib.
-
-@item
-Create a symlink in the Guile site directory to slib, e.g.,:
-
-@example
-ln -s /usr/local/share/slib /usr/local/share/guile/site/slib
-@end example
-
-@item
-Use Guile to create the catalog file, e.g.,:
-
-@example
-# guile
-guile> (use-modules (ice-9 slib))
-guile> (load "/usr/local/share/slib/mklibcat.scm")
-guile> (quit)
-@end example
-
-The catalog data should now be in
-@code{/usr/local/share/guile/site/slibcat}.
-
-If instead you get an error such as:
-
-@example
-Unbound variable: scheme-implementation-type
-@end example
-
-then a solution is to get a newer version of Guile,
-or to modify ice-9/slib.scm to use define-public for the
-offending variables.
-
-@item
-Install the documentation:
-
-@example
-cd /usr/local/share/slib
-rm /usr/local/info/slib.info*
-cp slib.info /usr/local/info
-install-info slib.info /usr/local/info/dir
-@end example
-@end enumerate
-
-@node JACAL
-@section JACAL
-
-@cindex Jaffer, Aubrey
-@cindex symbolic math
-@cindex math -- symbolic
-Jacal is a symbolic math package written in Scheme by Aubrey Jaffer. It
-is usually installed as an extra package in SLIB (@pxref{Packages not
-shipped with Guile}).
-
-You can use Guile's interface to SLIB to invoke Jacal:
-
-@smalllisp
-(use-modules (ice-9 slib))
-(slib:load "math")
-(math)
-@end smalllisp
-
-@noindent
-For complete documentation on Jacal, please read the Jacal manual. If
-it has been installed on line, you can look at @ref{Top, , Jacal, jacal,
-The SLIB Manual}. Otherwise you can find it on the web at
-@url{http://www-swiss.ai.mit.edu/~jaffer/JACAL.html}
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
deleted file mode 100644
index 32de27a4b..000000000
--- a/doc/ref/srfi-modules.texi
+++ /dev/null
@@ -1,2399 +0,0 @@
-@page
-@node SRFI Support
-@chapter SRFI Support Modules
-
-SRFI is an acronym for Scheme Request For Implementation. The SRFI
-documents define a lot of syntactic and procedure extensions to standard
-Scheme as defined in R5RS.
-
-Guile has support for a number of SRFIs. This chapter gives an overview
-over the available SRFIs and some usage hints. For complete
-documentation, design rationales and further examples, we advise you to
-get the relevant SRFI documents from the SRFI home page
-@url{http://srfi.schemers.org}.
-
-@menu
-* About SRFI Usage:: What to know about Guile's SRFI support.
-* SRFI-0:: cond-expand
-* SRFI-1:: List library.
-* SRFI-2:: and-let*.
-* SRFI-4:: Homogeneous numeric vector datatypes.
-* SRFI-6:: Basic String Ports.
-* SRFI-8:: receive.
-* SRFI-9:: define-record-type.
-* SRFI-10:: Hash-Comma Reader Extension.
-* SRFI-11:: let-values and let-values*.
-* SRFI-13:: String library.
-* SRFI-14:: Character-set library.
-* SRFI-16:: case-lambda
-* SRFI-17:: Generalized set!
-* SRFI-19:: Time/Date library.
-@end menu
-
-
-@node About SRFI Usage
-@section About SRFI Usage
-
-@c FIXME::martin: Review me!
-
-SRFI support in Guile is currently implemented partly in the core
-library, and partly as add-on modules. That means that some SRFIs are
-automatically available when the interpreter is started, whereas the
-other SRFIs require you to use the appropriate support module
-explicitly.
-
-There are several reasons for this inconsistency. First, the feature
-checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
-available immediately, because it must be there when the user wants to
-check for the Scheme implementation, that is, before she can know that
-it is safe to use @code{use-modules} to load SRFI support modules. The
-second reason is that some features defined in SRFIs had been
-implemented in Guile before the developers started to add SRFI
-implementations as modules (for example SRFI-6 (@pxref{SRFI-6})). In
-the future, it is possible that SRFIs in the core library might be
-factored out into separate modules, requiring explicit module loading
-when they are needed. So you should be prepared to have to use
-@code{use-modules} someday in the future to access SRFI-6 bindings. If
-you want, you can do that already. We have included the module
-@code{(srfi srfi-6)} in the distribution, which currently does nothing,
-but ensures that you can write future-safe code.
-
-Generally, support for a specific SRFI is made available by using
-modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
-number of the SRFI needed. Another possibility is to use the command
-line option @code{--use-srfi}, which will load the necessary modules
-automatically (@pxref{Invoking Guile}).
-
-
-@node SRFI-0
-@section SRFI-0 - cond-expand
-
-@c FIXME::martin: Review me!
-
-SRFI-0 defines a means for checking whether a Scheme implementation has
-support for a specified feature. The syntactic form @code{cond-expand},
-which implements this means, has the following syntax.
-
-@example
-@group
-<cond-expand>
- --> (cond-expand <cond-expand-clause>+)
- | (cond-expand <cond-expand-clause>* (else <command-or-definition>))
-<cond-expand-clause>
- --> (<feature-requirement> <command-or-definition>*)
-<feature-requirement>
- --> <feature-identifier>
- | (and <feature-requirement>*)
- | (or <feature-requirement>*)
- | (not <feature-requirement>)
-<feature-identifier>
- --> <a symbol which is the name or alias of a SRFI>
-@end group
-@end example
-
-When evaluated, this form checks all clauses in order, until it finds
-one whose feature requirement is satisfied. Then the form expands into
-the commands or definitions in the clause. A requirement is tested as
-follows:
-
-@itemize @bullet
-@item
-If it is a symbol, it is satisfied if the feature identifier is
-supported.
-
-@item
-If it is an @code{and} form, all requirements must be satisfied. If no
-requirements are given, it is satisfied, too.
-
-@item
-If it is an @code{or} form, at least one of the requirements must be
-satisfied. If no requirements are given, it is not satisfied.
-
-@item
-If it is a @code{not} form, the feature requirement must @emph{not} be
-satisfied.
-
-@item
-If the feature requirement is the keyword @code{else} and it is the last
-clause, it is satisfied if no prior clause matched.
-@end itemize
-
-If no clause is satisfied, an error is signalled.
-
-Since @code{cond-expand} is needed to tell what a Scheme implementation
-provides, it must be accessible without using any
-implementation-dependent operations, such as @code{use-modules} in
-Guile. Thus, it is not necessary to use any module to get access to
-this form.
-
-Currently, the feature identifiers @code{guile}, @code{r5rs} and
-@code{srfi-0} are supported. The other SRFIs are not in that list by
-default, because the SRFI modules must be explicitly used before their
-exported bindings can be used.
-
-So if a Scheme program wishes to use SRFI-8, it has two possibilities:
-First, it can check whether the running Scheme implementation is Guile,
-and if it is, it can use the appropriate module:
-
-@lisp
-(cond-expand
- (guile
- (use-modules (srfi srfi-8)))
- (srfi-8
- #t))
- ;; otherwise fail.
-@end lisp
-
-The other possibility is to use the @code{--use-srfi} command line
-option when invoking Guile (@pxref{Invoking Guile}). When you do that,
-the specified SRFI support modules will be loaded and add their feature
-identifier to the list of symbols checked by @code{cond-expand}.
-
-So, if you invoke Guile like this:
-
-@example
-$ guile --use-srfi=8
-@end example
-
-the following snippet will expand to @code{'hooray}.
-
-@lisp
-(cond-expand (srfi-8 'hooray))
-@end lisp
-
-
-@node SRFI-1
-@section SRFI-1 - List library
-
-@c FIXME::martin: Review me!
-
-The list library defined in SRFI-1 contains a lot of useful list
-processing procedures for construction, examining, destructuring and
-manipulating lists and pairs.
-
-Since SRFI-1 also defines some procedures which are already contained
-in R5RS and thus are supported by the Guile core library, some list
-and pair procedures which appear in the SRFI-1 document may not appear
-in this section. So when looking for a particular list/pair
-processing procedure, you should also have a look at the sections
-@ref{Lists} and @ref{Pairs}.
-
-@menu
-* SRFI-1 Constructors:: Constructing new lists.
-* SRFI-1 Predicates:: Testing list for specific properties.
-* SRFI-1 Selectors:: Selecting elements from lists.
-* SRFI-1 Length Append etc:: Length calculation and list appending.
-* SRFI-1 Fold and Map:: Higher-order list processing.
-* SRFI-1 Filtering and Partitioning:: Filter lists based on predicates.
-* SRFI-1 Searching:: Search for elements.
-* SRFI-1 Deleting:: Delete elements from lists.
-* SRFI-1 Association Lists:: Handle association lists.
-* SRFI-1 Set Operations:: Use lists for representing sets.
-@end menu
-
-@node SRFI-1 Constructors
-@subsection Constructors
-
-@c FIXME::martin: Review me!
-
-New lists can be constructed by calling one of the following
-procedures.
-
-@deffn {Scheme Procedure} xcons d a
-Like @code{cons}, but with interchanged arguments. Useful mostly when
-passed to higher-order procedures.
-@end deffn
-
-@deffn {Scheme Procedure} list-tabulate n init-proc
-Return an @var{n}-element list, where each list element is produced by
-applying the procedure @var{init-proc} to the corresponding list
-index. The order in which @var{init-proc} is applied to the indices
-is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} circular-list elt1 elt2 @dots{}
-Return a circular list containing the given arguments @var{elt1}
-@var{elt2} @dots{}.
-@end deffn
-
-@deffn {Scheme Procedure} iota count [start step]
-Return a list containing @var{count} elements, where each element is
-calculated as follows:
-
-@var{start} + (@var{count} - 1) * @var{step}
-
-@var{start} defaults to 0 and @var{step} defaults to 1.
-@end deffn
-
-
-@node SRFI-1 Predicates
-@subsection Predicates
-
-@c FIXME::martin: Review me!
-
-The procedures in this section test specific properties of lists.
-
-@deffn {Scheme Procedure} proper-list? obj
-Return @code{#t} if @var{obj} is a proper list, that is a finite list,
-terminated with the empty list. Otherwise, return @code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} circular-list? obj
-Return @code{#t} if @var{obj} is a circular list, otherwise return
-@code{#f}.
-@end deffn
-
-@deffn {Scheme Procedure} dotted-list? obj
-Return @code{#t} if @var{obj} is a dotted list, return @code{#f}
-otherwise. A dotted list is a finite list which is not terminated by
-the empty list, but some other value.
-@end deffn
-
-@deffn {Scheme Procedure} null-list? lst
-Return @code{#t} if @var{lst} is the empty list @code{()}, @code{#f}
-otherwise. If something else than a proper or circular list is passed
-as @var{lst}, an error is signalled. This procedure is recommended
-for checking for the end of a list in contexts where dotted lists are
-not allowed.
-@end deffn
-
-@deffn {Scheme Procedure} not-pair? obj
-Return @code{#t} is @var{obj} is not a pair, @code{#f} otherwise.
-This is shorthand notation @code{(not (pair? @var{obj}))} and is
-supposed to be used for end-of-list checking in contexts where dotted
-lists are allowed.
-@end deffn
-
-@deffn {Scheme Procedure} list= elt= list1 @dots{}
-Return @code{#t} if all argument lists are equal, @code{#f} otherwise.
-List equality is determined by testing whether all lists have the same
-length and the corresponding elements are equal in the sense of the
-equality predicate @var{elt=}. If no or only one list is given,
-@code{#t} is returned.
-@end deffn
-
-
-@node SRFI-1 Selectors
-@subsection Selectors
-
-@c FIXME::martin: Review me!
-
-@deffn {Scheme Procedure} first pair
-@deffnx {Scheme Procedure} second pair
-@deffnx {Scheme Procedure} third pair
-@deffnx {Scheme Procedure} fourth pair
-@deffnx {Scheme Procedure} fifth pair
-@deffnx {Scheme Procedure} sixth pair
-@deffnx {Scheme Procedure} seventh pair
-@deffnx {Scheme Procedure} eighth pair
-@deffnx {Scheme Procedure} ninth pair
-@deffnx {Scheme Procedure} tenth pair
-These are synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}.
-@end deffn
-
-@deffn {Scheme Procedure} car+cdr pair
-Return two values, the @sc{car} and the @sc{cdr} of @var{pair}.
-@end deffn
-
-@deffn {Scheme Procedure} take lst i
-@deffnx {Scheme Procedure} take! lst i
-Return a list containing the first @var{i} elements of @var{lst}.
-
-@code{take!} may modify the structure of the argument list @var{lst}
-in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} drop lst i
-Return a list containing all but the first @var{i} elements of
-@var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} take-right lst i
-Return the a list containing the @var{i} last elements of @var{lst}.
-@end deffn
-
-@deffn {Scheme Procedure} drop-right lst i
-@deffnx {Scheme Procedure} drop-right! lst i
-Return the a list containing all but the @var{i} last elements of
-@var{lst}.
-
-@code{drop-right!} may modify the structure of the argument list
-@var{lst} in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} split-at lst i
-@deffnx {Scheme Procedure} split-at! lst i
-Return two values, a list containing the first @var{i} elements of the
-list @var{lst} and a list containing the remaining elements.
-
-@code{split-at!} may modify the structure of the argument list
-@var{lst} in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} last lst
-Return the last element of the non-empty, finite list @var{lst}.
-@end deffn
-
-
-@node SRFI-1 Length Append etc
-@subsection Length, Append, Concatenate, etc.
-
-@c FIXME::martin: Review me!
-
-@deffn {Scheme Procedure} length+ lst
-Return the length of the argument list @var{lst}. When @var{lst} is a
-circular list, @code{#f} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} concatenate list-of-lists
-@deffnx {Scheme Procedure} concatenate! list-of-lists
-Construct a list by appending all lists in @var{list-of-lists}.
-
-@code{concatenate!} may modify the structure of the given lists in
-order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} append-reverse rev-head tail
-@deffnx {Scheme Procedure} append-reverse! rev-head tail
-Reverse @var{rev-head}, append @var{tail} and return the result. This
-is equivalent to @code{(append (reverse @var{rev-head}) @var{tail})},
-but more efficient.
-
-@code{append-reverse!} may modify @var{rev-head} in order to produce
-the result.
-@end deffn
-
-@deffn {Scheme Procedure} zip lst1 lst2 @dots{}
-Return a list as long as the shortest of the argument lists, where
-each element is a list. The first list contains the first elements of
-the argument lists, the second list contains the second elements, and
-so on.
-@end deffn
-
-@deffn {Scheme Procedure} unzip1 lst
-@deffnx {Scheme Procedure} unzip2 lst
-@deffnx {Scheme Procedure} unzip3 lst
-@deffnx {Scheme Procedure} unzip4 lst
-@deffnx {Scheme Procedure} unzip5 lst
-@code{unzip1} takes a list of lists, and returns a list containing the
-first elements of each list, @code{unzip2} returns two lists, the
-first containing the first elements of each lists and the second
-containing the second elements of each lists, and so on.
-@end deffn
-
-
-@node SRFI-1 Fold and Map
-@subsection Fold, Unfold & Map
-
-@c FIXME::martin: Review me!
-
-@deffn {Scheme Procedure} fold kons knil lst1 lst2 @dots{}
-Fold the procedure @var{kons} across all elements of @var{lst1},
-@var{lst2}, @dots{}. Produce the result of
-
-@code{(@var{kons} @var{en1} @var{en2} @dots{} (@var{kons} @var{e21}
-@var{e22} (@var{kons} @var{e11} @var{e12} @var{knil})))},
-
-if @var{enm} are the elements of the lists @var{lst1}, @var{lst2},
-@dots{}.
-@end deffn
-
-@deffn {Scheme Procedure} fold-right kons knil lst1 lst2 @dots{}
-Similar to @code{fold}, but applies @var{kons} in right-to-left order
-to the list elements, that is:
-
-@code{(@var{kons} @var{e11} @var{e12}(@var{kons} @var{e21}
-@var{e22} @dots{} (@var{kons} @var{en1} @var{en2} @var{knil})))},
-@end deffn
-
-@deffn {Scheme Procedure} pair-fold kons knil lst1 lst2 @dots{}
-Like @code{fold}, but apply @var{kons} to the pairs of the list
-instead of the list elements.
-@end deffn
-
-@deffn {Scheme Procedure} pair-fold-right kons knil lst1 lst2 @dots{}
-Like @code{fold-right}, but apply @var{kons} to the pairs of the list
-instead of the list elements.
-@end deffn
-
-@deffn {Scheme Procedure} reduce f ridentity lst
-@code{reduce} is a variant of @code{reduce}. If @var{lst} is
-@code{()}, @var{ridentity} is returned. Otherwise, @code{(fold (car
-@var{lst}) (cdr @var{lst}))} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} reduce-right f ridentity lst
-This is the @code{fold-right} variant of @var{reduce}.
-@end deffn
-
-@deffn {Scheme Procedure} unfold p f g seed [tail-gen]
-@code{unfold} is defined as follows:
-
-@lisp
-(unfold p f g seed) =
- (if (p seed) (tail-gen seed)
- (cons (f seed)
- (unfold p f g (g seed))))
-@end lisp
-
-@table @var
-@item p
-Determines when to stop unfolding.
-
-@item f
-Maps each seed value to the corresponding list element.
-
-@item g
-Maps each seed value to next seed valu.
-
-@item seed
-The state value for the unfold.
-
-@item tail-gen
-Creates the tail of the list; defaults to @code{(lambda (x) '())}.
-@end table
-
-@var{g} produces a series of seed values, which are mapped to list
-elements by @var{f}. These elements are put into a list in
-left-to-right order, and @var{p} tells when to stop unfolding.
-@end deffn
-
-@deffn {Scheme Procedure} unfold-right p f g seed [tail]
-Construct a list with the following loop.
-
-@lisp
-(let lp ((seed seed) (lis tail))
- (if (p seed) lis
- (lp (g seed)
- (cons (f seed) lis))))
-@end lisp
-
-@table @var
-@item p
-Determines when to stop unfolding.
-
-@item f
-Maps each seed value to the corresponding list element.
-
-@item g
-Maps each seed value to next seed valu.
-
-@item seed
-The state value for the unfold.
-
-@item tail-gen
-Creates the tail of the list; defaults to @code{(lambda (x) '())}.
-@end table
-
-@end deffn
-
-@deffn {Scheme Procedure} map f lst1 lst2 @dots{}
-Map the procedure over the list(s) @var{lst1}, @var{lst2}, @dots{} and
-return a list containing the results of the procedure applications.
-This procedure is extended with respect to R5RS, because the argument
-lists may have different lengths. The result list will have the same
-length as the shortest argument lists. The order in which @var{f}
-will be applied to the list element(s) is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} for-each f lst1 lst2 @dots{}
-Apply the procedure @var{f} to each pair of corresponding elements of
-the list(s) @var{lst1}, @var{lst2}, @dots{}. The return value is not
-specified. This procedure is extended with respect to R5RS, because
-the argument lists may have different lengths. The shortest argument
-list determines the number of times @var{f} is called. @var{f} will
-be applied to the list elements in left-to-right order.
-
-@end deffn
-
-@deffn {Scheme Procedure} append-map f lst1 lst2 @dots{}
-@deffnx {Scheme Procedure} append-map! f lst1 lst2 @dots{}
-Equivalent to
-
-@lisp
-(apply append (map f clist1 clist2 ...))
-@end lisp
-
-and
-
-@lisp
-(apply append! (map f clist1 clist2 ...))
-@end lisp
-
-Map @var{f} over the elements of the lists, just as in the @code{map}
-function. However, the results of the applications are appended
-together to make the final result. @code{append-map} uses
-@code{append} to append the results together; @code{append-map!} uses
-@code{append!}.
-
-The dynamic order in which the various applications of @var{f} are
-made is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} map! f lst1 lst2 @dots{}
-Linear-update variant of @code{map} -- @code{map!} is allowed, but not
-required, to alter the cons cells of @var{lst1} to construct the
-result list.
-
-The dynamic order in which the various applications of @var{f} are
-made is not specified. In the n-ary case, @var{lst2}, @var{lst3},
-@dots{} must have at least as many elements as @var{lst1}.
-@end deffn
-
-@deffn {Scheme Procedure} pair-for-each f lst1 lst2 @dots{}
-Like @code{for-each}, but applies the procedure @var{f} to the pairs
-from which the argument lists are constructed, instead of the list
-elements. The return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} filter-map f lst1 lst2 @dots{}
-Like @code{map}, but only results from the applications of @var{f}
-which are true are saved in the result list.
-@end deffn
-
-
-@node SRFI-1 Filtering and Partitioning
-@subsection Filtering and Partitioning
-
-@c FIXME::martin: Review me!
-
-Filtering means to collect all elements from a list which satisfy a
-specific condition. Partitioning a list means to make two groups of
-list elements, one which contains the elements satisfying a condition,
-and the other for the elements which don't.
-
-@deffn {Scheme Procedure} filter pred lst
-@deffnx {Scheme Procedure} filter! pred lst
-Return a list containing all elements from @var{lst} which satisfy the
-predicate @var{pred}. The elements in the result list have the same
-order as in @var{lst}. The order in which @var{pred} is applied to
-the list elements is not specified.
-
-@code{filter!} is allowed, but not required to modify the structure of
-@end deffn
-
-@deffn {Scheme Procedure} partition pred lst
-@deffnx {Scheme Procedure} partition! pred lst
-Return two lists, one containing all elements from @var{lst} which
-satisfy the predicate @var{pred}, and one list containing the elements
-which do not satisfy the predicated. The elements in the result lists
-have the same order as in @var{lst}. The order in which @var{pred} is
-applied to the list elements is not specified.
-
-@code{partition!} is allowed, but not required to modify the structure of
-the input list.
-@end deffn
-
-@deffn {Scheme Procedure} remove pred lst
-@deffnx {Scheme Procedure} remove! pred lst
-Return a list containing all elements from @var{lst} which do not
-satisfy the predicate @var{pred}. The elements in the result list
-have the same order as in @var{lst}. The order in which @var{pred} is
-applied to the list elements is not specified.
-
-@code{remove!} is allowed, but not required to modify the structure of
-the input list.
-@end deffn
-
-
-@node SRFI-1 Searching
-@subsection Searching
-
-@c FIXME::martin: Review me!
-
-The procedures for searching elements in lists either accept a
-predicate or a comparison object for determining which elements are to
-be searched.
-
-@deffn {Scheme Procedure} find pred lst
-Return the first element of @var{lst} which satisfies the predicate
-@var{pred} and @code{#f} if no such element is found.
-@end deffn
-
-@deffn {Scheme Procedure} find-tail pred lst
-Return the first pair of @var{lst} whose @sc{car} satisfies the
-predicate @var{pred} and @code{#f} if no such element is found.
-@end deffn
-
-@deffn {Scheme Procedure} take-while pred lst
-@deffnx {Scheme Procedure} take-while! pred lst
-Return the longest initial prefix of @var{lst} whose elements all
-satisfy the predicate @var{pred}.
-
-@code{take-while!} is allowed, but not required to modify the input
-list while producing the result.
-@end deffn
-
-@deffn {Scheme Procedure} drop-while pred lst
-Drop the longest initial prefix of @var{lst} whose elements all
-satisfy the predicate @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} span pred lst
-@deffnx {Scheme Procedure} span! pred lst
-@deffnx {Scheme Procedure} break pred lst
-@deffnx {Scheme Procedure} break! pred lst
-@code{span} splits the list @var{lst} into the longest initial prefix
-whose elements all satisfy the predicate @var{pred}, and the remaining
-tail. @code{break} inverts the sense of the predicate.
-
-@code{span!} and @code{break!} are allowed, but not required to modify
-the structure of the input list @var{lst} in order to produce the
-result.
-@end deffn
-
-@deffn {Scheme Procedure} any pred lst1 lst2 @dots{}
-Apply @var{pred} across the lists and return a true value if the
-predicate returns true for any of the list elements(s); return
-@code{#f} otherwise. The true value returned is always the result of
-the first successful application of @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} every pred lst1 lst2 @dots{}
-Apply @var{pred} across the lists and return a true value if the
-predicate returns true for every of the list elements(s); return
-@code{#f} otherwise. The true value returned is always the result of
-the final successful application of @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{}
-Return the index of the leftmost element that satisfies @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} member x lst [=]
-Return the first sublist of @var{lst} whose @sc{car} is equal to
-@var{x}. If @var{x} does no appear in @var{lst}, return @code{#f}.
-Equality is determined by the equality predicate @var{=}, or
-@code{equal?} if @var{=} is not given.
-@end deffn
-
-
-@node SRFI-1 Deleting
-@subsection Deleting
-
-@c FIXME::martin: Review me!
-
-The procedures for deleting elements from a list either accept a
-predicate or a comparison object for determining which elements are to
-be removed.
-
-@deffn {Scheme Procedure} delete x lst [=]
-@deffnx {Scheme Procedure} delete! x lst [=]
-Return a list containing all elements from @var{lst}, but without the
-elements equal to @var{x}. Equality is determined by the equality
-predicate @var{=}, which defaults to @code{equal?} if not given.
-
-@code{delete!} is allowed, but not required to modify the structure of
-the argument list in order to produce the result.
-@end deffn
-
-@deffn {Scheme Procedure} delete-duplicates lst [=]
-@deffnx {Scheme Procedure} delete-duplicates! lst [=]
-Return a list containing all elements from @var{lst}, but without
-duplicate elements. Equality of elements is determined by the
-equality predicate @var{=}, which defaults to @code{equal?} if not
-given.
-
-@code{delete-duplicates!} is allowed, but not required to modify the
-structure of the argument list in order to produce the result.
-@end deffn
-
-
-@node SRFI-1 Association Lists
-@subsection Association Lists
-
-@c FIXME::martin: Review me!
-
-Association lists are described in detail in section @ref{Association
-Lists}. The present section only documents the additional procedures
-for dealing with association lists defined by SRFI-1.
-
-@deffn {Scheme Procedure} assoc key alist [=]
-Return the pair from @var{alist} which matches @var{key}. Equality is
-determined by @var{=}, which defaults to @code{equal?} if not given.
-@var{alist} must be an association lists---a list of pairs.
-@end deffn
-
-@deffn {Scheme Procedure} alist-cons key datum alist
-Equivalent to
-
-@lisp
-(cons (cons @var{key} @var{datum}) @var{alist})
-@end lisp
-
-This procedure is used to coons a new pair onto an existing
-association list.
-@end deffn
-
-@deffn {Scheme Procedure} alist-copy alist
-Return a newly allocated copy of @var{alist}, that means that the
-spine of the list as well as the pairs are copied.
-@end deffn
-
-@deffn {Scheme Procedure} alist-delete key alist [=]
-@deffnx {Scheme Procedure} alist-delete! key alist [=]
-Return a list containing the pairs of @var{alist}, but without the
-pairs whose @sc{cars} are equal to @var{key}. Equality is determined
-by @var{=}, which defaults to @code{equal?} if not given.
-
-@code{alist-delete!} is allowed, but not required to modify the
-structure of the list @var{alist} in order to produce the result.
-@end deffn
-
-
-@node SRFI-1 Set Operations
-@subsection Set Operations on Lists
-
-@c FIXME::martin: Review me!
-
-Lists can be used for representing sets of objects. The procedures
-documented in this section can be used for such set representations.
-Man combining several sets or adding elements, they make sure that no
-object is contained more than once in a given list. Please note that
-lists are not a too efficient implementation method for sets, so if
-you need high performance, you should think about implementing a
-custom data structure for representing sets, such as trees, bitsets,
-hash tables or something similar.
-
-All these procedures accept an equality predicate as the first
-argument. This predicate is used for testing the objects in the list
-sets for sameness.
-
-@deffn {Scheme Procedure} lset<= = list1 @dots{}
-Return @code{#t} if every @var{listi} is a subset of @var{listi+1},
-otherwise return @code{#f}. Returns @code{#t} if called with less
-than two arguments. @var{=} is used for testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset= = list1 list2 @dots{}
-Return @code{#t} if all argument lists are equal. @var{=} is used for
-testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-adjoin = list elt1 @dots{}
-@deffnx {Scheme Procedure} lset-adjoin! = list elt1 @dots{}
-Add all @var{elts} to the list @var{list}, suppressing duplicates and
-return the resulting list. @code{lset-adjoin!} is allowed, but not
-required to modify its first argument. @var{=} is used for testing
-element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-union = list1 @dots{}
-@deffnx {Scheme Procedure} lset-union! = list1 @dots{}
-Return the union of all argument list sets. The union is the set of
-all elements which appear in any of the argument sets.
-@code{lset-union!} is allowed, but not required to modify its first
-argument. @var{=} is used for testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-intersection = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-intersection! = list1 list2 @dots{}
-Return the intersection of all argument list sets. The intersection
-is the set containing all elements which appear in all argument sets.
-@code{lset-intersection!} is allowed, but not required to modify its
-first argument. @var{=} is used for testing element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-difference = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-difference! = list1 list2 @dots{}
-Return the difference of all argument list sets. The difference is
-the the set containing all elements of the first list which do not
-appear in the other lists. @code{lset-difference!} is allowed, but
-not required to modify its first argument. @var{=} is used for testing
-element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-xor = list1 @dots{}
-@deffnx {Scheme Procedure} lset-xor! = list1 @dots{}
-Return the set containing all elements which appear in the first
-argument list set, but not in the second; or, more generally: which
-appear in an odd number of sets. @code{lset-xor!} is allowed, but
-not required to modify its first argument. @var{=} is used for testing
-element equality.
-@end deffn
-
-@deffn {Scheme Procedure} lset-diff+intersection = list1 list2 @dots{}
-@deffnx {Scheme Procedure} lset-diff+intersection! = list1 list2 @dots{}
-Return two values, the difference and the intersection of the argument
-list sets. This works like a combination of @code{lset-difference} and
-@code{lset-intersection}, but is more efficient.
-@code{lset-diff+intersection!} is allowed, but not required to modify
-its first argument. @var{=} is used for testing element equality. You
-have to use some means to deal with the multiple values these
-procedures return (@pxref{Multiple Values}).
-@end deffn
-
-
-@node SRFI-2
-@section SRFI-2 - and-let*
-
-@c FIXME::martin: Review me!
-
-The syntactic form @code{and-let*} combines the conditional evaluation
-form @code{and} with the binding form @var{let*}. Each argument
-expression will be evaluated sequentially, bound to a variable (if a
-variable name is given), but only as long as no expression returns
-the false value @code{#f}.
-
-Use @code{(use-modules (srfi srfi-2)} to access this syntax form.
-
-A short example will demonstrate how it works. In the first expression,
-@var{x} will get bound to 1, but the next expression (@code{#f}) is
-false, so evaluation of the form is stopped, and @code{#f} is returned.
-In the next expression, @var{x} is bound to 1, @var{y} is bound to
-@code{#t} and since no expression in the binding section was false, the
-body of the @code{and-let*} expression is evaluated, which in this case
-returns the value of @var{x}.
-
-@lisp
-(and-let* ((x 1) (y #f)) 42)
-@result{}
-#f
-(and-let* ((x 1) (y #t)) x)
-@result{}
-1
-@end lisp
-
-
-@node SRFI-4
-@section SRFI-4 - Homogeneous numeric vector datatypes.
-
-@c FIXME::martin: Review me!
-
-SRFI-4 defines a set of datatypes for vectors whose elements are all
-of the same numeric type. Vectors for signed and unsigned exact
-integer or inexact real numbers in several precisions are available.
-
-Procedures similar to the vector procedures (@pxref{Vectors}) are
-provided for handling these homogeneous vectors, but they are distinct
-datatypes.
-
-The reason for providing this set of datatypes is that with the
-limitation (all elements must have the same type), it is possible to
-implement them much more memory-efficient than normal, heterogenous
-vectors.
-
-If you want to use these datatypes and the corresponding procedures,
-you have to use the module @code{(srfi srfi-4)}.
-
-Ten vector data types are provided: Unsigned and signed integer values
-with 8, 16, 32 and 64 bits and floating point values with 32 and 64
-bits. In the following descriptions, the tags @code{u8}, @code{s8},
-@code{u16}, @code{s16}, @code{u32}, @code{s32}, @code{u64},
-@code{s64}, @code{f32}, @code{f64}, respectively, are used for
-denoting the various types.
-
-@menu
-* SRFI-4 - Read Syntax:: How to write homogeneous vector literals.
-* SRFI-4 - Procedures:: Available homogeneous vector procedures.
-@end menu
-
-
-@node SRFI-4 - Read Syntax
-@subsection SRFI-4 - Read Syntax
-
-Homogeneous numeric vectors have an external representation (read
-syntax) similar to normal Scheme vectors, but with an additional tag
-telling the vector's type.
-
-@lisp
-#u16(1 2 3)
-@end lisp
-
-denotes a homogeneous numeric vector of three elements, which are the
-values 1, 2 and 3, represented as 16-bit unsigned integers.
-Correspondingly,
-
-@lisp
-#f64(3.1415 2.71)
-@end lisp
-
-denotes a vector of two elements, which are the values 3.1415 and
-2.71, represented as floating-point values of 64 bit precision.
-
-Please note that the read syntax for floating-point vectors conflicts
-with Standard Scheme, because there @code{#f} is defined to be the
-literal false value. That means, that with the loaded SRFI-4 module,
-it is not possible to enter some list like
-
-@lisp
-'(1 #f3)
-@end lisp
-
-and hope that it will be parsed as a three-element list with the
-elements 1, @code{#f} and 3. In normal use, this should be no
-problem, because people tend to terminate tokens sensibly when writing
-Scheme expressions.
-
-@node SRFI-4 - Procedures
-@subsection SRFI-4 Procedures
-
-The procedures listed in this section are provided for all homogeneous
-numeric vector datatypes. For brevity, they are not all documented,
-but a summary of the procedures is given. In the following
-descriptions, you can replace @code{TAG} by any of the datatype
-indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32},
-@code{s32}, @code{u64}, @code{s64}, @code{f32} and @code{f64}.
-
-For example, you can use the procedures @code{u8vector?},
-@code{make-s8vector}, @code{u16vector}, @code{u32vector-length},
-@code{s64vector-ref}, @code{f32vector-set!} or @code{f64vector->list}.
-
-@deffn {Scheme Procedure} TAGvector? obj
-Return @code{#t} if @var{obj} is a homogeneous numeric vector of type
-@code{TAG}.
-@end deffn
-
-@deffn {Scheme Procedure} make-TAGvector n [value]
-Create a newly allocated homogeneous numeric vector of type
-@code{TAG}, which can hold @var{n} elements. If @var{value} is given,
-the vector is initialized with the value, otherwise, the contents of
-the returned vector is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector value1 @dots{}
-Create a newly allocated homogeneous numeric vector of type
-@code{TAG}. The returned vector is as long as the number of arguments
-given, and is initialized with the argument values.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector-length TAGvec
-Return the number of elements in @var{TAGvec}.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector-ref TAGvec i
-Return the element at index @var{i} in @var{TAGvec}.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector-ref TAGvec i value
-Set the element at index @var{i} in @var{TAGvec} to @var{value}. The
-return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} TAGvector->list TAGvec
-Return a newly allocated list holding all elements of @var{TAGvec}.
-@end deffn
-
-@deffn {Scheme Procedure} list->TAGvector lst
-Return a newly allocated homogeneous numeric vector of type @code{TAG},
-initialized with the elements of the list @var{lst}.
-@end deffn
-
-
-@node SRFI-6
-@section SRFI-6 - Basic String Ports
-
-SRFI-6 defines the procedures @code{open-input-string},
-@code{open-output-string} and @code{get-output-string}. These
-procedures are included in the Guile core, so using this module does not
-make any difference at the moment. But it is possible that support for
-SRFI-6 will be factored out of the core library in the future, so using
-this module does not hurt, after all.
-
-@node SRFI-8
-@section SRFI-8 - receive
-
-@code{receive} is a syntax for making the handling of multiple-value
-procedures easier. It is documented in @xref{Multiple Values}.
-
-
-@node SRFI-9
-@section SRFI-9 - define-record-type
-
-This is the SRFI way for defining record types. The Guile
-implementation is a layer above Guile's normal record construction
-procedures (@pxref{Records}). The nice thing about this kind of record
-definition method is that no new names are implicitly created, all
-constructor, accessor and predicates are explicitly given. This reduces
-the risk of variable capture.
-
-The syntax of a record type definition is:
-
-@example
-@group
-<record type definition>
- -> (define-record-type <type name>
- (<constructor name> <field tag> ...)
- <predicate name>
- <field spec> ...)
-<field spec> -> (<field tag> <accessor name>)
- -> (<field tag> <accessor name> <modifier name>)
-<field tag> -> <identifier>
-<... name> -> <identifier>
-@end group
-@end example
-
-Usage example:
-
-@example
-guile> (use-modules (srfi srfi-9))
-guile> (define-record-type :foo (make-foo x) foo?
- (x get-x) (y get-y set-y!))
-guile> (define f (make-foo 1))
-guile> f
-#<:foo x: 1 y: #f>
-guile> (get-x f)
-1
-guile> (set-y! f 2)
-2
-guile> (get-y f)
-2
-guile> f
-#<:foo x: 1 y: 2>
-guile> (foo? f)
-#t
-guile> (foo? 1)
-#f
-@end example
-
-
-@node SRFI-10
-@section SRFI-10 - Hash-Comma Reader Extension
-
-@cindex hash-comma
-@cindex #,()
-The module @code{(srfi srfi-10)} implements the syntax extension
-@code{#,()}, also called hash-comma, which is defined in SRFI-10.
-
-The support for SRFI-10 consists of the procedure
-@code{define-reader-ctor} for defining new reader constructors and the
-read syntax form
-
-@example
-#,(@var{ctor} @var{datum} ...)
-@end example
-
-where @var{ctor} must be a symbol for which a read constructor was
-defined previously, using @code{define-reader-ctor}.
-
-Example:
-
-@lisp
-(define-reader-ctor 'file open-input-file)
-(define f '#,(file "/etc/passwd"))
-(read-line f)
-@result{}
-"root:x:0:0:root:/root:/bin/bash"
-@end lisp
-
-Please note the quote before the @code{#,(file ...)} expression. This
-is necessary because ports are not self-evaluating in Guile.
-
-@deffn {Scheme Procedure} define-reader-ctor symbol proc
-Define @var{proc} as the reader constructor for hash-comma forms with a
-tag @var{symbol}. @var{proc} will be applied to the datum(s) following
-the tag in the hash-comma expression after the complete form has been
-read in. The result of @var{proc} is returned by the Scheme reader.
-@end deffn
-
-
-@node SRFI-11
-@section SRFI-11 - let-values
-
-This module implements the binding forms for multiple values
-@code{let-values} and @code{let-values*}. These forms are similar to
-@code{let} and @code{let*} (@pxref{Local Bindings}), but they support
-binding of the values returned by multiple-valued expressions.
-
-Write @code{(use-modules (srfi srfi-11))} to make the bindings
-available.
-
-@lisp
-(let-values (((x y) (values 1 2))
- ((z f) (values 3 4)))
- (+ x y z f))
-@result{}
-10
-@end lisp
-
-@code{let-values} performs all bindings simultaneously, which means that
-no expression in the binding clauses may refer to variables bound in the
-same clause list. @code{let-values*}, on the other hand, performs the
-bindings sequentially, just like @code{let*} does for single-valued
-expressions.
-
-
-@node SRFI-13
-@section SRFI-13 - String Library
-
-In this section, we will describe all procedures defined in SRFI-13
-(string library) and implemented by the module @code{(srfi srfi-13)}.
-
-Note that only the procedures from SRFI-13 are documented here which are
-not already contained in Guile. For procedures not documented here
-please refer to the relevant chapters in the Guile Reference Manual, for
-example the documentation of strings and string procedures
-(@pxref{Strings}).
-
-All of the procedures defined in SRFI-13, which are not already
-included in the Guile core library, are implemented in the module
-@code{(srfi srfi-13)}. The procedures which are both in Guile and in
-SRFI-13 are slightly extended in this module. Their bindings
-overwrite those in the Guile core.
-
-The procedures which are defined in the section @emph{Low-level
-procedures} of SRFI-13 for parsing optional string indices, substring
-specification checking and Knuth-Morris-Pratt-Searching are not
-implemented.
-
-The procedures @code{string-contains} and @code{string-contains-ci} are
-not implemented very efficiently at the moment. This will be changed as
-soon as possible.
-
-@menu
-* Loading SRFI-13:: How to load SRFI-13 support.
-* SRFI-13 Predicates:: String predicates.
-* SRFI-13 Constructors:: String constructing procedures.
-* SRFI-13 List/String Conversion:: Conversion from/to lists.
-* SRFI-13 Selection:: Selection portions of strings.
-* SRFI-13 Modification:: Modify strings in-place.
-* SRFI-13 Comparison:: Compare strings.
-* SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes.
-* SRFI-13 Searching:: Searching for substrings.
-* SRFI-13 Case Mapping:: Mapping to lower-/upper-case.
-* SRFI-13 Reverse/Append:: Reverse and append strings.
-* SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings.
-* SRFI-13 Replicate/Rotate:: Replicate and rotate portions of strings.
-* SRFI-13 Miscellaneous:: Left-over string procedures.
-* SRFI-13 Filtering/Deleting:: Filter and delete characters from strings.
-@end menu
-
-
-@node Loading SRFI-13
-@subsection Loading SRFI-13
-
-When Guile is properly installed, SRFI-13 support can be loaded into a
-running Guile by using the @code{(srfi srfi-13)} module.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-13))
-guile>
-@end example
-
-When this step causes any errors, Guile is not properly installed.
-
-One possible reason is that Guile cannot find either the Scheme module
-file @file{srfi-13.scm}, or it cannot find the shared object file
-@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the
-Guile load path and that the latter is either installed in some default
-location like @file{/usr/local/lib} or that the directory it was
-installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to
-@file{srfi-14.scm}.
-
-Now you can test whether the SRFI-13 procedures are working by calling
-the @code{string-concatenate} procedure.
-
-@example
-guile> (string-concatenate '("Hello" " " "World!"))
-"Hello World!"
-@end example
-
-@node SRFI-13 Predicates
-@subsection Predicates
-
-In addition to the primitives @code{string?} and @code{string-null?},
-which are already in the Guile core, the string predicates
-@code{string-any} and @code{string-every} are defined by SRFI-13.
-
-@deffn {Scheme Procedure} string-any pred s [start end]
-Check if the predicate @var{pred} is true for any character in
-the string @var{s}, proceeding from left (index @var{start}) to
-right (index @var{end}). If @code{string-any} returns true,
-the returned true value is the one produced by the first
-successful application of @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} string-every pred s [start end]
-Check if the predicate @var{pred} is true for every character
-in the string @var{s}, proceeding from left (index @var{start})
-to right (index @var{end}). If @code{string-every} returns
-true, the returned true value is the one produced by the final
-application of @var{pred} to the last character of @var{s}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Constructors
-@subsection Constructors
-
-SRFI-13 defines several procedures for constructing new strings. In
-addition to @code{make-string} and @code{string} (available in the Guile
-core library), the procedure @code{string-tabulate} does exist.
-
-@deffn {Scheme Procedure} string-tabulate proc len
-@var{proc} is an integer->char procedure. Construct a string
-of size @var{len} by applying @var{proc} to each index to
-produce the corresponding string element. The order in which
-@var{proc} is applied to the indices is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 List/String Conversion
-@subsection List/String Conversion
-
-The procedure @code{string->list} is extended by SRFI-13, that is why it
-is included in @code{(srfi srfi-13)}. The other procedures are new.
-The Guile core already contains the procedure @code{list->string} for
-converting a list of characters into a string (@pxref{List/String
-Conversion}).
-
-@deffn {Scheme Procedure} string->list str [start end]
-Convert the string @var{str} into a list of characters.
-@end deffn
-
-@deffn {Scheme Procedure} reverse-list->string chrs
-An efficient implementation of @code{(compose string->list
-reverse)}:
-
-@smalllisp
-(reverse-list->string '(#\a #\B #\c)) @result{} "cBa"
-@end smalllisp
-@end deffn
-
-@deffn {Scheme Procedure} string-join ls [delimiter grammar]
-Append the string in the string list @var{ls}, using the string
-@var{delim} as a delimiter between the elements of @var{ls}.
-@var{grammar} is a symbol which specifies how the delimiter is
-placed between the strings, and defaults to the symbol
-@code{infix}.
-
-@table @code
-@item infix
-Insert the separator between list elements. An empty string
-will produce an empty list.
-
-@item string-infix
-Like @code{infix}, but will raise an error if given the empty
-list.
-
-@item suffix
-Insert the separator after every list element.
-
-@item prefix
-Insert the separator before each list element.
-@end table
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Selection
-@subsection Selection
-
-These procedures are called @dfn{selectors}, because they access
-information about the string or select pieces of a given string.
-
-Additional selector procedures are documented in the Strings section
-(@pxref{String Selection}), like @code{string-length} or
-@code{string-ref}.
-
-@code{string-copy} is also available in core Guile, but this version
-accepts additional start/end indices.
-
-@deffn {Scheme Procedure} string-copy str [start end]
-Return a freshly allocated copy of the string @var{str}. If
-given, @var{start} and @var{end} delimit the portion of
-@var{str} which is copied.
-@end deffn
-
-@deffn {Scheme Procedure} substring/shared str start [end]
-Like @code{substring}, but the result may share memory with the
-argument @var{str}.
-@end deffn
-
-@deffn {Scheme Procedure} string-copy! target tstart s [start end]
-Copy the sequence of characters from index range [@var{start},
-@var{end}) in string @var{s} to string @var{target}, beginning
-at index @var{tstart}. The characters are copied left-to-right
-or right-to-left as needed - the copy is guaranteed to work,
-even if @var{target} and @var{s} are the same string. It is an
-error if the copy operation runs off the end of the target
-string.
-@end deffn
-
-@deffn {Scheme Procedure} string-take s n
-@deffnx {Scheme Procedure} string-take-right s n
-Return the @var{n} first/last characters of @var{s}.
-@end deffn
-
-@deffn {Scheme Procedure} string-drop s n
-@deffnx {Scheme Procedure} string-drop-right s n
-Return all but the first/last @var{n} characters of @var{s}.
-@end deffn
-
-@deffn {Scheme Procedure} string-pad s len [chr start end]
-@deffnx {Scheme Procedure} string-pad-right s len [chr start end]
-Take that characters from @var{start} to @var{end} from the
-string @var{s} and return a new string, right(left)-padded by the
-character @var{chr} to length @var{len}. If the resulting
-string is longer than @var{len}, it is truncated on the right (left).
-@end deffn
-
-@deffn {Scheme Procedure} string-trim s [char_pred start end]
-@deffnx {Scheme Procedure} string-trim-right s [char_pred start end]
-@deffnx {Scheme Procedure} string-trim-both s [char_pred start end]
-Trim @var{s} by skipping over all characters on the left/right/both
-sides of the string that satisfy the parameter @var{char_pred}:
-
-@itemize @bullet
-@item
-if it is the character @var{ch}, characters equal to
-@var{ch} are trimmed,
-
-@item
-if it is a procedure @var{pred} characters that
-satisfy @var{pred} are trimmed,
-
-@item
-if it is a character set, characters in that set are trimmed.
-@end itemize
-
-If called without a @var{char_pred} argument, all whitespace is
-trimmed.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Modification
-@subsection Modification
-
-The procedure @code{string-fill!} is extended from R5RS because it
-accepts optional start/end indices. This bindings shadows the procedure
-of the same name in the Guile core. The second modification procedure
-@code{string-set!} is documented in the Strings section (@pxref{String
-Modification}).
-
-@deffn {Scheme Procedure} string-fill! str chr [start end]
-Stores @var{chr} in every element of the given @var{str} and
-returns an unspecified value.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Comparison
-@subsection Comparison
-
-The procedures in this section are used for comparing strings in
-different ways. The comparison predicates differ from those in R5RS in
-that they do not only return @code{#t} or @code{#f}, but the mismatch
-index in the case of a true return value.
-
-@code{string-hash} and @code{string-hash-ci} are for calculating hash
-values for strings, useful for implementing fast lookup mechanisms.
-
-@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2]
-Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the
-mismatch index, depending upon whether @var{s1} is less than,
-equal to, or greater than @var{s2}. The mismatch index is the
-largest index @var{i} such that for every 0 <= @var{j} <
-@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is,
-@var{i} is the first position that does not match. The
-character comparison is done case-insensitively.
-@end deffn
-
-@deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}.
-@end deffn
-
-@deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2]
-Compare @var{s1} and @var{s2} and return @code{#f} if the predicate
-fails. Otherwise, the mismatch index is returned (or @var{end1} in the
-case of @code{string=}. These are the case-insensitive variants.
-@end deffn
-
-@deffn {Scheme Procedure} string-hash s [bound start end]
-@deffnx {Scheme Procedure} string-hash-ci s [bound start end]
-Return a hash value of the string @var{s} in the range 0 @dots{}
-@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Prefixes/Suffixes
-@subsection Prefixes/Suffixes
-
-Using these procedures you can determine whether a given string is a
-prefix or suffix of another string or how long a common prefix/suffix
-is.
-
-@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
-Return the length of the longest common prefix/suffix of the two
-strings. @code{string-prefix-length-ci} and
-@code{string-suffix-length-ci} are the case-insensitive variants.
-@end deffn
-
-@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2]
-Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and
-@code{string-suffix-ci?} are the case-insensitive variants.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Searching
-@subsection Searching
-
-Use these procedures to find out whether a string contains a given
-character or a given substring, or a character from a set of characters.
-
-@deffn {Scheme Procedure} string-index s char_pred [start end]
-@deffnx {Scheme Procedure} string-index-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurrence of a character which
-
-@itemize @bullet
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisfies the predicate @var{char_pred}, if it is a
-procedure,
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-skip s char_pred [start end]
-@deffnx {Scheme Procedure} string-skip-right s char_pred [start end]
-Search through the string @var{s} from left to right (right to left),
-returning the index of the first (last) occurrence of a character which
-
-@itemize @bullet
-@item
-does not equal @var{char_pred}, if it is character,
-
-@item
-does not satisfy the predicate @var{char_pred}, if it is
-a procedure.
-
-@item
-is not in the set if @var{char_pred} is a character set.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-count s char_pred [start end]
-Return the count of the number of characters in the string
-@var{s} which
-
-@itemize @bullet
-@item
-equals @var{char_pred}, if it is character,
-
-@item
-satisfies the predicate @var{char_pred}, if it is a procedure.
-
-@item
-is in the set @var{char_pred}, if it is a character set.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2]
-@deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2]
-Does string @var{s1} contain string @var{s2}? Return the index
-in @var{s1} where @var{s2} occurs as a substring, or false.
-The optional start/end indices restrict the operation to the
-indicated substrings.
-
-@code{string-contains-ci} is the case-insensitive variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Case Mapping
-@subsection Alphabetic Case Mapping
-
-These procedures convert the alphabetic case of strings. They are
-similar to the procedures in the Guile core, but are extended to handle
-optional start/end indices.
-
-@deffn {Scheme Procedure} string-upcase s [start end]
-@deffnx {Scheme Procedure} string-upcase! s [start end]
-Upcase every character in @var{s}. @code{string-upcase!} is the
-side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} string-downcase s [start end]
-@deffnx {Scheme Procedure} string-downcase! s [start end]
-Downcase every character in @var{s}. @code{string-downcase!} is the
-side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} string-titlecase s [start end]
-@deffnx {Scheme Procedure} string-titlecase! s [start end]
-Upcase every first character in every word in @var{s}, downcase the
-other characters. @code{string-titlecase!} is the side-effecting
-variant.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Reverse/Append
-@subsection Reverse/Append
-
-One appending procedure, @code{string-append} is the same in R5RS and in
-SRFI-13, so it is not redefined.
-
-@deffn {Scheme Procedure} string-reverse str [start end]
-@deffnx {Scheme Procedure} string-reverse! str [start end]
-Reverse the string @var{str}. The optional arguments
-@var{start} and @var{end} delimit the region of @var{str} to
-operate on.
-
-@code{string-reverse!} modifies the argument string and returns an
-unspecified value.
-@end deffn
-
-@deffn {Scheme Procedure} string-append/shared ls @dots{}
-Like @code{string-append}, but the result may share memory
-with the argument strings.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate ls
-Append the elements of @var{ls} (which must be strings)
-together into a single string. Guaranteed to return a freshly
-allocated string.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate/shared ls
-Like @code{string-concatenate}, but the result may share memory
-with the strings in the list @var{ls}.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate-reverse ls final_string end
-Without optional arguments, this procedure is equivalent to
-
-@smalllisp
-(string-concatenate (reverse ls))
-@end smalllisp
-
-If the optional argument @var{final_string} is specified, it is
-consed onto the beginning to @var{ls} before performing the
-list-reverse and string-concatenate operations. If @var{end}
-is given, only the characters of @var{final_string} up to index
-@var{end} are used.
-
-Guaranteed to return a freshly allocated string.
-@end deffn
-
-@deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end
-Like @code{string-concatenate-reverse}, but the result may
-share memory with the the strings in the @var{ls} arguments.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Fold/Unfold/Map
-@subsection Fold/Unfold/Map
-
-@code{string-map}, @code{string-for-each} etc. are for iterating over
-the characters a string is composed of. The fold and unfold procedures
-are list iterators and constructors.
-
-@deffn {Scheme Procedure} string-map proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} string-map! proc s [start end]
-@var{proc} is a char->char procedure, it is mapped over
-@var{s}. The order in which the procedure is applied to the
-string elements is not specified. The string @var{s} is
-modified in-place, the return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} string-fold kons knil s [start end]
-@deffnx {Scheme Procedure} string-fold-right kons knil s [start end]
-Fold @var{kons} over the characters of @var{s}, with @var{knil} as the
-terminating element, from left to right (or right to left, for
-@code{string-fold-right}). @var{kons} must expect two arguments: The
-actual character and the last result of @var{kons}' application.
-@end deffn
-
-@deffn {Scheme Procedure} string-unfold p f g seed [base make_final]
-@deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final]
-These are the fundamental string constructors.
-@itemize @bullet
-@item @var{g} is used to generate a series of @emph{seed}
-values from the initial @var{seed}: @var{seed}, (@var{g}
-@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}),
-@dots{}
-@item @var{p} tells us when to stop - when it returns true
-when applied to one of these seed values.
-@item @var{f} maps each seed value to the corresponding
-character in the result string. These chars are assembled into the
-string in a left-to-right (right-to-left) order.
-@item @var{base} is the optional initial/leftmost (rightmost)
- portion of the constructed string; it default to the empty string.
-@item @var{make_final} is applied to the terminal seed
-value (on which @var{p} returns true) to produce the final/rightmost
-(leftmost) portion of the constructed string. It defaults to
-@code{(lambda (x) "")}.
-@end itemize
-@end deffn
-
-@deffn {Scheme Procedure} string-for-each proc s [start end]
-@var{proc} is mapped over @var{s} in left-to-right order. The
-return value is not specified.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Replicate/Rotate
-@subsection Replicate/Rotate
-
-These procedures are special substring procedures, which can also be
-used for replicating strings. They are a bit tricky to use, but
-consider this code fragment, which replicates the input string
-@code{"foo"} so often that the resulting string has a length of six.
-
-@lisp
-(xsubstring "foo" 0 6)
-@result{}
-"foofoo"
-@end lisp
-
-@deffn {Scheme Procedure} xsubstring s from [to start end]
-This is the @emph{extended substring} procedure that implements
-replicated copying of a substring of some string.
-
-@var{s} is a string, @var{start} and @var{end} are optional
-arguments that demarcate a substring of @var{s}, defaulting to
-0 and the length of @var{s}. Replicate this substring up and
-down index space, in both the positive and negative directions.
-@code{xsubstring} returns the substring of this string
-beginning at index @var{from}, and ending at @var{to}, which
-defaults to @var{from} + (@var{end} - @var{start}).
-@end deffn
-
-@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end]
-Exactly the same as @code{xsubstring}, but the extracted text
-is written into the string @var{target} starting at index
-@var{tstart}. The operation is not defined if @code{(eq?
-@var{target} @var{s})} or these arguments share storage - you
-cannot copy a string on top of itself.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Miscellaneous
-@subsection Miscellaneous
-
-@code{string-replace} is for replacing a portion of a string with
-another string and @code{string-tokenize} splits a string into a list of
-strings, breaking it up at a specified character.
-
-@deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2]
-Return the string @var{s1}, but with the characters
-@var{start1} @dots{} @var{end1} replaced by the characters
-@var{start2} @dots{} @var{end2} from @var{s2}.
-@end deffn
-
-@deffn {Scheme Procedure} string-tokenize s [token-set start end]
-Split the string @var{s} into a list of substrings, where each
-substring is a maximal non-empty contiguous sequence of characters
-from the character set @var{token_set}, which defaults to an
-equivalent of @code{char-set:graphic}. If @var{start} or @var{end}
-indices are provided, they restrict @code{string-tokenize} to
-operating on the indicated substring of @var{s}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-13 Filtering/Deleting
-@subsection Filtering/Deleting
-
-@dfn{Filtering} means to remove all characters from a string which do
-not match a given criteria, @dfn{deleting} means the opposite.
-
-@deffn {Scheme Procedure} string-filter s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-satisfy the @var{char_pred} argument. If the argument is a
-procedure, it is applied to each character as a predicate, if
-it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-@deffn {Scheme Procedure} string-delete s char_pred [start end]
-Filter the string @var{s}, retaining only those characters that
-do not satisfy the @var{char_pred} argument. If the argument
-is a procedure, it is applied to each character as a predicate,
-if it is a character, it is tested for equality and if it is a
-character set, it is tested for membership.
-@end deffn
-
-
-@node SRFI-14
-@section SRFI-14 - Character-set Library
-
-SRFI-14 defines the data type @dfn{character set}, and also defines a
-lot of procedures for handling this character type, and a few standard
-character sets like whitespace, alphabetic characters and others.
-
-All procedures from SRFI-14 (character-set library) are implemented in
-the module @code{(srfi srfi-14)}, as well as the standard variables
-@code{char-set:letter}, @code{char-set:digit} etc.
-
-@menu
-* Loading SRFI-14:: How to make charsets available.
-* SRFI-14 Character Set Data Type:: Underlying data type for charsets.
-* SRFI-14 Predicates/Comparison:: Charset predicates.
-* SRFI-14 Iterating Over Character Sets:: Enumerate charset elements.
-* SRFI-14 Creating Character Sets:: Making new charsets.
-* SRFI-14 Querying Character Sets:: Test charsets for membership etc.
-* SRFI-14 Character-Set Algebra:: Calculating new charsets.
-* SRFI-14 Standard Character Sets:: Variables containing predefined charsets.
-@end menu
-
-
-@node Loading SRFI-14
-@subsection Loading SRFI-14
-
-When Guile is properly installed, SRFI-14 support can be loaded into a
-running Guile by using the @code{(srfi srfi-14)} module.
-
-@example
-$ guile
-guile> (use-modules (srfi srfi-14))
-guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar"))
-#<charset @{#\a #\b #\f #\o #\r@}>
-guile>
-@end example
-
-
-@node SRFI-14 Character Set Data Type
-@subsection Character Set Data Type
-
-The data type @dfn{charset} implements sets of characters
-(@pxref{Characters}). Because the internal representation of character
-sets is not visible to the user, a lot of procedures for handling them
-are provided.
-
-Character sets can be created, extended, tested for the membership of a
-characters and be compared to other character sets.
-
-The Guile implementation of character sets deals with 8-bit characters.
-In the standard variables, only the ASCII part of the character range is
-really used, so that for example @dfn{Umlaute} and other accented
-characters are not considered to be letters. In the future, as Guile
-may get support for international character sets, this will change, so
-don't rely on these ``features''.
-
-
-@c ===================================================================
-
-@node SRFI-14 Predicates/Comparison
-@subsection Predicates/Comparison
-
-Use these procedures for testing whether an object is a character set,
-or whether several character sets are equal or subsets of each other.
-@code{char-set-hash} can be used for calculating a hash value, maybe for
-usage in fast lookup procedures.
-
-@deffn {Scheme Procedure} char-set? obj
-Return @code{#t} if @var{obj} is a character set, @code{#f}
-otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} char-set= cs1 @dots{}
-Return @code{#t} if all given character sets are equal.
-@end deffn
-
-@deffn {Scheme Procedure} char-set<= cs1 @dots{}
-Return @code{#t} if every character set @var{cs}i is a subset
-of character set @var{cs}i+1.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-hash cs [bound]
-Compute a hash value for the character set @var{cs}. If
-@var{bound} is given and not @code{#f}, it restricts the
-returned value to the range 0 @dots{} @var{bound - 1}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Iterating Over Character Sets
-@subsection Iterating Over Character Sets
-
-Character set cursors are a means for iterating over the members of a
-character sets. After creating a character set cursor with
-@code{char-set-cursor}, a cursor can be dereferenced with
-@code{char-set-ref}, advanced to the next member with
-@code{char-set-cursor-next}. Whether a cursor has passed past the last
-element of the set can be checked with @code{end-of-char-set?}.
-
-Additionally, mapping and (un-)folding procedures for character sets are
-provided.
-
-@deffn {Scheme Procedure} char-set-cursor cs
-Return a cursor into the character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-ref cs cursor
-Return the character at the current cursor position
-@var{cursor} in the character set @var{cs}. It is an error to
-pass a cursor for which @code{end-of-char-set?} returns true.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-cursor-next cs cursor
-Advance the character set cursor @var{cursor} to the next
-character in the character set @var{cs}. It is an error if the
-cursor given satisfies @code{end-of-char-set?}.
-@end deffn
-
-@deffn {Scheme Procedure} end-of-char-set? cursor
-Return @code{#t} if @var{cursor} has reached the end of a
-character set, @code{#f} otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-fold kons knil cs
-Fold the procedure @var{kons} over the character set @var{cs},
-initializing it with @var{knil}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-unfold p f g seed [base_cs]
-@deffnx {Scheme Procedure} char-set-unfold! p f g seed base_cs
-This is a fundamental constructor for character sets.
-@itemize @bullet
-@item @var{g} is used to generate a series of ``seed'' values
-from the initial seed: @var{seed}, (@var{g} @var{seed}),
-(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
-@item @var{p} tells us when to stop -- when it returns true
-when applied to one of the seed values.
-@item @var{f} maps each seed value to a character. These
-characters are added to the base character set @var{base_cs} to
-form the result; @var{base_cs} defaults to the empty set.
-@end itemize
-
-@code{char-set-unfold!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-for-each proc cs
-Apply @var{proc} to every character in the character set
-@var{cs}. The return value is not specified.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-map proc cs
-Map the procedure @var{proc} over every character in @var{cs}.
-@var{proc} must be a character -> character procedure.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Creating Character Sets
-@subsection Creating Character Sets
-
-New character sets are produced with these procedures.
-
-@deffn {Scheme Procedure} char-set-copy cs
-Return a newly allocated character set containing all
-characters in @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set char1 @dots{}
-Return a character set containing all given characters.
-@end deffn
-
-@deffn {Scheme Procedure} list->char-set char_list [base_cs]
-@deffnx {Scheme Procedure} list->char-set! char_list base_cs
-Convert the character list @var{list} to a character set. If
-the character set @var{base_cs} is given, the character in this
-set are also included in the result.
-
-@code{list->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} string->char-set s [base_cs]
-@deffnx {Scheme Procedure} string->char-set! s base_cs
-Convert the string @var{str} to a character set. If the
-character set @var{base_cs} is given, the characters in this
-set are also included in the result.
-
-@code{string->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-filter pred cs [base_cs]
-@deffnx {Scheme Procedure} char-set-filter! pred cs base_cs
-Return a character set containing every character from @var{cs}
-so that it satisfies @var{pred}. If provided, the characters
-from @var{base_cs} are added to the result.
-
-@code{char-set-filter!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} ucs-range->char-set lower upper [error? base_cs]
-@deffnx {Scheme Procedure} uce-range->char-set! lower upper error? base_cs
-Return a character set containing all characters whose
-character codes lie in the half-open range
-[@var{lower},@var{upper}).
-
-If @var{error} is a true value, an error is signalled if the
-specified range contains characters which are not contained in
-the implemented character range. If @var{error} is @code{#f},
-these characters are silently left out of the resulting
-character set.
-
-The characters in @var{base_cs} are added to the result, if
-given.
-
-@code{ucs-range->char-set!} is the side-effecting variant.
-@end deffn
-
-@deffn {Scheme Procedure} ->char-set x
-Coerce @var{x} into a character set. @var{x} may be a string, a
-character or a character set.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Querying Character Sets
-@subsection Querying Character Sets
-
-Access the elements and other information of a character set with these
-procedures.
-
-@deffn {Scheme Procedure} char-set-size cs
-Return the number of elements in character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-count pred cs
-Return the number of the elements int the character set
-@var{cs} which satisfy the predicate @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set->list cs
-Return a list containing the elements of the character set
-@var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set->string cs
-Return a string containing the elements of the character set
-@var{cs}. The order in which the characters are placed in the
-string is not defined.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-contains? cs char
-Return @code{#t} iff the character @var{ch} is contained in the
-character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-every pred cs
-Return a true value if every character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-any pred cs
-Return a true value if any character in the character set
-@var{cs} satisfies the predicate @var{pred}.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Character-Set Algebra
-@subsection Character-Set Algebra
-
-Character sets can be manipulated with the common set algebra operation,
-such as union, complement, intersection etc. All of these procedures
-provide side-effecting variants, which modify their character set
-argument(s).
-
-@deffn {Scheme Procedure} char-set-adjoin cs char1 @dots{}
-@deffnx {Scheme Procedure} char-set-adjoin! cs char1 @dots{}
-Add all character arguments to the first argument, which must
-be a character set.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-delete cs char1 @dots{}
-@deffnx {Scheme Procedure} char-set-delete! cs char1 @dots{}
-Delete all character arguments from the first argument, which
-must be a character set.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-complement cs
-@deffnx {Scheme Procedure} char-set-complement! cs
-Return the complement of the character set @var{cs}.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-union cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-union! cs1 @dots{}
-Return the union of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-intersection cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-intersection! cs1 @dots{}
-Return the intersection of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-difference cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-difference! cs1 @dots{}
-Return the difference of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-xor cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-xor! cs1 @dots{}
-Return the exclusive-or of all argument character sets.
-@end deffn
-
-@deffn {Scheme Procedure} char-set-diff+intersection cs1 @dots{}
-@deffnx {Scheme Procedure} char-set-diff+intersection! cs1 @dots{}
-Return the difference and the intersection of all argument
-character sets.
-@end deffn
-
-
-@c ===================================================================
-
-@node SRFI-14 Standard Character Sets
-@subsection Standard Character Sets
-
-In order to make the use of the character set data type and procedures
-useful, several predefined character set variables exist.
-
-@defvar char-set:lower-case
-All lower-case characters.
-@end defvar
-
-@defvar char-set:upper-case
-All upper-case characters.
-@end defvar
-
-@defvar char-set:title-case
-This is empty, because ASCII has no titlecase characters.
-@end defvar
-
-@defvar char-set:letter
-All letters, e.g. the union of @code{char-set:lower-case} and
-@code{char-set:upper-case}.
-@end defvar
-
-@defvar char-set:digit
-All digits.
-@end defvar
-
-@defvar char-set:letter+digit
-The union of @code{char-set:letter} and @code{char-set:digit}.
-@end defvar
-
-@defvar char-set:graphic
-All characters which would put ink on the paper.
-@end defvar
-
-@defvar char-set:printing
-The union of @code{char-set:graphic} and @code{char-set:whitespace}.
-@end defvar
-
-@defvar char-set:whitespace
-All whitespace characters.
-@end defvar
-
-@defvar char-set:blank
-All horizontal whitespace characters, that is @code{#\space} and
-@code{#\tab}.
-@end defvar
-
-@defvar char-set:iso-control
-The ISO control characters with the codes 0--31 and 127.
-@end defvar
-
-@defvar char-set:punctuation
-The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}}
-@end defvar
-
-@defvar char-set:symbol
-The characters @code{$+<=>^`|~}.
-@end defvar
-
-@defvar char-set:hex-digit
-The hexadecimal digits @code{0123456789abcdefABCDEF}.
-@end defvar
-
-@defvar char-set:ascii
-All ASCII characters.
-@end defvar
-
-@defvar char-set:empty
-The empty character set.
-@end defvar
-
-@defvar char-set:full
-This character set contains all possible characters.
-@end defvar
-
-@node SRFI-16
-@section SRFI-16 - case-lambda
-
-@c FIXME::martin: Review me!
-
-The syntactic form @code{case-lambda} creates procedures, just like
-@code{lambda}, but has syntactic extensions for writing procedures of
-varying arity easier.
-
-The syntax of the @code{case-lambda} form is defined in the following
-EBNF grammar.
-
-@example
-@group
-<case-lambda>
- --> (case-lambda <case-lambda-clause>)
-<case-lambda-clause>
- --> (<formals> <definition-or-command>*)
-<formals>
- --> (<identifier>*)
- | (<identifier>* . <identifier>)
- | <identifier>
-@end group
-@end example
-
-The value returned by a @code{case-lambda} form is a procedure which
-matches the number of actual arguments against the formals in the
-various clauses, in order. @dfn{Formals} means a formal argument list
-just like with @code{lambda} (@pxref{Lambda}). The first matching clause
-is selected, the corresponding values from the actual parameter list are
-bound to the variable names in the clauses and the body of the clause is
-evaluated. If no clause matches, an error is signalled.
-
-The following (silly) definition creates a procedure @var{foo} which
-acts differently, depending on the number of actual arguments. If one
-argument is given, the constant @code{#t} is returned, two arguments are
-added and if more arguments are passed, their product is calculated.
-
-@lisp
-(define foo (case-lambda
- ((x) #t)
- ((x y) (+ x y))
- (z
- (apply * z))))
-(foo 'bar)
-@result{}
-#t
-(foo 2 4)
-@result{}
-6
-(foo 3 3 3)
-@result{}
-27
-(foo)
-@result{}
-1
-@end lisp
-
-The last expression evaluates to 1 because the last clause is matched,
-@var{z} is bound to the empty list and the following multiplication,
-applied to zero arguments, yields 1.
-
-
-@node SRFI-17
-@section SRFI-17 - Generalized set!
-
-This is an implementation of SRFI-17: Generalized set!
-
-It exports the Guile procedure @code{make-procedure-with-setter} under
-the SRFI name @code{getter-with-setter} and exports the standard
-procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
-@code{string-ref} and @code{vector-ref} as procedures with setters, as
-required by the SRFI.
-
-SRFI-17 was heavily criticized during its discussion period but it was
-finalized anyway. One issue was its concept of globally associating
-setter @dfn{properties} with (procedure) values, which is non-Schemy.
-For this reason, this implementation chooses not to provide a way to set
-the setter of a procedure. In fact, @code{(set! (setter @var{proc})
-@var{setter})} signals an error. The only way to attach a setter to a
-procedure is to create a new object (a @dfn{procedure with setter}) via
-the @code{getter-with-setter} procedure. This procedure is also
-specified in the SRFI. Using it avoids the described problems.
-
-
-@node SRFI-19
-@section SRFI-19 - Time/Date Library
-
-This is an implementation of SRFI-19: Time/Date Library
-
-It depends on SRFIs: 6 (@pxref{SRFI-6}), 8 (@pxref{SRFI-8}),
-9 (@pxref{SRFI-9}).
-
-This section documents constants and procedure signatures.
-
-@menu
-* SRFI-19 Constants::
-* SRFI-19 Current time and clock resolution::
-* SRFI-19 Time object and accessors::
-* SRFI-19 Time comparison procedures::
-* SRFI-19 Time arithmetic procedures::
-* SRFI-19 Date object and accessors::
-* SRFI-19 Time/Date/Julian Day/Modified Julian Day converters::
-* SRFI-19 Date to string/string to date converters::
-@end menu
-
-@node SRFI-19 Constants
-@subsection SRFI-19 Constants
-
-All these are bound to their symbol names:
-
-@example
- time-duration
- time-monotonic
- time-process
- time-tai
- time-thread
- time-utc
-@end example
-
-@node SRFI-19 Current time and clock resolution
-@subsection SRFI-19 Current time and clock resolution
-
-@example
- (current-date . tz-offset)
- (current-julian-day)
- (current-modified-julian-day)
- (current-time . clock-type)
- (time-resolution . clock-type)
-@end example
-
-@node SRFI-19 Time object and accessors
-@subsection SRFI-19 Time object and accessors
-
-@example
- (make-time type nanosecond second)
- (time? obj)
- (time-type time)
- (time-nanosecond time)
- (time-second time)
- (set-time-type! time type)
- (set-time-nanosecond! time nsec)
- (set-time-second! time sec)
- (copy-time time)
-@end example
-
-@node SRFI-19 Time comparison procedures
-@subsection SRFI-19 Time comparison procedures
-
-Args are all @code{time} values.
-
-@example
- (time<=? t1 t2)
- (time<? t1 t2)
- (time=? t1 t2)
- (time>=? t1 t2)
- (time>? t1 t2)
-@end example
-
-@node SRFI-19 Time arithmetic procedures
-@subsection SRFI-19 Time arithmetic procedures
-
-The @code{foo!} variants modify in place. Time difference
-is expressed in @code{time-duration} values.
-
-@example
- (time-difference t1 t2)
- (time-difference! t1 t2)
- (add-duration time duration)
- (add-duration! time duration)
- (subtract-duration time duration)
- (subtract-duration! time duration)
- @end example
-
-@node SRFI-19 Date object and accessors
-@subsection SRFI-19 Date object and accessors
-
-@example
- (make-date nsecs seconds minutes hours
- date month year offset)
- (date? obj)
- (date-nanosecond date)
- (date-second date)
- (date-minute date)
- (date-hour date)
- (date-day date)
- (date-month date)
- (date-year date)
- (date-zone-offset date)
- (date-year-day date)
- (date-week-day date)
- (date-week-number date day-of-week-starting-week)
-@end example
-
-@node SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-@subsection SRFI-19 Time/Date/Julian Day/Modified Julian Day converters
-
-@example
- (date->julian-day date)
- (date->modified-julian-day date)
- (date->time-monotonic date)
- (date->time-tai date)
- (date->time-utc date)
- (julian-day->date jdn . tz-offset)
- (julian-day->time-monotonic jdn)
- (julian-day->time-tai jdn)
- (julian-day->time-utc jdn)
- (modified-julian-day->date jdn . tz-offset)
- (modified-julian-day->time-monotonic jdn)
- (modified-julian-day->time-tai jdn)
- (modified-julian-day->time-utc jdn)
- (time-monotonic->date time . tz-offset)
- (time-monotonic->time-tai time-in)
- (time-monotonic->time-tai! time-in)
- (time-monotonic->time-utc time-in)
- (time-monotonic->time-utc! time-in)
- (time-tai->date time . tz-offset)
- (time-tai->julian-day time)
- (time-tai->modified-julian-day time)
- (time-tai->time-monotonic time-in)
- (time-tai->time-monotonic! time-in)
- (time-tai->time-utc time-in)
- (time-tai->time-utc! time-in)
- (time-utc->date time . tz-offset)
- (time-utc->julian-day time)
- (time-utc->modified-julian-day time)
- (time-utc->time-monotonic time-in)
- (time-utc->time-monotonic! time-in)
- (time-utc->time-tai time-in)
- (time-utc->time-tai! time-in)
-@end example
-
-@node SRFI-19 Date to string/string to date converters
-@subsection SRFI-19 Date to string/string to date converters
-
-@example
- (date->string date . format-string)
- (string->date input-string template-string)
-@end example
-
-@c srfi-modules.texi ends here
diff --git a/doc/ref/tcltk.texi b/doc/ref/tcltk.texi
deleted file mode 100644
index efc38ea9d..000000000
--- a/doc/ref/tcltk.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@page
-@node Tcl/Tk Interface
-@chapter Tcl/Tk Interface
diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi
deleted file mode 100644
index 061e34477..000000000
--- a/doc/ref/tools.texi
+++ /dev/null
@@ -1,386 +0,0 @@
-@page
-@node Miscellaneous Tools
-@chapter Miscellaneous Tools
-
-Programming is more fun with a good tools. This chapter describes snarfing
-tools, and the @code{guile-tools} program which can be used to invoke the rest
-of the tools (which are self-documenting). Some of these are used in Guile
-development, too. Imagine that!
-
-@menu
-* Snarfing:: Grepping the source in various ways.
-* Executable Modules:: Modules callable via guile-tools.
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node Snarfing
-@section Snarfing
-@cindex snarfing
-
-Because it's easier to maintain documentation, code, and other metainfo in one
-source file than in many files, there have evolved many methods for grepping
-source to lift and separate these kinds of info, in the process generating
-docs or fragments of source or what have you. This is known generally as
-@dfn{snarfing}, which comes from the verb ``to snarf'', here meaning ``to
-unceremoniously extract information from a somewhat unwilling source.''
-
-This section documents the installed program @code{guile-snarf} which does
-@dfn{init snarfing}, and also touches upon guile's doc snarfing process which
-is not yet finalized (i.e., doc snarfing programs are not installed at this
-time).
-
-@menu
-* Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme.
-* Doc Snarfing:: Generating GDFv2 or texi from source.
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node Init Snarfing with guile-snarf
-@subsection Init Snarfing with guile-snarf
-@c NOTE: This node and two subnodes are adapted from ../sources/snarf.texi.
-@cindex snarfing, init
-@cindex primitive functions
-@cindex subrs, defining
-
-When writing C code for use with Guile, you typically define a set of C
-functions, and then make some of them visible to the Scheme world by
-calling the @code{scm_c_define_gsubr} function; a C function published in
-this way is called a @dfn{subr}. If you have many subrs to publish, it
-can sometimes be annoying to keep the list of calls to
-@code{scm_c_define_gsubr} in sync with the list of function definitions.
-Frequently, a programmer will define a new subr in C, recompile the
-application, and then discover that the Scheme interpreter cannot see
-the subr, because of a missed call to @code{scm_c_define_gsubr}.
-
-Guile provides the @code{guile-snarf} command to manage this problem.
-Using this tool, you can keep all the information needed to define the
-subr alongside the function definition itself; @code{guile-snarf} will
-extract this information from your source code, and automatically
-generate a file of calls to @code{scm_c_define_gsubr} which you can
-@code{#include} into an initialization function.
-
-@menu
-* How guile-snarf works:: Using @code{guile-snarf}, with example.
-* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node How guile-snarf works
-@subsubsection How guile-snarf works
-@cindex guile-snarf invocation
-@cindex guile-snarf example
-
-Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
-
-What @code{guile-snarf} does:
-
-Process INFILE using the C pre-processor and some other programs.
-Write output to a file named OUTFILE or to the standard output when no
-OUTFILE has been specified or when OUTFILE is @code{-}. When writing
-to a file, ignore lines from the input matching the following grep(1)
-regular expression:
-
-@example
- ^#include ".*OUTFILE"
-@end example
-
-If there are errors during processing, delete OUTFILE and exit with
-non-zero status.
-
-Optional arg "-d" means grep INFILE for deprecated macros and
-issue a warning if any are found. Alternatively, "-D" means
-do the same thing but signal error and exit with non-zero status.
-
-If env var CPP is set, use its value instead of the C pre-processor
-determined at Guile configure-time.
-
-During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
-defined.
-
-@xref{Macros guile-snarf recognizes}, for a list of the special (some would
-say magic) cpp macros you can use, including the list of deprecated macros.
-
-For example, here is how you might define a new subr called
-@code{clear-image}, implemented by the C function @code{clear_image}:
-
-@example
-@group
-#include <libguile.h>
-
-SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
- (SCM image_smob),
- "Clear the image.")
-#define FUNC_NAME s_clear_image
-@{
- /* C code to clear the image... */
-@}
-#undef FUNC_NAME
-
-void
-init_image_type ()
-@{
-#include "image-type.x"
-@}
-@end group
-@end example
-
-The @code{SCM_DEFINE} declaration says that the C function
-@code{clear_image} implements a Scheme subr called @code{clear-image},
-which takes one required argument (type @code{SCM} named
-@code{image_smob}), no optional arguments, and no tail argument.
-@xref{Doc Snarfing}, for info on the docstring.
-
-This works in concert with @code{FUNC_NAME} to also define a static
-array of characters named @code{s_clear_image}, initialized to the
-string "clear-image". The body of @code{clear_image} may use the array
-in error messages, instead of writing out the literal string; this may
-save string space on some systems.
-
-Assuming the text above lives in a file named @file{image-type.c}, you will
-need to execute the following command to prepare this file for compilation:
-
-@example
-guile-snarf image-type.c
-@end example
-
-This scans @file{image-type.c} for @code{SCM_DEFINE}
-declarations, and writes to @file{image-type.x} the output:
-
-@example
-scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
-@end example
-
-When compiled normally, @code{SCM_DEFINE} is a macro which expands to a
-declaration of the @code{s_clear_image} string.
-
-Note that the output file name matches the @code{#include} from the
-input file. Also, you still need to provide all the same information
-you would if you were using @code{scm_c_define_gsubr} yourself, but you
-can place the information near the function definition itself, so it is
-less likely to become incorrect or out-of-date.
-
-If you have many files that @code{guile-snarf} must process, you should
-consider using a fragment like the following in your Makefile:
-
-@example
-snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
-.SUFFIXES: .x
-.c.x:
- guile-snarf -o $@ $< $(snarfcppopts)
-@end example
-
-This tells make to run @code{guile-snarf} to produce each needed
-@file{.x} file from the corresponding @file{.c} file.
-
-Aside from the required argument INFILE, @code{guile-snarf} passes its
-command-line arguments directly to the C preprocessor, which it uses to
-extract the information it needs from the source code. this means you can pass
-normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
-add header file directories, and so on.
-
-@c ---------------------------------------------------------------------------
-@node Macros guile-snarf recognizes
-@subsubsection Macros guile-snarf recognizes
-@cindex guile-snarf recognized macros
-@cindex guile-snarf deprecated macros
-
-Here are the macros you can use in your source code from which
-@code{guile-snarf} can construct initialization code:
-
-@example
-/* procedures */
-SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)
-
-SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
-SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
-
-SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)
-
-/* everything else */
-SCM_SYMBOL (c_name, scheme_name)
-SCM_GLOBAL_SYMBOL (c_name, scheme_name)
-
-SCM_KEYWORD (c_name, scheme_name)
-SCM_GLOBAL_KEYWORD (c_name, scheme_name)
-
-SCM_VARIABLE (c_name, scheme_name)
-SCM_GLOBAL_VARIABLE (c_name, scheme_name)
-
-SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
-SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
-@end example
-
-@c i like things dense, but maybe someone else will reformat this
-@c into an easier-to-read list. also, all-upcase to me is a form
-@c of quoting, so @var{} is not necessary there. --ttn
-REQ and OPT are numbers indicating required and optional argument
-counts, respectively; VAR is a number that, if non-zero, means the
-function will accept any remaining arguments as a list; DOCSTRING is a
-string (use @code{\n\} at eol for multi-line); FNAME is a C-language
-identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
-denoting the name available to Scheme code, STR and @var{scheme_name}
-likewise; RANAME is the name of the static string (must match that
-declared by the associated definition of cpp macro @var{FUNC_NAME});
-ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
-is a expression suitable for initializing a new variable.
-
-For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
-@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
-to be bothered with docstrings. Use @code{SCM_GPROC} for generic
-functions (@pxref{GOOPS,,,goops}). All procedures are declared
-@code{static} with return type @code{SCM}.
-
-For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
-symbols, and so on). The "_GLOBAL_" variants omit @code{static}
-declaration.
-
-All these macros should be used at top-level, outside function bodies.
-Also, it's a good idea to define @var{FUNC_NAME} immediately after using
-@code{SCM_DEFINE} (and similar), and then the function body, and then
-@code{#undef FUNC_NAME}.
-
-Here is the list of deprecated macros:
-
-@c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
-@example
- SCM_CONST_LONG
- SCM_VCELL
- SCM_VCELL_INIT
- SCM_GLOBAL_VCELL
- SCM_GLOBAL_VCELL_INIT
-@end example
-
-Some versions of guile (and guile-snarf) will continue to recognize them but
-at some point they will no longer work. You can pass either @code{-d} or
-@code{-D} option to have guile-snarf warn or signal error, respectively, if
-any of these are found in the input file.
-
-@xref{How guile-snarf works}, and also libguile source, for examples.
-@xref{Subrs}, for details on argument passing and how to write C
-functions.
-
-@c ---------------------------------------------------------------------------
-@node Doc Snarfing
-@subsection Doc Snarfing
-
-In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
-the libguile sources are also subject to doc snarfing, by programs that
-are included in the distribution (but not installed at this time). The
-output is the file @file{guile-procedures.txt} which is installed, and
-subsequently used by module @code{(ice-9 documentation)}.
-
-Here is a list of what does what according to @file{libguile/Makefile.am}:
-
-@itemize
-@item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
-@item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
-@item ../scripts/snarf-check-and-output-texi makes guile.texi
-@item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
-@item guile-func-name-check checks source snarf-syntax integrity (optional?)
-@item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf
-@end itemize
-
-Note that for guile-1.4, a completely different approach was used! All this
-is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
-
-[fixme: Document further once doc snarfing is tamed somewhat. --ttn]
-
-@c ---------------------------------------------------------------------------
-@node Executable Modules
-@section Executable Modules
-@cindex guile-tools
-@cindex modules, executable
-@cindex executable modules
-@cindex scripts
-
-When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
-a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
-Each is a regular Scheme module that has some additional packaging so
-that it can be called as a program in its own right, from the shell. For this
-reason, we sometimes use the term @dfn{script} in this context to mean the
-same thing.
-
-@c wow look at this hole^! variable-width font users eat your heart out.
-
-As a convenience, the @code{guile-tools} wrapper program is installed along w/
-@code{guile}; it knows where a particular module is installed and calls it
-passing its args to the program. The result is that you need not augment your
-PATH. Usage is straightforward:
-
-@example
-guile-tools --help
-guile-tools --version
-guile-tools [OPTION] PROGRAM [ARGS ...]
-
-If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
-PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
- --scriptsdir DIR -- Look in DIR for scripts
- --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
- --source -- Display PROGRAM source (ignore ARGS) to stdout
-@end example
-
-The modules are self-documenting. For example, to see the documentation for
-@code{lint}, use one (or both) of the shell commands:
-
-@example
-guile-tools display-commentary '(scripts lint)'
-guile-tools --source lint
-@end example
-
-The rest of this section describes the packaging that goes into creating an
-executable module. Feel free to skip to the next chapter.
-
-@subsection Writing Executable Modules
-
-@c adapted from scripts/README
-
-See template file @code{PROGRAM} for a quick start.
-
-Programs must follow the @dfn{executable module} convention, documented here:
-
-@itemize
-
-@item
-The file name must not end in ".scm".
-
-@item
-The file must be executable (chmod +x).
-
-@item
-The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
-signature "(PROGRAM . args)" must be exported. Basically, use some variant
-of the form:
-
-@example
-(define-module (scripts PROGRAM)
- :export (PROGRAM))
-@end example
-
-Feel free to export other definitions useful in the module context.
-
-@item
-There must be the alias:
-
-@example
-(define main PROGRAM)
-@end example
-
-However, `main' must NOT be exported.
-
-@item
-The beginning of the file must use the following invocation sequence:
-
-@example
-#!/bin/sh
-main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
-exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
-!#
-@end example
-
-@end itemize
-
-Following these conventions allows the program file to be used as module
-@code{(scripts PROGRAM)} in addition to as a standalone executable. Please
-also include a helpful Commentary section w/ some usage info.
-
-@c tools.texi ends here