+ Restructuring: Now, we have a three (four) layer concept:

Basic User, Advanced User, Administrative User
+ see file SURFLETS-STRUCTURES.TXT for details
+ Adapt example surflets to new structures. Only surflets that use extended
  features should need adaptations.

scheme/httpd/surflets/packages.scm

@@ -23,52 +23,143 @@
 	  surflet-response-headers
 	  surflet-response-data))
 
+;; SUrflet-requests as expected from the surflet handler
+(define-interface surflet-handler/requests-interface
+  (export make-surflet-request		;FIMXE? unusable for user
+	  surflet-request?
+	  surflet-request-request
+	  surflet-request-input-port
+	  surflet-request-method
+	  surflet-request-uri
+	  surflet-request-url
+	  surflet-request-version
+	  surflet-request-headers
+	  surflet-request-socket))
+
+(define-interface surflets/error-interface
+  (export send-error			;send error response
+	  (status-code :syntax)))	;from httpd-responses
+
 ;; Use for SUrflets
-(define-interface surflet-handler/surflets-interface
+(define-interface surflet-handler/primitives-interface
   (compound-interface 
    surflet-handler/responses-interface
+   surflet-handler/requests-interface
+   surflets/error-interface
    (export send/suspend			;send and suspend
 	   send/finish			;send and finish
 	   send				;just send (no finish, no suspend)
-	   send-error			;send error response
-	   set-session-data!
-	   get-session-data
-	   adjust-timeout!		;adjusts timeout of current session
 	   )))
 
-;; Use for adminstration of the Surflet Handler
-(define-interface surflet-handler/admin-interface
-  (export get-loaded-surflets
-	  unload-surflet
 
-	  options-session-lifetime
+;; Send HTML-Strings (for advanced user)
-	  options-cache-surflets?
+(define-interface surflets/send-html-string-interface
-	  options-surflet-path
+  (export send-html-string/suspend
-	  set-options-session-lifetime!
+	  send-html-string/finish
-	  set-options-cache-surflets?!
+	  send-html-string))
 
+;; Extensions/Exports to/from Olegs SSAX library
+(define-interface surflets/sxml-interface
+  (export display-low-level-sxml
+	  sxml->string
+	  sxml->string/internal
+	  sxml-attribute?
+	  default-rule
+	  text-rule
+	  attribute-rule))
+
+;; SUrflets' extensions to SXML
+(define-interface surflets/surflet-sxml-interface
+  (export surflet-sxml->low-level-sxml
+	  surflet-sxml-rules
+	  surflet-form-rule
+	  default-rules
+	  plain-html-rule
+	  url-rule))
+
+;; Use for advanced users: make your own conversion rules.
+(define-interface surflets/my-sxml-interface
+  (compound-interface
+   surflets/send-html-string-interface
+   surflets/sxml-interface
+   surflets/surflet-sxml-interface))
+
+(define-interface surflets/continuations-interface
+  (export get-continuations
+	  delete-continuation!))
+
+;; Access to session-id and continuation-id
+(define-interface surflets/ids-interface
+  (export my-session-id
+	  my-continuation-id
+	  my-ids
+	  instance-session-id))
+
+;; Use for advanced users: access to your sessions and continuations
+;; and continuations (currently you get access to all sessions; this
+;; should and will be restricted in the future)
+(define-interface surflets/my-sessions-interface
+  (compound-interface 
+   surflets/ids-interface
+   surflets/continuations-interface
+   (export get-session
+	   ;; That would be too much:
+	   ;; get-sessions
+	   delete-session!
+	   get-session-data
+	   set-session-data!
+	   instance-session-id
+	   session-adjust-timeout!
+	   adjust-timeout!
+	   session-alive?
+	   session-surflet-name
+	   options-session-lifetime
+	   options-cache-surflets?)))
+
+(define-interface surflets/sessions-interface
+  (export get-session
 	  get-sessions
+	  delete-session!
+	  get-session-data
+	  set-session-data!
+	  instance-session-id
+	  session-adjust-timeout!
+	  adjust-timeout!
 	  session-alive?
 	  session-surflet-name
+	  ;; FIXME: This is too much and should be restricted:
 	  session-memo
 	  session-continuation-table
 	  session-continuation-table-lock
-	  session-continuation-counter
+	  session-continuation-counter))
-	  delete-session!
 
-	  session-adjust-timeout!
+(define-interface surflet-handler/surflets-interface
-	  adjust-timeout!
+  (export get-loaded-surflets
+	  unload-surflet))
 
-	  get-continuations
+(define-interface surflet-handler/options-interface
-	  delete-continuation!
+  (export options-session-lifetime
+	  options-cache-surflets?
+	  options-surflet-path
+	  set-options-session-lifetime!
+	  set-options-cache-surflets?!))
 
-	  instance-session-id
+(define-interface surflet-handler/resume-url-interface
-
+  (export resume-url?
-	  resume-url?
 	  resume-url-ids
 	  resume-url-session-id
 	  resume-url-continuation-id))
 
+;; Use for adminstration of the Surflet Handler
+(define-interface surflet-handler/admin-interface
+  (compound-interface
+   surflet-handler/surflets-interface
+   surflets/sessions-interface
+   surflets/continuations-interface
+   surflet-handler/resume-url-interface
+   surflet-handler/options-interface
+))
+
 ;; THE interface that SUrflets use.
 (define-interface surflet-interface
   (export main))			; MAIN gets one parameter, the REQUEST
@@ -141,18 +232,7 @@
 	  thread-safe-counter-next!
 	  thread-safe-counter?))
 
-;; SUrflet-requests as expected from the surflet handler
+
-(define-interface surflet-requests-interface
-  (export make-surflet-request
-	  surflet-request?
-	  surflet-request-request
-	  surflet-request-input-port
-	  surflet-request-method
-	  surflet-request-uri
-	  surflet-request-url
-	  surflet-request-version
-	  surflet-request-headers
-	  surflet-request-socket))
 
 ;; These two are from Martin Gasbichler:
 (define-interface rt-module-language-interface 
@@ -177,14 +257,7 @@
   (export typed-optionals
 	  (optionals :syntax)))
 
-;; Extensions/Exports to/from Olegs SSAX library
+
-(define-interface surflets/sxml-interface
-  (export display-low-level-sxml
-	  sxml->string
-	  sxml-attribute?
-	  default-rule
-	  text-rule
-	  attribute-rule))
 
 ;; Input-fields as Scheme objects
 (define-interface surflets/input-fields-interface
@@ -213,22 +286,6 @@
   (export *input-field-trigger*
 	  input-field-html-tree))
 
-;; SUrflets' extensions to SXML
-(define-interface surflets/surflet-sxml-interface
-  (export surflet-sxml->low-level-sxml
-	  surflet-sxml-rules
-	  surflet-form-rule
-	  default-rules
-	  plain-html-rule
-	  url-rule))
-
-;; Access to session-id and continuation-id
-(define-interface surflets/ids-interface
-  (export my-session-id
-	  my-continuation-id
-	  my-ids
-	  instance-session-id))
-
 ;; Some utilities
 (define-interface surflets/utilities-interface
   (export form-query-list
@@ -263,33 +320,39 @@
 	  extract-bindings
 	  extract-single-binding))
 
-;; HTML-Extensions to send/suspend et al.
+;; HTML-Extensions to send/suspend et al. (for basic user)
 (define-interface surflets/send-html-interface
   (export send-html/suspend
 	  send-html/finish
 	  send-html))
 
 
-;; Helping functions for surflets
+
+;; Helping functions for surflets (for basic user)
 (define-interface surflets-interface
   (compound-interface
-   surflet-handler/surflets-interface
+;   surflet-handler/surflets-interface;
-   surflets/sxml-interface
+;   surflets/sxml-interface
-   surflets/surflet-sxml-interface
+;   surflets/surflet-sxml-interface
    surflets/send-html-interface
    surflets/input-fields-interface
    surflets/addresses-interface
    surflets/returned-via-interface
    surflets/bindings-interface))
 
-
 ;;; Structures
 ;; structures from SUrflet Handler
 (define-structures
   ((surflet-handler surflet-handler-interface)
    (surflet-handler/surflets surflet-handler/surflets-interface)
+   (surflet-handler/options surflet-handler/options-interface)
+   (surflet-handler/resume-url surflet-handler/resume-url-interface)
    (surflet-handler/admin surflet-handler/admin-interface)
-   (surflet-handler/responses surflet-handler/responses-interface))
+   (surflet-handler/primitives surflet-handler/primitives-interface)
+   (surflet-handler/responses surflet-handler/responses-interface)
+   (surflets/sessions surflets/sessions-interface)
+   (surflets/continuations surflets/continuations-interface)
+   (surflets/error surflets/error-interface))
   (open	define-record-types		;DEFINE-RECORD-TYPE
 	handle-fatal    		;WITH-FATAL-ERROR-HANDLER* et al.
 	handle-fatal-error
@@ -319,15 +382,19 @@
 
 ;; SUrflets library of helping functions 
 (define-structure surflets surflets-interface
-  (open surflet-handler/surflets
+  (open	surflets/send-html
-	surflets/sxml
-	surflets/surflet-sxml
-	surflets/send-html
 	surflets/input-fields
 	surflets/addresses
 	surflets/returned-via
 	surflets/bindings))
 
+;; SUrflets library for advanced users: make and use your own
+;; conversion rules.
+(define-structure surflets/my-sxml surflets/my-sxml-interface
+  (open	surflets/send-html-string
+	surflets/sxml
+	surflets/surflet-sxml))
+
 ;; Shift-Reset
 (define-structure shift-reset shift-reset-interface
   (open scheme
@@ -372,7 +439,13 @@
   (files thread-safe-counter))
 
 ;; SUrflet-requests as expected from the SUrflet handler 
-(define-structure surflet-requests surflet-requests-interface
+;;; We have two names for the same thing to ease the use of structure
+;;; names: requests seem to be part of the surflet-handler, but are
+;;; actually seperate files. If you know everything about SUrflets,
+;;; you use `surlfet-requests'.
+(define-structures
+  ((surflet-handler/requests surflet-handler/requests-interface)
+   (surflet-requests surflet-handler/requests-interface))
   (open scheme
 	define-record-types
 	httpd-requests)
@@ -442,7 +515,7 @@
 (define-structure surflets/utilities surflets/utilities-interface
   (open scheme
 	parse-html-forms
-	(subset surflet-handler/surflets (send/suspend)))
+	(subset surflet-handler/primitives (send/suspend)))
   (files utilities))
 
 
@@ -482,10 +555,11 @@
 	(subset sunet-utilities (get-header)))
   (files bindings))
 
-(define-structure surflets/send-html surflets/send-html-interface
+(define-structures
+  ((surflets/send-html surflets/send-html-interface)
+   (surflets/send-html-string surflets/send-html-string-interface))
   (open scheme
-	(subset httpd-responses (status-code))
+	surflet-handler/primitives
-	surflet-handler/surflets
 	surflets/sxml
 	surflets/surflet-sxml)
   (files send-html))

scheme/httpd/surflets/surflets-structures.txt

@@ -0,0 +1,188 @@
+We have three basic layers of structures:            -*- Outline -*- 
+
+* Overview
+(a) Basic User           surflets, simple-surflet-api
+(b) Advanced User        surflets/my-sxml, surflets/my-sessions,
+                         surflet-handler/primitives
+(c) Administrative User  surflet-handler/admin, profiling
+
+The fourth layer:
+(d) Various              surflets/outdaters, surflets/utilities
+
+Finally, there is a HOWTO added, that describes how you can use your
+own rules.
+
+* (a) Basic User
+**    structures: (1) surflets
+      provides:      . sending of html represented by surflet-sxml
+                     . using special tags in its surflet-sxml:
+                       url, plain-html, surflet-form
+                     . input-fields, input-field-value,...
+                     . get-bindings, extract-bindings, ...
+                     . make-address, make-annotated-address, ...
+                     . returned-via?, case-returned-via, ...
+                     surflets is splitted in several parts, that can
+                       be loaded independently from each other.
+  
+**    structures: (2) simple-surflet-api
+      provides:     . PLT like generation of simple web pages:
+                    . single-query, form-query, inform-page,
+                      final-page
+                    . make-password, make-number...
+  
+
+* (b) Advanced User
+**    structures: (1) surflets/my-sxml
+      provides:       . generating and sending of own sxml, 
+                        see HOWTO below
+                      . send-html-string/suspend...
+                      . sxml-rules...
+                      . sxml->string
+                      . surflet-sxml-rules...
+                      . surflet-sxml->low-level-sxml
+  
+**    structures: (2) surflets/my-sessions
+      provides:       . Everything needed to administrate your own 
+                        sessions and continuations.
+                        (This represents the access to the sessions of
+                        one surflet. However, you currently have
+                        access to all sessions. This will be
+                        restricted in the future.)
+                      . my-session-id, my-continuation-id, 
+                        instance-session-id
+                      . get-session, delete-session!
+                      . get-continuation, delete-continuation!
+                      . session-adjust-timeout!, adjust-timeout!
+                      . session-alive?, session-surflet-name
+                      . access to options: options-session-lifetime,
+                        options-cache-surflets?
+**    structures: (3) surflet-handler/primitives
+      provides:     . Access to the primitives of the 
+                      surflet handler:
+                    . send/suspend, ... that send surflet responses
+                    . send-error (sending Webserver error message)
+                    . make-surflet-response, ... status-code:
+                      surflet responses with own status-code, own
+                      content-type, own headers and own content
+                      (string or list of strings)
+                    . surflet-requests...
+  
+
+* (c) Administrative User
+**    structures: (1) surflet-handler/admin
+      provides:     . Access to all internal structures of the
+                      handler
+                    . surflets: get-loaded-surflets, unload-surflet
+                    . sessions: get-session, get-sessions,
+                      session-data, instance-session-id,
+                      adjust-timeout..., session-record selectors
+                    . continuations: get-continuations,
+                      delete-continuations!
+                    . resume-urls: resume-url?, resume-url-ids...
+                    . options: options-session-lifetime...
+                      set-options...!
+                    surflet-handler/admin is splitted in several
+                      parts, that can be loaded independently from
+                      each other.
+  
+**    structures: (2) profiling
+      provides:     . Access to memory usage of the whole scsh session
+                    . profile-space, profile-results,
+                      with-gnuplot-data-file, space-info-pair,
+                      space-info-symbol...
+  
+
+* (d) Various
+**    structures: (1) surflets/outdaters
+      provides:     . Data structure to prevent call for outdated
+                      links. This is useful if in some places of your
+                      session the user should not go back and recall
+                      another continuation.
+                    . make-outdater, if-outdated, show-outdated
+  
+**    structures: (2) surflets/utilities
+      provides:     . Various utilities that didn't fit in another
+                      package but were too small for an own one.
+                    . form-query-list: url-query->alist
+                    . rev-append
+                    . make-callback enables you to place a callback
+                      below a link. If the user clicks the link, an
+                      arbitrary function is called.
+                    . generate-unique-name generates name from a
+                      prefix that are highest probable unique with
+                      this prefix. For example this is used to
+                      generate the names of the input fields.
+  
+
+* HOWTO use your own conversion rules:
+
+**  (i) Create your own conversion rules:
+
+ (trigger [*preorder*] . function)
+
+ - TRIGGER is the symbol that trigger the rule
+
+ - FUNCTION will get the trigger and the rest of the list, that
+   triggered the rule as arguments. Thus, if you know, you will
+   only get (at least x) arguments, FUNCTION must accept (at
+   least) x+1 arguments.  FUNCTION must return a list
+   containing only characters or strings or, recursively, lists
+   of this type. (Well, there may be others also, but this is
+   too advanced.)
+
+ - If *PREORDER* misses, the rules will be first applied to all
+   arguments, before the are passed to function.
+
+
+*** Examples:
+  MY-HEAD will take no args and creates my heading:
+
+  (define my-head-rule
+  `(my-head . (lambda (trigger) 
+               (list "<head><title>My Page</title></head"))))
+
+  MY-TITLE-HEAD takes one argument, the title:
+  (define my-title-head-rul
+  `(my-title-head . (lambda (trigger title)
+                     (list "<head><title>" 
+                           title
+                           "</title></head"))))
+
+*** SXML->STRING/INTERNAL
+  MY-ATTRIBUTED-HEAD takes attributes as well. As we don't want
+    to reformat this on our own, we use SXML->STRING/INTERNAL,
+    assuming that MY-RULES contains *all* the rules we use for
+    this sublist. As we do everything for the rest of the tree
+    ourselves, we use *preorder*:
+  (define my-attributed-head
+  `(my-attributed-head *preorder* . 
+     ,(lambda (trigger attributes title)
+       (sxml->string/internal `(head ,attributes (title ,title))
+                              my-rules))))
+
+**  (ii) Create your own rule set. 
+  A rule set is a list of conversion rules. 
+
+***  Example:
+  (define my-rules 
+    (list default-rule
+          attribute-rule
+          text-rule
+          my-head-rule 
+          my-title-head 
+          my-attributed-head))
+
+***  Note:
+  If you want to use SXML->STRING/INTERNAL with the same
+  rule set that entered the rule, you have to define them
+  either on top level with define or with letrec like
+  
+  (letrec ((my-rules 
+            (cons my-attributed-head-rule default-rules))
+           (my-attributed-head-rule
+            `(my-attributed-head *preorder* . 
+               ,(lambda (trigger attributes title)
+                (sxml->string/internal `(head ,attributes (title ,title))
+                                       my-rules)))))
+    my-rules)
+

scheme/httpd/surflets/web-server/root/surflets/add-html.scm

@@ -2,6 +2,7 @@
   (open surflets
 	surflets/utilities		;form-query-list
 	surflet-requests
+	surflet-handler/primitives
 	httpd-responses
 	url
 	scheme-with-scsh)

scheme/httpd/surflets/web-server/root/surflets/add-raw.scm

@@ -5,7 +5,7 @@
 	url				; HTTP-url-SEARCH
 	srfi-1				; FILTER
 	surflet-handler/surflets	; SEND/SUSPEND, SEND/FINISH
-	surflet-handler/responses	; MAKE-SURFLET-RESPONSE
+	surflet-handler/primitives	; MAKE-SURFLET-RESPONSE
 	scheme-with-scsh)
   (begin
 

scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm

@@ -3,8 +3,8 @@
 	handle-fatal-error
 	let-opt
 	surflets
-	surflet-handler/admin
+	surflets/error
-	httpd-responses
+	surflet-handler/options
 	)
   (begin
 

scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm

@@ -1,17 +1,16 @@
 (define-structure surflet surflet-interface
   (open scheme-with-scsh
 	surflets
-	surflet-handler/admin
+	surflets/sessions
+	surflets/error
 	profiling
 	handle-fatal-error
-	httpd-responses
 	(subset srfi-1 (iota))
 	define-record-types
 	locks
 	let-opt
 	receiving
-	primitives
+	(subset primitives (add-finalizer!))
-	handle-fatal-error
 	)
   (begin
 

scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm

@@ -3,8 +3,8 @@
 	surflets
 	surflets/utilities		;make-callback
 	surflets/outdaters
+	surflets/error
 	surflet-handler/admin
-	httpd-responses
 	handle-fatal-error
 	let-opt
 	srfi-1				;filter-map

scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm

@@ -4,10 +4,8 @@
 	surflets/utilities		;make-callback
 	surflets/outdaters
 	surflets/ids
+	surflets/error
 	surflet-handler/admin
-	httpd-responses
-	surflet-requests
-	url
 	handle-fatal-error
 	let-opt
 	srfi-1				;filter-map, last