From 4aec9800fca665713b0eba19f10af927b483332e Mon Sep 17 00:00:00 2001
From: "Douglas B. Rumbaugh" <doug@douglasrumbaugh.com>
Date: Sat, 6 Jun 2026 12:17:21 -0400
Subject: Documentation

---
 man/bib-convert.1 | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 man/bib-convert.1

(limited to 'man/bib-convert.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)
-- 
cgit v1.2.3