Skribe User Manual

In this chapter, the syntax of a Skribe text is presented 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.

1.1 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:

Hello World!

This is a very simple text.

The HTML source file for such a page should look like:

<!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:

(document :title [Hello World!] [
This is a very simple text.])

1.2 Adding colors and fonts

Let us suppose that we want now to colorize and change the face of some words such as:

Hello World!

This is a very simple text.

The HTML source file for such a document should look like:

<!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:

(document :title [Hello World!] [
This is a ,(bold [very]) ,(it [simple]) ,(color :fg [red] [text]).])

As one may notice the Skribe version is much more compact than the HTML one.

1.3 Structured documents

For large documents there is an obvious need of structure. Skribe documents may contain chapters, sections, subsections, itemize, ... For instance, if we want to extend our previous example to:

Hello World!

1. A first Section
This is a very simple text.

2. A second Section
That contains an itemize construction:
  . first item
  . second item
  . third item

The Skribe source for that text is:

(document :title [Hello World!] 

(section :title [A first Section] [
 This is a ,(bold [very]) ,(it [simple]) ,(color :fg [red] [text]).])

(section :title [A second Section] [
 That section contains an ,(bold itemize) construction:
 ,(itemize (item [first item])
           (item [second item])
           (item [third item]))]))

1.4 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:

(document :title [Various links] [

(section :title "A Section" [
The first link points to an external web page. Here we point to a
,(ref :url [http://slashdot.org/] [Slashdot])
web page. The second one points to the second
,(ref :section [A second Section] [Section])
of that document.])

(section :title [A second Section] [
The last links points to the first
,(ref :scribe [user.scr] :figure [A simple web page] [Figure])
of the Scribe User Manual.])])

1.5 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.

1.5.1 Simple computations

In this section we present how to introduce a simple computation into a document. For instance, the following sentence

Document creation date: Tue Jun 29 09:37:13 2010

is generated with the following piece of code

[Document creation date: ,(date)]

Here, we use the Skribe function date to compute the date to be inserted in the document. In general, any valid Scheme expression is authorized inside a ,(...) construct.¹. Another example of such a computation is given below.

[The value of ,(symbol "pi") is ,(* 4 (atan 1))]

When evaluated, this form produces the following output:

The value of π is 3.1415926535898.

1.5.2 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.

The square of 1 is 1
The square of 2 is 4
The square of 3 is 9
The square of 4 is 16
The square of 5 is 25
The square of 6 is 36
The square of 7 is 49
The square of 8 is 64
The square of 9 is 81

This text has been generated with the following piece of code

(itemize
 (map (lambda (x) (item [The square of ,(bold x) is ,(bold (* x x))]))
      '(1 2 3 4 5 6 7 8 9)))

1.5.3 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:

(resolve (lambda (n e env)
            (let* ((current-chapter (ast-chapter n))
                   (body  (markup-body current-chapter))
                   (sects (filter (lambda (x) (is-markup? x 'section))
                                  body)))
               (itemize 
                (map (lambda (x)
                        (item (it (markup-option x :title))))
                     sects)))))

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.

The execution of this code yield the following text

Hello World!
Adding colors and fonts
Structured documents
Hyperlinks
Dynamic documents
Compiling Skribe documents

1.6 Compiling Skribe documents

There are several ways to render a Skribe document. It can be statically compiled by the skribe compiler to various formats such as HTML, LaTeX, man and so on. It can be compiled on-demand by the mod_skribe Apache Skribe module. In this section we only present static compilation.

Let us suppose a Skribe text located in a file file.skb. In order to compile to various formats one must type in:

$ skribe file.skb -o file.html # This produces an HTML file.
$ skribe file.skb -o file.tex  # This produces a TeX file.
$ skribe file.skb -o file.man  # This produces a man page.
$ skribe file.skb -o file.info # This produces an info page.
$ skribe file.skb -o file.mgp  # This produces a MagicPoint document

¹: Skribe can be built either with Bigloo or STklos Scheme systems. The Scheme expressions which are valid inside a ,(...) depends of the Scheme system used at Skribe construction.