[Documentation] non-reference structure & sources

[Andrew Chadwick <andrew dot chadwick at symbian dot com>]

[Ian, as References: header]
> Dorai Sitaram <ds26@gte.com> has written a beautiful Scheme tutorial
> "Teach Yourself Scheme in Fixnum Days"
> http://www.cs.rice.edu/~dorai/t-y-scheme/t-y-scheme.html. It already
> has a section on guile and could easily be turned into a general
> scheme-side guile tutorial if all the guile-specific things were
> added (and the MzSceme, STk, SCM stuff removed.)

It's been mentioned on the lists before, but

  ftp://ftp.cs.utexas.edu/pub/garbage/cs345/schintro-v14/schintro_toc.html

might also be useful. Its style's perhaps a bit rambling for a basic
online introduction to scheme (it's a paper book the guy's working
on), but there are some nice bits in there about the functional
techniques you might use.


[Greg, <qrr4se1tiej.fsf@clavicle.cs.washington.edu>]
> Let us begin discussion on an outline of the non-reference material
> sections that we need. We could use R[45]RS and just add sections
> for Guile-specific notions. Alternatively, maybe one of the other
> Scheme-based scripting language has documentation that we can make
> use of as our starting point.

Just my two'penn'orth: I've tried to collate and organise the various
thoughts people have been having on this list and some sources of
information and make a sensible ordering for them. Hope it makes
sense.

---8<---
* Programming Guile

   * Ten(?)-minute tour of Scheme
      - Mechanics: types, procedures, macros, evaluation.
         - links into detailed section, but minimally. Don't want to
           confuse or lose the new reader.
      - How scheme differs from other languages.
         - C
	 - C++, Java
	 - Perl, Python
	 - Other dialects of Lisp.

   * /Detailed/ tour of Guile's implementation of Scheme
      * First cover the bits in the last section in the same order,
        but in much more detail. Repetition or backlinks?
      * How the evaluator works
	 - How procedures evaluate
	    - Examples
	    - emphasise that everything in the list's evaled.
	    - demonstrate ((lambda (x) x) 42) forms
         - Macros
            - Contrast macro and procedure expansion.
	 - Interactive: guile enters another module, why it does that.
      * The Guile module system
	 - What does using these get you?
         - The load path
	 - Demonstrations
	 - Imports and exports: exactly what's visible from where?
	 - How to import stuff, how to export it.
	    - general export and export-syntax  (well, I prefer 'em)
	    - sugared forms
	 - details of the implementation?
      * <Um, more to come here, I'm sure>
      * Schemely tricks and techniques for propellor-heads
         - Closures, currying, HOFs etc.
	 - Macrologies, procedure-macro-module interaction?
      * Oddities of guile's implementation of standard things
      * General list of the functional areas guile adds (links into
        reference heavily) (perhaps this should go further up)

   * Big reference to the Scheme interface to Guile.
      * Standard, portable scheme from {builtins, ice-9}
         - Remove from the following sections and put here. Useful.
      * Guile-specific builtins
         - by functional area
      * Guile-specific ice-9 stuff
	 - organised by module
            - then by functional area

   * HOWTO-style docs for specific techniques
      - Grab http://home.thezone.net/~gharvey/guile/qdocs/html/qdocs_toc.html
      - Grab http://www.gnu.org/software/guile/docs/faq/guile-faq.html#Recipes
      - Perhaps automatic linking to+from the reference?
      * Processing text
         - http://www.gnu.org/software/guile/docs/faq/guile-faq.html#File%20by%20lines
	 - ports, calling with input from port, string-fun
      * CGI: http://www.cs.rice.edu/~dorai/t-y-scheme/t-y-scheme-Z-H-19.html#%_chap_17
      * Sockets
      * Threads / coroutines

   * Extending the language
      - gh_ interface (mostly existing)
      - calling scheme from C
      - adding types (http://www.gnu.org/software/guile/docs/data-rep.html#SEC24)
      - interfacing with the module system (doesn't SCWM do this?
        can't remember).
--->8---

I'm sure there's a lot I've missed, and I've deliberately left out
front matter, conventions, indices and glossaries. Any additions?

-- 
Andrew Chadwick
System Documentation
Symbian Ltd.