diff options
Diffstat (limited to 'doc/user/start.skb')
| -rw-r--r-- | doc/user/start.skb | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/doc/user/start.skb b/doc/user/start.skb new file mode 100644 index 0000000..f3c1e28 --- /dev/null +++ b/doc/user/start.skb @@ -0,0 +1,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")])])) |