summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/bibtex/urlbst/README
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-07-02 20:58:10 +0000
committerKarl Berry <karl@freefriends.org>2019-07-02 20:58:10 +0000
commit0224d61fd55e2ceab02210fc8d671a3b186293b1 (patch)
tree1977220f6d5ed5f2059503449d36c3151afeb5c5 /Master/texmf-dist/doc/bibtex/urlbst/README
parentad5ffc75cdf78f6cf6160e4334d45be15dd48221 (diff)
urlbst (2jul19)
git-svn-id: svn://tug.org/texlive/trunk@51530 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/bibtex/urlbst/README')
-rw-r--r--Master/texmf-dist/doc/bibtex/urlbst/README436
1 files changed, 53 insertions, 383 deletions
diff --git a/Master/texmf-dist/doc/bibtex/urlbst/README b/Master/texmf-dist/doc/bibtex/urlbst/README
index 38dfabd93d0..d9705a58402 100644
--- a/Master/texmf-dist/doc/bibtex/urlbst/README
+++ b/Master/texmf-dist/doc/bibtex/urlbst/README
@@ -1,383 +1,53 @@
-
-
-
-
-
-
-
-
-
- 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.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 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 [[‐‐‐‐[[nnoo]]eepprriinntt]] [[‐‐‐‐[[nnoo]]ddooii]] [[‐‐‐‐[[nnoo]]ppuubbmmeedd]]
- [[‐‐‐‐iinnlliinneelliinnkkss]] [[‐‐‐‐nnoohhyyppeerrlliinnkkss]] [[‐‐‐‐hhyyppeerrtteexx]] [[‐‐‐‐hhyyppeerr‐‐
- rreeff]] [[‐‐‐‐lliitteerraall kkeeyy==vvaalluuee]] [[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.
-By default (in the current version), the output includes
-support for eprint, doi and pubmed, but these can be dis‐
-abled by ‐‐‐‐nnooeepprriinntt , ‐‐‐‐nnooddooii and ‐‐‐‐nnooppuubbmmeedd , respectively.
-
- 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.
-
- 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 ‐‐‐‐lliitteerraall option,
-followed by a kkeeyy==vvaalluuee pair, for example ‐‐‐‐lliitteerraall
-oonnlliinnee==""oonn tthh’’iinntteerrtt0000bbss"" , to replace the default UURRLL::
-text. The possible values, and their defaults, are below
-(say ‐‐‐‐lliitteerraall hheellpp 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
- 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 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.
-
-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
-
- _0_._7_, Add ‐‐nodoi, ‐‐noeprints and ‐‐nopubmed options
- (which defaulted on, and couldn’t otherwise be turned
- off)
-
- 00..77bb11,, 22001111 MMaarrcchh 1177 Allow parameterisation of literal
- strings, with option ‐‐‐‐lliitteerraall &.
-
- 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 July 20
-
+urlbst -- add @webpage entry and url/doi/eprint/pubmed fields to BibTeX
+=======================================================================
+
+Version 0.8, 2019 July 1.
+
+The urlbst package consists of a Perl script which edits BibTeX style
+files (.bst) to add a `@webpage` entry type, and which adds a few new
+fields -- notably including 'url' -- to all other entry types. The
+distribution includes preconverted versions of the four standard
+BibTeX .bst style files.
+
+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 new fields.
+
+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 (see https://doi.org);
+ * 'eprint', for an arXiv eprint reference (see http://arxiv.org); and
+ * 'pubmed' for a reference's PubMed identifier (PMID, see http://pubmed.gov).
+
+Licences
+--------
+
+The copyright and licence position for the modified `.bst` files seems
+slightly muddy to me. On the grounds that any licence is better than
+no licence, I therefore assert that the _modifications_ which the
+`urlbst` 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.
+
+The original `.bst` 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 `.bst` file. If anyone disagrees with the logic
+here, I'd be very happy to discuss that.
+
+The `urlbst` script itself is distributed under the GPL, version 2.0.
+
+See the files `LICENCE-lppl.txt` and `LICENCE-gpl-2.0.txt` in the
+distribution, for the relevant licence text.
+
+
+Norman Gray
+http://nxg.me.uk