[Emacs-diffs] trunk r116476: Some remember doc

[Glenn Morris]

------------------------------------------------------------
revno: 116476
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2014-02-19 00:34:45 -0800
message:
  Some remember doc
  
  * doc/misc/remember.texi: Copyedits.
  (Quick Start): No need for manual autoloads.  Mention remember-notes.
  (Function Reference): Update arguments.  Add new commands.
  
  * lisp/textmodes/remember.el: Set maintainer to emacs-devel
  according to remember.texi.
  Move provide statement to end.
  (remember-mode-map, remember-notes-mode-map, remember-notes-mode)
  (remember-notes): Doc fixes.
modified:
  doc/misc/ChangeLog             changelog-20091113204419-o5vbwnq5f7feedwu-6331
  doc/misc/remember.texi         
remember.texi-20091113204419-o5vbwnq5f7feedwu-7582
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/textmodes/remember.el     
remember.el-20091113204419-o5vbwnq5f7feedwu-7584

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2014-02-18 08:09:51 +0000
+++ b/doc/misc/ChangeLog        2014-02-19 08:34:45 +0000
@@ -1,3 +1,9 @@
+2014-02-19  Glenn Morris  <address@hidden>
+
+       * remember.texi: Copyedits.
+       (Quick Start): No need for manual autoloads.  Mention remember-notes.
+       (Function Reference): Update arguments.  Add new commands.
+
 2014-02-18  Glenn Morris  <address@hidden>
 
        * remember.texi (copying): Bump remember mode version.

=== modified file 'doc/misc/remember.texi'
--- a/doc/misc/remember.texi    2014-02-18 08:09:51 +0000
+++ b/doc/misc/remember.texi    2014-02-19 08:34:45 +0000
@@ -96,8 +96,8 @@
 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 address@hidden  How it's stored is really the
+``Remember so-and-so's phone number, or that I have to buy dinner for the
+cats tonight.''  That's the address@hidden  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.
@@ -175,7 +175,7 @@
 @itemize
 
 @item
-Type @kbd{M-x remember}.  The @samp{*Remember*} buffer should be
+Type @kbd{M-x remember}.  The @file{*Remember*} buffer should be
 displayed.
 
 @item
@@ -185,7 +185,7 @@
 
 @item
 Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close
-the @samp{*Remember*} buffer.
+the @file{*Remember*} buffer.
 @end itemize
 
 By default, @code{remember-finalize} saves the note in @file{~/emacs.d/notes}.
@@ -194,7 +194,7 @@
 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
+remember} displays a @file{*Remember*} buffer with the region as the
 initial contents.
 
 As a simple beginning, you can start by using the Text File backend,
@@ -203,26 +203,23 @@
 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})
+You can also store remembered data in other backends.  @xref{Backends}.
 
-Here is one way to map the remember functions in your @file{.emacs} to
+Here is one way to map the remember functions in your init file 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
 
 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.
+set @code{remember-run-all-annotation-functions-flag} to a
address@hidden value.
 
 @defopt remember-run-all-annotation-functions-flag
-Non-nil means use all annotations returned by
address@hidden means use all annotations returned by
 @code{remember-annotation-functions}.
 @end defopt
 
@@ -237,17 +234,32 @@
   (call-interactively 'remember)))
 @end lisp
 
address@hidden notes
+The @code{remember-notes} command creates a @dfn{notes} buffer that
+visits the file specified by the option @code{remember-data-file}.
+The option @code{remember-notes-buffer-name} specifies the name of the
+buffer.  The buffer uses @code{remember-notes-initial-major-mode} and
address@hidden minor mode.  Use @kbd{C-c C-c} to save
+and bury the buffer.  The command @code{save-some-buffers} saves this
+buffer without asking.  This function is a suitable setting for
address@hidden
+
+
 @node Function Reference
 @chapter Function Reference
 
 @file{remember.el} defines the following interactive functions:
 
address@hidden remember initial
address@hidden remember &optional initial
 Remember an arbitrary piece of data.  With a prefix, it will use the
 region as @var{initial}.
 @end defun
 
address@hidden remember-region beg end
address@hidden remember-other-frame &optional initial
+Like @code{remember}, but uses a new frame.
address@hidden defun
+
address@hidden remember-region &optional 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
@@ -263,13 +275,37 @@
 Remember the contents of the current buffer.
 @end defun
 
address@hidden remember-destroy
+Destroy the current remember buffer.
address@hidden defun
+
 @defun remember-mode
-This enters the major mode for output from @command{remember}.  This
+This enters the major mode for output from @code{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
 
address@hidden remember-notes &optional switch-to
+This returns the notes buffer, creating it if needed, and switches
+to it if called interactively (or if @var{switch-to} is address@hidden).
+The notes buffer visits @code{remember-data-file}, and
+is named @code{remember-notes-buffer-name}.  It uses
address@hidden and @code{remember-notes-mode}
+minor mode.
address@hidden defun
+
address@hidden remember-notes-mode &optional arg
+This is a minor mode for the notes buffer.  It sets
address@hidden so that @code{save-some-buffers} will
+save the notes buffer without asking.  Use @kbd{C-c C-c} to
+run the command @code{remember-notes-save-and-bury-buffer}.
address@hidden defun
+
address@hidden remember-notes-save-and-bury-buffer
+Save (if it is modified) and bury the current buffer.
address@hidden defun
+
 @node Keystrokes
 @chapter Keystroke Reference
 
@@ -277,14 +313,12 @@
 
 @table @kbd
 
address@hidden C-c C-c (`remember-finalize')
-Remember the contents of the current buffer.
-
address@hidden C-c C-k (`remember-destroy')
-Destroy the current *Remember* buffer.
-
address@hidden C-x C-s (`remember-finalize')
-Remember the contents of the current buffer.
address@hidden C-c C-c
address@hidden C-x C-s
+Remember the contents of the current buffer (`remember-finalize').
+
address@hidden C-c C-k
+Destroy the current @file{*Remember*} buffer (`remember-destroy').
 
 @end table
 
@@ -359,7 +393,7 @@
 
 @defopt remember-diary-file
 File for extracted diary entries.
-If this is nil, then @code{diary-file} will be used instead."
+If this is @code{nil}, then @code{diary-file} will be used instead.
 @end defopt
 
 @node Mailbox

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-02-18 08:09:51 +0000
+++ b/etc/NEWS  2014-02-19 08:34:45 +0000
@@ -713,13 +713,9 @@
 
 ** Remember
 
-*** The new command `remember-notes' creates a buffer that is saved on
-`kill-emacs'.  You can think of it as a *scratch* buffer whose content
-is preserved.  In fact, it was designed as a replacement for *scratch*
-buffer and can be used that way by setting `initial-buffer-choice' to
-`remember-notes' and `remember-notes-buffer-name' to "*scratch*".
-Without the second change, the *scratch* buffer will still be there
-for notes that do not need to be preserved.
++++
+*** The new command `remember-notes' creates a buffer that is saved on exit.
+You can use it as a more permanent *scratch* buffer.
 
 +++
 *** Remember can now store notes in separate files.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-02-18 18:14:36 +0000
+++ b/lisp/ChangeLog    2014-02-19 08:34:45 +0000
@@ -1,3 +1,9 @@
+2014-02-19  Glenn Morris  <address@hidden>
+
+       * textmodes/remember.el: Move provide statement to end.
+       (remember-mode-map, remember-notes-mode-map, remember-notes-mode)
+       (remember-notes): Doc fixes.
+
 2014-02-18  Stefan Monnier  <address@hidden>
 
        * delsel.el (delete-char): Restore incorrectly erased property

=== modified file 'lisp/textmodes/remember.el'
--- a/lisp/textmodes/remember.el        2014-02-18 08:09:51 +0000
+++ b/lisp/textmodes/remember.el        2014-02-19 08:34:45 +0000
@@ -3,6 +3,7 @@
 ;; Copyright (C) 1999-2001, 2003-2014 Free Software Foundation, Inc.
 
 ;; Author: John Wiegley <address@hidden>
+;; Maintainer: address@hidden
 ;; Created: 29 Mar 1999
 ;; Version: 2.0
 ;; Keywords: data memory todo pim
@@ -178,8 +179,6 @@
 
 ;;; Code:
 
-(provide 'remember)
-
 (defconst remember-version "2.0"
   "This version of remember.")
 
@@ -230,6 +229,8 @@
   :type 'boolean
   :group 'remember)
 
+;; See below for more user variables.
+
 ;;; Internal Variables:
 
 (defvar remember-buffer "*Remember*"
@@ -553,7 +554,7 @@
     (define-key map "\C-c\C-c" 'remember-finalize)
     (define-key map "\C-c\C-k" 'remember-destroy)
     map)
-  "Keymap used in Remember mode.")
+  "Keymap used in `remember-mode'.")
 
 (define-derived-mode remember-mode indented-text-mode "Remember"
   "Major mode for output from \\[remember].
@@ -599,10 +600,14 @@
   (let ((map (make-sparse-keymap)))
     (define-key map "\C-c\C-c" 'remember-notes-save-and-bury-buffer)
     map)
-  "Keymap used in remember-notes mode.")
+  "Keymap used in `remember-notes-mode'.")
 
 (define-minor-mode remember-notes-mode
-  "Minor mode for the `remember-notes' buffer."
+  "Minor mode for the `remember-notes' buffer.
+This sets `buffer-save-without-query' so that `save-some-buffers' will
+save the notes buffer without asking.
+
+\\{remember-notes-mode-map}"
   nil nil nil
   (cond
    (remember-notes-mode
@@ -612,29 +617,25 @@
 
 ;;;###autoload
 (defun remember-notes (&optional switch-to)
-  "Creates notes buffer and switches to it if called interactively.
-
-If a notes buffer created by a previous invocation of this
-function already exist, it will be returned.  Otherwise a new
-buffer will be created whose content will be read from file
-pointed by `remember-data-file'.  If a buffer visiting this file
-already exist, that buffer will be used instead of creating a new
-one (see `find-file-noselect' function for more details).
-
-Name of the created buffer is taken from `remember-notes-buffer-name'
-variable and if a buffer with that name already exist (but was not
-created by this function), it will be first killed.
-\\<remember-notes-mode-map>
-`remember-notes-mode' is active in the notes buffer which by default
-contains only one \\[save-and-bury-buffer] binding which saves and
-buries the buffer.
-
-Function returns notes buffer.  When called interactively,
-switches to it as well.
-
-Notes buffer is meant for keeping random notes which you'd like to
-preserve across Emacs restarts.  The notes will be stored in the
-`remember-data-file'."
+  "Return the notes buffer, creating it if needed, and maybe switch to it.
+This buffer is for notes that you want to preserve across Emacs sessions.
+The notes are saved in `remember-data-file'.
+
+If a buffer is already visiting that file, just return it.
+
+Otherwise, create the buffer, and rename it to `remember-notes-buffer-name',
+unless a buffer of that name already exists.  Set the major mode according
+to `remember-notes-initial-major-mode', and enable `remember-notes-mode'
+minor mode.
+
+Use \\<remember-notes-mode-map>\\[remember-notes-save-and-bury-buffer] to save 
and bury the notes buffer.
+
+Interactively, or if SWITCH-TO is non-nil, switch to the buffer.
+Return the buffer.
+
+Set `initial-buffer-choice' to `remember-notes' to visit your notes buffer
+when Emacs starts.  Set `remember-notes-buffer-name' to \"*scratch*\"
+to turn the *scratch* buffer into your notes buffer."
   (interactive "p")
   (let ((buf (or (find-buffer-visiting remember-data-file)
                  (with-current-buffer (find-file-noselect remember-data-file)
@@ -662,4 +663,6 @@
         nil)
     t))
 
+(provide 'remember)
+
 ;;; remember.el ends here