From 8da31dbbab0615774dd58fae5a5f249ae790c9f4 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <henrik@lissner.net>
Date: Sat, 25 Jul 2020 22:38:37 -0400
Subject: [PATCH] config/literate: update & revise readme

---
 modules/config/literate/README.org | 50 ++++++++++++++++++++++--------
 1 file changed, 37 insertions(+), 13 deletions(-)

diff --git a/modules/config/literate/README.org b/modules/config/literate/README.org
index ea8d9affb..7a423f7f3 100644
--- a/modules/config/literate/README.org
+++ b/modules/config/literate/README.org
@@ -13,6 +13,7 @@
 - [[#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]]
+  - [[#modularizing-your-literate-config-with-include-directives][Modularizing your literate config with ~#+INCLUDE~ directives]]
 - [[#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]]
@@ -37,23 +38,28 @@ This module installs no plugins.
 This module has no prerequisites.
 
 * Features
-+ Automatically tangle ~config.org~ to ~config.el~ when saving.
++ Automatically tangles ~config.org~ to ~config.el~ when saving. See
+  Troubleshooting section belong on how to disable it.
 
 * Configuration
 ** Change the location of config.org
-The ~+literate-config-file~ variable controls where to look for your central
-config.org. However, it must be changed early, in =DOOMDIR/init.el= or
+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 for example ~#+BEGIN_SRC elisp~ but currently it does not matter what language is used, it tangles all to ~config.el~. ~elisp~ gives correct syntax highlight. If you don't want to specify language in block you can also enforce tangling by adding ~#+BEGIN_SRC :tangle~
+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
+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 elisp src blocks to config.org unless
-otherwise specified.
+By default, this module tangles all src blocks (with a valid language) to
+config.org unless otherwise specified.
 
-To specify otherwise, use the =:tangle= parameter to:
+To specify otherwise use the =:tangle= parameter to:
 
-- Specify another destination, other than config.el, like packages.el
+- Specify a destination other than config.el, like packages.el
 - Disable tangling of the block altogether
 - Or force non-elisp src blocks to tangle somewhere
 
@@ -74,18 +80,36 @@ echo Hello world
 ,#+END_SRC
 #+END_SRC
 
+** Modularizing your literate config with ~#+INCLUDE~ directives
+Literate configs can be split up into separate files and imported into a central
+=config.org= using the ~#+INCLUDE~ org directive. Here are some examples:
+#+BEGIN_SRC org
+,#+INCLUDE other-file.org
+,#+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
+,#+INCLUDE: "~/.emacs" :lines "5-10"
+,#+INCLUDE: "~/.emacs" :lines "-10"
+,#+INCLUDE: "~/.emacs" :lines "10-"
+,#+INCLUDE: "./paper.org::*conclusion" :lines 1-20
+,#+INCLUDE: "./paper.org::#theory" :only-contents t
+#+END_SRC
+
+See [[https://orgmode.org/manual/Include-Files.html][this entry in the Emacs manual]] for more on this directive.
+
 * Troubleshooting
 ** How to tangle to =DOOMDIR/init.el=
-If your literate needs are more complex (e.g. you want to incorporate your
-init.el into your literate config), this module won't cut it. Doom comes with a
-[[file:../../../bin/org-tangle][bin/org-tangle]] script, which you can use to tangle arbitrary org files from then
-command line. Use it to create your own compilation workflows.
+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.
+
+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
 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
 (remove-hook 'org-mode-hook #'+literate-enable-recompile-h)