7. Skribe User Manual -- Computer programs

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 indentation. This indentation is important because it helps in understanding the text; it is thus desirable to preserve it in the Skribe text. The pre text layout already enables such a text formating. This chapter presents two new Skribe functions: prog and source that is specially designed to represent computer programs in Skribe text.

7.1 Program

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

(prog [:ident] [:class "prog"] [:line 1] [:linedigit] [:mark ";!"])
identhtml latex xml The node identifier.
classhtml latex xml The node class.
linehtml latex 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 latex xml The number of digit for representing line numbers.
markhtml latex 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 "##" [

all: demo.html demo.man  ##main-goal

demo.html: demo.skb
        $(SKRIBE) demo.skb -o demo.html

demo.man: demo.skb
        $(SKRIBE) demo.skb -o demo.man

(p [The main goal is specified line ,(ref :line "main-goal").])
Ex. 31: A program


10: SKRIBE=skribe
12: all: demo.html demo.man  
14: demo.html: demo.skb
15: 	$(SKRIBE) demo.skb -o demo.html
17: demo.man: demo.skb
18: 	$(SKRIBE) demo.skb -o demo.man

The main goal is specified 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.

(source :language [:file] [:start] [:stop] [:fontify #t] [:definition] [:tab 8])
languagehtml latex xml The language of the source code.
filehtml latex xml The file containing the actual source code. The file is searched in the skribe-source-path path.
starthtml latex xml A start line number or a start marker.
stophtml latex xml A stop line number or a stop marker.
definitionhtml latex xml The identifier of the definition to extract.
fontifyhtml latex xml A bool that enables/disables fontification.
tabhtml latex xml The tabulation width.
See also
prog language ref skribe-source-path
(frame :width 100. 
       (prog (source :language bigloo :file "prgm.skb" :definition 'fib)))

(p [The Fibonacci function is defined line ,(ref :line "fib").])

(frame :width 100.
       (prog :line 11 :mark #f
             (source :language skribe :file "prgm.skb" :start 11 :stop 24)))

(p [Here is the source of the frame above:])

(frame :width 100.
       (prog :line 30 :mark #f
             (source :language skribe :file "src/prgm2.skb"
                :start ";!start"
                :stop ";!stop")))
Ex. 32: The source markup


1: (define (fib x) 
2:    (if (< x 2)
3:        1
4:        (+ (fib (- x 1)) (fib (- x 2)))))

The Fibonacci function is defined line 1.

11: ;*---------------------------------------------------------------------*/
12: ;*    fib ...                                                          */
13: ;*---------------------------------------------------------------------*/
14: (define (fib x) ;!fib
15:    (if (< x 2)
16:        1
17:        (+ (fib (- x 1)) (fib (- x 2)))))
19: ;*---------------------------------------------------------------------*/
20: ;*    Computer programs                                                */
21: ;*---------------------------------------------------------------------*/
22: (chapter :title "Computer programs" 

Here is the source of the frame above:

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

7.3 Language

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

(language :name [:fontifier] [:extractor])
namehtml latex xml A string which denotes the name of the language.
fontifierhtml latex xml A function of one argument (a string), that colorizes a line source code.
extractorhtml latex 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
(define (makefile-fontifier string)
   (with-input-from-string string
      (lambda ()
         (read/rp (regular-grammar ()
                     ((: #\# (+ all))
                      ;; makefile comment
                      (let ((cmt (the-string)))
                         (cons (it cmt) (ignore))))
                     ((bol (: (+ (out " \t\n:")) #\:))
                      ;; target
                      (let ((prompt (the-string)))
                         (cons (bold prompt) (ignore))))
                     ((bol (: (+ alpha) #\=))
                      ;; variable definitions
                      (let* ((len (- (the-length) 1))
                             (var (the-substring 0 len)))
                         (cons (list (color :fg "#bb0000" (bold var)) "=")
                     ((+ (out " \t\n:=$"))
                      ;; plain strings
                      (let ((str (the-string)))
                         (cons str (ignore))))
                     ((: #\$ #\( (+ (out " )\n")) #\))
                      ;; variable references
                      (let ((str (the-string))
                            (var (the-substring 2 (- (the-length) 1))))
                         (cons (underline str) (ignore))))
                     ((+ (in " \t\n:"))
                      ;; separators
                      (let ((nl (the-string)))
                         (cons nl (ignore))))
                      ;; default
                      (let ((c (the-failure)))
                         (if (eof-object? c)
                             (skribe-error 'makefile "Unexpected char" c)))))

(define makefile
   (language :name "Makefile"
             :fontifier makefile-fontifier))
(frame :width 100. 
       (prog (source :language makefile [

all: demo.html demo.man

demo.html: demo.skb
        $(SKRIBE) demo.skb -o demo.html

demo.man: demo.skb
        $(SKRIBE) demo.skb -o demo.man
Ex. 33: An ad-hoc fontification


 1: SKRIBE=skribe
 3: all: demo.html demo.man
 5: demo.html: demo.skb
 6:         $(SKRIBE) demo.skb -o demo.html
 8: demo.man: demo.skb
 9:         $(SKRIBE) demo.skb -o demo.man

This Html page has been produced by Skribe.
Last update Tue Jun 29 09:37:13 2010.