[Emacs-diffs] emacs/lisp ChangeLog mail/rmailout.el

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       09/02/16 01:18:43

Modified files:
        lisp           : ChangeLog 
        lisp/mail      : rmailout.el 

Log message:
        (rmail-delete-unwanted-fields)
        (rmail-output-as-babyl, rmail-output-to-babyl-buffer)
        (rmail-convert-to-babyl-format, rmail-nuke-pinhead-header)
        (rmail-output-as-mbox, rmail-output-to-rmail-buffer, rmail-output)
        (rmail-output-as-seen, rmail-output-body-to-file): Doc fixes.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/lisp/ChangeLog?cvsroot=emacs&r1=1.15336&r2=1.15337
http://cvs.savannah.gnu.org/viewcvs/emacs/lisp/mail/rmailout.el?cvsroot=emacs&r1=1.91&r2=1.92

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/lisp/ChangeLog,v
retrieving revision 1.15336
retrieving revision 1.15337
diff -u -b -r1.15336 -r1.15337
--- ChangeLog   15 Feb 2009 20:45:03 -0000      1.15336
+++ ChangeLog   16 Feb 2009 01:18:38 -0000      1.15337
@@ -1,3 +1,11 @@
+2009-02-16  Glenn Morris  <address@hidden>
+
+       * mail/rmailout.el (rmail-delete-unwanted-fields)
+       (rmail-output-as-babyl, rmail-output-to-babyl-buffer)
+       (rmail-convert-to-babyl-format, rmail-nuke-pinhead-header)
+       (rmail-output-as-mbox, rmail-output-to-rmail-buffer, rmail-output)
+       (rmail-output-as-seen, rmail-output-body-to-file): Doc fixes.
+
 2009-02-15  Glenn Morris  <address@hidden>
 
        * mail/rmailsum.el (rmail-summary-output-as-seen): Doc fix.

Index: mail/rmailout.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/mail/rmailout.el,v
retrieving revision 1.91
retrieving revision 1.92
diff -u -b -r1.91 -r1.92
--- mail/rmailout.el    15 Feb 2009 20:45:06 -0000      1.91
+++ mail/rmailout.el    16 Feb 2009 01:18:43 -0000      1.92
@@ -84,10 +84,10 @@
               (or read-file (file-name-nondirectory default-file))
               (file-name-directory default-file)))))))
 
-;; Delete from the buffer header fields we don't want output.
-;; Buffer should be pre-narrowed to the header.
-;; PRESERVE is a regexp for fields NEVER to delete.
 (defun rmail-delete-unwanted-fields (preserve)
+  "Delete all headers matching `rmail-fields-not-to-output'.
+Retains headers matching the regexp PRESERVE.  The buffer should be
+narrowed to just the header."
   (if rmail-fields-not-to-output
       (save-excursion
        (goto-char (point-min))
@@ -99,9 +99,13 @@
 
 (defun rmail-output-as-babyl (file-name nomsg)
   "Convert the current buffer's text to Babyl and output to FILE-NAME.
-It alters the current buffer's text, so it should be a temp buffer."
-  (let ((coding-system-for-write
-        'emacs-mule-unix))
+Alters the current buffer's text, so it should be a temporary buffer.
+If a buffer is visiting FILE-NAME, adds the text to that buffer
+rather than saving the file directly.  If the buffer is an Rmail buffer,
+updates it accordingly.  If no buffer is visiting FILE-NAME, appends
+the text directly to FILE-NAME, and displays a \"Wrote file\" message
+unless NOMSG is a symbol (neither nil nor t)."
+  (let ((coding-system-for-write 'emacs-mule-unix))
     (save-restriction
       (goto-char (point-min))
       (search-forward "\n\n" nil 'move)
@@ -134,11 +138,10 @@
 (declare-function rmail-update-summary "rmailsum" (&rest ignore))
 
 (defun rmail-output-to-babyl-buffer (tembuf msg)
-  "Copy msg in TEMBUF from BEG to END into this old R-mail BABYL buffer.
-Do what is necessary to make babyl R-mail know about the new message.
-Then display message number MSG."
-  ;; Turn on Auto Save mode, if it's off in this
-  ;; buffer but enabled by default.
+  "Copy message in TEMBUF into the current Babyl Rmail buffer.
+Do what is necessary to make Rmail know about the new message, then
+display message number MSG."
+  ;; Turn on Auto Save mode, if it's off in this buffer but enabled by default.
   (and (not buffer-auto-save-file-name)
        auto-save-default
        (auto-save-mode t))
@@ -152,11 +155,11 @@
   (narrow-to-region (point) (point-max))
   (rmail-count-new-messages t)
   (if (rmail-summary-exists)
-      (rmail-select-summary
-       (rmail-update-summary)))
+      (rmail-select-summary (rmail-update-summary)))
   (rmail-show-message-1 msg))
 
 (defun rmail-convert-to-babyl-format ()
+  "Convert the mbox message in the current buffer to Babyl format."
   (let ((count 0) (start (point-min))
        (case-fold-search nil)
        (buffer-undo-list t))
@@ -251,11 +254,11 @@
                (symbol-name last-coding-system-used)
                "\n")))))
 
-;; Delete the "From ..." line, creating various other headers with
-;; information from it if they don't already exist.  Now puts the
-;; original line into a mail-from: header line for debugging and for
-;; use by the rmail-output function.
 (defun rmail-nuke-pinhead-header ()
+  "Delete the \"From \" line in the current mbox message.
+The variable `rmail-unix-mail-delimiter' specifies the From line format.
+Replaces the From line with a \"Mail-from\" header.  Adds \"Date\" and
+\"From\" headers if they are not already present."
   (save-excursion
     (save-restriction
       (let ((start (point))
@@ -306,8 +309,12 @@
 
 (defun rmail-output-as-mbox (file-name nomsg &optional as-seen)
   "Convert the current buffer's text to mbox and output to FILE-NAME.
-It alters the current buffer's text, so call with a temp buffer current.
-If FILE-NAME is visited, output into its buffer instead.
+Alters the current buffer's text, so it should be a temporary buffer.
+If a buffer is visiting FILE-NAME, adds the text to that buffer
+rather than saving the file directly.  If the buffer is an Rmail buffer,
+updates it accordingly.  If no buffer is visiting FILE-NAME, appends
+the text directly to FILE-NAME, and displays a \"Wrote file\" message
+unless NOMSG is a symbol (neither nil nor t).
 AS-SEEN is non-nil if we are copying the message \"as seen\"."
   (let ((case-fold-search t)
        from date)
@@ -363,9 +370,9 @@
            (insert-buffer-substring tembuf)))))))
 
 (defun rmail-output-to-rmail-buffer (tembuf msg)
-  "Copy msg in TEMBUF from BEG to END into this Rmail buffer.
-Do what is necessary to make Rmail know about the new message.
-Then display message number MSG."
+  "Copy message in TEMBUF into the current Rmail buffer.
+Do what is necessary to make Rmail know about the new message. then
+display message number MSG."
   (save-excursion
     (rmail-swap-buffers-maybe)
     ;; Turn on Auto Save mode, if it's off in this
@@ -378,8 +385,7 @@
     (insert-buffer-substring tembuf)
     (rmail-count-new-messages t)
     (if (rmail-summary-exists)
-       (rmail-select-summary
-        (rmail-update-summary)))
+       (rmail-select-summary (rmail-update-summary)))
     (rmail-show-message-1 msg)))
 
 ;;; There are functions elsewhere in Emacs that use this function;
@@ -389,8 +395,11 @@
   "Append this message to mail file FILE-NAME.
 This works with both mbox format and Babyl format files,
 outputting in the appropriate format for each.
-The default file name comes from `rmail-default-file',
-which is updated to the name you use in this command.
+
+Interactively, the default file name comes from `rmail-default-file',
+which is updated to the name you use in this command.  In all uses, if
+FILE-NAME is not absolute, it is expanded with the directory part of
+`rmail-default-file'.
 
 A prefix argument COUNT says to output that many consecutive messages,
 starting with the current one.  Deleted messages are skipped and don't count.
@@ -402,7 +411,7 @@
 The optional third argument NOATTRIBUTE, if non-nil, says not
 to set the `filed' attribute, and not to display a message.
 
-The optional fourth argument FROM-GNUS is set when called from GNUS."
+The optional fourth argument FROM-GNUS is set when called from Gnus."
   (interactive
    (list (rmail-output-read-file-name)
         (prefix-numeric-value current-prefix-arg)))
@@ -481,7 +490,7 @@
 The optional third argument NOATTRIBUTE, if non-nil, says not
 to set the `filed' attribute, and not to display a message.
 
-The optional fourth argument FROM-GNUS is set when called from GNUS."
+The optional fourth argument FROM-GNUS is set when called from Gnus."
   (interactive
    (list (rmail-output-read-file-name)
         (prefix-numeric-value current-prefix-arg)))
@@ -552,7 +561,15 @@
 ;;;###autoload
 (defun rmail-output-body-to-file (file-name)
   "Write this message body to the file FILE-NAME.
-FILE-NAME defaults, interactively, from the Subject field of the message."
+Interactively, the default file name comes from either the message
+\"Subject\" header, or from `rmail-default-body-file'.  Updates the value
+of `rmail-default-body-file' accordingly.  In all uses, if FILE-NAME
+is not absolute, it is expanded with the directory part of
+`rmail-default-body-file'.
+
+Note that this overwrites FILE-NAME (after confirmation), rather
+than appending to it.  Deletes the message after writing if
+`rmail-delete-after-output' is non-nil."
   (interactive
    (let ((default-file
           (or (mail-fetch-field "Subject")