6. Skribilo User Manual — Bibliographies
Contents↑ Skribilo User Manual

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:

The following sections will guide you through these steps.

6.1 Bibliography Tables

This section describes functions dealing with bibliography tables. Essentially, bibliography tables are the representation of your bibliographies used by Skribilo at run-time.

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

prototype
(bib-table? obj)
argumentdescription
objThe value to be tested
See also
make-bib-table *bib-table* bibliography the-bibliography

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

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

Technically, *bib-table* is actually an SRFI-39 parameter object, so it can be queried and modified like any other parameter object.

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

prototype
(make-bib-table ident)
argumentdescription
identThe name of the bibliography table.
See also
bib-table? *bib-table* bibliography the-bibliography

6.2 Bibliography

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

prototype
(bibliography [:bib-table (*bib-table*)] [:command] entry...)
optionenginesdescription
:commandhtml lout latex context info 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-tablehtml lout latex context info xml The table where entry is searched.
argumentdescription
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 *bib-table* the-bibliography

Files passed as an argument to bibliography are searched in the current bibliography path, which is defined by the *bib-path* SRFI-39 parameter. This parameter contains a list of directories and its value can be obtained using (*bib-path*). Its value can be altered using the -B command-line option of the skribilo compiler (see Chapter 14 for details).

The :command option can be used to import foreign bibliography. The following example, shows how to directly use a BibTeX bibliography using the Skribebibtex translator.

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

6.2.1 Bibliography Syntax

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:

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

BibTeX files cannot be directly loaded 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 "Christian Queinnec")
   (title "Lisp In Small Pieces")
   (publisher "Cambridge University Press")
   (year "1996"))

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

(misc bigloo
   (author "Manuel Serrano")
   (year "2006")
   (url "http://www.inria.fr/mimosa/fp/Bigloo"))

(misc scheme:r4rs
   (title [The Revised,(sup [4]) Report on the Algorithmic Language Scheme])
   (author "William D. Clinger, Jonathan Rees")
   (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 "Richard Kelsey, William D. Clinger, Jonathan Rees")
   (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 "Harold Abelson, Gerald Jay Sussman")
   (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 [:labels 'number] [:count 'partial] [:sort bib-sort/authors] [:bib-table (*bib-table*)])
optionenginesdescription
:bib-tablehtml lout latex context info xml The bibliography table to be displayed.
:predhtml lout latex context info xml A predicate filtering the bibliography entries. It takes two parameters: the bibliography entry and the the-bibliography node.
:sorthtml lout latex context info xml A function sorting a list of entries.
:labelshtml lout latex context info xml Specifies the style for bibliography entries labels. The default, number, uses numbers to identify references, e.g., "[7]". When name+year is chosen, long labels including the first author's last name (and optionally the second author's last name) and the year of publication will be used. For instance: "[Smith 1984]", "[Smith & Johnson 1979]", or "[Smith et al. 1980]".
:counthtml lout latex context info xml The symbol partial or full specifies the numbering to be applied. The value partial tells Skribilo to count only the entries filtered in by :pred. The value full tells Skribilo to count all entries, event those filtered out by :pred.
See also
bib-table? make-bib-table *bib-table* bibliography noabbrev

Note that the name+year label style will only work if the following conventions are followed by the author field of your bibliography entries:

When using the name+year label style, it is sometimes desirable to preclude automatic abbreviations for some authors, e.g., when the author is the name of a consortium or company rather than that of a person. In that case, you should enclose the value of your author field in a noabbrev markup.

prototype
(noabbrev [:class] [:ident])
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
See also
the-bibliography bib-sort/first-author-last-name

The following example illustrates typical use of a bibliography.

[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. 28: Printing a Bibliography

... produces:

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

-- Bibliography --
[2]Christian Queinnec. Lisp In Small Pieces. Cambridge University Press, 1996.[3]Harold Abelson, Gerald Jay Sussman. Structure and Interpretation of Computer Programs. MIT Press, Cambridge, Mass., USA, 1985.[5]Richard Kelsey, William D. Clinger, Jonathan Rees. The Revised5 Report on the Algorithmic Language Scheme. In Higher-Order and Symbolic Computation, 11(1) , Sep 1998, .

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.

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

... produces:

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

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

(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. 30: Unfiltering Bibliography Entries

... produces:

[2]Christian Queinnec. Lisp In Small Pieces. Cambridge University Press, 1996.[3]Harold Abelson, Gerald Jay Sussman. Structure and Interpretation of Computer Programs. MIT Press, Cambridge, Mass., USA, 1985.

The last example, illustrates how to change the rendering of a bibliography. It uses the [?mark processor: skribilo/documentation/manual.scm:307:] construction and it defines two [?ident writer: ./bib.skb:245:] 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.

(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)
                                            (evaluate-document (it (markup-body n)) e)))
                          e))
                    (the-bibliography :pred 
                                      (lambda (m n)
                                         (eq? (markup-option m 'kind) 'book))))))
Ex. 31: Unfiltering Bibliography Entries

... produces:

[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.[CHRISTIAN QUEINNEC:1996]Christian Queinnec. Lisp In Small Pieces. Cambridge University Press, 1996.[HAROLD ABELSON, GERALD JAY SUSSMAN:1985]Harold Abelson, Gerald Jay Sussman. Structure and Interpretation of Computer Programs. MIT Press, Cambridge, Mass., USA, 1985.

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)
argumentdescription
lThe list of entries.
See also
bib-sort/first-author-last-name

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.

(define (bib-sort/idents l)
   (sort l (lambda (e f) (string<? (markup-ident e) (markup-ident f)))))
Ex. 32: Sorting Bibliography Entries

In addition, the (skribilo biblio author) module exports a fourth procedure that sorts bibliography entries:

prototype
(bib-sort/first-author-last-name entries)
argumentdescription
entriesThe list of entries.
See also
bib-sort/authors the-bibliography noabbrev

This procedure allows entries to be sorted according to the last name of the first author of each bibliography entry. For this to work, the author field of bibliography entries must follow the same conventions as for the name+year label style of the-bibliography.


6.4 Skribebibtex

FIXME: This tool is not available as of Skribilo version 0.9.2.


(made with skribilo)