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
indentation. Indentation is important because it helps
understand the code; it is thus desirable to preserve
indentation in program text. The
pre text layout
already allows indentation to be preserved. This chapter presents two
new functions that complement it:
prog and
source, both of which are specially designed to represent computer
programs in text.
A
prog function call preserves the indentation of the
program. It may automatically introduce line numbers.
(
prog [
:mark
";!"] [
:linedigit
] [
:line
1] [
:class
"prog"] [
:ident
]
)
#f disables
the line numbering.
html
lout
latex
context
info
xml
#f. If this option
is a string, that string is the prefix
of line marks. These marks can be used in the
ref reference. A mark
identifier is defined by the regular expression:
[_a-zA-Z][_a-zA-Z0-9]*. The prefix and the mark are removed from the output program.
html
lout
latex
context
info
xml (frame :width 100. (prog :line 10 :mark "##" [ SKRIBILO = skribilo all: demo.html demo.lout ##main-goal demo.html: demo.skb $(SKRIBILO) -t html demo.skb -o demo.html demo.lout: demo.skb $(SKRIBILO) -t lout demo.skb -o demo.lout ] )) ( p [ The main goal is specified on line ,( ref :line "main-goal" ). ] )
... produces:
The
source function extracts part of the source code and
enables
fontification. That is, some words of the program
can be rendered using different colors or faces.
(
source
:language
[
:tab
8] [
:definition
] [
:stop
] [
:start
] [
:file
]
)(use-modules (skribilo source lisp)) ( linebreak ) (frame :width 100. (prog (source :language scheme :file "prgm.skb" :definition 'fib))) ( p [ The Fibonacci function is defined on line ,( ref :line "fib" ). ] ) ( linebreak ) (frame :width 100. (prog :line 23 :mark #f (source :language skribe :file "prgm.skb" :start 22 :stop 29))) ( 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 (string-append ";" "!start" ) ;; trick! :stop (string-append ";" "!stop" ))))
... produces:
The Fibonacci function is defined on line 1.
23: ;*---------------------------------------------------------------------*/ 24: ;* fib ... */ 25: ;*---------------------------------------------------------------------*/ 26: ( define (fib x) ;!fib 27: ( if (< x 2) 28: 1 29: (+ (fib (- x 1)) (fib (- x 2))))) 30:
Here is the source of the frame above:
Note that even awful programming languages of the C family can be highlighted!
(use-modules (skribilo source c)) ( p [ Here's how: ] ) ( linebreak ) (prog (source :language c [ #include <stdlib.h> static int foo = 10 ; static float bar ; /* This is the function responsible for integer chbouibification. */ float chbouibify (int x) { bar = foo + (float) x / random () ; foo = (float) x * random () ; if (x > 2) /* Great! */ printf ( "hello world!\n" ) ; else printf ( "lower than two\n" ) ; return ((float) foo * bar) ; } ] ))
... produces:
Here's how:
1: #include <stdlib.h> 2: 3: static int foo = 10; 4: static float bar; 5: 6: /* This is the function responsible 7: for integer chbouibification. */ 8: float 9: chbouibify (int x) 10: { 11: bar = foo + (float) x / random (); 12: foo = (float) x * random (); 13: 14: if (x > 2) 15: /* Great! */ 16: printf ( "hello world!n" ); 17: else 18: printf ( "lower than twon" ); 19: 20: return ((float) foo * bar); 21: }
You would highlight Java™ code in a similar way, i.e., with :language java.
Files passed as the
:file argument of
source
are searched in the current
source path, which is defined by the
*source-path*
SRFI-39 parameter. This parameter contains
a list of directories and its value can be obtained using
(*source-path*). Its value can be altered using the
-S
command-line option of the
skribilo compiler (see
Chapter 14 for details).
The
:language
parameter of
source takes a
language object, which performs the actual source highlighting.
Several programming languages are currently supported: the
(skribilo source lisp) module provides
skribe,
scheme,
stklos,
bigloo and
lisp, which implement source
highlighting for the corresponding lispy dialects, while the
(skribilo source c) module provides
c and
java.
Thus, you need to import the relevant module to get the right language,
for instance by adding
(use-modules (skribilo source c)) at
the beginning of your document. Additional languages can be created
using the
language function (see below).
The
language function builds a language that can be used
in
source function call.
(
language
:name
[
:extractor
] [
:fontifier
]
)