diff --git a/modules/config/README.org b/modules/config/README.org index a281f7866..d323876ad 100644 --- a/modules/config/README.org +++ b/modules/config/README.org @@ -1,10 +1,9 @@ -← [[doom-module-index:][Back to module index]] ↙ [[doom-changelog-search:::config nil][Changelog]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:config][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] -------------------------------------------------------------------------------- -#+TITLE: :config -#+CREATED: July 29, 2021 -#+SINCE: v21.12.0 -#+SETUPFILE: ../../docs/.setupfile.org +#+TITLE: :config +#+CREATED: July 29, 2021 +#+SINCE: 21.12.0 * Description -Modules that configure Emacs one way or another, or focus on making it easier -for you to customize it yourself. It is best to load these last. +Modules in this category provide sane defaults or improve your ability to +configure Emacs. It is best to load these last. diff --git a/modules/config/default/README.org b/modules/config/default/README.org index 3a431c035..df4b4227b 100644 --- a/modules/config/default/README.org +++ b/modules/config/default/README.org @@ -1,44 +1,70 @@ -#+TITLE: :config default +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::config default][Issues]] ↖ [[doom-module-source:config/default][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+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, ~~ 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~ diff --git a/modules/config/literate/README.org b/modules/config/literate/README.org index 59421fb48..ea80a9cc4 100644 --- a/modules/config/literate/README.org +++ b/modules/config/literate/README.org @@ -1,106 +1,126 @@ -#+TITLE: config/literate -#+DATE: May 4, 2020 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::config literate][Issues]] ↖ [[doom-module-source:config/literate][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+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