Bibliographic Notes with the Citar-Denote Emacs Package
Peter Prevos |
2375 words | 12 minutes
Share this content
Taking notes about the articles and books you read is an essential part of intellectual life. Many note-taking systems can connect to a bibliographic database (such as a plain text BibTeX file, or external software such as Zotero). These databases are helpful when adding citations to your writings. Electronic bibliographies also help you to create and find notes related to your literature collection. and provide access to related materials, such as links to online sources and electronic versions of relevant books or articles.
The Citar-Denote Emacs package integrates the Citar bibliography package with the Denote note-taking system. Citar lets you browse and act on bibliographic data in BibTeX, BibLaTeX and JSON-CSL format. Denote is a is a versatile Emacs package for taking notes. Combining these two packages enables linking any note in your Denote collection to one or more bibliographic entries, providing a complete solution for documenting literature reviews. My article about taking notes with Emacs explains how to use Denote.
This article is part of Emacs Writing Studio, a book that explains how to use Emacs to undertake research and write and publish articles, books, and websites. Emacs Writing Studio is available as an e-book from your favourite retailer.
Emacs Writing Studio
A comprehensive guide for writers seeking to streamline their workflow using Emacs. The book covers everything from organising ideas and writing distraction-free to publishing in multiple formats. It’s perfect for both beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.
The source files of the book and EWS configuration are also freely available on GitHub.
To learn how to create and maintain a plain text bibliographic database in Emacs, read the article about BibTeX mode. The article about writing in Org mode explains how to add citations. This page explains how to use the Citar-Denote package, which integrates a Citar bibliography with your Denote notes.
Principles
A bibliographic note is a file that refers to one or more pieces of literature in your bibliography. The note and the entry in your literature database are intrinsically linked, making it easy to move between the two. Two types of relationships exist between your notes and your bibliography:
- Reference: Relates the whole file to one or more publication (a bibliographic note). Indicated by the reference line in the front matter and the
bibkeyword. - Citation: A citation inside a note mentions one or more publications. A citation relates a portion of a text to a publication.
The Citar-Denote package maintains a many-to-many relationship between your notes and your bibliographies. Each bibliographic entry can have one or more notes, and each note can reference one or more pieces of literature.
You can create several atomic notes for each publication or write a complete literature review of a collection of references within one note. You could, for example, create a note about each chapter of a book, or write a single literature review note for a collection of journal articles. You can use Citar and Denote which ever way best suits your workflow.
To enable references, we need a stable link between the collection of notes and the bibliography. The most common behaviour for bibliography managers in Emacs is that the filename for the relevant note includes the citation key (e.g. marcuse_1969_essay.org) to link it to the bibliography. However, Denote follows a strict naming convention, so we cannot use this approach to link notes and literature as it might contain characters that Denote disallows in its file names. The various citation system don't have strict naming conventions on citation keys, so we need to find another way to link literature to a note.
In Citar-Denote, the citation key is part of the front matter through the #+reference: keyword. Citar-Denote stores the relationship between citation keys and note files in a cache. The package regenerates this cache after you edit a bibliography file or call any Citar functions. Each bibliographic note uses the configurable bib file tag. This tag reduces the number of Denote files the system needs to track. The front matter for a bibliographic note would look something like this:
#+title: Marcuse: An Essay on Liberation
#+date: [2022-11-12 Sat 19:23]
#+filetags: :bib:culture:marketing:philosophy:
#+identifier: 20221112T192310
#+reference: marcuse_1969_essay
The Citar-Denote package also provides insight into citations used in the Denote directory, which uses the xref system. You can improve the search process by installing the faster ripgrep program and setting xref-search-program to ripgrep.
Create bibliographic notes
Open the Citar interface with C-c w b c (citar-create-note). The letters or icons at the start of the Citar menu indicate whether the entry has a link, note, attachment or is cited in the current buffer. Select the entry you want to create a note for, hit ENTER and follow the prompts.
If a note already exists and you have set the citar-open-always-create-notes variable to t, then you can create additional notes for this entry. Otherwise, Citar will open the exiting note.
Various configuration options are available to fine-tune determine how Emacs creates now bibliographic notes.
Default file type
You can create bibliographic notes for each file type that Denote supports: Org mode, two flavours of Markdown and plain text. Citar-Denote uses the default file type set by the denote-file-type variable, which you can override with citar-denote-file-type to use a different file type for bibliographic notes.
Bibliographic note title
The default name for a new note is the title of the bibliographic entry. You can modify this behaviour with the citar-denote-title-format variable. Four options are available:
title: Extract the title from the bibliographic item (default)author-year: Use citation format as "author(s) (year)" (or editors when no authors are defined)author-year-title: Concatenate the first two optionsfull: Full citation of the entry- Fallback option or
nil: The citation key
For example, using this citation: Coppa, Hass, Peck, Burger (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present, Palgrave Macmillan.
title: "Performing Magic on the Western Stage: From the Eighteenth Century to the Present".author-year: "Coppa et al. (2008)".author-year-title: "Coppa et al. (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present".full: "Coppa, Hass, Peck, Burger (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present, Palgrave Macmillan".nil: "coppa_2008_perf".
Using author-year for entries allows for some further configuration. For entries with more than one author, you can specify the maximum number of names with citar-denote-title-format-authors, which is one by default. When the number of defined authors is more than the number in the citation, "et al." is added to the end. When this variable exceeds the number of defined authors, all authors are listed. The default term between authors is "and", which can be changed by customising citar-denote-title-format-andstr.
For example, when using up to three authors and "&" as connecting term, the title for the example above becomes Or "Coppa, Hass & Peck et al. (2008)"
Bibliographic keywords
The bib file tag is added to every new bibliographic note. This tag minimises the search space when caching notes to accelerate the process. The citar-denote-keyword variable lets you change the tag to something else. For example, if you primay language is Welsh, you might want to change it to lly.
Changing the default requires updating all your existing bibliographic notes, because the package only recognises a single string. The change will come into effect the next time the package is loaded. The Denote-Explore package has a function to rename Denote keywords.
The citar-denote-use-bib-keywords variable lets you include keywords defined in the bibliography as Denote keywords. When set to a non-nil value, Citar-Denote extracts the available keywords from the BibTeX keywords field.
Subdirectory
If you prefer storing your bibliographic notes in a subdirectory of your Denote folder, then set the citar-denote-subdir variable to t. When this variable is non-nil, Denote asks for a subdirectory when creating a new bibliographic note. When this variable contains a string, then any new bibliographic notes are stored in the subdirectory that matches this name.
Signature
When the citar-denote-signature variable is non-nil, Denote will ask for a signature when creating a new bibliographic note. If you enter an empty line for a signature, then the citation key is used.
Please note that Denote changes or removes punctuation marks in the citation key to enforce compliance with its file naming convention. For example, when the citation key is einstein_1905, the signature becomes einstein=2005.
Create notes using templates
Denote allows you to create template for various types of notes. You could, for example, have standard headings for bibliographic notes, other headings for meta notes, or whatever else you might need.
To include templates in new bibliographic notes, set the citar-denote-template to non-nil and define a template.
The example below lets the user choose between a note that has two headings (Abstract and Review), or a plain note without any template content. The extensive Denote manual provides some more detailed information about using templates for all your notes.
(setq denote-templates
'((biblio . "* Abstract\n\n* Review")
(plain . nil)))Working with existing notes
Once you have some bibliographic notes you will want to access and modify them. You can access the attachments, links and other notes associated with the references from within via the Citar menu (citar-open), C-c w b o. Entries with a note are indicated with an N in the third column.
Open existing bibliographic notes
There are two entry points to find notes that relate to literature, either as a reference or as a citation.
Use citar-denote-open-note (C-c w b n) to open the Citar menu with only entries that have one or more associated notes. Select your target and hit ENTER.
Citar provides a list of resources for the selected entry: attachments, existing notes, links and an option to create an additional note. Select the note you seek, hit ENTER again and select the Denote file you want to open.
The previous function shows all literature that has one or more bibliographic note(s). The citar-denote-find-citation function (C-c w c f) lists all bibliographic entries cited inside your Denote collection, from where you can open the relevant note. Some of these will also have their own bibliographic note, indicated in the Citar menu sidebar.
Searching through all your notes for citations can take a moment, depending on the size of your digital garden.
Open attachments, links and notes
The citar-denote-dwim function (C-c w b d) provides access to the Citar menu from where you can open attachments, other notes, and links related to the citation references associated with the current Denote buffer.
Select the required bibliographic item when there is more than one reference. You can then select the attachment, link or note you like to access and hit ENTER, after which you select your link, note or attachment. Alternatively, you can also create a new note
Open bibliographic entry
The citar-denote-open-reference-entry function (C-c w b e) opens the bibliographic entry (BibTeX, BibLaTeX or CSL file) for a selected reference from where you can edit the bibliographic data.
Convert existing notes to bibliographic notes
The citar-denote-add-citekey function (C-c w b k) adds citation keys or converts an existing Denote file to a bibliographic note. When converting a regular Denote file, the function adds the bib keyword to the front matter and renames the file accordingly.
This function opens the Citar selection menu and adds the selected citation keys to the front matter. Use the TAB key to select multiple entries.
Remove references from bibliographic notes
You remove citation references with the citar-denote-remove-citekey command (C-c w b K). If more than one piece of literature is referenced, select the unwanted item in the minibuffer first. The bibliography keyword is also removed, and the file is renamed when removing the only reference.
Citation management
What is the point of building a bibliography without using each entry as a citation or a reference in a bibliographic note? The last two functions let you cite literature or create a new bibliographic note for any item not used in your Denote collection.
The citar-denote-nocite (C-c w b x) function opens the Citar menu and shows all items in your bibliography that are neither cited nor referenced. From there you can create a new bibliographic note, follow a link or read the file.
Configuration
The Emacs Writing Studio configuration builds on the C-c w prefix keys. Pressing C-c w b provides access to bibliographic commands using the keystroke completion menu provided by the Which Key package .
This configuration also sets a variable from the Citar package that allows you to create multiple notes for a bibliographic entry.
(use-package citar-denote
:custom
(citar-open-always-create-notes t)
:init
(citar-denote-mode)
:bind
(("C-c w b c" . citar-create-note)
("C-c w b n" . citar-denote-open-note)
("C-c w b x" . citar-denote-nocite)
("C-c w b k" . citar-denote-add-citekey)
("C-c w b K" . citar-denote-remove-citekey)
("C-c w b d" . citar-denote-dwim)
("C-c w b e" . citar-denote-open-reference-entry)))The source code for Citar-Denote is available on GitHub and the package is available through MELPA.
This page is a previous version of the manual. You can read the recent manual with C-h R citar-denote or evaluate (info "citar-denote")
Emacs Writing Studio
If you like to support my work, then please purchase the Emacs Writing Studio book.
Emacs Writing Studio
A comprehensive guide for writers seeking to streamline their workflow using Emacs. The book covers everything from organising ideas and writing distraction-free to publishing in multiple formats. It’s perfect for both beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.
Emacs is a malleable system, and everybody has personal preferences on how to undertake a task and configure Emacs. Any article on how to use Emacs is thus opinionated. If you have a different way of doing things, please complete the contact form to send me an email or contact me on social media.
The next article in this series describes how to use Emacs Org mode for distraction-free writing.
Share this content
