[bpt/guile.git] / doc / sources / jimb-org.texi

@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.
Commit	Line	Data
009e2b30 NJ	1	@menu
	2	Preliminary
	3
	4	* Introduction::
	5	* Using Guile::
	6
	7
	8
	9	@bye
	10
	11	>You can actually put any English text to break up the menu, so you
	12	>could put the "Part n" headings in it.
	13
	14
	15
	16	Introduction
	17	--- Explains Guile's goals, and gives brief examples of how to use
	18	Guile interactively (show off repl), as a script interpreter,
	19	and as an embedded interpreter.
	20
	21	Part I: Guile Scheme
	22	R4RS Scheme as a Starting Point
	23	--- Here we refer to R4RS, and explain that we're only
	24	describing differences.
	25	Block comments and interpreter triggers
	26	Symbol case
	27	Keywords
	28	Exceptions
	29	Modules
	30	--- the preceeding three come first, because we need them
	31	in order to explain the behavior of some things later
	32	Exception Handling
	33	--- mention that repls usually establish default exception handlers
	34	Dynamic Wind
	35	Records
	36	Structures
	37	Arrays
	38	Binary Numeric Operations
	39	Shared and Read-Only Strings
	40	Object Properties
	41	Association Lists and Hash Tables
	42	(Dictionaries In General)
	43	association lists
	44	hash tables (Hash Values)
	45	Input/Output ports
	46	file ports
	47	soft ports
	48	string ports
	49	extended I/O (fseek; line read/write)
	50	Garbage Collection
	51	Threads and Dynamic Roots
	52	Reflection
	53	eval
	54	Tag Values
	55	Weak references
	56	Regular Expressions
	57	SLIB
	58	POSIX system calls and networking
	59	--- I think people will generally know whether they're looking
	60	for a system call or not, so this should be an okay category.
	61	conventions (includes error handling)
	62	ports vs. file descriptors
	63	file system (mknod goes here, no?)
	64	user database
65	time (includes gettimeofday or whatever, strftime, strptime)
66	processes
67	terminals and pseudo-terminals
68	pipes
69	networking (includes databases, address conversion, and sockets)
70	system identification (uname)
71	locales (setlocale)
72	--- Note that there is no more 'misc'. It's better to have
73	small sections than unhelpful names.
74	SCSH
75	--- includes info on how to get SCSH features (open this
76	module), but mostly just a pointer to the SCSH manual.
77	This should not be under POSIX. SCSH includes plenty of
78	high-level stuff for starting processes and string
79	processing. SCSH is not a subset of POSIX, nor the
80	reverse.
81	Tcl/Tk interface
82	Module internals
83	first-class variables
84	first-class modules
85	internal debugging interface
86	--- The name of this chapter needs to clearly distinguish it
87	from the appendix describing the debugger UI. The intro
88	should have a pointer to the UI appendix.
89
90	Part II: Using Scheme with C --- a Portable Interface
91	--- We cover gh in a completely separate section. Why? I admit
92	I'm on shaky ground, but here's my reasoning: People who want
93	to write portable C code need to restrict themselves to only
94	using GH, and GH's semantics are (necessarily) well-defined
95	without reference to Guile's particulars. This makes life
96	more difficult for folks who just prefer to use the GH
97	interface when they can, but I really think the SCM interface
98	is not so bad, once you're used to it. A lot of GH
99	functions are just wrappers for SCM functions.
100	--- We cover repls here too, since GH has repl functions.
101
102	Part III: Using Scheme with C --- Guile's Interface
103	Scheme data representation
104	Relationship between Scheme and C functions
105	--- this is where we explain that all the functions marked as
106	"Primitive Functions" are also accessible from C, and how
107	to derive the C interface given the Scheme interface, when
108	we don't spell it out.
109	... I think there's other stuff needed here ...
110	I/O internals
111	linking Guile with your code
112	--- Mark's "Tools to automate adding libraries" is not a
113	well-defined concept. I think this is closer to what we
114	want to cover for now.
115	snarfing
116
117	Appendices:
118	Obtaining and Installing Guile
119	Invoking Guile
120	--- mentions read-eval-print loops
121	--- both the SCSH and GAWK manuals relegate invocation details
122	to an appendix. We can give examples in the introduction.
123	debugger user interface
124	--- The title and introduction of this appendix need to
125	distinguish this clearly from the chapter on the internal
126	debugging interface.
127
128	Indices:
129	--- At the top of the function/variable index, remind people
130	to look for functions under their Scheme names as well as
131	their C names.