* doc/man/emacsclient.1: Tiny markup fix
[emacs.git] / doc / misc / remember.texi
blob5e2c1e2b0f6ec28ad40a55466dbe9e880c62bf8b
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../../info/remember
4 @settitle Remember Manual
5 @syncodeindex fn cp
6 @documentencoding UTF-8
7 @c %**end of header
9 @copying
10 This manual is for Remember Mode, version 2.0
12 Copyright @copyright{} 2001, 2004--2005, 2007--2014
13 Free Software Foundation, Inc.
15 @quotation
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
20 and with the Back-Cover Texts as in (a) below.  A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''.
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
25 @end quotation
26 @end copying
28 @dircategory Emacs misc features
29 @direntry
30 * Remember: (remember).         Simple information manager for Emacs.
31 @end direntry
33 @titlepage
34 @title Guide to Remember Mode
35 @subtitle a simple information manager
36 @subtitle for Emacs and XEmacs
38 @c The following two commands
39 @c start the copyright page.
40 @page
41 @vskip 0pt plus 1filll
42 @insertcopying
43 @end titlepage
45 @contents
47 @ifnottex
48 @node Top
49 @top Remember
51 @insertcopying
52 @end ifnottex
54 @menu
55 * Preface::                     About the documentation.
56 * Introduction::                What is Remember Mode?
57 * Implementation::              How Remember came into existence.
58 * Quick Start::                 Get started using Remember.
59 * Function Reference::          Interactive functions in remember.el.
60 * Keystrokes::                  Keystrokes bound in Remember Mode.
61 * Backends::                    Backends for saving notes.
62 * GNU Free Documentation License::  The license for this documentation.
63 * Concept Index::               Search for terms.
65 @detailmenu
66  --- The Detailed Node Listing ---
68 Backends
70 * Text File::                   Saving to a text file.
71 * Separate Text Files::         Saving to separate text files.
72 * Diary::                       Saving to a Diary file.
73 * Mailbox::                     Saving to a mailbox.
74 * Org::                         Saving to an Org Mode file.
76 @end detailmenu
77 @end menu
79 @node Preface
80 @chapter Preface
82 This document describes remember.el, which was written by John Wiegley,
83 was once maintained by Sacha Chua, and is now maintained by the Emacs
84 developers.
86 This document is a work in progress, and your contribution will be
87 greatly appreciated.
89 @node Introduction
90 @chapter Introduction
92 Todo lists, schedules, phone databases... everything we use databases
93 for is really just a way to extend the power of our memory, to be able
94 to remember what our conscious mind may not currently have access to.
96 There are many different databases out there---and good ones---which
97 this mode is not trying to replace.  Rather, it's how that data gets
98 there that's the question.  Most of the time, we just want to say
99 ``Remember so-and-so's phone number, or that I have to buy dinner for the
100 cats tonight.''  That's the FACT@.  How it's stored is really the
101 computer's problem.  But at this point in time, it's most definitely
102 also the user's problem, and sometimes so laboriously so that people
103 just let data slip, rather than expend the effort to record it.
105 ``Remember'' is a mode for remembering data.  It uses whatever
106 back-end is appropriate to record and correlate the data, but its main
107 intention is to allow you to express as @emph{little} structure as
108 possible up front.  If you later want to express more powerful
109 relationships between your data, or state assumptions that were at
110 first too implicit to be recognized, you can ``study'' the data later
111 and rearrange it.  But the initial ``just remember this'' impulse
112 should be as close to simply throwing the data at Emacs as possible.
114 Have you ever noticed that having a laptop to write on doesn't
115 @emph{actually} increase the amount of quality material that you turn
116 out, in the long run?  Perhaps it's because the time we save
117 electronically in one way, we're losing electronically in another; the
118 tool should never dominate one's focus.  As the mystic Faridu'd-Din
119 `Attar wrote: ``Be occupied as little as possible with things of the
120 outer world but much with things of the inner world; then right action
121 will overcome inaction.''
123 If Emacs could become a more intelligent data store, where brainstorming
124 would focus on the @emph{ideas} involved---rather than the structuring
125 and format of those ideas, or having to stop your current flow of work
126 in order to record them---it would map much more closely to how the mind
127 (well, at least mine) works, and hence would eliminate that very
128 manual-ness which computers from the very beginning have been championed
129 as being able to reduce.
131 @node Implementation
132 @chapter Implementation
134 Hyperbole, as a data presentation tool, always struck me as being very
135 powerful, but it seemed to require a lot of ``front-end'' work before
136 that data was really available.  The problem with BBDB, or keeping up
137 a Bibl-mode file, is that you have to use different functions to
138 record the data, and it always takes time to stop what you're doing,
139 format the data in the manner expected by that particular data
140 interface, and then resume your work.
142 With ``remember'', you just hit @kbd{M-x remember} (you'd probably
143 want to bind this to an easily accessible keystroke, like @kbd{C-x
144 M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}.
145 It will file the data away for later retrieval, and possibly indexing.
147 Indexing is to data what ``studying'' is in the real world.  What you do
148 when you study (or lucubrate, for some of us) is to realize certain
149 relationships implicit in the data, so that you can make use of those
150 relationships.  Expressing that a certain quote you remembered was a
151 literary quote, and that you want the ability to pull up all quotes of a
152 literary nature, is what studying does.  This is a more labor intensive
153 task than the original remembering of the data, and it's typical in real
154 life to set aside a special period of time for doing this work.
156 ``Remember'' works in the same way.  When you enter data, either by
157 typing it into a buffer, or using the contents of the selected region,
158 it will store that data---unindexed, uninterpreted---in a data pool.
159 It will also try to remember as much context information as possible
160 (any text properties that were set, where you copied it from, when,
161 how, etc.).  Later, you can walk through your accumulated set of data
162 (both organized, and unorganized) and easily begin moving things
163 around, and making annotations that will express the full meaning of
164 that data, as far as you know it.
166 Obviously this latter stage is more user-interface intensive, and it
167 would be nice if ``remember'' could do it as elegantly as possible,
168 rather than requiring a billion keystrokes to reorganize your
169 hierarchy.  Well, as the future arrives, hopefully experience and user
170 feedback will help to make this as intuitive a tool as possible.
172 @node Quick Start
173 @chapter Quick Start
175 @itemize
177 @item
178 Type @kbd{M-x remember}.  The @file{*Remember*} buffer should be
179 displayed.
181 @item
182 Type in what you want to remember.  The first line will be treated as
183 the headline, and the rest of the buffer will contain the body of the
184 note.
186 @item
187 Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close
188 the @file{*Remember*} buffer.
189 @end itemize
191 By default, @code{remember-finalize} saves the note in @file{~/emacs.d/notes}.
192 You can edit it now to see the remembered and timestamped note.  You
193 can edit this file however you want.  New entries will always be added
194 to the end.
196 To remember a region of text, use the universal prefix.  @kbd{C-u M-x
197 remember} displays a @file{*Remember*} buffer with the region as the
198 initial contents.
200 As a simple beginning, you can start by using the Text File backend,
201 keeping your @file{~/.emacs.d/notes} file in outline-mode format, with a final
202 entry called @samp{* Raw data}.  Remembered data will be added to the
203 end of the file.  Every so often, you can move the data that gets
204 appended there into other files, or reorganize your document.
206 You can also store remembered data in other backends.  @xref{Backends}.
208 Here is one way to map the remember functions in your init file
209 (@pxref{Init File, , The Emacs Initialization File, emacs, GNU Emacs
210 Manual}) to very accessible keystrokes facilities using the mode:
212 @lisp
213 (define-key global-map (kbd "<f9> r") 'remember)
214 (define-key global-map (kbd "<f9> R") 'remember-region)
215 @end lisp
217 @cindex annotation
218 By default, remember uses the first annotation returned by
219 @code{remember-annotation-functions}.  To include all of the annotations,
220 set @code{remember-run-all-annotation-functions-flag} to a
221 non-@code{nil} value.
223 @defopt remember-run-all-annotation-functions-flag
224 Non-@code{nil} means use all annotations returned by
225 @code{remember-annotation-functions}.
226 @end defopt
228 You can write custom functions that use a different set of
229 remember-annotation-functions.  For example:
231 @lisp
232 (defun my/remember-with-filename ()
233  "Always use the filename."
234  (interactive)
235  (let ((remember-annotation-functions '(buffer-file-name)))
236   (call-interactively 'remember)))
237 @end lisp
239 @cindex notes
240 The @code{remember-notes} command creates a @dfn{notes} buffer that
241 visits the file specified by the option @code{remember-data-file}.
242 The option @code{remember-notes-buffer-name} specifies the name of the
243 buffer.  The buffer uses @code{remember-notes-initial-major-mode} and
244 @code{remember-notes-mode} minor mode.  Use @kbd{C-c C-c} to save
245 and bury the buffer.  The command @code{save-some-buffers} saves this
246 buffer without asking.  This function is a suitable setting for
247 @code{initial-buffer-choice}.
250 @node Function Reference
251 @chapter Function Reference
253 @file{remember.el} defines the following interactive functions:
255 @defun remember &optional initial
256 Remember an arbitrary piece of data.  With a prefix, it will use the
257 region as @var{initial}.
258 @end defun
260 @defun remember-other-frame &optional initial
261 Like @code{remember}, but uses a new frame.
262 @end defun
264 @defun remember-region &optional beg end
265 If called from within the remember buffer, @var{beg} and @var{end} are
266 ignored, and the entire buffer will be remembered.  If called from any
267 other buffer, that region, plus any context information specific to
268 that region, will be remembered.
269 @end defun
271 @defun remember-clipboard
272 Remember the contents of the current clipboard.  This is most useful
273 for remembering things from Netscape or other X Windows applications.
274 @end defun
276 @defun remember-finalize
277 Remember the contents of the current buffer.
278 @end defun
280 @defun remember-destroy
281 Destroy the current remember buffer.
282 @end defun
284 @defun remember-mode
285 This enters the major mode (@pxref{Major Modes, , Major Modes, emacs,
286 GNU Emacs Manual}) for output from @code{remember}.  This buffer is
287 used to collect data that you want remember.  Just hit @kbd{C-c C-c}
288 when you're done entering, and it will go ahead and file the data for
289 latter retrieval, and possible indexing.
290 @end defun
292 @defun remember-notes &optional switch-to
293 This returns the notes buffer, creating it if needed, and switches
294 to it if called interactively (or if @var{switch-to} is non-@code{nil}).
295 The notes buffer visits @code{remember-data-file}, and
296 is named @code{remember-notes-buffer-name}.  It uses
297 @code{remember-notes-initial-major-mode} and @code{remember-notes-mode}
298 minor mode.
299 @end defun
301 @defun remember-notes-mode &optional arg
302 This is a minor mode for the notes buffer.  It sets
303 @code{buffer-save-without-query} so that @code{save-some-buffers} will
304 save the notes buffer without asking.  Use @kbd{C-c C-c} to
305 run the command @code{remember-notes-save-and-bury-buffer}.
306 @end defun
308 @defun remember-notes-save-and-bury-buffer
309 Save (if it is modified) and bury the current buffer.
310 @end defun
312 @node Keystrokes
313 @chapter Keystroke Reference
315 @file{remember.el} defines the following keybindings by default:
317 @table @kbd
319 @item C-c C-c
320 @itemx C-x C-s
321 Remember the contents of the current buffer (`remember-finalize').
323 @item C-c C-k
324 Destroy the current @file{*Remember*} buffer (`remember-destroy').
326 @end table
328 @node Backends
329 @chapter Backends
331 You can save remembered notes to a variety of backends.
333 @menu
334 * Text File::                   Saving to a text file.
335 * Separate Text Files::         Saving to separate text files.
336 * Diary::                       Saving to a Diary file.
337 * Mailbox::                     Saving to a mailbox.
338 * Org::                         Saving to an Org Mode file.
339 @end menu
341 @node Text File
342 @section Saving to a Text File
343 @cindex text file, saving to
345 @subheading Insinuation
347 @lisp
348 (setq remember-handler-functions '(remember-append-to-file))
349 @end lisp
351 @subheading Options
353 @defopt remember-data-file
354 The file in which to store unprocessed data.
355 @end defopt
357 @defopt remember-leader-text
358 The text used to begin each remember item.
359 @end defopt
362 @node Separate Text Files
363 @section Saving to Separate Text Files
364 @cindex text files, saving to separate
366 @subheading Insinuation
368 @lisp
369 (setq remember-handler-functions '(remember-store-in-files))
370 @end lisp
372 @subheading Options
374 @defopt remember-data-directory
375 The directory in which to store remember data as files.
376 @end defopt
378 @defopt remember-directory-file-name-format
379 A format string to use for naming files in the remember directory.
380 File names are formed by calling @code{format-time-string} at the time
381 of saving, using this format string.
382 @end defopt
385 @node Diary
386 @section Saving to a Diary file
387 @cindex diary, integration
389 @subheading Insinuation
391 @lisp
392 (add-to-list 'remember-handler-functions 'remember-diary-extract-entries)
393 @end lisp
395 @subheading Options
397 @defopt remember-diary-file
398 File for extracted diary entries.
399 If this is @code{nil}, then @code{diary-file} will be used instead.
400 @end defopt
402 @node Mailbox
403 @section Saving to a Mailbox
404 @cindex mailbox, saving to
406 @subheading Insinuation
408 @lisp
409 (add-to-list 'remember-handler-functions 'remember-store-in-mailbox)
410 @end lisp
412 @subheading Options
414 @defopt remember-mailbox
415 The file in which to store remember data as mail.
416 @end defopt
418 @defopt remember-default-priority
419 The default priority for remembered mail messages.
420 @end defopt
422 @node Org
423 @section Saving to an Org Mode file
424 @cindex org mode, integration
426 @ignore
427 From org.texi:
428 Up to version 6.36 Org used a special setup
429 for @file{remember.el}.  @file{org-remember.el} is still part of Org mode for
430 backward compatibility with existing setups.  You can find the documentation
431 for org-remember at @url{http://orgmode.org/org-remember.pdf}.
432 @end ignore
433 For instructions on how to integrate Remember with Org Mode,
434 consult @ref{Capture, , , org}.
436 @node GNU Free Documentation License
437 @appendix GNU Free Documentation License
438 @include doclicense.texi
440 @node Concept Index
441 @unnumbered Index
443 @printindex cp
445 @bye