remember.el

   1 ;;; remember --- a mode for quickly jotting down things to remember
   2
   3 ;; Copyright (C) 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2007,
   4 ;;   2008  Free Software Foundation, Inc.
   5
   6 ;; Author: John Wiegley <johnw@gnu.org>
   7 ;; Created: 29 Mar 1999
   8 ;; Version: 1.9
   9 ;; Keywords: data memory todo pim
  10 ;; URL: http://gna.org/projects/remember-el/
  11
  12 ;; This file is part of GNU Emacs.
  13
  14 ;; GNU Emacs is free software; you can redistribute it and/or modify
  15 ;; it under the terms of the GNU General Public License as published by
  16 ;; the Free Software Foundation; either version 3, or (at your option)
  17 ;; any later version.
  18
  19 ;; GNU Emacs is distributed in the hope that it will be useful,
  20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 ;; GNU General Public License for more details.
  23
  24 ;; You should have received a copy of the GNU General Public License
  25 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  26 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  27 ;; Boston, MA 02110-1301, USA.
  28
  29 ;;; Commentary:
  30
  31 ;; * The idea
  32 ;;
  33 ;; Todo lists, schedules, phone databases... everything we use
  34 ;; databases for is really just a way to extend the power of our
  35 ;; memory.  To be able to remember what our conscious mind may not
  36 ;; currently have access to.
  37 ;;
  38 ;; There are many different databases out there -- and good ones --
  39 ;; which this mode is not trying to replace.  Rather, it's how that
  40 ;; data gets there that's the question.  Most of the time, we just
  41 ;; want to say "Remember so-and-so's phone number, or that I have to
  42 ;; buy dinner for the cats tonight."  That's the FACT.  How it's
  43 ;; stored is really the computer's problem.  But at this point in
  44 ;; time, it's most definitely also the user's problem, and sometimes
  45 ;; so laboriously so that people just let data slip, rather than
  46 ;; expend the effort to record it.
  47 ;;
  48 ;; "Remember" is a mode for remembering data.  It uses whatever
  49 ;; back-end is appropriate to record and correlate the data, but it's
  50 ;; main intention is to allow you to express as _little_ structure as
  51 ;; possible up front.  If you later want to express more powerful
  52 ;; relationships between your data, or state assumptions that were at
  53 ;; first too implicit to be recognized, you can "study" the data later
  54 ;; and rearrange it.  But the initial "just remember this" impulse
  55 ;; should be as close to simply throwing the data at Emacs as
  56 ;; possible.
  57 ;;
  58 ;; * Implementation
  59 ;;
  60 ;; Hyperbole, as a data presentation tool, always struck me as being
  61 ;; very powerful, but it seemed to require a lot of "front-end" work
  62 ;; before that data was really available.  The problem with BBDB, or
  63 ;; keeping up a Bibl-mode file, is that you have to use different
  64 ;; functions to record the data, and it always takes time to stop what
  65 ;; you're doing, format the data in the manner expected by that
  66 ;; particular data interface, and then resume your work.
  67 ;;
  68 ;; With "remember", you just hit `M-x remember' (you'd probably want
  69 ;; to bind this to an easily accessible keystroke, like C-x M-r), slam
  70 ;; in your text however you like, and then hit C-c C-c.  It will file
  71 ;; the data away for later retrieval, and possibly indexing.
  72 ;;
  73 ;; Indexing is to data what "studying" is in the real world.  What you
  74 ;; do when you study (or lucubrate, for some of us) is to realize
  75 ;; certain relationships implicit in the data, so that you can make
  76 ;; use of those relationships.  Expressing that a certain quote you
  77 ;; remembered was a religious quote, and that you want the ability to
  78 ;; pull up all quotes of a religious nature, is what studying does.
  79 ;; This is a more labor intensive task than the original remembering
  80 ;; of the data, and it's typical in real life to set aside a special
  81 ;; period of time for doing this work.
  82 ;;
  83 ;; "Remember" works in the same way.  When you enter data, either by
  84 ;; typing it into a buffer, or using the contents of the selected
  85 ;; region, it will store that data -- unindexed, uninterpreted -- in a
  86 ;; data pool.  It will also try to remember as much context
  87 ;; information as possible (any text properties that were set, where
  88 ;; you copied it from, when, how, etc).  Later, you can walk through
  89 ;; your accumulated set of data (both organized, and unorganized) and
  90 ;; easily begin moving things around, and making annotations that will
  91 ;; express the full meaning of that data, as far as you know it.
  92 ;;
  93 ;; Obviously this latter stage is more user-interface intensive, and
  94 ;; it would be nice if "remember" could do it as elegantly as
  95 ;; possible, rather than requiring a billion keystrokes to reorganize
  96 ;; your hierarchy.  Well, as the future arrives, hopefully experience
  97 ;; and user feedback will help to make this as intuitive a tool as
  98 ;; possible.
  99 ;;
 100 ;; * Future Goals
 101 ;;
 102 ;; This tool hopes to track (and by doing it with as little new code
 103 ;; as possible):
 104 ;;
 105 ;;  - The raw data that gets entered
 106 ;;
 107 ;;  - The relationships between that data (either determined
 108 ;;    implicitly by parsing the input, or explicitly by the user's
 109 ;;    studying the data).
 110 ;;
 111 ;;  - Revisioning of the data
 112 ;;
 113 ;;  - Where it came from, and any context information that can be
 114 ;;    programmatically determined.
 115 ;;
 116 ;;  - Allowing particular views of the initially amorphous data pool
 117 ;;    (ala the Xanadu concept).
 118 ;;
 119 ;;  - Storage of the data in a manner most appopriate to that data,
 120 ;;    such as keeping address-book type information in BBDB, etc.
 121 ;;
 122 ;; * Using "remember"
 123 ;;
 124 ;; As a rough beginning, what I do is to keep my .notes file in
 125 ;; outline-mode format, with a final entry called "* Raw data".  Then,
 126 ;; at intervals, I can move the data that gets appended there into
 127 ;; other places.  But certainly this should evolve into an intuitive
 128 ;; mechanism for shuffling data off to its appropriate corner of the
 129 ;; universe.
 130 ;;
 131 ;; To map the primary remember function to the keystroke F8, do the
 132 ;; following.
 133 ;;
 134 ;;   (autoload 'remember "remember" nil t)
 135 ;;
 136 ;;   (define-key global-map [f8] 'remember)
 137 ;;
 138 ;; * Feedback
 139 ;;
 140 ;; If Emacs could become a more intelligent data store, where
 141 ;; brainstorming would focus on the IDEAS involved -- rather than the
 142 ;; structuring and format of those ideas, or having to stop your
 143 ;; current flow of work in order to record them -- it would map much
 144 ;; more closely to how the mind (well, at least mine) works, and hence
 145 ;; would eliminate that very manual-ness which computers from the very
 146 ;; beginning have been championed as being able to reduce.
 147 ;;
 148 ;; Have you ever noticed that having a laptop to write on doesn't
 149 ;; _actually_ increase the amount of quality material that you turn
 150 ;; out, in the long run?  Perhaps its because the time we save
 151 ;; electronically in one way, we're losing electronically in another;
 152 ;; the tool should never dominate one's focus.  As the mystic
 153 ;; Faridu'd-Din `Attar wrote: "Be occupied as little as possible with
 154 ;; things of the outer world but much with things of the inner world;
 155 ;; then right action will overcome inaction."
 156 ;;
 157 ;; * Diary integration
 158 ;;
 159 ;; To use, add the following to your .emacs:
 160 ;;
 161 ;;   ;; This should be before other entries that may return t
 162 ;;   (add-to-list 'remember-handler-functions 'remember-diary-extract-entries)
 163 ;;
 164 ;; This module recognizes entries of the form
 165 ;;
 166 ;;   DIARY: ....
 167 ;;
 168 ;; and puts them in your ~/.diary (or remember-diary-file) together
 169 ;; with an annotation.  Dates in the form YYYY.MM.DD are converted to
 170 ;; YYYY-MM-DD so that diary can understand them.
 171 ;;
 172 ;; For example:
 173 ;;
 174 ;;   DIARY: 2003.08.12 Sacha's birthday
 175 ;;
 176 ;; is stored as
 177 ;;
 178 ;;   2003.08.12 Sacha's birthday
 179
 180 ;;; History:
 181
 182 ;;; Code:
 183
 184 (provide 'remember)
 185
 186 (defconst remember-version "1.9"
 187   "This version of remember.")
 188
 189 (defgroup remember nil
 190   "A mode to remember information."
 191   :group 'data)
 192
 193 ;;; User Variables:
 194
 195 (defcustom remember-mode-hook nil
 196   "Functions run upon entering `remember-mode'."
 197   :type 'hook
 198   :options '(flyspell-mode turn-on-auto-fill org-remember-apply-template)
 199   :group 'remember)
 200
 201 (defcustom remember-in-new-frame nil
 202   "Non-nil means use a separate frame for capturing remember data."
 203   :type 'boolean
 204   :group 'remember)
 205
 206 (defcustom remember-register ?R
 207   "The register in which the window configuration is stored."
 208   :type 'character
 209   :group 'remember)
 210
 211 (defcustom remember-filter-functions nil
 212   "*Functions run to filter remember data.
 213 All functions are run in the remember buffer."
 214   :type 'hook
 215   :group 'remember)
 216
 217 (defcustom remember-handler-functions '(remember-append-to-file)
 218   "*Functions run to process remember data.
 219 Each function is called with the current buffer narrowed to what the
 220 user wants remembered.
 221 If any function returns non-nil, the data is assumed to have been
 222 recorded somewhere by that function. "
 223   :type 'hook
 224   :options '(remember-store-in-mailbox
 225              remember-append-to-file
 226              remember-diary-extract-entries
 227              org-remember-handler)
 228   :group 'remember)
 229
 230 (defcustom remember-all-handler-functions nil
 231   "If non-nil every function in `remember-handler-functions' is
 232 called."
 233   :type 'boolean
 234   :group 'remember)
 235
 236 ;;; Internal Variables:
 237
 238 (defvar remember-buffer "*Remember*"
 239   "The name of the remember data entry buffer.")
 240
 241 (defcustom remember-save-after-remembering t
 242   "*Non-nil means automatically save after remembering."
 243   :type 'boolean
 244   :group 'remember)
 245
 246 ;;; User Functions:
 247
 248 ;; People with planner.el can set this to planner-annotation-functions:
 249 ;; (defvaralias 'remember-annotation-functions 'planner-annotation-functions)
 250 ;; or (defalias 'remember-annotation-functions 'planner-annotation-functions)
 251 (defcustom remember-annotation-functions
 252   (if (boundp 'planner-annotation-functions)
 253       planner-annotation-functions
 254     '(buffer-file-name))
 255   "Hook that returns an annotation to be inserted into the remember buffer."
 256   :type 'hook
 257   :options '(org-remember-annotation buffer-file-name)
 258   :group 'remember)
 259
 260 (defvar remember-annotation nil
 261   "Current annotation.")
 262 (defvar remember-initial-contents nil
 263   "Initial contents to place into *Remember* buffer.")
 264
 265 (defcustom remember-before-remember-hook nil
 266   "Functions run before switching to the *Remember* buffer."
 267   :type 'hook
 268   :group 'remember)
 269
 270 (defcustom remember-run-all-annotation-functions-flag nil
 271   "Non-nil means use all annotations returned by
 272 `remember-annotation-functions'."
 273   :type 'boolean
 274   :group 'remember)
 275
 276 ;;;###autoload
 277 (defun remember (&optional initial)
 278   "Remember an arbitrary piece of data.
 279 INITIAL is the text to initially place in the *Remember* buffer,
 280 or nil to bring up a blank *Remember* buffer.
 281
 282 With a prefix or a visible region, use the region as INITIAL."
 283   (interactive
 284    (list (when (or current-prefix-arg
 285                    (and mark-active
 286                         transient-mark-mode))
 287            (buffer-substring (region-beginning) (region-end)))))
 288   (funcall (if remember-in-new-frame
 289                #'frame-configuration-to-register
 290              #'window-configuration-to-register) remember-register)
 291   (let* ((annotation
 292           (if remember-run-all-annotation-functions-flag
 293               (mapconcat 'identity
 294                          (delq nil
 295                                (mapcar 'funcall remember-annotation-functions))
 296                          "\n")
 297             (run-hook-with-args-until-success
 298              'remember-annotation-functions)))
 299          (buf (get-buffer-create remember-buffer)))
 300     (run-hooks 'remember-before-remember-hook)
 301     (funcall (if remember-in-new-frame
 302                  #'switch-to-buffer-other-frame
 303                #'switch-to-buffer-other-window) buf)
 304     (if remember-in-new-frame
 305         (set-window-dedicated-p
 306          (get-buffer-window (current-buffer) (selected-frame)) t))
 307     (remember-mode)
 308     (when (= (point-max) (point-min))
 309       (when initial (insert initial))
 310       (setq remember-annotation annotation)
 311       (when remember-initial-contents (insert remember-initial-contents))
 312       (when (and (stringp annotation)
 313                  (not (equal annotation "")))
 314         (insert "\n\n" annotation))
 315       (setq remember-initial-contents nil)
 316       (goto-char (point-min)))
 317     (message "Use C-c C-c to remember the data.")))
 318
 319 ;;;###autoload
 320 (defun remember-other-frame (&optional initial)
 321   "Call `remember' in another frame."
 322   (interactive
 323    (list (when current-prefix-arg
 324            (buffer-substring (point) (mark)))))
 325   (let ((remember-in-new-frame t))
 326     (remember initial)))
 327
 328 (defsubst remember-time-to-seconds (time)
 329   "Convert TIME to a floating point number."
 330   (+ (* (car time) 65536.0)
 331      (cadr time)
 332      (/ (or (car (cdr (cdr time))) 0) 1000000.0)))
 333
 334 (defsubst remember-mail-date (&optional rfc822-p)
 335   "Return a simple date.  Nothing fancy."
 336   (if rfc822-p
 337       (format-time-string "%a, %e %b %Y %T %z" (current-time))
 338     (format-time-string "%a %b %e %T %Y" (current-time))))
 339
 340 (defun remember-buffer-desc ()
 341   "Using the first line of the current buffer, create a short description."
 342   (buffer-substring (point-min)
 343                     (save-excursion
 344                       (goto-char (point-min))
 345                       (end-of-line)
 346                       (if (> (- (point) (point-min)) 60)
 347                           (goto-char (+ (point-min) 60)))
 348                       (point))))
 349
 350 ;; Remembering to UNIX mailboxes
 351
 352 (defcustom remember-mailbox "~/Mail/remember"
 353   "*The file in which to store remember data as mail."
 354   :type 'file
 355   :group 'remember)
 356
 357 (defcustom remember-default-priority "medium"
 358   "*The default priority for remembered mail messages."
 359   :type 'string
 360   :group 'remember)
 361
 362 (defun remember-store-in-mailbox ()
 363   "Store remember data as if it were incoming mail.
 364 In which case `remember-mailbox' should be the name of the mailbox.
 365 Each piece of psuedo-mail created will have an `X-Todo-Priority'
 366 field, for the purpose of appropriate splitting."
 367   (let ((who (read-string "Who is this item related to? "))
 368         (moment
 369          (format "%.0f" (remember-time-to-seconds (current-time))))
 370         (desc (remember-buffer-desc))
 371         (text (buffer-string)))
 372     (with-temp-buffer
 373       (insert (format "From %s  %s
 374 Date: %s
 375 From: %s
 376 Message-Id: <remember-%s@%s>
 377 X-Todo-Priority: %s
 378 To: %s <%s>
 379 Subject: %s\n\n"
 380                       (user-login-name)
 381                       (remember-mail-date)
 382                       (remember-mail-date t)
 383                       who
 384                       moment (system-name)
 385                       remember-default-priority
 386                       (user-full-name) user-mail-address
 387                       desc))
 388       (let ((here (point)))
 389         (insert text)
 390         (unless (bolp)
 391           (insert "\n"))
 392         (insert "\n")
 393         (goto-char here)
 394         (while (re-search-forward "^\\(From[: ]\\)" nil t)
 395           (replace-match ">\\1")))
 396       (append-to-file (point-min) (point-max) remember-mailbox)
 397       t)))
 398
 399 ;; Remembering to plain files
 400
 401 (defcustom remember-data-file "~/.notes"
 402   "*The file in which to store unprocessed data."
 403   :type 'file
 404   :group 'remember)
 405
 406 (defcustom remember-leader-text "** "
 407   "*The text used to begin each remember item."
 408   :type 'string
 409   :group 'remember)
 410
 411 (defun remember-append-to-file ()
 412   "Remember, with description DESC, the given TEXT."
 413   (let ((text (buffer-string))
 414         (desc (remember-buffer-desc)))
 415     (with-temp-buffer
 416       (insert "\n" remember-leader-text (current-time-string)
 417               " (" desc ")\n\n" text)
 418       (if (not (bolp))
 419           (insert "\n"))
 420       (if (find-buffer-visiting remember-data-file)
 421           (let ((remember-text (buffer-string)))
 422             (set-buffer (get-file-buffer remember-data-file))
 423             (save-excursion
 424               (goto-char (point-max))
 425               (insert remember-text)
 426               (when remember-save-after-remembering (save-buffer))))
 427         (append-to-file (point-min) (point-max) remember-data-file)))))
 428
 429 (defun remember-region (&optional beg end)
 430   "Remember the data from BEG to END.
 431 It is called from within the *Remember* buffer to save the text
 432 that was entered.
 433
 434 If BEG and END are nil, the entire buffer will be remembered.
 435
 436 If you want to remember a region, supply a universal prefix to
 437 `remember' instead.  For example: C-u M-x remember RET."
 438   ;; Sacha: I have no idea where remember.el gets this context information, but
 439   ;; you can just use remember-annotation-functions.
 440   (interactive)
 441   (let ((b (or beg (min (point) (or (mark) (point-min)))))
 442         (e (or end (max (point) (or (mark) (point-max))))))
 443     (save-restriction
 444       (narrow-to-region b e)
 445       (if remember-all-handler-functions
 446           (run-hooks 'remember-handler-functions)
 447         (run-hook-with-args-until-success 'remember-handler-functions))
 448       (remember-destroy))))
 449
 450 ;;;###autoload
 451 (defun remember-clipboard ()
 452   "Remember the contents of the current clipboard.
 453 Most useful for remembering things from Netscape or other X Windows
 454 application."
 455   (interactive)
 456   (remember (current-kill 0)))
 457
 458 (defun remember-finalize ()
 459   "Remember the contents of the current buffer."
 460   (interactive)
 461   (remember-region (point-min) (point-max)))
 462
 463 ;; Org needs this
 464 (if (fboundp 'define-obsolete-function-alias)
 465     (define-obsolete-function-alias 'remember-buffer 'remember-finalize)
 466   (defalias 'remember-buffer 'remember-finalize))
 467
 468 (defun remember-destroy ()
 469   "Destroy the current *Remember* buffer."
 470   (interactive)
 471   (when (equal remember-buffer (buffer-name))
 472     (kill-buffer (current-buffer))
 473     (jump-to-register remember-register)))
 474
 475 ;;; Diary integration
 476
 477 (defcustom remember-diary-file nil
 478   "*File for extracted diary entries.
 479 If this is nil, then `diary-file' will be used instead."
 480   :type 'file
 481   :group 'remember)
 482
 483 (defun remember-diary-convert-entry (entry)
 484   "Translate MSG to an entry readable by diary."
 485   (save-match-data
 486     (when remember-annotation
 487         (setq entry (concat entry " " remember-annotation)))
 488     (if (string-match "\\([0-9]+\\)\\.\\([0-9]+\\)\\.\\([0-9]+\\)" entry)
 489         (replace-match
 490          (if european-calendar-style
 491              (concat (match-string 3 entry) "/"
 492                      (match-string 2 entry) "/"
 493                      (match-string 1 entry))
 494            (concat (match-string 2 entry) "/"
 495                    (match-string 3 entry) "/"
 496                    (match-string 1 entry)))
 497          t t entry)
 498       entry)))
 499
 500 (autoload 'make-diary-entry "diary-lib")
 501
 502 ;;;###autoload
 503 (defun remember-diary-extract-entries ()
 504   "Extract diary entries from the region."
 505   (save-excursion
 506     (goto-char (point-min))
 507     (let (list)
 508       (while (re-search-forward "^DIARY:\\s-*\\(.+\\)" nil t)
 509         (add-to-list 'list (remember-diary-convert-entry (match-string 1))))
 510       (when list
 511         (make-diary-entry (mapconcat 'identity list "\n")
 512                           nil (or remember-diary-file diary-file)))
 513       nil))) ;; Continue processing
 514
 515 ;;; Internal Functions:
 516
 517 (defvar remember-mode-map
 518   (let ((map (make-sparse-keymap)))
 519     (define-key map "\C-x\C-s" 'remember-finalize)
 520     (define-key map "\C-c\C-c" 'remember-finalize)
 521     (define-key map "\C-c\C-k" 'remember-destroy)
 522
 523     map)
 524   "Keymap used in Remember mode.")
 525
 526 (defun remember-mode ()
 527   "Major mode for output from \\[remember].
 528 This buffer is used to collect data that you want to remember.
 529
 530 Just hit `C-c C-c' when you're done entering, and it will file
 531 the data away for latter retrieval, and possible indexing.
 532
 533 \\{remember-mode-map}"
 534   (interactive)
 535   (kill-all-local-variables)
 536   (indented-text-mode)
 537   (use-local-map remember-mode-map)
 538   (setq major-mode 'remember-mode
 539         mode-name "Remember")
 540   (run-hooks 'remember-mode-hook))
 541
 542 ;; arch-tag: 59312a05-06c7-4da1-b6f7-5ea41c9d5577
 543 ;;; remember.el ends here