Check in Remember Mode

2 files changed, 469 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