summaryrefslogtreecommitdiff
path: root/doc/user
diff options
context:
space:
mode:
authorLudovic Courtès2008-02-03 21:39:42 +0100
committerLudovic Courtès2008-02-03 21:39:42 +0100
commit71529195046227ccbecfd84d9492cc3a1f91f310 (patch)
tree4299ef3eed651ad7135d19c025ffe6d50adbd891 /doc/user
parentd13911b6c6bac9fb3ad20d6cb39e2002759f8496 (diff)
downloadskribilo-71529195046227ccbecfd84d9492cc3a1f91f310.tar.gz
skribilo-71529195046227ccbecfd84d9492cc3a1f91f310.tar.lz
skribilo-71529195046227ccbecfd84d9492cc3a1f91f310.zip
doc: Improve chapter on computer program highlighting.
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/prgm.skb38
-rw-r--r--doc/user/src/prgm1.skb12
-rw-r--r--doc/user/src/prgm2.skb13
3 files changed, 40 insertions, 23 deletions
diff --git a/doc/user/prgm.skb b/doc/user/prgm.skb
index 95a69bf..e44ad10 100644
--- a/doc/user/prgm.skb
+++ b/doc/user/prgm.skb
@@ -32,17 +32,16 @@
;*---------------------------------------------------------------------*/
(chapter :title "Computer Programs"
-(p [It is common that some parts of a Skribe text represent other
-texts. For instance, for a document describing a computer programming
-language, it is frequent to include excerpt of programs. These
-embedded texts are frequently displayed in a specific font and with no
-justification but with a precise ,(emph "indentation"). This indentation is
-important because it helps in understanding the text,(begin ";")
-it is thus desirable to preserve it in the Skribe text. The
-,(markup-ref "pre") text layout already enables such a
-text formating. This chapter presents two new Skribe functions:
-,(markup-ref "prog") and ,(markup-ref "source") that is specially
-designed to represent computer programs in Skribe text.])
+(p [In a document describing a computer programming language, it is
+common to include excerpt of programs. Program code is typically
+typeset in a specific font, with no justification, and with a precise
+,(emph "indentation"). Indentation is important because it helps
+understand the code,(begin ";") it is thus desirable to preserve
+indentation in program text. The ,(markup-ref "pre") text layout
+already allows indentation to be preserved. This chapter presents two
+new functions that complement it: ,(markup-ref "prog") and ,(markup-ref
+"source"), both of which are specially designed to represent computer
+programs in text.])
;*---------------------------------------------------------------------*/
;* Programs ... @label prog@ */
@@ -94,7 +93,8 @@ can be rendered using different colors or faces.])
:force-engines *api-engines*
:see-also '(prog language ref *source-path*))
;!source-stop
-
+
+(linebreak)
(example-produce
(example :legend "The source markup" (prgm :file "src/prgm2.skb"))
(disp (include "src/prgm2.skb")))
@@ -106,7 +106,19 @@ are searched in the current ,(emph [source path]), which is defined by the
a list of directories and its value can be obtained using ,(code
[(*source-path*)]). Its value can be altered using the ,(tt [-S])
command-line option of the ,(tt [skribilo]) compiler (see ,(numref :text
-[Chapter] :ident "compiler") for details).]))
+[Chapter] :ident "compiler") for details).])
+
+(p [The ,(param :language) parameter of ,(markup-ref "source") takes a
+,(tt [language]) object, which performs the actual source highlighting.
+Several programming languages are currently supported: the ,(tt
+[(skribilo source lisp)]) module provides ,(tt [skribe]), ,(tt [scheme]),
+,(tt [stklos]), ,(tt [bigloo]) and ,(tt [lisp]), which implement source
+highlighting for the corresponding lispy dialects, while the ,(tt
+[(skribilo source c)]) module provides ,(tt [c]) and ,(tt [java]).
+Thus, you need to import the relevant module to get the right language,
+for instance by adding ,(code [(use-modules (skribilo source c))]) at
+the beginning of your document. Additional languages can be created
+using the ,(markup-ref "language") function (see below).]))
;*---------------------------------------------------------------------*/
;* Language ... @label language@ */
diff --git a/doc/user/src/prgm1.skb b/doc/user/src/prgm1.skb
index dcdeb88..53b24d2 100644
--- a/doc/user/src/prgm1.skb
+++ b/doc/user/src/prgm1.skb
@@ -1,15 +1,15 @@
(frame :width 100.
(prog :line 10 :mark "##" [
-SKRIBE=skribe
+SKRIBILO = skribilo
-all: demo.html demo.man ##main-goal
+all: demo.html demo.lout ##main-goal
demo.html: demo.skb
- $(SKRIBE) demo.skb -o demo.html
+ $(SKRIBILO) -t html demo.skb -o demo.html
-demo.man: demo.skb
- $(SKRIBE) demo.skb -o demo.man
+demo.lout: demo.skb
+ $(SKRIBILO) -t lout demo.skb -o demo.lout
]))
-(p [The main goal is specified line ,(ref :line "main-goal").])
+(p [The main goal is specified on line ,(ref :line "main-goal").])
diff --git a/doc/user/src/prgm2.skb b/doc/user/src/prgm2.skb
index 2996cc8..8ba1bc3 100644
--- a/doc/user/src/prgm2.skb
+++ b/doc/user/src/prgm2.skb
@@ -1,7 +1,11 @@
+(use-modules (skribilo source lisp))
+
+(linebreak)
(frame :width 100.
- (prog (source :language bigloo :file "prgm.skb" :definition 'fib)))
+ (prog (source :language scheme :file "prgm.skb" :definition 'fib)))
-(p [The Fibonacci function is defined line ,(ref :line "fib").])
+(p [The Fibonacci function is defined on line ,(ref :line "fib").])
+(linebreak)
;!start
(frame :width 100.
@@ -10,9 +14,10 @@
;!stop
(p [Here is the source of the frame above:])
+(linebreak)
(frame :width 100.
(prog :line 30 :mark #f
(source :language skribe :file "src/prgm2.skb"
- :start ";!start"
- :stop ";!stop")))
+ :start (string-append ";" "!start") ;; trick!
+ :stop (string-append ";" "!stop"))))