doomemacs/modules/config/literate/README.org

#+title:    :config literate
#+subtitle: Disguise your config as poor documentation
#+created:  May 28, 2020
#+since:    2.0.9

* 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.

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
/This module doesn't install any packages./

** Hacks
/No hacks documented for this module./

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

** 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=.

Source blocks needs to be in some language to be automatically tangled, for
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~

** 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:
- 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 emacs-lisp :tangle no
(message "Don't tangle me")
,#+end_src

,#+begin_src emacs-lisp :tangle packages.el
(package! my-package)
(package! other-package)
,#+end_src

,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
#!/usr/bin/env bash
echo Hello world
,#+end_src

,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
echo Hello world
,#+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 Org manual]].

* Troubleshooting
/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= 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 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 emacs-lisp
;; add to $DOOMDIR/config.el
(remove-hook 'org-mode-hook #'+literate-enable-recompile-h)
#+end_src

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote