summaryrefslogtreecommitdiff
path: root/doc/user
diff options
context:
space:
mode:
authorLudovic Courtès2008-02-01 13:22:53 +0100
committerLudovic Courtès2008-02-01 13:22:53 +0100
commit654ba1f34b7661a81b0ce720040f17591f79b552 (patch)
tree29494a96d907e1e27f3e79e088a99002429a74ad /doc/user
parent0e2a5636d9e0bb90c3e98cc472e454fe05221dd9 (diff)
downloadskribilo-654ba1f34b7661a81b0ce720040f17591f79b552.tar.gz
skribilo-654ba1f34b7661a81b0ce720040f17591f79b552.tar.lz
skribilo-654ba1f34b7661a81b0ce720040f17591f79b552.zip
doc: Various insignificant cleanups.
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/bib.skb83
-rw-r--r--doc/user/compiler.skb7
-rw-r--r--doc/user/emacs.skb5
-rw-r--r--doc/user/figure.skb30
-rw-r--r--doc/user/markup.skb87
-rw-r--r--doc/user/syntax.skb7
-rw-r--r--doc/user/user.skb27
7 files changed, 146 insertions, 100 deletions
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