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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
;;; start.skb -- Getting started with Skribilo
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2007, 2008, 2009, 2012 Ludovic Court�s <ludo@gnu.org>
;;; Copyright 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/>.
;*---------------------------------------------------------------------*/
;* Getting started */
;*---------------------------------------------------------------------*/
(chapter :title "Getting Started"
(p [In this chapter, the syntax of a Skribilo text is presented ,(emph
"informally"). In particular, the Skribilo syntax is compared to the HTML
syntax. Then, it is presented how one can use Skribilo to make dynamic
text (i.e texts which are generated by the system rather than entered-in
by hand). Finally, It is also presented how Skribilo source files can be
processed.])
;*--- Hello world -----------------------------------------------------*/
(section :title "Hello World!"
(p [In this section we show how to produce very simple electronic documents
with Skribilo. Suppose that we want to produce the following Web document:
,(disp [,(font :size 2. (bold "Hello World!"))
,(linebreak 2)
This is a very simple text.])
The HTML source file for such a page should look like:
,(prgm :language xml [
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Hello World Example</TITLE>
</HEAD>
<BODY>
<H1>Hello World!</H1>
This is a very simple text.
</BODY>
</HTML>])
In Skribilo, the very same document must be written:
,(prgm :language skribe :file "src/start1.skb")]))
;*--- Adding colors and fonts -----------------------------------------*/
(section :title "Adding Colors and Fonts"
(p [Let us suppose that we want now to colorize and change the face of some
words such as:
,(disp [,(font :size 2. (bold "Hello World!"))
,(linebreak 2)
This is a ,(bold "very") ,(it "simple") ,(color :fg "red" "text").])
The HTML source file for such a document should look like:
,(prgm :language xml [
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Hello World Example</TITLE>
</HEAD>
<BODY>
<H1>Hello World!</H1>
This is a <B>very</B> <I>simple</I> <FONT color="red">text</FONT>.
</BODY>
</HTML>])
In Skribilo, the very same document must be written:
,(prgm :language skribe (source :file "src/start2.skb"))
As one may notice the Skribilo version is much more compact than the HTML one.]))
;*--- Structured documents --------------------------------------------*/
(section :title "Structured Documents" [
,(p [For large documents there is an obvious need of structure. Skribilo
documents may contain ,(bold "chapters"), ,(bold "sections"),
,(bold "subsections"), ,(bold "itemize"), ... For instance, if we want to
extend our previous example to:])
,(disp :verb #t [,(bold (font :size 2. "Hello World!"))
,(font :size 1. (bold "1. A first Section"))
This is a ,(bold "very") ,(it "simple") ,(color :fg "red" "text").
,(font :size 1. (bold "2. A second Section"))
That contains an ,(bold "itemize") construction:
. first item
. second item
. third item])
The Skribilo source for that text is:
,(prgm :language skribe (source :file "src/start3.skb"))])
;*--- Hyperlinks ------------------------------------------------------*/
(section :title "Hyperlinks"
(p [A Skribilo document may contain links to chapters, to sections, to other
Skribilo documents or web pages. The following Skribilo source
code illustrates these various kinds of links:
,(prgm :language skribe (source :file "src/start4.skb"))]))
;*--- Modules ---------------------------------------------------------*/
(section :title "Using Modules" :info-node "Modules" :ident "modules"
(index :index *function-index* "use-modules")
(p [Skribilo comes with extra features bundled in ,(emph [modules]).
In fact, anyone can write new modules that extend Skribilo. For example, extra ,(ref :ident
"biblio" :text [bibliography features]) are bundled in a module called
,(code [(skribilo biblio)]). To use them in a document, that document
the following line must be added at the very beginning of the document,
before the ,(markup-ref "document") markup:
,(prgm :language skribe (source [(use-modules (skribilo biblio))]))
Suppose you also want to use the ,(ref :ident "equations" :text
[mathematical formula layout package]), which is bundled in the ,(code
[(skribilo package eq)]) module. To do that, you can either add another
,(code [use-modules]) form at the top of the document, or combine both:
,(prgm :language skribe (source [
(use-modules (skribilo biblio)
(skribilo package eq))]))])
(p [The module system described above is actually that of ,(ref :text
[GNU Guile] :url "http://www.gnu.org/software/guile/"). More
information is available in Guile's manual.]))
;*--- Dynamic documents -----------------------------------------------*/
(section :title "Dynamic Documents"
(p [Since Skribilo is a programming language, rather than just a markup language,
it is easy to use it to generate some parts of a document. This section
presents here the kind of documents that can be created with Skribilo.])
(subsection :title "Simple Computations"
(p [In this section we present how to introduce a simple
computation into a document. For instance, the following sentence
,(disp [Document creation date: ,(date->string (current-date))])
is generated with the following piece of code (using ,(srfi-ref 19)):
,(prgm :language skribe [
\[Document creation date: \,(date->string (current-date))\]
])
Here, we use the Skribilo function ,(code "date") to compute the date to
be inserted in the document. In general, any valid Scheme expression
is authorized inside a ,(code ",(...)") construct,(footnote
[Any valid GNU Guile Scheme code may be used inside ,(code ",(...)")
expressions!]).])
(p [Another example of
such a computation is given below.
,(prgm :language skribe [
\[The value of \,(symbol "pi") is \,(* 4 (atan 1))\]
])
When evaluated, this form produces the following output:
,(disp [
The value of ,(symbol "pi") is ,(* 4 (atan 1)).])
]))
(subsection :title "Text Generation"
(p [When building a document, one
often need to generate some repetitive text. Skribilo programming skills
can be used to ease the construction of such documents as illustrated below.
,(disp
(itemize
(map (lambda (x)
(item [The square of ,(bold x) is ,(bold (* x x))]))
'(1 2 3 4 5 6 7 8 9))))
This text has been generated with the following piece of code
,(prgm :language skribe [
(itemize
(map (lambda (x)
(item \[The square of \,(bold x) is \,(bold (* x x))\]))
'(1 2 3 4 5 6 7 8 9)))
])]))
(subsection :title "Introspection"
(p [In Skribilo, a document is represented by a tree which is
available to the user. So, it is easy to perform introspective tasks on
the current document. For instance the following code displays as an
enumeration the sections titles of the current chapter:])
(prgm :language skribe :file "src/start5.skb")
(p [Without entering too much into the details here, the resolve
function is called at the end of the document processing. This function
searches the node representing the chapter to which belongs the current
node and from it finds all its sections. The titles of these sections
are put in italics in an itemize.])
(p [The execution of this code yield the following text:
,(disp (include "src/start5.skb"))])))
;*--- Compiling documents --------------------------------------*/
(section :title "Compiling Skribilo Documents"
(p [There are several ways to render a Skribilo document. It can be
statically compiled by the ,(tt "skribilo") compiler to various formats
such as HTML, LaTeX, Lout and so on. In this section we only present
static ``document compilation''.])
(p [Let us suppose a Skribilo text located in a file ,(tt "file.skb").
In order to compile to various formats one must type in:]
(disp :verb #t [
$ skribilo --target=html file.skb -o file.html ,(char 35) ,(it "This produces an HTML file.")
$ skribilo -t latex file.skb -o file.tex ,(char 35) ,(it "This produces a TeX file.")
$ skribilo -t lout file.skb -o file.lout ,(char 35) ,(it "This produces a Lout file.")])
[The reference of the ,(tt [skribilo]) compiler is given in
,(numref :text [Chapter] :ident "compiler").])))
;; Local Variables:
;; comment-start: ";"
;; comment-end: ""
;; ispell-local-dictionary: "american"
;; End:
|
