emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs(:config): update READMEs to new format

Browse source
This commit is contained in:
Henrik Lissner 2021-10-16 01:21:52 +02:00 • committed by Henrik Lissner
parent 11793094ba
commit c27f005011
3 changed files with 143 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

9
modules/config/README.org
View file

@ -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 #+TITLE: :config
#+CREATED: July 29, 2021 #+CREATED: July 29, 2021
#+SINCE: v21.12.0 #+SINCE: 21.12.0
#+SETUPFILE: ../../docs/.setupfile.org
* Description * Description
Modules that configure Emacs one way or another, or focus on making it easier Modules in this category provide sane defaults or improve your ability to
for you to customize it yourself. It is best to load these last. configure Emacs. It is best to load these last.

90
modules/config/default/README.org
View file

@ -1,44 +1,70 @@
← [[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 #+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: This module provides a set of reasonable defaults, including:
+ A Spacemacs-esque keybinding scheme - A Spacemacs-inspired keybinding scheme
+ Extra Ex commands for evil-mode users - A configuration for (almost) universally repeating searches with [[kbd:][;]] and [[kbd:][,]]
+ A yasnippet snippets library tailored to Doom emacs - A [[doom-package:][smartparens]] configuration for smart completion of certain delimiters, like
+ A configuration for (almost) universally repeating searches with =;= and =,= ~/* */~ 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 #+begin_quote
The defaults module is intended as a "reasonable-defaults" module, but also as a 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
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.
#+end_quote #+end_quote
* Table of Contents :TOC: * TODO Configuration
- [[#install][Install]] #+begin_quote
- [[#configuration][Configuration]] 🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
- [[#im-not-an-evil-user][I'm not an evil user...]] #+end_quote
- [[#appendix][Appendix]]
- [[#commands][Commands]]
- [[#hacks][Hacks]]
* Install * Troubleshooting
This module has no external dependencies. /There are no known problems with this module./ [[doom-report:][Report one?]]
* Configuration * Frequently asked questions
** I'm not an evil user... /This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
That's fine. All evil configuration is ignored if =:editor evil= is disabled.
* TODO Appendix
#+begin_quote
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote
* Appendix
** Commands ** Commands
+ ~+default/browse-project~ - ~+default/browse-project~
+ ~+default/browse-templates~ - ~+default/browse-templates~
+ ~+default/find-in-templates~ - ~+default/find-in-templates~
+ ~+default/browse-notes~ - ~+default/browse-notes~
+ ~+default/find-in-notes~ - ~+default/find-in-notes~
+ ~+default/find-in-snippets~ - ~+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+!*

136
modules/config/literate/README.org
View file

@ -1,106 +1,126 @@
#+TITLE: config/literate ← [[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]]
#+DATE: May 4, 2020 --------------------------------------------------------------------------------
#+SINCE: v2.0.9 #+TITLE: :config literate
#+STARTUP: inlineimages nofold #+SUBTITLE: Disguise your config as poor documentation
#+CREATED: May 28, 2020
#+SINCE: 2.0.9
* Table of Contents :TOC_3:noexport: * Description :unfold:
- [[#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
This module enables support for a literate config. This module enables support for a literate config.
A literate config consists of a =DOOMDIR/config.org=. All src blocks within are 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. tangled =$DOOMDIR/config.el=, by default, when ~$ doom sync~ is executed.
** Maintainers ** Maintainers
This module has no dedicated maintainers. /This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags ** Module flags
This module provides no flags. /This module has no flags./
** Plugins ** Packages
This module installs no plugins. /This module doesn't install any packages./
* Prerequisites ** Hacks
This module has no prerequisites. /No hacks documented for this module./
* Features ** TODO Changelog
+ Automatically tangles ~config.org~ to ~config.el~ when saving. See # This section will be machine generated. Don't edit it by hand.
Troubleshooting section belong on how to disable it. /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 ** Change the location of config.org
The ~+literate-config-file~ variable controls where to look for your 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 To change this it must be modified early -- in =$DOOMDIR/init.el= or
=DOOMDIR/cli.el=. =$DOOMDIR/cli.el=.
Source blocks needs to be in some language to be automatically tangled, for 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 example ~#+begin_src emacs-lisp~, but it doesn't matter what language is used.
blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax 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 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 ** Change where src blocks are tangled or prevent it entirely
By default, this module tangles all src emacs-lisp blocks to config.el unless By default, this module tangles all src emacs-lisp blocks to config.el unless
otherwise specified. 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~ - Specify a destination other than config.el: ~:tangle packages.el~
- Disable tangling of the block altogether with ~:tangle no~ - Disable tangling of the block altogether with ~:tangle no~
- Or force non-elisp src blocks to tangle somewhere - Or force non-elisp src blocks to tangle somewhere
For example: For example:
#+BEGIN_SRC org #+begin_src org
,#+BEGIN_SRC elisp :tangle no ,#+begin_src emacs-lisp :tangle no
(message "Don't tangle me") (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! my-package)
(package! other-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 #!/usr/bin/env bash
echo Hello world 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 echo Hello world
,#+END_SRC ,#+end_src
#+END_SRC #+end_src
You'll find more information about babel src blocks and what parameters they 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 * 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 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 literate), this module won't cut it. =init.el= files in modules are loaded long
=config.org= is tangled in the ~doom sync~ process. 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 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 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 workflows. This is /much/ faster than using ~org-babel-load-file~ directly to
load your literate config every time Doom is started. 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 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 slow, produces too much noise, or happens too often (on unrelated org files in
your =DOOMDIR=). This behavior can be disabled with: your =$DOOMDIR=). This behavior can be disabled with:
#+BEGIN_SRC elisp #+begin_src emacs-lisp
;; add to DOOMDIR/config.el ;; add to $DOOMDIR/config.el
(remove-hook 'org-mode-hook #'+literate-enable-recompile-h) (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