diff options
Diffstat (limited to 'doc/user/prgm.skb')
| -rw-r--r-- | doc/user/prgm.skb | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/doc/user/prgm.skb b/doc/user/prgm.skb new file mode 100644 index 0000000..c894614 --- /dev/null +++ b/doc/user/prgm.skb @@ -0,0 +1,121 @@ +;*=====================================================================*/ +;* serrano/prgm/project/skribe/doc/user/prgm.skb */ +;* ------------------------------------------------------------- */ +;* Author : Manuel Serrano */ +;* Creation : Fri Nov 30 09:21:11 2001 */ +;* Last change : Wed Sep 22 02:11:49 2004 (serrano) */ +;* Copyright : 2001-04 Manuel Serrano */ +;* ------------------------------------------------------------- */ +;* Computer programs */ +;*=====================================================================*/ + +;*---------------------------------------------------------------------*/ +;* fib ... */ +;*---------------------------------------------------------------------*/ +(define (fib x) ;!fib + (if (< x 2) + 1 + (+ (fib (- x 1)) (fib (- x 2))))) + +;*---------------------------------------------------------------------*/ +;* Computer programs */ +;*---------------------------------------------------------------------*/ +(chapter :title "Computer programs" + +(p [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 ,(emph "indentation"). This indentation is +important because it helps in understanding the text,(begin ";") +it is thus desirable to preserve it in the Skribe text. The +,(markup-ref "pre") text layout already enables such a +text formating. This chapter presents two new Skribe functions: +,(markup-ref "prog") and ,(markup-ref "source") that is specially +designed to represent computer programs in Skribe 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 "skribe-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 skribe-source-path)) +;!source-stop + +(example-produce + (example :legend "The source markup" (prgm :file "src/prgm2.skb")) + (disp (include "src/prgm2.skb")))) + +;*---------------------------------------------------------------------*/ +;* 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 + '())))) |