docs(:emacs): update READMEs to new format

This commit is contained in:
Henrik Lissner 2021-10-16 01:23:04 +02:00 committed by Henrik Lissner
parent 9ada400805
commit 73c1dd1338
6 changed files with 290 additions and 148 deletions

View file

@ -1,9 +1,8 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-changelog-search:::emacs nil][Changelog]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:emacs][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :emacs
#+CREATED: August 1, 2021
#+SINCE: v21.12.0
#+SETUPFILE: ../../docs/.setupfile.org
#+TITLE: :emacs
#+CREATED: August 01, 2021
#+SINCE: 21.12.0
* Description
Modules in this category augment and extend the built-in features of Emacs.

View file

@ -1,49 +1,76 @@
#+TITLE: emacs/dired
#+DATE: May 27, 2018
#+SINCE: v2.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::emacs dired][Issues]] ↖ [[doom-module-source:emacs/dired][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :emacs dired
#+SUBTITLE: Making dired pretty [functional]
#+CREATED: February 20, 2017
#+SINCE: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#keybindings][Keybindings]]
- [[#ranger][Ranger]]
* Description :unfold:
This module provides reasonable defaults and augmentations for dired.
* Description
This module provides configuration for dired.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+ranger= Enables dired to be more like [[https://github.com/ranger/ranger][ranger]].
+ =+icons= Enables the display of fancy icons depending on file types in dired
buffers.
** Module flags
- +icons ::
Enables the display of fancy icons depending on file types in dired buffers.
- +ranger ::
Enables dired to be more like [[https://github.com/ranger/ranger][ranger]].
** Plugins
+ [[https://github.com/purcell/diredfl][diredfl]]
+ [[https://github.com/stsquad/dired-rsync][dired-rsync]]
+ [[https://github.com/dgutov/diff-hl/][diff-hl]]
+ [[https://github.com/yqrashawn/fd-dired][fd-dired]]
+ =+ranger=
+ [[https://github.com/ralesi/ranger.el][ranger]]
+ =+icons=
+ [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]]
** Packages
- [[doom-package:][all-the-icons-dired]] if [[doom-module:][+icons]]
- [[doom-package:][diff-hl]]
- [[doom-package:][diredfl]]
- [[doom-package:][dired-rsync]]
- [[doom-package:][fd-dired]]
- [[doom-package:][ranger]] if [[doom-module:][+ranger]]
* Prerequisites
This module has no prerequisites *except on BSDs* where =GNU ls= (~gls~) is
needed for it to work properly (Doom doctor will notify you if it is missing).
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* Keybindings
| Keybind | Description |
|-----------+------------------------------|
| =SPC f d= | Find directory with dired |
| =q= | Exit dired buffer |
| =C-c C-r= | Run =dired-rsync= |
| =C-c C-e= | Rename entries with =wdired= |
** 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.]]
This module has no requirements *except on BSDs* like MacOS or FreeBSD, where
=GNU ls= (aka ~gls~) is required.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
| Keybind | Description |
|---------+----------------------------|
| [[kbd:][SPC f d]] | Find directory with dired |
| [[kbd:][q]] | Exit dired buffer |
| [[kbd:][C-c C-r]] | Run [[doom-package:][dired-rsync]] |
| [[kbd:][C-c C-e]] | Rename entries with [[doom-package:][wdired]] |
Other keybindings can be found on the official [[https://www.gnu.org/software/emacs/refcards/pdf/dired-ref.pdf][Dired reference card]].
** Ranger
If =+ranger= is enabled often a buffer will be opened in minimal ranger mode
(deer-mode). In this case =z P= can be used to toggle between full ranger and
deer-mode.
If [[doom-module:][+ranger]] is enabled often a buffer will be opened in minimal ranger mode
(~deer-mode~). In this case [[kbd:][z P]] can be used to toggle between full ranger and
~deer-mode~.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* 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

View file

@ -0,0 +1,56 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::emacs electric][Issues]] ↖ [[doom-module-source:emacs/electric][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :emacs electric
#+SUBTITLE: Shocking keyword-based electric-indent
#+CREATED: February 21, 2017
#+SINCE: 2.0.0
* Description :unfold:
This module augments the built-in [[doom-package:][electric]] package with keyword-based
indentation (as opposed to character-based).
** Maintainers
- [[doom-user:][@hlissner]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
/This module doesn't install any packages./
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** 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.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* 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

View file

@ -1,36 +1,59 @@
#+TITLE: emacs/ibuffer
#+DATE: October 20, 2019
#+SINCE: v2.1.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::emacs ibuffer][Issues]] ↖ [[doom-module-source:emacs/ibuffer][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :emacs ibuffer
#+SUBTITLE: Edit me like one of your French buffers
#+CREATED: October 20, 2019
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module augments the built-in [[doom-package:][ibuffer]] package.
* Description
This module augments ibuffer.
- Adds project-based grouping of buffers
- Support for file-type icons
- Uses human-readable file-size
+ Adds project-based grouping of buffers
+ Support for file-type icons
+ Uses human-readable file-size
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+icons= Enables filetype icons for buffers
** Module flags
- +icons ::
Enable filetype icons for buffers using [[doom-package:][all-the-icons]].
** Plugins
+ [[https://github.com/purcell/ibuffer-projectile][ibuffer-projectile]]
+ [[https://github.com/purcell/ibuffer-vc][ibuffer-vc]]
** Packages
- [[doom-package:][ibuffer-projectile]]
- [[doom-package:][ibuffer-vc]]
* Prerequisites
This module has no prerequisites.
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* TODO Features
** 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.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* 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

View file

@ -1,68 +1,85 @@
#+TITLE: emacs/undo
#+DATE: April 13, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::emacs undo][Issues]] ↖ [[doom-module-source:emacs/undo][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :emacs undo
#+SUBTITLE: Persistent, smarter undo for your inevitable mistakes
#+CREATED: April 14, 2020
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#disabling-persistent-undo-history][Disabling persistent undo history]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module augments Emacs' built-in undo system to be more intuitive and to
persist across Emacs sessions.
** Maintainers
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
+ =+tree= Uses ~undo-tree~ instead of ~undo-fu~, which is a little less stable,
but offers branching undo history and a visualizer for navigating it.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://gitlab.com/ideasman42/emacs-undo-fu][undo-fu]]
+ [[https://gitlab.com/ideasman42/emacs-undo-fu-session][undo-fu-session]]
+ [[https://github.com/emacsmirror/undo-tree][undo-tree]] (=+tree=)
** Module flags
- +tree ::
Uses [[doom-package:][undo-tree]] instead of [[doom-package:][undo-fu]], which is a little less stable, but offers
branching undo history and a visualizer for navigating it.
** Packages
- [[doom-package:][undo-fu]]
- [[doom-package:][undo-fu-session]]
- [[doom-package:][undo-tree]] if [[doom-module:][+tree]]
** Hacks
+ Both undo-fu and undo-tree have been modified to use zstd to compress undo
- Both undo-fu and undo-tree have been modified to use =zstd= to compress undo
history if it is available.
+ undo-tree only
+ Text properties are stripped from undo history to shrink it.
+ Undo-tree is too chatty about saving its history files. This has be
- undo-tree only
- Text properties are stripped from undo history to shrink it.
- Undo-tree is too chatty about saving its history files. This has be
"silenced". i.e. It's visible in \*Messages\*, but won't appear in your
minibuffer.
+ unfo-fu only
+ Doom defines =undo-fu-mode= to make it easier to add hooks/mode-local
- unfo-fu only
- Doom defines ~undo-fu-mode~ to make it easier to add hooks/mode-local
keybinds.
* Prerequisites
This module has no prerequisites.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Disabling persistent undo history
+ If you are using =+tree=:
#+BEGIN_SRC elisp
- If you are using [[doom-module:][+tree]]:
#+begin_src emacs-lisp
(after! undo-tree
(setq undo-tree-auto-save-history nil))
#+END_SRC
#+end_src
+ If you aren't:
#+BEGIN_SRC elisp
- If you aren't:
#+begin_src emacs-lisp
(remove-hook 'undo-fu-mode-hook #'global-undo-fu-session-mode)
#+END_SRC
#+end_src
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
[[doom-report:][Report an issue?]]
** undo-tree
- Has been known to truncate undo history unpredictably, due to Emacs' undo
cleanup imposing linear undo limits on non-linear undo tree data. Doom already
sets ~undo-limit~, ~undo-strong-limit~, and ~undo-outer-limit~ absurdly high
to mitigate this somewhat.
* 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

View file

@ -1,42 +1,62 @@
#+TITLE: emacs/vc
#+DATE: May 23, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::emacs vc][Issues]] ↖ [[doom-module-source:emacs/vc][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :emacs vc
#+SUBTITLE: Be the difference you want to see in the fringe
#+CREATED: February 20, 2017
#+SINCE: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
This module augments Emacs builtin version control support and provides better integration with git
* Description :unfold:
This module augments Emacs builtin version control support and provides better
integration with =git=.
** Maintainers
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
# A list of linked plugins
+ [[https://github.com/rmuslimov/browse-at-remote][browse-at-remote]]
+ [[https://gitlab.com/pidu/git-timemachine][git-timemachine]]
+ [[https://github.com/magit/git-modes][gitconfig-mode]]
+ [[https://github.com/magit/git-modes][gitignore-mode]]
** Module flags
/This module has no flags./
* Prerequisites
This module has no prerequisites.
** Packages
- [[doom-package:][browse-at-remote]]
- [[doom-package:][git-timemachine]]
- [[doom-package:][gitconfig-mode]]
- [[doom-package:][gitignore-mode]]
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
** Hacks
- Allow [[doom-package:][browse-at-remote]] commands in [[doom-package:][git-timemachine]] buffers to open that file
in your browser at the visited revision.
- [[doom-package:][git-timemachine]] buffers will display revision details in the header-line,
rather than the minibuffer (easier to see).
- [[doom-package:][browse-at-remote]] will fall back to the =master= branch if target is in a
detached state.
** 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.]]
This module only requires [[https://git-scm.com/][Git]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* 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