








                           UUrrllbbsstt



                          _A_B_S_T_R_A_C_T

          A script to add a wweebbppaaggee BibTeX entry type,
     and add support for general uurrll and llaassttcchheecckkeedd
     fields, to (most) BibTeX ..bbsstt files.  Optionally
     adds basic support for eepprriinntt , ddooii and ppuubbmmeedd
     fields, and hypertex/hyperref support.

          The Persistent URL for this page is
     hhttttpp::////ppuurrll..oorrgg//nnxxgg//ddiisstt//uurrllbbsstt &.

          Version 0.7, 2011 July 20.


     Contents

*    Usage

*    For example...

*    Download and installation

*    Further Information

*    Version history

     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 uurrllbbsstt can be used to add this support
to an arbitrary ..bbsstt file which has a reasonably ‘conven‐
tional’ 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.

11..  UUssaaggee

     uurrllbbsstt [[‐‐‐‐[[nnoo]]eepprriinntt]] [[‐‐‐‐[[nnoo]]ddooii]] [[‐‐‐‐[[nnoo]]ppuubbmmeedd]]
     [[‐‐‐‐iinnlliinneelliinnkkss]] [[‐‐‐‐nnoohhyyppeerrlliinnkkss]] [[‐‐‐‐hhyyppeerrtteexx]] [[‐‐‐‐hhyyppeerr‐‐
     rreeff]] [[‐‐‐‐lliitteerraall kkeeyy==vvaalluuee]] [[iinnppuutt‐‐ffiillee [[oouuttppuutt‐‐ffiillee]]]]

     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 dis‐
abled by ‐‐‐‐nnooeepprriinntt , ‐‐‐‐nnooddooii and ‐‐‐‐nnooppuubbmmeedd , respectively.

     The added fields are:

*    uurrll and llaassttcchheecckkeedd , to associate a URL with a refer‐
     ence, along with the date at which the URL was last
     checked to exist;

*    ddooii , for a reference’s DOI;

*    eepprriinntt , for an arXiv eprint reference; and

*    ppuubbmmeedd for a reference’s PubMed identifier (PMID).

     If either of the ‐‐‐‐hhyyppeerrtteexx or ‐‐‐‐hhyyppeerrrreeff options is
present, then the generated ..bbsstt file includes support for
hyperlinks in the generated eprint entries in the bibliogra‐
phy, 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 ‐‐‐‐eepprriinntt or ‐‐‐‐ddooii options
is given: when URLs are included in the bibliography, they
are written out using the rrll{{......}} command, and hyperref
automatically processes that in the correct way to include a
hyperlink.

     The ‐‐‐‐iinnlliinneelliinnkkss 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 any‐
one who reads your document online (this option can only be
used with ‐‐‐‐hhyyppeerrrreeff or ‐‐‐‐hhyyppeerrtteexx ).  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 pre‐
fer different text.  To do this, give the ‐‐‐‐lliitteerraall option,
followed by a kkeeyy==vvaalluuee pair, for example ‐‐‐‐lliitteerraall
oonnlliinnee==""oonn tthh’’iinntteerrtt0000bbss"" , to replace the default UURRLL::
text.  The possible values, and their defaults, are below
(say ‐‐‐‐lliitteerraall hheellpp to get this list printed out): keyword‐
defaultmeaning citedcitedindicator of citation, or "last
checked", date doiprefixdoi:text printed before DOI eprint‐
prefixarXiv:text printed before eprint ref link‐
text[link]fallback link text pubmedprefixPMID:text printed
before PUBMED reference onlineonlineindication that resource
is online urlintroURL:location of online resource (an alter‐
native 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, ger‐
alpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst,
ieeetr.bst, siam.bst, mla.bst

     Style files which are known to fail:

*    Currently (as of at least v0.5), there exists a style
     aacchhiiccaaggoo..bbsstt which seems to fox uurrllbbsstt ; it turns out
     that there’s a simpler but almost equivalent style
     cchhiiccaaggoo..bbsstt which works.

*    Some APA‐like styles, including at least aappaaggeerr..bbsstt ,
     seem to be sufficiently different from the most common
     styles, that they confuse uurrllbbsstt completely.

*    The _k_o_m_a_‐_s_c_r_i_p_t styles and the _r_e_f_e_r styles are not
     designed to produce conventional ..bbbbll files, and uurrllbbsstt
     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 per‐
suading 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.

22..  FFoorr eexxaammppllee......

     To add URL support to the standard ssiiaamm..bbsstt file, you
can give the command

     %% uurrllbbsstt //ppaatthh//ttoo//oorriiggiinnaall//ssiiaamm..bbsstt ssiiaammuurrll..bbsstt

     Your TeX installation will likely have some way of
helping you find where the original ..bbsstt files are.  On
teTeX‐based systems, for example, the command kkppsseewwhhiicchh
ssiiaamm..bbsstt returns the full path of the ssiiaamm..bbsstt file which
BibTeX would find.

     The distributed files aabbbbrrvvuurrll..bbsstt , aallpphhaauurrll..bbsstt ,
ppllaaiinnuurrll..bbsstt and uunnssrrttuurrll..bbsstt 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.

33..  DDoowwnnllooaadd aanndd iinnssttaallllaattiioonn

     Download the file as a tarball or zip file and unpack
it.  Or you can clone the source repository at bit‐
bucket.org.

     To install, you should simply copy the distributed
uurrllbbsstt script to someplace on the path (such as
//uussrr//llooccaall//bbiinn , or ~~//llooccaall//bbiinn , depending on your privi‐
leges and tastes).

     If you (might) want to use the pre‐converted standard
..bbsstt 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 tteexxhhaasshh , mmkktteexxllssrr 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

     ##!! //uussrr//llooccaall//bbiinn//ppeerrll

     if that’s where your Perl binary is.

     You can also use the conventional ..//ccoonnffiigguurree;; mmaakkee;;
mmaakkee iinnssttaallll to configure and install the package (as root,
or using ssuuddoo if you’re installing it in a system location),
though you still have to install the ..bbsstt files by hand.
This is rather heavyweight for the trivial amount of config‐
uration required, so it’s almost always simpler just to do
things by hand.

     If you need to change some of the uurrllbbsstt defaults, how‐
ever, or if your fingers type ..//ccoonnffiigguurree spontaneously,
then you can be reassured that the configure script supports
the standard ‐‐‐‐pprreeffiixx option, plus the following options
setting defaults:

     ‐‐‐‐wwiitthh‐‐eepprriinnttss==uurrll , ‐‐‐‐wwiitthhoouutt‐‐eepprriinnttss This makes the
     ‐‐‐‐eepprriinnttss 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
     hhttttpp::////aarrxxiivv..oorrgg//aabbss// ‐‐ this is appropriate for arXiv,
     obviously, but there are now a variety of other pre‐
     print archives appearing, for which this might be inap‐
     propriate.  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 dis‐
     abling the ‐‐‐‐eepprriinnttss option for urlbst, the give the
     configure option ‐‐‐‐wwiitthhoouutt‐‐eepprriinnttss

     ‐‐‐‐wwiitthh‐‐ddooii==uurrll , ‐‐‐‐wwiitthhoouutt‐‐ddooii This makes available the
     ‐‐‐‐ddooii option to urlbst and, as with the ‐‐‐‐wwiitthh‐‐eepprriinnttss
     option, allows you to customise the DOI resolver URL.
     The ‐‐‐‐ddooii option to urlbst is on by default.

     ‐‐‐‐wwiitthh‐‐hhrreeff==00//11//22 This allows you to specify the type
     of hyperlinks which are inserted in the bibliography.
     Values 0, 1 and 2, indicating no hyperlinks, hypertex‐
     style links, and hyperref‐style links, respectively.
     The default is ‐‐‐‐wwiitthh‐‐hhrreeff==00 &.  The hhyyppeerrrreeff ‐style
     option is intended to complement the increasingly stan‐
     dard hhyyppeerrrreeff package.

     The first two options simply change defaults, and if
you never use the new eepprriinnttss or ddooii fields, then the
defaults don’t matter to you.

     Since the modified style generates URLs wrapped in the
rrll{{}} macro, it is useful to use the resulting bibliography
style alongside the uurrll package.  Since this tends to work
with hhyyppeerrrreeff anyway, where possible, you don’t get any
extra goodness by changing the ‐‐‐‐wwiitthh‐‐hhrreeff default at con‐
figuration time.

33..11..  DDooccuummeennttaattiioonn

     Basic documentation is in the file uurrllbbsstt..tteexx &.  This
is distributed as a PDF file, but if you want to regenerate
it, use

     %% llaatteexx uurrllbbsstt %% bbiibbtteexx uurrllbbsstt %% llaatteexx uurrllbbsstt %% llaatteexx
     uurrllbbsstt

44..  FFuurrtthheerr IInnffoorrmmaattiioonn aanndd aacckknnoowwlleeddggeemmeennttss

     uurrllbbsstt is archived on CTAN at bbiibblliioo//bbiibbtteexx//ccoonn‐‐
ttrriibb//uurrllbbsstt// , and discussed in the TeX FAQ.

     The source code for the package is maintained at bit‐
bucket.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.

55..  VVeerrssiioonn hhiissttoorryy

     _0_._7_, Add ‐‐nodoi, ‐‐noeprints and ‐‐nopubmed options
     (which defaulted on, and couldn’t otherwise be turned
     off)

     00..77bb11,, 22001111 MMaarrcchh 1177 Allow parameterisation of literal
     strings, with option ‐‐‐‐lliitteerraall &.

     00..66‐‐55,, 22001111 MMaarrcchh 88 Adjust support for inline links
     (should now work for arXiv, DOI and Pubmed)

     00..66‐‐44,, 22000099 AApprriill 2288 Work around BibTeX linebreaking
     bug (thanks to Andras Salamon for the bug report).

     00..66‐‐33,, 22000099 AApprriill 1199 Fix inline link generation (thanks
     to Eric Chamberland for the bug report).

     00..66‐‐22,, 22000088 NNoovveemmbbeerr 1177 We now turn on inlinelinks when
     we spot format.vol.num.pages, which means we include
     links for those styles which don’t include a title in
     the citation (common for articles in physical science
     styles, such as aip.sty).

     00..66‐‐11,, 22000088 JJuunnee 1166 Fixed some broken links to the var‐
     ious citation standards (I think in this context this
     should probably _n_o_t be happening, yes?).  The distrib‐
     uted **uurrll..bbsstt no longer have the ‐‐‐‐iinnlliinneelliinnkkss option
     turned on by default.

     _0_._6_, _2_0_0_7 _M_a_r_c_h _2_6

     Added the option ‐‐‐‐iinnlliinneelliinnkkss , 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 pre‐
paring 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.

     00..66bb33 Further reworkings of the inlinelinks support, so
     that it’s now fired by a format.title (or format.bti‐
     tle) line, with a fallback in fin.entry.  This should
     be more robust, and allows me to delete some of the
     previous version’s gymnastics.

     00..66bb22 Reworked iinnlliinneelliinnkkss support; should now be more
     robust.  Incorporate hyperref bugfixes from PaweÅ
     Widera.

     00..66bb11 Added the option iinnlliinneelliinnkkss , 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.

     00..55..22,, 22000066 SSeepptteemmbbeerr 66 Another set of documentation‐
     only changes, hopefully clarifying installation.

     00..55..11,, 22000066 JJaannuuaarryy 1100 No functionality changes.  Docu‐
     mentation and webpage changes only, hopefully clarify‐
     ing usage and configuration

     _0_._5_, _2_0_0_5 _J_u_n_e _3 Added support for Digital Object Iden‐
     tifiers (DOI) fields in bibliographies.

     00..44‐‐11,, 22000055 AApprriill 1122 Documentation improvements ‐‐
     there are now examples in the help text!

     _0_._4_, _2_0_0_4 _D_e_c_e_m_b_e_r _1 Bug fixes: now compatible with
     mla.bst and friends.  Now uses ..//ccoonnffiigguurree (option‐
     ally).  Assorted reorganisation.

     _0_._3_, _2_0_0_3 _J_u_n_e _4 Added ‐‐eprint, ‐‐hypertex and
     ‐‐hyperref options.

     _0_._2_, _2_0_0_2 _O_c_t_o_b_e_r _2_3 The ‘editor’ field is now sup‐
     ported in the webpage entry type.  Basic documentation
     added.

     _0_._1_, _2_0_0_2 _A_p_r_i_l Initial version

     Norman Gray 2011 July 20

