'\" t
.\" Title: BIBUTILS
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: November 8, 2016
.\" Manual: User Commands
.\" Source: bibutils 7.2
.\" Language: English
.\"
.TH "BIBUTILS" "1" "November 8, 2016" "bibutils 7\&.2" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bibutils \- bibliography conversion utilities
.SH "SYNOPSIS"
.HP \w'\fB\fIformat\fR\fR\fB2xml\fR\ 'u
\fB\fIformat\fR\fR\fB2xml\fR [\fIOPTIONS\fR] [\fIfile\&.format\fR]
.HP \w'\fBxml2\fR\fB\fIformat\fR\fR\ 'u
\fBxml2\fR\fB\fIformat\fR\fR [\fIOPTIONS\fR] [\fIfile\&.xml\fR]
.SH "DESCRIPTION"
.PP
The bibutils program set inter\-converts between various bibliography formats using
\m[blue]\fBLibrary of Congress\fR\m[]\&\s-2\u[1]\d\s+2\*(Aqs
\m[blue]\fBMetadata Object Description Schema (MODS)\fR\m[]\&\s-2\u[2]\d\s+2version 3\&.1\&. For example, one can convert RIS\-format files to Bibtex by doing two transformations: RIS\->MODS\->Bibtex\&.
.SH "CONVERTING TO MODS"
.SS "Overview"
.\" line length increase to cope w/ tbl weirdness
.ll +(\n(LLu * 62u / 100u)
.TS
ll.
\fICommand\fR \fIDescription\fR
T{
bib2xml
T} T{
convert bibtex to MODS
T}
T{
biblatex2xml
T} T{
convert biblatex to MODS
T}
T{
copac2xml
T} T{
convert \m[blue]\fBCOPAC\fR\m[]\&\s-2\u[3]\d\s+2format references to MODS
T}
T{
ebi2xml
T} T{
convert EBI XML to MODS
T}
T{
end2xml
T} T{
convert EndNote (Refer format) to MODS
T}
T{
endx2xml
T} T{
convert EndNote XML to MODS
T}
T{
isi2xml
T} T{
convert ISI web of science to MODS
T}
T{
med2xml
T} T{
convert Pubmed XML references to MODS
T}
T{
nbib2xml
T} T{
convert Pubmed nbib format references to MODS
T}
T{
modsclean
T} T{
a MODS to MODS converter
T}
T{
ris2xml
T} T{
convert RIS format to MODS
T}
T{
wordbib2xml
T} T{
convert Word2007 bibliography XML to MODS
T}
.TE
.\" line length decrease back to previous value
.ll -(\n(LLu * 62u / 100u)
.sp
.SS "Common Options Converting to MODS"
.PP
Several flags available for the end2xml, endx2xml, bib2xml, ris2xml, med2xml, and copac2xml programs\&. Most options have both a short and a long version\&.
.\" line length increase to cope w/ tbl weirdness
.ll +(\n(LLu * 62u / 100u)
.TS
lll.
T{
\-h
T} T{
\-\-help
T} T{
display help
T}
T{
\-v
T} T{
\-\-version
T} T{
display version
T}
T{
\-a
T} T{
\-\-add\-refcount
T} T{
add "_#", where # is reference count to reference id
T}
T{
\-s
T} T{
\-\-single\-refperfile
T} T{
put one reference per file name by the reference number
T}
T{
\-i
T} T{
\-\-input\-encoding
T} T{
interpret the input file as using the requested character set (use w/o argument for current list derived from character sets at \m[blue]\fBwww\&.kostis\&.net\fR\m[]\&\s-2\u[4]\d\s+2) unicode is now a character set option
T}
T{
\-u
T} T{
\-\-unicode\-characters
T} T{
encode unicode characters directly in the file rather than as XML entities
T}
T{
\-un
T} T{
\-\-unicode\-no\-bom
T} T{
as \-u, but don\*(Aqt include a byte order mark
T}
T{
\-x
T} T{
\-\-xml\-entities
T} T{
encode unicode characters as XML entities (opposite of \-u)
T}
T{
\-nl
T} T{
\-\-no\-latex
T} T{
do not convert latex\-style character combinations
T}
T{
\-s
T} T{
\-\-single\-refperfile
T} T{
one reference per output file
T}
T{
\-d
T} T{
\-\-drop\-key
T} T{
don\*(Aqt put citation key in the mods id field
T}
T{
\-c
T} T{
\-\-corporation\-file
T} T{
with argument specifying a file containing a list of corporation names to be placed in instead of type="personal" and eliminate name mangling
T}
T{
\-a
T} T{
\-\-asis
T} T{
with argument specifying a file containing a list of names to be treated verbatim
T}
T{
\-nt
T} T{
\-\-nosplit\-title
T} T{
don\*(Aqt split titles into TITLE/SUBTITLE pairs
T}
T{
T} T{
\-\-verbose
T} T{
verbose output
T}
T{
T} T{
\-\-debug
T} T{
very verbose output (mostly for debugging)
T}
.TE
.\" line length decrease back to previous value
.ll -(\n(LLu * 62u / 100u)
.sp
.SS "bib2xml"
.PP
\fBbib2xml\fR
converts a bibtex\-formatted reference file to an XML\-intermediate bibliography file\&. Specify file(s) to be converted on the command line\&. Files containing bibtex substitutions strings should be specified before the files where substitutions are specified (or in the same file before their use)\&. If no files are specified, then bibtex information will be read from standard input\&.
.sp
.if n \{\
.RS 4
.\}
.nf
bib2xml bibtex_file\&.bib > output_file\&.xml
.fi
.if n \{\
.RE
.\}
.SS "biblatex2xml"
.PP
\fBbiblatex2xml\fR
converts a biblatex (not to be confused with bibtex) formatted reference file to an MODS XML\-intermediate bibliography file\&.
.sp
.if n \{\
.RS 4
.\}
.nf
biblatex2xml biblatex_file\&.bib > outputfile\&.xml
.fi
.if n \{\
.RE
.\}
.SS "copac2xml"
.PP
\fBcopac2xml\fRconverts a COPAC formatted reference file to a MODS XML\-intermediate bibliography file\&.
.SS "end2xml"
.PP
\fBend2xml\fR
converts a text endnote\-formatted reference file to an XML\-intermediate bibliography file\&. This program will not work on the binary library; the file needs to be exported first\&. Endnote tagged formats ("Refer" format export) look like
Example\ \&1, \(lqExample refer format file\(rq\&. There are very nice instructions for making sure that you are properly exporting this at
\m[blue]\fBhttp://www\&.sonnysoftware\&.com/endnoteimport\&.html\fR\m[]\&\s-2\u[5]\d\s+2
.PP
Usage for
\fBend2xml\fR
is the same as
\fBbib2xml\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
end2xml endnote_file\&.end > output_file\&.xml
.fi
.if n \{\
.RE
.\}
.SS "ebi2xml"
.PP
\fBebi2xml\fR
converts a EBI XML file to a MODS XML\-intermediate bibliography file\&.
.SS "endx2xml"
.PP
\fBendx2xml\fR
converts a EndNote\-XML exported reference file to a MODS XML\-intermediate bibliography file\&. This program will not work on the binary library; the file needs to be exported first\&.
.SS "isi2xml"
.PP
\fBisi2xml\fR
converts an ISI\-web\-of\-science\-formatted reference file to an XML\-intermediate bibliography file\&.
.PP
Usage for
\fBisi2xml\fR
is the same as
\fBbib2xml\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
isi2xml input_file\&.isi > output_file\&.xml
.fi
.if n \{\
.RE
.\}
.SS "ris2xml"
.PP
\fBris2xml\fR
converts a RIS\-formatted reference file to an XML\-intermediate bibliography file\&.
\fBris2xml\fR
usage is as
\fBend2xml\fR
and
\fBbib2xml\fR
.sp
.if n \{\
.RS 4
.\}
.nf
ris2xml ris_file\&.ris > output_file\&.xml
.fi
.if n \{\
.RE
.\}
.SS "wordbib2xml"
.PP
\fBwordbib2xml\fR
convert a Word2007\-formatted reference file to an XML\-intermediate bibliogrpahy file\&.
.SH "CONVERTING FROM MODS"
.SS "Overview"
.\" line length increase to cope w/ tbl weirdness
.ll +(\n(LLu * 62u / 100u)
.TS
ll.
\fICommand\fR \fIDescription\fR
T{
xml2ads
T} T{
convert MODS into the SAO/NASA ADS format
T}
T{
xml2bib
T} T{
convert MODS into bibtex
T}
T{
xml2end
T} T{
convert MODS into format for EndNote
T}
T{
xml2isi
T} T{
convert MODS to ISI format
T}
T{
xml2ris
T} T{
convert MODS into RIS format
T}
T{
xml2wordbib
T} T{
convert MODS into Word 2007 bibliography format
T}
.TE
.\" line length decrease back to previous value
.ll -(\n(LLu * 62u / 100u)
.sp
.SS "Common Options Converting from MODS"
.PP
Note that
\fI\-\-output\-encoding\fR
refers to the input file
.\" line length increase to cope w/ tbl weirdness
.ll +(\n(LLu * 62u / 100u)
.TS
lll.
T{
\-h
T} T{
\-\-help
T} T{
display help
T}
T{
\-v
T} T{
\-\-version
T} T{
display version
T}
T{
\-o
T} T{
\-\-output\-encoding
T} T{
interpret the input file as using the requested character set (use w/o argument for current list derived from character sets at \m[blue]\fBwww\&.kostis\&.net\fR\m[]\&\s-2\u[4]\d\s+2) unicode is now a character set option
T}
T{
\-s
T} T{
\-\-single\-refperfile
T} T{
put one reference per file name by the reference number
T}
T{
\-nb
T} T{
\-\-no\-bom
T} T{
do not write Byte Order Mark if writing UTF8
T}
.TE
.\" line length decrease back to previous value
.ll -(\n(LLu * 62u / 100u)
.sp
.SS "xml2bib"
.PP
\fBxml2bib\fR
converts the MODS XML bibliography into a bibtex\-formatted reference file\&.
\fBxml2bib\fR
usage is as for other tools
.sp
.if n \{\
.RS 4
.\}
.nf
xml2bib xml_file\&.xml > output_file\&.bib
.fi
.if n \{\
.RE
.\}
.PP
Since the BibTeX reference format is fairly flexible and seems to have the greatest number of personal preferences, it has also accumulated a number of specific options that are not available for other formats\&.
.PP
Starting with 3\&.24, xml2bib output uses lowercase tags and mixed case reference types for better interaction with other software\&. The older behavior with all uppercase tags/reference types can still be generated using the command\-line switch \-U/\-\-uppercase\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBxml2bib-specific Options:\fR
.RS 4
.\" line length increase to cope w/ tbl weirdness
.ll +(\n(LLu * 62u / 100u)
.TS
lll.
T{
\-fc
T} T{
\-\-finalcomma
T} T{
add final comma in the bibtex output for those that want it
T}
T{
\-sd
T} T{
\-\-singledash
T} T{
use one dash instead of two (longer dash in latex) between numbers in page output
T}
T{
\-b
T} T{
\-\-brackets
T} T{
use brackets instead of quotation marks around field data
T}
T{
\-w
T} T{
\-\-whitespace
T} T{
add beautifying whitespace to output
T}
T{
\-U
T} T{
\-\-uppercase
T} T{
use all uppercase for tags (field names) and reference types (pre\-3\&.24 behavior)
T}
T{
\-sk
T} T{
\-\-strictkey
T} T{
only use alphanumeric characters for bibtex citation keys
T}
.TE
.\" line length decrease back to previous value
.ll -(\n(LLu * 62u / 100u)
.sp
.RE
.SS "xml2ads"
.PP
\fBxml2ads\fR
converts the MODS XML bibliography to the Smithsonian Astrophysical Observatory (SAO)/National Aeronautics and Space Administration (NASA) Astrophyics Data System or
\m[blue]\fBADS reference format\fR\m[]\&\s-2\u[6]\d\s+2
(which is very similar to the tagged Endnote style)\&.
\fBxml2ads\fR
usage is as for other tools
.sp
.if n \{\
.RS 4
.\}
.nf
xml2ads xml_file\&.xml > output_file\&.ads
.fi
.if n \{\
.RE
.\}
.SS "xml2ris"
.PP
\fBxml2ris\fR
converts the MODS XML bibliography to RIS\-formatted bibliography file\&.
\fBxml2ris\fR
usage is as for other tools
.sp
.if n \{\
.RS 4
.\}
.nf
xml2ris xml_file\&.xml > output_file\&.ris
.fi
.if n \{\
.RE
.\}
.SS "xml2end"
.PP
\fBxml2end\fR
converts the MODS XML bibliography to tagged Endnote (refer\-format) bibliography file\&.
\fBxml2end\fR
usage is as for other tools
.sp
.if n \{\
.RS 4
.\}
.nf
xml2end xml_file\&.xml > output_file\&.end
.fi
.if n \{\
.RE
.\}
.SS "xml2wordbib"
.PP
\fBxml2wordbib\fR
converts the MODS XML bibliography to Word 2007\-formatted XML bibliography file\&.
\fBxml2wordbib\fR
usage is as for other tools
.sp
.if n \{\
.RS 4
.\}
.nf
xml2wordbib xml_file\&.xml > output_file\&.word\&.xml
.fi
.if n \{\
.RE
.\}
.PP
\fBxml2wordbib\fR
was called xml2word in versions of bibutils prior to 3\&.40\&. It was renamed to avoid confusion with other tools\&. Hopefully this will not break too many scripts already in use\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Example refer format file\fR
.sp
.if n \{\
.RS 4
.\}
.nf
%0 Journal Article
%A C\&. D\&. Putnam
%A C\&. S\&. Pikaard
%D 1992
%T Cooperative binding of the Xenopus RNA polymerase I
transcription factor xUBF to repetitive ribosomal gene enhancers
%J Mol Cell Biol
%V 12
%P 4970\-4980
%F Putnam1992
.fi
.if n \{\
.RE
.\}
.SS "xml2bib Output Variations"
.PP
\fBExample\ \&2.\ \&Default\fR
.sp
.if n \{\
.RS 4
.\}
.nf
@Article{Putnam1992,
author="C\&. D\&. Putnam
and C\&. S\&. Pikaard",
year="1992",
month="Nov",
title="Cooperative binding of the
Xenopus RNA polymerase I transcription
factor xUBF to repetitive ribosomal
gene enhancers",
journal="Mol Cell Biol",
volume="12",
pages="4970\-\-4980",
number="11"}
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&3.\ \&Final Comma\fR
.sp
.if n \{\
.RS 4
.\}
.nf
@Article{Putnam1992,
author="C\&. D\&. Putnam
and C\&. S\&. Pikaard",
year="1992",
month="Nov",
title="Cooperative binding of the
Xenopus RNA polymerase I transcription
factor xUBF to repetitive ribosomal
gene enhancers",
journal="Mol Cell Biol",
volume="12",
pages="4970\-\-4980",
number="11",}
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&4.\ \&Single Dash\fR
.sp
.if n \{\
.RS 4
.\}
.nf
@Article{Putnam1992,
author="C\&. D\&. Putnam
and C\&. S\&. Pikaard",
year="1992",
month="Nov",
title="Cooperative binding of the
Xenopus RNA polymerase I transcription
factor xUBF to repetitive ribosomal
gene enhancers",
journal="Mol Cell Biol",
volume="12",
pages="4970\-4980",
number="11"}
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&5.\ \&Whitespace\fR
.sp
.if n \{\
.RS 4
.\}
.nf
@Article{Putnam1992,
author = "C\&. D\&. Putnam
and C\&. S\&. Pikaard",
year = "1992",
month = "Jan",
title = "Cooperative binding of
the Xenopus RNA polymerase I transcription
factor xUBF to repetitive ribosomal gene
enhancers",
journal = "Mol Cell Biol",
volume = "12",
pages = "4970\-\-4980"
}
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&6.\ \&Brackets\fR
.sp
.if n \{\
.RS 4
.\}
.nf
@Article{Putnam1992,
author={Putnam, C\&. D\&.
and Pikaard, C\&. S\&.},
title={Cooperative binding of the Xenopus
RNA polymerase I transcription factor xUBF
to repetitive ribosomal gene enhancers},
journal={Mol Cell Biol},
year={1992},
month={Nov},
volume={12},
number={11},
pages={4970\-\-4980}
}
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&7.\ \&Uppercase\fR
.sp
.if n \{\
.RS 4
.\}
.nf
@ARTICLE{Putnam1992,
AUTHOR="Putnam, C\&. D\&.
and Pikaard, C\&. S\&.",
TITLE="Cooperative binding of the Xenopus
RNA polymerase I transcription factor xUBF
to repetitive ribosomal gene enhancers",
JOURNAL="Mol Cell Biol",
YEAR="1992",
MONTH="Nov",
VOLUME="12",
NUMBER="11",
PAGES="4970\-\-4980"
}
.fi
.if n \{\
.RE
.\}
.SH "LICENSE"
.PP
All versions of bibutils are released under the GNU General Public License (GPL)\&. In a nutshell, feel free to download, run, and modify these programs as required\&. If you re\-release these, you need to release the modified version of the source\&. (And I\*(Aqd appreciate patches as well\&.\&.\&.if you care enough to make the change, then I\*(Aqd like to see what you\*(Aqre adding or fixing\&.)
.PP
\m[blue]\fBChris Putnam, Ludwig Institute for Cancer Research\fR\m[]\&\s-2\u[7]\d\s+2
.SH "COPYRIGHT"
.br
Copyright \(co 2021 David Bremner (Manual)
.br
Copyright \(co 2021 Christopher Putnam (Software and Manual)
.br
.PP
This manual page is distributed under the terms of version 2 of the GNU General Public License\&.
.sp
.SH "NOTES"
.IP " 1." 4
Library of Congress
.RS 4
\%http://www.loc.gov
.RE
.IP " 2." 4
Metadata Object Description Schema (MODS)
.RS 4
\%http://www.loc.gov/standards/mods/
.RE
.IP " 3." 4
COPAC
.RS 4
\%http://copac.ac.uk/
.RE
.IP " 4." 4
www.kostis.net
.RS 4
\%http://www.kostis.net/
.RE
.IP " 5." 4
http://www.sonnysoftware.com/endnoteimport.html
.RS 4
\%http://www.sonnysoftware.com/endnoteimport.html
.RE
.IP " 6." 4
ADS reference format
.RS 4
\%http://doc.adsabs.harvard.edu/abs_doc/help_pages/taggedformat.html
.RE
.IP " 7." 4
Chris Putnam, Ludwig Institute for Cancer Research
.RS 4
\%http://www.sourceforge.net/p/bibutils/home/Bibutils
.RE