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