diff --git a/modules/tools/biblio/README.org b/modules/tools/biblio/README.org index 5b7fc461a..feee1edfa 100644 --- a/modules/tools/biblio/README.org +++ b/modules/tools/biblio/README.org @@ -1,151 +1,140 @@ -#+TITLE: tools/biblio -#+DATE: April 11, 2020 -#+SINCE: 21.12.0 (#5290) -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :tools biblio +#+subtitle: Writes a PhD for you (citation needed) +#+created: April 11, 2020 +#+since: 21.12.0 (#5290) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#pdf-viewing][PDF viewing]] - - [[#bibtex-completion][Bibtex completion]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#org-cite][Org-cite]] - - [[#processor-configuration][Processor configuration]] - - [[#other-configuration-options][Other configuration options]] - - [[#path-configuration][Path configuration]] - - [[#templates][Templates]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds tools to help when working with bibliographies and citations. Minimal modifications have been made to the packages and the configuration details are listed in [[*Configuration][Configuration]] below. Some sensible defaults have been selected so it should be possible to use without modifications. ** Maintainers -+ [[https://github.com/bdarcus][bdarcus]] -+ [[https://github.com/brianmcgillion][bmg]] +- [[doom-user:][bdarcus]] +- [[doom-user:][bmg]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/tmalsburg/helm-bibtex][bibtex-completion]] -+ ~:completion vertico~ - + [[https://github.com/bdarcus/citar][citar]] -+ ~:completion helm~ - + [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] -+ ~:completion ivy~ - + [[https://github.com/tmalsburg/helm-bibtex][ivy-bibtex]] +** Module flags +/This module has no flags./ -* Prerequisites -There are no hard dependencies for this module. +** Packages +- [[doom-package:][bibtex-completion]] if [[doom-module:][:completion ivy]] or [[doom-module:][:completion helm]] +- [[doom-package:][citar]] if [[doom-module:][:completion vertico]] +- [[doom-package:][helm-bibtex]] if [[doom-module:][:completion helm]] +- [[doom-package:][ivy-bibtex]] if [[doom-module:][:completion ivy]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +There are no hard dependencies for this module, but this module can benefit from +having a PDF reader and one of Doom's [[doom-module:][:completion]] modules. ** PDF viewing An application for opening PDF files is required. By default =DocView= is used -though it is highly recommended to enable =:tools pdf= in your personal ~init.el~ -file to enable [[https://github.com/politza/pdf-tools][pdf-tools]]. +though [[doom-module:][:tools pdf]] is highly recommended so PDFs can be viewed within Emacs. ** Bibtex completion -For vertico, helm, or ivy bibtex completion you should enable =:completion vertico=, =:completion helm=, or -=:completion ivy= respectively. +For vertico, helm, or ivy bibtex completion you should enable [[doom-module:][:completion +vertico]], [[doom-module:][:completion helm]], or [[doom-module:][:completion ivy]] respectively. -* Features -Both [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] (includes helm-bibtex, ivy-bibtex and bibtex-completion code) -and [[https://github.com/bdarcus/bibtex-actions][citar]] provide an extensive range of features so it is best to check their +* Usage +Both [[doom-package:][helm-bibtex]] (includes [[doom-package:][helm-bibtex]], [[doom-package:][ivy-bibtex]], and bibtex-completion code) +and [[doom-package:][citar]] provide an extensive range of features so it is best to check their respective sites for a full list of features. On a high-level you can expect: -+ bibliography management -+ notes per reference -+ citation support -+ citation lookup -+ org integration for writing literate latex (org-roam) -+ fast indexing and searching of references. +- bibliography management +- notes per reference +- citation support +- citation lookup +- org integration for writing literate latex (org-roam) +- fast indexing and searching of references. -To understand the interaction between these packages this [[https://www.reddit.com/r/emacs/comments/cxu0qg/emacs_org_and_bibtex_as_alternative_to_zotero_and/eyqe4vq/][reddit]] thread will explain -the unique features and the overlapping functionality, if any. +To understand the interaction between these packages this [[https://www.reddit.com/r/emacs/comments/cxu0qg/emacs_org_and_bibtex_as_alternative_to_zotero_and/eyqe4vq/][reddit]] thread will +explain the unique features and the overlapping functionality, if any. -In addition, this module provides support for native Org-mode citations: =org-cite=. +In addition, this module provides support for native Org-mode citations +([[doom-package:][org-cite]]). * Configuration - -For all these packages it is advisable to use ~(after! package)~ in your -~config.el~ to override any default settings and tune the packages to your -needs. +To override any defaults set by this module, do so in an ~(after! package ...)~ +block in =$DOOMDIR/config.el=. ** Org-cite - *** Processor configuration +[[doom-package:][org-cite]] provides rich features and flexible configuration options via its +"processor" capabilities. -=Org-cite= provides rich features and flexible configuration options via its "processor" capabilities. - -1. /insert/ provides =org-cite-insert= integration for inserting and editing citations. +1. /insert/ provides =org-cite-insert= integration for inserting and editing + citations. 2. /activate/ provides fontification, previews, etc. 3. /follow/ integrates contextual citation actions with =org-open-at-point=. 4. /export/ for different output targets. This module makes the following processors available: - 1. The core =oc-basic=, =oc-natbib=, =oc-biblatex=, and =oc-csl=. -2. [[https://github.com/bdarcus/bibtex-actions][citar]] for integration with =vertico= completion. - -The module configures these processors as follows for the different completion modules: +2. [[doom-package:][citar]] for integration with [[doom-package:][vertico]] completion. +The module configures these processors as follows for the different completion +modules: | Feature | Vertico | Ivy | Helm | |----------+---------+----------+----------| | Insert | citar | oc-basic | oc-basic | | Activate | citar | oc-basic | oc-basic | | Follow | citar | oc-basic | oc-basic | - *** Other configuration options - If you like, you can also set the =oc-csl= processor to look in a specific directory for your CSL styles: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (setq org-cite-csl-styles-dir "~/Zotero/styles") -#+END_SRC +#+end_src ** Path configuration - -You must set the path variable for either =citar= (if using =vertico= -completion) or =bibtex-completion= (if using =ivy= or =helm=); this module will -in turn set the =org-cite-global-bibliography= variable to the same value: - -#+BEGIN_src emacs-lisp +You must set the path variable for either [[doom-package:][citar]] (if using [[doom-module:][:completion vertico]]) +or [[doom-package:][bibtex-completion]] (if using [[doom-module::completion ivy][ivy]] or [[doom-module::completion helm][helm]]); this module will in turn set the +[[var:][org-cite-global-bibliography]] variable to the same value: +#+begin_src emacs-lisp (setq! bibtex-completion-bibliography '("/path/to/references.bib")) -#+END_src +#+end_src -#+BEGIN_src emacs-lisp +#+begin_src emacs-lisp (setq! citar-bibliography '("/path/to/references.bib")) -#+END_src +#+end_src You may also set the respective note and library path variables as well for enhanced functionality: - -#+BEGIN_src emacs-lisp +#+begin_src emacs-lisp (setq! bibtex-completion-library-path '("/path/to/library/path/") bibtex-completion-notes-path "/path/to/your/notes/") -#+END_src +#+end_src -#+BEGIN_src emacs-lisp +#+begin_src emacs-lisp (setq! citar-library-paths '("/path/to/library/files/") citar-notes-paths '("/path/to/your/notes/")) -#+END_src +#+end_src ** Templates - This module provides reasonable default templates for the packages. However, if -you wish to change them, refer to the respective packages' documentation for in-depth -instructions. +you wish to change them, refer to the respective packages' documentation for +in-depth instructions. * Troubleshooting -# Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] -Refer to the respective package repositories. +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/tools/tree-sitter/README.org b/modules/tools/tree-sitter/README.org index a38bf71d9..f8c6926ed 100644 --- a/modules/tools/tree-sitter/README.org +++ b/modules/tools/tree-sitter/README.org @@ -1,158 +1,152 @@ -#+TITLE: tools/tree-sitter -#+DATE: August 17, 2021 -#+SINCE: 3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :tools tree-sitter +#+subtitle: Syntax and parsing, sitting in a tree... +#+created: August 17, 2021 +#+since: 22.06.0 (#5401) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#language-support][Language support]] - - [[#text-objects][Text Objects]] - - [[#goto-certain-nodes][Goto certain nodes]] -- [[#configuration][Configuration]] - - [[#rebinding-text-objects][Rebinding text objects]] - - [[#adding-your-own-text-objects][Adding your own text objects]] - - [[#disabling-highlighting-for-certain-modes][Disabling highlighting for certain modes]] -- [[#troubleshooting][Troubleshooting]] - - [[#error-bad-bounding-indices-0-1][=(error "Bad bounding indices: 0, 1")=]] - -* Description - -This module adds [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] support to Doom: +* Description :unfold: +This module adds [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] support to Doom Emacs. #+begin_quote -Tree sitter is a parser generator tool and an incremental parsing library. It -can build a concrete syntax tree for a source file and efficiently update the -syntax tree as the source file is edited. This allows for features of the editor -to become syntax aware. + 💬 Tree sitter is a parser generator tool and an incremental parsing library. + It can build a concrete syntax tree for a source file and efficiently update + the syntax tree as the source file is edited. This allows for features of + the editor to become syntax aware. #+end_quote It includes: - -+ Better syntax highlighting of supported languages. -+ Structural text objects to manipulate functions statements and other code +- Better syntax highlighting of supported languages. +- Structural text objects to manipulate functions statements and other code structures like any other text object. ** Maintainers +- [[doom-user:][@jeetelongname]] -+ @jeetelongname +[[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags +** Module flags +/This module has no flags./ -This module provides no flags. +** Packages +- [[doom-package:][evil-textobj-tree-sitter]] if [[doom-module:][:editor evil +everywhere]] +- [[doom-package:][tree-sitter]] +- [[doom-package:][tree-sitter-langs]] -** Plugins +** Hacks +/No hacks documented for this module./ -+ [[https://github.com/emacs-tree-sitter/elisp-tree-sitter][tree-sitter]] -+ [[https://github.com/emacs-tree-sitter/tree-sitter-langs][tree-sitter-langs]] -+ [[https://github.com/meain/evil-textobj-tree-sitter][evil-textobj-tree-sitter]]* (=:editor evil +everywhere=) +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Prerequisites +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -This module has no prerequisites. +This module has no direct requirements, but some languages may have their own to +fulfill before tree-sitter support works for them. Run ~$ doom doctor~ to find +out what you're missing. + +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Language support - Currently Emacs tree sitter has [[https://github.com/emacs-tree-sitter/tree-sitter-langs/tree/master/repos][parsers for these languages]], and syntax highlighting support for [[https://github.com/emacs-tree-sitter/tree-sitter-langs/tree/master/queries][these languages]] as well as ~typescript-tsx-mode~. -To enable tree sitter for individual languages, add the =+tree-sitter= flag. Check -the module readme of your language for support. +To enable tree-sitter support for specific languages, add the =+tree-sitter= +flag to their respective Doom modules. Check the module readme of your language +for support. ** Text Objects - Not all languages support all text objects (yet). [[https://github.com/nvim-treesitter/nvim-treesitter-textobjects#built-in-textobjects][Here is a table of the text object languages support]]. -Note: Only languages with parsers in Emacs have text object support currently. -Currently text objects are bound to: +#+begin_quote + 🚧 Only languages with parsers in Emacs have text object support at the moment. +#+end_quote +Currently text objects are bound to: | key | text object | |-----+---------------------| -| =A= | parameter list | -| =f= | function definition | -| =F= | function call | -| =C= | class | -| =c= | comment | -| =v= | conditional | -| =l= | loop | +| [[kbd:][A]] | parameter list | +| [[kbd:][f]] | function definition | +| [[kbd:][F]] | function call | +| [[kbd:][C]] | class | +| [[kbd:][c]] | comment | +| [[kbd:][v]] | conditional | +| [[kbd:][l]] | loop | -They are used in a container context (not =vf= but =vaf= or =vif=) +They are used in a container context (not [[kbd:][vf]], but [[kbd:][vaf]] or [[kbd:][vif]]). ** Goto certain nodes - -You can also jump to the next / previous node type in a buffer by using =[g= or =]g= +To jump to the next/previous node, type in a buffer by using [[kbd:][[g]] or [[kbd:][]g]] respectfully, the following key will correspond to the text object you want to jump to. Currently keys are bound to: - | key | text object | |-----+----------------| -| =a= | parameter list | -| =f= | function | -| =F= | function call | -| =c= | comment | -| =C= | class | -| =v= | conditional | -| =l= | loop | +| [[kbd:][a]] | parameter list | +| [[kbd:][f]] | function | +| [[kbd:][F]] | function call | +| [[kbd:][c]] | comment | +| [[kbd:][C]] | class | +| [[kbd:][v]] | conditional | +| [[kbd:][l]] | loop | -* Configuration -** Rebinding text objects - -Rebinding keys is the same as any other key, but do note that they need to be -bound to the keymaps ~+tree-sitter-inner-text-object-map~ or -~+tree-sitter-outer-text-object-map~. +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote +** Rebind text objects +Rebinding keys works the same as rebinding any other key, but text-object keys +must be bound on one or both of the ~+tree-sitter-inner-text-object-map~ or +~+tree-sitter-outer-text-object-map~ keymaps: #+begin_src emacs-lisp (map! (:map +tree-sitter-outer-text-objects-map - "f" nil "f" (evil-textobj-tree-sitter-get-textobj "call.inner") - "F" nil "F" (evil-textobj-tree-sitter-get-textobj "function.inner")) (:map +tree-sitter-inner-text-objects-map - "f" nil "f" (evil-textobj-tree-sitter-get-textobj "call.inner") - "F" nil "F" (evil-textobj-tree-sitter-get-textobj "function.inner"))) #+end_src -** Adding your own text objects -If you wish to [[https://github.com/meain/evil-textobj-tree-sitter#custom-textobjects][add your own custom text objects]] then you need to bind them to -~+tree-sitter-{inner, outer}-text-objects-map~. For example: - +** Add your own text objects +To [[https://github.com/meain/evil-textobj-tree-sitter#custom-textobjects][add your own custom text objects]], bind them to ~+tree-sitter-{inner, +outer}-text-objects-map~: #+begin_src emacs-lisp -(map! (:map +tree-sitter-outer-text-objects-map - "m" (evil-textobj-tree-sitter-get-textobj "import" - '((python-mode . [(import_statement) @import]) - (rust-mode . [(use_declaration) @import]))))) +(map! :map +tree-sitter-outer-text-objects-map + "m" (evil-textobj-tree-sitter-get-textobj "import" + '((python-mode . [(import_statement) @import]) + (rust-mode . [(use_declaration) @import])))) #+end_src -** Disabling highlighting for certain modes - -If you want to disable highlighting by default you can do: - -#+begin_src emacs-lisp -(after! MODE-PACKAGE - (tree-sitter-hl-mode -1)) -#+end_src - -If you only want it for certain modes, then: - +** Disable syntax highlighting for certain modes +To disable syntax highlighting across the board you can do: #+begin_src emacs-lisp (remove-hook 'tree-sitter-after-on-hook #'tree-sitter-hl-mode) +#+end_src -(add-hook 'MAJOR-MODE-HOOK #'tree-sitter-hl-mode) +Then it can be enabled for specific major modes: +#+begin_src emacs-lisp +(add-hook 'MAJOR-MODE-hook #'tree-sitter-hl-mode) #+end_src * Troubleshooting -** =(error "Bad bounding indices: 0, 1")= +[[doom-report:][Report an issue?]] +** =(error "Bad bounding indices: 0, 1")= This means that the text object does not have the underlying query needed. This can be fixed by either adding in a custom query (which would override the current key bound) or [[https://github.com/nvim-treesitter/nvim-treesitter-textobjects/][contributing upstream!]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote