summaryrefslogtreecommitdiff
path: root/skribe/doc/user/start.skb
blob: f3c1e285e0f81b4f58788957d20ab406d37f666d (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
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
;*=====================================================================*/
;*    serrano/prgm/project/skribe/doc/user/start.skb                   */
;*    -------------------------------------------------------------    */
;*    Author      :  Manuel Serrano                                    */
;*    Creation    :  Mon Sep  1 11:22:25 2003                          */
;*    Last change :  Sun Feb 29 16:14:21 2004 (eg)                     */
;*    Copyright   :  2003-04 Manuel Serrano                            */
;*    -------------------------------------------------------------    */
;*    Getting started with Skribe                                      */
;*=====================================================================*/

;*---------------------------------------------------------------------*/
;*    Getting started                                                  */
;*---------------------------------------------------------------------*/
(chapter :title "Getting Started"

(p [
In this chapter, the syntax of a Skribe text is presented ,(emph "informally").
In particular, the Skribe syntax is compared to the HTML syntax. Then,
it is presented how one can use Skribe 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 Skribe source files can be processed.])

;*--- Hello world -----------------------------------------------------*/
(section :title "Hello World!" [
In this section we show how to produce very simple electronic documents
with Skribe. 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 Skribe, the very same document must be written:

,(prgm :language skribe :file "src/start1.skb")])

;*--- Adding colors and fonts -----------------------------------------*/
(section :title "Adding colors and fonts" [
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 Skribe, the very same document must be written:

,(prgm :language skribe (source :file "src/start2.skb"))

As one may notice the Skribe 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. Skribe 
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 Skribe source for that text is:

,(prgm :language skribe (source :file "src/start3.skb"))])

;*--- Hyperlinks ------------------------------------------------------*/
(section :title "Hyperlinks" [
A Skribe document may contain links to chapters, to sections, to other
Skribe documents or Web pages. The following Skribe source
code illustrates these various kinds of links:

,(prgm :language skribe (source :file "src/start4.skb"))])

;*--- Dynamic documents -----------------------------------------------*/
(section :title "Dynamic documents" [
Since Skribe 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 Skribe.

,(subsection :title "Simple computations" [
In this section we present how to introduce a simple computation into a
document. For instance, the following sentence
,(disp [
Document creation date: ,(date)])
is generated with the following piece of code

,(prgm :language skribe [
\[Document creation date: \,(date)\]
])

Here, we use the Skribe 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
[Skribe can be built either with Bigloo or STklos Scheme systems. The Scheme
expressions which are valid inside a ,(code ",(...)") depends of the Scheme system
used at Skribe construction.]).
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" [ When building a document, one
often need to generate some repetitive text. Skribe 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" [
In Skribe, 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")

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 skribe documents --------------------------------------*/
(section :title "Compiling Skribe documents" [

There are several ways to render a Skribe document. It can be statically
compiled by the ,(tt "skribe") compiler to various formats such as HTML,
LaTeX, man and so on. It can be compiled on-demand by the ,(tt "mod_skribe")
,(ref :url "http://www.apache.org/" :text "Apache") Skribe module. In this
section we only present static compilation.

,(p [Let us suppose a Skribe text located in a file ,(tt "file.skb").
In order to compile to various formats one must type in:])

,(disp :verb #t [
$ skribe file.skb -o file.html ,(char 35) ,(it "This produces an HTML file.")
$ skribe file.skb -o file.tex  ,(char 35) ,(it "This produces a TeX file.")
$ skribe file.skb -o file.man  ,(char 35) ,(it "This produces a man page.")
$ skribe file.skb -o file.info ,(char 35) ,(it "This produces an info page.")
$ skribe file.skb -o file.mgp  ,(char 35) ,(it "This produces a MagicPoint document")])]))