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

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

2 files changed, 113 insertions, 89 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:
diff --git a/doc/user/user.skb b/doc/user/user.skb
index 588b6f6..38ea61c 100644
--- a/doc/user/user.skb
+++ b/doc/user/user.skb
@@ -20,7 +20,7 @@
 ;;; USA.
 
 ;*---------------------------------------------------------------------*/
-;*    The Skribe documentation style                                   */
+;*    The Skribilo documentation style                                   */
 ;*---------------------------------------------------------------------*/
 (use-modules (skribilo package web-book)
              (skribilo documentation env)
@@ -76,33 +76,40 @@ If you are new to Skribilo, please read the ,(ref :ident "intro"
 
 
 ;;; Introduction
-(chapter :title "Introduction" :ident "intro" :number #f :toc #t :file #f [
-Skribe is a programming language designed for implementing electronic
-documents. It is mainly designed for the writing of technical documents
-such as the documentation of computer programs. With Skribe these
-documents can be rendered using various tools and technologies. For
-instance, a Skribe document can be ,(emph "compiled") to an HTML file
-that suits Web browser, it can be compiled to a TeX file in order to
-produce a high-quality printed document, and so on.]
+(chapter :title "Introduction" :ident "intro" :number #f :toc #t :file #f
+
+   (p [Skribilo is a document production toolkit and a programming
+language designed for implementing electronic documents,(footnote [To be
+more precise, the programming language itself is that of ,(ref :text
+[Skribe] :url "http://www-sop.inria.fr/mimosa/fp/Skribe/"), the project
+Skribilo is based on.]).  It is mainly designed for the writing of
+technical documents such as the documentation of computer programs.
+With Skribilo these documents can be rendered using various tools and
+technologies.  For instance, a Skribilo document can be ,(emph
+"compiled") to an HTML file that suits Web browser, it can be compiled
+to a TeX file in order to produce a high-quality printed document, and
+so on.])
    
-   (section :title "Who may use Skribe?" :number #f [
-Everyone needing to design web pages, info documents, man pages or
-Postscript files can use Skribe. In particular, there is ,(bold "no need")
-for programming skills in order to use Skribe. Skribe can be used as
-any text description languages such as ,(ref :text [LaTeX] :url
+   (section :title "Who May Use Skribilo?" :number #f
+      
+      (p [Anyone needing to design web pages, PostScript/PDF files or
+Info documents can use Skribilo.  In particular, there is ,(emph "no
+need") for programming skills in order to use Skribilo.  Skribilo can be
+used as any text description languages such as ,(ref :text [LaTeX] :url
 "http://latex-project.org/"), ,(ref :text [Lout] :url
-"http://lout.sf.net/") or HTML.])
-   
-   (section :title "Why using Skribe?" :number #f [
-There are three main reasons for using Skribe:]
+"http://lout.sf.net/") or HTML.]))
+
+   (section :title "Why Use Skribilo?" :number #f
+      
+      (p [There are three main reasons for using Skribilo:]
       
       (itemize
 	 (item [
-It is easier to type in Skribe texts than other text description formats.
+It is easier to type in Skribilo texts than other text description formats.
 The need for ,(emph "meta keyword"), that is, words used to describe
 the structure of the text and not the text itself, is very limited.])
 	 (item [
-Skribe is highly skilled for computing texts. It is very common that
+Skribilo is highly skilled for computing texts. It is very common that
 one needs to automatically produce parts of the text. This can
 be very simple such as, for instance, the need to include inside a text,
 the date of the last update or the number of the last revision.
@@ -110,11 +117,11 @@ Sometimes it may be more complex. For instance, one may be willing to
 embed inside a text the result of a complex arithmetic computation. Or
 even, you may want to include some statistics about that
 text, such as, the number of words, paragraphs, sections, and so on.
-Skribe makes these sort of text manipulation easy whereas other
+Skribilo makes these sort of text manipulation easy whereas other
 systems rely on the use of text preprocessors.])
 	 (item [
 The same source file can be compiled to various output formats such
-as HTML, Info pages, man pages, Postscript, etc.]))))
+as HTML, PostScript, Info pages, etc.])))))
 
 ;;; toc
 (if (engine-format? "latex")
@@ -126,7 +133,7 @@ as HTML, Info pages, man pages, Postscript, etc.]))))
 ;;; Syntax
 (include "syntax.skb")
 
-;;; Skribe Markup Library
+;;; Skribilo Markup Library
 (include "markup.skb")
 
 ;;; Hyperlinks and references
@@ -156,7 +163,7 @@ as HTML, Info pages, man pages, Postscript, etc.]))))
 ;;; Emacs
 (include "emacs.skb")
 
-;;; Skribe
+;;; Skribilo
 (include "skribec.skb")
 
 ;;; Slides
@@ -191,4 +198,5 @@ as HTML, Info pages, man pages, Postscript, etc.]))))
 ;; coding: latin-1
 ;; comment-start: ";"
 ;; comment-end: ""
+;; ispell-local-dictionary: "american"
 ;; End: