@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.6 2001-11-11 15:01:51 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).
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: Programming with Guile
-* Programming Intro:: Intoduction to programming with Guile.
-* Programming Options:: Programming Options in 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.
* Guile Scripting:: How to write Guile scripts.
* Command Line Handling:: Command line options and arguments.
* Libguile Intro:: Using Guile as an extension language.
-* Scheme Primitives:: Writing Scheme primitives in C.
+* 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.
-* Data Types:: Data types for generic use.
+* 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.
* 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.
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: Programming with Guile}).
+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 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
HCoop / bpt / guile.git / blobdiff