From 839203d749de348ad6bf0ca2d1f6357df0208b49 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès
Date: Sat, 13 Dec 2008 19:03:41 +0100
Subject: doc: Add "Writing New Readers".

* doc/user/syntax.skb (syntax)[custom-syntax]: New section.  Suggested
  by Klaus Schilling <schilling.klaus@web.de>.

* doc/user/engine.skb (custom-engine): Link to `custom-syntax'.
---
 doc/user/engine.skb |  5 ++++-
 doc/user/syntax.skb | 40 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/doc/user/engine.skb b/doc/user/engine.skb
index d075ebc..17106f5 100644
--- a/doc/user/engine.skb
+++ b/doc/user/engine.skb
@@ -163,6 +163,7 @@ list of available customs is shown for each engine, along with each
 custom's default value and a description.]))
       
       (subsection :title [Writing New Engines]
+	          :ident "custom-engine"
 	 
 	 (p [Writing new engines (i.e., output formats) and making them
 available to Skribilo is an easy task.  Essentially, this boils down to
@@ -190,7 +191,9 @@ must be bound, in that module, to a variable called, say, ,(tt
 Guile's load path; for instance, you can adjust the ,(tt
 [GUILE_LOAD_PATH]) environment variable.]))
 
-This is all it takes to extend Skribilo's set of engines!])))
+This is all it takes to extend Skribilo's set of engines!  Note that
+this mechanism is the same as that of ,(emph [readers]) (see ,(numref
+:text [Section] :ident "custom-syntax")).])))
 
    ;; existing engines
    (include "htmle.skb")
diff --git a/doc/user/syntax.skb b/doc/user/syntax.skb
index e5917ca..cdcdf9c 100644
--- a/doc/user/syntax.skb
+++ b/doc/user/syntax.skb
@@ -226,7 +226,45 @@ compiler does]), would look like this:]
 	 
         [This should give you an idea of the wonderful, life-changing
 things that can be achieved with a bit of ,(emph [document
-programming]).])))
+programming]).]))
+   
+   (section :title [Writing New Readers]
+            :ident "custom-syntax"
+      
+      (p [Skribilo is extensible and makes it easy to add ,(emph [custom
+readers]), allowing the use of virtually any input syntax.  A reader is
+essentially a procedure like R5RS' ,(tt [read]), i.e., a one-argument
+procedure that takes a port and returns an S-expression.  The returned
+S-expression should be a valid ``document program'' as shown in ,(ref
+:ident "scheme-syntax").])
+      
+      (p [The are a few additional details, though.  Implementations of
+readers are required to use the ,(tt [(skribilo reader)]) modules and
+the ,(tt [define-reader]) macro.  In addition, the reader must live in
+its own module, under the ,(tt [(skribilo reader)]) module hierarchy, so
+that the reader lookup mechanism (used by the ,(tt [--reader]) option of
+the compiler) can find it.  This mechanism is the same as that used for
+engines (see ,(numref :text [Section] :ident "custom-engine")).  A
+skeleton for a reader would be like this:]
+    
+	(example :legend [Writing a new reader.]
+	 (prgm :language scheme [
+(define-module (skribilo reader my-reader)
+  :use-module (skribilo reader)
+  :export (reader-specification))
+
+(define (make-my-reader)
+  (lambda (port)
+    ...))
+
+(define-reader my-reader  ;; the reader name
+  "0.1"                   ;; a version number
+  make-my-reader)         ;; the procedure that returns
+                          ;; a reader procedure
+]))
+	
+      	[Users and encouraged to look at examples in the Skribilo
+source for additional details.])))
 
 
 ;;; Local Variables:
-- 
cgit v1.2.3