;;; prgm.skb -- Computer programs
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2008 Ludovic Courtès <ludo@gnu.org>
;;; 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 <http://www.gnu.org/licenses/>.
;*---------------------------------------------------------------------*/
;* 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:
