summaryrefslogtreecommitdiff
path: root/biblio/bibtex/contrib/urlbst/urlbst.tex
diff options
context:
space:
mode:
Diffstat (limited to 'biblio/bibtex/contrib/urlbst/urlbst.tex')
-rw-r--r--biblio/bibtex/contrib/urlbst/urlbst.tex145
1 files changed, 111 insertions, 34 deletions
diff --git a/biblio/bibtex/contrib/urlbst/urlbst.tex b/biblio/bibtex/contrib/urlbst/urlbst.tex
index 7743ce0564..a8d828e38f 100644
--- a/biblio/bibtex/contrib/urlbst/urlbst.tex
+++ b/biblio/bibtex/contrib/urlbst/urlbst.tex
@@ -1,8 +1,8 @@
\documentclass[a4paper]{article}
\title{The \texttt{urlbst} package}
-\author{Norman Gray\\\texttt{<http://nxg.me.uk>}}
-\date{Version 0.8, 2019 July 1}
+\author{Norman Gray\\\texttt{<https://nxg.me.uk>}}
+\date{Version 0.9, 2022 December 1}
%\usepackage{times}
\usepackage{url}
@@ -54,21 +54,83 @@ The added fields are:
\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
+ (see \url{https://arxiv.org}); and
\item \btfield{pubmed} for a reference's PubMed identifier
(\textsc{PMID}, see \url{http://pubmed.gov}).
\end{itemize}
-Usage is simple:
+The script's home page is \url{https://purl.org/nxg/dist/urlbst}
+(\textbf{please quote this rather than the URL it redirects to}).
+It is on CTAN at \url{https://ctan.org/pkg/urlbst}.
+The code repository is at \url{https://heptapod.host/nxg/urlbst}.
+
+
+\section{Usage}
+Command line:
\begin{verbatim}
-% urlbst [--eprint] [--doi] [--pubmed]
- [--nohyperlinks] [--inlinelinks] [--hypertex] [--hyperref]
+% urlbst [--setting key=value] [--literal key=value]
[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.
+
+There are a number of settings which can be applied on the
+command-line, to adjust the support in the generated style file. See
+the following tables for the (current) list, and \texttt{urlbst --setting help}
+and \texttt{urlbst --literal help}. Some of these can be alternately
+set with particular options as shown in Table~\ref{t:options}. Each
+of these options sets a flag in the generated \texttt{.bst} file, but
+you should feel free to adjust/hack these flags by editing the generated
+file (for example |#0 'adddoi :=| will disable generation of DOI
+links; don't blame me for the eccentric \texttt{.bst} syntax).
+
+\begin{table}
+ \begin{tabular}{lll}
+ setting&description&default\\
+ \hline
+inlinelinks & 0=URLs explicit; 1=URLs attached to titles & 0\\
+addpubmed & 0=no PUBMED resolver; 1=include it & 1\\
+addeprints & 0=no eprints; 1=include eprints & 1\\
+hrefform & 0=no crossrefs; 1=hypertex hrefs; 2=hyperref hrefs & 0\\
+adddoi & 0=no DOI resolver; 1=include it & 1\\
+doiform & 0=with href; 1=with |\doi{}| & 0\\
+ \end{tabular}
+ \caption{Defined settings}
+\end{table}
+\begin{table}
+ \begin{tabular}{lll}
+ literal&description&default\\
+ \hline
+urlintro & prefix before URL & URL: \\
+pubmedprefix & prefix before PUBMED ref & PMID:\\
+pubmedurl & prefix to make URL from PMID \\
+ && \multicolumn1r{\llap{http://www.ncbi.nlm.nih.gov/pubmed/}}\\
+eprintprefix & prefix printed before eprint ref & arXiv:\\
+linktextstring & anonymous link text & [link]\\
+citedstring & label in `lastchecked' remark & cited \\
+eprinturl & prefix to make URL from eprint ref & https://arxiv.org/abs/\\
+doiurl & prefix to make URL from DOI & https://doi.org/\\
+doiprefix & printed text to introduce DOI & doi:\\
+onlinestring & label that a resource is online & online\\
+ \end{tabular}
+\caption{Literal strings for inclusion in the generated file}
+\end{table}
+
+\begin{table}
+ \begin{tabular}{ll}
+ option & setting\\
+ \hline
+ \texttt{--[no]eprint} & addeprints\\
+ \texttt{--[no]doi} & adddoi\\
+ \texttt{--nohyperlinks} & hrefform=0\\
+ \texttt{--hyper[tex/ref]} & hrefform=1/2\\
+ \texttt{--inlinelinks} & inlinelinks\\
+ \end{tabular}
+ \caption{Backward-compatibility options\label{t:options}}
+\end{table}
+
For example:
\begin{verbatim}
% urlbst --eprint bibstyle.bst
@@ -78,39 +140,36 @@ 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
+If the setting \texttt{addeprint} is true (ie, 1), then we switch on support for
+\btfield{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
+\url{https://arxiv.org/help/faq/references}. If the option
+\texttt{adddoi} is true, we include support for a \btfield{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
+\url{https://doi.org/}. And if \texttt{addpubmed} is true, we include
+support for a \btfield{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.
+The genereated .bst file may include support for hyperlinks where
+appropriate, in the generated entries in the bibliography. If the
+\texttt{hrefform} setting is zero, this is suppressed, and it if is~1
+or~2, the support is include using Hyper\TeX\ (see
+\url{https://arxiv.org/hypertex/#implementation}), supported by xdvi,
+dvips and others, or the \package{hyperref} package, respectively. 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
+\texttt{--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
+entry, linked to the corresponding URL. If the \texttt{inlinelinks}
+setting is true, 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
+no sense to specify \texttt{inlinelinks} with \texttt{hrefform=0}, 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;
@@ -137,7 +196,7 @@ 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
+\texttt{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
@@ -146,7 +205,10 @@ 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).
+to Eric Chamberland for this suggestion). A slightly more generic
+approach is to apply the setting \texttt{doiform=1}, which will
+generate DOIs wrapped in the macro |\doi{...}|. This allows you to
+supply a generic |\doi| macro to format them as you desire.
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
@@ -293,6 +355,20 @@ to Katrin Leinweber for the pull request which fixed the format of DOI
references.
\begin{description}
+\item[\textbf{0.9, 2022 December 1}]\relax
+\begin{itemize}
+ \item Changed repository location to heptapod\footnote{\url{https://heptapod.host/nxg/urlbst}}
+ (when Bitbucket dropped support for Mercurial).
+ The issue links below, pointing to Bitbucket, will therefore no
+ longer work.
+ \item Refactoring of the mechanism for configuring the generated
+ |.bst| file, specifically adding the
+ |--setting| option.
+ \item Added the |doiform| setting to generate DOIs wrapped
+ in |\doi{...}|.
+\end{itemize}
+
+
\item[\textbf{0.8, 2019 July 1}]\relax
\begin{itemize}
\item The presence of a preexisting |format.doi|,
@@ -309,8 +385,9 @@ code contributed by Katrin Leinweber\footnote{\url{https://bitbucket.org/nxg/url
\item[0.7, 2011 July 20]\relax
-Add |--nodoi|, |--noeprints| and |--nopubmed| options (which defaulted
-on, and couldn't otherwise be turned off)
+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|.