mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 11:50:28 +02:00
131 lines
4.4 KiB
Text
131 lines
4.4 KiB
Text
@menu
|
|
Preliminary
|
|
|
|
* Introduction::
|
|
* Using Guile::
|
|
|
|
|
|
|
|
@bye
|
|
|
|
>You can actually put any English text to break up the menu, so you
|
|
>could put the "Part n" headings in it.
|
|
|
|
|
|
|
|
Introduction
|
|
--- Explains Guile's goals, and gives brief examples of how to use
|
|
Guile interactively (show off repl), as a script interpreter,
|
|
and as an embedded interpreter.
|
|
|
|
Part I: Guile Scheme
|
|
R4RS Scheme as a Starting Point
|
|
--- Here we refer to R4RS, and explain that we're only
|
|
describing differences.
|
|
Block comments and interpreter triggers
|
|
Symbol case
|
|
Keywords
|
|
Exceptions
|
|
Modules
|
|
--- the preceeding three come first, because we need them
|
|
in order to explain the behavior of some things later
|
|
Exception Handling
|
|
--- mention that repls usually establish default exception handlers
|
|
Dynamic Wind
|
|
Records
|
|
Structures
|
|
Arrays
|
|
Binary Numeric Operations
|
|
Shared and Read-Only Strings
|
|
Object Properties
|
|
Association Lists and Hash Tables
|
|
(Dictionaries In General)
|
|
association lists
|
|
hash tables (Hash Values)
|
|
Input/Output ports
|
|
file ports
|
|
soft ports
|
|
string ports
|
|
extended I/O (fseek; line read/write)
|
|
Garbage Collection
|
|
Threads and Dynamic Roots
|
|
Reflection
|
|
eval
|
|
Tag Values
|
|
Weak references
|
|
Regular Expressions
|
|
SLIB
|
|
POSIX system calls and networking
|
|
--- I think people will generally know whether they're looking
|
|
for a system call or not, so this should be an okay category.
|
|
conventions (includes error handling)
|
|
ports vs. file descriptors
|
|
file system (mknod goes here, no?)
|
|
user database
|
|
time (includes gettimeofday or whatever, strftime, strptime)
|
|
processes
|
|
terminals and pseudo-terminals
|
|
pipes
|
|
networking (includes databases, address conversion, and sockets)
|
|
system identification (uname)
|
|
locales (setlocale)
|
|
--- Note that there is no more 'misc'. It's better to have
|
|
small sections than unhelpful names.
|
|
SCSH
|
|
--- includes info on how to get SCSH features (open this
|
|
module), but mostly just a pointer to the SCSH manual.
|
|
This should not be under POSIX. SCSH includes plenty of
|
|
high-level stuff for starting processes and string
|
|
processing. SCSH is not a subset of POSIX, nor the
|
|
reverse.
|
|
Tcl/Tk interface
|
|
Module internals
|
|
first-class variables
|
|
first-class modules
|
|
internal debugging interface
|
|
--- The name of this chapter needs to clearly distinguish it
|
|
from the appendix describing the debugger UI. The intro
|
|
should have a pointer to the UI appendix.
|
|
|
|
Part II: Using Scheme with C --- a Portable Interface
|
|
--- We cover gh in a completely separate section. Why? I admit
|
|
I'm on shaky ground, but here's my reasoning: People who want
|
|
to write portable C code need to restrict themselves to only
|
|
using GH, and GH's semantics are (necessarily) well-defined
|
|
without reference to Guile's particulars. This makes life
|
|
more difficult for folks who just prefer to use the GH
|
|
interface when they can, but I really think the SCM interface
|
|
is not so bad, once you're used to it. A *lot* of GH
|
|
functions are just wrappers for SCM functions.
|
|
--- We cover repls here too, since GH has repl functions.
|
|
|
|
Part III: Using Scheme with C --- Guile's Interface
|
|
Scheme data representation
|
|
Relationship between Scheme and C functions
|
|
--- this is where we explain that all the functions marked as
|
|
"Primitive Functions" are also accessible from C, and how
|
|
to derive the C interface given the Scheme interface, when
|
|
we don't spell it out.
|
|
... I think there's other stuff needed here ...
|
|
I/O internals
|
|
linking Guile with your code
|
|
--- Mark's "Tools to automate adding libraries" is not a
|
|
well-defined concept. I think this is closer to what we
|
|
want to cover for now.
|
|
snarfing
|
|
|
|
Appendices:
|
|
Obtaining and Installing Guile
|
|
Invoking Guile
|
|
--- mentions read-eval-print loops
|
|
--- both the SCSH and GAWK manuals relegate invocation details
|
|
to an appendix. We can give examples in the introduction.
|
|
debugger user interface
|
|
--- The title and introduction of this appendix need to
|
|
distinguish this clearly from the chapter on the internal
|
|
debugging interface.
|
|
|
|
Indices:
|
|
--- At the top of the function/variable index, remind people
|
|
to look for functions under their Scheme names as well as
|
|
their C names.
|