Check in Remember Mode

7 files changed, 1049 insertions, 0 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index fcb1f0ac651..1c6edbf22dc 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,7 @@
+2007-10-30  Michael Olson  <mwolson@gnu.org>
+
+        * remember.texi: New file containing the Remember Mode Manual.
+
 2007-10-29  Michael Albinus  <michael.albinus@gmx.de>
 
         * tramp.texi (Connection caching): Host names must be different
diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi
new file mode 100644
index 00000000000..39f8b1e0d49
--- /dev/null
+++ b/doc/misc/remember.texi
@@ -0,0 +1,465 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../../info/remember
+@settitle Remember Manual
+@c %**end of header
+
+@dircategory Emacs
+@direntry
+* Remember: (remember). Simple information manager for Emacs
+@end direntry
+
+@syncodeindex fn cp
+
+@copying
+This manual is for Remember Mode, version 1.9
+
+Copyright @copyright{} 2001, 2004, 2005, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+Texts.  A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+@end copying
+
+@titlepage
+@title Guide to Remember Mode
+@subtitle a simple information manager
+@subtitle for Emacs and XEmacs
+
+@c The following two commands
+@c start the copyright page.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c So the toc is printed at the start
+@contents
+
+@ifnottex
+@node Top, Preface, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+@top Remember
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Preface::                     About the documentation.
+* Introduction::                What is Remember Mode?
+* Installation::                How to install Remember.
+* Implementation::              How Remember came into existence.
+* Quick Start::                 Get started using Remember.
+* Backends::                    Backends for saving notes.
+* Function Reference::          Interactive functions in remember.el.
+* Copying::                     The GNU General Public License gives you
+                                  permission to redistribute Remember on
+                                  certain terms; it also explains that
+                                  there is no warranty.
+* GNU Free Documentation License::  The license for this documentation.
+* Concept Index::               Search for terms.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Backends
+
+* Text File::                   Saving to a text file.
+* Mailbox::                     Saving to a mailbox.
+* Bibliography::                Saving to a bibliography.
+* Planner Page::                Saving to a Planner page.
+
+@end detailmenu
+@end menu
+
+@node Preface, Introduction, Top, Top
+@comment  node-name,  next,  previous,  up
+@chapter Preface
+
+This document describes remember-el, which was written by John Wiegley,
+was once maintained by Sacha Chua, and is now maintained by the Emacs
+developers.
+
+This document is a work in progress, and your contribution will be
+greatly appreciated.
+
+@node Introduction, Installation, Preface, Top
+@comment  node-name,  next,  previous,  up
+@chapter Introduction
+
+Todo lists, schedules, phone databases... everything we use databases
+for is really just a way to extend the power of our memory, to be able
+to remember what our conscious mind may not currently have access to.
+
+There are many different databases out there---and good ones---
+which this mode is not trying to replace.  Rather, it's how that
+data gets there that's the question.  Most of the time, we just
+want to say "Remember so-and-so's phone number, or that I have to
+buy dinner for the cats tonight."  That's the FACT.  How it's
+stored is really the computer's problem.  But at this point in
+time, it's most definitely also the user's problem, and sometimes
+so laboriously so that people just let data slip, rather than
+expend the effort to record it.
+
+``Remember'' is a mode for remembering data.  It uses whatever
+back-end is appropriate to record and correlate the data, but its main
+intention is to allow you to express as @emph{little} structure as
+possible up front.  If you later want to express more powerful
+relationships between your data, or state assumptions that were at
+first too implicit to be recognized, you can ``study'' the data later
+and rearrange it.  But the initial ``just remember this'' impulse
+should be as close to simply throwing the data at Emacs as possible.
+
+Have you ever noticed that having a laptop to write on doesn't
+@emph{actually} increase the amount of quality material that you turn
+out, in the long run?  Perhaps it's because the time we save
+electronically in one way, we're losing electronically in another; the
+tool should never dominate one's focus.  As the mystic Faridu'd-Din
+`Attar wrote: ``Be occupied as little as possible with things of the
+outer world but much with things of the inner world; then right action
+will overcome inaction.''
+
+If Emacs could become a more intelligent data store, where brainstorming
+would focus on the @emph{ideas} involved---rather than the structuring
+and format of those ideas, or having to stop your current flow of work
+in order to record them---it would map much more closely to how the mind
+(well, at least mine) works, and hence would eliminate that very
+manual-ness which computers from the very beginning have been championed
+as being able to reduce.
+
+@node Installation, Implementation, Introduction, Top
+@comment  node-name,  next,  previous,  up
+@chapter Installation
+
+Installing Remember Mode is as simple as adding the following lines to
+your Emacs configuration file (usually @file{~/.emacs.d/init.el} or
+@file{~/.emacs}).
+
+@lisp
+(add-to-list 'load-path "/path/to/remember")
+(require 'remember)
+@end lisp
+
+@node Implementation, Quick Start, Installation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Implementation
+
+Hyperbole, as a data presentation tool, always struck me as being very
+powerful, but it seemed to require a lot of ``front-end'' work before
+that data was really available.  The problem with BBDB, or keeping up
+a Bibl-mode file, is that you have to use different functions to
+record the data, and it always takes time to stop what you're doing,
+format the data in the manner expected by that particular data
+interface, and then resume your work.
+
+With ``remember'', you just hit @kbd{M-x remember} (you'd probably
+want to bind this to an easily accessible keystroke, like @kbd{C-x
+M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}.
+It will file the data away for later retrieval, and possibly indexing.
+
+Indexing is to data what ``studying'' is in the real world.  What you
+do when you study (or lucubrate, for some of us) is to realize certain
+relationships implicit in the data, so that you can make use of those
+relationships.  Expressing that a certain quote you remembered was a
+religious quote, and that you want the ability to pull up all quotes
+of a religious nature, is what studying does.  This is a more labor
+intensive task than the original remembering of the data, and it's
+typical in real life to set aside a special period of time for doing
+this work.
+
+``Remember'' works in the same way.  When you enter data, either by
+typing it into a buffer, or using the contents of the selected region,
+it will store that data---unindexed, uninterpreted---in a data pool.
+It will also try to remember as much context information as possible
+(any text properties that were set, where you copied it from, when,
+how, etc).  Later, you can walk through your accumulated set of data
+(both organized, and unorganized) and easily begin moving things
+around, and making annotations that will express the full meaning of
+that data, as far as you know it.
+
+Obviously this latter stage is more user-interface intensive, and it
+would be nice if ``remember'' could do it as elegantly as possible,
+rather than requiring a billion keystrokes to reorganize your
+hierarchy.  Well, as the future arrives, hopefully experience and user
+feedback will help to make this as intuitive a tool as possible.
+
+@node Quick Start, Backends, Implementation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Quick Start
+
+@itemize
+
+@item
+Load @file{remember.el}.
+
+@item
+Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be
+displayed.
+
+@item
+Type in what you want to remember. The first line will be treated as
+the headline, and the rest of the buffer will contain the body of the
+note.
+
+@item
+Type @kbd{C-c C-c} (@code{remember-buffer}) to save the note and close
+the @samp{*Remember*} buffer.
+@end itemize
+
+By default, @code{remember-buffer} saves the note in @file{~/.notes}.
+You can edit it now to see the remembered and timestamped note. You
+can edit this file however you want. New entries will always be added
+to the end.
+
+To remember a region of text, use the universal prefix. @kbd{C-u M-x
+remember} displays a @samp{*Remember*} buffer with the region as the
+initial contents.
+
+As a simple beginning, you can start by using the Text File backend,
+keeping your @file{~/.notes} file in outline-mode format, with a final
+entry called @samp{* Raw data}. Remembered data will be added to the
+end of the file. Every so often, you can move the data that gets
+appended there into other files, or reorganize your document.
+
+You can also store remembered data in other backends.
+(@pxref{Backends})
+
+Here is one way to map the remember functions in your @file{.emacs} to
+very accessible keystrokes facilities using the mode:
+
+@lisp
+(autoload 'remember ``remember'' nil t)
+(autoload 'remember-region ``remember'' nil t)
+
+(define-key global-map (kbd "<f9> r") 'remember)
+(define-key global-map (kbd "<f9> R") 'remember-region)
+@end lisp
+
+Check out the Planner package
+(@uref{http://www.emacswiki.org/cgi-bin/wiki/PlannerMode}) for plenty
+of annotation functions you can use with Remember. If you use Planner,
+you can easily publish your remembered notes as HTML and RSS.
+(@pxref{Planner Page})
+
+By default, remember uses the first annotation returned by
+@code{remember-annotation-functions}. To include all of the annotations,
+set @code{remember-run-all-annotation-functions-flag} to non-nil.
+
+@defopt remember-run-all-annotation-functions-flag
+Non-nil means use all annotations returned by
+@code{remember-annotation-functions}.
+@end defopt
+
+You can write custom functions that use a different set of
+remember-annotation-functions. For example:
+
+@lisp
+(defun my/remember-with-filename ()
+ "Always use the filename."
+ (interactive)
+ (let ((remember-annotation-functions '(buffer-file-name)))
+  (call-interactively 'remember)))
+@end lisp
+
+@node Backends, Function Reference, Quick Start, Top
+@chapter Backends
+
+You can save remembered notes to a variety of backends.
+
+@menu
+* Text File::                   Saving to a text file.
+* Mailbox::                     Saving to a mailbox.
+* Bibliography::                Saving to a bibliography.
+* Planner Page::                Saving to a Planner page.
+@end menu
+
+@node Text File, Mailbox, Backends, Backends
+@section Saving to a Text File
+@cindex text file
+@cindex outline
+
+This backend comes with Emacs.
+
+@lisp
+(setq remember-handler-functions '(remember-append-to-file))
+@end lisp
+
+@defopt remember-data-file
+@end defopt
+
+@defopt remember-leader-text
+@end defopt
+
+@node Mailbox, Bibliography, Text File, Backends
+@section Saving to a Mailbox
+@cindex mailbox, saving to a
+
+@lisp
+(setq remember-handler-functions '(remember-store-in-mailbox))
+@end lisp
+
+@defopt remember-mailbox
+Name of mailbox to save messages to.
+@end defopt
+
+This backend does not come with Emacs.  To get it, download the latest
+version of Remember from @url{http://download.gna.org/remember-el/}.
+
+If you want to use BBDB to associate remembered snippets with entries
+in your contact database, use the following code snippet:
+
+@lisp
+(require 'remember-bbdb)
+(setq remember-handler-functions '(remember-bbdb-store-in-mailbox))
+@end lisp
+
+@node Bibliography, Planner Page, Mailbox, Backends
+@section Saving to a Bibliography
+
+This backend does not come with Emacs.  To get it, download the latest
+version of Remember from @url{http://download.gna.org/remember-el/}.
+
+Bibl-mode is a major mode for maintaining bibliography files. You can
+get bibl-mode from:
+@uref{http://ftp.azc.uam.mx/mirrors/gnu/emacs-lisp/bosullivan-packages/bibl-mode/}.
+
+@lisp
+(require 'remember-bibl)
+@end lisp
+
+@defun remember-url
+Remember a URL in @code{bibl-mode} that is being visited with w3.
+@end defun
+
+@defun remember-location
+Remember a bookmark location in `bibl-mode'.
+@end defun
+
+You can use this in addition to your normal remember backend.
+
+@node Planner Page,  , Bibliography, Backends
+@comment  node-name,  next,  previous,  up
+@section Saving to a Planner Page
+@cindex @file{remember-planner.el}, using
+@cindex remember-el, using with PlannerMode
+
+This backend does not come with Emacs.  To get it, download the latest
+version of Remember from @url{http://download.gna.org/remember-el/}.
+
+If you are using PlannerMode, depending on your configuration, notes
+made using remember-el may actually be saved to a project and/or day
+plan page.
+
+@file{remember-planner.el} makes the notes you save with remember have
+more context information associated with them, in the way that
+PlannerMode tasks do.
+
+To use remember-planner, place this in your @file{.emacs}:
+
+@lisp
+(require 'remember-planner)
+(setq remember-handler-functions '(remember-planner-append))
+@end lisp
+
+To take advantage of PlannerMode's annotation functions, add the
+following code as well:
+
+@lisp
+(setq remember-annotation-functions planner-annotation-functions)
+@end lisp
+
+Then, type @kbd{M-x remember} to remember new text, @kbd{M-x
+remember-region} to remember the current region, or @kbd{C-u M-x
+remember} to remember the current region but have an opportunity to
+edit it before it is saved.
+
+@defopt remember-planner-xref-p
+Non-nil means cross-reference new entries with plan pages. Plan pages
+are useful for gathering related information. If you don't want a note
+associated with a plan page, you can press RET to accept the default
+(just today's page) or specify nil at the prompt.
+@end defopt
+
+@defopt remember-planner-copy-on-xref-flag
+Non-nil means copy note text instead of moving it to the plan page. If
+nil, move the note body to the plan page, leaving a cross-reference
+link on the day page. This results in shorter day pages but may be
+harder for people to read.
+@end defopt
+
+@defopt remember-planner-timestamp-format
+Format of timestamp for remember entries.
+@end defopt
+
+@file{remember-planner.el} does not define any interactive functions
+or keybindings.
+
+@node Function Reference, Copying, Backends, Top
+@comment  node-name,  next,  previous,  up
+@chapter Function Reference
+
+@subheading Interactive functions
+
+@file{remember.el} defines the following interactive functions:
+
+@defun remember initial
+Remember an arbitrary piece of data. With a prefix, it will use the
+region as @var{initial}.
+@end defun
+
+@defun remember-region beg end
+If called from within the remember buffer, @var{beg} and @var{end} are
+ignored, and the entire buffer will be remembered.  If called from any
+other buffer, that region, plus any context information specific to
+that region, will be remembered.
+@end defun
+
+@defun remember-clipboard
+Remember the contents of the current clipboard.  This is most useful
+for remembering things from Netscape or other X Windows applications.
+@end defun
+
+@defun remember-buffer
+Remember the contents of the current buffer.
+@end defun
+
+@defun remember-mode
+This enters the major mode for output from @command{remember}.  This
+buffer is used to collect data that you want remember.  Just hit
+@kbd{C-c C-c} when you're done entering, and it will go ahead and file
+the data for latter retrieval, and possible indexing.
+@end defun
+
+@subheading Keystrokes
+
+@file{remember.el} defines the following keybindings by default:
+
+@table @kbd
+
+@item C-x C-s (`remember-buffer')
+
+@item C-c C-c (`remember-buffer')
+
+@end table
+
+@node Copying, GNU Free Documentation License, Function Reference, Top
+@comment  node-name,  next,  previous,  up
+@appendix GNU GENERAL PUBLIC LICENSE
+@include gpl.texi
+
+@node GNU Free Documentation License, Concept Index, Copying, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index,  , GNU Free Documentation License, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Index
+
+@printindex cp
+
+@bye
diff --git a/etc/ChangeLog b/etc/ChangeLog
index d552455e101..017db136df7 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,7 @@
+2007-10-30  Michael Olson  <mwolson@gnu.org>
+
+        * NEWS: Add entry for Remember Mode.
+
 2007-10-29  Glenn Morris  <rgm@gnu.org>
 
         * refcards/gnus-refcard.tex: Restore Feb 2007 copyright
diff --git a/etc/NEWS b/etc/NEWS
index 10075824f6f..dcc066e9e3b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -163,6 +163,11 @@ its usage.
 
 ** minibuffer-indicate-depth-mode shows the minibuffer depth in the prompt.
 
+** Remember Mode (remember.el) is now included with Emacs.  It is a
+mode for quickly jotting down things to remember.  Included with
+remember.el is a backend that can save notes to a Diary file.  Please
+consult the Remember Manual for usage details.
+
 
 * Changes in Specialized Modes and Packages in Emacs 23.1
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 79cffa6e39a..07bc2244f7a 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -2,6 +2,12 @@
 
         * desktop.el (desktop-minor-mode-table): Add line for ERC.
 
+        * textmodes/remember.el: New file that implements a mode for
+        quickly jotting down things to remember.
+
+        * textmodes/remember-diary.el: A backend for remember.el that
+        implements saving notes to a Diary file.
+
 2007-10-29  Ken Manheimer  <ken.manheimer@gmail.com>
 
         * allout.el (allout-command-prefix, allout-inhibit-auto-fill):
diff --git a/lisp/textmodes/remember-diary.el b/lisp/textmodes/remember-diary.el
new file mode 100644
index 00000000000..4053908e1fc
--- /dev/null
+++ b/lisp/textmodes/remember-diary.el
@@ -0,0 +1,93 @@
+;;; remember-diary --- extracting diary information from buffers
+
+;; Copyright (C) 1999, 2000, 2001, 2004 Free Software Foundation, Inc.
+
+;; Author: Sacha Chua <sacha@free.net.ph>
+;; Created: 24 Mar 2004
+;; Keywords: data memory todo pim diary
+;; URL: http://gna.org/projects/remember-el/
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Commentary:
+
+;; This module recognizes entries of the form
+;;
+;;     DIARY: ....
+;;
+;; and puts them in your ~/.diary (or remember-diary-file) together
+;; with an annotation. Planner-style dates (yyyy.mm.dd) are converted
+;; to yyyy-mm-dd so that diary can understand them.
+;;
+;; For example:
+;;
+;; DIARY: 2003.08.12 Sacha's birthday
+;;
+;; is stored as
+;;
+;; 2003.08.12 Sacha's birthday [[/home/sacha/notebook/emacs/emacs-wiki/remember-diary.el]]
+;;
+;; To use, add the following to your .emacs:
+;;
+;;    (require 'remember-diary)
+;;    ;; This should be before other entries that may return t
+;;    (add-to-list 'remember-handler-functions 'remember-diary-extract-entries)
+;;
+
+(require 'remember)
+(require 'diary-lib)
+
+;;; Code:
+(defcustom remember-diary-file diary-file
+  "*File for extracted diary entries."
+  :type 'file
+  :group 'remember)
+
+(defun remember-diary-convert-entry (entry)
+  "Translate MSG to an entry readable by diary."
+  (save-match-data
+    (when remember-annotation
+        (setq entry (concat entry " " remember-annotation)))
+    (if (string-match "\\([0-9]+\\)\\.\\([0-9]+\\)\\.\\([0-9]+\\)" entry)
+        (replace-match
+         (if european-calendar-style
+             (concat (match-string 3 entry) "/"
+                     (match-string 2 entry) "/"
+                     (match-string 1 entry))
+           (concat (match-string 2 entry) "/"
+                   (match-string 3 entry) "/"
+                   (match-string 1 entry)))
+         t t entry)
+      entry)))
+
+;;;###autoload
+(defun remember-diary-extract-entries ()
+  "Extract diary entries from the region."
+  (save-excursion
+    (goto-char (point-min))
+    (let (list)
+      (while (re-search-forward "^DIARY:\\s-*\\(.+\\)" nil t)
+        (add-to-list 'list (remember-diary-convert-entry (match-string 1))))
+      (when list
+        (make-diary-entry (mapconcat 'identity list "\n")
+                          nil remember-diary-file))
+      nil))) ;; Continue processing
+
+(provide 'remember-diary)
+
+;;; remember-diary.el ends here
diff --git a/lisp/textmodes/remember.el b/lisp/textmodes/remember.el
new file mode 100644
index 00000000000..ac9931ff320
--- /dev/null
+++ b/lisp/textmodes/remember.el
@@ -0,0 +1,472 @@
+;;; remember --- a mode for quickly jotting down things to remember
+
+;; Copyright (C) 1999, 2000, 2001, 2003, 2004, 2005, 2006,
+;;   2007 Free Software Foundation, Inc.
+
+;; Author: John Wiegley <johnw@gnu.org>
+;; Created: 29 Mar 1999
+;; Version: 1.9
+;; Keywords: data memory todo pim
+;; URL: http://gna.org/projects/remember-el/
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Commentary:
+
+;; The idea
+;;
+;; Todo lists, schedules, phone databases... everything we use
+;; databases for is really just a way to extend the power of our
+;; memory.  To be able to remember what our conscious mind may not
+;; currently have access to.
+;;
+;; There are many different databases out there -- and good ones --
+;; which this mode is not trying to replace.  Rather, it's how that
+;; data gets there that's the question.  Most of the time, we just
+;; want to say "Remember so-and-so's phone number, or that I have to
+;; buy dinner for the cats tonight."  That's the FACT.  How it's
+;; stored is really the computer's problem.  But at this point in
+;; time, it's most definitely also the user's problem, and sometimes
+;; so laboriously so that people just let data slip, rather than
+;; expend the effort to record it.
+;;
+;; "Remember" is a mode for remembering data.  It uses whatever
+;; back-end is appropriate to record and correlate the data, but it's
+;; main intention is to allow you to express as _little_ structure as
+;; possible up front.  If you later want to express more powerful
+;; relationships between your data, or state assumptions that were at
+;; first too implicit to be recognized, you can "study" the data later
+;; and rearrange it.  But the initial "just remember this" impulse
+;; should be as close to simply throwing the data at Emacs as
+;; possible.
+;;
+;; Implementation
+;;
+;; Hyperbole, as a data presentation tool, always struck me as being
+;; very powerful, but it seemed to require a lot of "front-end" work
+;; before that data was really available.  The problem with BBDB, or
+;; keeping up a Bibl-mode file, is that you have to use different
+;; functions to record the data, and it always takes time to stop what
+;; you're doing, format the data in the manner expected by that
+;; particular data interface, and then resume your work.
+;;
+;; With "remember", you just hit `M-x remember' (you'd probably want
+;; to bind this to an easily accessible keystroke, like C-x M-r), slam
+;; in your text however you like, and then hit C-c C-c.  It will file
+;; the data away for later retrieval, and possibly indexing.
+;;
+;; Indexing is to data what "studying" is in the real world.  What you
+;; do when you study (or lucubrate, for some of us) is to realize
+;; certain relationships implicit in the data, so that you can make
+;; use of those relationships.  Expressing that a certain quote you
+;; remembered was a religious quote, and that you want the ability to
+;; pull up all quotes of a religious nature, is what studying does.
+;; This is a more labor intensive task than the original remembering
+;; of the data, and it's typical in real life to set aside a special
+;; period of time for doing this work.
+;;
+;; "Remember" works in the same way.  When you enter data, either by
+;; typing it into a buffer, or using the contents of the selected
+;; region, it will store that data -- unindexed, uninterpreted -- in a
+;; data pool.  It will also try to remember as much context
+;; information as possible (any text properties that were set, where
+;; you copied it from, when, how, etc).  Later, you can walk through
+;; your accumulated set of data (both organized, and unorganized) and
+;; easily begin moving things around, and making annotations that will
+;; express the full meaning of that data, as far as you know it.
+;;
+;; Obviously this latter stage is more user-interface intensive, and
+;; it would be nice if "remember" could do it as elegantly as
+;; possible, rather than requiring a billion keystrokes to reorganize
+;; your hierarchy.  Well, as the future arrives, hopefully experience
+;; and user feedback will help to make this as intuitive a tool as
+;; possible.
+;;
+;; Future Goals
+;;
+;; This tool hopes to track (and by doing it with as little new code
+;; as possible):
+;;
+;;  - The raw data that gets entered
+;;
+;;  - The relationships between that data (either determined
+;;    implicitly by parsing the input, or explicitly by the user's
+;;    studying the data).
+;;
+;;  - Revisioning of the data
+;;
+;;  - Where it came from, and any context information that can be
+;;    programmatically determined.
+;;
+;;  - Allowing particular views of the initially amorphous data pool
+;;    (ala the Xanadu concept).
+;;
+;;  - Storage of the data in a manner most appopriate to that data,
+;;    such as keeping address-book type information in BBDB, etc.
+;;
+;; Using "remember"
+;;
+;; As a rough beginning, what I do is to keep my .notes file in
+;; outline-mode format, with a final entry called "* Raw data".  Then,
+;; at intervals, I can move the data that gets appended there into
+;; other places.  But certainly this should evolve into an intuitive
+;; mechanism for shuffling data off to its appropriate corner of the
+;; universe.
+;;
+;; Mapping the remember functions to very accessible keystrokes
+;; facilities using the mode:
+;;
+;;  (autoload 'remember "remember" nil t)
+;;  (autoload 'remember-region "remember" nil t)
+;;
+;;  (define-key global-map [f8] 'remember)
+;;  (define-key global-map [f9] 'remember-region)
+;;
+;; planner.el users should use `remember-to-planner' instead of `remember'
+;; to save more context information.
+;;
+;; Feedback
+;;
+;; If Emacs could become a more intelligent data store, where
+;; brainstorming would focus on the IDEAS involved -- rather than the
+;; structuring and format of those ideas, or having to stop your
+;; current flow of work in order to record them -- it would map much
+;; more closely to how the mind (well, at least mine) works, and hence
+;; would eliminate that very manual-ness which computers from the very
+;; beginning have been championed as being able to reduce.
+;;
+;; Have you ever noticed that having a laptop to write on doesn't
+;; _actually_ increase the amount of quality material that you turn
+;; out, in the long run?  Perhaps its because the time we save
+;; electronically in one way, we're losing electronically in another;
+;; the tool should never dominate one's focus.  As the mystic
+;; Faridu'd-Din `Attar wrote: "Be occupied as little as possible with
+;; things of the outer world but much with things of the inner world;
+;; then right action will overcome inaction."
+
+;;; History:
+
+;;; Code:
+
+(provide 'remember)
+
+(defconst remember-version "1.9"
+  "This version of remember.")
+
+(defgroup remember nil
+  "A mode to remember information."
+  :group 'data)
+
+;;; User Variables:
+
+(defcustom remember-mode-hook nil
+  "Functions run upon entering `remember-mode'."
+  :type 'hook
+  :options '(flyspell-mode turn-on-auto-fill)
+  :group 'remember)
+
+(defcustom remember-in-new-frame nil
+  "Non-nil means use a separate frame for capturing remember data."
+  :type 'boolean
+  :group 'remember)
+
+(defcustom remember-register ?R
+  "The register in which the window configuration is stored."
+  :type 'character
+  :group 'remember)
+
+(defcustom remember-filter-functions nil
+  "*Functions run to filter remember data.
+All functions are run in the remember buffer."
+  :type 'hook
+  :group 'remember)
+
+(defcustom remember-handler-functions '(remember-append-to-file)
+  "*Functions run to process remember data.
+Each function is called with the current buffer narrowed to what the
+user wants remembered.
+If any function returns non-nil, the data is assumed to have been
+recorded somewhere by that function. "
+  :type 'hook
+  :group 'remember)
+
+(defcustom remember-all-handler-functions nil
+  "If non-nil every function in `remember-handler-functions' is
+called."
+  :type 'boolean
+  :group 'remember)
+
+;;; Internal Variables:
+
+(defvar remember-buffer "*Remember*"
+  "The name of the remember data entry buffer.")
+
+(defcustom remember-save-after-remembering t
+  "*Non-nil means automatically save after remembering."
+  :type 'boolean
+  :group 'remember)
+
+;;; User Functions:
+
+;; People with planner.el can set this to planner-annotation-functions:
+;; (defvaralias 'remember-annotation-functions 'planner-annotation-functions)
+;; or (defalias 'remember-annotation-functions 'planner-annotation-functions)
+(defcustom remember-annotation-functions
+  (if (boundp 'planner-annotation-functions)
+      planner-annotation-functions
+    '(buffer-file-name))
+  "Hook that returns an annotation to be inserted into the remember buffer.
+If you have planner.el, it's nice to set this to
+`planner-annotation-functions'."
+  :type 'hook
+  :group 'remember)
+
+(defvar remember-annotation nil
+  "Current annotation.")
+(defvar remember-initial-contents nil
+  "Initial contents to place into *Remember* buffer.")
+(defvar remember-before-remember-hook nil
+  "Functions run before switching to the *Remember* buffer.")
+
+(defcustom remember-run-all-annotation-functions-flag nil
+  "Non-nil means use all annotations returned by
+`remember-annotation-functions'."
+  :type 'boolean
+  :group 'remember)
+
+;;;###autoload
+(defun remember (&optional initial)
+  "Remember an arbitrary piece of data.
+With a prefix, uses the region as INITIAL."
+  (interactive
+   (list (when current-prefix-arg
+           (buffer-substring (point) (mark)))))
+  (funcall (if remember-in-new-frame
+               #'frame-configuration-to-register
+             #'window-configuration-to-register) remember-register)
+  (let* ((annotation
+          (if remember-run-all-annotation-functions-flag
+              (mapconcat 'identity
+                         (delq nil
+                               (mapcar 'funcall remember-annotation-functions))
+                         "\n")
+            (run-hook-with-args-until-success
+             'remember-annotation-functions)))
+         (buf (get-buffer-create remember-buffer)))
+    (run-hooks 'remember-before-remember-hook)
+    (funcall (if remember-in-new-frame
+                 #'switch-to-buffer-other-frame
+               #'switch-to-buffer-other-window) buf)
+    (if remember-in-new-frame
+        (set-window-dedicated-p
+         (get-buffer-window (current-buffer) (selected-frame)) t))
+    (remember-mode)
+    (when (= (point-max) (point-min))
+      (when initial (insert initial))
+      (setq remember-annotation annotation)
+      (when remember-initial-contents (insert remember-initial-contents))
+      (when (and (stringp annotation)
+                 (not (equal annotation "")))
+        (insert "\n\n" annotation))
+      (setq remember-initial-contents nil)
+      (goto-char (point-min)))
+    (message "Use C-c C-c to remember the data.")))
+
+;;;###autoload
+(defun remember-other-frame (&optional initial)
+  "Call `remember' in another frame."
+  (interactive
+   (list (when current-prefix-arg
+           (buffer-substring (point) (mark)))))
+  (let ((remember-in-new-frame t))
+    (remember initial)))
+
+(defsubst remember-time-to-seconds (time)
+  "Convert TIME to a floating point number."
+  (+ (* (car time) 65536.0)
+     (cadr time)
+     (/ (or (car (cdr (cdr time))) 0) 1000000.0)))
+
+(defsubst remember-mail-date (&optional rfc822-p)
+  "Return a simple date.  Nothing fancy."
+  (if rfc822-p
+      (format-time-string "%a, %e %b %Y %T %z" (current-time))
+    (format-time-string "%c" (current-time))))
+
+(defun remember-buffer-desc ()
+  "Using the first line of the current buffer, create a short description."
+  (buffer-substring (point-min)
+                    (save-excursion
+                      (goto-char (point-min))
+                      (end-of-line)
+                      (if (> (- (point) (point-min)) 60)
+                          (goto-char (+ (point-min) 60)))
+                      (point))))
+
+;; Remembering to UNIX mailboxes
+
+(defcustom remember-mailbox "~/Mail/remember"
+  "*The file in which to store remember data as mail."
+  :type 'file
+  :group 'remember)
+
+(defcustom remember-default-priority "medium"
+  "*The default priority for remembered mail messages."
+  :type 'string
+  :group 'remember)
+
+(defun remember-store-in-mailbox ()
+  "Store remember data as if it were incoming mail.
+In which case `remember-mailbox' should be the name of the mailbox.
+Each piece of psuedo-mail created will have an `X-Todo-Priority'
+field, for the purpose of appropriate splitting."
+  (let ((who (read-string "Who is this item related to? "))
+        (moment
+         (format "%.0f" (remember-time-to-seconds (current-time))))
+        (desc (remember-buffer-desc))
+        (text (buffer-string)))
+    (with-temp-buffer
+      (insert (format "
+From %s  %s
+Date: %s
+From: %s
+Message-Id: <remember-%s@%s>
+X-Todo-Priority: %s
+To: %s <%s>
+Subject: %s\n\n"
+                      (user-login-name)
+                      (remember-mail-date)
+                      (remember-mail-date t)
+                      who
+                      moment (system-name)
+                      remember-default-priority
+                      (user-full-name) user-mail-address
+                      desc))
+      (let ((here (point)))
+        (insert text)
+        (unless (bolp)
+          (insert "\n"))
+        (insert "\n")
+        (goto-char here)
+        (while (re-search-forward "^\\(From[: ]\\)" nil t)
+          (replace-match ">\\1")))
+      (append-to-file (point-min) (point-max) remember-mailbox)
+      t)))
+
+(custom-add-option 'remember-handler-functions 'remember-store-in-mailbox)
+
+;; Remembering to plain files
+
+(defcustom remember-data-file "~/.notes"
+  "*The file in which to store unprocessed data."
+  :type 'file
+  :group 'remember)
+
+(defcustom remember-leader-text "** "
+  "*The text used to begin each remember item."
+  :type 'string
+  :group 'remember)
+
+(defun remember-append-to-file ()
+  "Remember, with description DESC, the given TEXT."
+  (let ((text (buffer-string))
+        (desc (remember-buffer-desc)))
+    (with-temp-buffer
+      (insert "\n" remember-leader-text (current-time-string)
+              " (" desc ")\n\n" text)
+      (if (not (bolp))
+          (insert "\n"))
+      (if (find-buffer-visiting remember-data-file)
+          (let ((remember-text (buffer-string)))
+            (set-buffer (get-file-buffer remember-data-file))
+            (save-excursion
+              (goto-char (point-max))
+              (insert remember-text)
+              (when remember-save-after-remembering (save-buffer))))
+        (append-to-file (point-min) (point-max) remember-data-file)))))
+
+(custom-add-option 'remember-handler-functions 'remember-append-to-file)
+
+;;;###autoload
+(defun remember-region (&optional beg end)
+  "Remember the data from BEG to END.
+If called from within the remember buffer, BEG and END are ignored,
+and the entire buffer will be remembered.
+
+This function is meant to be called from the *Remember* buffer.
+If you want to remember a region, supply a universal prefix to
+`remember' instead. For example: C-u M-x remember."
+  ;; Sacha: I have no idea where remember.el gets this context information, but
+  ;; you can just use remember-annotation-functions.
+  (interactive)
+  (let ((b (or beg (min (point) (or (mark) (point-min)))))
+        (e (or end (max (point) (or (mark) (point-max))))))
+    (save-restriction
+      (narrow-to-region b e)
+      (if remember-all-handler-functions
+          (run-hooks 'remember-handler-functions)
+        (run-hook-with-args-until-success 'remember-handler-functions))
+      (remember-destroy))))
+
+;;;###autoload
+(defun remember-clipboard ()
+  "Remember the contents of the current clipboard.
+Most useful for remembering things from Netscape or other X Windows
+application."
+  (interactive)
+  (remember (current-kill 0)))
+
+;;;###autoload
+(defun remember-buffer ()
+  "Remember the contents of the current buffer."
+  (interactive)
+  (remember-region (point-min) (point-max)))
+
+;;;###autoload
+(defun remember-destroy ()
+  "Destroy the current *Remember* buffer."
+  (interactive)
+  (when (equal remember-buffer (buffer-name))
+    (kill-buffer (current-buffer))
+    (jump-to-register remember-register)))
+
+;;; Internal Functions:
+
+(defvar remember-mode-map ()
+  "Keymap used in Remember mode.")
+(when (not remember-mode-map)
+  (setq remember-mode-map (make-sparse-keymap))
+  (define-key remember-mode-map "\C-x\C-s" 'remember-buffer)
+  (define-key remember-mode-map "\C-c\C-c" 'remember-buffer)
+  (define-key remember-mode-map "\C-c\C-k" 'remember-destroy))
+
+(defun remember-mode ()
+  "Major mode for output from \\[remember].
+\\<remember-mode-map>This buffer is used to collect data that you want
+remember.  Just hit \\[remember-region] when you're done entering, and
+it will go ahead and file the data for latter retrieval, and possible
+indexing.  \\{remember-mode-map}"
+  (interactive)
+  (kill-all-local-variables)
+  (indented-text-mode)
+  (use-local-map remember-mode-map)
+  (setq major-mode 'remember-mode
+        mode-name "Remember")
+  (run-hooks 'remember-mode-hook))
+
+;;; remember.el ends here