citar-denote.texi

\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename citar-denote.info
@settitle Citar-Denote Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@finalout
@titlepage
@title Citar-Denote Manual
@author Peter Prevos
@end titlepage

@ifnottex
@node Top
@top Citar-Denote Manual

Taking notes about the articles and books you read is essential to intellectual life. Many note-taking systems can connect to a bibliographic database (such as a plain text Bib@TeX{} file or external software such as Zotero). These databases are helpful when you need to add citations to your writing. Electronic bibliographies also help you create and find notes related to your literature collection and provide access to related materials, such as online sources and files stored on your computer.

Citar-Denote integrates the @uref{https://github.com/emacs-citar/citar, Citar} bibliography package with the Denote note-taking system:  @ref{Top,Denote,,denote,}  Citar lets you browse and act on bibliographic data in Bib@TeX{}, Bib@LaTeX{} or JSON format. Denote is a versatile Emacs package for taking and managing notes. Combining these two packages enables linking notes in your Denote collection to your bibliography, providing a complete solution for documenting literature reviews.
@end ifnottex

@menu
* Principles::
* Create bibliographic notes::
* Working with existing notes::
* Relationships between bibliographic notes::
* Citation management::
* Installation and example configuration::
* Acknowledgements::
* License::

@detailmenu
--- The Detailed Node Listing ---

Create bibliographic notes

* Default file type::
* Bibliographic note title::
* Bibliographic keywords::
* Subdirectory::
* Signature::
* Create notes using templates::
* Literature meta notes::

Working with existing notes

* Open existing bibliographic notes::
* Open attachments, links and notes: Open attachments links and notes. 
* Open bibliographic entry::
* Convert existing notes to bibliographic notes::
* Remove references from bibliographic notes::

@end detailmenu
@end menu

@node Principles
@chapter Principles

A bibliographic note is a file that refers to one or more pieces of literature in your bibliography. The notes and the entries in your literature database are intrinsically linked, making it easy to move between them. Two types of relationships exist between your notes and your bibliography:

@itemize
@item
Reference: Relates the whole file to one or more publications (a bibliographic note). Indicated by the reference line in the front matter and the @samp{bib} keyword.
@item
Citation: A citation inside a note mentions one or more publications. A citation relates a portion of the note's content to a publication.
@end itemize

The Citar-Denote package maintains a many-to-many relationship between your notes and your bibliography. Each item in the bibliography 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. For example, you could write a note about each book chapter or a single literature review note for a collection of journal articles. 

The system requires a stable link between the collection of notes and the bibliography to enable references. The most common behaviour for bibliography packages in Emacs is that the filename for the relevant note includes the citation key to link it to the bibliography (e.g., @samp{marcuse_1969_essay.org}). However, Denote follows a strict naming convention, so this approach to linking notes and literature is not feasible.

In Citar-Denote, the citation key is part of the front matter of Denote files through the @samp{#+reference:} line.

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 is marked with the configurable @samp{_bib} file tag (@code{citar-denote-keyword}). This tag reduces the search space to generate the cache.

The front matter for a bibliographic Org mode note looks something like this:

@example
#+title:      Marcuse: An Essay on Liberation
#+date:       [2022-11-12 Sat 19:23]
#+filetags:   :bib:culture:marketing:philosophy:
#+identifier: 20221112T192310
#+reference:  marcuse_1969_essay
@end example

The package also provides insight into citations used in the Denote collections. You can cite a bibliographic entry in a Denote Org mode note with the @code{org-cite-insert} function. @ref{Citations,Org mode citations,,org,}

@node Create bibliographic notes
@chapter Create bibliographic notes

Open the Citar interface with @code{citar-create-note}. The letters at the start of the Citar menu indicate whether the entry has a link (@samp{L}), note (@samp{N}), attachment (@samp{F}) or is cited in the current buffer (@samp{C}). Select the entry you want to create a note for and use the @samp{TAB} key to select more than one reference. Hit Return and follow the prompts to create a new note.

If a note already exists, you can open it. To enable multiple notes for bibliographic items, set the @code{citar-open-always-create-notes} variable to @samp{t}.

Various configuration options are available to fine-tune and determine how Citar-Denote creates bibliographic notes.

@menu
* Default file type::
* Bibliographic note title::
* Bibliographic keywords::
* Subdirectory::
* Signature::
* Create notes using templates::
* Literature meta notes::
@end menu

@node Default file type
@section Default file type

You can create bibliographic notes for each file type that Denote supports: Org mode, two Markdown flavours and plain text.

Citar-Denote uses the default file type set by the @code{denote-file-type} variable, which you can override with @code{citar-denote-file-type} to use a different file type for bibliographic notes.

Please note that the citation functionality only works in Org mode. Citation mechanisms exist for Markdown, but these are not standardised.

@node Bibliographic note title
@section Bibliographic note title

The default name for a new note is the title of the bibliographic entry. You can modify this behaviour with the @code{citar-denote-title-format} variable. Four options are available:

@enumerate
@item
@samp{title}: Extract the title from the bibliographic item (default)
@item
@samp{author-year}: Use citation format as ``author(s) (year)'' (or editors when no authors are defined)
@item
@samp{author-year-title}: Concatenate the first two options
@item
@samp{full}: Full citation of the entry
@item
Fallback option or @samp{nil}: The citation key
@end enumerate

For example, using this citation: Coppa, Hass, Peck, Burger (2008) @emph{Performing Magic on the Western Stage: From the Eighteenth Century to the Present}, Palgrave Macmillan @uref{https://doi.org/10.1057/9780230617124}. The five options result in:

@enumerate
@item
@samp{title}: ``Performing Magic on the Western Stage: From the Eighteenth Century to the Present''.
@item
@samp{author-year}: ``Coppa et al. (2008)''. 
@item
@samp{author-year-title}: ``Coppa et al. (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present''.
@item
@samp{full}: ``Coppa, Hass, Peck, Burger (2008) @emph{Performing Magic on the Western Stage: From the Eighteenth Century to the Present}, Palgrave Macmillan''.
@item
@samp{nil}: ``coppa@math{_2008}@math{_perf}''.
@end enumerate

Using @samp{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 @code{citar-denote-title-format-authors}, which is one by default. When the number of defined authors exceeds the number in the citation, ``et al.'' is added to the end. All authors are listed when this variable exceeds the number of defined authors.

The default term between authors is ``and'', which can be changed by customising @code{citar-denote-title-format-andstr}.

For example, when using up to three authors and ``&'' as a connecting term, the title for the example above becomes ``Coppa, Hass & Peck et al. (2008).''

@node Bibliographic keywords
@section Bibliographic keywords

Every new bibliographic note includes the @samp{bib} file tag. This tag minimises the search space when caching notes to accelerate the process. The @code{citar-denote-keyword} variable lets you change the tag to something else. For example, if your primary language is Welsh, you might want to change it to @samp{llenyddiaeth} (literature).

Changing the default keyword requires updating all your bibliographic notes because the package only recognises a single string. The Denote-Explore package provides a function to rename Denote keywords. @ref{Managing Keywords,Denote-Explore,,denote-explore,}

The @code{citar-denote-use-bib-keywords} variable lets you include any keywords defined in the bibliography entry in the note. When set to @samp{t}, Citar-Denote extracts the available keywords from the Bib@TeX{} @samp{keywords} field and uses these as Denote file tags.

@node Subdirectory
@section Subdirectory

All new notes are stored in the location specified by @samp{denote-directory}.

If you like storing your bibliographic notes in a subdirectory, set the @code{citar-denote-subdir} variable to @samp{t}. Denote now asks for a subdirectory when creating a new bibliographic note.

When the content of this variable is a string, Denote saves the note in a subdirectory with that name under @samp{denote-directory}. For example, if this variable is set at ``literature'', all bibliographic notes are stored under @samp{denote-directory/literature/}.

@node Signature
@section Signature

When the @code{citar-denote-signature} variable is @samp{'ask}, Denote will ask for a signature when creating a new bibliographic note.

When this variable is set at @samp{'citekey}, the citation key forms the basis of the signature. Please note that Denote changes or remove punctuation marks in the citation key with @code{denote-sluggify-signature} to enforce compliance with its file naming convention.

For example, when the citation key is @samp{einstein_1905}, the signature becomes @samp{einstein=2005}.

@node Create notes using templates
@section Create notes using templates

Denote allows you to create templates for various types of notes. You could use standard headings for bibliographic notes, other headings for meta notes, or whatever else you might need, @ref{The denote-templates option,Denote templates,,denote,}

To include templates in new bibliographic notes, set the @code{citar-denote-template} to either:

@itemize
@item
@samp{t}: Ask for a template when creating a note.
@item
The name of the default template for creating bibliographic notes
@end itemize

The example below lets the user choose between a note with two headings (Abstract and Review) or a plain note without any template content when @code{citar-denote-template} is non-nil. Setting @code{citar-denote-template} to @samp{biblio} will always use this template for new literature notes.

@lisp
(setq denote-templates
      '((biblio . "* Abstract\n\n* Review")
        (plain . nil))
      citar-denote-template 'biblio)
@end lisp

@node Literature meta notes
@section Literature meta notes

If you have a set of notes from the same book and use Org mode, you can create a meta note to combine the relevant notes. This note can have automated links to all related references with dynamic blocks or transclude the note's content.

The best way to create a meta note that combines literature notes from a single publication is to add the citation key in the signature, as explained above. You can then use the signature as the regular expression for the block. 

Other options include creating a meta note for an author or a specific subject matter. You can use dynamic blocks if the relevant notes all include the same character string in their file names, which you can fetch with a regular expression. For more information on meta notes, @ref{Writing metanotes,Writing metanotes,,denote,}

@node Working with existing notes
@chapter 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 (@code{citar-open}). Entries with a note are indicated with an @samp{N} in the third column.

@menu
* Open existing bibliographic notes::
* Open attachments, links and notes: Open attachments links and notes. 
* Open bibliographic entry::
* Convert existing notes to bibliographic notes::
* Remove references from bibliographic notes::
@end menu

@node Open existing bibliographic notes
@section Open existing bibliographic notes

There are two entry points to finding notes related to literature, either as references or as citations.

Use @code{citar-denote-open-note} to open the Citar menu with only entries with one or more associated notes. Select your target and hit Return.

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 Return again and select the Denote file you want to open. 

The previous function shows all literature with one or more bibliographic note(s) linked through a reference line. The @code{citar-denote-find-citation} function lists all bibliographic entries cited inside your Denote collection, from which you can open the relevant note.

When only one note cites the selected entry, this file is opened. When multiple files cite the chosen entry, you must pick which file to jump to.

By default, this function only looks at citations in your document. Setting the @code{citar-denote-cite-includes-reference} to non-nil includes references.

When using the @code{citar-embark} package, you can activate this function with Embark after you create a keyboard shortcut.

@code{(define-key citar-embark-citation-map "c" 'citar-denote-find-citation)}

Depending on the size of your digital garden, searching through all your notes for citations can take a moment. The citations search mechanism uses the @samp{xref} system. You can improve the search process by installing the faster @uref{https://github.com/BurntSushi/ripgrep, ripgrep} program and setting @code{xref-search-program} to @samp{ripgrep}.

@node Open attachments links and notes
@section Open attachments, links and notes

The @code{citar-denote-dwim} function 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 would like to access and hit Return, after which you will choose your link, note, or attachment. Alternatively, you can also create a new note for that reference.

@node Open bibliographic entry
@section Open bibliographic entry

The @code{citar-denote-open-reference-entry} function opens the bibliographic entry (Bib@TeX{}, Bib@LaTeX{} or CSL file) for a selected reference, from where you can edit the bibliographic data.

@node Convert existing notes to bibliographic notes
@section Convert existing notes to bibliographic notes

The @code{citar-denote-add-citekey} function adds citation keys or converts an existing Denote file to a bibliographic note. When converting a regular Denote file, the function adds the @samp{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.

@node Remove references from bibliographic notes
@section Remove references from bibliographic notes

You remove citation references with the @code{citar-denote-remove-citekey} command. Suppose the current buffer references more than one piece of literature. In that case, you must select the unwanted item in the minibuffer.

When no more reference items are left, the @samp{_bib} keyword is removed, and the file is renamed.

You can also manually edit your file and add and remove reference citation keys.

@node Relationships between bibliographic notes
@chapter Relationships between bibliographic notes

Bibliographic notes rarely exist in solitude. A note might be one of a series about the same topic or about the same book. 

The @code{citar-denote-find-reference} function finds all notes where another note cites the selected reference from the active buffer. A warning appears in the minibuffer when the selected reference is not found in any Denote files or you are not in a Denote file. 

If you would like to know whether one of the references in the current buffer is also referenced in another note, then use @code{citar-denote-dwim}, discussed above.

Denote has excellent capabilities for linking notes to each other. You can use this facility to link to any other bibliographic note in your collection. The @code{citar-denote-link-reference} function asks you to select a bibliographic entry for which a note exists and create a link to the relevant note in the current Denote buffer. If more than one note exists for the selected publication, you first choose which note you like to link to.

@node Citation management
@chapter 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 @code{citar-denote-nocite} function opens the Citar menu. It 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 associated file(s). If your Denote collection references or cites all items in your bibliography, a message appears in the minibuffer: ``No associated resources''.

The @code{citar-denote-cite-nocite} function cites an unused bibliographic entry. This function only works when the active buffer is a Denote Org mode note.

Lastly, the @code{citar-denote-nobib} function lists all references and citations in your Denote collection that are absent in the global bibliography in the @samp{*Messages*} buffer. Note that this list excludes any local bibliographies. The output of this function is a list of citation keys used in Denote that need to be added or corrected.

@node Installation and example configuration
@chapter Installation and example configuration

This package is available in MELPA@. The example below provides a minimum configuration for Citar and Denote. The minimum required configuration for Citar is to set the list of bibliography files. Using Org mode citations, you can set this variable the same as @code{org-cite-global-bibliography}. This configuration also sets Citar to accept multiple notes per reference.

@lisp
(use-package citar
  :ensure t
  :defer t
  :custom
  ;; set bibliography's location
  (citar-bibliography '("~/documents/library/magic-tricks.bib"))
  ;; Allow multiple notes per bibliographic entry
  (citar-open-always-create-notes nil)
  :init
  (fido-vertical-mode 1)
  :bind ("C-c w c" . citar-create-note))

(use-package denote
  :defer t
  :custom
  (denote-directory "~/documents/notes"))
@end lisp

The citar-Denote configuration includes all configurable variables with their package defaults. You can either remove these entries or configure them to your preferences. This configuration example also binds all available Citar-Denote commands. You will need to change the directory paths to suit your preferences.

@lisp
(use-package citar-denote
:ensure t
:demand t ;; Ensure minor mode loads
:after (:any citar denote)
:custom
;; Package defaults
(citar-denote-file-type 'org)
(citar-denote-keyword "bib")
(citar-denote-signature nil)
(citar-denote-subdir nil)
(citar-denote-template nil)
(citar-denote-title-format "title")
(citar-denote-title-format-andstr "and")
(citar-denote-title-format-authors 1)
(citar-denote-use-bib-keywords nil)
:preface
(bind-key "C-c w n" #'citar-denote-open-note)
:init
(citar-denote-mode)
;; Bind all available commands
:bind (("C-c w d" . citar-denote-dwim)
       ("C-c w e" . citar-denote-open-reference-entry)
       ("C-c w a" . citar-denote-add-citekey)
       ("C-c w k" . citar-denote-remove-citekey)
       ("C-c w r" . citar-denote-find-reference)
       ("C-c w l" . citar-denote-link-reference)
       ("C-c w f" . citar-denote-find-citation)
       ("C-c w x" . citar-denote-nocite)
       ("C-c w y" . citar-denote-cite-nocite)
       ("C-c w z" . citar-denote-nobib)))
@end lisp

You can use the standard configurations for Citar and Denote. Citar-Denote takes over the note-taking functionality in Citar with a minor mode.

You can also install this package directly from GitHub to enjoy the latest version (assuming you use Emacs 29 or above.

@lisp
(unless (package-installed-p 'citar-denote)
(package-vc-install
 '(citar-denote
   :url "https://github.com/pprevos/citar-denote/")))
@end lisp

@node Acknowledgements
@chapter Acknowledgements

This code would only have existed with the help of Protesilaos Stavrou, developer of Denote and Citar developer Bruce D'Arcus.

In addition, Joel Lööw and Noboru Ota made significant contributions, without which this package would not exist. Troy Figiel, Taha Aziz, Ben Ali, Guillermo Navarro, Colin McLear, Lucas Gruss, Adrian Adermon, Jonathan Sahar, Samuel W@. Flint, Yejun Su, and Elias Storms provided valuable suggestions to extend functionality.

Feel free to raise an issue here on GitHub if you have any questions or find bugs or suggestions for enhanced functionality.

@node License
@chapter License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License or (at your option) any later version.

This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE@. See the GNU General Public License for more details.

For a full copy of the GNU General Public License, see @uref{https://www.gnu.org/licenses/}.

@bye