Documentation

1 files changed, 49 insertions, 0 deletions

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)