diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/urlbst/README')
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/README | 302 |
1 files changed, 269 insertions, 33 deletions
diff --git a/Master/texmf-dist/doc/latex/urlbst/README b/Master/texmf-dist/doc/latex/urlbst/README index ed3af19c36a..7e30209d774 100644 --- a/Master/texmf-dist/doc/latex/urlbst/README +++ b/Master/texmf-dist/doc/latex/urlbst/README @@ -1,47 +1,283 @@ -Adds a `webpage' BibTeX entry type, and support for general `url' and -`lastchecked' fields, to arbitrary BibTeX style files. + Urlbst - %%VERSION%% 0.1 + 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 and doi fields, and + hypertex/hyperref support, too. -The Perl script urlbst.pl 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. + The Persistent URL for this page is http://purl.org/nxg/dist/urlbst. - Usage: urlbst.pl [input-file [output-file]] + Version 0.6-1, 2008 June 16. -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. + Contents + * Usage + * For example... + * Download and installation + * Further Information + * Version history -For example: + 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. - urlbst.pl `kpsewhich siam.bst` siamurl.bst + 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. -The distributed files abbrvurl.bst, alphaurl.bst, plainurl.bst and -unsrturl.bst are versions of the standard style files which have been -pre-converted. + 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. -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 +Usage - acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, - geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst and - siam.bst +urlbst [--eprint] [--doi] + [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] + [input-file [output-file]] -Style files known not to work, because they are too different from the -standard styles, include the koma-script styles and the refer styles -(they are not designed to produce conventional .bbl files). 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. + 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. - + If the option --eprint is present, then include support for a eprint + field in the modified .bst file, with a citation format matching that + recommended in the arXiv documentation. Similarly, if the option --doi + is present, then include support for a doi field, referring to a DOI + for the bibliographic item. + 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. -Copyright 2002, Norman Gray. -Released under the terms of the GNU General Public Licence. + 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. - Norman Gray - norman@astro.gla.ac.uk - $Date: 2002/04/22 15:49:06 $ + 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: + * Currently (v0.5), there exists a style achicago.bst which seems to + fox urlbst; it turns out that there's a simpler but almost + equivalent style chicago.bst which works. + * Some APA-like styles, including at least apager.bst, seem to be + sufficiently different from the most common styles, that they + confuse urlbst completely. + * The koma-script styles and the refer styles are not designed to + produce conventional .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 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. + +For example... + + 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 and installation + + Download the file urlbst-0.6-1.tar.gz and unpack it. + + 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 + This makes the --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 + This makes available the --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 + 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 --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. + + Documentation + + 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 + +Further Information + + urlbst is archived on CTAN at biblio/bibtex/contrib/urlbst/, and + discussed in the TeX FAQ. + + The home page of urlbst might possibly have more recent versions than + the one you're looking at now. + + Copyright 2002-8, Norman Gray. Released under the terms of the GNU + General Public Licence. + +Version history + + 0.6-1, 2008 June 16 + Fixed some broken links to the various citation standards (I + think in this context this should probably not be happening, + yes?). The distributed *url.bst no longer have the --inlinelinks + option turned on by default. + + 0.6, 2007 March 26 + 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 Pawel/ Widera. + + 0.6b3 + Further reworkings of the inlinelinks support, so that + it's now fired by a format.title (or format.btitle) 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.6b2 + Reworked inlinelinks support; should now be more robust. + Incorporate hyperref bugfixes from Pawel/ Widera. + + 0.6b1 + 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 (only) useful if you're preparing a + version of a document which will be read on-screen. + + 0.5.2, 2006 September 6 + Another set of documentation-only changes, hopefully clarifying + installation. + + 0.5.1, 2006 January 10 + No functionality changes. Documentation and webpage changes + only, hopefully clarifying usage and configuration + + 0.5, 2005 June 3 + Added support for Digital Object Identifiers (DOI) fields in + bibliographies. + + 0.4-1, 2005 April 12 + Documentation improvements -- there are now examples in the help + text! + + 0.4, 2004 December 1 + Bug fixes: now compatible with mla.bst and friends. Now uses + ./configure (optionally). Assorted reorganisation. + + 0.3, 2003 June 4 + Added --eprint, --hypertex and --hyperref options. + + 0.2, 2002 October 23 + The `editor' field is now supported in the webpage entry type. + Basic documentation added. + + 0.1, 2002 April + Initial version + + Norman Gray + 2008 June 16 |