X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=guile18%2Fdoc%2Fsources%2Fjimb-org.texi;fp=guile18%2Fdoc%2Fsources%2Fjimb-org.texi;h=5ec4216db87e01ecfa1914b6a0ca05cfc4915b0b;hb=139c38d9204dd07f6b235f83bae644faedbc63fd;hp=0000000000000000000000000000000000000000;hpb=652ed35a2013489d0a14fede6307cd2595abb2c4;p=lilypond.git

diff --git a/guile18/doc/sources/jimb-org.texi b/guile18/doc/sources/jimb-org.texi
new file mode 100644
index 0000000000..5ec4216db8
--- /dev/null
+++ b/guile18/doc/sources/jimb-org.texi
@@ -0,0 +1,131 @@
+@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.