;*=====================================================================*/
;*    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
    '()))))