urlbst (8mar11)

git-svn-id: svn://tug.org/texlive/trunk@21650 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 352 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/bibtex/urlbst/README b/Master/texmf-dist/doc/bibtex/urlbst/README
new file mode 100644
index 00000000000..a34caec73fe
--- /dev/null
+++ b/Master/texmf-dist/doc/bibtex/urlbst/README
@@ -0,0 +1,352 @@
+
+
+
+
+
+
+
+
+
+                           UUrrllbbsstt
+
+
+
+                          _A_B_S_T_R_A_C_T
+
+          A script to add a wweebbppaaggee BibTeX entry type,
+     and add support for general uurrll and llaassttcchheecckkeedd
+     fields, to (most) BibTeX ..bbsstt files.  Optionally
+     adds basic support for eepprriinntt , ddooii and ppuubbmmeedd
+     fields, and hypertex/hyperref support.
+
+          The Persistent URL for this page is
+     hhttttpp::////ppuurrll..oorrgg//nnxxgg//ddiisstt//uurrllbbsstt &.
+
+          Version 0.6‐5, 2011 March 8.
+
+
+     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 uurrllbbsstt can be used to add this support
+to an arbitrary ..bbsstt 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.
+
+11..  UUssaaggee
+
+     uurrllbbsstt [[‐‐‐‐eepprriinntt]] [[‐‐‐‐ddooii]] [[‐‐‐‐ppuubbmmeedd]] [[‐‐‐‐iinnlliinneelliinnkkss]]
+     [[‐‐‐‐nnoohhyyppeerrlliinnkkss]] [[‐‐‐‐hhyyppeerrtteexx]] [[‐‐‐‐hhyyppeerrrreeff]] [[iinnppuutt‐‐ffiillee
+     [[oouuttppuutt‐‐ffiillee]]]]
+
+     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.
+
+     The added fields are:
+
+*    uurrll and llaassttcchheecckkeedd , to associate a URL with a refer‐
+     ence, along with the date at which the URL was last
+     checked to exist;
+
+*    ddooii , for a reference’s DOI;
+
+*    eepprriinntt , for an arXiv eprint reference; and
+
+*    ppuubbmmeedd for a reference’s PubMed identifier (PMID).
+
+     If either of the ‐‐‐‐hhyyppeerrtteexx or ‐‐‐‐hhyyppeerrrreeff options is
+present, then the generated ..bbsstt 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 ‐‐‐‐eepprriinntt or ‐‐‐‐ddooii options
+is given: when URLs are included in the bibliography, they
+are written out using the rrll{{......}} command, and hyperref
+automatically processes that in the correct way to include a
+hyperlink.
+
+     The ‐‐‐‐iinnlliinneelliinnkkss 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 ‐‐‐‐hhyyppeerrrreeff or ‐‐‐‐hhyyppeerrtteexx ).  Any DOI or eprint
+text which would be produced as a result of the appropriate
+option will still appear in this mode.
+
+     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 (v0.5), there exists a style aacchhiiccaaggoo..bbsstt
+     which seems to fox uurrllbbsstt ; it turns out that there’s a
+     simpler but almost equivalent style cchhiiccaaggoo..bbsstt which
+     works.
+
+*    Some APA‐like styles, including at least aappaaggeerr..bbsstt ,
+     seem to be sufficiently different from the most common
+     styles, that they confuse uurrllbbsstt 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 ..bbbbll files, and uurrllbbsstt
+     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.
+
+22..  FFoorr eexxaammppllee......
+
+     To add URL support to the standard ssiiaamm..bbsstt file, you
+can give the command
+
+     %% uurrllbbsstt //ppaatthh//ttoo//oorriiggiinnaall//ssiiaamm..bbsstt ssiiaammuurrll..bbsstt
+
+     Your TeX installation will likely have some way of
+helping you find where the original ..bbsstt files are.  On
+teTeX‐based systems, for example, the command kkppsseewwhhiicchh
+ssiiaamm..bbsstt returns the full path of the ssiiaamm..bbsstt file which
+BibTeX would find.
+
+     The distributed files aabbbbrrvvuurrll..bbsstt , aallpphhaauurrll..bbsstt ,
+ppllaaiinnuurrll..bbsstt and uunnssrrttuurrll..bbsstt 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.
+
+33..  DDoowwnnllooaadd aanndd iinnssttaallllaattiioonn
+
+     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
+uurrllbbsstt script to someplace on the path (such as
+//uussrr//llooccaall//bbiinn , or ~~//llooccaall//bbiinn , depending on your privi‐
+leges and tastes).
+
+     If you (might) want to use the pre‐converted standard
+..bbsstt 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 tteexxhhaasshh , mmkktteexxllssrr 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
+
+     ##!! //uussrr//llooccaall//bbiinn//ppeerrll
+
+     if that’s where your Perl binary is.
+
+     You can also use the conventional ..//ccoonnffiigguurree;; mmaakkee;;
+mmaakkee iinnssttaallll to configure and install the package (as root,
+or using ssuuddoo if you’re installing it in a system location),
+though you still have to install the ..bbsstt 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 uurrllbbsstt defaults, how‐
+ever, or if your fingers type ..//ccoonnffiigguurree spontaneously,
+then you can be reassured that the configure script supports
+the standard ‐‐‐‐pprreeffiixx option, plus the following options
+setting defaults:
+
+     ‐‐‐‐wwiitthh‐‐eepprriinnttss==uurrll , ‐‐‐‐wwiitthhoouutt‐‐eepprriinnttss This makes the
+     ‐‐‐‐eepprriinnttss 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
+     hhttttpp::////aarrxxiivv..oorrgg//aabbss// ‐‐ 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 ‐‐‐‐eepprriinnttss option for urlbst, the give the
+     configure option ‐‐‐‐wwiitthhoouutt‐‐eepprriinnttss
+
+     ‐‐‐‐wwiitthh‐‐ddooii==uurrll , ‐‐‐‐wwiitthhoouutt‐‐ddooii This makes available the
+     ‐‐‐‐ddooii option to urlbst and, as with the ‐‐‐‐wwiitthh‐‐eepprriinnttss
+     option, allows you to customise the DOI resolver URL.
+     The ‐‐‐‐ddooii option to urlbst is on by default.
+
+     ‐‐‐‐wwiitthh‐‐hhrreeff==00//11//22 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 ‐‐‐‐wwiitthh‐‐hhrreeff==00 &.  The hhyyppeerrrreeff ‐style
+     option is intended to complement the increasingly stan‐
+     dard hhyyppeerrrreeff package.
+
+     The first two options simply change defaults, and if
+you never use the new eepprriinnttss or ddooii fields, then the
+defaults don’t matter to you.
+
+     Since the modified style generates URLs wrapped in the
+rrll{{}} macro, it is useful to use the resulting bibliography
+style alongside the uurrll package.  Since this tends to work
+with hhyyppeerrrreeff anyway, where possible, you don’t get any
+extra goodness by changing the ‐‐‐‐wwiitthh‐‐hhrreeff default at con‐
+figuration time.
+
+33..11..  DDooccuummeennttaattiioonn
+
+     Basic documentation is in the file uurrllbbsstt..tteexx &.  This
+is distributed as a PDF file, but if you want to regenerate
+it, use
+
+     %% llaatteexx uurrllbbsstt %% bbiibbtteexx uurrllbbsstt %% llaatteexx uurrllbbsstt %% llaatteexx
+     uurrllbbsstt
+
+44..  FFuurrtthheerr IInnffoorrmmaattiioonn aanndd aacckknnoowwlleeddggeemmeennttss
+
+     uurrllbbsstt is archived on CTAN at bbiibblliioo//bbiibbtteexx//ccoonn‐‐
+ttrriibb//uurrllbbsstt// , 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.
+
+55..  VVeerrssiioonn hhiissttoorryy
+
+     00..66‐‐55,, 22001111 MMaarrcchh 88 Adjust support for inline links
+     (should now work for arXiv, DOI and Pubmed)
+
+     00..66‐‐44,, 22000099 AApprriill 2288 Work around BibTeX linebreaking
+     bug (thanks to Andras Salamon for the bug report).
+
+     00..66‐‐33,, 22000099 AApprriill 1199 Fix inline link generation (thanks
+     to Eric Chamberland for the bug report).
+
+     00..66‐‐22,, 22000088 NNoovveemmbbeerr 1177 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).
+
+     00..66‐‐11,, 22000088 JJuunnee 1166 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 **uurrll..bbsstt no longer have the ‐‐‐‐iinnlliinneelliinnkkss option
+     turned on by default.
+
+     _0_._6_, _2_0_0_7 _M_a_r_c_h _2_6
+
+     Added the option ‐‐‐‐iinnlliinneelliinnkkss , 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.
+
+     00..66bb33 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.
+
+     00..66bb22 Reworked iinnlliinneelliinnkkss support; should now be more
+     robust.  Incorporate hyperref bugfixes from PaweÅ
+     Widera.
+
+     00..66bb11 Added the option iinnlliinneelliinnkkss , 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.
+
+     00..55..22,, 22000066 SSeepptteemmbbeerr 66 Another set of documentation‐
+     only changes, hopefully clarifying installation.
+
+     00..55..11,, 22000066 JJaannuuaarryy 1100 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.
+
+     00..44‐‐11,, 22000055 AApprriill 1122 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 ..//ccoonnffiigguurree (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 March 8
+