Skribe User Manual

Skribe supports bibliographies. In order to use bibliography ref it is needed to:

Use the default pre-existing bibliography table or create a custom one.
Provide a bibliography database.
Load the database by the mean of the bibliography Skribe function call.
Reference to a bibliography entry, with a ref Skribe function call.

6.1 Bibliography tables

This section describes the function of using and creating bibliography tables.

The predicate bib-table? returns #t if and only if its argument is a bibliography table as returned by make-bib-table or default-bib-table. Otherwise bib-table? returns #f.

prototype
`(bib-table? obj)`
argument		description
`obj`		The value to be tested
See also
`make-bib-table` `default-bib-table` `bibliography` `the-bibliography`

The function default-bib-table returns a global, pre-existing bibliography-table:

prototype
`(default-bib-table)`
See also
`bib-table?` `make-bib-table` `bibliography` `the-bibliography`

The function make-bib-table constructs a new bibliography-table:

prototype
`(make-bib-table ident)`
argument		description
`ident`		The name of the bibliography table.
See also
`bib-table?` `default-bib-table` `bibliography` `the-bibliography`

6.2 Bibliography

The function bibliography loads bibliography entries into the Skribe memory. An 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. A bibliography database must be loaded before any reference is introduced. It is advised to place the bibliography Skribe function call before the call to the document function call.

prototype
`(bibliography [:command] [:bib-table (default-bib-table)] entry...)`
option	engines	description
command	html latex xml	An external command to be applied when loading the bibliography entries. The sequence `~a` is replaced with the name of the file when the command is invoked.
bib-table	html latex xml	The table where entry is searched.
argument		description
`entry...`		If `entry` is a string, it denotes a file containing the entry (see bibliograph path). Otherwise, it is a list described by the syntax below.
See also
`bib-table?` `make-bib-table` `default-bib-table` `the-bibliography`

The command option can be used to import foreign bibliography. The following example, shows how to directly use a Bibtex bibliography using the Skribebibtex6.4 translator.

Example:

(bibliography :command "gzip -d --to-stdout ~a | skribebibtex" "scheme.bib.gz")

Ex. 25: Printing a bibliography

6.2.1 Bibliography syntax

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:

<entry>  -->  (<kind> <key> <field>+)
<kind>   -->  techreport | article | inproceedings | book
<key>    -->  <symbol> | <string>
<field>  -->  (<symbol> <string>)

Bibtex files cannot be directly loaded in Skribe but the tool skribebibtex can be use to automatically convert Bibtex format to Skribe bibliography format. Here is an example of a simple Skribe database.

(book queinnec:lisp
   (author "Queinnec, C.")
   (title "Lisp In Small Pieces")
   (publisher "Cambridge University Press")
   (year "1996"))

(book scheme:ieee
   (title "IEEE Standard for the Scheme Programming Language")
   (author "IEEE Std 1178-1990")
   (publisher "Institute of Electrical and Electronic Engineers, Inc.")
   (address "New York, NY")
   (year "1991"))

(misc bigloo
   (url "http://www.inria.fr/mimosa/fp/Bigloo"))

(misc scheme:r4rs
   (title "The Revised4 Report on the Algorithmic Language Scheme")
   (author "Clinger, W. and Rees, J.")
   (month "Nov")
   (year "1991")
   (url "http://www.cs.indiana.edu/scheme-repository/R4RS/r4rs_toc.html"))

(article scheme:r5rs
   (title "The Revised5 Report on the Algorithmic Language Scheme")
   (author "Kelsey, R. and Clinger, W. and Rees, J.")
   (journal "Higher-Order and Symbolic Computation")
   (volume "11")
   (number "1")
   (month "Sep")
   (year "1998")
   (url "http://kaolin.unice.fr/Bigloo/doc/r5rs.html"))

(book as:sicp
   (author "Abelson, H. and Sussman, G.")
   (title "Structure and Interpretation of Computer Programs")
   (year "1985")
   (publisher "MIT Press")
   (address "Cambridge, Mass., USA"))

6.3 Printing a bibliography

The function the-bibliography displays the bibliography.

prototype
`(the-bibliography :pred [:bib-table (default-bib-table)] [:sort bib-sort/authors] [:count 'partial])`
option	engines	description
bib-table	html latex xml	The bibliography make-bib-tabletable to be displayed.
pred	html latex xml	A predicate filtering the bibliography entries. It takes two parameters: the bibliography entry and the the-bibliography node.
sort	html latex xml	A function sorting a list of entries.
count	html latex xml	The symbol `partial` or `full` specifies the numbering to be applied. The value `partial` tells Skribe to count only the entries filtered in by pred. The value `full` tells Skribe to count all entries, event those filtered out by pred.
See also
`bib-table?` `make-bib-table` `default-bib-table` `bibliography`

Example:

[Scheme ,(ref :bib 'scheme:r5rs) is functional programming language. It exists
several books about this language ,(ref :bib '(as:sicp queinnec:lisp)).

,(linebreak 2)
,(center (bold [-- Bibliography --]))

,(center (frame :border 1 :margin 2 :width 90. (the-bibliography)))]

Ex. 26: Printing a bibliography

Produces:

Scheme [5] is functional programming language. It exists several books about this language [1,3].

-- Bibliography --

[1]	Abelson, H. and Sussman, G. -- Structure and Interpretation of Computer Programs -- MIT Press, Cambridge, Mass., USA, 1985.
[5]	Kelsey, R. and Clinger, W. and Rees, J. -- The Revised5 Report on the Algorithmic Language Scheme -- Higher-Order and Symbolic Computation, 11(1), Sep, 1998.
[3]	Queinnec, C. -- Lisp In Small Pieces -- Cambridge University Press, 1996.

6.3.1 Filtering bibliography entries

The pred option is bound to a function of one argument that filters bibliography entries. It is used to control which entries must appears on a bibliography. The default behavior is to display only the entries referenced to in the text. For instance, in order to display all the entries of a bibliography, is it needed to print the bibliography with a predicate returning always #t.

Example:

(center 
 (frame :border 1 :margin 2 :width 90. 
        (the-bibliography :pred (lambda (m n) #t))))

Ex. 27: Unfiltering bibliography entries

Produces:

[1]	-- http://www.inria.fr/mimosa/fp/Bigloo.
[1]	Abelson, H. and Sussman, G. -- Structure and Interpretation of Computer Programs -- MIT Press, Cambridge, Mass., USA, 1985.
[3]	Clinger, W. and Rees, J. -- The Revised4 Report on the Algorithmic Language Scheme -- http://www.cs.indiana.edu/scheme-repository/R4RS/r4rs_toc.html, Nov, 1991.
[2]	Ieee Std 1178-1990, -- IEEE Standard for the Scheme Programming Language -- Institute of Electrical and Electronic Engineers, Inc., New York, NY, 1991.
[5]	Kelsey, R. and Clinger, W. and Rees, J. -- The Revised5 Report on the Algorithmic Language Scheme -- Higher-Order and Symbolic Computation, 11(1), Sep, 1998.
[3]	Queinnec, C. -- Lisp In Small Pieces -- Cambridge University Press, 1996.

The second example, filters out the entries that are not book or that are not referenced to from the document.

Example:

(center
 (frame :border 1 :margin 2 :width 90.
        (the-bibliography :pred (lambda (m n) 
                                   (and (eq? (markup-option m 'kind) 'book)
                                        (pair? (markup-option m 'used)))))))

Ex. 28: Unfiltering bibliography entries

Produces:

[1]	Abelson, H. and Sussman, G. -- Structure and Interpretation of Computer Programs -- MIT Press, Cambridge, Mass., USA, 1985.
[3]	Queinnec, C. -- Lisp In Small Pieces -- Cambridge University Press, 1996.

The last example, illustrates how to change the rendering of a bibliography. It uses the [?mark processor: skr/manual.skr:7123] construction and it defines two [?ident writer: user/bib.skb:8293] for displaying &bib-entry-ident and &bib-entry-title markups. These two markups are introduced by Skribe when it loads a bibliography. All fields of bibliography entries are represented by markups whose prefix are &bib-entry-. The parent of all these markups is the bibliography entry itself. The &bib-entry- markups are options of there parent.

Example:

(center
 (frame :border 1 :margin 2 :width 90.
        (processor :engine
                   (make-engine '_ :filter string-upcase)
                   :combinator
                   (lambda (e1 e2)
                      (let ((e (copy-engine '_ e2)))
                         (markup-writer '&bib-entry-ident e
                                        :action
                                        (lambda (n e)
                                           (let* ((be (ast-parent n))
                                                  (o (markup-option be 'author))
                                                  (y (markup-option be 'year)))
                                              (output (markup-body o) e1)
                                              (display ":")
                                              (output (markup-body y) e))))
                         (markup-writer '&bib-entry-title e
                                        :action
                                        (lambda (n e)
                                           (skribe-eval (it (markup-body n)) e)))
                         e))
                   (the-bibliography :pred 
                                     (lambda (m n)
                                        (eq? (markup-option m 'kind) 'book))))))

Ex. 29: Unfiltering bibliography entries

Produces:

[ABELSONH.SUSSMANG.:1985]	Abelson, H. and Sussman, G. -- Structure and Interpretation of Computer Programs -- MIT Press, Cambridge, Mass., USA, 1985.
[IEEE STD 1178-1990:1991]	Ieee Std 1178-1990, -- IEEE Standard for the Scheme Programming Language -- Institute of Electrical and Electronic Engineers, Inc., New York, NY, 1991.
[QUEINNECC.:1996]	Queinnec, C. -- Lisp In Small Pieces -- Cambridge University Press, 1996.

6.3.2 Sorting bibliography entries

The sort option of the the-bibliography markup is used for sorting the bibliography entries. There are three pre-existing functions for sorting entries:

prototype
`(bib-sort/authors l)`
`(bib-sort/idents l)`
`(bib-sort/dates l)`
argument		description
`l`		The list of entries.

The first function sorts the entries according to an alphabetic ordering on authors. The second sorts according to an alphabetic ordering on entries identifier. The last one sorts according to entries date.

Example:

(define (bib-sort/idents l)
   (sort l (lambda (e f) (string<? (markup-ident e) (markup-ident f)))))

Ex. 30: Sorting bibliography entries

6.4 Skribebibtex

In this section we present the Skribebibtex translator that compiles Bibtex source files into a Skribe bibliography.

SYNOPSIS

../bin/skribebibtex.bigloo [options] [input]...

DESCRIPTION

This manual page is not meant to be exhaustive. It documents the skribebibtex, a tool that translates Bibtex files into Skribe, bibliography format. These files can be used by the skribe compiler to produce bibliography entries.

SUFFIXES

The skribe compiler uses file suffixes in order to select amongst its possible targets which to choose. These suffixes are:

.bib: a Bibtex source file.

OPTIONS

-h,--help: This help message.
--options: Display the options and exit.
-o OUT: Set the destination file.