diff options
| -rw-r--r-- | doc/user/engine.skb | 5 | ||||
| -rw-r--r-- | 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: |