1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Urlbst</title>
<link href="http://nxg.me.uk/" rev="author"/>
<link type="text/css" rel="stylesheet" href="/style/base.css"/>
</head>
<body>
<h1>Urlbst</h1>
<div class="abstract">
<p>A script to add a <code>webpage</code> BibTeX entry type, and add
support for general <code>url</code> and <code>lastchecked</code>
fields, to (most) BibTeX <code>.bst</code> files. Optionally adds
basic support for <code>eprint</code>, <code>doi</code> and <code>pubmed</code> fields, and
hypertex/hyperref support.</p>
<p>The Persistent URL for this page is
<code>http://purl.org/nxg/dist/urlbst</code>.
The code (and bugparade) is on
<a href='https://bitbucket.org/nxg/urlbst/'>bitbucket.org</a>.</p>
<p>Version 0.8, 2019 July 1.</p>
</div>
<p>Contents</p>
<ul>
<li><a href='#usage'>Usage</a></li>
<li><a href='#example'>For example...</a></li>
<li><a href='#download'>Download and installation</a></li>
<li><a href='#licences'>Licences</a></li>
<li><a href='#information'>Further Information</a></li>
<li><a href='#history'>Version history, and release notes</a></li>
</ul>
<p>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.</p>
<p>The Perl script <code>urlbst</code> can be used to add this support to an
arbitrary <code>.bst</code> file which has a reasonably `conventional'
structure. The result is meant to be robust rather than pretty.</p>
<p>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 <a href="urlbst.pdf"
>manual</a>.</p>
<h2><a name='usage'>Usage</a></h2>
<pre>
urlbst [--[no]eprint] [--[no]doi] [--[no]pubmed]
[--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref]
[--literal key=value]
[input-file [output-file]]
</pre>
<p>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 <code>--noeprint</code>, <code>--nodoi</code> and
<code>--nopubmed</code>, respectively.</p>
<p>The added fields are:</p>
<ul>
<li><code>url</code> and <code>lastchecked</code>, to associate a URL with
a reference, along with the date at which the URL was last checked
to exist;</li>
<li><code>doi</code>, for a reference's <a href='https://doi.org'>DOI</a>;</li>
<li><code>eprint</code>, for an <a href='http://arxiv.org'>arXiv</a> eprint reference; and</li>
<li><code>pubmed</code> for a reference's
<a href='http://pubmed.gov'>PubMed</a> identifier (PMID).</li>
</ul>
<p>If either of the <code>--hypertex</code> or <code>--hyperref</code>
options is present, then the generated <code>.bst</code> file includes
support for hyperlinks in the generated eprint entries in the
bibliography, with the format being either HyperTeX (see <a
href="http://arxiv.org/hypertex/#implementation" >arXiv, again</a>),
supported by xdvi, dvips and others, or using the support available
from the hyperref package. These options have no effect unless one of
the <code>--eprint</code> or <code>--doi</code> options is given: when
URLs are included in the bibliography, they are written out using the
<code>\url{...}</code> command, and hyperref automatically processes
that in the correct way to include a hyperlink.</p>
<p>The <code>--inlinelinks</code> 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 <code>--hyperref</code> or
<code>--hypertex</code>). Any DOI or eprint text which would be
produced as a result of the appropriate option will still appear in
this mode.</p>
<p>You may adjust various literal strings, either for the purposes of
internationalisation, or simply because you prefer different text. To
do this, give the <code>--literal</code> option, followed by a
<code>key=value</code> pair, for example <code>--literal online="on
th'intert00bs"</code>, to replace the default <code>URL:</code> text.
The possible values, and their defaults, are below (say
<code>--literal help</code> to get this list printed out):</p>
<table>
<tr><th>keyword</th><th>default</th><th>meaning</th></tr>
<tr><td>cited</td><td>cited</td><td>indicator of citation, or "last checked", date</td></tr>
<tr><td>doiprefix</td><td>doi:</td><td>text printed before DOI</td></tr>
<tr><td>eprintprefix</td><td>arXiv:</td><td>text printed before eprint
ref</td></tr>
<tr><td>linktext</td><td>[link]</td><td>fallback link text</td></tr>
<tr><td>pubmedprefix</td><td>PMID:</td><td>text printed before PUBMED reference</td></tr>
<tr><td>online</td><td>online</td><td>indication that resource is online</td></tr>
<tr><td>urlintro</td><td>URL:</td><td>location of online resource (an
alternative is "Available from:")</td></tr>
</table>
<p>The distribution includes preconverted versions of the four
standard BibTeX .bst style files.</p>
<p>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</p>
<blockquote>
acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst,
geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst,
siam.bst, mla.bst
</blockquote>
<p>Style files which are known to fail:</p>
<ul>
<li>Currently (as of at least v0.5), there exists a style <code>achicago.bst</code>
which seems to fox <code>urlbst</code>; it turns out that there's a
simpler but almost equivalent style <code>chicago.bst</code> which
works.</li>
<li>Some APA-like styles, including at least <code>apager.bst</code>,
seem to be sufficiently different from the most common styles, that
they confuse <code>urlbst</code> completely.</li>
<li>The <em>koma-script</em> styles and the <em>refer</em> styles are
not designed to produce conventional <code>.bbl</code> files, and
<code>urlbst</code> does not aim to produce anything useful from these.</li>
</ul>
<p>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.</p>
<p>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).</p>
<p>Note that the command to invoke the script changed from `urlbst.pl'
to plain `urlbst' between versions 0.3 and 0.4.</p>
<h2><a name='example'>For example...</a></h2>
<p>To add URL support to the standard <code>siam.bst</code> file, you
can give the command</p>
<pre>
% urlbst /path/to/original/siam.bst siamurl.bst
</pre>
<p>Your TeX installation will likely have some way of helping you find where
the original <code>.bst</code> files are. On teTeX-based systems, for
example, the command <code>kpsewhich siam.bst</code> returns the full
path of the <code>siam.bst</code> file which BibTeX would find.</p>
<p>The distributed files <code>abbrvurl.bst</code>,
<code>alphaurl.bst</code>, <code>plainurl.bst</code> and
<code>unsrturl.bst</code> are versions of the standard style files
which have been pre-converted.</p>
<p>There is more general discussion of including URLs in
bibliographies in the <a
href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL" >UK TeX
FAQ</a>.</p>
<h2><a name='download'>Download and installation</a></h2>
<p>Download the file as a
<a href="urlbst-0.8.tar.gz" >tarball</a>
or
<a href="urlbst-0.8.zip" >zip file</a>
and unpack it. Or you can clone the source repository at
<a href='http://bitbucket.org/nxg/urlbst/'>bitbucket.org</a>.</p>
<p>To install, you should simply copy the distributed
<code>urlbst</code> script to someplace on the path (such as
<code>/usr/local/bin</code>, or <code>~/local/bin</code>, depending on
your privileges and tastes).</p>
<p>If you (might) want to use the pre-converted standard
<code>.bst</code> files, then you'll need to copy these to somewhere
in the BibTeX search path. Type <kbd>kpsepath bst</kbd> 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 <code>texhash</code>,
<code>mktexlsr</code> or its equivalent, to update LaTeX's filename
cache. For further hints here, see
the TeX FAQ entries on <a
href='http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages'
>installing a package</a> and <a
href='http://www.tex.ac.uk/cgi-bin/texfaq2html?label=wherefiles'
>where LaTeX puts files</a>.</p>
<p>That should be all you have to do.</p>
<p>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</p>
<pre>
#! /usr/local/bin/perl
</pre>
<p>if that's where your Perl binary is.</p>
<p>You can also use the conventional <code>./configure; make; make
install</code> to configure and install the package (as root, or using
<code>sudo</code> if you're installing it in a system location),
though you still have to install the <code>.bst</code> 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.</p>
<p>If you need to change some of the <code>urlbst</code> defaults,
however, or if your fingers type <code>./configure</code>
spontaneously, then you can be reassured that the configure script
supports the standard <code>--prefix</code> option, plus the following
options setting defaults:</p>
<dl>
<dt><code>--with-eprints=url</code>, <code>--without-eprints</code></dt>
<dd>This makes the <code>--eprints</code> 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
<code>http://arxiv.org/abs/</code> -- 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 <code>--eprints</code> option for urlbst, the give the configure
option <code>--without-eprints</code></dd>
<dt><code>--with-doi=url</code>, <code>--without-doi</code></dt>
<dd>This makes available the <code>--doi</code> option to urlbst and,
as with the <code>--with-eprints</code> option, allows you to
customise the DOI resolver URL. The <code>--doi</code> option to
urlbst is on by default.</dd>
<dt><code>--with-href=0/1/2</code></dt>
<dd>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 <code>--with-href=0</code>. The
<code>hyperref</code>-style option is intended to complement the
increasingly standard <code>hyperref</code> package.</dd>
</dl>
<p>The first two options simply change defaults, and if you never use
the new <code>eprints</code> or <code>doi</code> fields, then the
defaults don't matter to you. </p>
<p>Since the modified style generates URLs wrapped in the
<code>\url{}</code> macro, it is useful to use the resulting
bibliography style alongside the <code>url</code> package. Since this
tends to work with <code>hyperref</code> anyway, where possible, you
don't get any extra goodness by changing the <code>--with-href</code>
default at configuration time.</p>
<h3>Documentation</h3>
<p>Basic documentation is in the file <code>urlbst.tex</code>. This
is distributed as a PDF file, but if you want to regenerate it, use</p>
<pre>
% latex urlbst
% bibtex urlbst
% latex urlbst
% latex urlbst
</pre>
<h2><a name='licences'>Licences</a></h2>
<!-- this text copied from the README.md -->
<p>The copyright and licence position for the modified <code>.bst</code> files seems
slightly muddy to me. On the grounds that any licence is better than
no licence, I therefore assert that the <em>modifications</em> which the
<code>urlbst</code> program makes to these files are copyright 2002-03, 2005-12, 2014, 2019,
Norman Gray, and that these modifications are available for
distribution under the terms of the LaTeX Project Public Licence.</p>
<p>The original <code>.bst</code> files are copyright Howard Trickey and Oren
Patashnik, with a set of permissions, in text at the top of the files,
which state that "Unlimited copying and redistribution of this file
are permitted as long as it is unmodified" (see the files for the
complete text). The distribution terms above therefore appear to be
compatible with -- in the sense of being morally equivalent to --
these terms in the <code>.bst</code> file. If anyone disagrees with
the logic here, I'd be very happy to discuss that.</p>
<p>The <code>urlbst</code> script itself is distributed under the GPL, version 2.0.</p>
<p>See the files <code>LICENCE-lppl.txt</code> and <code>LICENCE-gpl-2.0.txt</code> in the
distribution, for the relevant licence text.</p>
<h2><a name='information'>Further Information and acknowledgements</a></h2>
<p><code>urlbst</code> is archived <a
href='https://ctan.org/pkg/urlbst'
>on CTAN</a>, and discussed in the
<a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL" >TeX
FAQ</a>.</p>
<p>The source code for the package is maintained at
<a href='http://bitbucket.org/nxg/urlbst/'>bitbucket.org</a>,
which also includes an issue tracker, where you can report bugs (or
just mail me).</p>
<p>The <a href="http://purl.org/nxg/dist/urlbst"
>home page of urlbst</a> might possibly have more recent versions than the
one you're looking at now.</p>
<h2><a name='history'>Acknowledgements, and release notes</a></h2>
<!-- include:release-notes.html -->
<div xmlns='http://www.w3.org/1999/xhtml'>
<p>Thanks are due to many people for suggestions and requests:
to Jason Eisner for suggesting the <code>--inlinelinks</code> option;
to ‘ijvm’ for code contributions in the <code>urlbst</code> script;
to Paweł Widera for the suggestion to use <code>\path</code> when formatting DOIs;
to Michael Giffin for the suggestion to include PubMed URLs;
to Katrin Leinweber for the pull request which fixed the format of DOI
references.</p>
<dl>
<dt><strong>0.8, 2019 July 1</strong></dt>
<dd><ul>
<li>The presence of a preexisting <code>format.doi</code>,
<code>format.eprint</code> or <code>format.pubmed</code> function is
now detected, and warned about. The resulting <code>.bst</code> file
might still require some manual editing.
Resolves <a href='https://bitbucket.org/nxg/urlbst/issue/8'>issue 8</a>.</li>
<li>Clarified licences (I hope).</li>
<li>Adjust format of DOI resolver.
Resolves <a href='https://bitbucket.org/nxg/urlbst/issue/11'>issue 11</a>,
thanks to
<a href='https://bitbucket.org/nxg/urlbst/pull-requests/1/'
>code contributed by Katrin Leinweber</a>.</li>
</ul>
</dd>
<dt>0.7, 2011 July 20</dt>
<dd>Add <code>--nodoi</code>, <code>--noeprints</code> and <code>--nopubmed</code> options (which defaulted
on, and couldn't otherwise be turned off)</dd>
<dt>0.7b1, 2011 March 17</dt>
<dd>Allow parameterisation of literal strings, with option <code>--literal</code>.</dd>
<dt>0.6-5, 2011 March 8</dt>
<dd>Adjust support for inline links (should now work for arXiv, DOI and Pubmed)</dd>
<dt>0.6-4, 2009 April 28</dt>
<dd>Work around BibTeX linebreaking bug (thanks to Andras Salamon for the bug report).</dd>
<dt>0.6-3, 2009 April 19</dt>
<dd>Fix inline link generation (thanks to Eric Chamberland for the bug report).</dd>
<dt>0.6-2, 2008 November 17</dt>
<dd>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).</dd>
<dt>0.6-1, 2008 June 16</dt>
<dd>Fixed some broken links to the various citation standards
(I think in this context this should probably <em>not</em> be happening, yes?).
The distributed <code>*url.bst</code> no longer have the
<code>--inlinelinks</code> option turned on by default.</dd>
<dt><strong>0.6, 2007 March 26</strong></dt>
<dd><ul>
<li>Added the option <code>--inlinelinks</code>, 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.</li>
<li>Incorporate hyperref bugfixes from Paweł Widera.</li>
<li>Further reworkings of the inlinelinks support, so that it's now
fired by a <code>format.title</code> (or <code>format.btitle</code>) line, with a fallback in
<code>fin.entry</code>. This should be more robust, and allows me to delete some
of the previous version's gymnastics.</li>
<li>Reworked <code>inlinelinks</code> support; should now be more
robust. Incorporate hyperref bugfixes from Paweł Widera.</li>
<li>Added the option <code>inlinelinks</code>, 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.</li>
</ul>
</dd>
<dt>0.5.2, 2006 September 6</dt>
<dd>Another set of documentation-only changes, hopefully clarifying
installation.</dd>
<dt>0.5.1, 2006 January 10</dt>
<dd>No functionality changes. Documentation and webpage changes only,
hopefully clarifying usage and configuration</dd>
<dt><strong>0.5, 2005 June 3</strong></dt>
<dd>Added support for Digital Object Identifiers (DOI) fields in
bibliographies.</dd>
<dt>0.4-1, 2005 April 12</dt>
<dd>Documentation improvements -- there are now examples in the help text!</dd>
<dt><strong>0.4, 2004 December 1</strong></dt>
<dd>Bug fixes: now compatible with mla.bst and friends.
Now uses <code>./configure</code> (optionally). Assorted reorganisation.</dd>
<dt><strong>0.3, 2003 June 4</strong></dt>
<dd>Added <code>--eprint</code>, <code>--hypertex</code> and <code>--hyperref</code> options.</dd>
<dt><strong>0.2, 2002 October 23</strong></dt>
<dd>The `editor' field is now supported in the webpage entry type. Basic
documentation added.</dd>
<dt><strong>0.1, 2002 April</strong></dt>
<dd>Initial version</dd>
</dl>
</div>
<p>Copyright 2002-03, 2005-12, 2014, 2019, Norman Gray. Released under the terms of the GNU
General Public Licence.</p>
<div class="signature">
<a href="http://nxg.me.uk"
>Norman Gray</a><br/>
2019 July 1
</div>
</body>
</html>
|
