doc: Add section about "documents in Scheme programs".

* doc/user/Makefile.am (EXTRA_DIST): Add `src/scheme.scm'.

* doc/user/syntax.skb (Documents in Scheme Programs): New.

3 files changed, 53 insertions, 13 deletions

diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am
index c89c95f..4020dc7 100644
--- a/doc/user/Makefile.am
+++ b/doc/user/Makefile.am
@@ -21,7 +21,7 @@ EXTRA_DIST += src/api1.skb						\
   src/links2.skb src/pie1.skb src/pie2.skb src/prgm1.skb src/prgm2.skb	\
   src/prgm3.skb src/slides.skb src/start1.skb src/start2.skb		\
   src/start3.skb src/start4.skb src/start5.skb				\
-  src/outline.txt
+  src/outline.txt src/scheme.scm
 
 
 html_DATA = user.html
diff --git a/doc/user/src/scheme.scm b/doc/user/src/scheme.scm
new file mode 100644
index 0000000..0bb87e5
--- /dev/null
+++ b/doc/user/src/scheme.scm
@@ -0,0 +1,22 @@
+(use-modules (skribilo engine)       ;; provides `find-engine'
+	     (skribilo evaluator)    ;; provides `evaluate-document'
+	     (skribilo package base) ;; provides `chapter', etc.
+             (srfi srfi-1))
+
+(let (;; Select an engine, i.e., an output format.
+      (e (find-engine 'html))
+
+      ;; Create a document.
+      (d (document #:title "Some Title"
+	    (chapter #:title "The Chapter"
+                (p "The paragraph...  "
+                   "Text consists of "
+                   "a list of strings.")
+                (apply itemize
+                       (map number->string
+                            (iota 10)))))))
+
+  ;; "Evaluate" the document to an HTML file.
+  (with-output-to-file "foo.html"
+    (lambda ()
+      (evaluate-document d e))))
diff --git a/doc/user/syntax.skb b/doc/user/syntax.skb
index 5ade31a..b11b001 100644
--- a/doc/user/syntax.skb
+++ b/doc/user/syntax.skb
@@ -38,6 +38,7 @@ first described, and then alternate syntaxes are presented.])
 
 
    (section :title [The Skribe Syntax]
+            :ident "skribe-syntax"
 
       (p [By default or when the ,(tt [--reader=skribe]) option is
 passed to the compiler, a Skribilo document is composed of ,(emph
@@ -86,7 +87,7 @@ the escape sequence `,(color :fg "#009900" (char #\,)(char #\())'.])
 ;*---------------------------------------------------------------------*/
 ;*    Formal syntax                                                    */
 ;*---------------------------------------------------------------------*/
-(subsection :title "Skribe Syntax" 
+(subsection :title [Formal Syntax]
 
 (disp :verb #t :bg *prgm-skribe-color* [
 <expr>    --> <atom>
@@ -195,20 +196,37 @@ to the native ,(tt [skribe]) syntax:])
 					     (string #\newline))
 				(loop (read-line)
 				      (cons line result))))))))))
-	 (disp
-	   (prgm 
-	     (with-output-to-string
-	       (lambda ()
-		 (let* ((read  (make-reader 'outline))
-			(input (open-input-file src))
-			(sexp  (read input)))
-		   (pretty-print sexp :width 65))))))))
+	 (prgm 
+	   (with-output-to-string
+	     (lambda ()
+	       (let* ((read  (make-reader 'outline))
+		      (input (open-input-file src))
+		      (sexp  (read input)))
+		 (pretty-print sexp :width 65)))))))
       
       (p [The ,(tt [outline]) mode makes it possible to quickly create
 documents that can be output in variety of formats (see ,(numref :text
-[Chapter] :ident "engines")).  The downside is that, being a markup-less
-document format, there are many things cannot be done using it, most
-notably tables, bibliographies, and cross-references.])))
+[Chapter] :ident "engines")).  The downside is that, being a very simple
+markup-less document format, there are many things that cannot be done
+using it, most notably tables, bibliographies, and cross-references.]))
+   
+   (section :title [Documents in Scheme Programs]
+      
+      (p [It is also possible to create and output Skribilo documents
+from a Guile Scheme program.  In that case, you get to use the Scheme
+syntax, which is close to the ,(ref :ident "skribe-syntax" :text [Skribe
+syntax]) described above, modulo the ,(code "[...]") constructs.  A
+typical Scheme program that would produce and output a document, pretty
+much like what the ,(ref :ident "compiler" :text [,(tt [skribilo])
+compiler does]), would look like this:]
+	 
+	 (example :legend [Programming Skribilo documents in Scheme.]
+	  (prgm :language scheme :file "src/scheme.scm"))
+	 
+        [This should give you an idea of the wonderful, life-changing
+things that can be achieved with a bit of ,(emph [document
+programming]).])))
+
 
 ;;; Local Variables:
 ;;; coding: latin-1