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
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue