.\" BibTeX Converter
.\" Copyright (C) 2010-2024 by Thomas Dreibholz
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Contact: thomas.dreibholz@gmail.com
.\"
.\" ###### Setup ############################################################
.Dd November 10, 2023
.Dt bibtexconv 1
.Os bibtexconv
.\" ###### Name #############################################################
.Sh NAME
.Nm bibtexconv
.Nd BibTeX Converter
.\" ###### Synopsis #########################################################
.Sh SYNOPSIS
.Nm bibtexconv
BibTeX_file
.Op Fl export-to-bibtex=file
.Op Fl export-to-separate-bibtexs=prefix
.Op Fl export-to-xml=file
.Op Fl export-to-separate-xmls=prefix
.Op Fl nbsp=string
.Op Fl linebreak=string
.Op Fl non-interactive
.Op Fl check-urls
.Op Fl only-check-new-urls
.Op Fl store-downloads=directory
.Op Fl add-url-command
.Op Fl skip-notes-with-isbn-and-issn
.Op Fl add-notes-with-isbn-and-issn
.\" ###### Description ######################################################
.Sh DESCRIPTION
.Nm bibtexconv
is a BibTeX file converter which allows one to export BibTeX entries to other
formats, including customly defined text output. Furthermore, it provides the
possibility to check URLs (including MD5, size and MIME type computations) and
to verify ISBN and ISSN numbers.
.br
bibtexconv provides an interactive mode (usually used in form of export
scripts) which allows for fine-granular selection of entries, sorting and
export template specification.
.Pp
.\" ###### Arguments ########################################################
.Sh OPTIONS
The following arguments may be provided:
.Bl -tag -width indent
.It BibTeX_File
The BibTeX input file.
.It Fl export-to-bibtex=file
Write the results as BibTeX into the given file.
.It Fl export-to-separate-bibtexs=prefix
Write the results as BibTeX; for each entry, an own file will be created. The filename will be generated from given prefix (e.g. "/tmp/MyBibTex-"), the entry key and ".bib".
.It Fl export-to-xml=file
Write the results as XML (as used by IETF Internet Draft processing tools)
into the given file.
.It Fl export-to-separate-xmls=prefix
Write the results as XML; for each entry, an own file will be created. The filename will be generated from given prefix (e.g. "/tmp/MyBibTex-"), the entry key and ".xml".
.It Fl nbsp=string
Replace non-breakable space by given string (for example, "&nbsp;" when writing HTML).
.It Fl linebreak=string
Replace linebreak by given string (for example, "<br />" when writing HTML).
.It Fl check-urls
Check URLs by downloading the content file and adding MD5, size and MIME type
entries.
.It Fl only-check-new-urls
Combined with \-check-urls, checks are only performed for new entries where
MD5, size and/or MIME type are still unknown.
.It Fl store-downloads=directory
Combined with \-check-urls, all checked references are downloaded and stored in the given directory. Existing files will be overwritten.
.It Fl add-url-command
Add \\url{} commands to url tags in BibTeX export.
.It Fl skip-notes-with-isbn-and-issn
When reading the BibTeX file, ignore "note" items with ISBN and ISSN.
.It Fl add-notes-with-isbn-and-issn
When writing a BibTeX file, create "note" items with ISBN and ISSN.
.It Fl non-interactive
Turns on non-interactive mode. Useful for just performing URL checks and
ISBN/ISSN verification.
.El
.\" ###### Commands #########################################################
.Sh COMMANDS
After startup, bibtexconv accepts the following commands from standard input
(not as command-line arguments!):
.Bl -tag -width ident
.It cite key custom1 custom2 custom3 custom4 custom5
Select specific entry in the input BibTeX file, given by key. Optionally, up
to five custom strings may be attached to the selected entry.
.It citeAll
Select all entries in the input BibTeX file.
.It clear
Clear all selections.
.It echo string
Write given string to standard output.
.It export
Export selected entries to standard output, according to configured printing
template.
.It header
.It include file
Include another export script, given by file name.
.It monthNames jan feb mar apr may jun jul aug sep oct nov dec
Changes textual representation of month names. This is necessary when
non-English names are required for export.
.It nbsp
Changes textual representation of the "non-breakable space", for example
&nbsp; in HTML or ~ in BibTeX.
.It sort
.It template
.It template+
.It templatenew
.It trailer
.It utf8Style
.It xmlStyle
.El
.Pp
.\" ###### Arguments ########################################################
.Sh EXAMPLES
Have a look into /usr/share/doc/bibtexconv/examples/ (or corresponding path of your
system) for example export scripts. The export scripts contain the commands
which are read by bibtexconv from standard input.
.Bl -tag -width indent
.It bibtexconv \e
.br
/usr/share/doc/bibtexconv/examples/ExampleReferences.bib \e
.br
\-export-to-bibtex=UpdatedReferences.bib \e
.br
\-check-urls \-only-check-new-urls \-non-interactive
.br
Checks URLs of all entries in /usr/share/doc/bibtexconv/examples/ExampleReferences.bib, adds MD5, size and MIME type
items and writes the results to UpdatedReferences.bib.
.It bibtexconv \e
.br
/usr/share/doc/bibtexconv/examples/ExampleReferences.bib \e
.br
</usr/share/doc/bibtexconv/examples/web-example.export >MyPublications.html
.br
Uses export script /usr/share/doc/bibtexconv/examples/web-example.export to export references from /usr/share/doc/bibtexconv/examples/ExampleReferences.bib to MyPublications.html as XHTML 1.1.
.It bibtexconv \e
.br
/usr/share/doc/bibtexconv/examples/ExampleReferences.bib \e
.br
</usr/share/doc/bibtexconv/examples/text-example.export >MyPublications.txt
.br
Uses export script /usr/share/doc/bibtexconv/examples/text-example.export to export references from /usr/share/doc/bibtexconv/examples/ExampleReferences.bib to MyPublications.txt as plain text.
.It bibtexconv \e
.br
/usr/share/doc/bibtexconv/examples/ExampleReferences.bib \e
.br
\-non-interactive \-export-to-separate-xmls=reference.
.br
Convert all references to XML references to be includable in IETF Internet Drafts. For each reference, an own file is generated, named with the prefix "reference.", for example reference.Globecom2010.xml for entry Globecom2010.
.It bibtexconv \e
.br
/usr/share/doc/bibtexconv/examples/ExampleReferences.bib \e
.br
\-non-interactive \-export-to-separate-bibtexs=
.br
Convert all references to BibTeX references. For each reference, an own file is generated, named with the prefix "", for example Globecom2010.bib for entry Globecom2010.
.El