2 #+setupfile: ../../clean.theme
4 Source code files are hard to manage. They can get unwieldly quickly and making the
5 wrong assumption about your whereabouts in the code tree can have unintended
8 There are many ways to solve this problem to different degrees. We'll be talking about
9 one strategy in particular which I use and recommend for any software project.
11 Looking through the source code in the NAS-T repository you'll find some common
14 - every file start with at least one comment line for example:
16 ;;; file-name.lisp --- file description
19 - Before you see any code in a file, you'll likely encounter this line:
26 What's the deal here? To be clear, I'm of the mind that comments should be
27 significant. They should express to the reader something that is of a non-trivial nature
28 and 'where the code starts' doesn't quite qualify. Indeed, these comments don't fit that
31 The deal is that these comments aren't for the reader, they're for the developer. More
32 specifically, for the developer to treat as a special meta-language to describe the
33 structure of a source code file.
36 Like all my good ideas, this one is credited entirely to Emacs. In this case, the
37 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
38 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]].
40 I've grown quite fond of it. Here's the summary:
43 Outline mode is a major mode derived from Text mode, which is specialized for editing
44 outlines. It provides commands to navigate between entries in the outline structure, and
45 commands to make parts of a buffer temporarily invisible, so that the outline structure
46 may be more easily viewed.
48 --
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html][GNU]] 51 If you want to jump in right away, I recommend using these keybinds in Emacs:
53 #+tblname: outline-keys
54 | <backtab> | outline-cycle-buffer | 55 | M-TAB | outline-cycle | 56 | M-n | outline-next-visible-heading | 57 | M-p | outline-previous-visible-heading | 59 Here's a snippet which will enable the keybinds I use:
61 #+name: enable-outline-keys
62 #+begin_src emacs-lisp 64 '(("<backtab>" #'outline-cycle-buffer)
65 ("M-TAB" #'outline-cycle)
66 ("M-n" #'outline-next-visible-heading)
67 ("M-p" #'outline-previous-visible-heading))))
68 (cl-loop for (k fn) in keys
69 do (keymap-set outline-minor-mode-map k fn)))
72 Now open a file in the
[[../../src/][src]] directory, like
[[../../src/fs/btrfs/btrfs.lisp][this]] one, enable
=outline-minor-mode= and
73 move around the file with the new keybinds above.
76 Not all programming modes have outline support built-in. The good news is that it's easy
79 You only need to modify one variable:
=outline-regexp= and enable a minor-mode:
83 The way it's done in the NAS-T codebase is with a
[[../../.dir-locals.el][.dir-locals.el]] file.
85 You just need to add this form for the mode of your choice, replacing the string
86 with a regular expression which matches on a
/heading/. In this case we treat lines
87 starting with three comment chars or more as a new heading.
89 (makefile-mode . ((outline-regexp . "###+")))
92 =outline-regexp= is declared as a safe local var, so no prompts will appear asking if
93 you trust these values. You will need to configure your keybinds and enable the
94 minor-mode separately though. For project-level support, that's all there is to it.
97 You may also modify your config to enable
=outline-minor-mode= for select major-modes at
98 startup. Here's a quick example from my config:
100 #+begin_src emacs-lisp 102 (require 'default 'rw/fu)
104 (defun outline-hook (rx)
105 "Enable `outline-minor-mode' and set `outline-regexp'."
106 (setq-local outline-regexp rx)
107 (outline-minor-mode t))
109 (defun add-outline-hook (mode rx)
110 (let ((sym (symb mode "-hook")))
111 (add-hook sym (lambda () (outline-hook rx)))))
113 (defmacro outline-hooks (&rest pairs)
114 `(mapc (lambda (x) (add-outline-hook (car x) (cadr x))) ',pairs))
116 (outline-hooks (asm-mode ";;;+")
118 (rust-mode "\\(//!\\|////+\\)")
120 (sh-script-mode "###+")
121 (makefile-mode "###+"))
123 (provide 'outline-cfg)
124 ;;; outline-cfg.el ends here
127 Our default sections should look familiar - they're just Emacs Lisp defaults, with a few
130 First line of every source code file.
132 Here is the prototype in lisp:
134 ;;; filename --- description -*- vars -*-
139 //! filename --- description -*- vars -*-
143 **** Metadata :optional: 144 Some files may insert a blank line and start the
=Code= heading, while others will
145 include some additional information about the file such as a long-description, version,
146 list of exports, etc.
147 *** Commentary :optional: 148 An optional programmer commentary included in source code files after the
=Source 149 Header= but before the
=Code=. The contents are unpredictable but may include notes,
150 todos, diagrams, stack notations, test results, links, tips, etc.
152 The
=Code= heading should be the final toplevel heading of any source code file. You
153 may see a number of sub-headings, starting with four or more comment chars.