diff options
Diffstat (limited to 'Master/texmf-dist/doc/bibtex')
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/Makefile.in | 189 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/README | 352 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/VERSION | 1 | ||||
| -rwxr-xr-x | Master/texmf-dist/doc/bibtex/urlbst/urlbst | 763 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/urlbst.bib | 219 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/urlbst.html | 374 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/urlbst.html.in | 374 | ||||
| -rwxr-xr-x | Master/texmf-dist/doc/bibtex/urlbst/urlbst.in | 763 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf | bin | 0 -> 184859 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex | 278 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex.in | 278 |
11 files changed, 3591 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/bibtex/urlbst/Makefile.in b/Master/texmf-dist/doc/bibtex/urlbst/Makefile.in new file mode 100644 index 00000000000..4eba106fa06 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/Makefile.in @@ -0,0 +1,189 @@ +# BSTSTYLES are the standard styles that we distribute +BSTSTYLES=plainurl.bst unsrturl.bst alphaurl.bst abbrvurl.bst +# TESTSTYLES are a couple of extra ones that we explicitly test +TESTSTYLES=mlaurl.bst + +MAINTAINER_FILES= Makefile configure +GENERATED=urlbst urlbst.tex urlbst.pdf urlbst.html README VERSION $(BSTSTYLES) +# distribute generated files +# ...plus the configure files +# ...plus the configured files +DISTRIBS=$(GENERATED) \ + configure configure.ac \ + urlbst.in urlbst.bib urlbst.tex.in urlbst.html.in Makefile.in + +prefix=@prefix@ +exec_prefix=@exec_prefix@ +bindir=@bindir@ +DIST=urlbst-@PACKAGE_VERSION@ + +# On OS X, the following avoids extended attributes being included +TAR=COPYFILE_DISABLE=1 tar +#TAR=tar + +### Implicit rules + +# Don't include --inlinelinks when generating %url.bst here, as we +# do want the links visible when generating the documentation, and it's +# probably abetter default in any case. +%url.bst: urlbst + export BSTINPUTS=test: ; \ + if test -z "`kpsewhich ${@:url.bst=.bst}`"; then \ + echo "Can't locate ${@:url.bst=.bst}"; \ + else \ + ./urlbst --eprint --doi --pubmed --hyperref `kpsewhich ${@:url.bst=.bst}` $@; \ + fi + +# Incomplete TeX support +%.ps: %.dvi + dvips -o $@ $< +%.bbl: %.tex plainurl.bst + pdflatex $< + if ! test -f $@ || grep -q 'Citation.*undefined' ${<:.tex=.log}; then \ + bibtex ${<:.tex=}; \ + pdflatex $<; \ + rm ${<:.tex=.pdf}; \ + fi +%.pdf: %.tex %.bbl + pdflatex $< +%.dvi: %.tex %.bbl + latex $< +%.gz: % + gzip --best -f $< + +.PRECIOUS: .bbl + +### Targets start here + +all: urlbst + +dist: $(DIST).tar.gz $(DIST).zip + +$(DIST).tar: $(DIST)/urlbst.in + $(TAR) cf $@ $(DIST) + +$(DIST).zip: $(DIST)/urlbst.in + zip -r $@ $(DIST) + +$(DIST)/urlbst.in: $(DISTRIBS) + if test -d $(DIST); then rm -Rf $(DIST); fi && mkdir $(DIST) + cp $(DISTRIBS) $(DIST) + +# The following appears not to work. +# Perhaps it has to be installed, rather than run from the .app bundle +# (but it doesn't give you any choice about where you install it, +# and I'm not going to put it in a system location) +#PLATYPUS=/Data/LocalApplications/Platypus-4.0/Platypus.app/Contents/Resources/platypus +PLATYPUS=/usr/local/bin/platypus +urlbst.app: urlbst + rm -Rf urlbst.app + $(PLATYPUS) -a urlbst -c "$$PWD/urlbst" -o 'Progress Bar' \ + -p /usr/bin/perl -V @PACKAGE_VERSION@ -u Norman\ Gray -I uk.me.nxg.urlbst \ + -D -R -N CALLED_FROM_PLATYPUS=1 $$PWD/urlbst.app +urlbst-app.zip: urlbst.app + zip -r urlbst-app.zip urlbst.app + +#$(DIST).tar: $(DISTRIBS) +# sed '1s,.*,#! /usr/bin/env perl,' urlbst >tmp && mv tmp urlbst \ +# && chmod +x urlbst +# rm -Rf $(DIST) $(DIST).tar +# mkdir $(DIST) +# cp $(DISTRIBS) $(DIST) +# tar cf $@ $(DIST) +# rm -Rf $(DIST) + +urlbst: urlbst.in config.status + ./config.status urlbst + +urlbst.tex: urlbst.tex.in config.status + ./config.status urlbst.tex + +urlbst.html: urlbst.html.in config.status + ./config.status urlbst.html + +Makefile: Makefile.in config.status + ./config.status Makefile + +configure: configure.ac + autoconf + +config.status: configure + ./configure + +# Version stamp file, included in the distribution for convenience, +# so it's easy to see which version it is has been unpacked at CTAN. +VERSION: + echo $(DIST) >VERSION + +# The README is just a plain-text version of urlbst.html +README: urlbst.html prepare-roff.sed + xsltproc html2roff.xslt urlbst.html \ + | sed -f prepare-roff.sed \ + | nroff -Tutf8 -ms \ + | sed '/XXXEND/,$$d' >README + +# Write a roff file -- there comes a point where a string of -e '' +# commands is more confusing than is safe +# (plus trying to get '$a\' into that is mind-bending). +prepare-roff.sed: + rm -f $@ + { echo '$$a\'; echo '\'; echo 'XXXEND'; echo '/^ *$$/d'; echo 's/^ *//'; echo 's/^\.$$/\&./'; echo 's/^\. /\&. /'; } >$@ + +# Very simple install target -- hardly worth bothering, really.... +install: urlbst + cp urlbst $(bindir) + +# Very simple test target -- just check that we don't bomb converting +# the standard styles +test: $(BSTSTYLES) $(TESTSTYLES) + for f in $(BSTSTYLES) $(TESTSTYLES); do \ + ROOT=`echo $$f|sed s/\.bst$$//`; \ + printf '\\relax\n' > test-$$ROOT.aux; \ + printf '\\citation{*}\n' >> test-$$ROOT.aux; \ + printf '\\bibdata{urlbst}\n' >> test-$$ROOT.aux; \ + printf '\\bibstyle{'"$$ROOT"'}\n' >> test-$$ROOT.aux; \ + bibtex test-$$ROOT; \ + done + +# Brute-force test target, which finds all the system .bst files, +# converts them, and runs BibTeX on them. It doesn't test the results +# in any way -- you have to do that by eye. +# +# No, this is a hopelessly blunderbus approach. And in any case the +# 'locate *.bst' doesn't work. At least the following would find only things +# on the .bst search path. +# BSTPATH=`kpsepath bst` +# for d in `IFS=:; echo $BSTPATH`; do +# dd=`expr "$d" : '!*\(.*[^/]\)/*$'` +# echo dd=$dd +# test -d "$dd" && find $dd -name \*.bst +# done +test-all: + printf '\\relax\n'>test-all.mainaux + sed -n 's/^.*{\(test:.*\),/\\citation{\1}/p' urlbst.bib>>test-all.mainaux + for f in `locate '*.bst' | grep -v norman`; do T=`echo $$f|sed 's+.*/\(.*\)\.bst+\1url+'`;perl urlbst $$f $$T.bst; if test $$? = 0; then TF=test-$$T.aux; cp test-all.mainaux $$TF;printf '\\bibdata{urlbst}\n'>>$$TF; printf '\\bibstyle{$$T}\n'>>$$TF; else rm $$T.bst; fi done + for f in `ls test-*.aux|sed s+.aux++`;do bibtex $$f;done + rm test-all.mainaux + +# Tarball for unpacking in the webpage distribution directory +webpage-tarball.tar: urlbst.pdf urlbst.html $(DIST).tar.gz $(DIST).zip + mkdir webpage-tarball + cp urlbst.pdf $(DIST).tar.gz $(DIST).zip webpage-tarball + cp urlbst.html webpage-tarball/index.html + cd webpage-tarball; $(TAR) cf ../webpage-tarball.tar * + rm -Rf webpage-tarball + +tidy: + rm -f webpage-tarball.tar + rm -f *~ test-* + rm -f *.aux *.bbl *.log *.blg *.dvi *.pdf + rm -Rf urlbst.app + +clean: tidy + rm -f *.bst + rm -Rf config.status autom4te.cache prepare-roff.sed + rm -Rf $(DIST).tar $(DIST).tar.gz $(DIST).zip $(DIST) + rm -f $(GENERATED) + +maintainer-clean: clean + rm -f $(MAINTAINER_FILES) 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 + diff --git a/Master/texmf-dist/doc/bibtex/urlbst/VERSION b/Master/texmf-dist/doc/bibtex/urlbst/VERSION new file mode 100644 index 00000000000..3a3f6d04e37 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/VERSION @@ -0,0 +1 @@ +urlbst-0.6-5b1 diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst b/Master/texmf-dist/doc/bibtex/urlbst/urlbst new file mode 100755 index 00000000000..4cdae07ce5e --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst @@ -0,0 +1,763 @@ +#! /usr/bin/perl -w +# +# Usage: ./urlbst.pl [--eprint] [--doi] [--pubmed] +# [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref] +# [input-file [output-file]] +# If either input-file or output-file is omitted, they are replaced by +# stdin or stdout respectively. +# +# See http://purl.org/nxg/dist/urlbst for documentation +# +# $Id$ + +$version = '0.6-5'; +($progname = $0) =~ s/.*\///; +$mymarker = "% $progname"; +$mymarkerend = "% ...$progname to here"; +$myurl = 'http://purl.org/nxg/dist/urlbst'; + + +$infile = '-'; +$outfile = '-'; + +$addeprints = 1; # if true (nonzero) we add support for eprints +$eprintprefix = 'arXiv:'; # make these settable with --eprint? syntax? +$eprinturl = 'http://arxiv.org/abs/'; + +$adddoiresolver = 1; +$doiprefix = 'doi:'; +$doiurl = 'http://dx.doi.org/'; + +$addpubmedresolver = 1; +$pubmedprefix = 'PMID:'; +$pubmedurl = 'http://www.ncbi.nlm.nih.gov/pubmed/'; + +$makehref = 0; +$availablestring = "Available from: "; +$inlinelinks = 0; + +$automatic_output_filename = 0; + +$Usage = "$progname [--eprint] [--doi] [--pubmed]\n [--nohyperlinks] [--[no]inlinelinks] [--hypertex] [--hyperref]\n [--help] [input-file [output-file]]"; + +# Magic environment variable: if this is set, then we're being called from a Platypus wrapper +# See http://www.sveinbjorn.org/platypus +if ($ENV{"CALLED_FROM_PLATYPUS"}) { + $automatic_output_filename = 1; +} + +while ($#ARGV >= 0) { + if ($ARGV[0] eq '--eprint') { + $addeprints = 1; + } elsif ($ARGV[0] eq '--doi') { + $adddoiresolver = 1; + } elsif ($ARGV[0] eq '--pubmed') { + $addpubmedresolver = 1; + } elsif ($ARGV[0] eq '--nohyperlinks') { + $makehref = 0; + } elsif ($ARGV[0] eq '--hypertex') { + $makehref = 1; + } elsif ($ARGV[0] eq '--hyperref') { + $makehref = 2; + } elsif ($ARGV[0] eq '--inlinelinks') { + $inlinelinks = 1; + } elsif ($ARGV[0] eq '--noinlinelinks') { + $inlinelinks = 0; + } elsif ($ARGV[0] eq '--automatic-output') { + $automatic_output_filename = 1; + } elsif ($ARGV[0] eq '--help') { + print <<EOD; +urlbst version $version + Usage: $Usage + --eprint: include support for `eprint' fields + --doi: include support for `doi' field + --pubmed: include support for `pubmed' field + --nohyperlinks do not include active links anywhere + --inlinelinks add hyperlinks to entry titles + --hypertex: include HyperTeX-style hyperlink support + --hyperref: include {hyperref}-style hyperlink support + (generally better) + --help: print this help + Input and output files may be given as `-' (default) to indicate stdin/out +EOD + exit(0); + } elsif ($ARGV[0] =~ /^-/) { + die "Unrecognised option $ARGV[0]: Usage: $Usage\n"; + } elsif ($infile eq '-') { + $infile = $ARGV[0]; + } elsif ($outfile eq '-') { + $outfile = $ARGV[0]; + } else { + die "Usage: $Usage\n"; + } + shift(@ARGV); +} + +if ($inlinelinks && $makehref == 0) { + print <<'EOD'; +Warning: --inlinelinks and --nohyperlinks were both specified (possibly + implicitly). That combination makes no sense, so I'll ignore + --nohyperlinks and use --hyperref instead +EOD + $makehref = 2; +} + +if ($automatic_output_filename) { + if ($infile eq '-') { + print "ERROR: No input filename given with --automatic-output\n"; + } + $outfile = $infile; + @outparts = split /\./, $outfile; + $ext = pop(@outparts); + $outfile=join('.', @outparts); + if ($outfile eq '') { + $outfile = $ext . '-url'; + } else { + $outfile = $outfile . '-url.' . $ext; + } +} + +$exitstatus = 0; # success status + +open (IN, "<$infile") || die "Can't open $infile to read"; +open (OUT, ">$outfile") || die "Can't open $outfile to write"; + +# We have to make certain assumptions about the source files, in order +# to patch them at the correct places. Specifically, we assume that +# +# - there's a function init.state.consts +# +# - ...and an output.nonnull which does the actual outputting, which +# has the `usual' interface. +# +# - we can replace +# fin.entry +# by +# new.block +# output.url % the function which formats and displays any URL +# fin.entry +# +# - there is a function which handles the `article' entry type (this +# will always be true) +# +# - there is a function output.bibitem which is called at the +# beginning of each entry type +# - ...and one called fin.entry which is called at the end +# +# If the functions format.date, format.title or new.block are not defined (the +# former is not in apalike, for example, and the last is not in the +# AMS styles), then replacements are included in the output. +# +# All these assumptions are true of the standard files and, since most +# style files derive from them more or less directly, are true of most (?) +# other style files, too. +# +# There's some rather ugly Perl down here. The parsing for +# brace-matching could probably do with being rewritten in places, to +# make it less ugly, and more robust. + +print OUT "%%% Modification of BibTeX style file ", ($infile eq '-' ? '<stdin>' : $infile), "\n"; +print OUT "%%% ... by $progname, version $version (marked with \"$mymarker\")\n%%% See <$myurl>\n"; +print OUT "%%% Added webpage entry type, and url and lastchecked fields.\n"; +print OUT "%%% Added eprint support.\n" if ($addeprints); +print OUT "%%% Added DOI support.\n" if ($adddoiresolver); +print OUT "%%% Added PUBMED support.\n" if ($addpubmedresolver); +print OUT "%%% Added HyperTeX support.\n" if ($makehref == 1); +print OUT "%%% Added hyperref support.\n" if ($makehref == 2); +print OUT "%%% Original headers follow...\n\n"; + +$found{initconsts} = 0; +$found{outputnonnull} = 0; +$found{article} = 0; +$found{outputbibitem} = 0; +$found{finentry} = 0; +$found{formatdate} = 0; +$found{formattitle} = 0; +$found{newblock} = 0; + +while (<IN>) { + /^ *%/ && do { + # Pass commented lines unchanged + print OUT; + next; + }; + + /^ *ENTRY/ && do { + # Work through the list of entry types, finding what ones are there. + # If we find a URL entry there already, object, since these edits + # will mess things up. + $line = $_; + until ($line =~ /\{\s*(\w*)/) { + $line .= <IN>; + } + $bracematchtotal = 0; # reset + bracematcher($line); + $line =~ /\{\s*(\w*)/; + $found{'entry'.$1} = 1; + print OUT $line; + $line = <IN>; + until (bracematcher($line) == 0) { + # XXX deal with multiple entries on one line + ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); + print OUT $line; + $line = <IN>; + } + if (defined($found{entryurl})) { + print STDERR "$progname: style file $infile already has URL entry!\n"; + # print out the rest of the file, and give up + print OUT $line; + while (<IN>) { + print OUT; + } + $exitstatus = 1; + last; + } else { + print OUT " eprint $mymarker\n doi $mymarker\n pubmed $mymarker\n url $mymarker\n lastchecked $mymarker\n"; + } + print OUT $line; + next; + }; + + /^ *FUNCTION *\{init\.state\.consts\}/ && do { + # In the init.state.consts function, add an extra set of + # constants at the beginning. Also use this as the marker for + # the place to add the init strings function. + print OUT <<EOD; +$mymarker... +% urlbst constants and state variables +STRINGS { urlintro + eprinturl eprintprefix doiprefix doiurl pubmedprefix pubmedurl + openinlinelink closeinlinelink } +INTEGERS { hrefform inlinelinks makeinlinelink + addeprints adddoiresolver addpubmedresolver } +FUNCTION {init.urlbst.variables} +{ + % The following constants may be adjusted by hand, if desired + + % The first set allow you to enable or disable certain functionality. + #$addeprints 'addeprints := % 0=no eprints; 1=include eprints + #$adddoiresolver 'adddoiresolver := % 0=no DOI resolver; 1=include it + #$addpubmedresolver 'addpubmedresolver := % 0=no PUBMED resolver; 1=include it + #$makehref 'hrefform := % 0=no crossrefs; 1=hypertex xrefs; 2=hyperref refs + #$inlinelinks 'inlinelinks := % 0=URLs explicit; 1=URLs attached to titles + + % String constants, which you _might_ want to tweak. + "$availablestring" 'urlintro := % prefix before URL + "$eprinturl" 'eprinturl := % prefix to make URL from eprint ref + "$eprintprefix" 'eprintprefix := % text prefix printed before eprint ref + "$doiurl" 'doiurl := % prefix to make URL from DOI + "$doiprefix" 'doiprefix := % text prefix printed before DOI ref + "$pubmedurl" 'pubmedurl := % prefix to make URL from PUBMED + "$pubmedprefix" 'pubmedprefix := % text prefix printed before PUBMED ref + + % The following are internal state variables, not configuration constants, + % so they shouldn't be fiddled with. + #0 'makeinlinelink := % state variable managed by possibly.setup.inlinelink + "" 'openinlinelink := % ditto + "" 'closeinlinelink := % ditto +} +INTEGERS { + bracket.state + outside.brackets + open.brackets + within.brackets + close.brackets +} +$mymarkerend +EOD + $line = $_; + until ($line =~ /\{.*\}.*\{/s) { + $line .= <IN>; + } + $line =~ s/(\{.*?\}.*?\{)/$1 #0 'outside.brackets := $mymarker... + #1 'open.brackets := + #2 'within.brackets := + #3 'close.brackets := $mymarkerend + + /s; + print OUT $line; + $found{initconsts} = 1; + next; + }; + + /^ *EXECUTE *\{init\.state\.consts\}/ && do { + print OUT "EXECUTE {init.urlbst.variables} $mymarker\n"; + print OUT; + next; + }; + + /^ *FUNCTION *\{new.block\}/ && do { + $found{newblock} = 1; + }; + + /^ *FUNCTION *{output\.nonnull}/ && do { + print OUT "$mymarker\n"; + print OUT "FUNCTION {output.nonnull.original}\n"; + copy_block(); + print_output_functions(); + $found{outputnonnull} = 1; + next; + }; + + /FUNCTION *\{fin.entry\}/ && do { + # Rename fin.entry to fin.entry.original (wrapped below) + s/fin.entry/fin.entry.original/; + s/$/ $mymarker (renamed from fin.entry, so it can be wrapped below)/; + $found{finentry} = 1; + print OUT; + next; + }; + + /^ *FUNCTION *{format\.date}/ && do { + $found{formatdate} = 1; + print OUT; + next; + }; + + /^ *FUNCTION *{format\.title}/ && do { + # record that we found this + $found{formattitle} = 1; + print OUT; + next; + }; + + /^ *format\.b?title/ && do { + # interpolate a call to possibly.setup.inlinelink + print OUT " title empty\$ 'skip\$ 'possibly.setup\.inlinelink if\$ $mymarker\n"; + print OUT; + next; + }; + + /^ *format\.vol\.num\.pages/ && do { + # interpolate a call to possibly.setup.inlinelink + s/^( *)/$1possibly.setup.inlinelink /; + s/$/$mymarker/; + print OUT; + next; + }; + + /^ *FUNCTION *\{article\}/ && do { + + print_missing_functions(); + print_webpage_def(); + + print OUT; + $found{article} = 1; + next; + }; + + /FUNCTION *\{output.bibitem\}/ && do { + # Rename output.bibitem to output.bibitem.original (wrapped below) + s/{output.bibitem\}/\{output.bibitem.original\}/; + s/$/ $mymarker (renamed from output.bibitem, so it can be wrapped below)/; + $found{outputbibitem} = 1; + print OUT; + next; + }; + + print OUT; +}; + +if ($exitstatus == 0) { + # Skip this if we've already reported an error -- it'll only be confusing + foreach $k (keys %found) { + if ($found{$k} == 0) { + print STDERR "$progname: $infile: failed to find feature $k\n"; + } + } +} + +close (IN); +close (OUT); + +exit $exitstatus;; + + + + + + +sub print_output_functions { + print OUT "$mymarker...\n"; + + print OUT <<'EOD'; +% The following three functions are for handling inlinelink. They wrap +% a block of text which is potentially output with write$ by multiple +% other functions, so we don't know the content a priori. +% They communicate between each other using the variables makeinlinelink +% (which is true if a link should be made), and closeinlinelink (which holds +% the string which should close any current link. They can be called +% at any time, but start.inlinelink will be a no-op unless something has +% previously set makeinlinelink true, and the two ...end.inlinelink functions +% will only do their stuff if start.inlinelink has previously set +% closeinlinelink to be non-empty. +% (thanks to 'ijvm' for suggested code here) +FUNCTION {uand} +{ 'skip$ { pop$ #0 } if$ } % 'and' (which isn't defined at this point in the file) +FUNCTION {possibly.setup.inlinelink} +{ makeinlinelink hrefform #0 > uand + { doi empty$ adddoiresolver uand + { pubmed empty$ addpubmedresolver uand + { eprint empty$ addeprints uand + { url empty$ + { "" } + { url } + if$ } + { eprinturl eprint * } + if$ } + { pubmedurl pubmed * } + if$ } + { doiurl doi * } + if$ + % an appropriately-formatted URL is now on the stack + hrefform #1 = % hypertex + { "\special {html:<a href=" quote$ * swap$ * quote$ * "> }{" * 'openinlinelink := + "\special {html:</a>}" 'closeinlinelink := } + { "\href {" swap$ * "} {" * 'openinlinelink := % hrefform=#2 -- hyperref + % the space between "} {" matters: a URL of just the right length can cause "\% newline em" + "}" 'closeinlinelink := } + if$ + #0 'makeinlinelink := + } + 'skip$ + if$ % makeinlinelink +} +FUNCTION {add.inlinelink} +{ openinlinelink empty$ + 'skip$ + { openinlinelink swap$ * closeinlinelink * + "" 'openinlinelink := + } + if$ +} +EOD + + # new.block is defined elsewhere + + print OUT <<'EOD'; +FUNCTION {output.nonnull} +{ % Save the thing we've been asked to output + 's := + % If the bracket-state is close.brackets, then add a close-bracket to + % what is currently at the top of the stack, and set bracket.state + % to outside.brackets + bracket.state close.brackets = + { "]" * + outside.brackets 'bracket.state := + } + 'skip$ + if$ + bracket.state outside.brackets = + { % We're outside all brackets -- this is the normal situation. + % Write out what's currently at the top of the stack, using the + % original output.nonnull function. + s + add.inlinelink + output.nonnull.original % invoke the original output.nonnull + } + { % Still in brackets. Add open-bracket or (continuation) comma, add the + % new text (in s) to the top of the stack, and move to the close-brackets + % state, ready for next time (unless inbrackets resets it). If we come + % into this branch, then output.state is carefully undisturbed. + bracket.state open.brackets = + { " [" * } + { ", " * } % bracket.state will be within.brackets + if$ + s * + close.brackets 'bracket.state := + } + if$ +} + +% Call this function just before adding something which should be presented in +% brackets. bracket.state is handled specially within output.nonnull. +FUNCTION {inbrackets} +{ bracket.state close.brackets = + { within.brackets 'bracket.state := } % reset the state: not open nor closed + { open.brackets 'bracket.state := } + if$ +} + +FUNCTION {format.lastchecked} +{ lastchecked empty$ + { "" } + { inbrackets "cited " lastchecked * } + if$ +} +EOD + print OUT "$mymarkerend\n"; +} + +sub print_webpage_def { + print OUT "$mymarker...\n"; + + # Some of the functions below call new.block, so we need a dummy + # version, in the case where the style being edited doesn't supply + # that function. + if (! $found{newblock}) { + print OUT "FUNCTION {new.block} % dummy new.block function\n{\n % empty\n}\n\n"; + $found{newblock} = 1; + } + + print OUT <<'EOD'; +% Functions for making hypertext links. +% In all cases, the stack has (link-text href-url) +% +% make 'null' specials +FUNCTION {make.href.null} +{ + pop$ +} +% make hypertex specials +FUNCTION {make.href.hypertex} +{ + "\special {html:<a href=" quote$ * + swap$ * quote$ * "> }" * swap$ * + "\special {html:</a>}" * +} +% make hyperref specials +FUNCTION {make.href.hyperref} +{ + "\href {" swap$ * "} {\path{" * swap$ * "}}" * +} +FUNCTION {make.href} +{ hrefform #2 = + 'make.href.hyperref % hrefform = 2 + { hrefform #1 = + 'make.href.hypertex % hrefform = 1 + 'make.href.null % hrefform = 0 (or anything else) + if$ + } + if$ +} + +% If inlinelinks is true, then format.url should be a no-op, since it's +% (a) redundant, and (b) could end up as a link-within-a-link. +FUNCTION {format.url} +{ inlinelinks #1 = url empty$ or + { "" } + { hrefform #1 = + { % special case -- add HyperTeX specials + urlintro "\url{" url * "}" * url make.href.hypertex * } + { urlintro "\url{" * url * "}" * } + if$ + } + if$ +} + +FUNCTION {format.eprint} +{ eprint empty$ + { "" } + { eprintprefix eprint * eprinturl eprint * make.href } + if$ +} + +FUNCTION {format.doi} +{ doi empty$ + { "" } + { doiprefix doi * doiurl doi * make.href } + if$ +} + +FUNCTION {format.pubmed} +{ pubmed empty$ + { "" } + { pubmedprefix pubmed * pubmedurl pubmed * make.href } + if$ +} + +% Output a URL. We can't use the more normal idiom (something like +% `format.url output'), because the `inbrackets' within +% format.lastchecked applies to everything between calls to `output', +% so that `format.url format.lastchecked * output' ends up with both +% the URL and the lastchecked in brackets. +FUNCTION {output.url} +{ url empty$ + 'skip$ + { new.block + format.url output + format.lastchecked output + } + if$ +} + +FUNCTION {output.web.refs} +{ + new.block + inlinelinks + 'skip$ % links were inline -- don't repeat them + { + output.url + addeprints eprint empty$ not and + { format.eprint output.nonnull } + 'skip$ + if$ + adddoiresolver doi empty$ not and + { format.doi output.nonnull } + 'skip$ + if$ + addpubmedresolver pubmed empty$ not and + { format.pubmed output.nonnull } + 'skip$ + if$ + } + if$ +} + +% Wrapper for output.bibitem.original. +% If the URL field is not empty, set makeinlinelink to be true, +% so that an inline link will be started at the next opportunity +FUNCTION {output.bibitem} +{ outside.brackets 'bracket.state := + output.bibitem.original + inlinelinks url empty$ not doi empty$ not or pubmed empty$ not or eprint empty$ not or and + { #1 'makeinlinelink := } + { #0 'makeinlinelink := } + if$ +} + +% Wrapper for fin.entry.original +FUNCTION {fin.entry} +{ output.web.refs % urlbst + makeinlinelink % ooops, it appears we didn't have a title for inlinelink + { possibly.setup.inlinelink % add some artificial link text here, as a fallback + "[link]" output.nonnull } + 'skip$ + if$ + bracket.state close.brackets = % urlbst + { "]" * } + 'skip$ + if$ + fin.entry.original +} + +% Webpage entry type. +% Title and url fields required; +% author, note, year, month, and lastchecked fields optional +% See references +% ISO 690-2 http://www.nlc-bnc.ca/iso/tc46sc9/standard/690-2e.htm +% http://www.classroom.net/classroom/CitingNetResources.html +% http://neal.ctstateu.edu/history/cite.html +% http://www.cas.usf.edu/english/walker/mla.html +% for citation formats for web pages. +FUNCTION {webpage} +{ output.bibitem + author empty$ + { editor empty$ + 'skip$ % author and editor both optional + { format.editors output.nonnull } + if$ + } + { editor empty$ + { format.authors output.nonnull } + { "can't use both author and editor fields in " cite$ * warning$ } + if$ + } + if$ + new.block + title empty$ 'skip$ 'possibly.setup.inlinelink if$ + format.title "title" output.check + inbrackets "online" output + new.block + year empty$ + 'skip$ + { format.date "year" output.check } + if$ + % We don't need to output the URL details ('lastchecked' and 'url'), + % because fin.entry does that for us, using output.web.refs. The only + % reason we would want to put them here is if we were to decide that + % they should go in front of the rather miscellaneous information in 'note'. + new.block + note output + fin.entry +} +EOD + + print OUT "$mymarkerend\n\n\n"; +} + + +sub print_missing_functions { + # We've got to the bit of the file which handles the entry + # types, so write out the webpage entry handler. This uses + # the format.date function, which which many but not all + # bst files have (for example, apalike doesn't). So + # check that we either have found this function already, or + # add it. + if (! $found{formatdate}) { + if ($found{entrymonth}) { + print OUT <<'EOD'; +FUNCTION {format.date} +{ year empty$ + { month empty$ + { "" } + { "there's a month but no year in " cite$ * warning$ + month + } + if$ + } + { month empty$ + 'year + { month " " * year * } + if$ + } + if$ +} +EOD + } else { + print OUT <<'EOD'; +FUNCTION {format.date} +{ year empty$ + 'skip$ + { %write$ + "(" year * ")" * + } + if$ +} +EOD + } + $found{formatdate} = 1; + } + + # If the style file didn't supply a format.title function, then supply + # one here (the {webpage} function requires it). + if (! $found{formattitle}) { + print OUT <<'EOD'; +FUNCTION {format.title} +{ title empty$ + { "" } + { title "t" change.case$ } + if$ +} +EOD + $found{formattitle} = 1; + } +} + +# Utility function: Keep track of open and close braces in the string argument. +# Keep state in $bracematchtotal, return the current value. +sub bracematcher { + my $s = shift; + $s =~ s/[^\{\}]//g; + #print "s=$s\n"; + foreach my $c (split (//, $s)) { + $bracematchtotal += ($c eq '{' ? 1 : -1); + } + return $bracematchtotal; +} + +# Utility function: use bracematcher to copy the complete block which starts +# on or after the current line. +sub copy_block { + $bracematchtotal = 0; + # copy any leading lines which don't have braces (presumably comments) + while (defined ($line = <IN>) && ($line !~ /{/)) { + print OUT $line; + } + while (defined ($line) && bracematcher($line) > 0) { + print OUT $line; + $line = <IN>; + } + print OUT "$line\n"; # print out terminating \} (assumed + # alone on the line) +} diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.bib b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.bib new file mode 100644 index 00000000000..ee1cb4aac0e --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.bib @@ -0,0 +1,219 @@ +% Webpage with lastchecked and date +@webpage{url:weapas, + url = {http://www.beadsland.com/weapas/}, + title = {Web Extension to {American Psychological Association} Style ({WEAPAS}) (Rev.2.0)}, + author = {B Land}, + year = 2001, + month = jul, + lastchecked = {16 June 2008} +} + +@Manual{apastyle, + title = {Publication Manual of the American Psychological + Association}, + organization = {{American Psychological Association}}, + edition = {6th}, + year = 2009, + lastchecked = {9 August 2009}, + url = {http://www.apastyle.org/manual/index.aspx} +} + +@webpage{url:iso690, + author = {{International Standards Organisation}}, + title = {{ISO 690-2}}, + url = {http://en.wikipedia.org/wiki/ISO_690}, + lastchecked = {9 August 2009} +} + +% This one appears to be dead +@Webpage{gone:classroom96, + title = {Citing Internet Addresses: how students should + reference online sources in their bibliographies}, + year = 1996, + month = mar, + key = {Classroom}, + url = "http://www.classroom.net/classroom/CitingNetResources.html" +} + +@Webpage{emory95, + author = {{Goizueta Business Library}}, + title = "Citation Formats", + date = {1997}, + lastchecked = {9 August 2009}, + url = {http://business.library.emory.edu/eresources/citing.html} +} + +@Book{walker06, + author = {Janice R. Walker and Todd Taylor}, + title = {The Columbia Guide to Online Style}, + publisher = {Columbia University Press}, + year = 2006, + edition = {2nd}, + isbn = {978-0-231-13211-4}, + url = {http://cup.columbia.edu/book/978-0-231-13210-7/the-columbia-guide-to-online-style}, + lastchecked = {9 August 2009} +} + +% this one appears to be dead +@Webpage{walker-orig, + title = {{MLA}-Style Citations of Electronic Sources}, + author = {Janice R. Walker}, + url = {http://www.cas.usf.edu/english/walker/mla.html}, + year = 1995, + lastchecked = {23 October 2002}, + note = {Updated and superceded by \cite{walker}} +} + +@Webpage{texfaq, + url = {http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL}, + title = {{UK \TeX\ FAQ: URLs in BibTeX bibliographies}}, + key = {UK TeX FAQ}, + editor = {Robin Fairbairns}, + year = 2002, + lastchecked = {16 June 2008} +} + + + +@Webpage{url:daly, + url = {http://www.tex.ac.uk/tex-archive/macros/latex/contrib/custom-bib/}, + title = {Index of custom-bib}, + author = {Patrick W Daly}, + year = 2003, + lastchecked = {4 June 2003} +} + +% Following are test entries + +% Article with URL and lastchecked +@article{test:towell, + title = {Presence in Text-Based Networked Virtual + Environments or `{MUDs}'}, + author = {John Towell and Elizabeth Towell}, + journal = {Presence}, + volume = 6, + number = 5, + pages = {590-595}, + year = 1997, + url = {http://www-unix.mcs.anl.gov/~towell/presence.html}, + lastchecked = {13 February 2002} +} + +% Book with URL, lastchecked, and note. +@Book{test:raymond99, + author = {Eric S Raymond}, + title = {The Cathedral and the Bazaar}, + publisher = {O'Reilly}, + year = 1999, + url = {http://www.tuxedo.org}, + isbn = {1-56592-724-9}, + lastchecked = {1 April 2002}, + note = {The seminal book on the commercialisation of open-source} +} + +% Plain book, no URLs at all +@book{test:laurillard93, + author = {Diana Laurillard}, + title = {Rethinking University Teaching}, + publisher = {Routledge}, + year = 1993 +} + +% Webpage with lastchecked but no date +@webpage{test:iso690, + author = {{International Standards Organisation}}, + title = {{ISO 690-2}}, + url = {http://www.nlc-bnc.ca/iso/tc46sc9/standard/690-2e.htm}, + lastchecked = {20 August 2001} +} + +% Webpage with date but no lastchecked +@Webpage{test:classroom96, + title = {Citing Internet Addresses: how students should + reference online sources in their bibliographies}, + year = 1996, + month = mar, + key = {Classroom}, + url = "http://www.classroom.net/classroom/CitingNetResources.html" +} + +% Webpage with neither date nor lastchecked +@Webpage{test:emory95, + author = "libsf@web.cc.emory.edu", + title = "Citation Formats", + url = "http://www.emory.edu/WHSCL/citation.formats.html" +} + +% The same, but with no title either +@Webpage{test:emory95x, + author = "libsf@web.cc.emory.edu", + url = "http://www.emory.edu/WHSCL/citation.formats.html" +} + +% Article with eprint number +@techreport{test:simkin, + author = {Mikhail Simkin and V. P. Roychowdhury}, + title = {Read before you cite!}, + year = 2002, + institution = {UCLA}, + eprint = {cond-mat/0212043} +} + +% Article with a DOI +% an underscore +@article{test:gray00c, + author = "Norman Gray", + title = "Automatic Reduction of Elliptic Integrals using + {Carlson's} Relations", + journal = {Mathematics of Computation}, + volume = 71, + pages = {311-318}, + year = 2002, + doi = {10.1090/S0025-5718-01-01333-3} +} + +% Article with a PUBMED reference + + +@Article{test:giffin03, + author = {M J Giffin and J C Stroud and D L Bates and von Koenig, K D and J Hardin and L Chen}, + title = {Structure of {NFAT1} Bound as a Dimer to the {HIV-1 LTR} kappa {B} element}, + journal = {Nature Structural Biology}, + year = {2003}, + volume = {10}, + number = {10}, + pages = {800-6}, + month = oct, + pubmed = {12949493} +} + +@ARTICLE{test:nastydoi, + author = {Zemla, Adam and Venclovas, Ceslovas and Moult, John and + Fidelis, Krzysztof}, + title = {{P}rocessing and analysis of {CASP}3 protein structure predictions}, + journal = {Proteins: Structure, Function, and Genetics}, + year = {1999}, + volume = {37}, + pages = {22--29}, + number = {S3}, + month = jan, + comment = {Description of GDT measure.}, + doi = {10.1002/(SICI)1097-0134(1999)37:3+<22::AID-PROT5>3.0.CO;2-W}, + keywords = {CASP}, + timestamp = {2007-03-13} +} + +% Example from Jason Eisner, by mail (nothing special about the entry, +% but he seemed to be having formatting problems with unsrturl and proceedings +% entries. +@InProceedings{test:eisner-sample, + author = {Damianos Karakos and Sanjeev Khudanpur and Jason + Eisner and Carey~E. Priebe}, + title = {Iterative denoising using {J}ensen-{R}eny\'{\i} + divergences with an application to unsupervised + document categorization}, + booktitle = {Proceedings of ICASSP}, + year = 2007, + url = {http://cs.jhu.edu/~jason/papers/#icassp07} +} + diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.html b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.html new file mode 100644 index 00000000000..a169d5b1971 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.html @@ -0,0 +1,374 @@ +<?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="http://nxg.me.uk/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>.</p> + +<p>Version 0.6-5, 2011 March 8.</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='#information'>Further Information</a></li> +<li><a href='#history'>Version history</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 [--eprint] [--doi] [--pubmed] + [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] + [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.</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='http://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>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 (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...</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.6-5.tar.gz" >tarball</a> +or +<a href="urlbst-0.6-5.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='information'>Further Information and acknowledgements</a></h2> + +<p><code>urlbst</code> is archived on CTAN at <a +href="http://www.tex.ac.uk/tex-archive/biblio/bibtex/contrib/urlbst/" +><code>biblio/bibtex/contrib/urlbst/</code></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> + +<p>Thanks are due to many people for suggestions and requests, +and to 'ijvm' for code contributions.</p> + +<p>Copyright 2002-11, Norman Gray. Released under the terms of the GNU +General Public Licence.</p> + +<h2><a name='history'>Version history</a></h2> +<dl> +<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><p>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.</p> +<p>Incorporate hyperref bugfixes from Paweł Widera.</p> +<dl> +<dt>0.6b3</dt> +<dd>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.</dd> + +<dt>0.6b2</dt> +<dd>Reworked <code>inlinelinks</code> support; should now be more +robust. Incorporate hyperref bugfixes from Paweł Widera.</dd> + +<dt>0.6b1</dt> +<dd>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.</dd> +</dl> +</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 --eprint, --hypertex and --hyperref 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 class="signature"> +<a href="http://nxg.me.uk" + >Norman Gray</a><br/> +2011 March 8 +</div> + +</body> +</html> diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.html.in b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.html.in new file mode 100644 index 00000000000..8a3de2e4387 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.html.in @@ -0,0 +1,374 @@ +<?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="http://nxg.me.uk/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>.</p> + +<p>Version @PACKAGE_VERSION@, @RELEASEDATE@.</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='#information'>Further Information</a></li> +<li><a href='#history'>Version history</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 [--eprint] [--doi] [--pubmed] + [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] + [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.</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='http://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>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 (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...</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-@PACKAGE_VERSION@.tar.gz" >tarball</a> +or +<a href="urlbst-@PACKAGE_VERSION@.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='information'>Further Information and acknowledgements</a></h2> + +<p><code>urlbst</code> is archived on CTAN at <a +href="http://www.tex.ac.uk/tex-archive/biblio/bibtex/contrib/urlbst/" +><code>biblio/bibtex/contrib/urlbst/</code></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> + +<p>Thanks are due to many people for suggestions and requests, +and to 'ijvm' for code contributions.</p> + +<p>Copyright 2002-11, Norman Gray. Released under the terms of the GNU +General Public Licence.</p> + +<h2><a name='history'>Version history</a></h2> +<dl> +<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><p>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.</p> +<p>Incorporate hyperref bugfixes from Paweł Widera.</p> +<dl> +<dt>0.6b3</dt> +<dd>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.</dd> + +<dt>0.6b2</dt> +<dd>Reworked <code>inlinelinks</code> support; should now be more +robust. Incorporate hyperref bugfixes from Paweł Widera.</dd> + +<dt>0.6b1</dt> +<dd>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.</dd> +</dl> +</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 --eprint, --hypertex and --hyperref 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 class="signature"> +<a href="http://nxg.me.uk" + >Norman Gray</a><br/> +@RELEASEDATE@ +</div> + +</body> +</html> diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.in b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.in new file mode 100755 index 00000000000..f212601f96b --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.in @@ -0,0 +1,763 @@ +#! @PERL@ -w +# +# Usage: ./urlbst.pl [--eprint] [--doi] [--pubmed] +# [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref] +# [input-file [output-file]] +# If either input-file or output-file is omitted, they are replaced by +# stdin or stdout respectively. +# +# See http://purl.org/nxg/dist/urlbst for documentation +# +# $Id$ + +$version = '@PACKAGE_VERSION@'; +($progname = $0) =~ s/.*\///; +$mymarker = "% $progname"; +$mymarkerend = "% ...$progname to here"; +$myurl = 'http://purl.org/nxg/dist/urlbst'; + + +$infile = '-'; +$outfile = '-'; + +$addeprints = @WITHEPRINTS@; # if true (nonzero) we add support for eprints +$eprintprefix = 'arXiv:'; # make these settable with --eprint? syntax? +$eprinturl = '@EPRINTURL@'; + +$adddoiresolver = @WITHDOIRESOLVER@; +$doiprefix = 'doi:'; +$doiurl = '@DOIURL@'; + +$addpubmedresolver = @WITHPUBMEDRESOLVER@; +$pubmedprefix = 'PMID:'; +$pubmedurl = '@PUBMEDURL@'; + +$makehref = @WITHHREF@; +$availablestring = "Available from: "; +$inlinelinks = 0; + +$automatic_output_filename = 0; + +$Usage = "$progname [--eprint] [--doi] [--pubmed]\n [--nohyperlinks] [--[no]inlinelinks] [--hypertex] [--hyperref]\n [--help] [input-file [output-file]]"; + +# Magic environment variable: if this is set, then we're being called from a Platypus wrapper +# See http://www.sveinbjorn.org/platypus +if ($ENV{"CALLED_FROM_PLATYPUS"}) { + $automatic_output_filename = 1; +} + +while ($#ARGV >= 0) { + if ($ARGV[0] eq '--eprint') { + $addeprints = 1; + } elsif ($ARGV[0] eq '--doi') { + $adddoiresolver = 1; + } elsif ($ARGV[0] eq '--pubmed') { + $addpubmedresolver = 1; + } elsif ($ARGV[0] eq '--nohyperlinks') { + $makehref = 0; + } elsif ($ARGV[0] eq '--hypertex') { + $makehref = 1; + } elsif ($ARGV[0] eq '--hyperref') { + $makehref = 2; + } elsif ($ARGV[0] eq '--inlinelinks') { + $inlinelinks = 1; + } elsif ($ARGV[0] eq '--noinlinelinks') { + $inlinelinks = 0; + } elsif ($ARGV[0] eq '--automatic-output') { + $automatic_output_filename = 1; + } elsif ($ARGV[0] eq '--help') { + print <<EOD; +urlbst version $version + Usage: $Usage + --eprint: include support for `eprint' fields + --doi: include support for `doi' field + --pubmed: include support for `pubmed' field + --nohyperlinks do not include active links anywhere + --inlinelinks add hyperlinks to entry titles + --hypertex: include HyperTeX-style hyperlink support + --hyperref: include {hyperref}-style hyperlink support + (generally better) + --help: print this help + Input and output files may be given as `-' (default) to indicate stdin/out +EOD + exit(0); + } elsif ($ARGV[0] =~ /^-/) { + die "Unrecognised option $ARGV[0]: Usage: $Usage\n"; + } elsif ($infile eq '-') { + $infile = $ARGV[0]; + } elsif ($outfile eq '-') { + $outfile = $ARGV[0]; + } else { + die "Usage: $Usage\n"; + } + shift(@ARGV); +} + +if ($inlinelinks && $makehref == 0) { + print <<'EOD'; +Warning: --inlinelinks and --nohyperlinks were both specified (possibly + implicitly). That combination makes no sense, so I'll ignore + --nohyperlinks and use --hyperref instead +EOD + $makehref = 2; +} + +if ($automatic_output_filename) { + if ($infile eq '-') { + print "ERROR: No input filename given with --automatic-output\n"; + } + $outfile = $infile; + @outparts = split /\./, $outfile; + $ext = pop(@outparts); + $outfile=join('.', @outparts); + if ($outfile eq '') { + $outfile = $ext . '-url'; + } else { + $outfile = $outfile . '-url.' . $ext; + } +} + +$exitstatus = 0; # success status + +open (IN, "<$infile") || die "Can't open $infile to read"; +open (OUT, ">$outfile") || die "Can't open $outfile to write"; + +# We have to make certain assumptions about the source files, in order +# to patch them at the correct places. Specifically, we assume that +# +# - there's a function init.state.consts +# +# - ...and an output.nonnull which does the actual outputting, which +# has the `usual' interface. +# +# - we can replace +# fin.entry +# by +# new.block +# output.url % the function which formats and displays any URL +# fin.entry +# +# - there is a function which handles the `article' entry type (this +# will always be true) +# +# - there is a function output.bibitem which is called at the +# beginning of each entry type +# - ...and one called fin.entry which is called at the end +# +# If the functions format.date, format.title or new.block are not defined (the +# former is not in apalike, for example, and the last is not in the +# AMS styles), then replacements are included in the output. +# +# All these assumptions are true of the standard files and, since most +# style files derive from them more or less directly, are true of most (?) +# other style files, too. +# +# There's some rather ugly Perl down here. The parsing for +# brace-matching could probably do with being rewritten in places, to +# make it less ugly, and more robust. + +print OUT "%%% Modification of BibTeX style file ", ($infile eq '-' ? '<stdin>' : $infile), "\n"; +print OUT "%%% ... by $progname, version $version (marked with \"$mymarker\")\n%%% See <$myurl>\n"; +print OUT "%%% Added webpage entry type, and url and lastchecked fields.\n"; +print OUT "%%% Added eprint support.\n" if ($addeprints); +print OUT "%%% Added DOI support.\n" if ($adddoiresolver); +print OUT "%%% Added PUBMED support.\n" if ($addpubmedresolver); +print OUT "%%% Added HyperTeX support.\n" if ($makehref == 1); +print OUT "%%% Added hyperref support.\n" if ($makehref == 2); +print OUT "%%% Original headers follow...\n\n"; + +$found{initconsts} = 0; +$found{outputnonnull} = 0; +$found{article} = 0; +$found{outputbibitem} = 0; +$found{finentry} = 0; +$found{formatdate} = 0; +$found{formattitle} = 0; +$found{newblock} = 0; + +while (<IN>) { + /^ *%/ && do { + # Pass commented lines unchanged + print OUT; + next; + }; + + /^ *ENTRY/ && do { + # Work through the list of entry types, finding what ones are there. + # If we find a URL entry there already, object, since these edits + # will mess things up. + $line = $_; + until ($line =~ /\{\s*(\w*)/) { + $line .= <IN>; + } + $bracematchtotal = 0; # reset + bracematcher($line); + $line =~ /\{\s*(\w*)/; + $found{'entry'.$1} = 1; + print OUT $line; + $line = <IN>; + until (bracematcher($line) == 0) { + # XXX deal with multiple entries on one line + ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); + print OUT $line; + $line = <IN>; + } + if (defined($found{entryurl})) { + print STDERR "$progname: style file $infile already has URL entry!\n"; + # print out the rest of the file, and give up + print OUT $line; + while (<IN>) { + print OUT; + } + $exitstatus = 1; + last; + } else { + print OUT " eprint $mymarker\n doi $mymarker\n pubmed $mymarker\n url $mymarker\n lastchecked $mymarker\n"; + } + print OUT $line; + next; + }; + + /^ *FUNCTION *\{init\.state\.consts\}/ && do { + # In the init.state.consts function, add an extra set of + # constants at the beginning. Also use this as the marker for + # the place to add the init strings function. + print OUT <<EOD; +$mymarker... +% urlbst constants and state variables +STRINGS { urlintro + eprinturl eprintprefix doiprefix doiurl pubmedprefix pubmedurl + openinlinelink closeinlinelink } +INTEGERS { hrefform inlinelinks makeinlinelink + addeprints adddoiresolver addpubmedresolver } +FUNCTION {init.urlbst.variables} +{ + % The following constants may be adjusted by hand, if desired + + % The first set allow you to enable or disable certain functionality. + #$addeprints 'addeprints := % 0=no eprints; 1=include eprints + #$adddoiresolver 'adddoiresolver := % 0=no DOI resolver; 1=include it + #$addpubmedresolver 'addpubmedresolver := % 0=no PUBMED resolver; 1=include it + #$makehref 'hrefform := % 0=no crossrefs; 1=hypertex xrefs; 2=hyperref refs + #$inlinelinks 'inlinelinks := % 0=URLs explicit; 1=URLs attached to titles + + % String constants, which you _might_ want to tweak. + "$availablestring" 'urlintro := % prefix before URL + "$eprinturl" 'eprinturl := % prefix to make URL from eprint ref + "$eprintprefix" 'eprintprefix := % text prefix printed before eprint ref + "$doiurl" 'doiurl := % prefix to make URL from DOI + "$doiprefix" 'doiprefix := % text prefix printed before DOI ref + "$pubmedurl" 'pubmedurl := % prefix to make URL from PUBMED + "$pubmedprefix" 'pubmedprefix := % text prefix printed before PUBMED ref + + % The following are internal state variables, not configuration constants, + % so they shouldn't be fiddled with. + #0 'makeinlinelink := % state variable managed by possibly.setup.inlinelink + "" 'openinlinelink := % ditto + "" 'closeinlinelink := % ditto +} +INTEGERS { + bracket.state + outside.brackets + open.brackets + within.brackets + close.brackets +} +$mymarkerend +EOD + $line = $_; + until ($line =~ /\{.*\}.*\{/s) { + $line .= <IN>; + } + $line =~ s/(\{.*?\}.*?\{)/$1 #0 'outside.brackets := $mymarker... + #1 'open.brackets := + #2 'within.brackets := + #3 'close.brackets := $mymarkerend + + /s; + print OUT $line; + $found{initconsts} = 1; + next; + }; + + /^ *EXECUTE *\{init\.state\.consts\}/ && do { + print OUT "EXECUTE {init.urlbst.variables} $mymarker\n"; + print OUT; + next; + }; + + /^ *FUNCTION *\{new.block\}/ && do { + $found{newblock} = 1; + }; + + /^ *FUNCTION *{output\.nonnull}/ && do { + print OUT "$mymarker\n"; + print OUT "FUNCTION {output.nonnull.original}\n"; + copy_block(); + print_output_functions(); + $found{outputnonnull} = 1; + next; + }; + + /FUNCTION *\{fin.entry\}/ && do { + # Rename fin.entry to fin.entry.original (wrapped below) + s/fin.entry/fin.entry.original/; + s/$/ $mymarker (renamed from fin.entry, so it can be wrapped below)/; + $found{finentry} = 1; + print OUT; + next; + }; + + /^ *FUNCTION *{format\.date}/ && do { + $found{formatdate} = 1; + print OUT; + next; + }; + + /^ *FUNCTION *{format\.title}/ && do { + # record that we found this + $found{formattitle} = 1; + print OUT; + next; + }; + + /^ *format\.b?title/ && do { + # interpolate a call to possibly.setup.inlinelink + print OUT " title empty\$ 'skip\$ 'possibly.setup\.inlinelink if\$ $mymarker\n"; + print OUT; + next; + }; + + /^ *format\.vol\.num\.pages/ && do { + # interpolate a call to possibly.setup.inlinelink + s/^( *)/$1possibly.setup.inlinelink /; + s/$/$mymarker/; + print OUT; + next; + }; + + /^ *FUNCTION *\{article\}/ && do { + + print_missing_functions(); + print_webpage_def(); + + print OUT; + $found{article} = 1; + next; + }; + + /FUNCTION *\{output.bibitem\}/ && do { + # Rename output.bibitem to output.bibitem.original (wrapped below) + s/{output.bibitem\}/\{output.bibitem.original\}/; + s/$/ $mymarker (renamed from output.bibitem, so it can be wrapped below)/; + $found{outputbibitem} = 1; + print OUT; + next; + }; + + print OUT; +}; + +if ($exitstatus == 0) { + # Skip this if we've already reported an error -- it'll only be confusing + foreach $k (keys %found) { + if ($found{$k} == 0) { + print STDERR "$progname: $infile: failed to find feature $k\n"; + } + } +} + +close (IN); +close (OUT); + +exit $exitstatus;; + + + + + + +sub print_output_functions { + print OUT "$mymarker...\n"; + + print OUT <<'EOD'; +% The following three functions are for handling inlinelink. They wrap +% a block of text which is potentially output with write$ by multiple +% other functions, so we don't know the content a priori. +% They communicate between each other using the variables makeinlinelink +% (which is true if a link should be made), and closeinlinelink (which holds +% the string which should close any current link. They can be called +% at any time, but start.inlinelink will be a no-op unless something has +% previously set makeinlinelink true, and the two ...end.inlinelink functions +% will only do their stuff if start.inlinelink has previously set +% closeinlinelink to be non-empty. +% (thanks to 'ijvm' for suggested code here) +FUNCTION {uand} +{ 'skip$ { pop$ #0 } if$ } % 'and' (which isn't defined at this point in the file) +FUNCTION {possibly.setup.inlinelink} +{ makeinlinelink hrefform #0 > uand + { doi empty$ adddoiresolver uand + { pubmed empty$ addpubmedresolver uand + { eprint empty$ addeprints uand + { url empty$ + { "" } + { url } + if$ } + { eprinturl eprint * } + if$ } + { pubmedurl pubmed * } + if$ } + { doiurl doi * } + if$ + % an appropriately-formatted URL is now on the stack + hrefform #1 = % hypertex + { "\special {html:<a href=" quote$ * swap$ * quote$ * "> }{" * 'openinlinelink := + "\special {html:</a>}" 'closeinlinelink := } + { "\href {" swap$ * "} {" * 'openinlinelink := % hrefform=#2 -- hyperref + % the space between "} {" matters: a URL of just the right length can cause "\% newline em" + "}" 'closeinlinelink := } + if$ + #0 'makeinlinelink := + } + 'skip$ + if$ % makeinlinelink +} +FUNCTION {add.inlinelink} +{ openinlinelink empty$ + 'skip$ + { openinlinelink swap$ * closeinlinelink * + "" 'openinlinelink := + } + if$ +} +EOD + + # new.block is defined elsewhere + + print OUT <<'EOD'; +FUNCTION {output.nonnull} +{ % Save the thing we've been asked to output + 's := + % If the bracket-state is close.brackets, then add a close-bracket to + % what is currently at the top of the stack, and set bracket.state + % to outside.brackets + bracket.state close.brackets = + { "]" * + outside.brackets 'bracket.state := + } + 'skip$ + if$ + bracket.state outside.brackets = + { % We're outside all brackets -- this is the normal situation. + % Write out what's currently at the top of the stack, using the + % original output.nonnull function. + s + add.inlinelink + output.nonnull.original % invoke the original output.nonnull + } + { % Still in brackets. Add open-bracket or (continuation) comma, add the + % new text (in s) to the top of the stack, and move to the close-brackets + % state, ready for next time (unless inbrackets resets it). If we come + % into this branch, then output.state is carefully undisturbed. + bracket.state open.brackets = + { " [" * } + { ", " * } % bracket.state will be within.brackets + if$ + s * + close.brackets 'bracket.state := + } + if$ +} + +% Call this function just before adding something which should be presented in +% brackets. bracket.state is handled specially within output.nonnull. +FUNCTION {inbrackets} +{ bracket.state close.brackets = + { within.brackets 'bracket.state := } % reset the state: not open nor closed + { open.brackets 'bracket.state := } + if$ +} + +FUNCTION {format.lastchecked} +{ lastchecked empty$ + { "" } + { inbrackets "cited " lastchecked * } + if$ +} +EOD + print OUT "$mymarkerend\n"; +} + +sub print_webpage_def { + print OUT "$mymarker...\n"; + + # Some of the functions below call new.block, so we need a dummy + # version, in the case where the style being edited doesn't supply + # that function. + if (! $found{newblock}) { + print OUT "FUNCTION {new.block} % dummy new.block function\n{\n % empty\n}\n\n"; + $found{newblock} = 1; + } + + print OUT <<'EOD'; +% Functions for making hypertext links. +% In all cases, the stack has (link-text href-url) +% +% make 'null' specials +FUNCTION {make.href.null} +{ + pop$ +} +% make hypertex specials +FUNCTION {make.href.hypertex} +{ + "\special {html:<a href=" quote$ * + swap$ * quote$ * "> }" * swap$ * + "\special {html:</a>}" * +} +% make hyperref specials +FUNCTION {make.href.hyperref} +{ + "\href {" swap$ * "} {\path{" * swap$ * "}}" * +} +FUNCTION {make.href} +{ hrefform #2 = + 'make.href.hyperref % hrefform = 2 + { hrefform #1 = + 'make.href.hypertex % hrefform = 1 + 'make.href.null % hrefform = 0 (or anything else) + if$ + } + if$ +} + +% If inlinelinks is true, then format.url should be a no-op, since it's +% (a) redundant, and (b) could end up as a link-within-a-link. +FUNCTION {format.url} +{ inlinelinks #1 = url empty$ or + { "" } + { hrefform #1 = + { % special case -- add HyperTeX specials + urlintro "\url{" url * "}" * url make.href.hypertex * } + { urlintro "\url{" * url * "}" * } + if$ + } + if$ +} + +FUNCTION {format.eprint} +{ eprint empty$ + { "" } + { eprintprefix eprint * eprinturl eprint * make.href } + if$ +} + +FUNCTION {format.doi} +{ doi empty$ + { "" } + { doiprefix doi * doiurl doi * make.href } + if$ +} + +FUNCTION {format.pubmed} +{ pubmed empty$ + { "" } + { pubmedprefix pubmed * pubmedurl pubmed * make.href } + if$ +} + +% Output a URL. We can't use the more normal idiom (something like +% `format.url output'), because the `inbrackets' within +% format.lastchecked applies to everything between calls to `output', +% so that `format.url format.lastchecked * output' ends up with both +% the URL and the lastchecked in brackets. +FUNCTION {output.url} +{ url empty$ + 'skip$ + { new.block + format.url output + format.lastchecked output + } + if$ +} + +FUNCTION {output.web.refs} +{ + new.block + inlinelinks + 'skip$ % links were inline -- don't repeat them + { + output.url + addeprints eprint empty$ not and + { format.eprint output.nonnull } + 'skip$ + if$ + adddoiresolver doi empty$ not and + { format.doi output.nonnull } + 'skip$ + if$ + addpubmedresolver pubmed empty$ not and + { format.pubmed output.nonnull } + 'skip$ + if$ + } + if$ +} + +% Wrapper for output.bibitem.original. +% If the URL field is not empty, set makeinlinelink to be true, +% so that an inline link will be started at the next opportunity +FUNCTION {output.bibitem} +{ outside.brackets 'bracket.state := + output.bibitem.original + inlinelinks url empty$ not doi empty$ not or pubmed empty$ not or eprint empty$ not or and + { #1 'makeinlinelink := } + { #0 'makeinlinelink := } + if$ +} + +% Wrapper for fin.entry.original +FUNCTION {fin.entry} +{ output.web.refs % urlbst + makeinlinelink % ooops, it appears we didn't have a title for inlinelink + { possibly.setup.inlinelink % add some artificial link text here, as a fallback + "[link]" output.nonnull } + 'skip$ + if$ + bracket.state close.brackets = % urlbst + { "]" * } + 'skip$ + if$ + fin.entry.original +} + +% Webpage entry type. +% Title and url fields required; +% author, note, year, month, and lastchecked fields optional +% See references +% ISO 690-2 http://www.nlc-bnc.ca/iso/tc46sc9/standard/690-2e.htm +% http://www.classroom.net/classroom/CitingNetResources.html +% http://neal.ctstateu.edu/history/cite.html +% http://www.cas.usf.edu/english/walker/mla.html +% for citation formats for web pages. +FUNCTION {webpage} +{ output.bibitem + author empty$ + { editor empty$ + 'skip$ % author and editor both optional + { format.editors output.nonnull } + if$ + } + { editor empty$ + { format.authors output.nonnull } + { "can't use both author and editor fields in " cite$ * warning$ } + if$ + } + if$ + new.block + title empty$ 'skip$ 'possibly.setup.inlinelink if$ + format.title "title" output.check + inbrackets "online" output + new.block + year empty$ + 'skip$ + { format.date "year" output.check } + if$ + % We don't need to output the URL details ('lastchecked' and 'url'), + % because fin.entry does that for us, using output.web.refs. The only + % reason we would want to put them here is if we were to decide that + % they should go in front of the rather miscellaneous information in 'note'. + new.block + note output + fin.entry +} +EOD + + print OUT "$mymarkerend\n\n\n"; +} + + +sub print_missing_functions { + # We've got to the bit of the file which handles the entry + # types, so write out the webpage entry handler. This uses + # the format.date function, which which many but not all + # bst files have (for example, apalike doesn't). So + # check that we either have found this function already, or + # add it. + if (! $found{formatdate}) { + if ($found{entrymonth}) { + print OUT <<'EOD'; +FUNCTION {format.date} +{ year empty$ + { month empty$ + { "" } + { "there's a month but no year in " cite$ * warning$ + month + } + if$ + } + { month empty$ + 'year + { month " " * year * } + if$ + } + if$ +} +EOD + } else { + print OUT <<'EOD'; +FUNCTION {format.date} +{ year empty$ + 'skip$ + { %write$ + "(" year * ")" * + } + if$ +} +EOD + } + $found{formatdate} = 1; + } + + # If the style file didn't supply a format.title function, then supply + # one here (the {webpage} function requires it). + if (! $found{formattitle}) { + print OUT <<'EOD'; +FUNCTION {format.title} +{ title empty$ + { "" } + { title "t" change.case$ } + if$ +} +EOD + $found{formattitle} = 1; + } +} + +# Utility function: Keep track of open and close braces in the string argument. +# Keep state in $bracematchtotal, return the current value. +sub bracematcher { + my $s = shift; + $s =~ s/[^\{\}]//g; + #print "s=$s\n"; + foreach my $c (split (//, $s)) { + $bracematchtotal += ($c eq '{' ? 1 : -1); + } + return $bracematchtotal; +} + +# Utility function: use bracematcher to copy the complete block which starts +# on or after the current line. +sub copy_block { + $bracematchtotal = 0; + # copy any leading lines which don't have braces (presumably comments) + while (defined ($line = <IN>) && ($line !~ /{/)) { + print OUT $line; + } + while (defined ($line) && bracematcher($line) > 0) { + print OUT $line; + $line = <IN>; + } + print OUT "$line\n"; # print out terminating \} (assumed + # alone on the line) +} diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf Binary files differnew file mode 100644 index 00000000000..51da2dfe7be --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex new file mode 100644 index 00000000000..c642188d7c0 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex @@ -0,0 +1,278 @@ +\documentclass[a4paper]{article} + +\title{The \texttt{urlbst} package} +\author{Norman Gray\\\texttt{<http://nxg.me.uk>}} +\date{Version 0.6-5, 2011 March 8} + +%\usepackage{times} +\usepackage{url} +\usepackage{hyperref} + +% Not long enough to make it useful to number sections +\setcounter{secnumdepth}{0} + +% Squeeze a bit more on to the page +%\addtolength\textwidth{1cm} +%\addtolength\oddsidemargin{-0.5cm} + +\makeatletter +% Easy verbatim mode +\catcode`\|=\active +\def|{\begingroup \let\do\@makeother \dospecials \verbatim@font \doverb} +\def\doverb#1|{#1\endgroup} + +\renewcommand{\verbatim@font}{\normalfont\small\ttfamily} +\makeatother + +\newcommand{\ub}{\package{urlbst}} +\newcommand{\BibTeX}{Bib\TeX} +\newcommand{\package}[1]{\texttt{#1}} +\newcommand{\btfield}[1]{\textsf{#1}} + +\begin{document} +\maketitle + +The \ub\ package consists of a Perl script which edits \BibTeX\ style +files (|.bst|) to add a \btfield{webpage} entry type, and which adds a +few new fields -- notably including \btfield{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 \package{custom-bib} +package~\cite{url:daly} -- that is intended to create a \BibTeX\ style +|.bst| file from scratch, and supports \btfield{url} and +\btfield{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 \btfield{webpage} entry type, plus the new fields. + +The added fields are: +\begin{itemize} +\item \btfield{url} and \btfield{lastchecked}, to associate a URL with + a reference, along with the date at which the URL was last checked + to exist; +\item \btfield{doi}, for a reference's DOI + (see \url{http://doi.org}); +\item \btfield{eprint}, for an arXiv eprint reference + (see \url{http://arxiv.org}); and +\item \btfield{pubmed} for a reference's PubMed identifier + (\textsc{PMID}, see \url{http://pubmed.gov}). +\end{itemize} + +Usage is simple: +\begin{verbatim} +% urlbst [--eprint] [--doi] [--pubmed] + [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref] + [input-file [output-file]] +\end{verbatim} +where the |input-file| is an existing |.bst| file, and +the |output-file| is the name of the new style file to be +created. If either file name is missing, the default is the +standard input or standard output respectively. +For example: +\begin{verbatim} +% urlbst --eprint bibstyle.bst +\end{verbatim} +would convert the style file \texttt{bibstyle.bst}, including support +for e-prints, and sending the result to the standard output (ie, the +screen, so it would more useful if you were to either redirect this to +a file or supply the output-file argument). + +If the option |--eprint| is present, then we switch on support for +\texttt{eprint} fields in the modified .bst file, with a citation +format matching that recommended in +\url{http://arxiv.org/help/faq/references}. If the option +|--doi| is present, we include support for a |doi| field, referring +to a Digital Object Identifier (DOI) as standardised by +\url{http://www.doi.org/}. And if |--pubmed| is present, we include +support for a |pubmed| field, referring to a PubMed identifier as +supported at \url{http://www.pubmed.gov}. + +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 Hyper\TeX\ (see +\url{http://arxiv.org/hypertex/#implementation}), supported by xdvi, +dvips and others, or using the support available from the +\package{hyperref} package. These options have no effect unless one +of the |--eprint|, |--doi|, |--pubmed| or |--inlinelinks| options is given: +when URLs are included +in the bibliography, they are written out using the |\url{...}| +command. The \package{hyperref} support is more generic, and more +generally supported, and so you should choose this unless you have a +particular need for the Hyper\TeX\ support. The |--nohyperlinks| +option, which is present by default, suppresses all hyperlinking. + +By default, any URL field is displayed as part of the bibliography +entry, linked to the corresponding URL via the mechanism managed by +the |--hypertex| and |--hyperref| options. If the |--inlinelinks| +option is present, however, then the URL is not displayed in the +printed entry, but instead a hyperlink is created, linked to suitable +text within the bibliography entry, such as the citation title. This +option does not affect the display of eprints, DOI or PubMed fields. It makes +no sense to specify |--inlinelinks| with |--nohyperlinks|, and the +script warns you if you do that, for example by failing to specify one +of the link-style options. This option is (primarily) useful if +you're preparing a version of a document which will be read on-screen; +the point of it is that the resulting bibliography is substantially +more compact than it would otherwise be. + +The support for all the above behaviours is always included in the +output file. The options instead control only whether the various +behaviours are enabled or disabled, and if you need to alter these, +you may do so by editing the generated |.bst| file and adjusting +values in the |{init.urlbst.variables}| function, where indicated. + +The generated references have URLs inside |\url{...}|. The best +way to format this this is with the \package{url} package +(see~\cite{texfaq} for pointers), but as a poor alternative, you can +try |\newcommand{\url}[1]{\texttt{#1}}|. The \package{hyperref} +package automatically processes |\url{...}| in the correct way to +include a hyperlink, and if you have selected \package{hyperref} +output, then nothing more need be done. If you selected Hyper\TeX\ +output, however, then the script encloses the |\url| command in an +appropriate Hyper\TeX\ special. + +When the style file generates a link for DOIs, it does so by +prepending the string \texttt{http://dx.doi.org/} to the DOI. This is +generally reasonable, but some DOIs have characters in them which are +illegal in URLs, with the result that the resulting +\texttt{dx.doi.org} URL doesn't work. The only real way of resolving +this is to write a URL-encoding function in the style-file +implementation language, but while that would doubtless be feasible in +principle, it would be hard and very, very, ugly. The only advice I +can offer in this case is to rely on the fact that the DOI will still +appear in the typeset bibliography, and that users who would want to +take advantage of the DOI will frequently (or usually?) know how to +resolve the DOI when then need to. As a workaround, you could include +a URL-encoded DOI URL in the \btfield{url} field of the entry (thanks +to Eric Chamberland for this suggestion). + +The \ub\ script works by spotting patterns and characteristic function +names in the input |.bst| file. It works as-is in the case of the +four standard \BibTeX\ style files |plain.bst|, |unsrt.bst|, +|alpha.bst| and |abbrv.bst|. It also works straightforwardly for +many other style files -- since many of these are derived from, or at +least closely inspired by, the standard ones -- but it does not +pretend that it can do so for all of them. In some cases, such as the +style files for the \package{refer} or \package{koma-script} packages, +the style files are not intended to be used for formatting; others are +sufficiently different from the standard files that a meaningful edit +becomes impossible. For the large remainder, however, the result of +this script should need only relatively minor edits before being +perfectly usable. + +\section{New \texttt{.bib} entry and field types} + +The new entry type \btfield{webpage} has required fields +\btfield{title} and \btfield{url}, and optional fields +\btfield{author}, \btfield{editor}, \btfield{note}, \btfield{year}, +\btfield{month} and \btfield{lastchecked}. The \btfield{url} and +\btfield{lastchecked} fields are new, and are +valid in other entry types as well: the first, obviously, is the URL +which is being cited, or which is being quoted as an auxiliary source +for an article perhaps; the second is the date when you last checked +that the URL was there, in the state you quoted it; this is necessary +since some people, heedless of the archival importance of preserving +the validity of URLs, indulge in the vicious practice of reorganising +web pages and destroying links. For the case of the \btfield{webpage} entry +type, the \btfield{editor} field should be used for the `maintainer' +of a web page. + +For example, in Figure~\ref{f:ex} we illustrate two potential |.bib| +file entries. The \texttt{@webpage} entry type is the new type +provided by this package, and provides reference information for a +webpage; it includes the new \texttt{url} and \texttt{lastchecked} +fields. There is also an example of the standard \texttt{@book} entry +type, which now includes the \texttt{url} and \texttt{lastchecked} +fields as well. The difference between the two references is that in +the \texttt{@book} case it is the book being cited, so that the +\texttt{url} provides extra information; in the \texttt{@webpage} case +it is the page itself which is of interest. You use the new |eprint|, +|doi| and |pubmed| fields similarly, if the bibliographic item in +question has an e-print, DOI or PubMed reference. +\begin{figure} +\begin{verbatim} +@Manual{w3chome, + url = {http://www.w3.org}, + title = {The World Wide Web Consortium}, + year = 2009, + lastchecked = {26 August 2009}} + +@Book{schutz, + author = {Bernard Schutz}, + title = {Gravity from the GroundUp}, + publisher = {Cambridge University Press}, + year = {2003}, + url = {http://www.gravityfromthegroundup.org/}, + lastchecked = {2008 June 16}} +\end{verbatim} +\caption{\label{f:ex}The new \texttt{@webpage} entry type, and the \texttt{url} + field in action} +\end{figure} + +How do you use this in a document? To use the the +\texttt{alphaurl.bst} style -- which is a pre-converted version of the +standard \texttt{alpha.bst} style, included in the \texttt{urlbst} +distribution -- you simply make sure that \texttt{alphaurl.bst} is in +your BibTeX search path (use the command \texttt{kpsepath bst} to find +this path and \texttt{kpsewhich alphaurl.bst} to confirm that BibTeX +can find it) and add |\bibliographystyle{alphaurl}| to your \LaTeX\ document. + +\section{Sources} + +There are various sources which suggest how to format references to +web pages. I have followed none specifically, but fortunately they do +not appear to materially disagree. + +ISO-690~\cite{url:iso690} is a formal standard for this stuff. Walker +and Taylor's \emph{Columbia Guide to Online Style}~\cite{walker06} +provides extensive coverage (but is only available on dead trees). +Emory University's +\emph{Citation Formats}~\cite{emory95} is a compendium of links rather +than a guide itself. The APA has a couple of style guides, a proposed +one~\cite{url:weapas} and a style included in the published APA style +guide~\cite{apastyle} (I'm not sure of the relationship between these +last two). + +\section{Hints} + +If you use Emacs' \BibTeX\ mode, you can insert the following in your +|.emacs| file to add knowledge of the new \btfield{webpage} entry: +\begin{verbatim} +(defun my-bibtex-hook () + (setq bibtex-mode-user-optional-fields '("location" "issn")) ; e.g. + (setq bibtex-entry-field-alist + (cons + '("Webpage" + ((("url" "The URL of the page") + ("title" "The title of the resource")) + (("author" "The author of the webpage") + ("editor" "The editor/maintainer of the webpage") + ("year" "Year of publication of the page") + ("month" "Month of publication of the page") + ("lastchecked" "Date when you last verified the page was there") + ("note" "Remarks to be put at the end of the entry")))) + bibtex-entry-field-alist))) +(add-hook 'bibtex-mode-hook 'my-bibtex-hook) +\end{verbatim} +After that, you can add a \btfield{webpage} entry by typing |C-c C-b webpage| +(or |M-x bibtex-entry|). + +It is a \emph{very} good idea to use the \package{url} package: it deals with +the problem of line-breaking long URLs, and with the problem that +\BibTeX{} creates, of occasionally inserting \%-signs into URLs in +generated bibliographies. + +See also the URL entry in the UK \TeX\ FAQ~\cite{texfaq}, and +references therein. + +\textbf{Acknowledgements:} Thanks to Jason Eisner for suggesting +the |--inlinelinks| option, to Pawe\l{} Widera for the +suggestion to use |\path| when formatting DOIs and to Michael Giffin +for the suggestion to include PubMed URLs. + +\bibliography{urlbst} +\bibliographystyle{plainurl} + +\end{document} diff --git a/Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex.in b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex.in new file mode 100644 index 00000000000..a194ce8a6ce --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex.in @@ -0,0 +1,278 @@ +\documentclass[a4paper]{article} + +\title{The \texttt{urlbst} package} +\author{Norman Gray\\\texttt{<http://nxg.me.uk>}} +\date{Version @PACKAGE_VERSION@, @RELEASEDATE@} + +%\usepackage{times} +\usepackage{url} +\usepackage{hyperref} + +% Not long enough to make it useful to number sections +\setcounter{secnumdepth}{0} + +% Squeeze a bit more on to the page +%\addtolength\textwidth{1cm} +%\addtolength\oddsidemargin{-0.5cm} + +\makeatletter +% Easy verbatim mode +\catcode`\|=\active +\def|{\begingroup \let\do\@makeother \dospecials \verbatim@font \doverb} +\def\doverb#1|{#1\endgroup} + +\renewcommand{\verbatim@font}{\normalfont\small\ttfamily} +\makeatother + +\newcommand{\ub}{\package{urlbst}} +\newcommand{\BibTeX}{Bib\TeX} +\newcommand{\package}[1]{\texttt{#1}} +\newcommand{\btfield}[1]{\textsf{#1}} + +\begin{document} +\maketitle + +The \ub\ package consists of a Perl script which edits \BibTeX\ style +files (|.bst|) to add a \btfield{webpage} entry type, and which adds a +few new fields -- notably including \btfield{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 \package{custom-bib} +package~\cite{url:daly} -- that is intended to create a \BibTeX\ style +|.bst| file from scratch, and supports \btfield{url} and +\btfield{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 \btfield{webpage} entry type, plus the new fields. + +The added fields are: +\begin{itemize} +\item \btfield{url} and \btfield{lastchecked}, to associate a URL with + a reference, along with the date at which the URL was last checked + to exist; +\item \btfield{doi}, for a reference's DOI + (see \url{http://doi.org}); +\item \btfield{eprint}, for an arXiv eprint reference + (see \url{http://arxiv.org}); and +\item \btfield{pubmed} for a reference's PubMed identifier + (\textsc{PMID}, see \url{http://pubmed.gov}). +\end{itemize} + +Usage is simple: +\begin{verbatim} +% urlbst [--eprint] [--doi] [--pubmed] + [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref] + [input-file [output-file]] +\end{verbatim} +where the |input-file| is an existing |.bst| file, and +the |output-file| is the name of the new style file to be +created. If either file name is missing, the default is the +standard input or standard output respectively. +For example: +\begin{verbatim} +% urlbst --eprint bibstyle.bst +\end{verbatim} +would convert the style file \texttt{bibstyle.bst}, including support +for e-prints, and sending the result to the standard output (ie, the +screen, so it would more useful if you were to either redirect this to +a file or supply the output-file argument). + +If the option |--eprint| is present, then we switch on support for +\texttt{eprint} fields in the modified .bst file, with a citation +format matching that recommended in +\url{http://arxiv.org/help/faq/references}. If the option +|--doi| is present, we include support for a |doi| field, referring +to a Digital Object Identifier (DOI) as standardised by +\url{http://www.doi.org/}. And if |--pubmed| is present, we include +support for a |pubmed| field, referring to a PubMed identifier as +supported at \url{http://www.pubmed.gov}. + +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 Hyper\TeX\ (see +\url{http://arxiv.org/hypertex/#implementation}), supported by xdvi, +dvips and others, or using the support available from the +\package{hyperref} package. These options have no effect unless one +of the |--eprint|, |--doi|, |--pubmed| or |--inlinelinks| options is given: +when URLs are included +in the bibliography, they are written out using the |\url{...}| +command. The \package{hyperref} support is more generic, and more +generally supported, and so you should choose this unless you have a +particular need for the Hyper\TeX\ support. The |--nohyperlinks| +option, which is present by default, suppresses all hyperlinking. + +By default, any URL field is displayed as part of the bibliography +entry, linked to the corresponding URL via the mechanism managed by +the |--hypertex| and |--hyperref| options. If the |--inlinelinks| +option is present, however, then the URL is not displayed in the +printed entry, but instead a hyperlink is created, linked to suitable +text within the bibliography entry, such as the citation title. This +option does not affect the display of eprints, DOI or PubMed fields. It makes +no sense to specify |--inlinelinks| with |--nohyperlinks|, and the +script warns you if you do that, for example by failing to specify one +of the link-style options. This option is (primarily) useful if +you're preparing a version of a document which will be read on-screen; +the point of it is that the resulting bibliography is substantially +more compact than it would otherwise be. + +The support for all the above behaviours is always included in the +output file. The options instead control only whether the various +behaviours are enabled or disabled, and if you need to alter these, +you may do so by editing the generated |.bst| file and adjusting +values in the |{init.urlbst.variables}| function, where indicated. + +The generated references have URLs inside |\url{...}|. The best +way to format this this is with the \package{url} package +(see~\cite{texfaq} for pointers), but as a poor alternative, you can +try |\newcommand{\url}[1]{\texttt{#1}}|. The \package{hyperref} +package automatically processes |\url{...}| in the correct way to +include a hyperlink, and if you have selected \package{hyperref} +output, then nothing more need be done. If you selected Hyper\TeX\ +output, however, then the script encloses the |\url| command in an +appropriate Hyper\TeX\ special. + +When the style file generates a link for DOIs, it does so by +prepending the string \texttt{http://dx.doi.org/} to the DOI. This is +generally reasonable, but some DOIs have characters in them which are +illegal in URLs, with the result that the resulting +\texttt{dx.doi.org} URL doesn't work. The only real way of resolving +this is to write a URL-encoding function in the style-file +implementation language, but while that would doubtless be feasible in +principle, it would be hard and very, very, ugly. The only advice I +can offer in this case is to rely on the fact that the DOI will still +appear in the typeset bibliography, and that users who would want to +take advantage of the DOI will frequently (or usually?) know how to +resolve the DOI when then need to. As a workaround, you could include +a URL-encoded DOI URL in the \btfield{url} field of the entry (thanks +to Eric Chamberland for this suggestion). + +The \ub\ script works by spotting patterns and characteristic function +names in the input |.bst| file. It works as-is in the case of the +four standard \BibTeX\ style files |plain.bst|, |unsrt.bst|, +|alpha.bst| and |abbrv.bst|. It also works straightforwardly for +many other style files -- since many of these are derived from, or at +least closely inspired by, the standard ones -- but it does not +pretend that it can do so for all of them. In some cases, such as the +style files for the \package{refer} or \package{koma-script} packages, +the style files are not intended to be used for formatting; others are +sufficiently different from the standard files that a meaningful edit +becomes impossible. For the large remainder, however, the result of +this script should need only relatively minor edits before being +perfectly usable. + +\section{New \texttt{.bib} entry and field types} + +The new entry type \btfield{webpage} has required fields +\btfield{title} and \btfield{url}, and optional fields +\btfield{author}, \btfield{editor}, \btfield{note}, \btfield{year}, +\btfield{month} and \btfield{lastchecked}. The \btfield{url} and +\btfield{lastchecked} fields are new, and are +valid in other entry types as well: the first, obviously, is the URL +which is being cited, or which is being quoted as an auxiliary source +for an article perhaps; the second is the date when you last checked +that the URL was there, in the state you quoted it; this is necessary +since some people, heedless of the archival importance of preserving +the validity of URLs, indulge in the vicious practice of reorganising +web pages and destroying links. For the case of the \btfield{webpage} entry +type, the \btfield{editor} field should be used for the `maintainer' +of a web page. + +For example, in Figure~\ref{f:ex} we illustrate two potential |.bib| +file entries. The \texttt{@webpage} entry type is the new type +provided by this package, and provides reference information for a +webpage; it includes the new \texttt{url} and \texttt{lastchecked} +fields. There is also an example of the standard \texttt{@book} entry +type, which now includes the \texttt{url} and \texttt{lastchecked} +fields as well. The difference between the two references is that in +the \texttt{@book} case it is the book being cited, so that the +\texttt{url} provides extra information; in the \texttt{@webpage} case +it is the page itself which is of interest. You use the new |eprint|, +|doi| and |pubmed| fields similarly, if the bibliographic item in +question has an e-print, DOI or PubMed reference. +\begin{figure} +\begin{verbatim} +@Manual{w3chome, + url = {http://www.w3.org}, + title = {The World Wide Web Consortium}, + year = 2009, + lastchecked = {26 August 2009}} + +@Book{schutz, + author = {Bernard Schutz}, + title = {Gravity from the GroundUp}, + publisher = {Cambridge University Press}, + year = {2003}, + url = {http://www.gravityfromthegroundup.org/}, + lastchecked = {2008 June 16}} +\end{verbatim} +\caption{\label{f:ex}The new \texttt{@webpage} entry type, and the \texttt{url} + field in action} +\end{figure} + +How do you use this in a document? To use the the +\texttt{alphaurl.bst} style -- which is a pre-converted version of the +standard \texttt{alpha.bst} style, included in the \texttt{urlbst} +distribution -- you simply make sure that \texttt{alphaurl.bst} is in +your BibTeX search path (use the command \texttt{kpsepath bst} to find +this path and \texttt{kpsewhich alphaurl.bst} to confirm that BibTeX +can find it) and add |\bibliographystyle{alphaurl}| to your \LaTeX\ document. + +\section{Sources} + +There are various sources which suggest how to format references to +web pages. I have followed none specifically, but fortunately they do +not appear to materially disagree. + +ISO-690~\cite{url:iso690} is a formal standard for this stuff. Walker +and Taylor's \emph{Columbia Guide to Online Style}~\cite{walker06} +provides extensive coverage (but is only available on dead trees). +Emory University's +\emph{Citation Formats}~\cite{emory95} is a compendium of links rather +than a guide itself. The APA has a couple of style guides, a proposed +one~\cite{url:weapas} and a style included in the published APA style +guide~\cite{apastyle} (I'm not sure of the relationship between these +last two). + +\section{Hints} + +If you use Emacs' \BibTeX\ mode, you can insert the following in your +|.emacs| file to add knowledge of the new \btfield{webpage} entry: +\begin{verbatim} +(defun my-bibtex-hook () + (setq bibtex-mode-user-optional-fields '("location" "issn")) ; e.g. + (setq bibtex-entry-field-alist + (cons + '("Webpage" + ((("url" "The URL of the page") + ("title" "The title of the resource")) + (("author" "The author of the webpage") + ("editor" "The editor/maintainer of the webpage") + ("year" "Year of publication of the page") + ("month" "Month of publication of the page") + ("lastchecked" "Date when you last verified the page was there") + ("note" "Remarks to be put at the end of the entry")))) + bibtex-entry-field-alist))) +(add-hook 'bibtex-mode-hook 'my-bibtex-hook) +\end{verbatim} +After that, you can add a \btfield{webpage} entry by typing |C-c C-b webpage| +(or |M-x bibtex-entry|). + +It is a \emph{very} good idea to use the \package{url} package: it deals with +the problem of line-breaking long URLs, and with the problem that +\BibTeX{} creates, of occasionally inserting \%-signs into URLs in +generated bibliographies. + +See also the URL entry in the UK \TeX\ FAQ~\cite{texfaq}, and +references therein. + +\textbf{Acknowledgements:} Thanks to Jason Eisner for suggesting +the |--inlinelinks| option, to Pawe\l{} Widera for the +suggestion to use |\path| when formatting DOIs and to Michael Giffin +for the suggestion to include PubMed URLs. + +\bibliography{urlbst} +\bibliographystyle{plainurl} + +\end{document} |