citar
v1.3.0 - configurable indicators
Citar bietet ein hochgradig konfigurierbares completing-read Frontend zum Durchsuchen und Bearbeiten bibliografischer BibTeX-, BibLaTeX- und CSL-JSON-Daten sowie Unterstützung für LaTeX, Markdown und Org-Cite-Bearbeitung.
citar-embark , das kontextbezogene Aktionen im Minipuffer und auch at-point in Org-, Markdown- und LaTeX-Puffer bereitstellt.org-roam , denote und zk verfügbar sindHier ist ein Screenshot mit der unten aufgeführten Anpassung von Vertiko und Symbolen.
Und hier ist citar-capf in einem Markdown-Puffer.
Um citar in Aktion mit org-cite zu sehen, können Sie sich diese Emacs Conf 2021-Präsentation von Ahmed Khaled ansehen.
Es gibt verschiedene Möglichkeiten, citar zu installieren:
vertico Vervollständigungsmodul.emacs-citar bereit.Darüber hinaus werden die folgenden Pakete für das beste Erlebnis dringend empfohlen.
Insbesondere wenn Sie Ihre Suche nach Autoren, Titeln usw. eingrenzen möchten (also nicht nur nach Zitierschlüsseln), müssen Sie einen Vervollständigungsstil verwenden, der unabhängig von der Reihenfolge ist; zum Beispiel „Orderless“ mit der Einstellung completion-styles (orderless basic) (siehe Beispielkonfiguration).
Wir empfehlen außerdem Emacs 28 oder neuer.
Dies ist die minimale Konfiguration und funktioniert mit jeder Complete-Read-kompatiblen vertikalen Vervollständigungs-Benutzeroberfläche wie Vertico oder dem integrierten icomplete-vertical, wobei Aktionen über Mx -Befehle verfügbar sind.
( use-package citar
:custom
(citar-bibliography '( " ~/bib/references.bib " )))citar-capf Dieses Paket enthält eine Funktion completion-at-point , um Zitatschlüssel im Puffer zu vervollständigen, die Sie wie folgt konfigurieren können:
( use-package citar
:custom
(citar-bibliography '( " ~/bib/references.bib " ))
:hook
( LaTeX-mode . citar-capf-setup)
( org-mode . citar-capf-setup)) Das Paket citar-embark fügt über den Nebenmodus citar-embark-mode kontextbezogene Zugriffsaktionen im Minipuffer und am Punkt hinzu.
Bei Verwendung von Embark sind die Citar-Aktionen generisch und funktionieren im Org-, Markdown- und Latex-Modus gleich.
( use-package citar-embark
:after citar embark
:no-require
:config (citar-embark-mode)) Dies zeigt die von citar-embark zur Verfügung gestellten Pufferaktionen:
Wenn Sie Citar nur im Org-Modus nutzen möchten, ist dies die beste Option.
( use-package citar
:no-require
:custom
(org-cite-global-bibliography '( " ~/bib/references.bib " ))
(org-cite-insert-processor 'citar )
(org-cite-follow-processor 'citar )
(org-cite-activate-processor 'citar )
(citar-bibliography org-cite-global-bibliography)
; ; optional: org-cite-insert is also bound to C-c C-x C-@
:bind
( :map org-mode-map :package org ( " C-c b " . # 'org-cite-insert ))) Sie können Zitate mit dem Befehl org-cite-insert einfügen, der in Org-Mode-Puffer an Cc Cx C-@ gebunden ist. Der optionale Befehl :bind oben gibt ihm auch die kürzere Cc b -Bindung.
Wenn Sie das Embark-Menü lieber mit org-open-at-point öffnen möchten, sollten Sie diese Variable festlegen.
( setq citar-at-point-function 'embark-act ) Sie können sowohl embark-act als auch embark-dwim aufrufen, jedoch unabhängig von org-at-point und in anderen Modi wie dem latex-mode .
Citar enthält ein Adapter-Framework, um die hauptmodusspezifische Bearbeitungsintegration zu ermöglichen. Solche Adapter können die folgenden Funktionen bereitstellen, die man mit der Liste citar-major-mode-functions konfigurieren kann:
insert-keys : um Zitierschlüssel einzufügen (dies kann jedoch verschwinden)insert-citation : um Zitate einzufügeninsert-edit : um Zitate einzufügen oder an einer Stelle zu bearbeitenlocal-bib-files : um bibliografische Dateien zu finden, die einem Puffer zugeordnet sindkey-at-point : Gibt den Zitierschlüssel an der Stelle zurückcitation-at-point : Gibt die Liste der Schlüssel im Zitat an der Stelle zurückCitar umfasst derzeit die folgenden Adapter:
citar-org : unterstützt standardmäßig nur org-cite , kann aber für andere Formate konfiguriert werdencitar-latex : konfigurierbare Bibtex-, Natbib- und Biblatex-Unterstützung (erfordert AUCTeX)citar-markdown : Unterstützt standardmäßig nur die pandoc ZitatsyntaxKeines davon sollte eine Konfiguration erfordern und bei Bedarf geladen werden.
Der Befehl citar-open-entry öffnet den Quelldateneintrag. Sie können dies mit citar-open-entry-function konfigurieren. Standardmäßig wird hierfür citar-open-entry-in-file verwendet, wodurch die entsprechende bibliografische Datei geöffnet und der Punkt zum Eintrag verschoben wird. Die andere enthaltene Option ist citar-open-entry-in-zotero , die das Element in Zotero auswählt. Beachten Sie, dass die Funktionalität von Better BibTeX abhängt (das Sie auf jeden Fall verwenden sollten!).
Es gibt drei Abschnitte der Browser-Benutzeroberfläche.
Sie können nach allen oben genannten Inhalten suchen. Für das Präfix können Sie nach zugehörigen Dateien oder Notizen filtern, indem Sie has:file bzw. has:notes verwenden (und zumindest bei orderless sogar die Abkürzung :p oder :n ).
Die Variable citar-templates konfiguriert die Formatierung dieser Abschnitte sowie die Standardnotizfunktion. Hier ist der Standardwert:
( setq citar-templates
'((main . " ${author editor:30%sn} ${date year issued:4} ${title:48} " )
(suffix . " ${=key= id:15} ${=type=:12} ${tags keywords:*} " )
(preview . " ${author editor:%etal} (${year issued date}) ${title}, ${journal journaltitle publisher container-title collection-title}. n " )
(note . " Notes on ${author editor:%etal}, ${title} " )))Notiz:
% -Zeichen steht vor einem Token, das als Schlüssel in citar-display-transform-functions definiert ist und dessen Wert eine Liste von Funktionen und optionalen Argumenten ist. Beachten Sie, dass, wenn Sie dies angeben und auch eine Breitenangabe angeben, diese nach der Breite stehen muss.Die Benutzeroberfläche enthält konfigurierbare Indikatoren. Standardmäßig enthält es Klartextindikatoren für, die jeweils das Vorhandensein verschiedener Ressourcen im Zusammenhang mit der Referenz anzeigen:
Weitere Indikatoren finden Sie im Wiki.
Hier ist ein Screenshot mit dieser Konfiguration, die den Link-Indikator entfernt und reinen Text und einen Symbol-Indikator unter Verwendung von all-the-icons mischt.
( setq citar-indicators
( list citar-indicator-files ; plain text
citar-indicator-notes-icons)) ; icon 
Sie können natürlich auch Ihre eigenen Indikatoren erstellen. Hier ist ein Beispiel für eine Indikatordefinition mit Symbolen:
( defvar citar-indicator-notes-icons
(citar-indicator-create
:symbol (all-the-icons-material
" speaker_notes "
:face 'all-the-icons-blue
:v-adjust -0.3 )
:function # 'citar-has-notes
:padding " "
:tag " has:notes " ))Beachten Sie jedoch, dass die enthaltenen Prädikatfunktionen leistungsoptimiert sein müssen, da die Vervollständigungs-Benutzeroberfläche sie jedes Mal, wenn Sie sie öffnen, für Ihre gesamte Bibliothek ausführt.
Nerd-icons.el ist eine Bibliothek zur einfachen Verwendung von Nerd-Font-Symbolen in Emacs, eine Alternative zu All-the-Icons, und es handelt sich um das Symbolpaket, das bereits in Doom Emacs enthalten ist. Hier ist ein Beispiel dafür, wie man damit ein ähnliches Aussehen erhält:
( defvar citar-indicator-notes-icons
(citar-indicator-create
:symbol (nerd-icons-mdicon
" nf-md-notebook "
:face 'nerd-icons-blue
:v-adjust -0.3 )
:function # 'citar-has-notes
:padding " "
:tag " has:notes " ))
( defvar citar-indicator-links-icons
(citar-indicator-create
:symbol (nerd-icons-octicon
" nf-oct-link "
:face 'nerd-icons-orange
:v-adjust -0.1 )
:function # 'citar-has-links
:padding " "
:tag " has:links " ))
( defvar citar-indicator-files-icons
(citar-indicator-create
:symbol (nerd-icons-faicon
" nf-fa-file "
:face 'nerd-icons-green
:v-adjust -0.1 )
:function # 'citar-has-files
:padding " "
:tag " has:files " ))
( setq citar-indicators
( list citar-indicator-files-icons
citar-indicator-notes-icons
citar-indicator-links-icons)) Das Repository- test enthält auch ein Skript, mit dem Sie dieses und zugehörige Pakete in der Sandbox emacs -Q ausführen können. Führen Sie dazu einfach ./run.sh aus dem test aus.
citar verfügt über eine ähnliche Funktionalität wie die vordefinierte Suchfunktion in helm-bibtex und ivy-bibtex , jedoch mit einer anderen Implementierung. Anstatt einen neuen Befehl mit den Suchbegriffen als Argument zu erstellen, legen Sie einfach die Variable citar-presets fest und fügen die Zeichenfolgen hinzu, auf die Sie zugreifen möchten:
( setq citar-presets '( " one search string " " another search string " ))Sie haben dann zwei Möglichkeiten, über die Vervollständigungsaufforderung auf diese Zeichenfolgen zuzugreifen:
Mn an der Eingabeaufforderung verwenden, wodurch die Zeichenfolgen durchlaufen werdencitar-insert-preset mit einer Tastenkombination aufrufen und dann die Zeichenfolge auswählen citar behält auch den Verlauf Ihrer Auswahlen bei (siehe allerdings den folgenden Vorbehalt zur Auswahl mehrerer Kandidaten), auf die auch in Ihrer Vervollständigungs-Benutzeroberfläche zugegriffen werden kann, jedoch über Mp . Sie können diesen Verlauf sitzungsübergreifend speichern, indem citar-history zu savehist-additional-variables hinzufügen.
Citar verwendet einen Cache, um die Anzeige der Bibliothek zu beschleunigen. Wenn sich eine bib-Datei ändert, wird der Cache automatisch aktualisiert, wenn Sie das nächste Mal einen Citar-Befehl ausführen.
Beachten Sie, dass vorformatierte Vervollständigungskandidaten für zwischengespeicherte Daten unabhängig nach Datei verfolgt werden. Wenn Sie beispielsweise über eine sehr große Bibliografiedatei verfügen, die sich häufig ändert, können Sie die Aufteilung in eine große Datei, die stabiler ist, und eine oder mehrere kleinere Dateien, die sich häufiger ändern, in Betracht ziehen.
Citar bietet konfigurierbare Notizen- und Zugriffsintegration. Die Variable citar-notes-sources konfiguriert Notiz-Backends und citar-notes-source aktiviert das von Ihnen gewählte Backend.
Ein Backend spezifiziert in erster Linie Funktionen zum Aktualisieren der Citar-Anzeige, zum Erstellen der Vervollständigungskandidaten und zum Öffnen bestehender und neuer Notizen. Weitere Informationen finden Sie in der Dokumentzeichenfolge citar-notes-sources sowie in den Komfortfunktionen citar-register-notes-source und citar-remove-notes-source .
Wenn Sie citar-library-paths festgelegt haben, suchen die entsprechenden Öffnungsbefehle in diesen Verzeichnissen nach Dateinamen von CITEKEY.EXTENSION . Sie analysieren auch den Inhalt eines Dateifelds. Die Variable citar-file-parser-functions regelt, welche Parser verwendet werden sollen, und es sind zwei enthaltene Parser:
citar-file-parser-default -Parser funktioniert für einfache durch Doppelpunkte oder Semikolons getrennte Listen von Dateipfaden, wie in Zotero.citar-file-parser-triplet funktioniert für Mendeley und Calibre, die Dateien in einem Format wie :/path/file.pdf:PDF darstellen.Wenn Sie eine Mischung aus Einträgen haben, die mit Zotero und Calibre erstellt wurden, können Sie es wie folgt einstellen und beide werden geparst:
( setq citar-file-parser-functions
'(citar-file-parser-default
citar-file-parser-triplet)) Die Variable citar-library-file-extensions regelt, welche Dateierweiterungen die Öffnungsbefehle erkennen; Bei „Null“ werden alle Erweiterungen erkannt. Die Variable citar-file-additional-files-separator definiert, welche Muster citar für mehrere Bibliotheksdateien für denselben Referenzschlüssel identifizieren soll. Hier ist ein Beispiel, um nur PDF- und JPG-Erweiterungen, aber zusätzliche Dateinamen der Form test-1.jpg zu erkennen:
( setq citar-library-file-extensions ( list " pdf " " jpg " )
citar-file-additional-files-separator " - " ) Um zu ändern, wie citar Dateien mit bestimmten Erweiterungen öffnet, passen Sie die in citar-file.el definierte Variable citar-file-open-functions .
Bei Verwendung mit „emboard“ und „consult“ stehen den Kandidaten eine Reihe alternativer Aktionen zur Verfügung.
Bei BibTeX-Einträgen, die über ein „Crossref“-Feld verfügen, ordnet Citar den Schlüssel des Eintrags den Ressourcen (Dateien, Notizen, Links) zu, die mit dem Eintrag, auf den verwiesen wird, verknüpft sind.
Betrachten Sie beispielsweise einen Eintrag für „Baym1965“, der ein „Crossref“-Feld „Meyers1999“ enthält. Wenn citar-open aufgerufen und „Baym1965“ ausgewählt wird, listet der Minipuffer alle Dateien, Notizen und Links auf, die sowohl mit „Baym1965“ als auch mit „Meyers1999“ verknüpft sind. Die richtigen Präfixe, die eine zugehörige Datei, Notiz oder einen Link kennzeichnen, werden ebenfalls bei jedem Kandidaten im Minipuffer aufgeführt.
HINWEIS: Damit die Crossref-Funktion von BibTeX ordnungsgemäß funktioniert, muss der Eintrag mit dem Feld „crossref“ vor dem Eintrag mit Querverweis in der bib-Datei stehen. (Dies ist eine Anforderung von BibTeX, nicht speziell von Citar.) Im obigen Beispiel muss also der Eintrag für „Baym1965“ vor dem Eintrag für „Meyers1999“ stehen.
Es gibt verschiedene Möglichkeiten, Citar zu verwenden.
Citar enthält einen Org-Cite- citar Prozessor mit den Funktionen „Einfügen“, „Aktivieren“ und „Folgen“. Wenn von org-cite die Rede ist, beziehen sich Zitate auf eine Reihe von einer oder mehreren Referenzen (citation-references) , denen jeweils ein Text vorangestellt (Präfix) und ein Text davor (Suffix) stehen kann. Um mehr über org-cite zu erfahren, besuchen Sie die Seite „Zitate“ im Org-Handbuch.
Der „Einfügeprozessor“ verwendet citar-select-refs um Ihre Bibliothek zu durchsuchen, um Zitate und Zitatverweise mit dem Befehl org-cite-insert einzufügen und zu bearbeiten. Der Befehl ist kontextabhängig, daher hängt sein Verhalten von der Position des Punktes in einem Zitat ab . Wenn zum Beispiel Punkt:
Der „Activate-Prozessor“ führt die Liste der Funktionen in citar-org-activation-functions aus, die standardmäßig citar-org-cite-basic-activate verwenden, eine Version des basic von oc-basic um eine Schriftart bereitzustellen, die die Leistung von citar nutzt Caching sowie eine kleine Funktion, die eine Keymap ( citar-org-citation-map ) zum Bearbeiten von Zitaten an der Stelle hinzufügt. Die Tastaturbelegung citar-org-citation-map umfasst die folgenden Bindungen, die zusätzliche Bearbeitungsoptionen für Zitate und Zitationsreferenzen bieten.
| Schlüssel | Bindung | Beschreibung |
|---|---|---|
| Cc Cx DEL | citar-org-delete-citation | Zitat oder Zitat-Referenz an dieser Stelle löschen |
| Cc Cx k | citar-org-kill-citation | Zitat oder Zitat-Referenz an dieser Stelle töten |
| S-<links> | citar-org-shift-reference-left | Zitierungsreferenz an Punkt nach links verschieben |
| S-<rechts> | citar-org-shift-reference-right | Zitat-Referenz an der Stelle nach rechts verschieben |
| MP | citar-org-update-prefix-suffix | Präfix und Suffix der Referenz am Punkt aktualisieren, oder |
| Bei Aufruf mit Präfix arg alle aktualisieren | ||
| Zitat-Referenzen im Zitat an der Stelle | ||
| <mouse-1> | citar-dwim | Rufen Sie den Wert von citar-at-point-function at point auf |
| <mouse-3> | Einschiffungsakt | Rufen Sie embark-act an |
Der „Follow-Prozessor“ bietet At-Point-Funktionalität, auf die über den Befehl org-open-at-point zugegriffen werden kann. Wenn sich point im Organisationsmodus mit Unterstützung für org-cite auf einem Zitat oder einer Zitatreferenz befindet und Sie org-open-at-point aufrufen, wird standardmäßig der Befehlssatz in citar-at-point-function ausgeführt. welches standardmäßig citar-open ist. Wenn Sie den Wert von citar-at-point-function in embark-act ändern, wenn „embark“ installiert und konfiguriert ist, erhalten Sie Zugriff auf die standardmäßigen „citar“-Befehle am Punkt.
Org-Cite-Zitate enthalten optionale „Stile“ und „Varianten“, um die Zitatwiedergabe lokal zu ändern. Wenn Sie ein neues Zitat einfügen, werden Sie durch den Aufruf org-cite-insert mit dem Präfix arg aufgefordert, einen Stil auszuwählen. Um den Stil eines vorhandenen Zitats zu bearbeiten, stellen Sie einfach sicher, dass sich der Punkt auf dem Zitatpräfix befindet, bevor Sie org-cite-insert ausführen. Sie erhalten dann eine Liste der verfügbaren Stile. Diese Liste basiert auf Ihrer Konfiguration; Wenn Sie beispielsweise die Prozessoren oc-natbib und oc-csl konfiguriert haben, enthält die Liste die Stile und Varianten, die in diesen beiden Prozessoren verfügbar sind. Zu den in den gebündelten Prozessoren enthaltenen Varianten gehören die folgenden, wobei die Verknüpfungen in Klammern angegeben sind:
bare ( b ): ohne umgebende Interpunktioncaps ( c ): Erzwingt die anfängliche Großschreibungfull ( f ): Ignorieren Sie die Abkürzung für Autorennamen Im Allgemeinen sollten Sie diese nicht benötigen, sie können jedoch unter bestimmten Umständen nützlich sein. Wenn ein Exportprozessor eine bestimmte Variante für einen bestimmten Stil nicht unterstützt, sollte er einfach auf den Basisstil zurückgreifen. Wenn Sie beispielsweise text/f angeben und der von Ihnen verwendete Exportprozessor die f -Variante dort nicht unterstützt, sollte die Ausgabe einfach so erfolgen, als ob Sie text angegeben hätten.
Mx Führen Sie einfach Mx aus, wählen Sie den gewünschten Befehl aus, geben Sie die Begriffe ein, um den gesuchten Artikel zu finden, und drücken Sie die Eingabetaste. Dadurch wird die Standardaktion ausgeführt: der von Ihnen aufgerufene Befehl.
embark-act auf eine alternative Aktion zu Wenn Sie beim Durchsuchen stattdessen diesen Datensatz lieber bearbeiten möchten und Embark installiert und konfiguriert haben, kommt hier embark-act ins Spiel. Geben Sie einfach die Tastenkombination für embark-act (in meinem Fall Co ) ein und wählen Sie die alternative Aktion aus.
embark-collect-snapshot Eine letzte Option, die nützlich sein kann: Führen Sie embark-collect-snapshot ( S ) von embark-act aus. Dadurch wird die Kandidatenteilmenge ausgewählt und in einem separaten Puffer geöffnet. Von dort aus können Sie dieselben oben beschriebenen Optionen mit embark-act ausführen (das auch an a im Sammelpuffer gebunden ist).
Angenommen, Sie arbeiten an einer Arbeit. Irgendwann in diesem Puffer halten Sie die vollständige Obermenge der Elemente, die Sie zitieren möchten. Von dort aus können Sie nach Belieben verschiedene Aktionen für die Kandidaten ausführen, anstatt einzeln nach jedem Element zu suchen, das Sie zitieren möchten.
citar-dwim Mx citar-dwim führt die Standardaktion direkt auf Zitierschlüssel aus, die an der Stelle gefunden werden. Wenn Sie embark installiert haben, können Sie stattdessen can embark-dwim für dasselbe Verhalten und embark-act für zusätzliche Aktionen an der Stelle verwenden.
Wenn kein Zitierschlüssel gefunden wird, wird der Minipuffer zur Auswahl geöffnet. Sie können dieses Verhalten deaktivieren, indem Sie citar-at-point-fallback auf Null setzen.
Die folgenden Pakete erweitern oder verbessern citar auf andere Weise.
Diese kleinen Pakete stellen Quellen für Zigarrennoten bereit und ermöglichen so eine engere Integration mit den jeweiligen Notizenverwaltungspaketen.
Um zu verstehen, wie citar im Vergleich zu anderen Paketen wie org-ref , ivy-bibtex und helm-bibtex (und dem zugehörigen bibtex-completion ) abschneidet, sehen Sie sich die Vergleichsseite im Wiki an.
Die Ideen zu diesem Projekt wurden zunächst im Gespräch mit Maxime Tréca und Daniel Mendler erarbeitet. Daniel, Autor von Consult und Marginalia, half uns, die Möglichkeiten der neuen Suite von Complete-Read-Paketen zu verstehen, während Maxime einen ersten Prototyp entwickelte.
Dieser Code nimmt diese Ideen auf und implementiert sie erneut, um den Funktionsumfang zu vervollständigen und außerdem die Klarheit und Leistung des Codes zu optimieren.
