# bibutils
A collection of small, single-purpose scripts written in POSIX shell and awk
for the manipulation of bibtex database files from the command line. Each one
is small and single purpose. They are as follows:

## bib-util
A general wrapper script that centralizes the functionality of many of the
smaller provided scripts for convenience's sake.

## bib-add
A script for inserting a new entry into a bibtex database file. It will
accept a fully formatted entry on standard input and add it to a database
file presented as an argument. The database is never modified in place:
the new version is built in a temporary file, verified, and only then
swapped in, with the previous contents saved in db.bib.bak. Replacing an
entry (-f) preserves every other byte of the file.

## bib-gen
A script which generates a bibtex entry based on input. By default it will
run in an interactive mode, prompting the user to enter the relevant details.
Additionally, it can be configured to read the data directly from stdin based
on format arguments, or data can be provided directly as arguments. The
formatted bibtex entry will be emitted on stdout.

## bib-extract 
A script which filters a bibtex database provided on stdin or as an argument
and emits only those entries contained within a specified aux file. Both
classic bibtex and biblatex/biber aux files are understood, and \nocite{*}
selects the whole database. (roff citation sources are planned but not yet
supported.)

## bib-ls
List the entries in a database, one key per line, or with -l as
tab-separated key, type, author, year and title.

## bib-check
Lint a database: reports missing required fields, duplicate keys,
duplicate titles (likely duplicated entries) and empty field values.
Exits nonzero if any problem was found.

## bib-key
A script which accepts a bibtex entry on stdin, and emits it on stdout with
an automatically generated bibtex key.

## bib-fetch
A script which accepts a pdf file as an input argument and will attempt to
fetch a corresponding bibtex entry based on its DOI (via crossref.org) or,
failing that, its arXiv id (via arxiv.org). An identifier can also be given
directly with -d (DOI) or -a (arXiv id).

## bib-convert
Convert between bibtex and refer database formats. The direction is detected
automatically from the input, or can be forced with -b (to bibtex) or -r
(to refer).

# Canonical form
Entries that pass through these tools are canonicalized: lowercase entry
types and field names, 2-space indentation, brace-delimited values with
internal whitespace collapsed, bare numbers left bare, and macro
references/concatenations preserved verbatim. @string and @preamble blocks
pass through untouched.

# Installation
    make install            # PREFIX=/usr/local by default

Scripts go to $(PREFIX)/bin, the shared awk library to
$(PREFIX)/share/bibutils, and man pages to $(PREFIX)/share/man/man1.

The scripts look for the shared awk library in $BIBUTILS_LIB, then in
lib/ next to the script, then in /usr/local/share/bibutils. If installing
with a non-default PREFIX, set BIBUTILS_LIB accordingly.

# Dependencies
POSIX shell and awk only, with two exceptions: bib-fetch requires curl,
plus pdftotext (poppler) for DOI extraction from pdfs.

# Tests
    make test               # unit + integration suites
    make fuzz               # robustness fuzzing against bogus input