9 files changed, 474 insertions, 0 deletions
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)