diff options
| -rw-r--r-- | doc/modules/skribilo/documentation/env.scm | 1 | ||||
| -rw-r--r-- | doc/user/bib.skb | 83 | ||||
| -rw-r--r-- | doc/user/compiler.skb | 7 | ||||
| -rw-r--r-- | doc/user/emacs.skb | 5 | ||||
| -rw-r--r-- | doc/user/figure.skb | 30 | ||||
| -rw-r--r-- | doc/user/markup.skb | 87 | ||||
| -rw-r--r-- | doc/user/syntax.skb | 7 | ||||
| -rw-r--r-- | doc/user/user.skb | 27 |
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 |