@setfilename guile.info
@settitle Guile Reference Manual
@set guile
+@set MANUAL_EDITION 1.1
@c %**end of header
-@c Notes: (distilled from Jim's and Tim's notes, and kept up to date)
+@c Notes
@c
-@c Remember to use "primitive" whereever appropriate.
-@c FIXME: gotta change existing "subr" uses to "Primitive".
-@c [JimB:] In my text for the Guile snarfer, I've used the term "subr"
-@c to denote a C function made available to the Scheme world as a
-@c function. This terminology is weird, but consistent with the
-@c function names and also with Emacs Lisp, which I assume takes
-@c Maclisp's lead.
+@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 function to the Guile manual, please document
-@c it with @deffn as one of `primitive', `procedure', or `syntax'.
+@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 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 a great reason why some of these should
-@c *not* go in the manual, please let me know.
+@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
@include version.texi
+@c Macros for describing version information. I've initially defined
+@c all of these to expand to nothing, but they could perhaps be made to
+@c expand to something like "New in Guile 45!" in future.
+
+@c vnew - indicates the Guile version in which item first appeared.
+@macro vnew{VERSION}
+@end macro
+
+@c vdeprecated - indicates that the item has been deprecated, and the
+@c Guile version in which the deprecation started.
+@macro vdeprecated{VERSION}
+@end macro
+
+@c vgone - a way of tracking items that are no longer here. In this
+@c case, VERSION is the last Guile version in which the item was present.
+@macro vgone{WHAT, VERSION}
+@end macro
+
+@c vchanged - indicates the Guile version in which item's behaviour
+@c significantly changed.
+@macro vchanged{VERSION}
+@end macro
+
+@c vnote - catchall for any additional notes.
+@macro vnote{NOTE}
+@end macro
+
@c @iftex
@c @cropmarks
@c @end iftex
@dircategory The Algorithmic Language Scheme
@direntry
-* Guile Reference: (guile). The Guile reference manual.
+* Guile Reference: (guile). The Guile reference manual.
@end direntry
@setchapternewpage off
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.4 2001-08-30 20:19:20 ossau Exp $
+@subtitle $Id: guile.texi,v 1.14 2002-03-15 14:03:53 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@c AUTHORS
@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 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).
Language for Extensions. It describes how to use Guile in many useful
and interesting ways.
-This Info file contains edition 1.0 of the reference manual,
-corresponding to Guile version @value{VERSION}.
+This Info file contains edition @value{MANUAL_EDITION} of the reference
+manual, corresponding to Guile version @value{VERSION}.
@end ifinfo
@menu
Part I: Introduction to Guile
* What is Guile?:: And what does it do?
-* Whirlwind Tour:: An introductory whirlwind tour.
+* Whirlwind Tour:: An introductory whirlwind tour.
+* Obtaining and Installing Guile::
* Reporting Bugs:: Reporting bugs in Guile or this manual.
-Part II: Guile Scheme
+Part II: Programming with Guile
+* Programming Intro:: Introduction to this part.
+* Programming Overview:: An overview of Guile programming.
* Scheme Intro:: Introduction to Guile Scheme.
* Basic Ideas:: Basic ideas in Scheme.
-* Data Types:: Data types for generic use.
+* Guile Scripting:: How to write Guile scripts.
+* Command Line Handling:: Command line options and arguments.
+* Libguile Intro:: Using Guile as an extension language.
+* Guile API:: Overview of the Guile API.
+* Data Representation:: Data representation in Guile.
+* GH:: The deprecated GH interface.
+* Debugger User Interface::
+* Autoconf Support:: Guile-specific configure.in macros.
+* Miscellaneous Tools:: Snarfing, linting, etc.
+* Further Reading:: Where to find out more about Scheme programming.
+
+Part III: Guile API Reference
+
+* Reference Intro:: Introduction to the Guile API reference.
+* 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.
* Translation:: Support for translating other languages.
* Debugging:: Internal debugging interface.
* Deprecated:: Features that are planned to disappear.
-* Further Reading:: Where to find out more about Scheme programming.
-Part III: Guile Modules
+Part IV: Guile Modules
* SLIB:: Using the SLIB Scheme library.
* POSIX:: POSIX system calls and networking.
* 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)::
- The SCSH compatibility module has been made an
- add-on, so maybe it shouldn't be documented here
- (though it is nice to have a link from here to the
- Guile-scsh manual, if one exists).
-@c * Tcl/Tk Interface::
-
-Part IV: Guile Scripting
-
-* Guile Scripting:: How to write Guile scripts.
-* Command Line Handling:: Command line options and arguments.
-
-Part V: Extending Applications Using Guile
-
-* Libguile Intro:: Using Guile as an extension language.
-* Data Representation:: Data representation in Guile.
-* Scheme Primitives:: Writing Scheme primitives in C.
-* I/O Extensions:: Using and extending ports in C.
-* Handling Errors:: How to handle errors in C code.
-* GH:: The deprecated GH interface.
-
-Appendices
-
-* Obtaining and Installing Guile::
-* Debugger User Interface::
+* The Scheme shell (scsh):: Using scsh interfaces in Guile.
Indices
@include preface.texi
-@c preliminary
@iftex
@page
@unnumbered{Part I: Introduction to Guile}
@include intro.texi
-@c programming in Scheme
-@iftex
@page
-@unnumbered{Part II: Guile Scheme}
-@end iftex
+@node Programming Intro
+@unnumbered Part II: Programming with Guile
+
+In this part of the manual, we aim to present a wide ranging picture of
+what it means to program using Guile, 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 III (@pxref{Reference Intro,,Part III --- Guile API Reference}).
+
+We begin in the first chapter of this part by looking at the programming
+options available.
+@include program.texi
@include scheme-intro.texi
@include scheme-ideas.texi
+@include scripts.texi
+@include script-getopt.texi
+@include extend.texi
+@include scm.texi
+@include data-rep.texi
+@include gh.texi
+@include debugging.texi
+@include autoconf.texi
+@include tools.texi
+@include scheme-reading.texi
+
+@page
+@node Reference Intro
+@unnumbered Part III: 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 scheme-data.texi
+@include scheme-compound.texi
@include scheme-procedures.texi
@include scheme-utility.texi
@include scheme-binding.texi
@include scheme-translation.texi
@include scheme-debug.texi
@include deprecated.texi
-@include scheme-reading.texi
-@include scheme-indices.texi
-@c Unix system interface
@iftex
@page
-@unnumbered{Part III: Guile Modules}
+@unnumbered{Part IV: Guile Modules}
@end iftex
@include slib.texi
@include misc-modules.texi
@include expect.texi
@include scsh.texi
-@c @include tcltk.texi
-@c Guile as an scripting language
-@iftex
-@page
-@unnumbered{Part IV: Guile Scripting}
-@end iftex
-
-@include scripts.texi
-@include script-getopt.texi
-
-@c Guile as an extension language
-@iftex
-@page
-@unnumbered{Part V: Extending Applications Using Guile}
-@end iftex
-
-@include extend.texi
-@include data-rep.texi
-@include scm.texi
-@include gh.texi
-
-@c Appendices
-@iftex
-@page
-@unnumbered{Appendices}
-@end iftex
-
-@include appendices.texi
-
-@c Indices
@iftex
@page
@unnumbered{Indices}
@end iftex
@include indices.texi
+@include scheme-indices.texi
@contents
HCoop / bpt / guile.git / blobdiff