AUX module – handling .aux files

LaTeX generates .aux files which tie together the collection of bibliographic citations obtained from the source file, the bibliographic data base(s) which are to be used (the .bib files) and the citation style.

The .aux file is in TeX syntax, with only the \citation, \bibdata and \bibstyle commands recognised:

If beastie is asked to process a .aux file as input, then it will assume that the citation style is a standard .bst file, and handle it on that basis. To use a separate .scm file, the extension must be included explicitly.

You can either parse the aux file directly, with parse-aux-file, or use call-with-aux-file to parse it and invoke a processor in one step.

call-with-aux-file : string? ((listof symbol?) (listof string?) string? [:parse-aux-file fn] -> unspecified: In (call-with-aux-file fn processor), the aux-file fn is opened, parsed, and the contents processed with the function processor, called with the results from parse-aux-file.

The given processor function is called with three arguments:

• citations: a list of citation keys, as symbols, or the special symbol 'all
• bibdata: a list of paths to the .bib files to read from, as indicated by \bibdata
• bibstyle: a style file indicated by the \bibstyle command

If the fn is passed as #f, then parse stdin.

If the aux file can't be opened, or it can't be parsed, then return #f.

For a suitable processor, see the function process-bibs/bst in the bst module.

If the keyword argument :parse-aux-file is present, then that function is used, instead of the default parse-aux-file function, to parse the file. A suitable alternative function might be, for example,

(define (parse-aux-file/nobst fn)
  (let ((result (parse-aux-file fn)))
    (list (car result) (cadr result) #f)))

will have the same effect as parse-aux-file, but discarding the style-file found there.

parse-aux-file : string? -> (list (listof symbol?) (listof string?) string? : In (parse-aux-file filename) parse the aux file filename, and return relevant contents.

We return a list (list-of-symbols list-of-strings string) which are in order the list of citations, or 'all if we see \citation{*}; the list of .bib databases to consult; and the style-file to use. The databases and style-file elements are returned as #f if they're absent.

We recognise the following commands in the .aux file:

• \citation{foo} : cite an object with BibTeX key foo.
• \citation{*} : include all of the entries in the database.
• \bibdata{bib} : names the BibTeX database to consult; this command can appear more than once, the argument can be a single file or a list separated by commas, and the .bib extension is optional.
• \bibstyle{plain} : the style file to be used.

If the kpathsea library was available when beastie was built (it usually is) then it will be used to look up the values of the \bibdata and \bibstyle commands.

If the fn is passed as #f, then parse stdin.

Returns #f if the file can't be parsed as an aux-file.

Like parse-aux-file, mostly for debugging.