A script to add a webpage
BibTeX entry type, and add
support for general url
and lastchecked
fields, to (most) BibTeX .bst
files. Optionally adds
basic support for eprint
, doi
and pubmed
fields, and
hypertex/hyperref support.
The Persistent URL for this page is
http://purl.org/nxg/dist/urlbst
.
Version @PACKAGE_VERSION@, @RELEASEDATE@.
Contents
The standard BibTeX styles have no explicit support for the web, in that they include no `webpage' type, and have no support for adding URLs to references. There are rumours that such support might appear in BibTeX 1.0, but there is no estimate of when that is likely to arrive.
The Perl script urlbst
can be used to add this support to an
arbitrary .bst
file which has a reasonably `conventional'
structure. The result is meant to be robust rather than pretty.
It has a different goal from Patrick Daly's `custom-bib' package -- that is intended to create a BibTeX style .bst file from scratch, and supports `url' and `eprint' fields. This package, on the other hand, is intended for the case where you already have a style file that works (or at least, which you cannot or will not change), and edits it to add the new webpage entry type, plus the url, lastchecked and eprint fields. Fuller details are in the manual.
urlbst [--[no]eprint] [--[no]doi] [--[no]pubmed] [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] [--literal key=value] [input-file [output-file]]
If either the input-file or the output-file is omitted, they
default to stdin and stdout respectively. If the input file already
has a URL entry type, then the script objects.
By default (in the current version), the output
includes support for eprint, doi and pubmed, but these can be disabled
by --noeprint
, --nodoi
and
--nopubmed
, respectively.
The added fields are:
url
and lastchecked
, to associate a URL with
a reference, along with the date at which the URL was last checked
to exist;doi
, for a reference's DOI;eprint
, for an arXiv eprint reference; andpubmed
for a reference's
PubMed identifier (PMID).If either of the --hypertex
or --hyperref
options is present, then the generated .bst
file includes
support for hyperlinks in the generated eprint entries in the
bibliography, with the format being either HyperTeX (see arXiv, again),
supported by xdvi, dvips and others, or using the support available
from the hyperref package. These options have no effect unless one of
the --eprint
or --doi
options is given: when
URLs are included in the bibliography, they are written out using the
\url{...}
command, and hyperref automatically processes
that in the correct way to include a hyperlink.
The --inlinelinks
option tells urlbst not to write out
the URL as text within the bibliography entry. Instead, urlbst will
produce a more conventional-looking and compact bibliography entry,
but the entry's title will now be a hyperlink to that URL. This
hyperlink may be useful to anyone who reads your document online
(this option can only be used with --hyperref
or
--hypertex
). Any DOI or eprint text which would be
produced as a result of the appropriate option will still appear in
this mode.
You may adjust various literal strings, either for the purposes of
internationalisation, or simply because you prefer different text. To
do this, give the --literal
option, followed by a
key=value
pair, for example --literal online="on
th'intert00bs"
, to replace the default URL:
text.
The possible values, and their defaults, are below (say
--literal help
to get this list printed out):
keyword | default | meaning |
---|---|---|
cited | cited | indicator of citation, or "last checked", date |
doiprefix | doi: | text printed before DOI |
eprintprefix | arXiv: | text printed before eprint ref |
linktext | [link] | fallback link text |
pubmedprefix | PMID: | text printed before PUBMED reference |
online | online | indication that resource is online |
urlintro | URL: | location of online resource (an alternative is "Available from:") |
The distribution includes preconverted versions of the four standard BibTeX .bst style files.
Only the style files which result from conversion of the standard styles are checked in the regression tests. Other style files which are known to work include
acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, siam.bst, mla.bst
Style files which are known to fail:
achicago.bst
which seems to fox urlbst
; it turns out that there's a
simpler but almost equivalent style chicago.bst
which
works.apager.bst
,
seem to be sufficiently different from the most common styles, that
they confuse urlbst
completely..bbl
files, and
urlbst
does not aim to produce anything useful from these.This might be a good time for me to revisit the rather convoluted logic within the script, to make it a little more robust in the face of variants like these, but don't hold your breath. The logic within the script is pretty hideous (it essentially works by spotting patterns in the input style file, and replacing or extending bits of BibTeX style-file code. This is a fragile technique, and is probably at the limits of its usefulness, therefore I'd take some persuading to add significant extra functionality to the script.
The natbib and revtex style files already have URL fields. If you have a BibTeX style file which you think ought to work, but with which the script fails, send it to me, and I'll try to work out what I've missed (no promises, though).
Note that the command to invoke the script changed from `urlbst.pl' to plain `urlbst' between versions 0.3 and 0.4.
To add URL support to the standard siam.bst
file, you
can give the command
% urlbst /path/to/original/siam.bst siamurl.bst
Your TeX installation will likely have some way of helping you find where
the original .bst
files are. On teTeX-based systems, for
example, the command kpsewhich siam.bst
returns the full
path of the siam.bst
file which BibTeX would find.
The distributed files abbrvurl.bst
,
alphaurl.bst
, plainurl.bst
and
unsrturl.bst
are versions of the standard style files
which have been pre-converted.
There is more general discussion of including URLs in bibliographies in the UK TeX FAQ.
Download the file as a tarball or zip file and unpack it. Or you can clone the source repository at bitbucket.org.
To install, you should simply copy the distributed
urlbst
script to someplace on the path (such as
/usr/local/bin
, or ~/local/bin
, depending on
your privileges and tastes).
If you (might) want to use the pre-converted standard
.bst
files, then you'll need to copy these to somewhere
in the BibTeX search path. Type kpsepath bst on Unix to
find out the list of places BibTeX searches, and pick either one of
the user-local locations, or a system-wide one. If you're installing
in a system-wide location, you'll need admin privileges, obviously,
and you will probably need to use texhash
,
mktexlsr
or its equivalent, to update LaTeX's filename
cache. For further hints here, see
the TeX FAQ entries on installing a package and where LaTeX puts files.
That should be all you have to do.
The urlbst script is distributed with a path which should just work, as long as the Perl binary is in your path, but if you have problems here, then you might want to change the first line to something like
#! /usr/local/bin/perl
if that's where your Perl binary is.
You can also use the conventional ./configure; make; make
install
to configure and install the package (as root, or using
sudo
if you're installing it in a system location),
though you still have to install the .bst
files by hand.
This is rather heavyweight for the trivial amount of configuration
required, so it's almost always simpler just to do things by hand.
If you need to change some of the urlbst
defaults,
however, or if your fingers type ./configure
spontaneously, then you can be reassured that the configure script
supports the standard --prefix
option, plus the following
options setting defaults:
--with-eprints=url
, --without-eprints
--eprints
option to urlbst available
by default, and allows you to optionally specify a prefix for creating
URLs from eprint numbers. The default for this URL is
http://arxiv.org/abs/
-- this is appropriate for arXiv,
obviously, but there are now a variety of other preprint archives
appearing, for which this might be inappropriate. If you have
comments on this default, or alternatives, please let me know. This
option is enabled by default; if you have some reason for disabling
the --eprints
option for urlbst, the give the configure
option --without-eprints
--with-doi=url
, --without-doi
--doi
option to urlbst and,
as with the --with-eprints
option, allows you to
customise the DOI resolver URL. The --doi
option to
urlbst is on by default.--with-href=0/1/2
--with-href=0
. The
hyperref
-style option is intended to complement the
increasingly standard hyperref
package.The first two options simply change defaults, and if you never use
the new eprints
or doi
fields, then the
defaults don't matter to you.
Since the modified style generates URLs wrapped in the
\url{}
macro, it is useful to use the resulting
bibliography style alongside the url
package. Since this
tends to work with hyperref
anyway, where possible, you
don't get any extra goodness by changing the --with-href
default at configuration time.
Basic documentation is in the file urlbst.tex
. This
is distributed as a PDF file, but if you want to regenerate it, use
% latex urlbst % bibtex urlbst % latex urlbst % latex urlbst
urlbst
is archived on CTAN at biblio/bibtex/contrib/urlbst/
, and discussed in the
TeX
FAQ.
The source code for the package is maintained at bitbucket.org, which also includes an issue tracker, where you can report bugs (or just mail me).
The home page of urlbst might possibly have more recent versions than the one you're looking at now.
Thanks are due to many people for suggestions and requests, and to 'ijvm' for code contributions.
Copyright 2002-11, Norman Gray. Released under the terms of the GNU General Public Licence.
--literal
.*url.bst
no longer have the
--inlinelinks
option turned on by default.Added the option --inlinelinks
, which adds inline hyperlinks
to any bibliography entries which have URLs, but does so inline, rather
than printing the URL explicitly in the bibliography. This is (primarily)
useful if you're preparing a version of a document which will be read
on-screen. Thanks to Jason Eisner for the suggestion, and much testing.
Incorporate hyperref bugfixes from Paweł Widera.
inlinelinks
support; should now be more
robust. Incorporate hyperref bugfixes from Paweł Widera.inlinelinks
, which adds inline hyperlinks
to any bibliography entries which have URLs, but does so inline, rather
than printing the URL explicitly in the bibliography. This is (only)
useful if you're preparing a version of a document which will be read
on-screen../configure
(optionally). Assorted reorganisation.