From: Aymeric Agon-Rambosson Date: Fri, 19 Aug 2022 00:44:33 +0200 Subject: Drop references to external pages and debianise Forwarded: not-needed --- a/README.org +++ b/README.org @@ -1,18 +1,12 @@ -[[https://melpa.org/#/citar][file:https://melpa.org/packages/citar-badge.svg]] +#+title: citar - Quickly find and act on bibliographic references +#+author: Bruce D'Arcus +#+language: en +#+export_file_name: citar.texi +#+texinfo_dir_category: Emacs +#+texinfo_dir_title: Citar: (citar). +#+texinfo_dir_desc: Find and act on bibliographic references -* Citar - :PROPERTIES: - :CUSTOM_ID: citar - :END: - -- [[#features][Features]] -- [[#installation][Installation]] -- [[#configuration][Configuration]] -- [[#usage][Usage]] -- [[#comparisons][Comparisons]] -- [[#acknowledgements][Acknowledgements]] - -** Features +* Features :PROPERTIES: :CUSTOM_ID: features :END: @@ -28,7 +22,7 @@ Citar provides a highly-configurable =co - major-mode adapters - entry-opening, to go to the original entry data -Here's a screenshot with [[https://github.com/minad/vertico][vertico]] and symbol customization [[https://github.com/bdarcus/citar#icons][noted below]]. +Here's a screenshot with vertico (~apt install elpa-vertico~) and symbol customization [[*Indicators][noted below]]. #+caption: vertico with citar [[file:images/vertico.png]] @@ -40,34 +34,30 @@ And here's =citar-capf= in a markdown bu To see citar in action with org-cite, you can watch [[https://emacsconf.org/2021/talks/research/][this Emacs Conf 2021 presentation]] by [[https://github.com/rka97][Ahmed Khaled]]. -** Installation +* Installation :PROPERTIES: :CUSTOM_ID: installation :END: -There are a variety of ways to install citar: - -- Doom Emacs :: The easiest way to install and configure citar and related packages is to use the [[https://github.com/hlissner/doom-emacs/tree/master/modules/tools/biblio][Doom Emacs biblio module]] with the ~vertico~ completion module. -- MELPA :: citar is also available via [[https://melpa.org/#/citar][MELPA]]. -- GUIX :: provides the ~emacs-citar~ package. +citar is installed with ~apt install elpa-citar~. In addition, the following packages are strongly recommended for the best experience. -1. [[https://github.com/minad/vertico][Vertico]] (completion interface) -2. [[https://github.com/oantolin/orderless][Orderless]] (completion style) -3. [[https://github.com/oantolin/embark][Embark]] (contextual actions) -4. [[https://github.com/minad/marginalia][Marginalia]] (annotations, and also candidate classification for Embark) +1. Vertico (completion interface) +2. Orderless (~apt install elpa-orderless~) (completion style) +3. Embark (~apt install elpa-embark~) (contextual actions) +4. Marginalia (~apt install elpa-marginalia~) (annotations, and also candidate classification for Embark) -In particular, if you want to narrow your search using authors, titles, etc (i.e., not only citation keys), you need to use a completion style that is order independent; for example, [[https://github.com/oantolin/orderless][Orderless]] with ~completion-styles~ set to ~(orderless basic)~ (see [[https://github.com/oantolin/orderless#overview][example config]]). +In particular, if you want to narrow your search using authors, titles, etc (i.e., not only citation keys), you need to use a completion style that is order independent; for example, Orderless with ~completion-styles~ set to ~(orderless basic)~ (see [[https://github.com/oantolin/orderless#overview][example config]]). We also recommend Emacs 28 or newer. -** Configuration +* Configuration :PROPERTIES: :CUSTOM_ID: configuration :END: -*** Basic +** Basic :PROPERTIES: :CUSTOM_ID: basic :END: @@ -80,7 +70,7 @@ This is the minimal configuration, and w (citar-bibliography '("~/bib/references.bib"))) #+end_src -*** =citar-capf= +** =citar-capf= This package includes a ~completion-at-point~ function to complete citation keys in the buffer, which you can configure like so: @@ -93,7 +83,7 @@ This package includes a ~completion-at-p (org-mode . citar-capf-setup)) #+end_src -*** Embark +** Embark The =citar-embark= package adds contextual access actions in the minibuffer and at-point via the ~citar-embark-mode~ minor mode. @@ -106,11 +96,11 @@ When using Embark, the Citar actions are :config (citar-embark-mode)) #+end_src -*** Org-Cite +* Org-Cite This shows the buffer actions made available by =citar-embark=: -#+CAPTION: org-cite at-point integration with =embark-act= +#+CAPTION: org-cite at-point integration with embark-act [[file:images/org-cite-embark-point.png]] If you want to use Citar only in Org-Mode, this is the best option. @@ -140,7 +130,7 @@ If you prefer to have the Embark menu op You can invoke both =embark-act= and =embark-dwim=, however, independently of =org-at-point=, and in other modes such as =latex-mode=. -*** Major-mode adapters +* Major-mode adapters :PROPERTIES: :CUSTOM_ID: major-mode-adapters :END: @@ -163,7 +153,7 @@ Citar currently includes the following s None of these should require any configuration, and should load as needed. -*** Opening reference entries +** Opening reference entries The =citar-open-entry= command will open the source data entry. You may configure this using ~citar-open-entry-function~. @@ -171,7 +161,7 @@ By default, this uses ~citar-open-entry- The other included option is ~citar-open-entry-in-zotero~, which will select the item in Zotero. Note that functionality depends on [[https://retorque.re/zotero-better-bibtex/][Better BibTeX]] (which you should be using anyway!). -** Rich UI +* Rich UI :PROPERTIES: :CUSTOM_ID: rich-ui :END: @@ -188,7 +178,7 @@ For the prefix, you can filter for assoc #+CAPTION: UI sections [[file:images/ui-segments.png]] -*** Templates +** Templates The =citar-templates= variable configures formatting for these sections, as well as the default note function. Here's the default value: @@ -211,7 +201,7 @@ Note: 5. The ~%~ character preceeds a token defined as a key in ~citar-display-transform-functions~, whose value is a list of functions and optional arguments. Note that if you include this, if you also include a width specification, it must come after the width. -*** Indicators +** Indicators The UI includes configurable indicators. By default, it includes plain text indicators for, each of which indicates the presence of different resources related to the reference: @@ -233,7 +223,7 @@ Here's a screenshot using this configura #+caption: UI with customized indicators. #+name: fig-indicators -[[images/indicators.png]] +[[file:images/indicators.png]] You can create your own indicators, of course. Here's an example indicator definition incorporating icons: @@ -252,15 +242,7 @@ Here's an example indicator definition i Keep in mind, however, the included predicate functions must be performance-optimized, since the completion UI runs them on your entire library every time you open it. -** Test Script - :PROPERTIES: - :CUSTOM_ID: test-script - :END: - -The repository =test= directory also includes a script you can use to run this and associated packages in the =emacs -Q= sandbox. -To do that, simply run =./run.sh= from the =test= directory. - -** History and predefined searches +* History and predefined searches :PROPERTIES: :CUSTOM_ID: history-and-predefined-searches :END: @@ -280,7 +262,7 @@ You then have two ways to access these s =citar= also preserves the history of your selections (see caveat below about multiple candidate selection though), which are also accessible in your completion UI, but by using =M-p=. You can save this history across sessions by adding =citar-history= to =savehist-additional-variables=. -** Refreshing the library display +* Refreshing the library display :PROPERTIES: :CUSTOM_ID: refreshing-the-library-display :END: @@ -291,7 +273,7 @@ If a bib file changes, the cache will au Note that cached data preformatted completion candidates are independently tracked by file. So, for example, if you have one very large bibliography file that changes a lot, you might consider splitting into one large file that is more stable, and one-or-more smaller ones that change more frequently. -** Notes +* Notes Citar offers configurable note-taking and access integration. The ~citar-notes-sources~ variable configures note backends, and ~citar-notes-source~ activates your chosen backend. @@ -299,7 +281,7 @@ The ~citar-notes-sources~ variable confi A backend primarily specifies functions to update the Citar display, to create the completion candidates, and to open existing and new notes. See the ~citar-notes-sources~ docstring for details, and the =citar-register-notes-source= and =citar-remove-notes-source= convenience functions. -** Files, file association and file-field parsing +* Files, file association and file-field parsing If you have ~citar-library-paths~ set, the relevant open commands will look in those directories for file names of =CITEKEY.EXTENSION=. They will also parse contents of a file-field. @@ -332,7 +314,7 @@ When used with embark and consult, you w #+CAPTION: File candidates with embark options [[file:images/file-browser-embark.png]] -*** BibTeX Crossref File Support +** BibTeX Crossref File Support For BibTeX entries that have a 'crossref' field, Citar will associate the entry's key with the resources (files, notes, links) that are associated with the cross-referenced entry. @@ -340,14 +322,14 @@ For example: consider an entry for "Baym NOTE: For the BibTeX crossref feature to work properly, the entry with the 'crossref' field must come *before* the cross-referenced entry in the bib file. (This is a requirement of BibTeX, not of Citar specifically.) In the example above, then, the entry for "Baym1965" must come before the entry for "Meyers1999". -** Usage +* Usage :PROPERTIES: :CUSTOM_ID: usage :END: You have a few different ways to use citar. -*** Org-cite +** Org-cite Citar includes an org-cite =citar= processor, with "insert," "activate" and "follow" capabilities. When speaking about org-cite, *citations* refer to a set of one or more *references (citation-references)*, each of which may have text that precedes it (prefix) and text that proceeds it (suffix). @@ -398,7 +380,7 @@ For example, if you specify =text/f=, an #+CAPTION: citation styles [[file:images/oc-styles.png]] -*** =M-x= +** =M-x= :PROPERTIES: :CUSTOM_ID: m-x :END: @@ -406,7 +388,7 @@ For example, if you specify =text/f=, an Simply do =M-x= and select the command that you want, enter the terms to find the item you are looking for, and hit return. This runs the default action: the command you invoked. -*** Access an alternate action via =embark-act= +** Access an alternate action via =embark-act= :PROPERTIES: :CUSTOM_ID: access-an-alternate-action-via-embark-act :END: @@ -414,7 +396,7 @@ This runs the default action: the comman If while browsing you instead would rather edit that record, and you have embark installed and configured, this is where =embark-act= comes in. Simply input the keybinding for =embark-act= (in my case =C-o=), and select the alternate action. -*** Use =embark-collect-snapshot= +** Use =embark-collect-snapshot= :PROPERTIES: :CUSTOM_ID: use-embark-collect-snapshot :END: @@ -426,7 +408,7 @@ From there, you can run the same options So, for example, say you are working on a paper. You hold the complete super-set of items you are interested in citing at some point in that buffer. From there, you can run different actions on the candidates at will, rather than search individually for each item you want to cite. -*** Use =citar-dwim= +** Use =citar-dwim= :PROPERTIES: :CUSTOM_ID: use-citar-dwim :END: @@ -449,20 +431,20 @@ These small packages provide citar notes - [[https://github.com/pprevos/citar-denote][citar-denote]] - [[https://github.com/localauthor/zk][zk-citar]] -** Comparisons +* Comparisons :PROPERTIES: :CUSTOM_ID: comparisons :END: To understand how citar compares to other packages like =org-ref=, =ivy-bibtex= and =helm-bibtex= (and the related =bibtex-completion=), see the [[https://github.com/emacs-citar/citar/wiki/Comparisons][comparisons]] page on the wiki. -** Acknowledgements +* Acknowledgements :PROPERTIES: :CUSTOM_ID: acknowledgements :END: The ideas in this project were initially worked out in a [[https://github.com/tmalsburg/helm-bibtex/issues/353][conversation]] with [[https://github.com/mtreca][Maxime Tréca]] and [[https://github.com/minad][Daniel Mendler]]. -Daniel, author of [[https://github.com/minad/consult][consult]] and [[https://github.com/minad/marginalia][marginalia]], helped us understand the possibilities of the new suite of completing-read packages, while Maxime came up with an [[https://github.com/tmalsburg/helm-bibtex/pull/355][initial prototype]]. +Daniel, author of consult and marginalia, helped us understand the possibilities of the new suite of completing-read packages, while Maxime came up with an [[https://github.com/tmalsburg/helm-bibtex/pull/355][initial prototype]]. This code takes those ideas and re-implements them to fill out the feature set, and also optimize the code clarity and performance.