This Emacs package provides a way to show retraction information for citations and citation data at point. This is done using the Crossref REST API (https://www.crossref.org/documentation/retrieve-metadata/rest-api/) (experimental version until the feature is available on the regular version). At the moment, it explicitly supports detection of DOI from `ebib' (http://joostkremers.github.io/ebib/) as well as `bibtex-mode'. It is possible to show retraction information as a Universal Sidecar Section (https://git.sr.ht/~swflint/emacs-universal-sidecar), and support for `eldoc' is forthcoming. ;; Configuration For general use, there is one major variable that must be customized. `retraction-viewer-crossref-email' should be set to your email address (or an email address that will be checked, see https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service). In particular, it may be helpful to set it to `user-mail-address', as follows. (setopt retraction-viewer-crossref-email user-mail-address) ;;; Notice Formatting It is possible to customize how notices are formatted using the `retraction-viewer-notice-format' variable. The % escapes are defined in `retraction-viewer-format-spec', which can be customized as well. The `retraction-viewer-format-spec' is an alist of (unique) characters to either variable names or functions taking a retraction notice message. In either case, they should return a string, or nil (which will become the empty string). Retraction notice data is a direct translation from the JSON output of the CrossRef REST API. As it is at present using the experimental version of the API keys are subject to change. ;;; Performance Tuning Additionally, there are two variables which can be used to tune performance: `retraction-viewer-connect-timeout' and `retraction-viewer-timeout'. These can either be a number of seconds, or nil. If nil, the variables `plz-connect-timeout' and `plz-timeout', respectively are used to provide the values. ;;; Eldoc Configuration Retraction notices can also be showed using `eldoc', by enabling both `eldoc-mode' and `retraction-viewer-eldoc-mode'. Note, this operates asynchronously, and will format notices using `retraction-viewer-notice-format'. Additionally, collecting retraction data is subject to collecting a DOI (see `retraction-viewer-get-doi-functions' described below). ;;; DOI Getters Finally, it's possible to configure how the "current DOI" is detected using the `retraction-viewer-get-doi-functions' hook. The functions are evaluated until one returns non-nil. By default, it will get the DOI from ebib if called in an ebib buffer (`retraction-viewer-get-ebib-doi'), from the bibtex entry-at-point if within a bibtex buffer (`retraction-viewer-get-bibtex-doi'), from the currently shown elfeed entry if in an `elfeed-show' buffer (`retraction-viewer-get-elfeed-doi'), or if point is on a DOI (see `retraction-viewer-doi-regexp'). Additional functions can be written to select a current DOI, and should operate by: a) not adjusting match data; b) not adjust point/mark; c) not adjust narrowing, and d) fail early (i.e., return nil ASAP). ;; Use as a Library Additionally, `retraction-viewer' is intended to be a way for other packages to get retraction information and related data easily. To this end, there are three categories of functions it provides: DOI detection, retraction status, and notice formatting. DOIs can be detected using `retraction-viewer-current-doi' to determine if there is a DOI in the current context (whatever that may be given mode, etc.), for more information about how this can be extended, see above. Additionally, the `retraction-viewer-doi-at-point' can be used directly to determine if there is a DOI at point (using `retraction-viewer-doi-regexp'). The retraction status of a DOI can be determined with `retraction-viewer-doi-status', which will return a list of alists describing any retraction notices found in the RetractionWatch database. These alists are at present subject to change. Additionally, a callback, taking the status record can be passed as an optional second argument; for an example of use, see `retraction-viewer-eldoc-function'. Finally, retraction notices can be formatted easily using a format-string like construct using `retraction-viewer-format-notice', (see above section, "Notice Formatting" for more information). ;; Errors and Patches If you find an error, or have a patch to improve this package (or are able to add additional DOI getters), please send an email to ~swflint/emacs-utilities@lists.sr.ht.