diff options
Diffstat (limited to 'Master/texmf-dist/doc/bibtex/urlbst/README')
-rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/README | 436 |
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 |