Documentation

1 files changed, 68 insertions, 0 deletions

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)