doc: Various insignificant cleanups.

8 files changed, 147 insertions, 100 deletions

diff --git a/doc/modules/skribilo/documentation/env.scm b/doc/modules/skribilo/documentation/env.scm
index da4915a..e49898c 100644
--- a/doc/modules/skribilo/documentation/env.scm
+++ b/doc/modules/skribilo/documentation/env.scm
@@ -33,6 +33,7 @@
 (define-public *texinfo-url* "http://www.texinfo.org")
 (define-public *r5rs-url* "http://www.inria.fr/mimosa/fp/Bigloo/doc/r5rs.html")
 (define-public *bigloo-url* "http://www.inria.fr/mimosa/fp/Bigloo")
+(define-public *skribe-url* "http://www.inria.fr/mimosa/fp/Skribe")
 
 (define-public *skribe-user-doc-url*
   (string-append (skribilo-doc-directory) "/user.html"))
diff --git a/doc/user/bib.skb b/doc/user/bib.skb
index c92f89e..b40015a 100644
--- a/doc/user/bib.skb
+++ b/doc/user/bib.skb
@@ -19,16 +19,15 @@
 ;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
 ;;; USA.
 
-(bibliography "src/bib1.sbib")
-
 ;*---------------------------------------------------------------------*/
 ;*    Index                                                            */
 ;*---------------------------------------------------------------------*/
 (chapter :title "Bibliographies"
 
-   (p [
-Skribe supports bibliographies. In order to use bibliography
-,(markup-ref "ref") it is needed to:])
+   (p [Skribilo provides support for bibliographies.  To setup a
+bibliography database and to be able to refer to its entries from a
+document, the following things must be done:]
+
    (itemize 
       (item [
 Use the default pre-existing ,(emph "bibliography table") or create a 
@@ -36,20 +35,22 @@ custom one.])
       (item [
 Provide a ,(emph "bibliography database").])
       (item [
-Load the database by the mean of the ,(markup-ref "bibliography") 
-Skribe function call.])
+Load the database using the ,(markup-ref "bibliography") function.])
       (item [
-Reference to a bibliography entry, with a ,(markup-ref "ref") Skribe 
-function call.]))
+Reference to bibliography entries with ,(code [,(markup-ref "ref")
+,(param [:bib])]) function calls.]))
+   
+   [The following sections will guide you through these steps.])
+
 
 ;*---------------------------------------------------------------------*/
 ;*    Bibliography tables                                              */
 ;*---------------------------------------------------------------------*/
-(section :title "Bibliography tables"
+(section :title "Bibliography Tables"
    
-   (p [
-This section describes the function of using and creating bibliography 
-tables.])
+   (p [This section describes functions dealing with ,(emph
+[bibliography tables]).  Essentially, bibliography tables are the
+representation of your bibliographies used by Skribilo at run-time.])
    
    (p [The predicate ,(code "bib-table?") returns ,(code "#t") if and only
 if its argument is a bibliography table as returned by 
@@ -92,15 +93,15 @@ bibliography-table:])
 ;*---------------------------------------------------------------------*/
 (section :title "Bibliography"
 
-(p [The function ,(code "bibliography") loads bibliography ,(param 'entries) 
-into the Skribe memory. An ,(emph "entry") is either a list
-representing one entry (such as an article or book reference) or a
-string which denotes a file name that contains several
-entries. All the entries loaded in memory are available for the function
-,(ref :ident "ref" :text "references"). A bibliography database must be loaded
-,(emph "before") any reference is introduced. It is advised to place
-the ,(code "bibliography") Skribe function call before the call to the
-,(markup-ref "document") function call.])
+(p [The ,(markup-ref "bibliography") function loads bibliography entries
+into the bibliography table specified using the ,(param :bib-table)
+parameter.  It can be passed either lists representing entries (such as
+an article or book reference), or strings denoting the names of files
+that contains several entries.  All the entries loaded in memory can
+then be referred to with ,(markup-ref "ref").  A bibliography database
+must be loaded ,(emph "before") any reference is introduced.  It is
+advised to place the ,(markup-ref "bibliography") function call before
+the call to the ,(markup-ref "document") function call.])
 
 (doc-markup 'bibliography
 	    `((:command ,[An external command to be applied when loading
@@ -126,9 +127,9 @@ contains a list of directories and its value can be obtained using
 [-B]) command-line option of the ,(tt [skribilo]) compiler (see ,(numref
 :text [Chapter] :ident "compiler") for details).])
 
-(p [The ,(param :command) option can be used to import foreign bibliography.
-The following example, shows how to directly use a Bibtex bibliography
-using the ,(ref :section "Skribebibtex") translator.])
+(p [The ,(param :command) option can be used to import foreign
+bibliography.  The following example, shows how to directly use a BibTeX
+bibliography using the ,(ref :section "Skribebibtex") translator.])
 
 (example-produce 
  (example :legend "Printing a Bibliography" (prgm :file "src/bib6.skb")))
@@ -137,9 +138,9 @@ using the ,(ref :section "Skribebibtex") translator.])
 ;; bibliography syntax
 (subsection :title "Bibliography Syntax"
 
-(p [The Skribe bibliography database uses a format very close to
-the Bibtex one. It is a parenthetic version of Bibtex. Here is the
-syntax of an entry:])
+(p [The Skribe/Skribilo bibliography database uses a format very close
+to the BibTeX one, which is a parenthetic version of BibTeX.  Here is
+the syntax of an entry:])
 
 (disp :verb #t :bg *prgm-skribe-color* [
 <entry>  -->  ,(bold "(")<kind> <key> <field>+,(bold ")")
@@ -147,10 +148,10 @@ syntax of an entry:])
 <key>    -->  <symbol> | <string>
 <field>  -->  ,(bold "(")<symbol> <string>,(bold ")")])
 
-(p [Bibtex files cannot be directly loaded in Skribe but the tool
-,(ref :section "Skribebibtex" :text (tt "skribebibtex")) can be use to
-automatically convert Bibtex format to Skribe bibliography format.
-Here is an example of a simple Skribe database.])
+(p [BibTeX files cannot be directly loaded but the tool ,(ref :section
+"Skribebibtex" :text (tt "skribebibtex")) can be use to automatically
+convert BibTeX format to Skribe bibliography format.  Here is an example
+of a simple Skribe database.])
 
 (prgm :file "src/bib1.sbib")))
 
@@ -295,12 +296,18 @@ conventions as for the ,(code "name+year") label style of ,(ref :ident
 
 ;*---------------------------------------------------------------------*/
 ;*    skribebibtex                                                     */
+;*    FIXME: Uncomment section below when we have a replacement.       */
 ;*---------------------------------------------------------------------*/
 (section :title "Skribebibtex"
+   
+   (p [FIXME: This tool is not available as of Skribilo version
+,(skribilo-version).]))
+
+#;(section :title "Skribebibtex"
 (index "skribebibtex" :note "manual page")
-(index "bibtex")
+(index "BibTeX")
 (p [
-In this section we present the Skribebibtex translator that compiles Bibtex
+In this section we present the Skribebibtex translator that compiles BibTeX
 source files into a Skribe bibliography.])
 
 ;; Synopsis (FIXME)
@@ -311,7 +318,7 @@ source files into a Skribe bibliography.])
 (subsection :title "DESCRIPTION" :number #f [
 This manual page is not meant to be exhaustive. It
 documents the ,(tt "skribebibtex"), a tool that translates
-,(bold "Bibtex") files into ,(it "Skribe"), bibliography format. These 
+,(bold "BibTeX") files into ,(it "Skribe"), bibliography format. These 
 files can be used by the ,(bold "skribe") compiler to produce  
 bibliography entries.])
 
@@ -321,7 +328,7 @@ The ,(ref :chapter "Skribilo Compiler" :text "skribilo") compiler uses file
 suffixes in order to select amongst its possible targets which to choose. 
 These suffixes are:
 
-,(description (item :key (it ".bib") [a ,(bold "Bibtex") source file.]))])
+,(description (item :key (it ".bib") [a ,(bold "BibTeX") source file.]))])
 
 ;; Options (FIXME)
 ;;(subsection :title "OPTIONS" :number #f 
@@ -329,3 +336,7 @@ These suffixes are:
 
    ))
 
+;;; Local Variables:
+;;; coding: latin-1
+;;; ispell-local-dictionary: "american"
+;;; End:
diff --git a/doc/user/compiler.skb b/doc/user/compiler.skb
index cde7331..572bcef 100644
--- a/doc/user/compiler.skb
+++ b/doc/user/compiler.skb
@@ -82,10 +82,9 @@ the output format.  For details on engines and for a list of supported
 engines, see ,(numref :text [Chapter] :ident "engines").])
 	`("compat" "compat" ,[Use ,(tt "compat") as the compatibility
 mode.  This defaults to ,(tt [skribilo]).  Specifying ,(tt [skribe])
-enables the ,(ref :text [Skribe] :url
-"http://www-sop.inria.fr/mimosa/fp/Skribe/") compatibility mode, making
-it possible to compile most Skribe documents.  Technically, the ,(tt
-[skribe]) compatibility mode populates the name space of Skribilo
+enables the ,(ref :text [Skribe] :url *skribe-url*) compatibility mode,
+making it possible to compile most Skribe documents.  Technically, the
+,(tt [skribe]) compatibility mode populates the name space of Skribilo
 documents with bindings available to Skribe documents and that are not
 available by default to Skribilo documents,(footnote [Skribe uses a
 single name space for all the code of packages, documents, in addition
diff --git a/doc/user/emacs.skb b/doc/user/emacs.skb
index 3a9c01c..0d531e5 100644
--- a/doc/user/emacs.skb
+++ b/doc/user/emacs.skb
@@ -57,9 +57,8 @@ present the two most important key bindings specific to this mode:
 expression.]))])
 
 (p [In order to install the Skribe Emacs mode, you first need to install
-,(ref :text [Bigloo's development environment] :url
-"http://www-sop.inria.fr/mimosa/fp/Bigloo/") called ``UDE'' (on
-Debian-based systems, it boils down to ,(tt [apt-get install
+,(ref :text [Bigloo's development environment] :url *bigloo-url*) called
+``UDE'' (on Debian-based systems, it boils down to ,(tt [apt-get install
 bigloo-ude])).  Then, you need to specify that when the Emacs Lisp ,(tt
 "skribe-mode") function is needed it has to be loaded from the ,(tt
 "skribe.el") file:])
diff --git a/doc/user/figure.skb b/doc/user/figure.skb
index 5998986..dd418a6 100644
--- a/doc/user/figure.skb
+++ b/doc/user/figure.skb
@@ -1,5 +1,6 @@
-;;; figure.skb  --  Skribe figures
+;;; figure.skb  --  Figures.
 ;;;
+;;; Copyright 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2003  Manuel Serrano
 ;;;
 ;;;
@@ -21,7 +22,14 @@
 ;*---------------------------------------------------------------------*/
 ;*    Figure ... @label figure@                                        */
 ;*---------------------------------------------------------------------*/
-(section :title "Figure" :file #t
+(section :title "Figures" :file #t
+
+   (p [The ,(markup-ref "figure") markup shown below produces floating
+figures.  Well, whether the figure is really ``floating'' depends on the
+engine used (see ,(numref :text [Chapter] :ident "engines")): printed
+output as produced by the ,(tt [lout]) and ,(tt [latex]) engines do
+produce floating figures, but on-line output as produced by the ,(tt
+[html]) engine does not.])
 
 (doc-markup 'figure
 	    `((:legend ,[The legend of the figure. If no ,(param :ident) is
@@ -47,17 +55,21 @@
  (include "src/api14.skb")
 
 ;*--- List of figures -------------------------------------------------*/
-(subsection :title "List of figures"
+(subsection :title "List of Figures"
 (index "figure" :note "list of figures")
 
-(p [Skribe has no builtin facility for displaying the list of figures.
-Instead, it provides a general machinery for displaying any kind of lists
-contained in the document. This is described in the section ,(ref
-:section "Resolve") and ,(ref :section "Introspection") but for the
-sake of the coherence, this section also contains an example that
-shows how to display the list of figures of a document.])
+(p [Skribilo has no built-in facility to display the list of figures.
+Instead, it provides a general machinery for displaying any kind of
+lists of items contained in a document.  This is described in the
+section ,(ref :section "Resolve") and ,(ref :subsection
+"Introspection").  For the sake of simplicity, an example showing how to
+display the list of figures of a document is included below.])
 
 (example-produce
  (example :legend "The figure markup" (prgm :file "src/api15.skb"))
  (disp (include "src/api15.skb")))))
 
+;;; Local Variables:
+;;; coding: latin-1
+;;; ispell-local-dictionary: "american"
+;;; End:
diff --git a/doc/user/markup.skb b/doc/user/markup.skb
index 7469703..2109066 100644
--- a/doc/user/markup.skb
+++ b/doc/user/markup.skb
@@ -1,6 +1,6 @@
 ;;; markup.skb  --  The Skribilo standard markups
 ;;;
-;;; Copyright 2007  Ludovic Courtès <ludo@gnu.org>
+;;; Copyright 2007, 2008  Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright 2003, 2004  Manuel Serrano
 ;;;
 ;;;
@@ -22,57 +22,75 @@
 ;*---------------------------------------------------------------------*/
 ;*    API                                                              */
 ;*---------------------------------------------------------------------*/
-(chapter :title "Standard Markups" :ident "std-markups" [
+(chapter :title "Standard Markups" :ident "std-markups"
 
-This chapter describes the forms composing Skribe texts. In XML/HTML
-these forms are called ,(emph "markups"). In LaTeX they are called
-,(emph "macros"). In Skribe these forms are called ,(emph
-"functions"). In this manual, we will say that we ,(emph "call a
-function") when a function is used in a form. The values used in a
-function call are named the ,(emph "actual parameters") of the
-function or ,(emph "parameters") in short. When calling a function
-with parameters we say that we are ,(emph "passing") arguments to the
-function.
+   (p [This chapter describes the forms composing Skribilo texts that
+use the Skribe syntax (see ,(numref :text [Section] :ident
+"skribe-syntax")).  In XML/HTML jargon these forms are called ,(emph
+"markups").  In LaTeX they are called ,(emph "macros").  In Skribilo
+these forms are called ,(emph "functions").  In this manual, we will say
+that we ,(emph "call a function") when a function is used in a form.
+The values used in a function call are named the ,(emph "actual
+parameters") of the function or ,(emph "parameters") in short.  When
+calling a function with parameters we say that we are ,(emph "passing")
+arguments to the function.])
 
-,(p [ In this documentation function names are typesetted in bold
-face. We call a ,(emph "keyword argument"), an argument whose
-identifier starts with the ,(tt ":") character. Arguments whose
-identifier does not start with this character are called ,(emph "plain
-arguments") or ,(emph "arguments") in short. An ,(emph "optional
+   (p [In this document function names are typeset in boldface.  We call
+,(emph "keyword argument") a named argument, i.e., an argument whose
+name, starting with a colon (,(tt [:])), must be specified when the
+function is called.  Other arguments are called ,(emph "plain
+arguments") or ,(emph "arguments") for short.  An ,(emph "optional
 argument") is represented by a list, starting with the character ,(q
 (char 91)) and ending with the character ,(q (char 93)), whose first
-element is a keyword argument and the optional second (,(code "#f")
-when not specified) element is the default value used if the optional
-argument value is not provided on a function call. Arguments that are
-not optional are said ,(emph "mandatory"). If a plain argument is
-preceeded with a ,(tt ".")  character, this argument may be used to
-accumulate several values. There are two ways to pass actual arguments
-to a function.])
+element is a keyword argument and the optional second (,(code "#f") when
+not specified) element is the default value used if the optional
+argument value is not provided on a function call.  Arguments that are
+not optional are said ,(emph "mandatory").  If a plain argument is
+preceded by a ,(tt ".")  character, this argument may be used to
+accumulate several values.  There are two ways to pass actual arguments
+to a function:]
 
-,(itemize (item [for keyword arguments: the value of the parameter
+(itemize (item [for keyword arguments: the value of the parameter
 must be preceeded by the name of the argument.])
 	  (item [for plain arguments: a value is provided.]))
 
-Example: Let us consider the function ,(tt "section") defined as follows:
+[Example: Let us consider the function ,(tt "section") defined as follows:
 ,(prgm "(section :title [:number #t] [:toc #t] . body)")
-
-,(p [
 The argument ,(param :title) is a mandatory keyword argument.
 The keyword arguments ,(param :number) and ,(param :toc) are
 optional. The plain argument ,(param 'body) is preceeded with a
 ,(tt ".") character so it may receive several values. All the following
-calls are legal ,(tt "section") calls:])
+calls are legal ,(tt "section") calls:]
+
+(prgm (source :file "src/api1.skb")))
+   
+   (p [The remainder of this chapter describes ``standard'' markups or
+functions that are commonly used in documents.  By ``standard'', we mean
+two things: first, you will quickly notice that they look familiar if
+you have ever written, say, HTML or LaTeX documents; second, they are
+standard because these markups are always available by default to
+Skribilo documents, unlike those bundled in separate packages such as
+,(ref :ident "pie-charts" :text [pie charts]), ,(ref :text [slides]
+:ident "slides"), etc.  In fact, these markups are also bundled in a
+package, called ,(tt [base]), but this package is always available to
+Skribilo documents,(footnote [When creating Skribilo documents within
+Guile Scheme programs (see ,(numref :text [Section] :ident
+"scheme-syntax")), these standard markups can be made available by using
+the following clause: ,(code [(use-modules (skribilo package
+base))]).]).])
 
-,(prgm (source :file "src/api1.skb"))]
 
 ;*---------------------------------------------------------------------*/
 ;*    Markup index ...                                                 */
 ;*---------------------------------------------------------------------*/
-(section :title "Markup index" :ident "markups-index" :file #f :number #f :toc #t
-   (the-index :class 'markup-index 
-      :column (if (engine-format? "latex") 2 4)
-      :split #f
-      *markup-index*))
+(resolve (lambda (n e env)
+	   (and (not (engine-format? "lout" e))
+		(section :title "Markup Index" :ident "markups-index"
+		         :file #f :number #f :toc #t
+		   (the-index :class 'markup-index 
+		      :column (if (engine-format? "latex") 2 4)
+		      :split #f
+		      *markup-index*)))))
 
 ;*---------------------------------------------------------------------*/
 ;*    Markups                                                          */
@@ -95,6 +113,7 @@ calls are legal ,(tt "section") calls:])
 
 ;; Local Variables:
 ;; coding: latin-1
+;; ispell-local-dictionary: "american"
 ;; comment-start: ";"
 ;; comment-end: ""
 ;; End:
diff --git a/doc/user/syntax.skb b/doc/user/syntax.skb
index b11b001..e5917ca 100644
--- a/doc/user/syntax.skb
+++ b/doc/user/syntax.skb
@@ -32,9 +32,9 @@ by a ,(emph [reader]).  The input syntax (and reader) can be selected at
 document compilation time using the ,(tt [--reader]) option of the
 compiler (see ,(numref :text [Chapter] :ident "compiler")).
 Nevertheless, it has a ``preferred'' syntax (the default syntax), which
-is that of the ,(ref :url "http://www-sop.inria.fr/mimosa/fp/Skribe/"
-:text [Skribe document preparation system]).  Thus, the Skribe syntax is
-first described, and then alternate syntaxes are presented.])
+is that of the ,(ref :url *skribe-url* :text [Skribe document
+preparation system]).  Thus, the Skribe syntax is first described, and
+then alternate syntaxes are presented.])
 
 
    (section :title [The Skribe Syntax]
@@ -211,6 +211,7 @@ markup-less document format, there are many things that cannot be done
 using it, most notably tables, bibliographies, and cross-references.]))
    
    (section :title [Documents in Scheme Programs]
+            :ident "scheme-syntax"
       
       (p [It is also possible to create and output Skribilo documents
 from a Guile Scheme program.  In that case, you get to use the Scheme
diff --git a/doc/user/user.skb b/doc/user/user.skb
index 6447a62..3b14c77 100644
--- a/doc/user/user.skb
+++ b/doc/user/user.skb
@@ -53,6 +53,12 @@
    (engine-custom-set! he 'body-width 100.))
 
 
+;*---------------------------------------------------------------------*/
+;*    Example bibliography                                             */
+;*---------------------------------------------------------------------*/
+(bibliography "src/bib1.sbib")
+
+
 
 ;*---------------------------------------------------------------------*/
 ;*    The document                                                     */
@@ -61,11 +67,11 @@
    :keywords '("Skribilo" "Skribe" "User Manual" "text processing"
 	       "HTML" "LaTeX" "Lout" "PostScript" "PDF")
    :env '((example-counter 0) (example-env ()))
-   :author (list (author :name "Erick Gallesio"
+   :author (list (author :name "Érick Gallesio"
 		    :affiliation "Université de Nice - Sophia Antipolis"
 		    :email (mailto "eg@essi.fr"))
 		 (author :name "Manuel Serrano"
-		    :affiliation "Inria Sophia-Antipolis"
+		    :affiliation "INRIA Sophia-Antipolis"
 		    :email (mailto *serrano-mail*))
 		 (author :name "Ludovic Courtès"
 		    :email (mailto *courtes-mail*)))
@@ -75,7 +81,7 @@
 	   ;; text outside of chapters.
 	   (and (not (engine-format? "lout" e))
 	        (p :class "welcome"
-   [Welcome to the User Manual for Skribilo version ,(skribe-release).
+   [Welcome to the User Manual for Skribilo version ,(skribilo-version)!
 If you are new to Skribilo, please read the ,(ref :ident "intro"
 :text [introduction]) first.]))))
 
@@ -90,14 +96,13 @@ If you are new to Skribilo, please read the ,(ref :ident "intro"
    (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.])
+[Skribe] :url *skribe-url*), 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.])
    
    (p [This manual documents Skribilo version ,(skribilo-version).  Since
 it is based on Skribe's user manual, you might stumble upon documentation