Documentation

1 files changed, 49 insertions, 0 deletions

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)