From 9f01aaa6360d65f70b5ff8b31c2f79e7feb1ca94 Mon Sep 17 00:00:00 2001 From: "Douglas B. Rumbaugh" Date: Sat, 6 Jun 2026 13:46:14 -0400 Subject: HTML readme --- README.html | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 README.html (limited to 'README.html') diff --git a/README.html b/README.html new file mode 100644 index 0000000..d3daee2 --- /dev/null +++ b/README.html @@ -0,0 +1,130 @@ + + + + + +bibutils + + + + +

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

+ + + -- cgit v1.2.3