;;; prgm.skb -- Computer programs ;;; -*- coding: iso-8859-1 -*- ;;; ;;; Copyright 2008 Ludovic Courtès ;;; Copyright 2001, 2002, 2003, 2004 Manuel Serrano ;;; ;;; ;;; This file is part of Skribilo. ;;; ;;; Skribilo is free software: you can redistribute it and/or modify ;;; it under the terms of the GNU General Public License as published by ;;; the Free Software Foundation, either version 3 of the License, or ;;; (at your option) any later version. ;;; ;;; Skribilo is distributed in the hope that it will be useful, ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;;; GNU General Public License for more details. ;;; ;;; You should have received a copy of the GNU General Public License ;;; along with Skribilo. If not, see . ;*---------------------------------------------------------------------*/ ;* fib ... */ ;*---------------------------------------------------------------------*/ (define (fib x) ;!fib (if (< x 2) 1 (+ (fib (- x 1)) (fib (- x 2))))) ;*---------------------------------------------------------------------*/ ;* Computer programs */ ;*---------------------------------------------------------------------*/ (chapter :title "Computer Programs" :ident "programs" (p [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 ,(emph "indentation"). Indentation is important because it helps understand the code,(begin ";") it is thus desirable to preserve indentation in program text. The ,(markup-ref "pre") text layout already allows indentation to be preserved. This chapter presents two new functions that complement it: ,(markup-ref "prog") and ,(markup-ref "source"), both of which are specially designed to represent computer programs in text.]) ;*---------------------------------------------------------------------*/ ;* Programs ... @label prog@ */ ;*---------------------------------------------------------------------*/ (section :title "Program" (p [A ,(code "prog") function call preserves the indentation of the program. It may automatically introduce line numbers.]) (doc-markup 'prog `((:line ,[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 ,(code "#f") disables the line numbering.]) (:linedigit ,[The number of digit for representing line numbers.]) (:mark ,[A string or the boolean ,(code "#f"). If this option is a string, that string is the prefix of line marks. These marks can be used in the ,(markup-ref "ref") reference. A mark identifier is defined by the regular expression: ,(code [,(char "[")_a-zA-Z,(char "]"),(char "[")_a-zA-Z0-9,(char "]")*]). The prefix and the mark are removed from the output program.])) :force-engines *api-engines* :see-also '(source pre ref)) (example-produce (example :legend "A program" (prgm :file "src/prgm1.skb")) (disp (include "src/prgm1.skb")))) ;*---------------------------------------------------------------------*/ ;* Source code ... @label source@ */ ;*---------------------------------------------------------------------*/ (section :title "Source Code" (p [The ,(code "source") function extracts part of the source code and enables ,(emph "fontification"). That is, some words of the program can be rendered using different colors or faces.]) ;!source-start (doc-markup 'source `((:language ,[The ,(markup-ref "language") of the source code.]) (:file ,[The file containing the actual source code. The file is searched in the ,(markup-ref "*source-path*") path.]) (:start [A start line number or a start marker.]) (:stop [A stop line number or a stop marker.]) (:definition [The identifier of the definition to extract.]) (:tab [The tabulation width.])) :common-args '() :force-engines *api-engines* :see-also '(prog language ref *source-path*)) ;!source-stop (linebreak) (example-produce (example :legend "The source markup" (prgm :file "src/prgm2.skb")) (disp (include "src/prgm2.skb"))) (p [Note that even awful programming languages of the C family can be highlighted!]) (linebreak) (example-produce (example :legend "The source markup for C" (prgm :file "src/prgm4.skb")) (disp (include "src/prgm4.skb"))) (p [You would highlight Java,(symbol "tm") code in a similar way, i.e., with ,(tt [:language java]).]) (mark "*source-path*") (p [Files passed as the ,(tt [:file]) argument of ,(markup-ref "source") are searched in the current ,(emph [source path]), which is defined by the ,(tt [*source-path*]) ,(srfi-ref 39) parameter. This parameter contains a list of directories and its value can be obtained using ,(code [(*source-path*)]). Its value can be altered using the ,(tt [-S]) command-line option of the ,(tt [skribilo]) compiler (see ,(numref :text [Chapter] :ident "compiler") for details).]) (p [The ,(param :language) parameter of ,(markup-ref "source") takes a ,(tt [language]) object, which performs the actual source highlighting. Several programming languages are currently supported: the ,(tt [(skribilo source lisp)]) module provides ,(tt [skribe]), ,(tt [scheme]), ,(tt [stklos]), ,(tt [bigloo]) and ,(tt [lisp]), which implement source highlighting for the corresponding lispy dialects, while the ,(tt [(skribilo source c)]) module provides ,(tt [c]) and ,(tt [java]). Thus, you need to import the relevant module to get the right language, for instance by adding ,(code [(use-modules (skribilo source c))]) at the beginning of your document. Additional languages can be created using the ,(markup-ref "language") function (see below).])) ;*---------------------------------------------------------------------*/ ;* Language ... @label language@ */ ;*---------------------------------------------------------------------*/ (section :title "Language" (index "source" :note "fontification") (index "fontification") (p [The ,(code "language") function builds a language that can be used in ,(markup-ref "source") function call.]) (doc-markup 'language `((:name [A string which denotes the name of the language.]) (:fontifier [A function of one argument (a string), that colorizes a line source code.]) (:extractor [A function of three arguments: an input port, an identifier, a tabulation size. This function ,(emph "scans") in the input port the definition is looks for.])) :common-args '() :force-engines *api-engines* :see-also '(prog source ref)) ; **** FIXME: (cond-expand (bigloo (example-produce (example :legend "An ad-hoc fontification" (prgm :file "src/prgm3.skb")) (disp (include "src/prgm3.skb")))) (else '())))) ;;; Local Variables: ;;; ispell-local-dictionary: "american" ;;; End: