Generated: Monday, November 14, 2011, 09:19:48 Copyright © 2011 , Kurt NÝrmark The local LAML software home page

Reference Manual of the LAML BibTeX library

Kurt NÝrmark © normark@cs.aau.dk Department of Computer Science, Aalborg University, Denmark.

LAML Source file: tools/bibtex/bibtex.scm

This is a collection of bibtex functionality for LAML. One main part of this collection provides a parsing function of a bibtex file, leaving the result as a list of Lisp association lists. Another part accesses information in parsed bibtex file. The last part has HTML/LAML presentation functions for bibtex.

Please notice that this is still not a complete bibtex parser. We currently support only the most common and most used constructs. The Bibtex presentation functions are not complete either.

The LAML bibtex parser is not very fast. So we envision that the parser is activated every now and then on a bibtex file f.bib, in order to produce the parsed lisp file f.lsp. We recommend that you place an LAML command file together with you bibtex file which does that job. You can read such files using the function read-parsed-bibtex-files.

Usage:

It is possible to parse a bibtex file and get the list bibtex entries represented as association lists. This is done by parse-bibtex-file. The variable parse-result will contain the entries.

As an example, the parser is can be activated by

 (parse-bibtex-file "file") 
where "file" is the file name without the bib extionsion.

Given the existence of a list of bibtex entries represented as a list of association lists bibtex-list, say parse-result, it is possible to HTML present this list by for instance

 (present-bibtex-entries parse-result (p)) 
Often it will be useful to extract some subset of a bibtex list. This can, of course, be done be filtering, but the following methods makes it possible to extract a subset given a key-list, for instance via
 (bibtex-entries key-list bibtex-list warn-if-non-existing-entry) 
The keylist itself can be produced from a bibtext-list via the following call:
 (key-list-matching "normark" bibtex-list) 

Besides the general library, this library requires the collect-skip parsing library (not loaded by bibtex). The presentation part also assumes that the HTML mirrors are loaded.

There exists a function called bibtex in laml.scm which activates the bibtex parser, and which in addition presents the bibtex entries in HTML via LAML. The bibtex function should be activated in an interactive LAML session (from a Scheme prompt with LAML loaded).

This tool can be used together with the HTML4.01 and XHTML validating mirrors.

Table of Contents:
1. Bibtex parsing. 2. Access to bibtex files and entries. 3. Bibtex HTML/LAML presentation functions.

Alphabetic index:
bibtex-entries (bibtex-entries key-list bibtex-list non-existing-key) Return a subset of bibtex-list, as ennumerated by key-list (a list of key strings), and in the order given by key-list.
bibtex-entry-leq-by-time? (bibtex-entry-leq-by-time? entry-1 entry-2) A less than or equal predicate on parsed bibtex entries (association lists).
bibtex-verbose bibtex-verbose A variable that controls whether bibtex-parse-file emits messages to standard output while parsing.
get-bibtex-entry (get-bibtex-entry key bibtex-list) Access and return a bibtex entry (an association list) from bibtex-list (a parsed bibtex list).
get-bibtex-field (get-bibtex-field key entry . optional-parameters) Get the field with key from the parsed bibtex entry.
ignore-non-existing-entry (ignore-non-existing-entry key) A possible non-existing-key function to bibtex-entries.
key-list-matching (key-list-matching key-part bibtex-list) Return a list of keys (string) which match partially or fully a key in bibtex-list.
parse-bibtex-file (parse-bibtex-file file) Parses a bibtex file file.bib and delivers the parsed result on file.lsp.
parse-result parse-result The result of bibtex-parsed can be accessed via the variable parse-result.
present-bibtex-entries (present-bibtex-entries entries sep) Present a list of bibtex entries speparated by sep (a string).
present-bibtex-entry (present-bibtex-entry entry [trailing-presentation]) The overall top-level function that presents a single bibtex entry.
present-links-from-title? present-links-from-title? A boolean variable that controls if a link is to be generated from the title of a biblographic item.
read-parsed-bibtex-file (read-parsed-bibtex-file file) Read and return the parsed entries of the bibtex file file, which is a full path without the trailing lsp extension.
read-parsed-bibtex-files (read-parsed-bibtex-files . file-list) Read and return an appended list of parsed bibtex files.
stop-if-non-existing-entry (stop-if-non-existing-entry key) A possible non-existing-key function to bibtex-entries.
warn-if-non-existing-entry (warn-if-non-existing-entry key) A possible non-existing-key function to bibtex-entries.


1 Bibtex parsing.
The function bibtex-parse-file parses a bibtex file f.bib and delivers the parsed result on f.lsp. The parser is able to parse my all.bib file, but it cannot accept all variants allowed by bibtex. Multiple authors separated by 'and' are parsed to a list of authors. All bibtex values must be enclosed in {...}, not "...".

parse-result
Form parse-result
Description The result of bibtex-parsed can be accessed via the variable parse-result.

bibtex-verbose
Form bibtex-verbose
Description A variable that controls whether bibtex-parse-file emits messages to standard output while parsing.

present-links-from-title?
Form present-links-from-title?
Description A boolean variable that controls if a link is to be generated from the title of a biblographic item. Notice that a link is only generated if a url field is given in the bibtext record.

parse-bibtex-file
Form (parse-bibtex-file file)
Description Parses a bibtex file file.bib and delivers the parsed result on file.lsp. The result is a list of association lists where two initial keys are used: type gives the bibtex type of an entry, and key gives the keyname which names the entry. The other keys in the association list are given by the field names in the bibtex record. All keys are symbols.


2 Access to bibtex files and entries.
The functions in this section accesses parsed bibtex files and bibtex entries (alist representations of bibtex entries).

read-parsed-bibtex-files
Form (read-parsed-bibtex-files . file-list)
Description Read and return an appended list of parsed bibtex files. File-list is a list of full paths to bibtex-files without the trailing lsp extension.

read-parsed-bibtex-file
Form (read-parsed-bibtex-file file)
Description Read and return the parsed entries of the bibtex file file, which is a full path without the trailing lsp extension.

get-bibtex-entry
Form (get-bibtex-entry key bibtex-list)
Description Access and return a bibtex entry (an association list) from bibtex-list (a parsed bibtex list). If it does not exit return #f.

bibtex-entries
Form (bibtex-entries key-list bibtex-list non-existing-key)
Description Return a subset of bibtex-list, as ennumerated by key-list (a list of key strings), and in the order given by key-list. non-existing is a procedure or function, which is called with key as parameter if a key does not appear in bibtex-list. non-existing can ignore the error, in which case the collection of entries continues, it can issue a warning, or it can stop the collection.

ignore-non-existing-entry
Form (ignore-non-existing-entry key)
Description A possible non-existing-key function to bibtex-entries. This function can be used as the last parameter to the function bibtex-entries.

warn-if-non-existing-entry
Form (warn-if-non-existing-entry key)
Description A possible non-existing-key function to bibtex-entries. This function can be used as the last parameter to the function bibtex-entries.

stop-if-non-existing-entry
Form (stop-if-non-existing-entry key)
Description A possible non-existing-key function to bibtex-entries. This function can be used as the last parameter to the function bibtex-entries.

key-list-matching
Form (key-list-matching key-part bibtex-list)
Description Return a list of keys (string) which match partially or fully a key in bibtex-list. This function is useful to select a subset of the keys in a bibtex collection. Use bibtex-entries to access these entries.

bibtex-entry-leq-by-time?
Form (bibtex-entry-leq-by-time? entry-1 entry-2)
Description A less than or equal predicate on parsed bibtex entries (association lists). Assumes as a pre-condition that the year field is defined in both entries. Takes a possible month field into consideration if necessary.


3 Bibtex HTML/LAML presentation functions.
The functions in this section presents a single bibtex entry as HTML via LAML.

present-bibtex-entry
Form (present-bibtex-entry entry [trailing-presentation])
Description The overall top-level function that presents a single bibtex entry. Returns an HTML string. As an optional-parameter, trailing-presentation is a function that may present additional and specialized aspectes of the entry. trailing-presentation is a function of one parameter, namely entry. It defaults to a function that returns the empty string.
Parameters entry A parsed bibtex entry.
trailing-presentation A function of entry that returns additional presentation to be string-appended to the main presentation. Defaults to (lambda (entry) "").
Returns a list of AST document constituents (pieces of markup, which for instance can be put into a div or p XHTML element).

present-bibtex-entries
Form (present-bibtex-entries entries sep)
Description Present a list of bibtex entries speparated by sep (a string). Returns an HTML string.

get-bibtex-field
Form (get-bibtex-field key entry . optional-parameters)
Description Get the field with key from the parsed bibtex entry. The key names are as given in the bibtex source file. Two special key names apply: key and type. key is unique identification of a bibtex record. The key url is special too. It accesses in reality rawurl, if available, else url. type is the kind of bibtex record. The optional parameter status is either the symbol required or optional, with required as default (used for warning purposes only).

Generated: Monday, November 14, 2011, 09:19:48
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)