summaryrefslogtreecommitdiff
path: root/doc/user/lib.skb
blob: 3a35687727efb92e53d7276a1c7487ca1eeb2d9a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
;;;;
;;;; Standard Library
;;;;
;;;;
;;;;           Author: Erick Gallesio [eg@essi.fr]
;;;;    Creation date: 21-Nov-2003 07:20 (eg)
;;;; Last file update: 21-Nov-2003 10:17 (eg)


(chapter :title "Standard Library" 

   (p [This section describes the Skribe standard library])

;;;
(section :title "File functions"
   
   (p [The function ,(code "include") is particularily useful to spread a
long document amongst several files.])
   
   (doc-markup 'include
	       '((file [The file containing the nodes to be included. 
These nodes are included in the document in place of the ,(code "include") 
call.]))
	       :common-args '()
	       :see-also '(skribe-load skribe-path skribe-path-set!)
	       :idx *function-index*)
   
   (p [The given file is searched in the current 
,(ref :mark "skribe-path" :text "Skribe path")])
   
   (p [The function ,(code "skribe-load") is generally used to load in the
Skribe memory, a package or an extension. In general the prelude of a 
Skribe document (the expressions placed before the ,(markup-ref "document")
call) contains several ,(code "skribe-load"). The file is search
in the ,(ref :mark "skribe-path" :text "Skribe path").])
   
   (doc-markup 'load-document
	       `((file [The file containing the expressions to be loaded.])
		 (:engine [The engine used to evaluate the expressions.])
		 (:path ,[The optional path where to find the file. The default
                          path is ,(markup-ref "skribe-path").])
		 (#!rest opt... [Additional user options.]))
               ;;:skribe-source? #f
	       ;;:source "skribilo/evaluator.scm"
               :source #f
      	       :def '(define (load-document file #!rest opt #!key engine path) ...)
	       :common-args '()
	       :see-also '(skribe-load-options skribe-path skribe-path-set!)
	       :idx *function-index*)
   
   (p [Returns the user of options of the last call to 
,(markup-ref "skribe-load")])
   (doc-markup '*load-options*
	       '()
               :skribe-source? #f-
	       ;;:source "skribilo/evaluator.scm"
               :source #f
               :def '(define (*load-options* #!optional opt) ...)
	       :common-args '()
	       :see-also '(load-document)
	       :idx *function-index*)
   
   (p [Skribe provides functions for dealing with paths. These functions
are related to the path that can be specified on the command line,
when the Skribe compiler is invoked (see Chapter 
,(ref :chapter "Skribe compiler").)])
   
   (doc-markup '*document-path*
	       '()
               ;;:skribe-source? #f
	       ;;:source "skribilo/parameters.scm"
               :source #f
               :def '(define (*document-path* #!optional opt) ...)
	       :common-args '()
	       :others '()  ;;'(*image-path* *bib-path* *source-path*)
	       :see-also '(include-document load-document image source
bibliography)
	       :idx *function-index*)
   
   (p [,(tt [*document-path*]) is a procedure as returned by SRFI-39
,(tt [make-parameter]).  As such, ,(tt [(*document-path*)]) returns the
current document path, while ,(tt [(*document-path* '("."
"/some/path"))]) changes the value of the current path.  An equivalent
way to achieve this is by using ,(tt [skribe-path-set!]):])

   (doc-markup 'skribe-path-set!
	       '((path [A list of strings which is the new Skribe search path.]))
               :skribe-source? #f
	       :source "skribilo/utils/compat.scm"
	       :common-args '()
	       :others '()
	       :see-also '(*document-path*)
	       :idx *function-index*))
   
;;; Misc   
(section :title "Misc. Functions"
   
   (p [The function ,(code "skribe-release") returns the Skribe version 
as a string])
   (doc-markup 'skribe-release
	       '()
	       :common-args '()
	       :source #f
	       :def '(define (skribe-release) ...)
	       :idx *function-index*)
   
   (p [For instance, the following piece of code:])
   (prgm :language skribe 
	 "[This manual documents the ,(bold (skribe-release)) Skribe release]")
   (p [produces the following output])
   (disp [This manual documents the ,(bold (skribe-release)) Skribe release]))
   
   (p [The function ,(code "skribe-configure") accesses the whole
Skribe configuration. It can be used to ,(emph "get") or ,(emph "check")
the configuration.])
   
   (doc-markup 'skribe-configure
	       '((#!rest opt... [Optional arguments.]))
	       :common-args '()
	       :source #f
	       :def '(define (skribe-configure #!rest opt...) ...)
	       :idx *function-index*)
   
   (p [The function ,(code "skribe-configure") can be used in three distinct 
ways depending on the number of provided arguments:])
   
   (enumerate
      (item [If no argument is provided, ,(code "skribe-configure") returns 
a fresh list of Skribe configuration.])
      (item [If one keyword argument is provided, ,(code "skribe-configure") 
returns the value associated with this keyword in the configuration list. 
If this value does not exist, it returns the symbol ,(code "void").])
      (item [(code "skribe-configure") is invoked with a list composed 
of ,(emph "keyword") ,(emph "value"). The actual configuration is checked 
against the provided values. Values are compared with ,(code "equal") except 
if the value to check has to be compared with a procedure. In that particular 
case the value of the check is the value produces by ,(emph "applying") the 
function to the actual value. The result of ,(code "skribe-configure") is a 
boolean.]))
   
   (p [Here are some examples.])
   (prgm :language skribe [
;; fetch the whole configuration list
(skribe-configure) 

;; fetch the release number
(skribe-configure :release) 

;; test if the release number is 1.0b
(skribe-configure :release "1.0b") 

;; test if the release number is greater or equal than "1.0b"
(skribe-configure :release (lambda (v) (string>=? v "1.0b")))

;; test if the release number is greater or equal than "1.0b"
;; and the implementation is bigloo
(skribe-configure :release (lambda (v) (string>=? v "1.0b")) :scheme "bigloo")])
   
   (p [The function ,(code "skribe-enforce-configure") checks for the Skribe
configuration. In case of mismatch, it raises an error. The syntax of the
arguments if the same as that of ,(code "skribe-configure") when invoked
with several arguments.])
   
   (doc-markup 'skribe-enforce-configure
	       '((#!rest opt... [Optional arguments.]))
	       :common-args '()
	       :source #f
	       :def '(define (skribe-enforce-configure #!rest opt...) ...)
	       :idx *function-index*))