docs(biblio,tree-sitter): update READMEs to new format
Also preforms minor spelling, grammar, and formatting corrections.
This commit is contained in:
Henrik Lissner
parent
d6ffd2bfaa
commit
304774cf39
2 changed files with 167 additions and 184 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue