[Emacs-diffs] trunk r116471: Some remember doc

[Glenn Morris]

------------------------------------------------------------
revno: 116471
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Tue 2014-02-18 00:09:51 -0800
message:
  Some remember doc
  
  * doc/misc/remember.texi (copying): Bump remember mode version.
  (Installation): Remove unnecessary chapter.
  (Quick Start): No need to explicitly load remember.el.
  (Separate Text Files): New section.
  
  * lisp/textmodes/remember.el (remember-data-directory)
  (remember-directory-file-name-format, remember-store-in-files)
  (remember-notes-initial-major-mode, remember-notes-bury-on-kill)
  (remember-notes-save-and-bury-buffer)
  (remember-notes--kill-buffer-query): Doc fixes.
  
  * etc/NEWS: Related edit.
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-17 18:40:09 +0000
+++ b/doc/misc/ChangeLog        2014-02-18 08:09:51 +0000
@@ -1,3 +1,10 @@
+2014-02-18  Glenn Morris  <address@hidden>
+
+       * remember.texi (copying): Bump remember mode version.
+       (Installation): Remove unnecessary chapter.
+       (Quick Start): No need to explicitly load remember.el.
+       (Separate Text Files): New section.
+
 2014-02-17  Glenn Morris  <address@hidden>
 
        * eieio.texi (Class Values, CLOS compatibility):

=== modified file 'doc/misc/remember.texi'
--- a/doc/misc/remember.texi    2014-01-27 02:02:28 +0000
+++ b/doc/misc/remember.texi    2014-02-18 08:09:51 +0000
@@ -7,7 +7,7 @@
 @c %**end of header
 
 @copying
-This manual is for Remember Mode, version 1.9
+This manual is for Remember Mode, version 2.0
 
 Copyright @copyright{} 2001, 2004--2005, 2007--2014
 Free Software Foundation, Inc.
@@ -54,7 +54,6 @@
 @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.
 * Function Reference::          Interactive functions in remember.el.
@@ -69,6 +68,7 @@
 Backends
 
 * Text File::                   Saving to a text file.
+* Separate Text Files::         Saving to separate text files.
 * Diary::                       Saving to a Diary file.
 * Mailbox::                     Saving to a mailbox.
 * Org::                         Saving to an Org Mode file.
@@ -128,18 +128,6 @@
 manual-ness which computers from the very beginning have been championed
 as being able to reduce.
 
address@hidden Installation
address@hidden Installation
-
-Installing Remember Mode is as simple as adding the following lines to
-your Emacs configuration file (usually @file{~/.emacs.d/init.el} or
address@hidden/.emacs}).
-
address@hidden
-(add-to-list 'load-path "/path/to/remember")
-(require 'remember)
address@hidden lisp
-
 @node Implementation
 @chapter Implementation
 
@@ -187,14 +175,11 @@
 @itemize
 
 @item
-Load @file{remember.el}.
-
address@hidden
-Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be
+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
+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.
 
@@ -204,18 +189,18 @@
 @end itemize
 
 By default, @code{remember-finalize} saves the note in @file{~/emacs.d/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
+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
+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{~/.emacs.d/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
+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.
@@ -233,7 +218,7 @@
 @end lisp
 
 By default, remember uses the first annotation returned by
address@hidden To include all of the annotations,
address@hidden  To include all of the annotations,
 set @code{remember-run-all-annotation-functions-flag} to non-nil.
 
 @defopt remember-run-all-annotation-functions-flag
@@ -242,7 +227,7 @@
 @end defopt
 
 You can write custom functions that use a different set of
-remember-annotation-functions. For example:
+remember-annotation-functions.  For example:
 
 @lisp
 (defun my/remember-with-filename ()
@@ -258,7 +243,7 @@
 @file{remember.el} defines the following interactive functions:
 
 @defun remember initial
-Remember an arbitrary piece of data. With a prefix, it will use the
+Remember an arbitrary piece of data.  With a prefix, it will use the
 region as @var{initial}.
 @end defun
 
@@ -310,6 +295,7 @@
 
 @menu
 * Text File::                   Saving to a text file.
+* Separate Text Files::         Saving to separate text files.
 * Diary::                       Saving to a Diary file.
 * Mailbox::                     Saving to a mailbox.
 * Org::                         Saving to an Org Mode file.
@@ -335,6 +321,30 @@
 The text used to begin each remember item.
 @end defopt
 
+
address@hidden Separate Text Files
address@hidden Saving to Separate Text Files
address@hidden text files, saving to separate
+
address@hidden Insinuation
+
address@hidden
+(setq remember-handler-functions '(remember-store-in-files))
address@hidden lisp
+
address@hidden Options
+
address@hidden remember-data-directory
+The directory in which to store remember data as files.
address@hidden defopt
+
address@hidden remember-directory-file-name-format
+A format string to use for naming files in the remember directory.
+File names are formed by calling @code{format-time-string} at the time
+of saving, using this format string.
address@hidden defopt
+
+
 @node Diary
 @section Saving to a Diary file
 @cindex diary, integration

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-02-18 01:33:30 +0000
+++ b/etc/NEWS  2014-02-18 08:09:51 +0000
@@ -28,6 +28,7 @@
 This happens by default if a suitable support library is found at
 build time, like libacl on GNU/Linux.  To prevent this, use the
 configure option `--disable-acl'.
+FIXME?  Should be --without-acl?
 
 ** Emacs can now be compiled with file notification support.
 This happens by default if a suitable system library is found at
@@ -720,11 +721,11 @@
 Without the second change, the *scratch* buffer will still be there
 for notes that do not need to be preserved.
 
-*** The Remember package can now store notes in separates files.
-You can use the new function `remember-store-in-files' within the
-`remember-handler-functions' option.  See `remember-data-directory'
-and `remember-directory-file-name-format' for new options related to
-this function.
++++
+*** Remember can now store notes in separate files.
+To use this, add `remember-store-in-files' to the `remember-handler-functions'
+option.  The files are saved in `remember-data-directory' using
+names specified by `remember-directory-file-name-format'.
 
 ** Rmail
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-02-18 01:33:30 +0000
+++ b/lisp/ChangeLog    2014-02-18 08:09:51 +0000
@@ -1,5 +1,11 @@
 2014-02-18  Glenn Morris  <address@hidden>
 
+       * textmodes/remember.el (remember-data-directory)
+       (remember-directory-file-name-format, remember-store-in-files)
+       (remember-notes-initial-major-mode, remember-notes-bury-on-kill)
+       (remember-notes-save-and-bury-buffer)
+       (remember-notes--kill-buffer-query): Doc fixes.
+
        * desktop.el (desktop-save-mode, desktop-auto-save-timeout): Doc fixes.
 
 2014-02-17  Alan Mackenzie  <address@hidden>

=== modified file 'lisp/textmodes/remember.el'
--- a/lisp/textmodes/remember.el        2014-02-14 06:55:59 +0000
+++ b/lisp/textmodes/remember.el        2014-02-18 08:09:51 +0000
@@ -442,21 +442,24 @@
       (remember-destroy))))
 
 (defcustom remember-data-directory "~/remember"
-  "The directory in which to store remember data as files."
+  "The directory in which to store remember data as files.
+Used by `remember-store-in-files'."
   :type 'directory
   :version "24.4"
   :group 'remember)
 
 (defcustom remember-directory-file-name-format "%Y-%m-%d_%T-%z"
-  "Format string for the file name in which to store unprocessed data."
+  "Format string for the file name in which to store unprocessed data.
+This is passed to `format-time-string'.
+Used by `remember-store-in-files'."
   :type 'string
   :version "24.4"
   :group 'remember)
 
 (defun remember-store-in-files ()
   "Store remember data in a file in `remember-data-directory'.
-The file is named after `remember-directory-file-name-format' fed through
-`format-time-string'."
+The file is named by calling `format-time-string' using
+`remember-directory-file-name-format' as the format string."
   (let ((name (format-time-string
               remember-directory-file-name-format (current-time)))
         (text (buffer-string)))
@@ -572,20 +575,19 @@
   :version "24.4")
 
 (defcustom remember-notes-initial-major-mode nil
-  "Major mode to set to notes buffer when it's created.
-If set to nil will use the same mode as `initial-major-mode'."
-  :type '(choice (const    :tag "Same as `initial-major-mode'" nil)
+  "Major mode to use in the notes buffer when it's created.
+If this is nil, use `initial-major-mode'."
+  :type '(choice (const    :tag "Use `initial-major-mode'" nil)
                 (function :tag "Major mode" text-mode))
   :version "24.4")
 
 (defcustom remember-notes-bury-on-kill t
-  "Whether to bury notes buffer instead of killing."
+  "Non-nil means `kill-buffer' will bury the notes buffer instead of killing."
   :type 'boolean
   :version "24.4")
 
 (defun remember-notes-save-and-bury-buffer ()
-  "Saves and buries current buffer.
-Buffer is saved only if `buffer-modified-p' returns non-nil."
+  "Save (if it is modified) and bury the current buffer."
   (interactive)
   (when (buffer-modified-p)
     (save-buffer))
@@ -648,10 +650,16 @@
     buf))
 
 (defun remember-notes--kill-buffer-query ()
+  "Function that `remember-notes-mode' adds to `kill-buffer-query-functions'.
+Save the current buffer if modified.  If `remember-notes-bury-on-kill'
+is non-nil, bury it and return nil; otherwise return t."
   (when (buffer-modified-p)
     (save-buffer))
   (if remember-notes-bury-on-kill
-      (bury-buffer)
+      (progn
+        ;; bury-buffer always returns nil, but let's be explicit.
+        (bury-buffer)
+        nil)
     t))
 
 ;;; remember.el ends here