7. Skribilo User Manual — Computer Programs |
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 ... 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:
1: (define (fib x) 2: (if (< x 2) 3: 1 4: (+ (fib (- x 1)) (fib (- x 2))))) |
The Fibonacci function is defined on line 1.
Here is the source of the frame above:
30: (frame :width 100. 31: (prog :line 23 :mark #f 32: (source :language skribe :file "prgm.skb" :start 22 :stop 29))) |
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])