| 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 |
| 8 | |
| 9 | @copying |
| 10 | This manual is for Remember Mode, version 2.0 |
| 11 | |
| 12 | Copyright @copyright{} 2001, 2004--2005, 2007--2014 |
| 13 | Free Software Foundation, Inc. |
| 14 | |
| 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''. |
| 22 | |
| 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 |
| 27 | |
| 28 | @dircategory Emacs misc features |
| 29 | @direntry |
| 30 | * Remember: (remember). Simple information manager for Emacs. |
| 31 | @end direntry |
| 32 | |
| 33 | @titlepage |
| 34 | @title Guide to Remember Mode |
| 35 | @subtitle a simple information manager |
| 36 | @subtitle for Emacs and XEmacs |
| 37 | |
| 38 | @c The following two commands |
| 39 | @c start the copyright page. |
| 40 | @page |
| 41 | @vskip 0pt plus 1filll |
| 42 | @insertcopying |
| 43 | @end titlepage |
| 44 | |
| 45 | @contents |
| 46 | |
| 47 | @ifnottex |
| 48 | @node Top |
| 49 | @top Remember |
| 50 | |
| 51 | @insertcopying |
| 52 | @end ifnottex |
| 53 | |
| 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. |
| 64 | |
| 65 | @detailmenu |
| 66 | --- The Detailed Node Listing --- |
| 67 | |
| 68 | Backends |
| 69 | |
| 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. |
| 75 | |
| 76 | @end detailmenu |
| 77 | @end menu |
| 78 | |
| 79 | @node Preface |
| 80 | @chapter Preface |
| 81 | |
| 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. |
| 85 | |
| 86 | This document is a work in progress, and your contribution will be |
| 87 | greatly appreciated. |
| 88 | |
| 89 | @node Introduction |
| 90 | @chapter Introduction |
| 91 | |
| 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. |
| 95 | |
| 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. |
| 104 | |
| 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. |
| 113 | |
| 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.'' |
| 122 | |
| 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. |
| 130 | |
| 131 | @node Implementation |
| 132 | @chapter Implementation |
| 133 | |
| 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. |
| 141 | |
| 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. |
| 146 | |
| 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. |
| 155 | |
| 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. |
| 165 | |
| 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. |
| 171 | |
| 172 | @node Quick Start |
| 173 | @chapter Quick Start |
| 174 | |
| 175 | @itemize |
| 176 | |
| 177 | @item |
| 178 | Type @kbd{M-x remember}. The @file{*Remember*} buffer should be |
| 179 | displayed. |
| 180 | |
| 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. |
| 185 | |
| 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 |
| 190 | |
| 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. |
| 195 | |
| 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. |
| 199 | |
| 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. |
| 205 | |
| 206 | You can also store remembered data in other backends. @xref{Backends}. |
| 207 | |
| 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: |
| 211 | |
| 212 | @lisp |
| 213 | (define-key global-map (kbd "<f9> r") 'remember) |
| 214 | (define-key global-map (kbd "<f9> R") 'remember-region) |
| 215 | @end lisp |
| 216 | |
| 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. |
| 222 | |
| 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 |
| 227 | |
| 228 | You can write custom functions that use a different set of |
| 229 | remember-annotation-functions. For example: |
| 230 | |
| 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 |
| 238 | |
| 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}. |
| 248 | |
| 249 | |
| 250 | @node Function Reference |
| 251 | @chapter Function Reference |
| 252 | |
| 253 | @file{remember.el} defines the following interactive functions: |
| 254 | |
| 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 |
| 259 | |
| 260 | @defun remember-other-frame &optional initial |
| 261 | Like @code{remember}, but uses a new frame. |
| 262 | @end defun |
| 263 | |
| 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 |
| 270 | |
| 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 |
| 275 | |
| 276 | @defun remember-finalize |
| 277 | Remember the contents of the current buffer. |
| 278 | @end defun |
| 279 | |
| 280 | @defun remember-destroy |
| 281 | Destroy the current remember buffer. |
| 282 | @end defun |
| 283 | |
| 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 |
| 291 | |
| 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 |
| 300 | |
| 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 |
| 307 | |
| 308 | @defun remember-notes-save-and-bury-buffer |
| 309 | Save (if it is modified) and bury the current buffer. |
| 310 | @end defun |
| 311 | |
| 312 | @node Keystrokes |
| 313 | @chapter Keystroke Reference |
| 314 | |
| 315 | @file{remember.el} defines the following keybindings by default: |
| 316 | |
| 317 | @table @kbd |
| 318 | |
| 319 | @item C-c C-c |
| 320 | @itemx C-x C-s |
| 321 | Remember the contents of the current buffer (`remember-finalize'). |
| 322 | |
| 323 | @item C-c C-k |
| 324 | Destroy the current @file{*Remember*} buffer (`remember-destroy'). |
| 325 | |
| 326 | @end table |
| 327 | |
| 328 | @node Backends |
| 329 | @chapter Backends |
| 330 | |
| 331 | You can save remembered notes to a variety of backends. |
| 332 | |
| 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 |
| 340 | |
| 341 | @node Text File |
| 342 | @section Saving to a Text File |
| 343 | @cindex text file, saving to |
| 344 | |
| 345 | @subheading Insinuation |
| 346 | |
| 347 | @lisp |
| 348 | (setq remember-handler-functions '(remember-append-to-file)) |
| 349 | @end lisp |
| 350 | |
| 351 | @subheading Options |
| 352 | |
| 353 | @defopt remember-data-file |
| 354 | The file in which to store unprocessed data. |
| 355 | @end defopt |
| 356 | |
| 357 | @defopt remember-leader-text |
| 358 | The text used to begin each remember item. |
| 359 | @end defopt |
| 360 | |
| 361 | |
| 362 | @node Separate Text Files |
| 363 | @section Saving to Separate Text Files |
| 364 | @cindex text files, saving to separate |
| 365 | |
| 366 | @subheading Insinuation |
| 367 | |
| 368 | @lisp |
| 369 | (setq remember-handler-functions '(remember-store-in-files)) |
| 370 | @end lisp |
| 371 | |
| 372 | @subheading Options |
| 373 | |
| 374 | @defopt remember-data-directory |
| 375 | The directory in which to store remember data as files. |
| 376 | @end defopt |
| 377 | |
| 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 |
| 383 | |
| 384 | |
| 385 | @node Diary |
| 386 | @section Saving to a Diary file |
| 387 | @cindex diary, integration |
| 388 | |
| 389 | @subheading Insinuation |
| 390 | |
| 391 | @lisp |
| 392 | (add-to-list 'remember-handler-functions 'remember-diary-extract-entries) |
| 393 | @end lisp |
| 394 | |
| 395 | @subheading Options |
| 396 | |
| 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 |
| 401 | |
| 402 | @node Mailbox |
| 403 | @section Saving to a Mailbox |
| 404 | @cindex mailbox, saving to |
| 405 | |
| 406 | @subheading Insinuation |
| 407 | |
| 408 | @lisp |
| 409 | (add-to-list 'remember-handler-functions 'remember-store-in-mailbox) |
| 410 | @end lisp |
| 411 | |
| 412 | @subheading Options |
| 413 | |
| 414 | @defopt remember-mailbox |
| 415 | The file in which to store remember data as mail. |
| 416 | @end defopt |
| 417 | |
| 418 | @defopt remember-default-priority |
| 419 | The default priority for remembered mail messages. |
| 420 | @end defopt |
| 421 | |
| 422 | @node Org |
| 423 | @section Saving to an Org Mode file |
| 424 | @cindex org mode, integration |
| 425 | |
| 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}. |
| 435 | |
| 436 | @node GNU Free Documentation License |
| 437 | @appendix GNU Free Documentation License |
| 438 | @include doclicense.texi |
| 439 | |
| 440 | @node Concept Index |
| 441 | @unnumbered Index |
| 442 | |
| 443 | @printindex cp |
| 444 | |
| 445 | @bye |