1 84b5784c 2018-03-11 rnkn ;;; side-notes.el --- Easy access to a directory notes file -*- lexical-binding: t; -*-
3 452378c6 2021-01-31 rnkn ;; Copyright (c) 2019-2021 Paul W. Rankin
5 452378c6 2021-01-31 rnkn ;; Author: Paul W. Rankin <pwr@bydasein.com>
6 84b5784c 2018-03-11 rnkn ;; Keywords: convenience
7 452378c6 2021-01-31 rnkn ;; Version: 0.4.1
8 610c3e46 2018-05-14 rnkn ;; Package-Requires: ((emacs "24.5"))
9 f8d1e63d 2019-07-15 rnkn ;; URL: https://github.com/rnkn/side-notes
11 e2000753 2019-09-03 rnkn ;; This file is not part of GNU Emacs.
13 84b5784c 2018-03-11 rnkn ;; This program is free software; you can redistribute it and/or modify
14 84b5784c 2018-03-11 rnkn ;; it under the terms of the GNU General Public License as published by
15 e2000753 2019-09-03 rnkn ;; the Free Software Foundation, either version 3 of the License, or (at
16 e2000753 2019-09-03 rnkn ;; your option) any later version.
18 e2000753 2019-09-03 rnkn ;; This program is distributed in the hope that it will be useful, but
19 e2000753 2019-09-03 rnkn ;; WITHOUT ANY WARRANTY; without even the implied warranty of
20 e2000753 2019-09-03 rnkn ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 e2000753 2019-09-03 rnkn ;; General Public License for more details.
23 84b5784c 2018-03-11 rnkn ;; You should have received a copy of the GNU General Public License
24 e2000753 2019-09-03 rnkn ;; along with this program. If not, see <https://www.gnu.org/licenses/>.
26 84b5784c 2018-03-11 rnkn ;;; Commentary:
28 b4370ff5 2020-09-26 rnkn ;; Side Notes
29 b4370ff5 2020-09-26 rnkn ;; ==========
31 d2efd288 2018-03-11 rnkn ;; Quickly display your quick side notes in quick side window.
33 b4370ff5 2020-09-26 rnkn ;; Side notes live in a plain text file, called notes.txt by default, in
34 b4370ff5 2020-09-26 rnkn ;; the current directory or any higher directory in the current hierarchy.
35 b4370ff5 2020-09-26 rnkn ;; i.e. When locating notes, we first look for a notes.txt file in the
36 b4370ff5 2020-09-26 rnkn ;; current directory, then one directory up, then two directories up, and
37 b4370ff5 2020-09-26 rnkn ;; so forth.
39 50fb7007 2020-06-10 rnkn ;; Side notes are displayed in a side window with the command
40 50fb7007 2020-06-10 rnkn ;; side-notes-toggle-notes.
42 50fb7007 2020-06-10 rnkn ;; The filename is defined by user option side-notes-file.
44 50fb7007 2020-06-10 rnkn ;; To really mix things up, there's the user option
45 50fb7007 2020-06-10 rnkn ;; side-notes-secondary-file, which defaults to notes-2.txt, and will
46 50fb7007 2020-06-10 rnkn ;; display a separate notes file in a lower side window when the command
47 4e7e78bf 2020-03-11 rnkn ;; side-notes-toggle-notes is prefixed with an argument (C-u).
49 b4370ff5 2020-09-26 rnkn ;; By default, having a notes file in any parent directory will locate that
50 b4370ff5 2020-09-26 rnkn ;; file rather than visit a non-existing file in the current directory, but
51 b4370ff5 2020-09-26 rnkn ;; you can override this by prefixing side-notes-toggle-notes with...
53 b4370ff5 2020-09-26 rnkn ;; - C-u C-u to force visiting side-notes-file within the current
54 b4370ff5 2020-09-26 rnkn ;; directory.
55 b4370ff5 2020-09-26 rnkn ;; - C-u C-u C-u to force visiting side-notes-secondary-file within
56 b4370ff5 2020-09-26 rnkn ;; the current directory.
58 50fb7007 2020-06-10 rnkn ;; Of course, you can use Markdown or Org Mode formatting by changing the
59 b4370ff5 2020-09-26 rnkn ;; file extensions of side-notes-file and/or side-notes-secondary-file.
61 50fb7007 2020-06-10 rnkn ;; For more information on how to change the way the side window is
62 50fb7007 2020-06-10 rnkn ;; displayed, see (info "(elisp) Side Windows")
65 b4370ff5 2020-09-26 rnkn ;; Installation
66 b4370ff5 2020-09-26 rnkn ;; ------------
68 b4370ff5 2020-09-26 rnkn ;; Install from [MELPA stable][1] then add something like the following to
69 4e7e78bf 2020-03-11 rnkn ;; your init file:
71 4e7e78bf 2020-03-11 rnkn ;; (define-key (current-global-map) (kbd "M-s n") #'side-notes-toggle-notes)
73 b4370ff5 2020-09-26 rnkn ;; [1]: https://stable.melpa.org/#/side-notes
74 b4370ff5 2020-09-26 rnkn ;; [2]: https://melpa.org/#/side-notes
79 84b5784c 2018-03-11 rnkn (defgroup side-notes ()
80 84b5784c 2018-03-11 rnkn "Display a notes file."
81 84b5784c 2018-03-11 rnkn :group 'convenience)
83 84b5784c 2018-03-11 rnkn (defcustom side-notes-hook
85 84b5784c 2018-03-11 rnkn "Hook run after showing notes buffer."
87 84b5784c 2018-03-11 rnkn :group 'side-notes)
89 84b5784c 2018-03-11 rnkn (defcustom side-notes-file
91 aba24426 2019-11-28 rnkn "Name of the notes file.
93 56cd2bfe 2019-05-23 rnkn This file lives in the current directory or any parent directory
94 56cd2bfe 2019-05-23 rnkn thereof, which allows you to keep a notes file in the top level
95 56cd2bfe 2019-05-23 rnkn of a multi-directory project.
97 56cd2bfe 2019-05-23 rnkn If you would like to use a file-specific notes file, specify a
98 56cd2bfe 2019-05-23 rnkn string with `add-file-local-variable'. Likewise you can specify a
99 56cd2bfe 2019-05-23 rnkn directory-specific notes file with `add-dir-local-variable'."
100 84b5784c 2018-03-11 rnkn :type 'string
101 57143a83 2018-05-24 rnkn :safe 'stringp
102 84b5784c 2018-03-11 rnkn :group 'side-notes)
103 84b5784c 2018-03-11 rnkn (make-variable-buffer-local 'side-notes-file)
105 aba24426 2019-11-28 rnkn (defcustom side-notes-secondary-file
106 75cf91fd 2020-06-10 rnkn "notes-2.txt"
107 aba24426 2019-11-28 rnkn "Name of an optional secondary notes file.
109 aba24426 2019-11-28 rnkn Like `side-notes-file' but displayed when `side-notes-toggle-notes'
110 aba24426 2019-11-28 rnkn is prefixed with \\[universal-argument].
112 aba24426 2019-11-28 rnkn If you would like to use a file-specific notes file, specify a
113 aba24426 2019-11-28 rnkn string with `add-file-local-variable'. Likewise you can specify a
114 aba24426 2019-11-28 rnkn directory-specific notes file with `add-dir-local-variable'."
115 75cf91fd 2020-06-10 rnkn :type 'string
116 aba24426 2019-11-28 rnkn :safe 'stringp
117 aba24426 2019-11-28 rnkn :group 'side-notes)
118 aba24426 2019-11-28 rnkn (make-variable-buffer-local 'side-notes-secondary-file)
120 84b5784c 2018-03-11 rnkn (defcustom side-notes-select-window
122 84b5784c 2018-03-11 rnkn "If non-nil, switch to notes window upon displaying it."
123 84b5784c 2018-03-11 rnkn :type 'boolean
124 57143a83 2018-05-24 rnkn :safe 'booleanp
125 49718449 2018-03-13 rnkn :group 'side-notes)
127 84b5784c 2018-03-11 rnkn (defcustom side-notes-display-alist
128 84b5784c 2018-03-11 rnkn '((side . right)
129 aba24426 2019-11-28 rnkn (window-width . 35))
130 84b5784c 2018-03-11 rnkn "Alist used to display notes buffer.
132 aba24426 2019-11-28 rnkn See `display-buffer-in-side-window' for example options.
134 aba24426 2019-11-28 rnkn n.b. the special symbol `slot' added automatically to ensure that
135 aba24426 2019-11-28 rnkn `side-notes-file' is displayed above `side-notes-secondary-file'."
136 84b5784c 2018-03-11 rnkn :type 'alist
137 49718449 2018-03-13 rnkn :group 'side-notes)
139 6e73a47c 2018-03-13 rnkn (defface side-notes
141 6e73a47c 2018-03-13 rnkn "Default face for notes buffer."
142 6e73a47c 2018-03-13 rnkn :group 'side-notes)
144 84b5784c 2018-03-11 rnkn (defvar-local side-notes-buffer-identify
146 84b5784c 2018-03-11 rnkn "Buffer local variable to identify a notes buffer.")
148 aba24426 2019-11-28 rnkn (defun side-notes-locate-notes (&optional arg)
149 8597ddd2 2019-04-03 rnkn "Look up directory hierachy for file `side-notes-file'.
151 8597ddd2 2019-04-03 rnkn Return nil if no notes file found."
152 75cf91fd 2020-06-10 rnkn (cond ((and side-notes-secondary-file (= arg 64))
153 75cf91fd 2020-06-10 rnkn (expand-file-name side-notes-secondary-file default-directory))
154 75cf91fd 2020-06-10 rnkn ((= arg 16)
155 75cf91fd 2020-06-10 rnkn (expand-file-name side-notes-file default-directory))
156 75cf91fd 2020-06-10 rnkn ((and side-notes-secondary-file (= arg 4))
157 75cf91fd 2020-06-10 rnkn (expand-file-name side-notes-secondary-file
158 75cf91fd 2020-06-10 rnkn (locate-dominating-file default-directory
159 75cf91fd 2020-06-10 rnkn side-notes-secondary-file)))
161 75cf91fd 2020-06-10 rnkn (expand-file-name side-notes-file
162 75cf91fd 2020-06-10 rnkn (locate-dominating-file default-directory
163 75cf91fd 2020-06-10 rnkn side-notes-file)))))
165 d8aebc7f 2019-08-16 noreply ;;;###autoload
166 aba24426 2019-11-28 rnkn (defun side-notes-toggle-notes (arg)
167 aba24426 2019-11-28 rnkn "Pop up a side window containing `side-notes-file'.
169 75cf91fd 2020-06-10 rnkn When prefixed with...
171 75cf91fd 2020-06-10 rnkn 1. \\[universal-argument], locate `side-notes-secondary-file' instead.
172 75cf91fd 2020-06-10 rnkn 2. \\[universal-argument] \\[universal-argument], force visiting `side-notes-file' within current directory.
173 75cf91fd 2020-06-10 rnkn 3. \\[universal-argument] \\[universal-argument] \\[universal-argument], force visiting `side-notes-secondary-file' within
174 75cf91fd 2020-06-10 rnkn current directory.
176 8597ddd2 2019-04-03 rnkn See `side-notes-display-alist' for options concerning displaying
177 8597ddd2 2019-04-03 rnkn the notes buffer."
178 75cf91fd 2020-06-10 rnkn (interactive "p")
179 84b5784c 2018-03-11 rnkn (if side-notes-buffer-identify
180 84b5784c 2018-03-11 rnkn (quit-window)
181 84b5784c 2018-03-11 rnkn (let ((display-buffer-mark-dedicated t)
182 aba24426 2019-11-28 rnkn (buffer (find-file-noselect (side-notes-locate-notes arg))))
183 84b5784c 2018-03-11 rnkn (if (get-buffer-window buffer (selected-frame))
184 84b5784c 2018-03-11 rnkn (delete-windows-on buffer (selected-frame))
185 aba24426 2019-11-28 rnkn (display-buffer-in-side-window
186 75cf91fd 2020-06-10 rnkn buffer (cons (cons 'slot (if (or (= arg 4) (= arg 64)) 1 -1))
187 75cf91fd 2020-06-10 rnkn side-notes-display-alist))
188 84b5784c 2018-03-11 rnkn (with-current-buffer buffer
189 84b5784c 2018-03-11 rnkn (setq side-notes-buffer-identify t)
190 6e73a47c 2018-03-13 rnkn (face-remap-add-relative 'default 'side-notes)
191 84b5784c 2018-03-11 rnkn (run-hooks 'side-notes-hook))
192 84b5784c 2018-03-11 rnkn (if side-notes-select-window
193 84b5784c 2018-03-11 rnkn (select-window (get-buffer-window buffer (selected-frame))))
194 84b5784c 2018-03-11 rnkn (message "Showing `%s'; %s to hide" buffer
195 84b5784c 2018-03-11 rnkn (key-description (where-is-internal this-command
196 84b5784c 2018-03-11 rnkn overriding-local-map t)))))))
198 84b5784c 2018-03-11 rnkn (provide 'side-notes)
199 84b5784c 2018-03-11 rnkn ;;; side-notes.el ends here
201 133498c2 2020-03-11 rnkn ;; Local Variables:
202 133498c2 2020-03-11 rnkn ;; coding: utf-8-unix
203 133498c2 2020-03-11 rnkn ;; fill-column: 80
204 133498c2 2020-03-11 rnkn ;; require-final-newline: t
205 133498c2 2020-03-11 rnkn ;; sentence-end-double-space: nil