7. Skribilo User Manual — Computer Programs
Contents↑ Skribilo User Manual

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.

7.1 Program

A prog function call preserves the indentation of the program. It may automatically introduce line numbers.

prototype
(prog [:mark ";!"] [:linedigit] [:line 1] [:class "prog"] [:ident])
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
:linehtml lout latex context info xml Enables/disables automatic line numbering. An integer value enables the line number and specifies the number of the first line of the program. A value of #f disables the line numbering.
:linedigithtml lout latex context info xml The number of digit for representing line numbers.
:markhtml lout latex context info xml A string or the boolean #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.
See also
source pre ref 
(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").])
Ex. 33: A program

... produces:

 10: SKRIBILO = skribilo
 11: 
 12: all: demo.html demo.lout  
 13: 
 14: demo.html: demo.skb
 15: 	$(SKRIBILO) -t html demo.skb -o demo.html
 16: 
 17: demo.lout: demo.skb
 18: 	$(SKRIBILO) -t lout demo.skb -o demo.lout

The main goal is specified on line 12.


7.2 Source Code

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.

prototype
(source :language [:tab 8] [:definition] [:stop] [:start] [:file])
optionenginesdescription
:languagehtml lout latex context info xml The language of the source code.
:filehtml lout latex context info xml The file containing the actual source code. The file is searched in the *source-path* path.
:starthtml lout latex context info xml A start line number or a start marker.
:stophtml lout latex context info xml A stop line number or a stop marker.
:definitionhtml lout latex context info xml The identifier of the definition to extract.
:tabhtml lout latex context info xml The tabulation width.
See also
prog language ref *source-path* 

(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"))))
Ex. 34: The source markup

... 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.


 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:


 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);
}]))
Ex. 35: The source markup for C

... 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).


7.3 Language

The language function builds a language that can be used in source function call.

prototype
(language :name [:extractor] [:fontifier])
optionenginesdescription
:namehtml lout latex context info xml A string which denotes the name of the language.
:fontifierhtml lout latex context info xml A function of one argument (a string), that colorizes a line source code.
:extractorhtml lout latex context info xml A function of three arguments: an input port, an identifier, a tabulation size. This function scans in the input port the definition is looks for.
See also
prog source ref

(made with skribilo)