citar
v1.3.0 - configurable indicators
Citar menyediakan front-end completing-read yang sangat dapat dikonfigurasi untuk menelusuri dan bertindak berdasarkan data bibliografi BibTeX, BibLaTeX, dan CSL JSON, serta dukungan pengeditan LaTeX, penurunan harga, dan kutipan organisasi.
citar-embark kecil, yang menyediakan tindakan kontekstual di minibuffer, dan juga di buffer organisasi, penurunan harga, dan LaTeX.org-roam , denote , dan zkBerikut tangkapan layar dengan penyesuaian vertico dan simbol di bawah.
Dan inilah citar-capf dalam buffer penurunan harga.
Untuk melihat citar beraksi dengan org-cite, Anda dapat menonton presentasi Emacs Conf 2021 oleh Ahmed Khaled.
Ada berbagai cara untuk menginstal citar:
vertico .emacs-citar .Selain itu, paket berikut sangat disarankan untuk pengalaman terbaik.
Secara khusus, jika Anda ingin mempersempit pencarian Anda menggunakan penulis, judul, dll (yaitu, tidak hanya kunci kutipan), Anda perlu menggunakan gaya penyelesaian yang tidak bergantung pada urutan; misalnya, Tanpa pesanan dengan completion-styles yang disetel ke (orderless basic) (lihat contoh konfigurasi).
Kami juga merekomendasikan Emacs 28 atau lebih baru.
Ini adalah konfigurasi minimal, dan akan bekerja dengan UI penyelesaian vertikal yang sesuai dengan penyelesaian-baca, seperti Vertico, atau icomplete-vertical bawaan, dengan tindakan yang tersedia melalui perintah Mx .
( use-package citar
:custom
(citar-bibliography '( " ~/bib/references.bib " )))citar-capf Paket ini menyertakan fungsi completion-at-point untuk menyelesaikan kunci kutipan di buffer, yang dapat Anda konfigurasikan seperti ini:
( use-package citar
:custom
(citar-bibliography '( " ~/bib/references.bib " ))
:hook
( LaTeX-mode . citar-capf-setup)
( org-mode . citar-capf-setup)) Paket citar-embark menambahkan tindakan akses kontekstual di minibuffer dan at-point melalui mode minor citar-embark-mode .
Saat menggunakan Embark, tindakan Citar bersifat umum, dan berfungsi sama di seluruh mode organisasi, penurunan harga, dan lateks.
( use-package citar-embark
:after citar embark
:no-require
:config (citar-embark-mode)) Ini menunjukkan tindakan buffer yang disediakan oleh citar-embark :
Jika Anda ingin menggunakan Citar hanya dalam Org-Mode, ini adalah pilihan terbaik.
( 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 ))) Anda dapat menyisipkan kutipan dengan perintah org-cite-insert , yang terikat pada Cc Cx C-@ dalam buffer Mode-Org. Perintah opsional :bind di atas juga memberikan pengikatan Cc b yang lebih pendek.
Jika Anda lebih suka membuka menu Embark dengan org-open-at-point , Anda harus mengatur variabel ini.
( setq citar-at-point-function 'embark-act ) Namun, Anda dapat memanggil embark-act dan embark-dwim secara terpisah dari org-at-point , dan dalam mode lain seperti latex-mode .
Citar menyertakan kerangka adaptor untuk mengaktifkan integrasi pengeditan khusus mode utama. Adaptor tersebut dapat memberikan kemampuan berikut, yang dapat dikonfigurasi dengan daftar citar-major-mode-functions :
insert-keys : untuk memasukkan kunci kutipan (meskipun ini mungkin hilang)insert-citation : untuk menyisipkan kutipaninsert-edit : untuk menyisipkan kutipan atau mengedit pada suatu titiklocal-bib-files : untuk menemukan file bibliografi yang terkait dengan bufferkey-at-point : mengembalikan kunci kutipan pada titikcitation-at-point : mengembalikan daftar kunci dalam kutipan pada titikCitar saat ini menyertakan adaptor berikut:
citar-org : secara default, hanya mendukung org-cite , tetapi dapat dikonfigurasi untuk format laincitar-latex : dukungan bibtex, natbib dan biblatex yang dapat dikonfigurasi (membutuhkan AUCTeX)citar-markdown : secara default, hanya mendukung sintaks kutipan pandocTak satu pun dari ini memerlukan konfigurasi apa pun, dan harus dimuat sesuai kebutuhan.
Perintah citar-open-entry akan membuka entri data sumber. Anda dapat mengonfigurasinya menggunakan citar-open-entry-function . Secara default, ini menggunakan citar-open-entry-in-file , yang akan membuka file bibliografi yang relevan dan memindahkan titik ke entri. Opsi lain yang disertakan adalah citar-open-entry-in-zotero , yang akan memilih item di Zotero. Perhatikan bahwa fungsionalitas bergantung pada Better BibTeX (yang tetap harus Anda gunakan!).
Ada tiga bagian UI penjelajahan.
Anda dapat mencari berdasarkan semua konten di atas. Untuk awalan, Anda dapat memfilter file atau catatan terkait masing-masing menggunakan has:file atau has:notes (dan setidaknya dengan orderless , bahkan singkatan :p atau :n ).
Variabel citar-templates mengonfigurasi pemformatan untuk bagian ini, serta fungsi catatan default. Inilah nilai defaultnya:
( 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} " )))Catatan:
% mendahului token yang didefinisikan sebagai kunci dalam citar-display-transform-functions , yang nilainya berupa daftar fungsi dan argumen opsional. Perhatikan bahwa jika Anda menyertakan ini, jika Anda juga menyertakan spesifikasi lebar, spesifikasi tersebut harus berada setelah lebar.UI menyertakan indikator yang dapat dikonfigurasi. Secara default, ini menyertakan indikator teks biasa, yang masing-masing menunjukkan keberadaan sumber daya berbeda yang terkait dengan referensi:
Untuk indikator lainnya, lihat wiki.
Berikut tangkapan layar menggunakan konfigurasi ini, yang menghilangkan indikator tautan, dan menggabungkan teks biasa dan indikator ikon menggunakan all-the-icons .
( setq citar-indicators
( list citar-indicator-files ; plain text
citar-indicator-notes-icons)) ; icon 
Tentu saja, Anda dapat membuat indikator sendiri. Berikut ini contoh definisi indikator yang menggabungkan ikon:
( 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 " ))Namun perlu diingat, fungsi predikat yang disertakan harus dioptimalkan kinerjanya, karena UI penyelesaian menjalankannya di seluruh perpustakaan Anda setiap kali Anda membukanya.
Nerd-icons.el adalah perpustakaan untuk dengan mudah menggunakan ikon Nerd Font di dalam Emacs, sebuah alternatif untuk semua ikon, dan merupakan paket ikon yang sudah disertakan dalam Doom Emacs. Berikut ini contoh untuk mendapatkan tampilan serupa:
( 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)) Direktori test repositori juga menyertakan skrip yang dapat Anda gunakan untuk menjalankan ini dan paket terkait di kotak pasir emacs -Q . Untuk melakukan itu, cukup jalankan ./run.sh dari direktori test .
citar memiliki fungsi yang mirip dengan fungsi pencarian yang telah ditentukan sebelumnya di helm-bibtex dan ivy-bibtex , tetapi dengan implementasi yang berbeda. Daripada membuat perintah baru dengan istilah pencarian sebagai argumen, Anda cukup mengatur variabel citar-presets , dan menambahkan string yang ingin Anda akses:
( setq citar-presets '( " one search string " " another search string " ))Anda kemudian memiliki dua cara untuk mengakses string ini dari perintah penyelesaian:
Mn dari prompt, yang akan menelusuri stringcitar-insert-preset dengan pengikatan tombol, lalu memilih string citar juga menyimpan riwayat pilihan Anda (lihat peringatan di bawah tentang pemilihan beberapa kandidat), yang juga dapat diakses di UI penyelesaian Anda, tetapi dengan menggunakan Mp . Anda dapat menyimpan riwayat ini di seluruh sesi dengan menambahkan citar-history ke savehist-additional-variables .
Citar menggunakan cache untuk mempercepat tampilan perpustakaan. Jika file bib berubah, cache akan diperbarui secara otomatis saat berikutnya Anda menjalankan perintah Citar.
Perhatikan bahwa data cache yang telah diformat sebelumnya, kandidat penyelesaian dilacak secara independen berdasarkan file. Jadi, misalnya, jika Anda memiliki satu file bibliografi sangat besar yang banyak berubah, Anda mungkin mempertimbangkan untuk membaginya menjadi satu file besar yang lebih stabil, dan satu atau lebih file kecil yang lebih sering berubah.
Citar menawarkan pencatatan yang dapat dikonfigurasi dan integrasi akses. Variabel citar-notes-sources mengonfigurasi backend catatan, dan citar-notes-source mengaktifkan backend pilihan Anda.
Backend terutama menentukan fungsi untuk memperbarui tampilan Citar, untuk membuat kandidat penyelesaian, dan untuk membuka catatan yang sudah ada dan baru. Lihat dokumen citar-notes-sources untuk detailnya, dan fungsi kenyamanan citar-register-notes-source dan citar-remove-notes-source .
Jika Anda telah menyetel citar-library-paths , perintah terbuka yang relevan akan mencari nama file CITEKEY.EXTENSION di direktori tersebut. Mereka juga akan mengurai isi kolom file. Variabel citar-file-parser-functions mengatur parser mana yang akan digunakan, dan ada dua parser yang disertakan:
citar-file-parser-default berfungsi untuk daftar jalur file sederhana yang dibatasi titik dua atau titik koma, seperti di Zotero.citar-file-parser-triplet berfungsi untuk Mendeley dan Calibre, yang merepresentasikan file menggunakan format seperti :/path/file.pdf:PDF .Jika Anda memiliki campuran entri yang dibuat dengan Zotero dan Calibre, Anda dapat mengaturnya seperti ini dan keduanya akan diurai:
( setq citar-file-parser-functions
'(citar-file-parser-default
citar-file-parser-triplet)) Variabel citar-library-file-extensions mengatur ekstensi file mana yang akan dikenali oleh perintah terbuka; ketika `nil`, ia akan mengenali semua ekstensi. Variabel citar-file-additional-files-separator mendefinisikan pola apa yang harus diidentifikasi citar untuk beberapa file perpustakaan untuk kunci referensi yang sama. Berikut contoh untuk hanya mengenali ekstensi pdf dan jpg, tetapi nama file tambahan berupa test-1.jpg :
( setq citar-library-file-extensions ( list " pdf " " jpg " )
citar-file-additional-files-separator " - " ) Untuk mengubah cara citar membuka file dengan ekstensi tertentu, sesuaikan variabel citar-file-open-functions yang ditentukan dalam citar-file.el .
Bila digunakan dengan memulai dan berkonsultasi, Anda akan memiliki serangkaian tindakan alternatif yang tersedia bagi para kandidat.
Untuk entri BibTeX yang memiliki kolom 'crossref', Citar akan mengaitkan kunci entri tersebut dengan sumber daya (file, catatan, tautan) yang terkait dengan entri referensi silang.
Misalnya: pertimbangkan entri untuk “Baym1965” yang memiliki kolom 'crossref' “Meyers1999”. Ketika citar-open dipanggil dan “Baym1965” dipilih, minibuffer akan mencantumkan semua file, catatan, dan tautan yang terkait dengan “Baym1965” dan “Meyers1999”. Awalan yang tepat, yang menunjukkan file, catatan, atau tautan terkait, juga akan dicantumkan bersama setiap kandidat di minibuffer.
CATATAN: Agar fitur crossref BibTeX berfungsi dengan baik, entri dengan kolom 'crossref' harus diletakkan sebelum entri referensi silang dalam file bib. (Ini adalah persyaratan BibTeX, bukan Citar secara spesifik.) Maka, dalam contoh di atas, entri untuk “Baym1965” harus berada sebelum entri untuk “Meyers1999”.
Anda memiliki beberapa cara berbeda untuk menggunakan citar.
Citar menyertakan prosesor citar org-cite, dengan kemampuan “masukkan”, “aktifkan”, dan “ikuti”. Ketika berbicara tentang org-cite, kutipan mengacu pada sekumpulan satu atau lebih referensi (referensi-kutipan) , yang masing-masing mungkin memiliki teks yang mendahuluinya (awalan) dan teks yang melanjutkannya (akhiran). Untuk mempelajari lebih lanjut tentang org-cite, kunjungi halaman Kutipan di Manual Org.
"Pemroses sisipkan" menggunakan citar-select-refs untuk menjelajahi perpustakaan Anda guna menyisipkan dan mengedit kutipan dan referensi kutipan menggunakan perintah org-cite-insert . Perintah ini sadar konteks, sehingga perilakunya bergantung pada lokasi titik dalam kutipan . Misalnya, jika titik:
“activate processor” menjalankan daftar fungsi di citar-org-activation-functions , yang secara default menggunakan citar-org-cite-basic-activate , versi prosesor basic dari oc-basic untuk menyediakan fontifikasi yang memanfaatkan kinerja citar caching, serta sedikit fungsi yang menambahkan keymap ( citar-org-citation-map ) untuk mengedit kutipan pada saat itu. Peta kunci citar-org-citation-map mencakup pengikatan berikut yang menyediakan opsi pengeditan kutipan dan referensi kutipan tambahan.
| kunci | mengikat | keterangan |
|---|---|---|
| Cc Cx DEL | citar-org-hapus-kutipan | hapus kutipan atau referensi kutipan pada titik tersebut |
| Cc Cxk | citar-org-bunuh-kutipan | bunuh kutipan atau referensi kutipan pada titik tersebut |
| S-<kiri> | citar-org-shift-referensi-kiri | pindahkan referensi kutipan di titik kiri |
| S-<kanan> | citar-org-shift-referensi-kanan | pindahkan referensi kutipan ke titik kanan |
| Mp | citar-org-update-awalan-akhiran | memperbarui awalan dan akhiran referensi pada titik, atau, |
| ketika dipanggil dengan awalan arg, perbarui semua | ||
| referensi kutipan dalam kutipan pada titik | ||
| <mouse-1> | citar-dwim | panggil nilai citar-at-point-function di titik |
| <tikus-3> | memulai tindakan | sebut embark-act pada saat itu |
“Follow processor” menyediakan fungsionalitas at-point yang dapat diakses melalui perintah org-open-at-point . Secara default, dalam mode-org dengan dukungan org-cite, ketika titik berada pada kutipan atau referensi-kutipan, dan Anda memanggil org-open-at-point , perintah yang diatur dalam citar-at-point-function akan dijalankan. yang merupakan citar-open secara default. Mengubah nilai citar-at-point-function untuk embark-act dengan embark diinstal dan dikonfigurasi akan memberikan akses ke perintah citar standar pada titik.
Kutipan kutipan organisasi menyertakan “gaya” dan “varian” opsional untuk mengubah rendering kutipan secara lokal. Saat menyisipkan kutipan baru, memanggil org-cite-insert dengan awalan arg akan meminta untuk memilih gaya. Untuk mengedit gaya kutipan yang sudah ada, pastikan titik berada pada awalan kutipan sebelum menjalankan org-cite-insert , dan Anda akan mendapatkan daftar gaya yang tersedia. Daftar itu didasarkan pada konfigurasi Anda; jika Anda memiliki prosesor oc-natbib dan oc-csl yang dikonfigurasi, misalnya, daftar tersebut akan menyertakan gaya dan varian yang tersedia di kedua prosesor tersebut. Varian yang disertakan dalam paket prosesor meliputi berikut ini, dengan pintasan dalam tanda kurung:
bare ( b ): tanpa tanda baca di sekitarnyacaps ( c ): memaksakan kapitalisasi awalfull ( f ): abaikan dkk kependekan nama penulis Secara umum, Anda tidak memerlukannya, namun dapat berguna dalam keadaan tertentu. Jika prosesor ekspor tidak mendukung varian tertentu untuk gaya tertentu, prosesor tersebut sebaiknya mundur ke gaya dasar. Misalnya, jika Anda menentukan text/f , dan prosesor ekspor yang Anda gunakan tidak mendukung varian f di sana, outputnya akan seperti jika Anda menentukan text .
Mx Cukup lakukan Mx dan pilih perintah yang Anda inginkan, masukkan istilah untuk menemukan item yang Anda cari, dan tekan kembali. Ini menjalankan tindakan default: perintah yang Anda panggil.
embark-act Jika saat browsing Anda lebih suka mengedit catatan itu, dan Anda telah menginstal dan mengkonfigurasi, di sinilah embark-act berperan. Cukup masukkan pengikatan tombol untuk embark-act (dalam kasus saya Co ), dan pilih tindakan alternatif.
embark-collect-snapshot Opsi terakhir, yang mungkin berguna: jalankan embark-collect-snapshot ( S ) dari embark-act . Ini akan memilih subset kandidat, dan membukanya di buffer terpisah. Dari sana, Anda dapat menjalankan opsi yang sama yang dibahas di atas menggunakan embark-act (yang juga terikat a buffer pengumpulan).
Jadi, misalnya, Anda sedang mengerjakan sebuah makalah. Anda memegang kumpulan super lengkap item yang ingin Anda kutip pada titik tertentu di buffer itu. Dari sana, Anda dapat menjalankan tindakan berbeda pada kandidat sesuai keinginan, daripada mencari satu per satu untuk setiap item yang ingin Anda kutip.
citar-dwim Mx citar-dwim akan menjalankan tindakan default pada kunci kutipan yang ditemukan secara langsung. Jika Anda sudah embark , Anda dapat menggunakan can embark-dwim untuk perilaku yang sama, dan embark-act untuk tindakan tambahan pada saat itu.
Jika tidak ada kunci kutipan yang ditemukan, minibuffer akan terbuka untuk dipilih. Anda dapat menonaktifkan perilaku ini dengan menyetel citar-at-point-fallback ke nil.
Paket-paket berikut memperluas atau meningkatkan citar.
Paket-paket kecil ini menyediakan sumber catatan citar, dan integrasi yang lebih erat dengan masing-masing paket manajemen catatan.
Untuk memahami bagaimana citar dibandingkan dengan paket lain seperti org-ref , ivy-bibtex dan helm-bibtex (dan bibtex-completion terkait), lihat halaman perbandingan di wiki.
Ide-ide dalam proyek ini awalnya diwujudkan dalam percakapan dengan Maxime Tréca dan Daniel Mendler. Daniel, penulis konsultasi dan marginalia, membantu kami memahami kemungkinan rangkaian baru paket penyelesaian-baca, sementara Maxime membuat prototipe awal.
Kode ini mengambil ide-ide tersebut dan mengimplementasikannya kembali untuk melengkapi rangkaian fitur, dan juga mengoptimalkan kejelasan dan kinerja kode.
