merge: rewrite-docs

I've omitted docs/*.org from this merge, as there is still work left to
do there, but I am pushing the module docs early so folks can benefit
from the new docs sooner.
This commit is contained in:
Henrik Lissner 2022-08-03 03:23:34 +02:00
commit 1f8bf7accb
No known key found for this signature in database
GPG key ID: B60957CA074D39A3
179 changed files with 13125 additions and 8630 deletions

11
modules/config/README.org Normal file
View file

@ -0,0 +1,11 @@
# -*- mode: doom-docs-org -*-
#+title: :config
#+created: July 29, 2021
#+since: 21.12.0
* Description
Modules in this category provide sane defaults or improve your ability to
configure Emacs. It is best to load these last.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

View file

@ -1,44 +1,69 @@
#+TITLE: :config default
# -*- mode: doom-docs-org -*-
#+title: :config default
#+subtitle: Reasonable defaults for reasonable people
#+created: February 14, 2018
#+since: 2.0.9
* Description :unfold:
This module provides a set of reasonable defaults, including:
+ A Spacemacs-esque keybinding scheme
+ Extra Ex commands for evil-mode users
+ A yasnippet snippets library tailored to Doom emacs
+ A configuration for (almost) universally repeating searches with =;= and =,=
- A Spacemacs-inspired keybinding scheme
- A configuration for (almost) universally repeating searches with [[kbd:][;]] and [[kbd:][,]]
- A [[doom-package:][smartparens]] configuration for smart completion of certain delimiters, like
~/* */~ command blocks in C-languages, ~<?php ?>~ tags in PHP, or ~def end~ in
Ruby/Crystal/etc.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +bindings :: ...
- +smartparens :: ...
** Packages
- [[doom-package:][avy]]
- [[doom-package:][drag-stuff]]
- [[doom-package:][link-hint]]
- [[doom-package:][expand-region]] unless [[doom-module:][:editor evil]]
** Hacks
- ~epa-pinentry-mode~ is set to ~'loopback~, forcing gpg-agent to use the Emacs
minibuffer when prompting for your passphrase. *Only works with GPG 2.1+!*
** 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
The defaults module is intended as a "reasonable-defaults" module, but also as a
reference for your own private modules. You'll find [[https://github.com/hlissner/doom-emacs-private][my private module in a
separate repo]].
Refer to the [[https://github.com/hlissner/doom-emacs/wiki/Customization][Customization page]] on the wiki for details on starting your own
private module.
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Table of Contents :TOC:
- [[#install][Install]]
- [[#configuration][Configuration]]
- [[#im-not-an-evil-user][I'm not an evil user...]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
- [[#hacks][Hacks]]
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Install
This module has no external dependencies.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Configuration
** I'm not an evil user...
That's fine. All evil configuration is ignored if =:editor evil= is disabled.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote
* Appendix
** Commands
+ ~+default/browse-project~
+ ~+default/browse-templates~
+ ~+default/find-in-templates~
+ ~+default/browse-notes~
+ ~+default/find-in-notes~
+ ~+default/find-in-snippets~
** Hacks
+ ~epa-pinentry-mode~ is set to ~'loopback~, forcing gpg-agent to use the Emacs
minibuffer when prompting for your passphrase. *Only works with GPG 2.1+!*
- ~+default/browse-project~
- ~+default/browse-templates~
- ~+default/find-in-templates~
- ~+default/browse-notes~
- ~+default/find-in-notes~
- ~+default/find-in-snippets~

View file

@ -1,106 +1,125 @@
#+TITLE: config/literate
#+DATE: May 4, 2020
#+SINCE: v2.0.9
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :config literate
#+subtitle: Disguise your config as poor documentation
#+created: May 28, 2020
#+since: 2.0.9
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#change-the-location-of-configorg][Change the location of config.org]]
- [[#change-where-src-blocks-are-tangled-or-prevent-it-entirely][Change where src blocks are tangled or prevent it entirely]]
- [[#troubleshooting][Troubleshooting]]
- [[#how-to-tangle-to-doomdirinitel][How to tangle to =DOOMDIR/init.el=]]
- [[#how-to-disable-tangle-on-save][How to disable tangle-on-save]]
* Description
* Description :unfold:
This module enables support for a literate config.
A literate config consists of a =DOOMDIR/config.org=. All src blocks within are
tangled =DOOMDIR/config.el=, by default, when ~doom sync~ is executed.
A literate config consists of a =$DOOMDIR/config.org=. All src blocks within are
tangled =$DOOMDIR/config.el=, by default, when ~$ doom sync~ is executed.
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
This module installs no plugins.
** Packages
/This module doesn't install any packages./
* Prerequisites
This module has no prerequisites.
** Hacks
/No hacks documented for this module./
* Features
+ Automatically tangles ~config.org~ to ~config.el~ when saving. See
Troubleshooting section belong on how to disable it.
** 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 a =$DOOMDIR/config.org=, which will be tangled into
=$DOOMDIR/config.el= when you run ~$ doom sync~.
#+begin_quote
🚧 *Be careful!* Enabling this module will overwrite =$DOOMDIR/config.el=! If
you are only trying out the module, *back up this file first!*
#+end_quote
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- Automatically tangles =$DOOMDIR/config.org= to =$DOOMDIR/config.el= when
saving. See [[*Troubleshooting][Troubleshooting]] section belong on how to disable it.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Change the location of config.org
The ~+literate-config-file~ variable controls where to look for your config.org.
To change this it must be modified early -- in =DOOMDIR/init.el= or
=DOOMDIR/cli.el=.
To change this it must be modified early -- in =$DOOMDIR/init.el= or
=$DOOMDIR/cli.el=.
Source blocks needs to be in some language to be automatically tangled, for
example ~#+BEGIN_SRC elisp~, but it doesn't matter what language is used. All
blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax
example ~#+begin_src emacs-lisp~, but it doesn't matter what language is used.
All blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax
highlighting. If you don't want to specify language in block you can also
enforce tangling by adding ~#+BEGIN_SRC :tangle yes~
enforce tangling by adding ~#+begin_src :tangle yes~
** Change where src blocks are tangled or prevent it entirely
By default, this module tangles all src emacs-lisp blocks to config.el unless
otherwise specified.
To specify otherwise use the =:tangle= parameter to:
To specify otherwise use the ~:tangle~ parameter to:
- Specify a destination other than config.el: ~:tangle packages.el~
- Disable tangling of the block altogether with ~:tangle no~
- Or force non-elisp src blocks to tangle somewhere
For example:
#+BEGIN_SRC org
,#+BEGIN_SRC elisp :tangle no
#+begin_src org
,#+begin_src emacs-lisp :tangle no
(message "Don't tangle me")
,#+END_SRC
,#+end_src
,#+BEGIN_SRC elisp :tangle packages.el
,#+begin_src emacs-lisp :tangle packages.el
(package! my-package)
(package! other-package)
,#+END_SRC
,#+end_src
,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
#!/usr/bin/env bash
echo Hello world
,#+END_SRC
,#+end_src
,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
echo Hello world
,#+END_SRC
#+END_SRC
,#+end_src
#+end_src
You'll find more information about babel src blocks and what parameters they
support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the manual]].
support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the Org manual]].
* Troubleshooting
** How to tangle to =DOOMDIR/init.el=
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** How do I tangle to =$DOOMDIR/init.el=?
If your literate needs are more complex (e.g. you want to make your init.el
literate), this module won't cut it. =init.el= is loaded long before
=config.org= is tangled in the ~doom sync~ process.
literate), this module won't cut it. =init.el= files in modules are loaded long
before =config.org= is tangled in the ~$ doom sync~ process.
However, Doom comes with a [[file:../../../bin/org-tangle][bin/org-tangle]] script which can be used to tangle
arbitrary org files from the command line. Use it to create your own compilation
workflows. This is /much/ faster than using ~org-babel-load-file~ directly to
load your literate config every time Doom is started.
** How to disable tangle-on-save
** How do I disable tangle-on-save?
There are occasions where tangling on save may be undesirable. Maybe it's too
slow, produces too much noise, or happens too often (on unrelated org files in
your =DOOMDIR=). This behavior can be disabled with:
#+BEGIN_SRC elisp
;; add to DOOMDIR/config.el
your =$DOOMDIR=). This behavior can be disabled with:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(remove-hook 'org-mode-hook #'+literate-enable-recompile-h)
#+END_SRC
#+end_src
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote