New Guidelines for DOI Linking and Display

Crossref_Logo_Stacked_RGB_SMALL.png

For sometime I have been collecting digital object identifiers (DOIs) in my BibTeX entries, as described in this blog post. When I use my own BST file to format the references BibTeX creates hyperlinks to the published source via the DOI. If I use the the SIAM BST file the DOI is instead displayed as part of the reference.

The Crossref organization (which provides DOIs) has recently issued revised guidelines on the display of DOIs. Up until now, DOIs have typically been displayed as, for example, 10.1137/130920137, and linked to as http://dx.doi.org/10.1137/16M1057577. The new guidelines say that the link should be https://doi.org/10.1137/16M1057577 and that it should always be displayed in this form, as a full URL. Note that the “dx” part of the URL has gone, and “https” has replaced “http”.

The main reason for the change is that the pure DOI on its own is not much use, as it can’t be clicked on or pasted into a browser address bar without first adding the https://doi.org/ prefix. Additionally, https provides more secure browsing than http, and Google gives a small ranking boost to sites that use https.

Crossmark states that the old http://dx.doi.org/10.1137/16M1057577 form of URL will continue to work forever.

I have updated my BST file myplain2-doi.bst in this GitHub repository, which contains a BibTeX bibliography for all my outputs, so that it produces links in the required form.

SIAM has updated the BST file in its macro packages to implement the new guidelines.

Managing BibTeX Files with Emacs

Here are a couple of tips on exploiting Emacs when working with BibTeX databases. I do not use a BibTeX database manager (though I have tried Jabref). I prefer to edit my bib files entirely within Emacs, and have had no trouble doing so even with my largest database of around 6800 entries.

1. Cleaning Downloaded Bib Entries

Back in the 1980s and 1990s BibTeX users had little choice but to create bib entries from scratch. Nowadays most journal websites have an “export citation” option that allows you to download a bib entry for a paper you are looking at. Unfortunately, these bib entries are of widely variable quality and are almost never entirely correct. What’s more, they will not match your own house style as regards ordering of fields and use of abbreviations. A great help in reformatting bib entries is the bibtex-clean-entry command in the BibTeX-mode of Emacs. I use it to

  • remove unwanted blank lines and spaces,
  • put the fields in the order I prefer,
  • change field delimiters from curly brackets to quotes,
  • delete delimiters around numerical fields,
  • change double dashes to single dashes in page ranges (BibTeX will convert single dashes to double as necessary),
  • change the entry type and field names to lower case,
  • set the indentation of field to two spaces.

These and other aspects of the formatting are customizable. Here is an example of a bib entry downloaded from JSTOR.

@article{10.2307/2323313,
 ISSN = {00029890, 19300972},
 URL = {http://www.jstor.org/stable/2323313},
 author = {Dan Scott, Donald R. Peeples},
 journal = {The American Mathematical Monthly},
 number = {7},
 pages = {651-653},
 publisher = {Mathematical Association of America},
 title = {A Constructive Proof of the Partial Fraction Decomposition},
 volume = {95},
 year = {1988}
}

After I hit C-c C-c in Emacs the entry is transformed to

@article{10.2307/2323313,
  author = "Dan Scott, Donald R. Peeples",
  title = "A Constructive Proof of the Partial Fraction Decomposition",
  journal = "The American Mathematical Monthly",
  volume = 95,
  number = 7,
  pages = "651-653",
  year = 1988,
  issn = "00029890, 19300972",
  url = "http://www.jstor.org/stable/2323313",
  publisher = "Mathematical Association of America"
        }

Further work is needed (such as replacing the comma by “and” in the author field), but the entry is now much closer to the format I require.

BibTeX-mode is not perfect. While bibtex-clean-entry can even generate a new key for the entry, I have not been able to get it to match my key-generating algorithm. And I have not found a way to make bibtex-clean-entry delete fields (such as issn, or publisher for the article type) that I do not use.

If you would like to see how I customized BibTeX-mode, take a look at the .emacs and .emacs-custom_windows files in my dot-emacs setup.

2. Bib Search and PDF Display with Helm-BibTeX

The Emacs RefTeX package provides some useful features for handling citations within a \LaTeX document, providing an intelligent link between the \LaTeX document and the relevant BibTeX databases. One thing it does not do is enable easy access to PDF files corresponding to bib entries. The Helm-BibTeX package can do this and much more.

To explain how I use Helm-BibTeX, suppose I have the following lines in my dot emacs.

(setq helm-bibtex-bibliography '("~/texmf/bibtex/bib/la.bib"
                                 "~/texmf/bibtex/bib/njhigham.bib"
                                 ))

(setq helm-bibtex-library-path '("~/pdf_papers" "~/pdf_books"))

These tell Helm-BibTeX to look in the first path for bib files and in the second path for PDF files whose names match a specified bib key.

If I type M-x helm-bibtex and type dongarra in the minibuffer then all bib entries in la.bib and njhigham.bib containing dongarra in the author or title fields are displayed, one per line. I can narrow the list down by typing a space and then another search term. Hitting tab displays several options, which include options to insert a \cite command for the item under the cursor, to insert a formatted reference for the item under the cursor, and to go to that entry in the bib file. The fourth column shows a looped square symbol (⌘) that indicates the presence of a matching PDF file. Hitting enter (or f1, or Ctrl-j) opens the PDF file in the default PDF application.

Here is Helm-BibTeX in action. helm-bibtex.jpg

Helm-BibTeX relies on the Helm package, which provides a powerful framework for incremental completion and selection narrowing.

Three BibTeX Tips

BibTeX is an important part of my workflow in writing papers and books. Here are three tips for getting the most out of it.

1. DOI and URL Links from Bibliography Entries

A digital object identifier (DOI) provides a persistent link to an object on the web, via the server at http://dx.doi.org. Most scholarly journals now assign DOIs to papers, and many papers from the past have been retrofitted with them. Books can also have DOIs, as in SpringerLink or the SIAM ebook program.

It is very convenient for a reader of a PDF document to be able to access items from the bibliography by clicking on part of the item. The links can be constructed from a DOI, and if one does not exist a URL can be used instead. How can we produce such links automatically with BibTeX? Simply add fields doi or url and use an appropriate BibTeX style (BST) file. I’m not aware of any standard BST file that handles these fields, so I modified my own BST file using these tips. The result, myplain2-doi.bst, is available in this GitHub repository. Example bib entries that work with it are as follows.

@article{ahr13,
  author = "Awad H. Al-Mohy and Nicholas J. Higham and Samuel D. Relton",
  title = "Computing the {Fr{\'e}chet} Derivative of the Matrix Logarithm
           and Estimating the Condition Number",
  journal = "SIAM J. Sci. Comput.",
  volume = 35,
  number = 4,
  pages = "C394-C410",
  year = 2013,
  doi = "10.1137/120885991",
  created = "2012.07.05",
  updated = "2013.08.06"
}

@article{hpp09,
  author = "Horn, Roger A. and Piazza, Giuseppe and Politi, Tiziano",
  title = "Explicit Polar Decompositions of Complex Matrices",
  journal = "Electron. J. Linear Algebra",
  volume = "18",
  pages = "693-699",
  year = "2009",
  url = "https://eudml.org/doc/233457",
  created = "2013.01.02",
  updated = "2015.07.15"
}

The journal in which the second example appears is one that does not itself provide DOIs or URLs for papers. However, the European Digital Mathematics Library provides URLs for this journal, so I have used the appropriate one from there.

My BST file hyperlinks the title of each item to the corresponding DOI or URL. For an example of the style in use, see the typeset version of njhigham.bib, for which here is a direct link. An alternative style is simply to print the DOI or URL with a hyperlink.

2. Web page from Bib File via BibBase

Once you have made a bib file of a group of publications a natural question is how you can automatically generate a web page that displays the publications in an easily browsable format. A great way to do this is with BibBase. You simply point BibBase at your online bib file and it generates some JavaScript, PHP, or iFrame code. When you include that code in your a web page it displays the Bib entries sorted by year, with each DOI or URL field made clickable and each BibTeX entry revealable. A menu allows sorting by author, type, or year and the list can be folded. My bib file njhigham.bib formatted by BibBase is available here.

BibBase is free to use. It was first released a few years ago and is still being developed, with improved support for LaTeX and for special characters added recently. Keep up to date with developments by following the BibBase Twitter feed.

Here are two screenshots. The first shows part of the default layout, with outputs from 2015 folded and one bib entry revealed. bibbase1.jpg

The second screenshot shows part of the list ordered by author. bibbase2.jpg

3. Bib Entry from DOI

If you happen to know the DOI of a paper and want to obtain a bib entry, go to the doi2bib service and type in your DOI. For further information see this blog post and follow the doi2bib Twitter feed.