6. Skribe User Manual -- Bibliography


main page
top:Skribe User Manual
index:Index
markups:Standard Markups


Bibliography
6.1Bibliography
6.2Printing a bibliography
6.3Skribebibtex


Chapters
1Getting Started
2Syntax & Values
3Standard Markups
4References and Hyperlinks
5Indexes
6Bibliography
7Computer programs
8Standard Library
9Engines
10Editing Skribe Programs
11Skribe compiler
12Compiling Texi documents
13List of examples
14Table of contents

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

  • 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

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] entry...)
optionenginesdescription
:commandhtml latex 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.
argumentdescription
entry...If entry is a string, it denotes a file containing the entry (see [?mark *skribe-bib-path*]). Otherwise, it is a list described by the syntax below.

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.

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

6.1.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.2 Printing a bibliography

The function the-bibliography displays the bibliography.

prototype
(the-bibliography :pred [:sort bib-sort/authors] [:count 'partial])
optionenginesdescription
:predhtml latex A predicate filtering the bibliography entries. It takes two parameters: the bibliography entry and the the-bibliography node.
:sorthtml latex A function sorting a list of entries.
:counthtml latex 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.
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.2.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 -- 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] construction and it defines two [?ident writer] 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:
[ABELSON, H. AND SUSSMAN, G.: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.
[QUEINNEC, C.:1996]Queinnec, C. -- Lisp In Small Pieces -- Cambridge University Press, 1996.

6.2.2 Sorting bibliography entries

The :sort option of the the-bibliography markup enables sorting the bibliography entries. Two pre-existing functions for sorting entries:

prototype
(bib-sort/authors l)
(bib-sort/idents l)
(bib-sort/dates l)
argumentdescription
lThe 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.3 Skribebibtex

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

SYNOPSIS

skribebibtex [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.


This Html page has been produced by Skribe.
Last update Thu Mar 16 19:59:29 2006.