citar-denote.info

This is citar-denote.info, produced by makeinfo version 7.1.1 from
citar-denote.texi.


File: citar-denote.info,  Node: Top,  Next: Principles,  Up: (dir)

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 BibTeX 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 Citar
(https://github.com/emacs-citar/citar) bibliography package with the
Denote note-taking system: *note Denote: (denote)Top. Citar lets you
browse and act on bibliographic data in BibTeX, BibLaTeX 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.

* Menu:

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

-- 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::



File: citar-denote.info,  Node: Principles,  Next: Create bibliographic notes,  Prev: Top,  Up: Top

1 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:

   • Reference: Relates the whole file to one or more publications (a
     bibliographic note).  Indicated by the reference line in the front
     matter and the ‘bib’ keyword.
   • Citation: A citation inside a note mentions one or more
     publications.  A citation relates a portion of the note's content
     to a publication.

   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.,
‘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 ‘#+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 ‘_bib’ file tag
(‘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:

     #+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 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 ‘org-cite-insert’ function.  *note Org mode citations:
(org)Citations.


File: citar-denote.info,  Node: Create bibliographic notes,  Next: Working with existing notes,  Prev: Principles,  Up: Top

2 Create bibliographic notes
****************************

Open the Citar interface with ‘citar-create-note’.  The letters at the
start of the Citar menu indicate whether the entry has a link (‘L’),
note (‘N’), attachment (‘F’) or is cited in the current buffer (‘C’).
Select the entry you want to create a note for and use the ‘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 ‘citar-open-always-create-notes’
variable to ‘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::


File: citar-denote.info,  Node: Default file type,  Next: Bibliographic note title,  Up: Create bibliographic notes

2.1 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 ‘denote-file-type’
variable, which you can override with ‘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.


File: citar-denote.info,  Node: Bibliographic note title,  Next: Bibliographic keywords,  Prev: Default file type,  Up: Create bibliographic notes

2.2 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:

  1. ‘title’: Extract the title from the bibliographic item (default)
  2. ‘author-year’: Use citation format as "author(s) (year)" (or
     editors when no authors are defined)
  3. ‘author-year-title’: Concatenate the first two options
  4. ‘full’: Full citation of the entry
  5. 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
<https://doi.org/10.1057/9780230617124>.  The five options result in:

  1. ‘title’: "Performing Magic on the Western Stage: From the
     Eighteenth Century to the Present".
  2. ‘author-year’: "Coppa et al.  (2008)".
  3. ‘author-year-title’: "Coppa et al.  (2008) Performing Magic on the
     Western Stage: From the Eighteenth Century to the Present".
  4. ‘full’: "Coppa, Hass, Peck, Burger (2008) _Performing Magic on the
     Western Stage: From the Eighteenth Century to the Present_,
     Palgrave Macmillan".
  5. ‘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 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 ‘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)."


File: citar-denote.info,  Node: Bibliographic keywords,  Next: Subdirectory,  Prev: Bibliographic note title,  Up: Create bibliographic notes

2.3 Bibliographic keywords
==========================

Every new bibliographic note includes the ‘bib’ file tag.  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 your primary language is Welsh, you might want to
change it to ‘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.
*note Denote-Explore: (denote-explore)Managing Keywords.

   The ‘citar-denote-use-bib-keywords’ variable lets you include any
keywords defined in the bibliography entry in the note.  When set to
‘t’, Citar-Denote extracts the available keywords from the BibTeX
‘keywords’ field and uses these as Denote file tags.


File: citar-denote.info,  Node: Subdirectory,  Next: Signature,  Prev: Bibliographic keywords,  Up: Create bibliographic notes

2.4 Subdirectory
================

All new notes are stored in the location specified by
‘denote-directory’.

   If you like storing your bibliographic notes in a subdirectory, set
the ‘citar-denote-subdir’ variable to ‘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 ‘denote-directory’.  For example,
if this variable is set at "literature", all bibliographic notes are
stored under ‘denote-directory/literature/’.


File: citar-denote.info,  Node: Signature,  Next: Create notes using templates,  Prev: Subdirectory,  Up: Create bibliographic notes

2.5 Signature
=============

When the ‘citar-denote-signature’ variable is ‘'ask’, Denote will ask
for a signature when creating a new bibliographic note.

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

   For example, when the citation key is ‘einstein_1905’, the signature
becomes ‘einstein=2005’.


File: citar-denote.info,  Node: Create notes using templates,  Next: Literature meta notes,  Prev: Signature,  Up: Create bibliographic notes

2.6 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, *note Denote templates:
(denote)The denote-templates option.

   To include templates in new bibliographic notes, set the
‘citar-denote-template’ to either:

   • ‘t’: Ask for a template when creating a note.
   • The name of the default template for creating bibliographic notes

   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 ‘citar-denote-template’ is non-nil.  Setting
‘citar-denote-template’ to ‘biblio’ will always use this template for
new literature notes.

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


File: citar-denote.info,  Node: Literature meta notes,  Prev: Create notes using templates,  Up: Create bibliographic notes

2.7 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, *note Writing metanotes: (denote)Writing metanotes.


File: citar-denote.info,  Node: Working with existing notes,  Next: Relationships between bibliographic notes,  Prev: Create bibliographic notes,  Up: Top

3 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’).  Entries with a note are indicated with an ‘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::


File: citar-denote.info,  Node: Open existing bibliographic notes,  Next: Open attachments links and notes,  Up: Working with existing notes

3.1 Open existing bibliographic notes
=====================================

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

   Use ‘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
‘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 ‘citar-denote-cite-includes-reference’ to non-nil includes
references.

   When using the ‘citar-embark’ package, you can activate this function
with Embark after you create a keyboard shortcut.

   ‘(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 ‘xref’ system.  You can improve the search process by
installing the faster ripgrep (https://github.com/BurntSushi/ripgrep)
program and setting ‘xref-search-program’ to ‘ripgrep’.


File: citar-denote.info,  Node: Open attachments links and notes,  Next: Open bibliographic entry,  Prev: Open existing bibliographic notes,  Up: Working with existing notes

3.2 Open attachments, links and notes
=====================================

The ‘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.


File: citar-denote.info,  Node: Open bibliographic entry,  Next: Convert existing notes to bibliographic notes,  Prev: Open attachments links and notes,  Up: Working with existing notes

3.3 Open bibliographic entry
============================

The ‘citar-denote-open-reference-entry’ function opens the bibliographic
entry (BibTeX, BibLaTeX or CSL file) for a selected reference, from
where you can edit the bibliographic data.


File: citar-denote.info,  Node: Convert existing notes to bibliographic notes,  Next: Remove references from bibliographic notes,  Prev: Open bibliographic entry,  Up: Working with existing notes

3.4 Convert existing notes to bibliographic notes
=================================================

The ‘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 ‘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.


File: citar-denote.info,  Node: Remove references from bibliographic notes,  Prev: Convert existing notes to bibliographic notes,  Up: Working with existing notes

3.5 Remove references from bibliographic notes
==============================================

You remove citation references with the ‘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 ‘_bib’ keyword is removed,
and the file is renamed.

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


File: citar-denote.info,  Node: Relationships between bibliographic notes,  Next: Citation management,  Prev: Working with existing notes,  Up: Top

4 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 ‘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
‘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 ‘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.


File: citar-denote.info,  Node: Citation management,  Next: Installation and example configuration,  Prev: Relationships between bibliographic notes,  Up: Top

5 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’ 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 ‘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 ‘citar-denote-nobib’ function lists all references and
citations in your Denote collection that are absent in the global
bibliography in the ‘*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.


File: citar-denote.info,  Node: Installation and example configuration,  Next: Acknowledgements,  Prev: Citation management,  Up: Top

6 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
‘org-cite-global-bibliography’.  This configuration also sets Citar to
accept multiple notes per reference.

     (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"))

   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.

     (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)))

   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.

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


File: citar-denote.info,  Node: Acknowledgements,  Next: License,  Prev: Installation and example configuration,  Up: Top

7 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.


File: citar-denote.info,  Node: License,  Prev: Acknowledgements,  Up: Top

8 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
<https://www.gnu.org/licenses/>.



Tag Table:
Node: Top87
Node: Principles1911
Node: Create bibliographic notes4628
Node: Default file type5673
Node: Bibliographic note title6305
Node: Bibliographic keywords8486
Node: Subdirectory9563
Node: Signature10274
Node: Create notes using templates10953
Node: Literature meta notes12091
Node: Working with existing notes13080
Node: Open existing bibliographic notes13835
Node: Open attachments links and notes15687
Node: Open bibliographic entry16453
Node: Convert existing notes to bibliographic notes16890
Node: Remove references from bibliographic notes17555
Node: Relationships between bibliographic notes18230
Node: Citation management19482
Node: Installation and example configuration20843
Node: Acknowledgements23810
Node: License24563

End Tag Table


Local Variables:
coding: utf-8
End: