Example beastie programs
========================

This directory contains a number of example beastie programs/scripts, intended
to illustrate how to write bibliography programs using beastie.

In versions before 1.0, I may change the functionality of the program
in such a way that example scripts from previous versions will no
longer work.  At present, I regard this as a list of illustrations of
how one might use Beastie, rather than a collection of supported
utility programs, which means that the tests in this directory remain
very basic ones, intended to detect obvious major breakage rather than
details of behaviour.  This may change as these mature.

In each case, see the comments at the top of the program for more
detailed information.

The file `test-examples.scm` is not an example program, but instead a
(simple) test-runner.

aux-to-refs.scm
---------------

Given an `.aux` file, this parses it, and generates a XHTML
bibliography using the functions in `plain.scm`.  It takes the name of
the `.scm` file from the `\bibstyle{foo}` command in the `.aux` file;
this must include the `.scm` extension, as the `kpathsea` search will
not add that by default.

bib-to-sql.scm
--------------

Convert a .bib file into a SQL database.

An alternative route to this is via [bibclean](http://www.math.utah.edu/pub/bibclean/)
and [bibtosql](http://www.math.utah.edu/pub/bibsql/).  That almost
works, but the post-processing required is slightly different from
this version.  Another minor advantage of doing this this way is
that we don't require any tools other than BibTeX.


bibliography-in-markdown.scm
----------------------------

Insert a bibliography into a Markdown file, to produce XHTML or basic Markdown.

This version uses the built-in support for RMarkdown-style citations
(cf, [RMarkdown docs][rmarkdown]).  This uses the functions defined in
`plain.scm` to do the formatting work.

Thea `bibliography-in-markdown-alt.scm` does a similar thing, but
without using the built-in support for citations, illustrating how one
can edit/rearrange/shake the xexpr document tree in a useful and/or
creative way.

[rmarkdown]: https://bookdown.org/yihui/rmarkdown-cookbook/bibliography.html

extract-bib.scm
---------------

This program takes a `.aux` file and produces a `.bib` file containing
the extracted data for the citations mentioned in the `.aux` file.
Alternatively, it can produce that output in [crossref][] form, or
YAML (the latter has no particular schema, but might be easy to
parse).

This program uses the `plain.scm` functions, just as
`bibliography-in-markdown.scm` does

[crossref]: https://www.crossref.org/documentation/schema-library/markup-guide-metadata-segments/references/

plain.scm
---------

This isn't a program by itself, but it's used by a couple of the
programs above to do the main formatting of bibliographies.
It's intended to be the broad equivalent of the BibTeX `plain.bst` style file.

It exports a function `assemble-bibliography`, which takes a list of
citation keys, as symbols, and a list of `.bib` files, and produces a
list of `citation?` objects (see `bibtex.scm`) which can be used to
produce the output.

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