summaryrefslogtreecommitdiff
path: root/doc/user
diff options
context:
space:
mode:
authorLudovic Courtès2008-01-29 18:16:56 +0100
committerLudovic Courtès2008-01-29 18:16:56 +0100
commit098652444872263b7dd370d4f5b3022f79cd11a1 (patch)
tree7d4f67228287bbbe8aa41f2d76d728913c961e05 /doc/user
parentbda408c218cad42b482981213de79e3382df87b6 (diff)
downloadskribilo-098652444872263b7dd370d4f5b3022f79cd11a1.tar.gz
skribilo-098652444872263b7dd370d4f5b3022f79cd11a1.tar.lz
skribilo-098652444872263b7dd370d4f5b3022f79cd11a1.zip
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.
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/Makefile.am2
-rw-r--r--doc/user/src/scheme.scm22
-rw-r--r--doc/user/syntax.skb42
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