diff options
author | Norbert Preining <norbert@preining.info> | 2022-12-05 03:03:23 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2022-12-05 03:03:23 +0000 |
commit | 673717f7c662dd135f63b61c1da1ecd59bcdbe90 (patch) | |
tree | 9fe13f30ece99ab02f375cefab300a65b069560c /biblio/bibtex/contrib/urlbst/urlbst.tex | |
parent | b153d9b098596910fb2be9311f13c4415233c2a2 (diff) |
CTAN sync 202212050303
Diffstat (limited to 'biblio/bibtex/contrib/urlbst/urlbst.tex')
-rw-r--r-- | biblio/bibtex/contrib/urlbst/urlbst.tex | 145 |
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|. |