;*=====================================================================*/
;* 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 [
Hello world Example
Hello World!
This is a very simple text.
])
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 [
Hello world Example
Hello World!
This is a very simple text.
])
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.info ,(char 35) ,(it "This produces an info page.")
$ skribe file.skb -o file.mgp ,(char 35) ,(it "This produces a MagicPoint document")])]))