Beastie – an experimental processor for BibTeX and friends
==========================================================

This is (a first cut at) a BibTeX processor.

Beastie is an experiment in supporting a decent
language for processing BibTeX bibliographies (by which I mean a
language which isn't the `.bst` language, which I enjoy, but only for
rather perverse reasons; and by which I mean more specifically
_Scheme_).  As a functionality goal, it also implements the `.bst`
language, showing that it is _at least_ as functional as that
language.

The goals of this project are:

  * to explore ways of processing `.bib` files which
    _aren't_ exclusively based on `.bst`;
  * to provide a second implementation of the BST language; and
  * to initiate some sort of conversation about BibTeX standards,
    broadly construed.

The first and second of those points aim to get away from BibTeX being
a single-implementation system, where the only thing that can reliably
process a `.bib` file is the `bibtex` program.  This isn't _quite_ the
case at present, but combined with the third documentation point, it's
quite hard to process BibTeX input in a confident way.

As far as the `.bst` language is concerned, it aims to support it
quite fully, in the sense that it will produce the same resuls as
BibTeX, for the standard styles.  However it doesn't support it
slavishly, and there are some deviations noted in `doc/beastie.md`.
It also aims to slightly improve `.bst` error reporting, and adds a
couple of extra `.bst` builtin functions, in both cases with the aim
of being useful for debugging or developing `.bst` files (eg, `printf$$`).

The tool depends on both [flex](https://github.com/westes/flex) and
[Bison 2 or 3](https://www.gnu.org/software/bison/).  Building from a checkout
additionally requires `autoconf`.  These are `apt`, `yum` and FreeBSD
`pkg` packages `flex`, `bison` and `autoconf`; as of Debian
12, RHEL 9, and FreeBSD 13, these are Bison3 in all cases.  On
macOS, flex and Bison2 come as stock.  The tool will use `kpsewhich`
if a suitable TeX installation is in the path.

To build from a distribution, you need only do

    ./configure
    make check

(we require GNU Make).
You can provide a `--without-kpse` option to `./configure`
to suppress use of the kpselib library (if it's present),
and provide `--with-icu[=path]` to give the path to the
[ICU][] library, if it's present and not found by default;
or add `--without-icu` to suppress it.
In Debian/apt terms, you'll need to install
`apt-get install gcc autoconf flex bison libicu-dev`
for a complete build from a repository checkout;
in RedHat/dnf terms, that's
`dnf install autoconf flex bison libicu-devel`;
from a distribution, you won't need `autoconf`.

[ICU]: https://icu.unicode.org

There's also a very simple `make install` target
(respects a `--prefix=$HOME/local` argument to `./configure`)
and a comprehensive `make check` target.  The distributed tarball
contains a source set slightly different from the repository source
(it includes generated documentation, and omits `configure.ac`).  It
should be suitable for simple hacking on the source, if necessary, but
it would probably be better to go to the repository and check out the
source.  The makefile also includes a few standalone (and only
semi-supported) lexers, so that, for example, `lex-authors` or
`lex-bib2` will produce the stream of lexemes the program consumes from
an author string or a `.bib` file (as a curiosity, or for debugging).

To build from a checkout, preface the above with `./bootstrap`
(this requires that `autoconf` and `autoheader` be in the path).

See the file `doc/beastie.md` (or `doc/beastie.xhtml` in a
distribution) for some `btx` anomalies (cases where the btxhak
documentation seems a little peculiar), some beastie deviations from
BibTeX behaviour, and a pointer to notes and tools from Nelson Beebe.
To read the manpage, either install Beastie, or `man doc/beastie.1`.

The Scheme implementation I use is the fine s7 mini-Scheme,
from [ccrma.stanford.edu](https://ccrma.stanford.edu/software/snd/snd/s7.html)
(see `./beastie -V` for the precise version).  Thanks to Bill
Schottstaedt for creating s7, and for advice on some of its intricacies.

There are some examples in the directory `examples/`.

The program is copyright Norman Gray, and distributed under the terms
of the 2-clause BSD licence.  See the file `LICENCE.txt` for details.
The exception is the pair of files `s7.c` and `s7.h`, which are
copyright Bill Schottstaedt, and released under the terms of the
‘BSD zero-clause’ licence.

  * Home page: https://purl.org/nxg/dist/beastie
  * Version: 0.14.1
  * Date: 2026 August 02


Plans
-----

Things to do...

...maybe sometime/never:

  * Clearer warning when an entry type has no style-file definition
    (BibTeX is noisy about this, beastie isn't).
  * In author lists or titles, handle 'text {TexT}' to suppress
    case-folding of bracketed text.  This is partly done, but is part of
    a slightly longer project to abstract the handling here, to make it
    easier to generate non-TeX outputs.
    Possibly consider also normalising of whitespace?
  * Prettyprint the .bst parse tree, and reimplement
    [urlbst](https://ctan.org/pkg/urlbst) by shaking that tree.
  * Investigate [.csl](https://citationstyles.org)?
  * Output: maybe produce LaTeX by producing HTML and formatting that:
    `(em "foo")` -> `"\emph{foo}"`.  Cute idea, probably unnecessary.
  * Markdown: support indented/literal code in itemized lists (I've just
    never got around to this); any other significant deviations from
    the Gruber spec? (apart from literal HTML, which is probably a bit
    of a project).  I have an interesting experiment on a branch.


See the [release notes](release-notes.md).

----
Norman Gray  
https://nxg.me.uk

----
SPDX-FileCopyrightText: 2023 Norman Gray <https://nxg.me.uk>
SPDX-License-Identifier: BSD-2-Clause

