7Skribilo 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 xml The node identifier.
:classhtml lout latex context xml The node class.
:linehtml lout latex context 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 xml The number of digit for representing line numbers.
:markhtml lout latex context 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. 32: 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 xml The language of the source code.
:filehtml lout latex context xml The file containing the actual source code. The file is searched in the *source-path* path.
:starthtml lout latex context xml A start line number or a start marker.
:stophtml lout latex context xml A stop line number or a stop marker.
:definitionhtml lout latex context xml The identifier of the definition to extract.
:tabhtml lout latex context 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 21 :mark #f
              (source :language skribe :file "prgm.skb" :start 20 :stop 27)))


(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. 33: The source markup

... produces:


  1: ;;; prgm.skb  --  Computer programs
  2: ;;;
  3: ;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
  4: ;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
  5: ;;;
  6: ;;;
  7: ;;; This program is free software; you can redistribute it and/or modify
  8: ;;; it under the terms of the GNU General Public License as published by
  9: ;;; the Free Software Foundation; either version 2 of the License, or
 10: ;;; (at your option) any later version.
 11: ;;;
 12: ;;; This program is distributed in the hope that it will be useful,
 13: ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 14: ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 15: ;;; GNU General Public License for more details.
 16: ;;;
 17: ;;; You should have received a copy of the GNU General Public License
 18: ;;; along with this program; if not, write to the Free Software
 19: ;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
 20: ;;; USA.
 21: 
 22: ;*---------------------------------------------------------------------*/
 23: ;*    fib ...                                                          */
 24: ;*---------------------------------------------------------------------*/
 25: (define (fib x) 
 26:    (if (< x 2)
 27:        1
 28:        (+ (fib (- x 1)) (fib (- x 2)))))

The Fibonacci function is defined on line 25.


 21: ;*---------------------------------------------------------------------*/
 22: ;*    fib ...                                                          */
 23: ;*---------------------------------------------------------------------*/
 24: (define (fib x) ;!fib
 25:    (if (< x 2)
 26:        1
 27:        (+ (fib (- x 1)) (fib (- x 2)))))

Here is the source of the frame above:


 30: (frame :width 100.
 31:        (prog :line 21 :mark #f
 32:               (source :language skribe :file "prgm.skb" :start 20 :stop 27)))

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. 34: 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 xml A string which denotes the name of the language.
:fontifierhtml lout latex context xml A function of one argument (a string), that colorizes a line source code.
:extractorhtml lout latex context 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)