guile18/doc/sources/jimb-org.texi

   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.