diff options
author | Karl Berry <karl@freefriends.org> | 2008-06-18 18:55:13 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-06-18 18:55:13 +0000 |
commit | ba68b87b140dbb977245265756c4872e375173e2 (patch) | |
tree | e26d7f0abfc99e203f971cc683985ef7c6093941 /Master/texmf-dist/doc/latex | |
parent | 35bf49efe29bec63bd2bd90993121c549a4abaa7 (diff) |
urlbst update (16jun08)
git-svn-id: svn://tug.org/texlive/trunk@8847 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/README | 302 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/VERSION | 1 | ||||
-rwxr-xr-x | Master/texmf-dist/doc/latex/urlbst/urlbst | 698 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/urlbst.html | 347 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/urlbst.html.in | 347 | ||||
-rwxr-xr-x | Master/texmf-dist/doc/latex/urlbst/urlbst.in | 698 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/urlbst.pdf | bin | 0 -> 102644 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/urlbst.tex | 255 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/urlbst/urlbst.tex.in | 255 |
9 files changed, 2870 insertions, 33 deletions
diff --git a/Master/texmf-dist/doc/latex/urlbst/README b/Master/texmf-dist/doc/latex/urlbst/README index ed3af19c36a..7e30209d774 100644 --- a/Master/texmf-dist/doc/latex/urlbst/README +++ b/Master/texmf-dist/doc/latex/urlbst/README @@ -1,47 +1,283 @@ -Adds a `webpage' BibTeX entry type, and support for general `url' and -`lastchecked' fields, to arbitrary BibTeX style files. + Urlbst - %%VERSION%% 0.1 + 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 Perl script urlbst.pl 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. + The Persistent URL for this page is http://purl.org/nxg/dist/urlbst. - Usage: urlbst.pl [input-file [output-file]] + Version 0.6-1, 2008 June 16. -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. + Contents + * Usage + * For example... + * Download and installation + * Further Information + * Version history -For example: + 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. - urlbst.pl `kpsewhich siam.bst` siamurl.bst + 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. -The distributed files abbrvurl.bst, alphaurl.bst, plainurl.bst and -unsrturl.bst are versions of the standard style files which have been -pre-converted. + 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. -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 +Usage - acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, - geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst and - siam.bst +urlbst [--eprint] [--doi] + [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] + [input-file [output-file]] -Style files known not to work, because they are too different from the -standard styles, include the koma-script styles and the refer styles -(they are not designed to produce conventional .bbl files). 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. + 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. -Copyright 2002, Norman Gray. -Released under the terms of the GNU General Public Licence. + 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. - Norman Gray - norman@astro.gla.ac.uk - $Date: 2002/04/22 15:49:06 $ + 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 new file mode 100644 index 00000000000..6a4461b90b2 --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/VERSION @@ -0,0 +1 @@ +urlbst-0.6-1 diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst b/Master/texmf-dist/doc/latex/urlbst/urlbst new file mode 100755 index 00000000000..18501bd58b3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst @@ -0,0 +1,698 @@ +#! /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 <<EOD; +urlbst version $version + Usage: $Usage + --eprint: include support for `eprint' fields + --doi: include support for `doi' field + --pubmed: include support for `pubmed' field + --nohyperlinks do not include active links anywhere + --inlinelinks add hyperlinks to entry titles + --hypertex: include HyperTeX-style hyperlink support + --hyperref: include {hyperref}-style hyperlink support + (generally better) + --help: print this help + Input and output files may be given as `-' (default) to indicate stdin/out +EOD + exit(0); + } elsif ($ARGV[0] =~ /^-/) { + die "Unrecognised option $ARGV[0]: Usage: $Usage\n"; + } elsif ($infile eq '-') { + $infile = $ARGV[0]; + } elsif ($outfile eq '-') { + $outfile = $ARGV[0]; + } else { + die "Usage: $Usage\n"; + } + shift(@ARGV); +} + +if ($inlinelinks && $makehref == 0) { + print <<'EOD'; +Warning: --inlinelinks and --nohyperlinks were both specified (possibly + implicitly). That combination makes no sense, so I'll ignore + --nohyperlinks and use --hyperref instead +EOD + $makehref = 2; +} + +$exitstatus = 0; # success status + +open (IN, "<$infile") || die "Can't open $infile to read"; +open (OUT, ">$outfile") || die "Can't open $outfile to write"; + +# We have to make certain assumptions about the source files, in order +# to patch them at the correct places. Specifically, we assume that +# +# - there's a function init.state.consts +# +# - ...and an output.nonnull which does the actual outputting, which +# has the `usual' interface. +# +# - we can replace +# fin.entry +# by +# new.block +# output.url % the function which formats and displays any URL +# fin.entry +# +# - there is a function which handles the `article' entry type (this +# will always be true) +# +# - there is a function output.bibitem which is called at the +# beginning of each entry type +# - ...and one called fin.entry which is called at the end +# +# If the functions format.date, format.title or new.block are not defined (the +# former is not in apalike, for example, and the last is not in the +# AMS styles), then replacements are included in the output. +# +# All these assumptions are true of the standard files and, since most +# style files derive from them more or less directly, are true of most (?) +# other style files, too. +# +# There's some rather ugly Perl down here. The parsing for +# brace-matching could probably do with being rewritten in places, to +# make it less ugly, and more robust. + +print OUT "%%% Modification of BibTeX style file ", ($infile eq '-' ? '<stdin>' : $infile), "\n"; +print OUT "%%% ... by $progname, version $version (marked with \"$mymarker\")\n%%% See <$myurl>\n"; +print OUT "%%% Added webpage entry type, and url and lastchecked fields.\n"; +print OUT "%%% Added eprint support.\n" if ($addeprints); +print OUT "%%% Added DOI support.\n" if ($adddoiresolver); +print OUT "%%% Added PUBMED support.\n" if ($addpubmedresolver); +print OUT "%%% Added HyperTeX support.\n" if ($makehref == 1); +print OUT "%%% Added hyperref support.\n" if ($makehref == 2); +print OUT "%%% Original headers follow...\n\n"; + +$found{initconsts} = 0; +$found{outputnonnull} = 0; +$found{article} = 0; +$found{outputbibitem} = 0; +$found{finentry} = 0; +$found{formatdate} = 0; +$found{formattitle} = 0; +$found{newblock} = 0; + +while (<IN>) { + /^ *%/ && do { + # Pass commented lines unchanged + print OUT; + next; + }; + + /^ *ENTRY/ && do { + # Work through the list of entry types, finding what ones are there. + # If we find a URL entry there already, object, since these edits + # will mess things up. + $line = $_; + until ($line =~ /\{\s*(\w*)/) { + $line .= <IN>; + } + $bracematchtotal = 0; # reset + bracematcher($line); + $line =~ /\{\s*(\w*)/; + $found{'entry'.$1} = 1; + print OUT $line; + $line = <IN>; + until (bracematcher($line) == 0) { + # XXX deal with multiple entries on one line + ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); + print OUT $line; + $line = <IN>; + } + if (defined($found{entryurl})) { + print STDERR "$progname: style file $infile already has URL entry!\n"; + # print out the rest of the file, and give up + print OUT $line; + while (<IN>) { + print OUT; + } + $exitstatus = 1; + last; + } else { + print OUT " eprint $mymarker\n doi $mymarker\n pubmed $mymarker\n url $mymarker\n lastchecked $mymarker\n"; + } + print OUT $line; + next; + }; + + /^ *FUNCTION *\{init\.state\.consts\}/ && do { + # In the init.state.consts function, add an extra set of + # constants at the beginning. Also use this as the marker for + # the place to add the init strings function. + print OUT <<EOD; +STRINGS { urlintro eprinturl eprintprefix doiprefix doiurl pubmedprefix pubmedurl openinlinelink closeinlinelink } $mymarker... +INTEGERS { hrefform inlinelinks makeinlinelink addeprints adddoiresolver addpubmedresolver } +% Following constants may be adjusted by hand, if desired +FUNCTION {init.urlbst.variables} +{ + "$availablestring" 'urlintro := % prefix before URL + "$eprinturl" 'eprinturl := % prefix to make URL from eprint ref + "$eprintprefix" 'eprintprefix := % text prefix printed before eprint ref + "$doiurl" 'doiurl := % prefix to make URL from DOI + "$doiprefix" 'doiprefix := % text prefix printed before DOI ref + "$pubmedurl" 'pubmedurl := % prefix to make URL from PUBMED + "$pubmedprefix" 'pubmedprefix := % text prefix printed before PUBMED ref + #$addeprints 'addeprints := % 0=no eprints; 1=include eprints + #$adddoiresolver 'adddoiresolver := % 0=no DOI resolver; 1=include it + #$addpubmedresolver 'addpubmedresolver := % 0=no PUBMED resolver; 1=include it + #$makehref 'hrefform := % 0=no crossrefs; 1=hypertex xrefs; 2=hyperref refs + #$inlinelinks 'inlinelinks := % 0=URLs explicit; 1=URLs attached to titles + % the following are internal state variables, not config constants + #0 'makeinlinelink := % state variable managed by setup.inlinelink + "" 'openinlinelink := % ditto + "" 'closeinlinelink := % ditto +} +INTEGERS { + bracket.state + outside.brackets + open.brackets + within.brackets + close.brackets +} +$mymarkerend +EOD + $line = $_; + until ($line =~ /\{.*\}.*\{/s) { + $line .= <IN>; + } + $line =~ s/(\{.*?\}.*?\{)/$1 #0 'outside.brackets := $mymarker + #1 'open.brackets := + #2 'within.brackets := + #3 'close.brackets := + + /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:<a href=" quote$ * url * quote$ * "> }{" * 'openinlinelink := + "\special {html:</a>}" '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:<a href=" quote$ * + swap$ * quote$ * "> }" * swap$ * + "\special {html:</a>}" * +} +% make hyperref specials +FUNCTION {make.href.hyperref} +{ + "\href {" swap$ * "} {\path{" * swap$ * "}}" * +} +FUNCTION {make.href} +{ hrefform #2 = + 'make.href.hyperref % hrefform = 2 + { hrefform #1 = + 'make.href.hypertex % hrefform = 1 + 'make.href.null % hrefform = 0 (or anything else) + if$ + } + if$ +} + +% If inlinelinks is true, then format.url should be a no-op, since it's +% (a) redundant, and (b) could end up as a link-within-a-link. +FUNCTION {format.url} +{ inlinelinks #1 = url empty$ or + { "" } + { hrefform #1 = + { % special case -- add HyperTeX specials + urlintro "\url{" url * "}" * url make.href.hypertex * } + { urlintro "\url{" * url * "}" * } + if$ + } + if$ +} + +FUNCTION {format.eprint} +{ eprint empty$ + { "" } + { eprintprefix eprint * eprinturl eprint * make.href } + if$ +} + +FUNCTION {format.doi} +{ doi empty$ + { "" } + { doiprefix doi * doiurl doi * make.href } + if$ +} + +FUNCTION {format.pubmed} +{ pubmed empty$ + { "" } + { pubmedprefix pubmed * pubmedurl pubmed * make.href } + if$ +} + +% Output a URL. We can't use the more normal idiom (something like +% `format.url output'), because the `inbrackets' within +% format.lastchecked applies to everything between calls to `output', +% so that `format.url format.lastchecked * output' ends up with both +% the URL and the lastchecked in brackets. +FUNCTION {output.url} +{ url empty$ + 'skip$ + { new.block + format.url output + format.lastchecked output + } + if$ +} + +FUNCTION {output.web.refs} +{ + new.block + 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 = <IN>) && ($line !~ /{/)) { + print OUT $line; + } + while (defined ($line) && bracematcher($line) > 0) { + print OUT $line; + $line = <IN>; + } + print OUT "$line\n"; # print out terminating \} (assumed + # alone on the line) +} diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.html b/Master/texmf-dist/doc/latex/urlbst/urlbst.html new file mode 100644 index 00000000000..eac33dfa948 --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst.html @@ -0,0 +1,347 @@ +<?xml version="1.0"?> + +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Urlbst</title> +<link href="http://nxg.me.uk/" rev="author"/> +<link type="text/css" rel="stylesheet" + href="http://nxg.me.uk/style/base.css"/> +</head> + +<body> +<h1>Urlbst</h1> +<div class="abstract"> +<p>A script to add a <code>webpage</code> BibTeX entry type, and add +support for general <code>url</code> and <code>lastchecked</code> +fields, to (most) BibTeX <code>.bst</code> files. Optionally adds +basic support for <code>eprint</code> and <code>doi</code> fields, and +hypertex/hyperref support, too.</p> + +<p>The Persistent URL for this page is +<code>http://purl.org/nxg/dist/urlbst</code>.</p> + +<p>Version 0.6-1, 2008 June 16.</p> +</div> + +<p>Contents</p> +<ul> +<li><a href='#usage'>Usage</a></li> +<li><a href='#example'>For example...</a></li> +<li><a href='#download'>Download and installation</a></li> +<li><a href='#information'>Further Information</a></li> +<li><a href='#history'>Version history</a></li> +</ul> + +<p>The standard BibTeX styles have no explicit support for the web, in +that they include no `webpage' type, and have no support for adding +URLs to references. There are rumours that such support might appear +in BibTeX 1.0, but there is no estimate of when that is likely to arrive.</p> + +<p>The Perl script <code>urlbst</code> can be used to add this support to an +arbitrary <code>.bst</code> file which has a reasonably `conventional' +structure. The result is meant to be robust rather than pretty.</p> + +<p>It has a different goal from Patrick Daly's `custom-bib' package -- +that is intended to create a BibTeX style .bst file from scratch, and +supports `url' and `eprint' fields. This package, on the other hand, +is intended for the case where you already have a style file that +works (or at least, which you cannot or will not change), and edits it +to add the new webpage entry type, plus the url, lastchecked and +eprint fields. Fuller details are in the <a href="urlbst.pdf" +>manual</a>.</p> + +<h2><a name='usage'>Usage</a></h2> +<pre> +urlbst [--eprint] [--doi] + [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] + [input-file [output-file]] +</pre> +<p>if either the input-file or the output-file is omitted, they default +to stdin and stdout respectively. If the input file already has a URL +entry type, then the script objects.</p> + +<p>If the option <code>--eprint</code> is present, then include +support for a <code>eprint</code> field in the modified +<code>.bst</code> file, with a citation format matching that +recommended in <a href="http://arxiv.org/help/faq/references" >the +arXiv documentation</a>. Similarly, if the option <code>--doi</code> +is present, then include support for a <code>doi</code> field, +referring to a <a href="http://www.doi.org/">DOI</a> for the +bibliographic item.</p> + +<p>If either of the <code>--hypertex</code> or <code>--hyperref</code> +options is present, then the generated <code>.bst</code> file includes +support for hyperlinks in the generated eprint entries in the +bibliography, with the format being either HyperTeX (see <a +href="http://arxiv.org/hypertex/#implementation" >arXiv, again</a>), +supported by xdvi, dvips and others, or using the support available +from the hyperref package. These options have no effect unless one of +the <code>--eprint</code> or <code>--doi</code> options is given: when +URLs are included in the bibliography, they are written out using the +<code>\url{...}</code> command, and hyperref automatically processes +that in the correct way to include a hyperlink.</p> + +<p>The <code>--inlinelinks</code> option tells urlbst not to write out +the URL as text within the bibliography entry. Instead, urlbst will +produce a more conventional-looking and compact bibliography entry, +but the entry's title will now be a hyperlink to that URL. This +hyperlink may be useful to anyone who reads your document online +(this option can only be used with <code>--hyperref</code> or +<code>--hypertex</code>). Any DOI or eprint text which would be +produced as a result of the appropriate option will still appear in +this mode.</p> + +<p>The distribution includes preconverted versions of the four +standard BibTeX .bst style files.</p> + +<p>Only the style files which result from conversion of the standard +styles are checked in the regression tests. Other style files which +are known to work include</p> +<blockquote> +acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, +geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, +siam.bst, mla.bst +</blockquote> + +<p>Style files which are known to fail:</p> +<ul> +<li>Currently (v0.5), there exists a style <code>achicago.bst</code> +which seems to fox <code>urlbst</code>; it turns out that there's a +simpler but almost equivalent style <code>chicago.bst</code> which +works.</li> + +<li>Some APA-like styles, including at least <code>apager.bst</code>, +seem to be sufficiently different from the most common styles, that +they confuse <code>urlbst</code> completely.</li> + +<li>The <em>koma-script</em> styles and the <em>refer</em> styles are +not designed to produce conventional <code>.bbl</code> files, and +<code>urlbst</code> does not aim to produce anything useful from these.</li> +</ul> +<p>This might be a good time for me to revisit the rather +convoluted logic within the script, to make it a little more robust in +the face of variants like these, but don't hold your breath...</p> + +<p>The natbib and revtex style files already have URL fields. If you have a +BibTeX style file which you think ought to work, but with which the +script fails, send it to me, and I'll try to work out what I've +missed (no promises, though).</p> + +<p>Note that the command to invoke the script changed from `urlbst.pl' +to plain `urlbst' between versions 0.3 and 0.4.</p> + +<h2><a name='example'>For example...</a></h2> +<p>To add URL support to the standard <code>siam.bst</code> file, you +can give the command</p> +<pre> +% urlbst /path/to/original/siam.bst siamurl.bst +</pre> +<p>Your TeX installation will likely have some way of helping you find where +the original <code>.bst</code> files are. On teTeX-based systems, for +example, the command <code>kpsewhich siam.bst</code> returns the full +path of the <code>siam.bst</code> file which BibTeX would find.</p> + +<p>The distributed files <code>abbrvurl.bst</code>, +<code>alphaurl.bst</code>, <code>plainurl.bst</code> and +<code>unsrturl.bst</code> are versions of the standard style files +which have been pre-converted.</p> + +<p>There is more general discussion of including URLs in +bibliographies in the <a +href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL" >UK TeX +FAQ</a>.</p> + +<h2><a name='download'>Download and installation</a></h2> + +<p>Download the file +<a href="urlbst-0.6-1.tar.gz" >urlbst-0.6-1.tar.gz</a> +and unpack it.</p> + +<p>To install, you should simply copy the distributed +<code>urlbst</code> script to someplace on the path (such as +<code>/usr/local/bin</code>, or <code>~/local/bin</code>, depending on +your privileges and tastes).</p> + +<p>If you (might) want to use the pre-converted standard +<code>.bst</code> files, then you'll need to copy these to somewhere +in the BibTeX search path. Type <kbd>kpsepath bst</kbd> on Unix to +find out the list of places BibTeX searches, and pick either one of +the user-local locations, or a system-wide one. If you're installing +in a system-wide location, you'll need admin privileges, obviously, +and you will probably need to use <code>texhash</code>, +<code>mktexlsr</code> or its equivalent, to update LaTeX's filename +cache. For further hints here, see +the TeX FAQ entries on <a +href='http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages' +>installing a package</a> and <a +href='http://www.tex.ac.uk/cgi-bin/texfaq2html?label=wherefiles' +>where LaTeX puts files</a>.</p> + +<p>That should be all you have to do.</p> + +<p>The urlbst script is distributed with a path which should just work, +as long as the Perl binary is in your path, but if you have problems +here, then you might want to change the first line to something like</p> +<pre> +#! /usr/local/bin/perl +</pre> +<p>if that's where your Perl binary is.</p> + +<p>You can also use the conventional <code>./configure; make; make +install</code> to configure and install the package (as root, or using +<code>sudo</code> if you're installing it in a system location), +though you still have to install the <code>.bst</code> files by hand. +This is rather heavyweight for the trivial amount of configuration +required, so it's almost always simpler just to do things by hand.</p> + +<p>If you need to change some of the <code>urlbst</code> defaults, +however, or if your fingers type <code>./configure</code> +spontaneously, then you can be reassured that the configure script +supports the standard <code>--prefix</code> option, plus the following +options setting defaults:</p> +<dl> + +<dt><code>--with-eprints=url</code>, <code>--without-eprints</code></dt> + +<dd>This makes the <code>--eprints</code> option to urlbst available +by default, and allows you to optionally specify a prefix for creating +URLs from eprint numbers. The default for this URL is +<code>http://arxiv.org/abs/</code> -- this is appropriate for arXiv, +obviously, but there are now a variety of other preprint archives +appearing, for which this might be inappropriate. If you have +comments on this default, or alternatives, please let me know. This +option is enabled by default; if you have some reason for disabling +the <code>--eprints</code> option for urlbst, the give the configure +option <code>--without-eprints</code></dd> + +<dt><code>--with-doi=url</code>, <code>--without-doi</code></dt> + +<dd>This makes available the <code>--doi</code> option to urlbst and, +as with the <code>--with-eprints</code> option, allows you to +customise the DOI resolver URL. The <code>--doi</code> option to +urlbst is on by default.</dd> + +<dt><code>--with-href=0/1/2</code></dt> + +<dd>This allows you to specify the type of hyperlinks which are +inserted in the bibliography. Values 0, 1 and 2, indicating no +hyperlinks, hypertex-style links, and hyperref-style links, +respectively. The default is <code>--with-href=0</code>. The +<code>hyperref</code>-style option is intended to complement the +increasingly standard <code>hyperref</code> package.</dd> + +</dl> + +<p>The first two options simply change defaults, and if you never use +the new <code>eprints</code> or <code>doi</code> fields, then the +defaults don't matter to you. </p> + +<p>Since the modified style generates URLs wrapped in the +<code>\url{}</code> macro, it is useful to use the resulting +bibliography style alongside the <code>url</code> package. Since this +tends to work with <code>hyperref</code> anyway, where possible, you +don't get any extra goodness by changing the <code>--with-href</code> +default at configuration time.</p> + +<h3>Documentation</h3> + +<p>Basic documentation is in the file <code>urlbst.tex</code>. This +is distributed as a PDF file, but if you want to regenerate it, use</p> +<pre> +% latex urlbst +% bibtex urlbst +% latex urlbst +% latex urlbst +</pre> + +<h2><a name='information'>Further Information</a></h2> + +<p><code>urlbst</code> is archived on CTAN at <a +href="http://www.tex.ac.uk/tex-archive/biblio/bibtex/contrib/urlbst/" +><code>biblio/bibtex/contrib/urlbst/</code></a>, and discussed in the +<a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL" >TeX +FAQ</a>.</p> + +<p>The <a href="http://purl.org/nxg/dist/urlbst" +>home page of urlbst</a> might possibly have more recent versions than the +one you're looking at now.</p> + +<p>Copyright 2002-8, Norman Gray. Released under the terms of the GNU +General Public Licence.</p> + +<h2><a name='history'>Version history</a></h2> +<dl> + +<dt>0.6-1, 2008 June 16</dt> +<dd>Fixed some broken links to the various citation standards (I think +in this context this should probably <em>not</em> be happening, +yes?). The distributed <code>*url.bst</code> no longer have the +<code>--inlinelinks</code> option turned on by default.</dd> + +<dt>0.6, 2007 March 26</dt> +<dd><p>Added the option <code>--inlinelinks</code>, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (primarily) +useful if you're preparing a version of a document which will be read +on-screen. Thanks to Jason Eisner for the suggestion, and much testing.</p> +<p>Incorporate hyperref bugfixes from Paweł Widera.</p> +<dl> +<dt>0.6b3</dt> +<dd>Further reworkings of the inlinelinks support, so that it's now +fired by a format.title (or format.btitle) line, with a fallback in +fin.entry. This should be more robust, and allows me to delete some +of the previous version's gymnastics.</dd> + +<dt>0.6b2</dt> +<dd>Reworked <code>inlinelinks</code> support; should now be more +robust. Incorporate hyperref bugfixes from Paweł Widera.</dd> + +<dt>0.6b1</dt> +<dd>Added the option <code>inlinelinks</code>, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (only) +useful if you're preparing a version of a document which will be read +on-screen.</dd> +</dl> +</dd> + +<dt>0.5.2, 2006 September 6</dt> +<dd>Another set of documentation-only changes, hopefully clarifying +installation.</dd> + +<dt>0.5.1, 2006 January 10</dt> +<dd>No functionality changes. Documentation and webpage changes only, +hopefully clarifying usage and configuration</dd> + +<dt>0.5, 2005 June 3</dt> +<dd>Added support for Digital Object Identifiers (DOI) fields in +bibliographies.</dd> + +<dt>0.4-1, 2005 April 12</dt> +<dd>Documentation improvements -- there are now examples in the help text!</dd> + +<dt>0.4, 2004 December 1</dt> +<dd>Bug fixes: now compatible with mla.bst and friends. Now uses +./configure (optionally). Assorted reorganisation.</dd> + +<dt>0.3, 2003 June 4</dt> +<dd>Added --eprint, --hypertex and --hyperref options.</dd> + +<dt>0.2, 2002 October 23</dt> +<dd>The `editor' field is now supported in the webpage entry type. Basic +documentation added.</dd> + +<dt>0.1, 2002 April</dt> +<dd>Initial version</dd> + +</dl> + + +<div class="signature"> +<a href="http://nxg.me.uk" + >Norman Gray</a><br/> +2008 June 16 +</div> + +</body> +</html> diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.html.in b/Master/texmf-dist/doc/latex/urlbst/urlbst.html.in new file mode 100644 index 00000000000..6facc246252 --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst.html.in @@ -0,0 +1,347 @@ +<?xml version="1.0"?> + +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Urlbst</title> +<link href="http://nxg.me.uk/" rev="author"/> +<link type="text/css" rel="stylesheet" + href="http://nxg.me.uk/style/base.css"/> +</head> + +<body> +<h1>Urlbst</h1> +<div class="abstract"> +<p>A script to add a <code>webpage</code> BibTeX entry type, and add +support for general <code>url</code> and <code>lastchecked</code> +fields, to (most) BibTeX <code>.bst</code> files. Optionally adds +basic support for <code>eprint</code> and <code>doi</code> fields, and +hypertex/hyperref support, too.</p> + +<p>The Persistent URL for this page is +<code>http://purl.org/nxg/dist/urlbst</code>.</p> + +<p>Version @PACKAGE_VERSION@, @RELEASEDATE@.</p> +</div> + +<p>Contents</p> +<ul> +<li><a href='#usage'>Usage</a></li> +<li><a href='#example'>For example...</a></li> +<li><a href='#download'>Download and installation</a></li> +<li><a href='#information'>Further Information</a></li> +<li><a href='#history'>Version history</a></li> +</ul> + +<p>The standard BibTeX styles have no explicit support for the web, in +that they include no `webpage' type, and have no support for adding +URLs to references. There are rumours that such support might appear +in BibTeX 1.0, but there is no estimate of when that is likely to arrive.</p> + +<p>The Perl script <code>urlbst</code> can be used to add this support to an +arbitrary <code>.bst</code> file which has a reasonably `conventional' +structure. The result is meant to be robust rather than pretty.</p> + +<p>It has a different goal from Patrick Daly's `custom-bib' package -- +that is intended to create a BibTeX style .bst file from scratch, and +supports `url' and `eprint' fields. This package, on the other hand, +is intended for the case where you already have a style file that +works (or at least, which you cannot or will not change), and edits it +to add the new webpage entry type, plus the url, lastchecked and +eprint fields. Fuller details are in the <a href="urlbst.pdf" +>manual</a>.</p> + +<h2><a name='usage'>Usage</a></h2> +<pre> +urlbst [--eprint] [--doi] + [--inlinelinks] [--nohyperlinks] [--hypertex] [--hyperref] + [input-file [output-file]] +</pre> +<p>if either the input-file or the output-file is omitted, they default +to stdin and stdout respectively. If the input file already has a URL +entry type, then the script objects.</p> + +<p>If the option <code>--eprint</code> is present, then include +support for a <code>eprint</code> field in the modified +<code>.bst</code> file, with a citation format matching that +recommended in <a href="http://arxiv.org/help/faq/references" >the +arXiv documentation</a>. Similarly, if the option <code>--doi</code> +is present, then include support for a <code>doi</code> field, +referring to a <a href="http://www.doi.org/">DOI</a> for the +bibliographic item.</p> + +<p>If either of the <code>--hypertex</code> or <code>--hyperref</code> +options is present, then the generated <code>.bst</code> file includes +support for hyperlinks in the generated eprint entries in the +bibliography, with the format being either HyperTeX (see <a +href="http://arxiv.org/hypertex/#implementation" >arXiv, again</a>), +supported by xdvi, dvips and others, or using the support available +from the hyperref package. These options have no effect unless one of +the <code>--eprint</code> or <code>--doi</code> options is given: when +URLs are included in the bibliography, they are written out using the +<code>\url{...}</code> command, and hyperref automatically processes +that in the correct way to include a hyperlink.</p> + +<p>The <code>--inlinelinks</code> option tells urlbst not to write out +the URL as text within the bibliography entry. Instead, urlbst will +produce a more conventional-looking and compact bibliography entry, +but the entry's title will now be a hyperlink to that URL. This +hyperlink may be useful to anyone who reads your document online +(this option can only be used with <code>--hyperref</code> or +<code>--hypertex</code>). Any DOI or eprint text which would be +produced as a result of the appropriate option will still appear in +this mode.</p> + +<p>The distribution includes preconverted versions of the four +standard BibTeX .bst style files.</p> + +<p>Only the style files which result from conversion of the standard +styles are checked in the regression tests. Other style files which +are known to work include</p> +<blockquote> +acm.bst, amsalpha.bst, amsplain.bst, apalike.bst, gerabbrv.bst, +geralpha.bst, gerapali.bst, gerplain.bst, gerunsrt.bst, ieeetr.bst, +siam.bst, mla.bst +</blockquote> + +<p>Style files which are known to fail:</p> +<ul> +<li>Currently (v0.5), there exists a style <code>achicago.bst</code> +which seems to fox <code>urlbst</code>; it turns out that there's a +simpler but almost equivalent style <code>chicago.bst</code> which +works.</li> + +<li>Some APA-like styles, including at least <code>apager.bst</code>, +seem to be sufficiently different from the most common styles, that +they confuse <code>urlbst</code> completely.</li> + +<li>The <em>koma-script</em> styles and the <em>refer</em> styles are +not designed to produce conventional <code>.bbl</code> files, and +<code>urlbst</code> does not aim to produce anything useful from these.</li> +</ul> +<p>This might be a good time for me to revisit the rather +convoluted logic within the script, to make it a little more robust in +the face of variants like these, but don't hold your breath...</p> + +<p>The natbib and revtex style files already have URL fields. If you have a +BibTeX style file which you think ought to work, but with which the +script fails, send it to me, and I'll try to work out what I've +missed (no promises, though).</p> + +<p>Note that the command to invoke the script changed from `urlbst.pl' +to plain `urlbst' between versions 0.3 and 0.4.</p> + +<h2><a name='example'>For example...</a></h2> +<p>To add URL support to the standard <code>siam.bst</code> file, you +can give the command</p> +<pre> +% urlbst /path/to/original/siam.bst siamurl.bst +</pre> +<p>Your TeX installation will likely have some way of helping you find where +the original <code>.bst</code> files are. On teTeX-based systems, for +example, the command <code>kpsewhich siam.bst</code> returns the full +path of the <code>siam.bst</code> file which BibTeX would find.</p> + +<p>The distributed files <code>abbrvurl.bst</code>, +<code>alphaurl.bst</code>, <code>plainurl.bst</code> and +<code>unsrturl.bst</code> are versions of the standard style files +which have been pre-converted.</p> + +<p>There is more general discussion of including URLs in +bibliographies in the <a +href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL" >UK TeX +FAQ</a>.</p> + +<h2><a name='download'>Download and installation</a></h2> + +<p>Download the file +<a href="urlbst-@PACKAGE_VERSION@.tar.gz" >urlbst-@PACKAGE_VERSION@.tar.gz</a> +and unpack it.</p> + +<p>To install, you should simply copy the distributed +<code>urlbst</code> script to someplace on the path (such as +<code>/usr/local/bin</code>, or <code>~/local/bin</code>, depending on +your privileges and tastes).</p> + +<p>If you (might) want to use the pre-converted standard +<code>.bst</code> files, then you'll need to copy these to somewhere +in the BibTeX search path. Type <kbd>kpsepath bst</kbd> on Unix to +find out the list of places BibTeX searches, and pick either one of +the user-local locations, or a system-wide one. If you're installing +in a system-wide location, you'll need admin privileges, obviously, +and you will probably need to use <code>texhash</code>, +<code>mktexlsr</code> or its equivalent, to update LaTeX's filename +cache. For further hints here, see +the TeX FAQ entries on <a +href='http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages' +>installing a package</a> and <a +href='http://www.tex.ac.uk/cgi-bin/texfaq2html?label=wherefiles' +>where LaTeX puts files</a>.</p> + +<p>That should be all you have to do.</p> + +<p>The urlbst script is distributed with a path which should just work, +as long as the Perl binary is in your path, but if you have problems +here, then you might want to change the first line to something like</p> +<pre> +#! /usr/local/bin/perl +</pre> +<p>if that's where your Perl binary is.</p> + +<p>You can also use the conventional <code>./configure; make; make +install</code> to configure and install the package (as root, or using +<code>sudo</code> if you're installing it in a system location), +though you still have to install the <code>.bst</code> files by hand. +This is rather heavyweight for the trivial amount of configuration +required, so it's almost always simpler just to do things by hand.</p> + +<p>If you need to change some of the <code>urlbst</code> defaults, +however, or if your fingers type <code>./configure</code> +spontaneously, then you can be reassured that the configure script +supports the standard <code>--prefix</code> option, plus the following +options setting defaults:</p> +<dl> + +<dt><code>--with-eprints=url</code>, <code>--without-eprints</code></dt> + +<dd>This makes the <code>--eprints</code> option to urlbst available +by default, and allows you to optionally specify a prefix for creating +URLs from eprint numbers. The default for this URL is +<code>http://arxiv.org/abs/</code> -- this is appropriate for arXiv, +obviously, but there are now a variety of other preprint archives +appearing, for which this might be inappropriate. If you have +comments on this default, or alternatives, please let me know. This +option is enabled by default; if you have some reason for disabling +the <code>--eprints</code> option for urlbst, the give the configure +option <code>--without-eprints</code></dd> + +<dt><code>--with-doi=url</code>, <code>--without-doi</code></dt> + +<dd>This makes available the <code>--doi</code> option to urlbst and, +as with the <code>--with-eprints</code> option, allows you to +customise the DOI resolver URL. The <code>--doi</code> option to +urlbst is on by default.</dd> + +<dt><code>--with-href=0/1/2</code></dt> + +<dd>This allows you to specify the type of hyperlinks which are +inserted in the bibliography. Values 0, 1 and 2, indicating no +hyperlinks, hypertex-style links, and hyperref-style links, +respectively. The default is <code>--with-href=0</code>. The +<code>hyperref</code>-style option is intended to complement the +increasingly standard <code>hyperref</code> package.</dd> + +</dl> + +<p>The first two options simply change defaults, and if you never use +the new <code>eprints</code> or <code>doi</code> fields, then the +defaults don't matter to you. </p> + +<p>Since the modified style generates URLs wrapped in the +<code>\url{}</code> macro, it is useful to use the resulting +bibliography style alongside the <code>url</code> package. Since this +tends to work with <code>hyperref</code> anyway, where possible, you +don't get any extra goodness by changing the <code>--with-href</code> +default at configuration time.</p> + +<h3>Documentation</h3> + +<p>Basic documentation is in the file <code>urlbst.tex</code>. This +is distributed as a PDF file, but if you want to regenerate it, use</p> +<pre> +% latex urlbst +% bibtex urlbst +% latex urlbst +% latex urlbst +</pre> + +<h2><a name='information'>Further Information</a></h2> + +<p><code>urlbst</code> is archived on CTAN at <a +href="http://www.tex.ac.uk/tex-archive/biblio/bibtex/contrib/urlbst/" +><code>biblio/bibtex/contrib/urlbst/</code></a>, and discussed in the +<a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=citeURL" >TeX +FAQ</a>.</p> + +<p>The <a href="http://purl.org/nxg/dist/urlbst" +>home page of urlbst</a> might possibly have more recent versions than the +one you're looking at now.</p> + +<p>Copyright 2002-8, Norman Gray. Released under the terms of the GNU +General Public Licence.</p> + +<h2><a name='history'>Version history</a></h2> +<dl> + +<dt>0.6-1, 2008 June 16</dt> +<dd>Fixed some broken links to the various citation standards (I think +in this context this should probably <em>not</em> be happening, +yes?). The distributed <code>*url.bst</code> no longer have the +<code>--inlinelinks</code> option turned on by default.</dd> + +<dt>0.6, 2007 March 26</dt> +<dd><p>Added the option <code>--inlinelinks</code>, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (primarily) +useful if you're preparing a version of a document which will be read +on-screen. Thanks to Jason Eisner for the suggestion, and much testing.</p> +<p>Incorporate hyperref bugfixes from Paweł Widera.</p> +<dl> +<dt>0.6b3</dt> +<dd>Further reworkings of the inlinelinks support, so that it's now +fired by a format.title (or format.btitle) line, with a fallback in +fin.entry. This should be more robust, and allows me to delete some +of the previous version's gymnastics.</dd> + +<dt>0.6b2</dt> +<dd>Reworked <code>inlinelinks</code> support; should now be more +robust. Incorporate hyperref bugfixes from Paweł Widera.</dd> + +<dt>0.6b1</dt> +<dd>Added the option <code>inlinelinks</code>, which adds inline hyperlinks +to any bibliography entries which have URLs, but does so inline, rather +than printing the URL explicitly in the bibliography. This is (only) +useful if you're preparing a version of a document which will be read +on-screen.</dd> +</dl> +</dd> + +<dt>0.5.2, 2006 September 6</dt> +<dd>Another set of documentation-only changes, hopefully clarifying +installation.</dd> + +<dt>0.5.1, 2006 January 10</dt> +<dd>No functionality changes. Documentation and webpage changes only, +hopefully clarifying usage and configuration</dd> + +<dt>0.5, 2005 June 3</dt> +<dd>Added support for Digital Object Identifiers (DOI) fields in +bibliographies.</dd> + +<dt>0.4-1, 2005 April 12</dt> +<dd>Documentation improvements -- there are now examples in the help text!</dd> + +<dt>0.4, 2004 December 1</dt> +<dd>Bug fixes: now compatible with mla.bst and friends. Now uses +./configure (optionally). Assorted reorganisation.</dd> + +<dt>0.3, 2003 June 4</dt> +<dd>Added --eprint, --hypertex and --hyperref options.</dd> + +<dt>0.2, 2002 October 23</dt> +<dd>The `editor' field is now supported in the webpage entry type. Basic +documentation added.</dd> + +<dt>0.1, 2002 April</dt> +<dd>Initial version</dd> + +</dl> + + +<div class="signature"> +<a href="http://nxg.me.uk" + >Norman Gray</a><br/> +@RELEASEDATE@ +</div> + +</body> +</html> diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.in b/Master/texmf-dist/doc/latex/urlbst/urlbst.in new file mode 100755 index 00000000000..0bb468f6322 --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst.in @@ -0,0 +1,698 @@ +#! @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 <<EOD; +urlbst version $version + Usage: $Usage + --eprint: include support for `eprint' fields + --doi: include support for `doi' field + --pubmed: include support for `pubmed' field + --nohyperlinks do not include active links anywhere + --inlinelinks add hyperlinks to entry titles + --hypertex: include HyperTeX-style hyperlink support + --hyperref: include {hyperref}-style hyperlink support + (generally better) + --help: print this help + Input and output files may be given as `-' (default) to indicate stdin/out +EOD + exit(0); + } elsif ($ARGV[0] =~ /^-/) { + die "Unrecognised option $ARGV[0]: Usage: $Usage\n"; + } elsif ($infile eq '-') { + $infile = $ARGV[0]; + } elsif ($outfile eq '-') { + $outfile = $ARGV[0]; + } else { + die "Usage: $Usage\n"; + } + shift(@ARGV); +} + +if ($inlinelinks && $makehref == 0) { + print <<'EOD'; +Warning: --inlinelinks and --nohyperlinks were both specified (possibly + implicitly). That combination makes no sense, so I'll ignore + --nohyperlinks and use --hyperref instead +EOD + $makehref = 2; +} + +$exitstatus = 0; # success status + +open (IN, "<$infile") || die "Can't open $infile to read"; +open (OUT, ">$outfile") || die "Can't open $outfile to write"; + +# We have to make certain assumptions about the source files, in order +# to patch them at the correct places. Specifically, we assume that +# +# - there's a function init.state.consts +# +# - ...and an output.nonnull which does the actual outputting, which +# has the `usual' interface. +# +# - we can replace +# fin.entry +# by +# new.block +# output.url % the function which formats and displays any URL +# fin.entry +# +# - there is a function which handles the `article' entry type (this +# will always be true) +# +# - there is a function output.bibitem which is called at the +# beginning of each entry type +# - ...and one called fin.entry which is called at the end +# +# If the functions format.date, format.title or new.block are not defined (the +# former is not in apalike, for example, and the last is not in the +# AMS styles), then replacements are included in the output. +# +# All these assumptions are true of the standard files and, since most +# style files derive from them more or less directly, are true of most (?) +# other style files, too. +# +# There's some rather ugly Perl down here. The parsing for +# brace-matching could probably do with being rewritten in places, to +# make it less ugly, and more robust. + +print OUT "%%% Modification of BibTeX style file ", ($infile eq '-' ? '<stdin>' : $infile), "\n"; +print OUT "%%% ... by $progname, version $version (marked with \"$mymarker\")\n%%% See <$myurl>\n"; +print OUT "%%% Added webpage entry type, and url and lastchecked fields.\n"; +print OUT "%%% Added eprint support.\n" if ($addeprints); +print OUT "%%% Added DOI support.\n" if ($adddoiresolver); +print OUT "%%% Added PUBMED support.\n" if ($addpubmedresolver); +print OUT "%%% Added HyperTeX support.\n" if ($makehref == 1); +print OUT "%%% Added hyperref support.\n" if ($makehref == 2); +print OUT "%%% Original headers follow...\n\n"; + +$found{initconsts} = 0; +$found{outputnonnull} = 0; +$found{article} = 0; +$found{outputbibitem} = 0; +$found{finentry} = 0; +$found{formatdate} = 0; +$found{formattitle} = 0; +$found{newblock} = 0; + +while (<IN>) { + /^ *%/ && do { + # Pass commented lines unchanged + print OUT; + next; + }; + + /^ *ENTRY/ && do { + # Work through the list of entry types, finding what ones are there. + # If we find a URL entry there already, object, since these edits + # will mess things up. + $line = $_; + until ($line =~ /\{\s*(\w*)/) { + $line .= <IN>; + } + $bracematchtotal = 0; # reset + bracematcher($line); + $line =~ /\{\s*(\w*)/; + $found{'entry'.$1} = 1; + print OUT $line; + $line = <IN>; + until (bracematcher($line) == 0) { + # XXX deal with multiple entries on one line + ($line =~ /^\s*(\w*)/) && ($found{'entry'.$1} = 1); + print OUT $line; + $line = <IN>; + } + if (defined($found{entryurl})) { + print STDERR "$progname: style file $infile already has URL entry!\n"; + # print out the rest of the file, and give up + print OUT $line; + while (<IN>) { + print OUT; + } + $exitstatus = 1; + last; + } else { + print OUT " eprint $mymarker\n doi $mymarker\n pubmed $mymarker\n url $mymarker\n lastchecked $mymarker\n"; + } + print OUT $line; + next; + }; + + /^ *FUNCTION *\{init\.state\.consts\}/ && do { + # In the init.state.consts function, add an extra set of + # constants at the beginning. Also use this as the marker for + # the place to add the init strings function. + print OUT <<EOD; +STRINGS { urlintro eprinturl eprintprefix doiprefix doiurl pubmedprefix pubmedurl openinlinelink closeinlinelink } $mymarker... +INTEGERS { hrefform inlinelinks makeinlinelink addeprints adddoiresolver addpubmedresolver } +% Following constants may be adjusted by hand, if desired +FUNCTION {init.urlbst.variables} +{ + "$availablestring" 'urlintro := % prefix before URL + "$eprinturl" 'eprinturl := % prefix to make URL from eprint ref + "$eprintprefix" 'eprintprefix := % text prefix printed before eprint ref + "$doiurl" 'doiurl := % prefix to make URL from DOI + "$doiprefix" 'doiprefix := % text prefix printed before DOI ref + "$pubmedurl" 'pubmedurl := % prefix to make URL from PUBMED + "$pubmedprefix" 'pubmedprefix := % text prefix printed before PUBMED ref + #$addeprints 'addeprints := % 0=no eprints; 1=include eprints + #$adddoiresolver 'adddoiresolver := % 0=no DOI resolver; 1=include it + #$addpubmedresolver 'addpubmedresolver := % 0=no PUBMED resolver; 1=include it + #$makehref 'hrefform := % 0=no crossrefs; 1=hypertex xrefs; 2=hyperref refs + #$inlinelinks 'inlinelinks := % 0=URLs explicit; 1=URLs attached to titles + % the following are internal state variables, not config constants + #0 'makeinlinelink := % state variable managed by setup.inlinelink + "" 'openinlinelink := % ditto + "" 'closeinlinelink := % ditto +} +INTEGERS { + bracket.state + outside.brackets + open.brackets + within.brackets + close.brackets +} +$mymarkerend +EOD + $line = $_; + until ($line =~ /\{.*\}.*\{/s) { + $line .= <IN>; + } + $line =~ s/(\{.*?\}.*?\{)/$1 #0 'outside.brackets := $mymarker + #1 'open.brackets := + #2 'within.brackets := + #3 'close.brackets := + + /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:<a href=" quote$ * url * quote$ * "> }{" * 'openinlinelink := + "\special {html:</a>}" '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:<a href=" quote$ * + swap$ * quote$ * "> }" * swap$ * + "\special {html:</a>}" * +} +% make hyperref specials +FUNCTION {make.href.hyperref} +{ + "\href {" swap$ * "} {\path{" * swap$ * "}}" * +} +FUNCTION {make.href} +{ hrefform #2 = + 'make.href.hyperref % hrefform = 2 + { hrefform #1 = + 'make.href.hypertex % hrefform = 1 + 'make.href.null % hrefform = 0 (or anything else) + if$ + } + if$ +} + +% If inlinelinks is true, then format.url should be a no-op, since it's +% (a) redundant, and (b) could end up as a link-within-a-link. +FUNCTION {format.url} +{ inlinelinks #1 = url empty$ or + { "" } + { hrefform #1 = + { % special case -- add HyperTeX specials + urlintro "\url{" url * "}" * url make.href.hypertex * } + { urlintro "\url{" * url * "}" * } + if$ + } + if$ +} + +FUNCTION {format.eprint} +{ eprint empty$ + { "" } + { eprintprefix eprint * eprinturl eprint * make.href } + if$ +} + +FUNCTION {format.doi} +{ doi empty$ + { "" } + { doiprefix doi * doiurl doi * make.href } + if$ +} + +FUNCTION {format.pubmed} +{ pubmed empty$ + { "" } + { pubmedprefix pubmed * pubmedurl pubmed * make.href } + if$ +} + +% Output a URL. We can't use the more normal idiom (something like +% `format.url output'), because the `inbrackets' within +% format.lastchecked applies to everything between calls to `output', +% so that `format.url format.lastchecked * output' ends up with both +% the URL and the lastchecked in brackets. +FUNCTION {output.url} +{ url empty$ + 'skip$ + { new.block + format.url output + format.lastchecked output + } + if$ +} + +FUNCTION {output.web.refs} +{ + new.block + 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 = <IN>) && ($line !~ /{/)) { + print OUT $line; + } + while (defined ($line) && bracematcher($line) > 0) { + print OUT $line; + $line = <IN>; + } + print OUT "$line\n"; # print out terminating \} (assumed + # alone on the line) +} diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.pdf b/Master/texmf-dist/doc/latex/urlbst/urlbst.pdf Binary files differnew file mode 100644 index 00000000000..5ff76111f17 --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst.pdf diff --git a/Master/texmf-dist/doc/latex/urlbst/urlbst.tex b/Master/texmf-dist/doc/latex/urlbst/urlbst.tex new file mode 100644 index 00000000000..2554f08b5cb --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst.tex @@ -0,0 +1,255 @@ +\documentclass[a4paper]{article} + +\title{The \texttt{urlbst} package} +\author{Norman Gray\\\texttt{<http://nxg.me.uk>}} +\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 new file mode 100644 index 00000000000..a063aca4abf --- /dev/null +++ b/Master/texmf-dist/doc/latex/urlbst/urlbst.tex.in @@ -0,0 +1,255 @@ +\documentclass[a4paper]{article} + +\title{The \texttt{urlbst} package} +\author{Norman Gray\\\texttt{<http://nxg.me.uk>}} +\date{Version @PACKAGE_VERSION@, @RELEASEDATE@} + +%\usepackage{times} +\usepackage{url} +\usepackage{hyperref} + +% Not long enough to make it useful to number sections +\setcounter{secnumdepth}{0} + +% Squeeze a bit more on to the page +%\addtolength\textwidth{1cm} +%\addtolength\oddsidemargin{-0.5cm} + +\makeatletter +% Easy verbatim mode +\catcode`\|=\active +\def|{\begingroup \let\do\@makeother \dospecials \verbatim@font \doverb} +\def\doverb#1|{#1\endgroup} + +\renewcommand{\verbatim@font}{\normalfont\small\ttfamily} +\makeatother + +\newcommand{\ub}{\package{urlbst}} +\newcommand{\BibTeX}{Bib\TeX} +\newcommand{\package}[1]{\texttt{#1}} +\newcommand{\btfield}[1]{\textsf{#1}} + +\begin{document} +\maketitle + +The \ub\ package consists of a Perl script which edits \BibTeX\ style +files (|.bst|) to add a \btfield{webpage} entry type, and which +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} |