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

13
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
#+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.

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

@ -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, ~<?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~

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

@ -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