summaryrefslogtreecommitdiff
path: root/biblio/bibtex/contrib/urlbst/urlbst.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /biblio/bibtex/contrib/urlbst/urlbst.tex
Initial commit
Diffstat (limited to 'biblio/bibtex/contrib/urlbst/urlbst.tex')
-rw-r--r--biblio/bibtex/contrib/urlbst/urlbst.tex398
1 files changed, 398 insertions, 0 deletions
diff --git a/biblio/bibtex/contrib/urlbst/urlbst.tex b/biblio/bibtex/contrib/urlbst/urlbst.tex
new file mode 100644
index 0000000000..7743ce0564
--- /dev/null
+++ b/biblio/bibtex/contrib/urlbst/urlbst.tex
@@ -0,0 +1,398 @@
+\documentclass[a4paper]{article}
+
+\title{The \texttt{urlbst} package}
+\author{Norman Gray\\\texttt{<http://nxg.me.uk>}}
+\date{Version 0.8, 2019 July 1}
+
+%\usepackage{times}
+\usepackage{url}
+\usepackage{hyperref}
+
+% Not long enough to make it useful to number sections
+\setcounter{secnumdepth}{0}
+
+% Squeeze a bit more on to the page
+%\addtolength\textwidth{1cm}
+%\addtolength\oddsidemargin{-0.5cm}
+
+\makeatletter
+% Easy verbatim mode
+\catcode`\|=\active
+\def|{\begingroup \let\do\@makeother \dospecials \verbatim@font \doverb}
+\def\doverb#1|{#1\endgroup}
+
+\renewcommand{\verbatim@font}{\normalfont\small\ttfamily}
+\makeatother
+
+\newcommand{\ub}{\package{urlbst}}
+\newcommand{\BibTeX}{Bib\TeX}
+\newcommand{\package}[1]{\texttt{#1}}
+\newcommand{\btfield}[1]{\textsf{#1}}
+
+\begin{document}
+\maketitle
+
+The \ub\ package consists of a Perl script which edits \BibTeX\ style
+files (|.bst|) to add a \btfield{webpage} entry type, and which adds a
+few new fields -- notably including \btfield{url} --
+to all other entry types. The distribution includes preconverted
+versions of the four standard \BibTeX\ |.bst| style files.
+
+It has a different goal from Patrick Daly's \package{custom-bib}
+package~\cite{url:daly} -- that is intended to create a \BibTeX\ style
+|.bst| file from scratch, and supports \btfield{url} and
+\btfield{eprint} fields. This package, on the other hand, is intended
+for the case where you already have a style file that works (or at
+least, which you cannot or will not change), and edits it to add the
+new \btfield{webpage} entry type, plus the new fields.
+
+The added fields are:
+\begin{itemize}
+\item \btfield{url} and \btfield{lastchecked}, to associate a URL with
+ a reference, along with the date at which the URL was last checked
+ to exist;
+\item \btfield{doi}, for a reference's DOI
+ (see \url{https://doi.org});
+\item \btfield{eprint}, for an arXiv eprint reference
+ (see \url{http://arxiv.org}); and
+\item \btfield{pubmed} for a reference's PubMed identifier
+ (\textsc{PMID}, see \url{http://pubmed.gov}).
+\end{itemize}
+
+Usage is simple:
+\begin{verbatim}
+% urlbst [--eprint] [--doi] [--pubmed]
+ [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref]
+ [input-file [output-file]]
+\end{verbatim}
+where the |input-file| is an existing |.bst| file, and
+the |output-file| is the name of the new style file to be
+created. If either file name is missing, the default is the
+standard input or standard output respectively.
+For example:
+\begin{verbatim}
+% urlbst --eprint bibstyle.bst
+\end{verbatim}
+would convert the style file \texttt{bibstyle.bst}, including support
+for e-prints, and sending the result to the standard output (ie, the
+screen, so it would more useful if you were to either redirect this to
+a file or supply the output-file argument).
+
+If the option |--eprint| is present, then we switch on support for
+\texttt{eprint} fields in the modified .bst file, with a citation
+format matching that recommended in
+\url{http://arxiv.org/help/faq/references}. If the option
+|--doi| is present, we include support for a |doi| field, referring
+to a Digital Object Identifier (DOI) as standardised by
+\url{http://www.doi.org/}. And if |--pubmed| is present, we include
+support for a |pubmed| field, referring to a PubMed identifier as
+supported at \url{http://www.pubmed.gov}.
+
+If either of the |--hypertex| or |--hyperref| options is present, then
+the generated .bst file includes support for hyperlinks in the
+generated eprint entries in the bibliography, with the format being
+either Hyper\TeX\ (see
+\url{http://arxiv.org/hypertex/#implementation}), supported by xdvi,
+dvips and others, or using the support available from the
+\package{hyperref} package. These options have no effect unless one
+of the |--eprint|, |--doi|, |--pubmed| or |--inlinelinks| options is given:
+when URLs are included
+in the bibliography, they are written out using the |\url{...}|
+command. The \package{hyperref} support is more generic, and more
+generally supported, and so you should choose this unless you have a
+particular need for the Hyper\TeX\ support. The |--nohyperlinks|
+option, which is present by default, suppresses all hyperlinking.
+
+By default, any URL field is displayed as part of the bibliography
+entry, linked to the corresponding URL via the mechanism managed by
+the |--hypertex| and |--hyperref| options. If the |--inlinelinks|
+option is present, however, then the URL is not displayed in the
+printed entry, but instead a hyperlink is created, linked to suitable
+text within the bibliography entry, such as the citation title. This
+option does not affect the display of eprints, DOI or PubMed fields. It makes
+no sense to specify |--inlinelinks| with |--nohyperlinks|, and the
+script warns you if you do that, for example by failing to specify one
+of the link-style options. This option is (primarily) useful if
+you're preparing a version of a document which will be read on-screen;
+the point of it is that the resulting bibliography is substantially
+more compact than it would otherwise be.
+
+The support for all the above behaviours is always included in the
+output file. The options instead control only whether the various
+behaviours are enabled or disabled, and if you need to alter these,
+you may do so by editing the generated |.bst| file and adjusting
+values in the |{init.urlbst.variables}| function, where indicated.
+
+The generated references have URLs inside |\url{...}|. The best
+way to format this this is with the \package{url} package
+(see~\cite{texfaq} for pointers), but as a poor alternative, you can
+try |\newcommand{\url}[1]{\texttt{#1}}|. The \package{hyperref}
+package automatically processes |\url{...}| in the correct way to
+include a hyperlink, and if you have selected \package{hyperref}
+output, then nothing more need be done. If you selected Hyper\TeX\
+output, however, then the script encloses the |\url| command in an
+appropriate Hyper\TeX\ special.
+
+When the style file generates a link for DOIs, it does so by
+prepending the string \texttt{https://doi.org/} to the DOI. This is
+generally reasonable, but some DOIs have characters in them which are
+illegal in URLs, with the result that the resulting
+\texttt{dx.doi.org} URL doesn't work. The only real way of resolving
+this is to write a URL-encoding function in the style-file
+implementation language, but while that would doubtless be feasible in
+principle, it would be hard and very, very, ugly. The only advice I
+can offer in this case is to rely on the fact that the DOI will still
+appear in the typeset bibliography, and that users who would want to
+take advantage of the DOI will frequently (or usually?) know how to
+resolve the DOI when then need to. As a workaround, you could include
+a URL-encoded DOI URL in the \btfield{url} field of the entry (thanks
+to Eric Chamberland for this suggestion).
+
+The \ub\ script works by spotting patterns and characteristic function
+names in the input |.bst| file. It works as-is in the case of the
+four standard \BibTeX\ style files |plain.bst|, |unsrt.bst|,
+|alpha.bst| and |abbrv.bst|. It also works straightforwardly for
+many other style files -- since many of these are derived from, or at
+least closely inspired by, the standard ones -- but it does not
+pretend that it can do so for all of them. In some cases, such as the
+style files for the \package{refer} or \package{koma-script} packages,
+the style files are not intended to be used for formatting; others are
+sufficiently different from the standard files that a meaningful edit
+becomes impossible. For the large remainder, however, the result of
+this script should need only relatively minor edits before being
+perfectly usable.
+
+\section{New \texttt{.bib} entry and field types}
+
+The new entry type \btfield{webpage} has required fields
+\btfield{title} and \btfield{url}, and optional fields
+\btfield{author}, \btfield{editor}, \btfield{note}, \btfield{year},
+\btfield{month} and \btfield{lastchecked}. The \btfield{url} and
+\btfield{lastchecked} fields are new, and are
+valid in other entry types as well: the first, obviously, is the URL
+which is being cited, or which is being quoted as an auxiliary source
+for an article perhaps; the second is the date when you last checked
+that the URL was there, in the state you quoted it; this is necessary
+since some people, heedless of the archival importance of preserving
+the validity of URLs, indulge in the vicious practice of reorganising
+web pages and destroying links. For the case of the \btfield{webpage} entry
+type, the \btfield{editor} field should be used for the `maintainer'
+of a web page.
+
+For example, in Figure~\ref{f:ex} we illustrate two potential |.bib|
+file entries. The \texttt{@webpage} entry type is the new type
+provided by this package, and provides reference information for a
+webpage; it includes the new \texttt{url} and \texttt{lastchecked}
+fields. There is also an example of the standard \texttt{@book} entry
+type, which now includes the \texttt{url} and \texttt{lastchecked}
+fields as well. The difference between the two references is that in
+the \texttt{@book} case it is the book being cited, so that the
+\texttt{url} provides extra information; in the \texttt{@webpage} case
+it is the page itself which is of interest. You use the new |eprint|,
+|doi| and |pubmed| fields similarly, if the bibliographic item in
+question has an e-print, DOI or PubMed reference.
+\begin{figure}
+\begin{verbatim}
+@Manual{w3chome,
+ url = {http://www.w3.org},
+ title = {The World Wide Web Consortium},
+ year = 2009,
+ lastchecked = {26 August 2009}}
+
+@Book{schutz,
+ author = {Bernard Schutz},
+ title = {Gravity from the GroundUp},
+ publisher = {Cambridge University Press},
+ year = {2003},
+ url = {http://www.gravityfromthegroundup.org/},
+ lastchecked = {2008 June 16}}
+\end{verbatim}
+\caption{\label{f:ex}The new \texttt{@webpage} entry type, and the \texttt{url}
+ field in action}
+\end{figure}
+
+How do you use this in a document? To use the the
+\texttt{alphaurl.bst} style -- which is a pre-converted version of the
+standard \texttt{alpha.bst} style, included in the \texttt{urlbst}
+distribution -- you simply make sure that \texttt{alphaurl.bst} is in
+your BibTeX search path (use the command \texttt{kpsepath bst} to find
+this path and \texttt{kpsewhich alphaurl.bst} to confirm that BibTeX
+can find it) and add |\bibliographystyle{alphaurl}| to your \LaTeX\ document.
+
+\section{Sources}
+
+There are various sources which suggest how to format references to
+web pages. I have followed none specifically, but fortunately they do
+not appear to materially disagree.
+
+ISO-690~\cite{url:iso690} is a formal standard for this stuff. Walker
+and Taylor's \emph{Columbia Guide to Online Style}~\cite{walker06}
+provides extensive coverage (but is only available on dead trees).
+There are two style guides associated with the APA, namely
+the published APA style
+guide~\cite{apastyle} (a paper-only publication, so should be
+ignored by all, if there's any justice in the world), and what appears
+to be the 1998 web-citation proposal for that~\cite{url:weapas}, which
+also includes some useful links.
+The TeX FAQ~\cite{texfaq} has both practical advice and pointers to other sources.%
+\footnote{Emory University's Goizueta Business Library once had a collection of
+useful links on this topic, but they've whimsically changed the URL at least twice
+since I first distributed \ub, and I've got fed up fixing their broken link.}
+
+\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 `ijvm' for code contributions in the |urlbst| script;
+%% to Pawe\l{} Widera for the suggestion to use |\path| when formatting DOIs;
+%% to Michael Giffin for the suggestion to include PubMed URLs;
+%% to Katrin Leinweber for the pull request which fixed the format of DOI
+%% references.
+
+\section{Acknowledgements, and release notes}
+
+%%% include:release-notes.tex
+
+
+Thanks are due to many people for suggestions and requests:
+to Jason Eisner for suggesting the |--inlinelinks| option;
+to ‘ijvm’ for code contributions in the |urlbst| script;
+to Paweł Widera for the suggestion to use |\path| when formatting DOIs;
+to Michael Giffin for the suggestion to include PubMed URLs;
+to Katrin Leinweber for the pull request which fixed the format of DOI
+references.
+
+\begin{description}
+\item[\textbf{0.8, 2019 July 1}]\relax
+\begin{itemize}
+\item The presence of a preexisting |format.doi|,
+|format.eprint| or |format.pubmed| function is
+now detected, and warned about. The resulting |.bst| file
+might still require some manual editing.
+Resolves issue 8\footnote{\url{https://bitbucket.org/nxg/urlbst/issue/8}}.
+\item Clarified licences (I hope).
+\item Adjust format of DOI resolver.
+Resolves issue 11\footnote{\url{https://bitbucket.org/nxg/urlbst/issue/11}},
+thanks to
+code contributed by Katrin Leinweber\footnote{\url{https://bitbucket.org/nxg/urlbst/pull-requests/1/}}.
+\end{itemize}
+
+
+\item[0.7, 2011 July 20]\relax
+Add |--nodoi|, |--noeprints| and |--nopubmed| options (which defaulted
+on, and couldn't otherwise be turned off)
+
+\item[0.7b1, 2011 March 17]\relax
+Allow parameterisation of literal strings, with option |--literal|.
+
+\item[0.6-5, 2011 March 8]\relax
+Adjust support for inline links (should now work for arXiv, DOI and Pubmed)
+
+\item[0.6-4, 2009 April 28]\relax
+Work around BibTeX linebreaking bug (thanks to Andras Salamon for the bug report).
+
+\item[0.6-3, 2009 April 19]\relax
+Fix inline link generation (thanks to Eric Chamberland for the bug report).
+
+\item[0.6-2, 2008 November 17]\relax
+We now turn on inlinelinks when we spot format.vol.num.pages,
+which means we include links for those styles which don't include a
+title in the citation (common for articles in physical science styles,
+such as aip.sty).
+
+\item[0.6-1, 2008 June 16]\relax
+Fixed some broken links to the various citation standards
+(I think in this context this should probably \emph{not} be happening, yes?).
+The distributed |*url.bst| no longer have the
+|--inlinelinks| option turned on by default.
+
+\item[\textbf{0.6, 2007 March 26}]\relax
+\begin{itemize}
+\item 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.
+
+\item Incorporate hyperref bugfixes from Paweł Widera.
+
+\item 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.
+
+\item Reworked |inlinelinks| support; should now be more
+robust. Incorporate hyperref bugfixes from Paweł Widera.
+
+\item 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.
+\end{itemize}
+
+
+\item[0.5.2, 2006 September 6]\relax
+Another set of documentation-only changes, hopefully clarifying
+installation.
+
+\item[0.5.1, 2006 January 10]\relax
+No functionality changes. Documentation and webpage changes only,
+hopefully clarifying usage and configuration
+
+\item[\textbf{0.5, 2005 June 3}]\relax
+Added support for Digital Object Identifiers (DOI) fields in
+bibliographies.
+
+\item[0.4-1, 2005 April 12]\relax
+Documentation improvements -- there are now examples in the help text!
+
+\item[\textbf{0.4, 2004 December 1}]\relax
+Bug fixes: now compatible with mla.bst and friends.
+Now uses |./configure| (optionally). Assorted reorganisation.
+
+\item[\textbf{0.3, 2003 June 4}]\relax
+Added |--eprint|, |--hypertex| and |--hyperref| options.
+
+\item[\textbf{0.2, 2002 October 23}]\relax
+The `editor' field is now supported in the webpage entry type. Basic
+documentation added.
+
+\item[\textbf{0.1, 2002 April}]\relax
+Initial version
+\end{description}
+
+\bibliography{urlbst}
+\bibliographystyle{plainurl}
+
+\end{document}