1.1--- a/draft/outlines.org	Mon Aug 12 18:31:37 2024 -0400
     1.2+++ b/draft/outlines.org	Sun Aug 18 22:16:12 2024 -0400
     1.3@@ -1,6 +1,10 @@
     1.4 #+title: outlines
     1.5 #+setupfile: ../../clean.theme
     1.6+#+property: header-args :eval no-export
     1.7 * Overview
     1.8+:PROPERTIES:
     1.9+:ID:       f49fa8a0-39a6-4a5f-8fb6-8d4086ea5476
    1.10+:END:
    1.11 Source code files are hard to manage. They can get unwieldly quickly and making the
    1.12 wrong assumption about your whereabouts in the code tree can have unintended
    1.13 consequences.
    1.14@@ -33,6 +37,9 @@
    1.15 structure of a source code file.
    1.16 
    1.17 * Outlines
    1.18+:PROPERTIES:
    1.19+:ID:       651aa74f-e634-4eac-8292-95efbe2aab9c
    1.20+:END:
    1.21 Like all my good ideas, this one is credited entirely to Emacs. In this case, the
    1.22 excellent [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html][Outline mode]]. If you are an Emacs user you've probably already used it without
    1.23 knowing -- Org mode, for example, is [[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/org.el?h=release_9.6.9#n4789][derived from outline-mode]].
    1.24@@ -48,6 +55,9 @@
    1.25 -- [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html][GNU]]
    1.26 
    1.27 ** Quickstart
    1.28+:PROPERTIES:
    1.29+:ID:       8e1927c5-5e2b-470a-9249-5fe0e375451c
    1.30+:END:
    1.31 If you want to jump in right away, I recommend using these keybinds in Emacs:
    1.32 
    1.33 #+tblname: outline-keys
    1.34@@ -73,6 +83,9 @@
    1.35 move around the file with the new keybinds above.
    1.36 
    1.37 ** Outlines4All
    1.38+:PROPERTIES:
    1.39+:ID:       0751feb7-7e44-44d3-befd-905d365d05a1
    1.40+:END:
    1.41 Not all programming modes have outline support built-in. The good news is that it's easy
    1.42 to enable it.
    1.43 
    1.44@@ -80,6 +93,9 @@
    1.45 =outline-minor-mode=.
    1.46 
    1.47 *** Using dir-locals
    1.48+:PROPERTIES:
    1.49+:ID:       cf39a556-fc2c-46e3-a2f7-e659213a915f
    1.50+:END:
    1.51 The way it's done in the NAS-T codebase is with a [[../../.dir-locals.el][.dir-locals.el]] file.
    1.52 
    1.53 You just need to add this form for the mode of your choice, replacing the string
    1.54@@ -94,6 +110,9 @@
    1.55 minor-mode separately though. For project-level support, that's all there is to it.
    1.56 
    1.57 *** Using init.el
    1.58+:PROPERTIES:
    1.59+:ID:       c76e4c71-c77a-43b6-811c-0a83981a1dc5
    1.60+:END:
    1.61 You may also modify your config to enable =outline-minor-mode= for select major-modes at
    1.62 startup. Here's a quick example from my config:
    1.63 
    1.64@@ -124,9 +143,15 @@
    1.65 ;;; outline-cfg.el ends here
    1.66 #+end_src
    1.67 ** Default Sections
    1.68+:PROPERTIES:
    1.69+:ID:       c912d356-9688-4d48-91a8-ae234b410d46
    1.70+:END:
    1.71 Our default sections should look familiar - they're just Emacs Lisp defaults, with a few
    1.72 choice extensions.
    1.73 *** Source Header
    1.74+:PROPERTIES:
    1.75+:ID:       6e5856f0-3d75-4a4d-b44d-35e9015a63ab
    1.76+:END:
    1.77 First line of every source code file.
    1.78 
    1.79 Here is the prototype in lisp:
    1.80@@ -141,13 +166,22 @@
    1.81 
    1.82 etc.
    1.83 **** Metadata                                                   :optional:
    1.84+:PROPERTIES:
    1.85+:ID:       56e5ccd3-b98a-4ba0-aaaa-eef49bc3fac7
    1.86+:END:
    1.87 Some files may insert a blank line and start the =Code= heading, while others will
    1.88 include some additional information about the file such as a long-description, version,
    1.89 list of exports, etc.
    1.90 *** Commentary                                                   :optional:
    1.91+:PROPERTIES:
    1.92+:ID:       a8e36d82-4788-422c-af83-3374f23f9dc9
    1.93+:END:
    1.94 An optional programmer commentary included in source code files after the =Source
    1.95 Header= but before the =Code=. The contents are unpredictable but may include notes,
    1.96 todos, diagrams, stack notations, test results, links, tips, etc.
    1.97 *** Code
    1.98+:PROPERTIES:
    1.99+:ID:       7422d382-450b-46d6-898f-42daae455a47
   1.100+:END:
   1.101 The =Code= heading should be the final toplevel heading of any source code file. You
   1.102 may see a number of sub-headings, starting with four or more comment chars.