7. Skribe User Manual -- Computer programs


main page
top:Skribe User Manual
index:Index
markups:Standard Markups


Computer programs
7.1Program
7.2Source code
7.3Language


Chapters
1Getting Started
2Syntax & Values
3Standard Markups
4References and Hyperlinks
5Indexes
6Bibliography
7Computer programs
8Standard Library
9Engines
10Editing Skribe Programs
11Skribe compiler
12Compiling Texi documents
13List of examples
14Table of contents

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.

prototype
(prog [:ident] [:class] [:line 1] [:linedigit] [:mark ";!"])
optionenginesdescription
:identhtml latex The node identifier.
:classhtml latex The node class.
:linehtml latex 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 The number of digit for representing line numbers.
:markhtml latex 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 ref
Example:
(frame :width 100. 
       (prog :line 10 :mark "##" [
SKRIBE=skribe

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
Produces:
10: SKRIBE=skribe
11: 
12: all: demo.html demo.man  
13: 
14: demo.html: demo.skb
15: 	$(SKRIBE) demo.skb -o demo.html
16: 
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.

prototype
(source :language [:file] [:start] [:stop] [:definition] [:tab 8])
optionenginesdescription
:languagehtml latex The language of the source code.
:filehtml latex The file containing the actual source code. The file is searched in the *skribe-source-path* path.
:starthtml latex A start line number.
:stophtml latex A stop line number.
:definitionhtml latex The identifier of the definition to extract.
:tabhtml latex The tabulation width.
See also
prog language ref
Example:
(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)))

Ex. 32: A Scheme definition
Produces:
1: (define (fib x) ;*fib
2:    (if (< x 2)
3:        1
4:        (+ (fib (- x 1)) (fib (- x 2)))))

The Fibonacci function is defined line [?line fib].

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

7.3 Language

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

prototype
(language :name [:fontifier] [:extractor])
optionenginesdescription
:namehtml latex A string which denotes the name of the language.
:fontifierhtml latex A function of one argument (a string), that colorizes a line source code.
:extractorhtml latex 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
Example:
(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)) "=")
                               (ignore))))
                     ((+ (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))))
                     (else
                      ;; default
                      (let ((c (the-failure)))
                         (if (eof-object? c)
                             '()
                             (skribe-error 'makefile "Unexpected char" c)))))
                  (current-input-port)))))

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

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
Produces:
 1: SKRIBE=skribe
 2: 
 3: all: demo.html demo.man
 4: 
 5: demo.html: demo.skb
 6: 	$(SKRIBE) demo.skb -o demo.html
 7: 
 8: demo.man: demo.skb
 9: 	$(SKRIBE) demo.skb -o demo.man


This Html page has been produced by Skribe.
Last update Wed Feb 13 18:08:32 2008.