From e5abb7960d35683e02c220371b77d39148079a77 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 9 Mar 2011 00:48:41 +0000 Subject: urlbst (8mar11) git-svn-id: svn://tug.org/texlive/trunk@21650 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/bibtex/urlbst/Makefile.in | 189 +++++ Master/texmf-dist/doc/bibtex/urlbst/README | 352 ++++++++++ Master/texmf-dist/doc/bibtex/urlbst/VERSION | 1 + Master/texmf-dist/doc/bibtex/urlbst/urlbst | 763 +++++++++++++++++++++ Master/texmf-dist/doc/bibtex/urlbst/urlbst.bib | 219 ++++++ Master/texmf-dist/doc/bibtex/urlbst/urlbst.html | 374 ++++++++++ Master/texmf-dist/doc/bibtex/urlbst/urlbst.html.in | 374 ++++++++++ Master/texmf-dist/doc/bibtex/urlbst/urlbst.in | 763 +++++++++++++++++++++ Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf | Bin 0 -> 184859 bytes Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex | 278 ++++++++ Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex.in | 278 ++++++++ Master/texmf-dist/doc/latex/urlbst/README | 283 -------- Master/texmf-dist/doc/latex/urlbst/VERSION | 1 - Master/texmf-dist/doc/latex/urlbst/urlbst | 698 ------------------- Master/texmf-dist/doc/latex/urlbst/urlbst.html | 347 ---------- Master/texmf-dist/doc/latex/urlbst/urlbst.html.in | 347 ---------- Master/texmf-dist/doc/latex/urlbst/urlbst.in | 698 ------------------- Master/texmf-dist/doc/latex/urlbst/urlbst.pdf | Bin 102644 -> 0 bytes Master/texmf-dist/doc/latex/urlbst/urlbst.tex | 255 ------- Master/texmf-dist/doc/latex/urlbst/urlbst.tex.in | 255 ------- 20 files changed, 3591 insertions(+), 2884 deletions(-) create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/Makefile.in create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/README create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/VERSION create mode 100755 Master/texmf-dist/doc/bibtex/urlbst/urlbst create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/urlbst.bib create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/urlbst.html create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/urlbst.html.in create mode 100755 Master/texmf-dist/doc/bibtex/urlbst/urlbst.in create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex create mode 100644 Master/texmf-dist/doc/bibtex/urlbst/urlbst.tex.in delete mode 100644 Master/texmf-dist/doc/latex/urlbst/README delete mode 100644 Master/texmf-dist/doc/latex/urlbst/VERSION delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst.html delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst.html.in delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst.in delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst.pdf delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst.tex delete mode 100644 Master/texmf-dist/doc/latex/urlbst/urlbst.tex.in (limited to 'Master/texmf-dist/doc') 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 <$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 '-' ? '' : $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 () { + /^ *%/ && 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 .= ; + } + $bracematchtotal = 0; # reset + bracematcher($line); + $line =~ /\{\s*(\w*)/; + $found{'entry'.$1} = 1; + print OUT $line; + $line = ; + until (bracematcher($line) == 0) { + # XXX deal with multiple entries on one line + ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); + print OUT $line; + $line = ; + } + 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 () { + 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 <; + } + $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: }{" * 'openinlinelink := + "\special {html:}" '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: }" * swap$ * + "\special {html:}" * +} +% 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 = ) && ($line !~ /{/)) { + print OUT $line; + } + while (defined ($line) && bracematcher($line) > 0) { + print OUT $line; + $line = ; + } + 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 @@ + + + + +Urlbst + + + + + +

Urlbst

+
+

A script to add a webpage BibTeX entry type, and add +support for general url and lastchecked +fields, to (most) BibTeX .bst files. Optionally adds +basic support for eprint, doi and pubmed fields, and +hypertex/hyperref support.

+ +

The Persistent URL for this page is +http://purl.org/nxg/dist/urlbst.

+ +

Version 0.6-5, 2011 March 8.

+
+ +

Contents

+ + +

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 urlbst can be used to add this support to an +arbitrary .bst file which has a reasonably `conventional' +structure. The result is meant to be robust rather than pretty.

+ +

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.

+ +

Usage

+
+urlbst [--eprint] [--doi] [--pubmed]
+           [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref]
+           [input-file [output-file]]
+
+

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:

+
    +
  • url and lastchecked, to associate a URL with + a reference, along with the date at which the URL was last checked + to exist;
  • +
  • doi, for a reference's DOI;
  • +
  • eprint, for an arXiv eprint reference; and
  • +
  • pubmed for a reference's + PubMed identifier (PMID).
  • +
+ +

If either of the --hypertex or --hyperref +options is present, then the generated .bst file includes +support for hyperlinks in the generated eprint entries in the +bibliography, with the format being either HyperTeX (see arXiv, again), +supported by xdvi, dvips and others, or using the support available +from the hyperref package. These options have no effect unless one of +the --eprint or --doi options is given: when +URLs are included in the bibliography, they are written out using the +\url{...} command, and hyperref automatically processes +that in the correct way to include a hyperlink.

+ +

The --inlinelinks option tells urlbst not to write out +the URL as text within the bibliography entry. Instead, urlbst will +produce a more conventional-looking and compact bibliography entry, +but the entry's title will now be a hyperlink to that URL. This +hyperlink may be useful to anyone who reads your document online +(this option can only be used with --hyperref or +--hypertex). Any DOI or eprint text which would be +produced as a result of the appropriate option will still appear in +this mode.

+ +

The distribution includes preconverted versions of the four +standard BibTeX .bst style files.

+ +

Only the style files which result from conversion of the standard +styles are checked in the regression tests. Other style files which +are known to work include

+
+acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, +geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, +siam.bst, mla.bst +
+ +

Style files which are known to fail:

+
    +
  • Currently (v0.5), there exists a style achicago.bst +which seems to fox urlbst; it turns out that there's a +simpler but almost equivalent style chicago.bst which +works.
  • + +
  • Some APA-like styles, including at least apager.bst, +seem to be sufficiently different from the most common styles, that +they confuse urlbst completely.
  • + +
  • The koma-script styles and the refer styles are +not designed to produce conventional .bbl files, and +urlbst does not aim to produce anything useful from these.
  • +
+

This might be a good time for me to revisit the rather +convoluted logic within the script, to make it a little more robust in +the face of variants like these, but don't hold your breath...

+ +

The natbib and revtex style files already have URL fields. If you have a +BibTeX style file which you think ought to work, but with which the +script fails, send it to me, and I'll try to work out what I've +missed (no promises, though).

+ +

Note that the command to invoke the script changed from `urlbst.pl' +to plain `urlbst' between versions 0.3 and 0.4.

+ +

For example...

+

To add URL support to the standard siam.bst file, you +can give the command

+
+% urlbst /path/to/original/siam.bst siamurl.bst
+
+

Your TeX installation will likely have some way of helping you find where +the original .bst files are. On teTeX-based systems, for +example, the command kpsewhich siam.bst returns the full +path of the siam.bst file which BibTeX would find.

+ +

The distributed files abbrvurl.bst, +alphaurl.bst, plainurl.bst and +unsrturl.bst are versions of the standard style files +which have been pre-converted.

+ +

There is more general discussion of including URLs in +bibliographies in the UK TeX +FAQ.

+ +

Download and installation

+ +

Download the file as a +tarball +or +zip file +and unpack it. Or you can clone the source repository at +bitbucket.org.

+ +

To install, you should simply copy the distributed +urlbst script to someplace on the path (such as +/usr/local/bin, or ~/local/bin, depending on +your privileges and tastes).

+ +

If you (might) want to use the pre-converted standard +.bst files, then you'll need to copy these to somewhere +in the BibTeX search path. Type kpsepath bst on Unix to +find out the list of places BibTeX searches, and pick either one of +the user-local locations, or a system-wide one. If you're installing +in a system-wide location, you'll need admin privileges, obviously, +and you will probably need to use texhash, +mktexlsr or its equivalent, to update LaTeX's filename +cache. For further hints here, see +the TeX FAQ entries on installing a package and where LaTeX puts files.

+ +

That should be all you have to do.

+ +

The urlbst script is distributed with a path which should just work, +as long as the Perl binary is in your path, but if you have problems +here, then you might want to change the first line to something like

+
+#! /usr/local/bin/perl
+
+

if that's where your Perl binary is.

+ +

You can also use the conventional ./configure; make; make +install to configure and install the package (as root, or using +sudo if you're installing it in a system location), +though you still have to install the .bst files by hand. +This is rather heavyweight for the trivial amount of configuration +required, so it's almost always simpler just to do things by hand.

+ +

If you need to change some of the urlbst defaults, +however, or if your fingers type ./configure +spontaneously, then you can be reassured that the configure script +supports the standard --prefix option, plus the following +options setting defaults:

+
+ +
--with-eprints=url, --without-eprints
+ +
This makes the --eprints option to urlbst available +by default, and allows you to optionally specify a prefix for creating +URLs from eprint numbers. The default for this URL is +http://arxiv.org/abs/ -- this is appropriate for arXiv, +obviously, but there are now a variety of other preprint archives +appearing, for which this might be inappropriate. If you have +comments on this default, or alternatives, please let me know. This +option is enabled by default; if you have some reason for disabling +the --eprints option for urlbst, the give the configure +option --without-eprints
+ +
--with-doi=url, --without-doi
+ +
This makes available the --doi option to urlbst and, +as with the --with-eprints option, allows you to +customise the DOI resolver URL. The --doi option to +urlbst is on by default.
+ +
--with-href=0/1/2
+ +
This allows you to specify the type of hyperlinks which are +inserted in the bibliography. Values 0, 1 and 2, indicating no +hyperlinks, hypertex-style links, and hyperref-style links, +respectively. The default is --with-href=0. The +hyperref-style option is intended to complement the +increasingly standard hyperref package.
+ +
+ +

The first two options simply change defaults, and if you never use +the new eprints or doi fields, then the +defaults don't matter to you.

+ +

Since the modified style generates URLs wrapped in the +\url{} macro, it is useful to use the resulting +bibliography style alongside the url package. Since this +tends to work with hyperref anyway, where possible, you +don't get any extra goodness by changing the --with-href +default at configuration time.

+ +

Documentation

+ +

Basic documentation is in the file urlbst.tex. This +is distributed as a PDF file, but if you want to regenerate it, use

+
+% latex urlbst
+% bibtex urlbst
+% latex urlbst
+% latex urlbst
+
+ +

Further Information and acknowledgements

+ +

urlbst is archived on CTAN at biblio/bibtex/contrib/urlbst/, and discussed in the +TeX +FAQ.

+ +

The source code for the package is maintained at +bitbucket.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.

+ +

Version history

+
+
0.6-5, 2011 March 8
+
Adjust support for inline links (should now work for arXiv, DOI and Pubmed)
+ +
0.6-4, 2009 April 28
+
Work around BibTeX linebreaking bug (thanks to Andras Salamon for the bug report).
+ +
0.6-3, 2009 April 19
+
Fix inline link generation (thanks to Eric Chamberland for the bug report).
+ +
0.6-2, 2008 November 17
+
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).
+ +
0.6-1, 2008 June 16
+
Fixed some broken links to the various citation standards +(I think in this context this should probably not be happening, yes?). +The distributed *url.bst no longer have the +--inlinelinks option turned on by default.
+ +
0.6, 2007 March 26
+

Added the option --inlinelinks, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (primarily) +useful if you're preparing a version of a document which will be read +on-screen. Thanks to Jason Eisner for the suggestion, and much testing.

+

Incorporate hyperref bugfixes from Paweł Widera.

+
+
0.6b3
+
Further reworkings of the inlinelinks support, so that it's now +fired by a format.title (or format.btitle) line, with a fallback in +fin.entry. This should be more robust, and allows me to delete some +of the previous version's gymnastics.
+ +
0.6b2
+
Reworked inlinelinks support; should now be more +robust. Incorporate hyperref bugfixes from Paweł Widera.
+ +
0.6b1
+
Added the option inlinelinks, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (only) +useful if you're preparing a version of a document which will be read +on-screen.
+
+
+ +
0.5.2, 2006 September 6
+
Another set of documentation-only changes, hopefully clarifying +installation.
+ +
0.5.1, 2006 January 10
+
No functionality changes. Documentation and webpage changes only, +hopefully clarifying usage and configuration
+ +
0.5, 2005 June 3
+
Added support for Digital Object Identifiers (DOI) fields in +bibliographies.
+ +
0.4-1, 2005 April 12
+
Documentation improvements -- there are now examples in the help text!
+ +
0.4, 2004 December 1
+
Bug fixes: now compatible with mla.bst and friends. +Now uses ./configure (optionally). Assorted reorganisation.
+ +
0.3, 2003 June 4
+
Added --eprint, --hypertex and --hyperref options.
+ +
0.2, 2002 October 23
+
The `editor' field is now supported in the webpage entry type. Basic +documentation added.
+ +
0.1, 2002 April
+
Initial version
+ +
+ + +
+Norman Gray
+2011 March 8 +
+ + + 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 @@ + + + + +Urlbst + + + + + +

Urlbst

+
+

A script to add a webpage BibTeX entry type, and add +support for general url and lastchecked +fields, to (most) BibTeX .bst files. Optionally adds +basic support for eprint, doi and pubmed fields, and +hypertex/hyperref support.

+ +

The Persistent URL for this page is +http://purl.org/nxg/dist/urlbst.

+ +

Version @PACKAGE_VERSION@, @RELEASEDATE@.

+
+ +

Contents

+ + +

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 urlbst can be used to add this support to an +arbitrary .bst file which has a reasonably `conventional' +structure. The result is meant to be robust rather than pretty.

+ +

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.

+ +

Usage

+
+urlbst [--eprint] [--doi] [--pubmed]
+           [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref]
+           [input-file [output-file]]
+
+

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:

+
    +
  • url and lastchecked, to associate a URL with + a reference, along with the date at which the URL was last checked + to exist;
  • +
  • doi, for a reference's DOI;
  • +
  • eprint, for an arXiv eprint reference; and
  • +
  • pubmed for a reference's + PubMed identifier (PMID).
  • +
+ +

If either of the --hypertex or --hyperref +options is present, then the generated .bst file includes +support for hyperlinks in the generated eprint entries in the +bibliography, with the format being either HyperTeX (see arXiv, again), +supported by xdvi, dvips and others, or using the support available +from the hyperref package. These options have no effect unless one of +the --eprint or --doi options is given: when +URLs are included in the bibliography, they are written out using the +\url{...} command, and hyperref automatically processes +that in the correct way to include a hyperlink.

+ +

The --inlinelinks option tells urlbst not to write out +the URL as text within the bibliography entry. Instead, urlbst will +produce a more conventional-looking and compact bibliography entry, +but the entry's title will now be a hyperlink to that URL. This +hyperlink may be useful to anyone who reads your document online +(this option can only be used with --hyperref or +--hypertex). Any DOI or eprint text which would be +produced as a result of the appropriate option will still appear in +this mode.

+ +

The distribution includes preconverted versions of the four +standard BibTeX .bst style files.

+ +

Only the style files which result from conversion of the standard +styles are checked in the regression tests. Other style files which +are known to work include

+
+acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, +geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, +siam.bst, mla.bst +
+ +

Style files which are known to fail:

+
    +
  • Currently (v0.5), there exists a style achicago.bst +which seems to fox urlbst; it turns out that there's a +simpler but almost equivalent style chicago.bst which +works.
  • + +
  • Some APA-like styles, including at least apager.bst, +seem to be sufficiently different from the most common styles, that +they confuse urlbst completely.
  • + +
  • The koma-script styles and the refer styles are +not designed to produce conventional .bbl files, and +urlbst does not aim to produce anything useful from these.
  • +
+

This might be a good time for me to revisit the rather +convoluted logic within the script, to make it a little more robust in +the face of variants like these, but don't hold your breath...

+ +

The natbib and revtex style files already have URL fields. If you have a +BibTeX style file which you think ought to work, but with which the +script fails, send it to me, and I'll try to work out what I've +missed (no promises, though).

+ +

Note that the command to invoke the script changed from `urlbst.pl' +to plain `urlbst' between versions 0.3 and 0.4.

+ +

For example...

+

To add URL support to the standard siam.bst file, you +can give the command

+
+% urlbst /path/to/original/siam.bst siamurl.bst
+
+

Your TeX installation will likely have some way of helping you find where +the original .bst files are. On teTeX-based systems, for +example, the command kpsewhich siam.bst returns the full +path of the siam.bst file which BibTeX would find.

+ +

The distributed files abbrvurl.bst, +alphaurl.bst, plainurl.bst and +unsrturl.bst are versions of the standard style files +which have been pre-converted.

+ +

There is more general discussion of including URLs in +bibliographies in the UK TeX +FAQ.

+ +

Download and installation

+ +

Download the file as a +tarball +or +zip file +and unpack it. Or you can clone the source repository at +bitbucket.org.

+ +

To install, you should simply copy the distributed +urlbst script to someplace on the path (such as +/usr/local/bin, or ~/local/bin, depending on +your privileges and tastes).

+ +

If you (might) want to use the pre-converted standard +.bst files, then you'll need to copy these to somewhere +in the BibTeX search path. Type kpsepath bst on Unix to +find out the list of places BibTeX searches, and pick either one of +the user-local locations, or a system-wide one. If you're installing +in a system-wide location, you'll need admin privileges, obviously, +and you will probably need to use texhash, +mktexlsr or its equivalent, to update LaTeX's filename +cache. For further hints here, see +the TeX FAQ entries on installing a package and where LaTeX puts files.

+ +

That should be all you have to do.

+ +

The urlbst script is distributed with a path which should just work, +as long as the Perl binary is in your path, but if you have problems +here, then you might want to change the first line to something like

+
+#! /usr/local/bin/perl
+
+

if that's where your Perl binary is.

+ +

You can also use the conventional ./configure; make; make +install to configure and install the package (as root, or using +sudo if you're installing it in a system location), +though you still have to install the .bst files by hand. +This is rather heavyweight for the trivial amount of configuration +required, so it's almost always simpler just to do things by hand.

+ +

If you need to change some of the urlbst defaults, +however, or if your fingers type ./configure +spontaneously, then you can be reassured that the configure script +supports the standard --prefix option, plus the following +options setting defaults:

+
+ +
--with-eprints=url, --without-eprints
+ +
This makes the --eprints option to urlbst available +by default, and allows you to optionally specify a prefix for creating +URLs from eprint numbers. The default for this URL is +http://arxiv.org/abs/ -- this is appropriate for arXiv, +obviously, but there are now a variety of other preprint archives +appearing, for which this might be inappropriate. If you have +comments on this default, or alternatives, please let me know. This +option is enabled by default; if you have some reason for disabling +the --eprints option for urlbst, the give the configure +option --without-eprints
+ +
--with-doi=url, --without-doi
+ +
This makes available the --doi option to urlbst and, +as with the --with-eprints option, allows you to +customise the DOI resolver URL. The --doi option to +urlbst is on by default.
+ +
--with-href=0/1/2
+ +
This allows you to specify the type of hyperlinks which are +inserted in the bibliography. Values 0, 1 and 2, indicating no +hyperlinks, hypertex-style links, and hyperref-style links, +respectively. The default is --with-href=0. The +hyperref-style option is intended to complement the +increasingly standard hyperref package.
+ +
+ +

The first two options simply change defaults, and if you never use +the new eprints or doi fields, then the +defaults don't matter to you.

+ +

Since the modified style generates URLs wrapped in the +\url{} macro, it is useful to use the resulting +bibliography style alongside the url package. Since this +tends to work with hyperref anyway, where possible, you +don't get any extra goodness by changing the --with-href +default at configuration time.

+ +

Documentation

+ +

Basic documentation is in the file urlbst.tex. This +is distributed as a PDF file, but if you want to regenerate it, use

+
+% latex urlbst
+% bibtex urlbst
+% latex urlbst
+% latex urlbst
+
+ +

Further Information and acknowledgements

+ +

urlbst is archived on CTAN at biblio/bibtex/contrib/urlbst/, and discussed in the +TeX +FAQ.

+ +

The source code for the package is maintained at +bitbucket.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.

+ +

Version history

+
+
0.6-5, 2011 March 8
+
Adjust support for inline links (should now work for arXiv, DOI and Pubmed)
+ +
0.6-4, 2009 April 28
+
Work around BibTeX linebreaking bug (thanks to Andras Salamon for the bug report).
+ +
0.6-3, 2009 April 19
+
Fix inline link generation (thanks to Eric Chamberland for the bug report).
+ +
0.6-2, 2008 November 17
+
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).
+ +
0.6-1, 2008 June 16
+
Fixed some broken links to the various citation standards +(I think in this context this should probably not be happening, yes?). +The distributed *url.bst no longer have the +--inlinelinks option turned on by default.
+ +
0.6, 2007 March 26
+

Added the option --inlinelinks, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (primarily) +useful if you're preparing a version of a document which will be read +on-screen. Thanks to Jason Eisner for the suggestion, and much testing.

+

Incorporate hyperref bugfixes from Paweł Widera.

+
+
0.6b3
+
Further reworkings of the inlinelinks support, so that it's now +fired by a format.title (or format.btitle) line, with a fallback in +fin.entry. This should be more robust, and allows me to delete some +of the previous version's gymnastics.
+ +
0.6b2
+
Reworked inlinelinks support; should now be more +robust. Incorporate hyperref bugfixes from Paweł Widera.
+ +
0.6b1
+
Added the option inlinelinks, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (only) +useful if you're preparing a version of a document which will be read +on-screen.
+
+
+ +
0.5.2, 2006 September 6
+
Another set of documentation-only changes, hopefully clarifying +installation.
+ +
0.5.1, 2006 January 10
+
No functionality changes. Documentation and webpage changes only, +hopefully clarifying usage and configuration
+ +
0.5, 2005 June 3
+
Added support for Digital Object Identifiers (DOI) fields in +bibliographies.
+ +
0.4-1, 2005 April 12
+
Documentation improvements -- there are now examples in the help text!
+ +
0.4, 2004 December 1
+
Bug fixes: now compatible with mla.bst and friends. +Now uses ./configure (optionally). Assorted reorganisation.
+ +
0.3, 2003 June 4
+
Added --eprint, --hypertex and --hyperref options.
+ +
0.2, 2002 October 23
+
The `editor' field is now supported in the webpage entry type. Basic +documentation added.
+ +
0.1, 2002 April
+
Initial version
+ +
+ + +
+Norman Gray
+@RELEASEDATE@ +
+ + + 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 <$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 '-' ? '' : $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 () { + /^ *%/ && 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 .= ; + } + $bracematchtotal = 0; # reset + bracematcher($line); + $line =~ /\{\s*(\w*)/; + $found{'entry'.$1} = 1; + print OUT $line; + $line = ; + until (bracematcher($line) == 0) { + # XXX deal with multiple entries on one line + ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); + print OUT $line; + $line = ; + } + 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 () { + 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 <; + } + $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: }{" * 'openinlinelink := + "\special {html:}" '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: }" * swap$ * + "\special {html:}" * +} +% 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 = ) && ($line !~ /{/)) { + print OUT $line; + } + while (defined ($line) && bracematcher($line) > 0) { + print OUT $line; + $line = ; + } + 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 new file mode 100644 index 00000000000..51da2dfe7be Binary files /dev/null and b/Master/texmf-dist/doc/bibtex/urlbst/urlbst.pdf differ 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{}} +\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{}} +\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} diff --git a/Master/texmf-dist/doc/latex/urlbst/README b/Master/texmf-dist/doc/latex/urlbst/README deleted file mode 100644 index 7e30209d774..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/README +++ /dev/null @@ -1,283 +0,0 @@ - Urlbst - - A script to add a webpage BibTeX entry type, and add support for - general url and lastchecked fields, to (most) BibTeX .bst files. - Optionally adds basic support for eprint and doi fields, and - hypertex/hyperref support, too. - - The Persistent URL for this page is http://purl.org/nxg/dist/urlbst. - - Version 0.6-1, 2008 June 16. - - 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 urlbst can be used to add this support to an arbitrary - .bst file which has a reasonably `conventional' structure. The result - is meant to be robust rather than pretty. - - 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. - -Usage - -urlbst [--eprint] [--doi] - [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] - [input-file [output-file]] - - if either the input-file or the output-file is omitted, they default to - stdin and stdout respectively. If the input file already has a URL - entry type, then the script objects. - - If the option --eprint is present, then include support for a eprint - field in the modified .bst file, with a citation format matching that - recommended in the arXiv documentation. Similarly, if the option --doi - is present, then include support for a doi field, referring to a DOI - for the bibliographic item. - - If either of the --hypertex or --hyperref options is present, then the - generated .bst file includes support for hyperlinks in the generated - eprint entries in the bibliography, with the format being either - HyperTeX (see arXiv, again), supported by xdvi, dvips and others, or - using the support available from the hyperref package. These options - have no effect unless one of the --eprint or --doi options is given: - when URLs are included in the bibliography, they are written out using - the \url{...} command, and hyperref automatically processes that in the - correct way to include a hyperlink. - - The --inlinelinks option tells urlbst not to write out the URL as text - within the bibliography entry. Instead, urlbst will produce a more - conventional-looking and compact bibliography entry, but the entry's - title will now be a hyperlink to that URL. This hyperlink may be useful - to anyone who reads your document online (this option can only be used - with --hyperref or --hypertex). Any DOI or eprint text which would be - produced as a result of the appropriate option will still appear in - this mode. - - The distribution includes preconverted versions of the four standard - BibTeX .bst style files. - - Only the style files which result from conversion of the standard - styles are checked in the regression tests. Other style files which are - known to work include - - acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, - geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, - siam.bst, mla.bst - - Style files which are known to fail: - * Currently (v0.5), there exists a style achicago.bst which seems to - fox urlbst; it turns out that there's a simpler but almost - equivalent style chicago.bst which works. - * Some APA-like styles, including at least apager.bst, seem to be - sufficiently different from the most common styles, that they - confuse urlbst completely. - * The koma-script styles and the refer styles are not designed to - produce conventional .bbl files, and urlbst does not aim to produce - anything useful from these. - - This might be a good time for me to revisit the rather convoluted logic - within the script, to make it a little more robust in the face of - variants like these, but don't hold your breath... - - The natbib and revtex style files already have URL fields. If you have - a BibTeX style file which you think ought to work, but with which the - script fails, send it to me, and I'll try to work out what I've missed - (no promises, though). - - Note that the command to invoke the script changed from `urlbst.pl' to - plain `urlbst' between versions 0.3 and 0.4. - -For example... - - To add URL support to the standard siam.bst file, you can give the - command -% urlbst /path/to/original/siam.bst siamurl.bst - - Your TeX installation will likely have some way of helping you find - where the original .bst files are. On teTeX-based systems, for example, - the command kpsewhich siam.bst returns the full path of the siam.bst - file which BibTeX would find. - - The distributed files abbrvurl.bst, alphaurl.bst, plainurl.bst and - unsrturl.bst are versions of the standard style files which have been - pre-converted. - - There is more general discussion of including URLs in bibliographies in - the UK TeX FAQ. - -Download and installation - - Download the file urlbst-0.6-1.tar.gz and unpack it. - - To install, you should simply copy the distributed urlbst script to - someplace on the path (such as /usr/local/bin, or ~/local/bin, - depending on your privileges and tastes). - - If you (might) want to use the pre-converted standard .bst files, then - you'll need to copy these to somewhere in the BibTeX search path. Type - kpsepath bst on Unix to find out the list of places BibTeX searches, - and pick either one of the user-local locations, or a system-wide one. - If you're installing in a system-wide location, you'll need admin - privileges, obviously, and you will probably need to use texhash, - mktexlsr or its equivalent, to update LaTeX's filename cache. For - further hints here, see the TeX FAQ entries on installing a package and - where LaTeX puts files. - - That should be all you have to do. - - The urlbst script is distributed with a path which should just work, as - long as the Perl binary is in your path, but if you have problems here, - then you might want to change the first line to something like -#! /usr/local/bin/perl - - if that's where your Perl binary is. - - You can also use the conventional ./configure; make; make install to - configure and install the package (as root, or using sudo if you're - installing it in a system location), though you still have to install - the .bst files by hand. This is rather heavyweight for the trivial - amount of configuration required, so it's almost always simpler just to - do things by hand. - - If you need to change some of the urlbst defaults, however, or if your - fingers type ./configure spontaneously, then you can be reassured that - the configure script supports the standard --prefix option, plus the - following options setting defaults: - - --with-eprints=url, --without-eprints - This makes the --eprints option to urlbst available by default, - and allows you to optionally specify a prefix for creating URLs - from eprint numbers. The default for this URL is - http://arxiv.org/abs/ -- this is appropriate for arXiv, - obviously, but there are now a variety of other preprint - archives appearing, for which this might be inappropriate. If - you have comments on this default, or alternatives, please let - me know. This option is enabled by default; if you have some - reason for disabling the --eprints option for urlbst, the give - the configure option --without-eprints - - --with-doi=url, --without-doi - This makes available the --doi option to urlbst and, as with the - --with-eprints option, allows you to customise the DOI resolver - URL. The --doi option to urlbst is on by default. - - --with-href=0/1/2 - This allows you to specify the type of hyperlinks which are - inserted in the bibliography. Values 0, 1 and 2, indicating no - hyperlinks, hypertex-style links, and hyperref-style links, - respectively. The default is --with-href=0. The hyperref-style - option is intended to complement the increasingly standard - hyperref package. - - The first two options simply change defaults, and if you never use the - new eprints or doi fields, then the defaults don't matter to you. - - Since the modified style generates URLs wrapped in the \url{} macro, it - is useful to use the resulting bibliography style alongside the url - package. Since this tends to work with hyperref anyway, where possible, - you don't get any extra goodness by changing the --with-href default at - configuration time. - - Documentation - - Basic documentation is in the file urlbst.tex. This is distributed as a - PDF file, but if you want to regenerate it, use -% latex urlbst -% bibtex urlbst -% latex urlbst -% latex urlbst - -Further Information - - urlbst is archived on CTAN at biblio/bibtex/contrib/urlbst/, and - discussed in the TeX FAQ. - - The home page of urlbst might possibly have more recent versions than - the one you're looking at now. - - Copyright 2002-8, Norman Gray. Released under the terms of the GNU - General Public Licence. - -Version history - - 0.6-1, 2008 June 16 - Fixed some broken links to the various citation standards (I - think in this context this should probably not be happening, - yes?). The distributed *url.bst no longer have the --inlinelinks - option turned on by default. - - 0.6, 2007 March 26 - Added the option --inlinelinks, which adds inline hyperlinks to - any bibliography entries which have URLs, but does so inline, - rather than printing the URL explicitly in the bibliography. - This is (primarily) useful if you're preparing a version of a - document which will be read on-screen. Thanks to Jason Eisner - for the suggestion, and much testing. - - Incorporate hyperref bugfixes from Pawel/ Widera. - - 0.6b3 - Further reworkings of the inlinelinks support, so that - it's now fired by a format.title (or format.btitle) line, - with a fallback in fin.entry. This should be more robust, - and allows me to delete some of the previous version's - gymnastics. - - 0.6b2 - Reworked inlinelinks support; should now be more robust. - Incorporate hyperref bugfixes from Pawel/ Widera. - - 0.6b1 - Added the option inlinelinks, which adds inline hyperlinks - to any bibliography entries which have URLs, but does so - inline, rather than printing the URL explicitly in the - bibliography. This is (only) useful if you're preparing a - version of a document which will be read on-screen. - - 0.5.2, 2006 September 6 - Another set of documentation-only changes, hopefully clarifying - installation. - - 0.5.1, 2006 January 10 - No functionality changes. Documentation and webpage changes - only, hopefully clarifying usage and configuration - - 0.5, 2005 June 3 - Added support for Digital Object Identifiers (DOI) fields in - bibliographies. - - 0.4-1, 2005 April 12 - Documentation improvements -- there are now examples in the help - text! - - 0.4, 2004 December 1 - Bug fixes: now compatible with mla.bst and friends. Now uses - ./configure (optionally). Assorted reorganisation. - - 0.3, 2003 June 4 - Added --eprint, --hypertex and --hyperref options. - - 0.2, 2002 October 23 - The `editor' field is now supported in the webpage entry type. - Basic documentation added. - - 0.1, 2002 April - Initial version - - Norman Gray - 2008 June 16 diff --git a/Master/texmf-dist/doc/latex/urlbst/VERSION b/Master/texmf-dist/doc/latex/urlbst/VERSION deleted file mode 100644 index 6a4461b90b2..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/VERSION +++ /dev/null @@ -1 +0,0 @@ -urlbst-0.6-1 diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst b/Master/texmf-dist/doc/latex/urlbst/urlbst deleted file mode 100644 index 18501bd58b3..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/urlbst +++ /dev/null @@ -1,698 +0,0 @@ -#! /usr/bin/env perl -# -# 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: urlbst.in,v 1.10 2008/01/27 23:18:54 norman Exp $ - -$version = '0.6-1'; -($progname = $0) =~ s/.*\///; -$mymarker = "% $progname"; -$mymarkerend = "% ...$progname to here"; -$myurl = 'http://purl.org/nxg/dist/urlbst'; - - -$infile = '-'; -$outfile = '-'; - -$addeprints = 0; # if true (nonzero) we add support for eprints -$eprintprefix = 'arXiv:'; # make these settable with --eprint? syntax? -$eprinturl = 'http://arxiv.org/abs/'; - -$adddoiresolver = 0; -$doiprefix = 'doi:'; -$doiurl = 'http://dx.doi.org/'; - -$addpubmedresolver = 0; -$pubmedprefix = 'PMID:'; -$pubmedurl = 'http://www.ncbi.nlm.nih.gov/pubmed/'; - -$makehref = 0; -$availablestring = "Available from: "; -$inlinelinks = 0; - -$Usage = "$progname [--eprint] [--doi] [--pubmed]\n [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref]\n [--help] [input-file [output-file]]"; - -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 '--help') { - print <$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 '-' ? '' : $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 () { - /^ *%/ && 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 .= ; - } - $bracematchtotal = 0; # reset - bracematcher($line); - $line =~ /\{\s*(\w*)/; - $found{'entry'.$1} = 1; - print OUT $line; - $line = ; - until (bracematcher($line) == 0) { - # XXX deal with multiple entries on one line - ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); - print OUT $line; - $line = ; - } - 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 () { - 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 <; - } - $line =~ s/(\{.*?\}.*?\{)/$1 #0 'outside.brackets := $mymarker - #1 'open.brackets := - #2 'within.brackets := - #3 'close.brackets := - - /s; - print OUT $line; - $found{initconsts} = 1; - next; - }; - - /^ *EXECUTE *\{init\.state\.consts\}/ && do { - print OUT "EXECUTE {init.urlbst.variables}\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/; - $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 setup.inlinelink - print OUT " title empty\$ 'skip\$ 'setup\.inlinelink if\$ $mymarker\n"; - 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\}/; - $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. -FUNCTION {setup.inlinelink} -{ makeinlinelink - { hrefform #1 = % hypertex - { "\special {html: }{" * 'openinlinelink := - "\special {html:}" 'closeinlinelink := - } - { hrefform #2 = % hyperref - { "\href{" url * "}{" * 'openinlinelink := - "}" 'closeinlinelink := - } - 'skip$ - if$ % hrefform #2 = - } - if$ % hrefform #1 = - #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: }" * swap$ * - "\special {html:}" * -} -% 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 - 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$ -} - -% 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 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 - { 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$ '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 = ) && ($line !~ /{/)) { - print OUT $line; - } - while (defined ($line) && bracematcher($line) > 0) { - print OUT $line; - $line = ; - } - print OUT "$line\n"; # print out terminating \} (assumed - # alone on the line) -} diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.html b/Master/texmf-dist/doc/latex/urlbst/urlbst.html deleted file mode 100644 index eac33dfa948..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/urlbst.html +++ /dev/null @@ -1,347 +0,0 @@ - - - - -Urlbst - - - - - -

Urlbst

-
-

A script to add a webpage BibTeX entry type, and add -support for general url and lastchecked -fields, to (most) BibTeX .bst files. Optionally adds -basic support for eprint and doi fields, and -hypertex/hyperref support, too.

- -

The Persistent URL for this page is -http://purl.org/nxg/dist/urlbst.

- -

Version 0.6-1, 2008 June 16.

-
- -

Contents

- - -

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 urlbst can be used to add this support to an -arbitrary .bst file which has a reasonably `conventional' -structure. The result is meant to be robust rather than pretty.

- -

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.

- -

Usage

-
-urlbst [--eprint] [--doi]
-           [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref]
-           [input-file [output-file]]
-
-

if either the input-file or the output-file is omitted, they default -to stdin and stdout respectively. If the input file already has a URL -entry type, then the script objects.

- -

If the option --eprint is present, then include -support for a eprint field in the modified -.bst file, with a citation format matching that -recommended in the -arXiv documentation. Similarly, if the option --doi -is present, then include support for a doi field, -referring to a DOI for the -bibliographic item.

- -

If either of the --hypertex or --hyperref -options is present, then the generated .bst file includes -support for hyperlinks in the generated eprint entries in the -bibliography, with the format being either HyperTeX (see arXiv, again), -supported by xdvi, dvips and others, or using the support available -from the hyperref package. These options have no effect unless one of -the --eprint or --doi options is given: when -URLs are included in the bibliography, they are written out using the -\url{...} command, and hyperref automatically processes -that in the correct way to include a hyperlink.

- -

The --inlinelinks option tells urlbst not to write out -the URL as text within the bibliography entry. Instead, urlbst will -produce a more conventional-looking and compact bibliography entry, -but the entry's title will now be a hyperlink to that URL. This -hyperlink may be useful to anyone who reads your document online -(this option can only be used with --hyperref or ---hypertex). Any DOI or eprint text which would be -produced as a result of the appropriate option will still appear in -this mode.

- -

The distribution includes preconverted versions of the four -standard BibTeX .bst style files.

- -

Only the style files which result from conversion of the standard -styles are checked in the regression tests. Other style files which -are known to work include

-
-acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, -geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, -siam.bst, mla.bst -
- -

Style files which are known to fail:

-
    -
  • Currently (v0.5), there exists a style achicago.bst -which seems to fox urlbst; it turns out that there's a -simpler but almost equivalent style chicago.bst which -works.
  • - -
  • Some APA-like styles, including at least apager.bst, -seem to be sufficiently different from the most common styles, that -they confuse urlbst completely.
  • - -
  • The koma-script styles and the refer styles are -not designed to produce conventional .bbl files, and -urlbst does not aim to produce anything useful from these.
  • -
-

This might be a good time for me to revisit the rather -convoluted logic within the script, to make it a little more robust in -the face of variants like these, but don't hold your breath...

- -

The natbib and revtex style files already have URL fields. If you have a -BibTeX style file which you think ought to work, but with which the -script fails, send it to me, and I'll try to work out what I've -missed (no promises, though).

- -

Note that the command to invoke the script changed from `urlbst.pl' -to plain `urlbst' between versions 0.3 and 0.4.

- -

For example...

-

To add URL support to the standard siam.bst file, you -can give the command

-
-% urlbst /path/to/original/siam.bst siamurl.bst
-
-

Your TeX installation will likely have some way of helping you find where -the original .bst files are. On teTeX-based systems, for -example, the command kpsewhich siam.bst returns the full -path of the siam.bst file which BibTeX would find.

- -

The distributed files abbrvurl.bst, -alphaurl.bst, plainurl.bst and -unsrturl.bst are versions of the standard style files -which have been pre-converted.

- -

There is more general discussion of including URLs in -bibliographies in the UK TeX -FAQ.

- -

Download and installation

- -

Download the file -urlbst-0.6-1.tar.gz -and unpack it.

- -

To install, you should simply copy the distributed -urlbst script to someplace on the path (such as -/usr/local/bin, or ~/local/bin, depending on -your privileges and tastes).

- -

If you (might) want to use the pre-converted standard -.bst files, then you'll need to copy these to somewhere -in the BibTeX search path. Type kpsepath bst on Unix to -find out the list of places BibTeX searches, and pick either one of -the user-local locations, or a system-wide one. If you're installing -in a system-wide location, you'll need admin privileges, obviously, -and you will probably need to use texhash, -mktexlsr or its equivalent, to update LaTeX's filename -cache. For further hints here, see -the TeX FAQ entries on installing a package and where LaTeX puts files.

- -

That should be all you have to do.

- -

The urlbst script is distributed with a path which should just work, -as long as the Perl binary is in your path, but if you have problems -here, then you might want to change the first line to something like

-
-#! /usr/local/bin/perl
-
-

if that's where your Perl binary is.

- -

You can also use the conventional ./configure; make; make -install to configure and install the package (as root, or using -sudo if you're installing it in a system location), -though you still have to install the .bst files by hand. -This is rather heavyweight for the trivial amount of configuration -required, so it's almost always simpler just to do things by hand.

- -

If you need to change some of the urlbst defaults, -however, or if your fingers type ./configure -spontaneously, then you can be reassured that the configure script -supports the standard --prefix option, plus the following -options setting defaults:

-
- -
--with-eprints=url, --without-eprints
- -
This makes the --eprints option to urlbst available -by default, and allows you to optionally specify a prefix for creating -URLs from eprint numbers. The default for this URL is -http://arxiv.org/abs/ -- this is appropriate for arXiv, -obviously, but there are now a variety of other preprint archives -appearing, for which this might be inappropriate. If you have -comments on this default, or alternatives, please let me know. This -option is enabled by default; if you have some reason for disabling -the --eprints option for urlbst, the give the configure -option --without-eprints
- -
--with-doi=url, --without-doi
- -
This makes available the --doi option to urlbst and, -as with the --with-eprints option, allows you to -customise the DOI resolver URL. The --doi option to -urlbst is on by default.
- -
--with-href=0/1/2
- -
This allows you to specify the type of hyperlinks which are -inserted in the bibliography. Values 0, 1 and 2, indicating no -hyperlinks, hypertex-style links, and hyperref-style links, -respectively. The default is --with-href=0. The -hyperref-style option is intended to complement the -increasingly standard hyperref package.
- -
- -

The first two options simply change defaults, and if you never use -the new eprints or doi fields, then the -defaults don't matter to you.

- -

Since the modified style generates URLs wrapped in the -\url{} macro, it is useful to use the resulting -bibliography style alongside the url package. Since this -tends to work with hyperref anyway, where possible, you -don't get any extra goodness by changing the --with-href -default at configuration time.

- -

Documentation

- -

Basic documentation is in the file urlbst.tex. This -is distributed as a PDF file, but if you want to regenerate it, use

-
-% latex urlbst
-% bibtex urlbst
-% latex urlbst
-% latex urlbst
-
- -

Further Information

- -

urlbst is archived on CTAN at biblio/bibtex/contrib/urlbst/, and discussed in the -TeX -FAQ.

- -

The home page of urlbst might possibly have more recent versions than the -one you're looking at now.

- -

Copyright 2002-8, Norman Gray. Released under the terms of the GNU -General Public Licence.

- -

Version history

-
- -
0.6-1, 2008 June 16
-
Fixed some broken links to the various citation standards (I think -in this context this should probably not be happening, -yes?). The distributed *url.bst no longer have the ---inlinelinks option turned on by default.
- -
0.6, 2007 March 26
-

Added the option --inlinelinks, which adds inline hyperlinks -to any bibliography entries which have URLs, but does so inline, rather -than printing the URL explicitly in the bibliography. This is (primarily) -useful if you're preparing a version of a document which will be read -on-screen. Thanks to Jason Eisner for the suggestion, and much testing.

-

Incorporate hyperref bugfixes from Paweł Widera.

-
-
0.6b3
-
Further reworkings of the inlinelinks support, so that it's now -fired by a format.title (or format.btitle) line, with a fallback in -fin.entry. This should be more robust, and allows me to delete some -of the previous version's gymnastics.
- -
0.6b2
-
Reworked inlinelinks support; should now be more -robust. Incorporate hyperref bugfixes from Paweł Widera.
- -
0.6b1
-
Added the option inlinelinks, which adds inline hyperlinks -to any bibliography entries which have URLs, but does so inline, rather -than printing the URL explicitly in the bibliography. This is (only) -useful if you're preparing a version of a document which will be read -on-screen.
-
-
- -
0.5.2, 2006 September 6
-
Another set of documentation-only changes, hopefully clarifying -installation.
- -
0.5.1, 2006 January 10
-
No functionality changes. Documentation and webpage changes only, -hopefully clarifying usage and configuration
- -
0.5, 2005 June 3
-
Added support for Digital Object Identifiers (DOI) fields in -bibliographies.
- -
0.4-1, 2005 April 12
-
Documentation improvements -- there are now examples in the help text!
- -
0.4, 2004 December 1
-
Bug fixes: now compatible with mla.bst and friends. Now uses -./configure (optionally). Assorted reorganisation.
- -
0.3, 2003 June 4
-
Added --eprint, --hypertex and --hyperref options.
- -
0.2, 2002 October 23
-
The `editor' field is now supported in the webpage entry type. Basic -documentation added.
- -
0.1, 2002 April
-
Initial version
- -
- - -
-Norman Gray
-2008 June 16 -
- - - diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.html.in b/Master/texmf-dist/doc/latex/urlbst/urlbst.html.in deleted file mode 100644 index 6facc246252..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/urlbst.html.in +++ /dev/null @@ -1,347 +0,0 @@ - - - - -Urlbst - - - - - -

Urlbst

-
-

A script to add a webpage BibTeX entry type, and add -support for general url and lastchecked -fields, to (most) BibTeX .bst files. Optionally adds -basic support for eprint and doi fields, and -hypertex/hyperref support, too.

- -

The Persistent URL for this page is -http://purl.org/nxg/dist/urlbst.

- -

Version @PACKAGE_VERSION@, @RELEASEDATE@.

-
- -

Contents

- - -

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 urlbst can be used to add this support to an -arbitrary .bst file which has a reasonably `conventional' -structure. The result is meant to be robust rather than pretty.

- -

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.

- -

Usage

-
-urlbst [--eprint] [--doi]
-           [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref]
-           [input-file [output-file]]
-
-

if either the input-file or the output-file is omitted, they default -to stdin and stdout respectively. If the input file already has a URL -entry type, then the script objects.

- -

If the option --eprint is present, then include -support for a eprint field in the modified -.bst file, with a citation format matching that -recommended in the -arXiv documentation. Similarly, if the option --doi -is present, then include support for a doi field, -referring to a DOI for the -bibliographic item.

- -

If either of the --hypertex or --hyperref -options is present, then the generated .bst file includes -support for hyperlinks in the generated eprint entries in the -bibliography, with the format being either HyperTeX (see arXiv, again), -supported by xdvi, dvips and others, or using the support available -from the hyperref package. These options have no effect unless one of -the --eprint or --doi options is given: when -URLs are included in the bibliography, they are written out using the -\url{...} command, and hyperref automatically processes -that in the correct way to include a hyperlink.

- -

The --inlinelinks option tells urlbst not to write out -the URL as text within the bibliography entry. Instead, urlbst will -produce a more conventional-looking and compact bibliography entry, -but the entry's title will now be a hyperlink to that URL. This -hyperlink may be useful to anyone who reads your document online -(this option can only be used with --hyperref or ---hypertex). Any DOI or eprint text which would be -produced as a result of the appropriate option will still appear in -this mode.

- -

The distribution includes preconverted versions of the four -standard BibTeX .bst style files.

- -

Only the style files which result from conversion of the standard -styles are checked in the regression tests. Other style files which -are known to work include

-
-acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, -geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, -siam.bst, mla.bst -
- -

Style files which are known to fail:

-
    -
  • Currently (v0.5), there exists a style achicago.bst -which seems to fox urlbst; it turns out that there's a -simpler but almost equivalent style chicago.bst which -works.
  • - -
  • Some APA-like styles, including at least apager.bst, -seem to be sufficiently different from the most common styles, that -they confuse urlbst completely.
  • - -
  • The koma-script styles and the refer styles are -not designed to produce conventional .bbl files, and -urlbst does not aim to produce anything useful from these.
  • -
-

This might be a good time for me to revisit the rather -convoluted logic within the script, to make it a little more robust in -the face of variants like these, but don't hold your breath...

- -

The natbib and revtex style files already have URL fields. If you have a -BibTeX style file which you think ought to work, but with which the -script fails, send it to me, and I'll try to work out what I've -missed (no promises, though).

- -

Note that the command to invoke the script changed from `urlbst.pl' -to plain `urlbst' between versions 0.3 and 0.4.

- -

For example...

-

To add URL support to the standard siam.bst file, you -can give the command

-
-% urlbst /path/to/original/siam.bst siamurl.bst
-
-

Your TeX installation will likely have some way of helping you find where -the original .bst files are. On teTeX-based systems, for -example, the command kpsewhich siam.bst returns the full -path of the siam.bst file which BibTeX would find.

- -

The distributed files abbrvurl.bst, -alphaurl.bst, plainurl.bst and -unsrturl.bst are versions of the standard style files -which have been pre-converted.

- -

There is more general discussion of including URLs in -bibliographies in the UK TeX -FAQ.

- -

Download and installation

- -

Download the file -urlbst-@PACKAGE_VERSION@.tar.gz -and unpack it.

- -

To install, you should simply copy the distributed -urlbst script to someplace on the path (such as -/usr/local/bin, or ~/local/bin, depending on -your privileges and tastes).

- -

If you (might) want to use the pre-converted standard -.bst files, then you'll need to copy these to somewhere -in the BibTeX search path. Type kpsepath bst on Unix to -find out the list of places BibTeX searches, and pick either one of -the user-local locations, or a system-wide one. If you're installing -in a system-wide location, you'll need admin privileges, obviously, -and you will probably need to use texhash, -mktexlsr or its equivalent, to update LaTeX's filename -cache. For further hints here, see -the TeX FAQ entries on installing a package and where LaTeX puts files.

- -

That should be all you have to do.

- -

The urlbst script is distributed with a path which should just work, -as long as the Perl binary is in your path, but if you have problems -here, then you might want to change the first line to something like

-
-#! /usr/local/bin/perl
-
-

if that's where your Perl binary is.

- -

You can also use the conventional ./configure; make; make -install to configure and install the package (as root, or using -sudo if you're installing it in a system location), -though you still have to install the .bst files by hand. -This is rather heavyweight for the trivial amount of configuration -required, so it's almost always simpler just to do things by hand.

- -

If you need to change some of the urlbst defaults, -however, or if your fingers type ./configure -spontaneously, then you can be reassured that the configure script -supports the standard --prefix option, plus the following -options setting defaults:

-
- -
--with-eprints=url, --without-eprints
- -
This makes the --eprints option to urlbst available -by default, and allows you to optionally specify a prefix for creating -URLs from eprint numbers. The default for this URL is -http://arxiv.org/abs/ -- this is appropriate for arXiv, -obviously, but there are now a variety of other preprint archives -appearing, for which this might be inappropriate. If you have -comments on this default, or alternatives, please let me know. This -option is enabled by default; if you have some reason for disabling -the --eprints option for urlbst, the give the configure -option --without-eprints
- -
--with-doi=url, --without-doi
- -
This makes available the --doi option to urlbst and, -as with the --with-eprints option, allows you to -customise the DOI resolver URL. The --doi option to -urlbst is on by default.
- -
--with-href=0/1/2
- -
This allows you to specify the type of hyperlinks which are -inserted in the bibliography. Values 0, 1 and 2, indicating no -hyperlinks, hypertex-style links, and hyperref-style links, -respectively. The default is --with-href=0. The -hyperref-style option is intended to complement the -increasingly standard hyperref package.
- -
- -

The first two options simply change defaults, and if you never use -the new eprints or doi fields, then the -defaults don't matter to you.

- -

Since the modified style generates URLs wrapped in the -\url{} macro, it is useful to use the resulting -bibliography style alongside the url package. Since this -tends to work with hyperref anyway, where possible, you -don't get any extra goodness by changing the --with-href -default at configuration time.

- -

Documentation

- -

Basic documentation is in the file urlbst.tex. This -is distributed as a PDF file, but if you want to regenerate it, use

-
-% latex urlbst
-% bibtex urlbst
-% latex urlbst
-% latex urlbst
-
- -

Further Information

- -

urlbst is archived on CTAN at biblio/bibtex/contrib/urlbst/, and discussed in the -TeX -FAQ.

- -

The home page of urlbst might possibly have more recent versions than the -one you're looking at now.

- -

Copyright 2002-8, Norman Gray. Released under the terms of the GNU -General Public Licence.

- -

Version history

-
- -
0.6-1, 2008 June 16
-
Fixed some broken links to the various citation standards (I think -in this context this should probably not be happening, -yes?). The distributed *url.bst no longer have the ---inlinelinks option turned on by default.
- -
0.6, 2007 March 26
-

Added the option --inlinelinks, which adds inline hyperlinks -to any bibliography entries which have URLs, but does so inline, rather -than printing the URL explicitly in the bibliography. This is (primarily) -useful if you're preparing a version of a document which will be read -on-screen. Thanks to Jason Eisner for the suggestion, and much testing.

-

Incorporate hyperref bugfixes from Paweł Widera.

-
-
0.6b3
-
Further reworkings of the inlinelinks support, so that it's now -fired by a format.title (or format.btitle) line, with a fallback in -fin.entry. This should be more robust, and allows me to delete some -of the previous version's gymnastics.
- -
0.6b2
-
Reworked inlinelinks support; should now be more -robust. Incorporate hyperref bugfixes from Paweł Widera.
- -
0.6b1
-
Added the option inlinelinks, which adds inline hyperlinks -to any bibliography entries which have URLs, but does so inline, rather -than printing the URL explicitly in the bibliography. This is (only) -useful if you're preparing a version of a document which will be read -on-screen.
-
-
- -
0.5.2, 2006 September 6
-
Another set of documentation-only changes, hopefully clarifying -installation.
- -
0.5.1, 2006 January 10
-
No functionality changes. Documentation and webpage changes only, -hopefully clarifying usage and configuration
- -
0.5, 2005 June 3
-
Added support for Digital Object Identifiers (DOI) fields in -bibliographies.
- -
0.4-1, 2005 April 12
-
Documentation improvements -- there are now examples in the help text!
- -
0.4, 2004 December 1
-
Bug fixes: now compatible with mla.bst and friends. Now uses -./configure (optionally). Assorted reorganisation.
- -
0.3, 2003 June 4
-
Added --eprint, --hypertex and --hyperref options.
- -
0.2, 2002 October 23
-
The `editor' field is now supported in the webpage entry type. Basic -documentation added.
- -
0.1, 2002 April
-
Initial version
- -
- - -
-Norman Gray
-@RELEASEDATE@ -
- - - diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.in b/Master/texmf-dist/doc/latex/urlbst/urlbst.in deleted file mode 100644 index 0bb468f6322..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/urlbst.in +++ /dev/null @@ -1,698 +0,0 @@ -#! @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: urlbst.in,v 1.10 2008/01/27 23:18:54 norman Exp $ - -$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; - -$Usage = "$progname [--eprint] [--doi] [--pubmed]\n [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref]\n [--help] [input-file [output-file]]"; - -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 '--help') { - print <$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 '-' ? '' : $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 () { - /^ *%/ && 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 .= ; - } - $bracematchtotal = 0; # reset - bracematcher($line); - $line =~ /\{\s*(\w*)/; - $found{'entry'.$1} = 1; - print OUT $line; - $line = ; - until (bracematcher($line) == 0) { - # XXX deal with multiple entries on one line - ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); - print OUT $line; - $line = ; - } - 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 () { - 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 <; - } - $line =~ s/(\{.*?\}.*?\{)/$1 #0 'outside.brackets := $mymarker - #1 'open.brackets := - #2 'within.brackets := - #3 'close.brackets := - - /s; - print OUT $line; - $found{initconsts} = 1; - next; - }; - - /^ *EXECUTE *\{init\.state\.consts\}/ && do { - print OUT "EXECUTE {init.urlbst.variables}\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/; - $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 setup.inlinelink - print OUT " title empty\$ 'skip\$ 'setup\.inlinelink if\$ $mymarker\n"; - 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\}/; - $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. -FUNCTION {setup.inlinelink} -{ makeinlinelink - { hrefform #1 = % hypertex - { "\special {html: }{" * 'openinlinelink := - "\special {html:}" 'closeinlinelink := - } - { hrefform #2 = % hyperref - { "\href{" url * "}{" * 'openinlinelink := - "}" 'closeinlinelink := - } - 'skip$ - if$ % hrefform #2 = - } - if$ % hrefform #1 = - #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: }" * swap$ * - "\special {html:}" * -} -% 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 - 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$ -} - -% 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 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 - { 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$ '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 = ) && ($line !~ /{/)) { - print OUT $line; - } - while (defined ($line) && bracematcher($line) > 0) { - print OUT $line; - $line = ; - } - print OUT "$line\n"; # print out terminating \} (assumed - # alone on the line) -} diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.pdf b/Master/texmf-dist/doc/latex/urlbst/urlbst.pdf deleted file mode 100644 index 5ff76111f17..00000000000 Binary files a/Master/texmf-dist/doc/latex/urlbst/urlbst.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.tex b/Master/texmf-dist/doc/latex/urlbst/urlbst.tex deleted file mode 100644 index 2554f08b5cb..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/urlbst.tex +++ /dev/null @@ -1,255 +0,0 @@ -\documentclass[a4paper]{article} - -\title{The \texttt{urlbst} package} -\author{Norman Gray\\\texttt{}} -\date{Version 0.6-1, 2008 June 16} - -%\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 -supports \btfield{url} and corresponding \btfield{lastchecked} fields -on 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 \btfield{url}, -\btfield{lastchecked} and \btfield{eprint} fields. - -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, then 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, then 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. - -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} -@Webpage{apastyle, - url = {http://www.apastyle.org/elecref.html}, - author = {{American Psychological Association}}, - title = {Electronic References}, - year = 2001, - lastchecked = {23 October 2002}, - note = {Excerpted from 5th edition of the APA Publication Manual} -} - -@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{walker} -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/latex/urlbst/urlbst.tex.in b/Master/texmf-dist/doc/latex/urlbst/urlbst.tex.in deleted file mode 100644 index a063aca4abf..00000000000 --- a/Master/texmf-dist/doc/latex/urlbst/urlbst.tex.in +++ /dev/null @@ -1,255 +0,0 @@ -\documentclass[a4paper]{article} - -\title{The \texttt{urlbst} package} -\author{Norman Gray\\\texttt{}} -\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 -supports \btfield{url} and corresponding \btfield{lastchecked} fields -on 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 \btfield{url}, -\btfield{lastchecked} and \btfield{eprint} fields. - -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, then 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, then 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. - -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} -@Webpage{apastyle, - url = {http://www.apastyle.org/elecref.html}, - author = {{American Psychological Association}}, - title = {Electronic References}, - year = 2001, - lastchecked = {23 October 2002}, - note = {Excerpted from 5th edition of the APA Publication Manual} -} - -@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{walker} -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} -- cgit v1.2.3