docs(biblio,tree-sitter): update READMEs to new format

Also preforms minor spelling, grammar, and formatting corrections.

modules/tools/biblio/README.org

@@ -1,151 +1,140 @@
-#+TITLE:   tools/biblio
+# -*- mode: doom-docs-org -*-
-#+DATE:    April 11, 2020
+#+title:    :tools biblio
-#+SINCE:   21.12.0 (#5290)
+#+subtitle: Writes a PhD for you (citation needed)
-#+STARTUP: inlineimages
+#+created:  April 11, 2020
+#+since:    21.12.0 (#5290)
 
-* Table of Contents :TOC_3:noexport:
+* Description :unfold:
-- [[#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
 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]]
+- [[doom-user:][bdarcus]]
-+ [[https://github.com/brianmcgillion][bmg]]
+- [[doom-user:][bmg]]
 
-** Module Flags
+[[doom-contrib-maintainer:][Become a maintainer?]]
-This module provides no flags.
 
-** Plugins
+** Module flags
-+  [[https://github.com/tmalsburg/helm-bibtex][bibtex-completion]]
+/This module has no flags./
-+ ~: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]]
 
-* Prerequisites
+** Packages
-There are no hard dependencies for this module.
+- [[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~
+though [[doom-module:][:tools pdf]] is highly recommended so PDFs can be viewed within Emacs.
-file to enable [[https://github.com/politza/pdf-tools][pdf-tools]].
 
 ** Bibtex completion
-For vertico, helm, or ivy bibtex completion you should enable =:completion vertico=, =:completion helm=, or
+For vertico, helm, or ivy bibtex completion you should enable [[doom-module:][:completion
-=:completion ivy= respectively.
+vertico]], [[doom-module:][:completion helm]], or [[doom-module:][:completion ivy]] respectively.
 
-* Features
+* Usage
-Both [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] (includes helm-bibtex, ivy-bibtex and bibtex-completion code)
+Both [[doom-package:][helm-bibtex]] (includes [[doom-package:][helm-bibtex]], [[doom-package:][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
+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
+- bibliography management
-+ notes per reference
+- notes per reference
-+ citation support
+- citation support
-+ citation lookup
+- citation lookup
-+ org integration for writing literate latex (org-roam)
+- org integration for writing literate latex (org-roam)
-+ fast indexing and searching of references.
+- 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
+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
-the unique features and the overlapping functionality, if any.
+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
-
+To override any defaults set by this module, do so in an ~(after! package ...)~
-For all these packages it is advisable to use ~(after! package)~ in your
+block in =$DOOMDIR/config.el=.
-~config.el~ to override any default settings and tune the packages to your
-needs.
 
 ** 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.
+2. [[doom-package:][citar]] for integration with [[doom-package:][vertico]] completion.
-
-The module configures these processors as follows for the different completion modules:
 
+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 [[doom-package:][citar]] (if using [[doom-module:][:completion vertico]])
-You must set the path variable for either =citar= (if using =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
-completion) or =bibtex-completion= (if using =ivy= or =helm=); this module will
+[[var:][org-cite-global-bibliography]] variable to the same value:
-in turn set the =org-cite-global-bibliography= variable to the same value:
+#+begin_src emacs-lisp
-
-#+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
+you wish to change them, refer to the respective packages' documentation for
-instructions.
+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

modules/tools/tree-sitter/README.org

@@ -1,158 +1,152 @@
-#+TITLE:   tools/tree-sitter
+# -*- mode: doom-docs-org -*-
-#+DATE:    August 17, 2021
+#+title:    :tools tree-sitter
-#+SINCE:   3.0.0
+#+subtitle: Syntax and parsing, sitting in a tree...
-#+STARTUP: inlineimages nofold
+#+created:  August 17, 2021
+#+since:    22.06.0 (#5401)
 
-* Table of Contents :TOC_3:noexport:
+* Description :unfold:
-- [[#description][Description]]
+This module adds [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] support to Doom Emacs.
-  - [[#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:
 
 #+begin_quote
-Tree sitter is a parser generator tool and an incremental parsing library. It
+ 💬 Tree sitter is a parser generator tool and an incremental parsing library.
-can build a concrete syntax tree for a source file and efficiently update the
+    It can build a concrete syntax tree for a source file and efficiently update
-syntax tree as the source file is edited. This allows for features of the editor
+    the syntax tree as the source file is edited. This allows for features of
-to become syntax aware.
+    the editor to become syntax aware.
 #+end_quote
 
 It includes:
-
+- Better syntax highlighting of supported languages.
-+ Better syntax highlighting of supported languages.
+- Structural text objects to manipulate functions statements and other code
-+ 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]]
+** TODO Changelog
-+ [[https://github.com/emacs-tree-sitter/tree-sitter-langs][tree-sitter-langs]]
+# This section will be machine generated. Don't edit it by hand.
-+ [[https://github.com/meain/evil-textobj-tree-sitter][evil-textobj-tree-sitter]]* (=:editor evil +everywhere=)
+/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
+To enable tree-sitter support for specific languages, add the =+tree-sitter=
-the module readme of your language for support.
+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.
+#+begin_quote
-Currently text objects are bound to:
+ 🚧 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      |
+| [[kbd:][A]]   | parameter list      |
-| =f=   | function definition |
+| [[kbd:][f]]   | function definition |
-| =F=   | function call       |
+| [[kbd:][F]]   | function call       |
-| =C=   | class               |
+| [[kbd:][C]]   | class               |
-| =c=   | comment             |
+| [[kbd:][c]]   | comment             |
-| =v=   | conditional         |
+| [[kbd:][v]]   | conditional         |
-| =l=   | loop                |
+| [[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
-
+To jump to the next/previous node, type in a buffer by using [[kbd:][[g]] or [[kbd:][]g]]
-You can also jump to the next / previous node type in a buffer by using =[g= or =]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 |
+| [[kbd:][a]]   | parameter list |
-| =f=   | function       |
+| [[kbd:][f]]   | function       |
-| =F=   | function call  |
+| [[kbd:][F]]   | function call  |
-| =c=   | comment        |
+| [[kbd:][c]]   | comment        |
-| =C=   | class          |
+| [[kbd:][C]]   | class          |
-| =v=   | conditional    |
+| [[kbd:][v]]   | conditional    |
-| =l=   | loop           |
+| [[kbd:][l]]   | loop           |
 
-* Configuration
+* TODO Configuration
-** Rebinding text objects
+#+begin_quote
-
+ 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
-Rebinding keys is the same as any other key, but do note that they need to be
+#+end_quote
-bound to the keymaps ~+tree-sitter-inner-text-object-map~ or
-~+tree-sitter-outer-text-object-map~.
 
+** 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
+** Add 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
+To [[https://github.com/meain/evil-textobj-tree-sitter#custom-textobjects][add your own custom text objects]], bind them to ~+tree-sitter-{inner,
-~+tree-sitter-{inner, outer}-text-objects-map~. For example:
+outer}-text-objects-map~:
-
 #+begin_src emacs-lisp
-(map! (:map +tree-sitter-outer-text-objects-map
+(map! :map +tree-sitter-outer-text-objects-map
-       "m" (evil-textobj-tree-sitter-get-textobj "import"
+      "m" (evil-textobj-tree-sitter-get-textobj "import"
-             '((python-mode . [(import_statement) @import])
+            '((python-mode . [(import_statement) @import])
-               (rust-mode . [(use_declaration) @import])))))
+              (rust-mode . [(use_declaration) @import]))))
 #+end_src
 
-** Disabling highlighting for certain modes
+** Disable syntax highlighting for certain modes
-
+To disable syntax highlighting across the board you can do:
-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:
-
 #+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