diff options
| -rw-r--r-- | Makefile | 9 | ||||
| -rw-r--r-- | README.md | 3 | ||||
| -rw-r--r-- | man/bib-add.1 | 45 | ||||
| -rw-r--r-- | man/bib-check.1 | 49 | ||||
| -rw-r--r-- | man/bib-convert.1 | 68 | ||||
| -rw-r--r-- | man/bib-extract.1 | 49 | ||||
| -rw-r--r-- | man/bib-fetch.1 | 61 | ||||
| -rw-r--r-- | man/bib-gen.1 | 61 | ||||
| -rw-r--r-- | man/bib-key.1 | 39 | ||||
| -rw-r--r-- | man/bib-ls.1 | 40 | ||||
| -rw-r--r-- | man/bib-util.1 | 62 |
11 files changed, 485 insertions, 1 deletions
@@ -1,12 +1,16 @@ PREFIX = /usr/local BINDIR = $(PREFIX)/bin LIBDIR = $(PREFIX)/share/bibutils +MANDIR = $(PREFIX)/share/man/man1 SCRIPTS = bib-util bib-add bib-check bib-convert bib-extract bib-fetch \ bib-gen bib-key bib-ls LIBS = lib/bib-parse.awk lib/bib-canon.awk lib/bib-select.awk \ lib/bib-lskeys.awk lib/bib-key.awk lib/bib-ls.awk \ lib/bib-check.awk lib/bib2ref.awk lib/ref2bib.awk +MANPAGES = man/bib-util.1 man/bib-add.1 man/bib-check.1 man/bib-convert.1 \ + man/bib-extract.1 man/bib-fetch.1 man/bib-gen.1 man/bib-key.1 \ + man/bib-ls.1 all: @echo "nothing to build; run 'make test' or 'make install'" @@ -16,12 +20,15 @@ test: tests/integration.sh install: - -mkdir -p $(BINDIR) $(LIBDIR) + -mkdir -p $(BINDIR) $(LIBDIR) $(MANDIR) cp $(SCRIPTS) $(BINDIR) cp $(LIBS) $(LIBDIR) + cp $(MANPAGES) $(MANDIR) uninstall: cd $(BINDIR) && rm -f $(SCRIPTS) + cd $(MANDIR) && rm -f bib-util.1 bib-add.1 bib-check.1 bib-convert.1 \ + bib-extract.1 bib-fetch.1 bib-gen.1 bib-key.1 bib-ls.1 rm -rf $(LIBDIR) .PHONY: all test install uninstall @@ -60,6 +60,9 @@ 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. diff --git a/man/bib-add.1 b/man/bib-add.1 new file mode 100644 index 0000000..5c7a674 --- /dev/null +++ b/man/bib-add.1 @@ -0,0 +1,45 @@ +.TH BIB-ADD 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-add \- insert bibtex entries into a database file +.SH SYNOPSIS +.B bib-add +.RB [ \-f ] +.I db.bib +.SH DESCRIPTION +.B bib-add +reads one or more fully formatted bibtex entries on standard input and +appends them to the database file +.IR db.bib , +creating it if necessary. +Entries are canonicalized on the way in: entry types and field names +are lowercased, values are brace-delimited with internal whitespace +collapsed, bare numbers are left bare, and macro references and +.B # +concatenations are preserved verbatim. +.PP +If an incoming entry's key already exists in the database, the entry is +rejected and the duplicate keys are reported on standard error, unless +.B \-f +is given. +.SH OPTIONS +.TP +.B \-f +Replace existing entries that share a key with an incoming entry. +The database is rewritten canonically in the process. +.SH EXIT STATUS +0 on success, 1 if no entries were read or a duplicate key was +rejected, 2 on usage error. +.SH ENVIRONMENT +.TP +.B BIBUTILS_LIB +Directory holding the shared awk library, overriding the default +search (lib/ next to the script, then /usr/local/share/bibutils). +.SH EXAMPLES +Add a fetched entry to a database: +.nf +bib-fetch paper.pdf | bib-add refs.bib +.fi +.SH SEE ALSO +.BR bib-gen (1), +.BR bib-key (1), +.BR bib-util (1) diff --git a/man/bib-check.1 b/man/bib-check.1 new file mode 100644 index 0000000..c48c0f7 --- /dev/null +++ b/man/bib-check.1 @@ -0,0 +1,49 @@ +.TH BIB-CHECK 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-check \- lint a bibtex database +.SH SYNOPSIS +.B bib-check +.RI [ file " ...]" +.SH DESCRIPTION +.B bib-check +reads bibtex databases from the named files (or standard input) and +reports problems on standard output, one per line, in the form +.IR key ": " problem . +The following are detected: +.TP +.B missing required fields +Each standard entry type has a set of required fields (for an article: +author, title, journal and year; for a book: author or editor, title, +publisher and year; and so on). +Entry types with no conventional requirements, such as +.BR @misc , +are not checked. +.TP +.B duplicate keys +Two entries sharing a citation key. +.TP +.B duplicate titles +Two entries whose titles are identical after case folding and removal +of non-alphanumeric characters \(em usually the same work entered +twice under different keys. +.TP +.B empty fields +Fields whose value is empty or only whitespace. +.SH EXIT STATUS +0 if the database is clean, 1 if any problem was found. +This makes +.B bib-check +usable as a pre-commit hook or CI gate. +.SH ENVIRONMENT +.TP +.B BIBUTILS_LIB +Directory holding the shared awk library, overriding the default +search (lib/ next to the script, then /usr/local/share/bibutils). +.SH EXAMPLES +.nf +bib-check refs.bib && echo clean +.fi +.SH SEE ALSO +.BR bib-ls (1), +.BR bib-util (1), +.BR bibtex (1) diff --git a/man/bib-convert.1 b/man/bib-convert.1 new file mode 100644 index 0000000..ce14279 --- /dev/null +++ b/man/bib-convert.1 @@ -0,0 +1,68 @@ +.TH BIB-CONVERT 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-convert \- convert between bibtex and refer database formats +.SH SYNOPSIS +.B bib-convert +.RB [ \-b +| +.BR \-r ] +.RI [ file ] +.SH DESCRIPTION +.B bib-convert +reads a bibliographic database from +.I file +(or standard input) and writes it on standard output in the other +format: bibtex input produces +.BR refer (1) +records, refer input produces canonical bibtex entries with citation +keys generated as by +.BR bib-key (1). +.PP +Without a flag the direction is detected from the input: text whose +first record starts with +.B @ +is taken as bibtex, with +.B % +as refer. +.PP +When converting refer records to bibtex, the entry type is guessed +from the fields present: a journal +.RB ( %J ) +gives an article, a book title +.RB ( %B ) +an inproceedings or incollection, a report number +.RB ( %R ) +a techreport, a bare publisher +.RB ( %I ) +a book, and anything else a misc. +Page ranges are translated between +.B \- +and +.B \-\- +conventions. +The mapping is necessarily lossy in both directions; fields with no +counterpart are dropped. +.SH OPTIONS +.TP +.B \-b +Force refer-to-bibtex conversion. +.TP +.B \-r +Force bibtex-to-refer conversion. +.SH EXIT STATUS +0 on success, 1 if the input format cannot be detected, 2 on usage +error. +.SH ENVIRONMENT +.TP +.B BIBUTILS_LIB +Directory holding the shared awk library, overriding the default +search (lib/ next to the script, then /usr/local/share/bibutils). +.SH EXAMPLES +.nf +bib-convert refs.bib > refs.ref +bib-convert refs.ref | bib-add refs.bib +.fi +.SH SEE ALSO +.BR bib-key (1), +.BR bib-util (1), +.BR refer (1) diff --git a/man/bib-extract.1 b/man/bib-extract.1 new file mode 100644 index 0000000..340cf97 --- /dev/null +++ b/man/bib-extract.1 @@ -0,0 +1,49 @@ +.TH BIB-EXTRACT 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-extract \- emit only the database entries cited in a document +.SH SYNOPSIS +.B bib-extract +.I file.aux +.RI [ db.bib ] +.SH DESCRIPTION +.B bib-extract +collects the citation keys recorded in +.I file.aux +and filters the bibtex database given as +.I db.bib +(or read on standard input), emitting only the cited entries, in +canonical form, on standard output. +.PP +Both classic bibtex +.RB ( \[rs]citation ) +and biblatex/biber +.RB ( \[rs]abx@aux@cite ) +aux files are understood. +A citation of +.B * +(as produced by +.BR \[rs]nocite{*} ) +selects the entire database. +.B @string +and +.B @preamble +blocks always pass through. +.PP +roff/refer citation sources are planned but not yet supported. +.SH EXIT STATUS +0 on success (including no citations found), 1 if the aux file cannot +be read, 2 on usage error. +.SH ENVIRONMENT +.TP +.B BIBUTILS_LIB +Directory holding the shared awk library, overriding the default +search (lib/ next to the script, then /usr/local/share/bibutils). +.SH EXAMPLES +Produce a minimal database for submission alongside a paper: +.nf +bib-extract paper.aux master.bib > paper.bib +.fi +.SH SEE ALSO +.BR bib-ls (1), +.BR bib-util (1), +.BR bibtex (1) diff --git a/man/bib-fetch.1 b/man/bib-fetch.1 new file mode 100644 index 0000000..0d41f78 --- /dev/null +++ b/man/bib-fetch.1 @@ -0,0 +1,61 @@ +.TH BIB-FETCH 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-fetch \- fetch a bibtex entry for a pdf by DOI or arXiv id +.SH SYNOPSIS +.B bib-fetch +.RB [ \-d +.I doi +| +.B \-a +.IR arxiv-id ] +.RI [ file.pdf ] +.SH DESCRIPTION +.B bib-fetch +emits a bibtex entry, in canonical form and with a generated citation +key, for the document identified by a DOI or an arXiv id. +.PP +Unless an identifier is supplied with +.B \-d +or +.BR \-a , +the first two pages of +.I file.pdf +are searched (using +.BR pdftotext (1)) +for a DOI and, failing that, for an arXiv stamp of the form +.BR arXiv:2104.01234v2 . +Both modern and old-style +.RB ( cs/0101001 ) +arXiv ids are recognized. +.PP +DOIs are resolved through doi.org content negotiation (crossref and +friends); arXiv ids through arxiv.org. +Note that arXiv reports the year of the latest revision of a preprint, +not of its first submission. +.SH OPTIONS +.TP +.BI \-d " doi" +Fetch by DOI; no pdf is read. +.TP +.BI \-a " arxiv-id" +Fetch by arXiv id; no pdf is read. +A leading +.B arXiv: +prefix is accepted and stripped. +.SH EXIT STATUS +0 on success, 1 if no identifier could be found or the fetch failed, +2 on usage error. +.SH DEPENDENCIES +.BR curl (1) +always; +.BR pdftotext (1) +(poppler) for identifier extraction from pdfs. +.SH EXAMPLES +.nf +bib-fetch paper.pdf | bib-add refs.bib +bib-fetch -a 1706.03762 +.fi +.SH SEE ALSO +.BR bib-add (1), +.BR bib-key (1), +.BR bib-util (1) diff --git a/man/bib-gen.1 b/man/bib-gen.1 new file mode 100644 index 0000000..0a60ae8 --- /dev/null +++ b/man/bib-gen.1 @@ -0,0 +1,61 @@ +.TH BIB-GEN 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-gen \- generate a bibtex entry +.SH SYNOPSIS +.B bib-gen +.RB [ \-t +.IR type ] +.RI [ field = value " ...]" +.br +.B bib-gen +.RB [ \-t +.IR type ] +.B \-F +.IR field , field ,... +.SH DESCRIPTION +.B bib-gen +builds bibtex entries and emits them on standard output, with citation +keys generated as by +.BR bib-key (1). +It runs in one of three modes: +.TP +.B interactive +With no field arguments and no +.BR \-F , +the user is prompted for the entry type and then for each field +appropriate to that type. +Fields left empty are omitted. +.TP +.B argument +Each +.IR field = value +argument supplies one field of a single entry. +.TP +.B batch +With +.BR \-F , +one entry is generated per line of standard input. +Lines are split on tabs, with columns assigned to the listed fields +in order. +.SH OPTIONS +.TP +.BI \-t " type" +The bibtex entry type (default +.BR article ). +.TP +.BI \-F " field,field,..." +Enable batch mode with the given column-to-field mapping. +.SH EXIT STATUS +0 on success, 1 if no fields were supplied, 2 on usage error. +.SH EXAMPLES +.nf +bib-gen -t book author='D. E. Knuth' title='The TeXbook' \\ + publisher='Addison-Wesley' year=1984 | bib-add refs.bib + +printf 'A. Author\\tSome Title\\tSome Journal\\t1999\\n' | + bib-gen -F author,title,journal,year +.fi +.SH SEE ALSO +.BR bib-add (1), +.BR bib-key (1), +.BR bib-util (1) diff --git a/man/bib-key.1 b/man/bib-key.1 new file mode 100644 index 0000000..84fad10 --- /dev/null +++ b/man/bib-key.1 @@ -0,0 +1,39 @@ +.TH BIB-KEY 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-key \- generate citation keys for bibtex entries +.SH SYNOPSIS +.B bib-key +.RI [ file " ...]" +.SH DESCRIPTION +.B bib-key +reads bibtex entries from the named files (or standard input) and +emits them on standard output, in canonical form, with automatically +generated citation keys replacing the existing ones. +.PP +Keys have the form +.IR surname year word , +for example +.BR knuth1984literate : +the lowercased surname of the first author (or editor, if there is no +author), the four-digit year, and the first word of the title that is +not a common stopword. +When two entries produce the same key, subsequent ones are +disambiguated with +.BR b , +.BR c , +\&... suffixes. +.SH EXIT STATUS +0 on success. +.SH ENVIRONMENT +.TP +.B BIBUTILS_LIB +Directory holding the shared awk library, overriding the default +search (lib/ next to the script, then /usr/local/share/bibutils). +.SH EXAMPLES +.nf +bib-fetch -d 10.1093/comjnl/27.2.97 | bib-key +.fi +.SH SEE ALSO +.BR bib-add (1), +.BR bib-gen (1), +.BR bib-util (1) diff --git a/man/bib-ls.1 b/man/bib-ls.1 new file mode 100644 index 0000000..b0de33e --- /dev/null +++ b/man/bib-ls.1 @@ -0,0 +1,40 @@ +.TH BIB-LS 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-ls \- list the entries in a bibtex database +.SH SYNOPSIS +.B bib-ls +.RB [ \-l ] +.RI [ file " ...]" +.SH DESCRIPTION +.B bib-ls +reads bibtex databases from the named files (or standard input) and +lists their entries on standard output, one per line. +By default only the citation keys are printed. +.SH OPTIONS +.TP +.B \-l +Long format: print key, entry type, author, year and title, +tab-separated. +Author lists are abbreviated to the first author followed by +\(lqet al.\(rq, so that the output remains one line per entry and +pipes cleanly into +.BR grep (1), +.BR cut (1) +and +.BR sort (1). +.SH EXIT STATUS +0 on success. +.SH ENVIRONMENT +.TP +.B BIBUTILS_LIB +Directory holding the shared awk library, overriding the default +search (lib/ next to the script, then /usr/local/share/bibutils). +.SH EXAMPLES +Find everything by Lamport in a database: +.nf +bib-ls -l refs.bib | grep -i lamport +.fi +.SH SEE ALSO +.BR bib-check (1), +.BR bib-extract (1), +.BR bib-util (1) diff --git a/man/bib-util.1 b/man/bib-util.1 new file mode 100644 index 0000000..57b4572 --- /dev/null +++ b/man/bib-util.1 @@ -0,0 +1,62 @@ +.TH BIB-UTIL 1 "June 2026" "bibutils" "User Commands" +.SH NAME +bib-util \- wrapper for the bibutils bibtex tools +.SH SYNOPSIS +.B bib-util +.I command +.RI [ args " ...]" +.SH DESCRIPTION +.B bib-util +dispatches to the individual bibutils scripts, so that the whole suite +can be driven through a single entry point. +The +.I command +is one of the following; all remaining arguments are passed through +unchanged. +.TP +.B add +insert entries into a database; see +.BR bib-add (1) +.TP +.B check +lint a database; see +.BR bib-check (1) +.TP +.B convert +convert between bibtex and refer formats; see +.BR bib-convert (1) +.TP +.B extract +filter a database down to the entries cited in a document; see +.BR bib-extract (1) +.TP +.B fetch +fetch an entry for a pdf by DOI or arXiv id; see +.BR bib-fetch (1) +.TP +.B gen +generate an entry from user input; see +.BR bib-gen (1) +.TP +.B key +generate citation keys for entries; see +.BR bib-key (1) +.TP +.B ls +list the entries in a database; see +.BR bib-ls (1) +.SH EXIT STATUS +That of the dispatched command, or 2 if the command is unknown. +.SH EXAMPLES +.nf +bib-util fetch paper.pdf | bib-util add refs.bib +.fi +.SH SEE ALSO +.BR bib-add (1), +.BR bib-check (1), +.BR bib-convert (1), +.BR bib-extract (1), +.BR bib-fetch (1), +.BR bib-gen (1), +.BR bib-key (1), +.BR bib-ls (1) |