doc: Improve "Getting Started" and "Introduction".

* doc/user/{start,user}.skb: Slightly improve stuff.  Use paragraphs.

1 files changed, 81 insertions, 65 deletions

diff --git a/doc/user/start.skb b/doc/user/start.skb
index 0835b31..814ba5d 100644
--- a/doc/user/start.skb
+++ b/doc/user/start.skb
@@ -1,5 +1,6 @@
-;;; start.skb  --  Getting started with Skribe
+;;; start.skb  --  Getting started with Skribilo
 ;;;
+;;; Copyright 2007  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2003, 2004  Manuel Serrano
 ;;;
 ;;;
@@ -23,17 +24,18 @@
 ;*---------------------------------------------------------------------*/
 (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
+(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 Skribe source files can be
+by hand).  Finally, It is also presented how Skribilo 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:
+(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)
@@ -54,13 +56,14 @@ This is a very simple text.
 </BODY>
 </HTML>])
 
-In Skribe, the very same document must be written:
+In Skribilo, the very same document must be written:
 
-,(prgm :language skribe :file "src/start1.skb")])
+,(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
+(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!"))
@@ -82,15 +85,16 @@ 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:
+In Skribilo, 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.])
+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. Skribe 
+(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:])
@@ -106,27 +110,31 @@ That contains an ,(bold "itemize") construction:
   . second item
   . third item])
 
-The Skribe source for that text is:
+The Skribilo 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
+(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"))])
+,(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,
+(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 Skribe.
+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
 
-,(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
@@ -135,13 +143,13 @@ is generated with the following piece of code
 \[Document creation date: \,(date)\]
 ])
 
-Here, we use the Skribe function ,(code "date") to compute the date to
+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
-[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
+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))\]
@@ -149,10 +157,12 @@ such a computation is given below.
 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
+   (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
@@ -164,42 +174,48 @@ 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)))
-])])
+])]))
 
-,(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:
+   (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")
+(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 [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])
+(p [The execution of this code yield the following text:
+
+,(disp (include "src/start5.skb"))])))
 
-,(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 "skribe") compiler to various formats
+such as HTML, LaTeX, man and so on.  In this section we only present
+static ``document compilation''.])
 
-;*--- Compiling skribe documents --------------------------------------*/
-(section :title "Compiling Skribe documents" [
+   (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:]
 
-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.
+   (disp :verb #t [
+$ skribilo file.skb -o file.html ,(char 35) ,(it "This produces an HTML file.")
+$ skribilo file.skb -o file.tex  ,(char 35) ,(it "This produces a TeX file.")
+$ skribilo file.skb -o file.lout ,(char 35) ,(it "This produces a Lout file.")]))))
 
-,(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")])]))
+;; Local Variables:
+;; coding: latin-1
+;; comment-start: ";"
+;; comment-end: ""
+;; ispell-local-dictionary: "american"
+;; End: