branch: elpa/vm
commit edecae201ca7261e0d5adedded25cea0bbaea432
Merge: b18f8ce5f9 562b451b61
Author: Mark Diekhans <[email protected]>
Commit: Mark Diekhans <[email protected]>
Merge branch '539-vm-ps-print-documentation' into 'main'
Improve documentation of vm-ps-print
See merge request emacs-vm/vm!69
---
lisp/vm-ps-print.el | 77 +++++++++++++++++++++++++----------------------------
1 file changed, 36 insertions(+), 41 deletions(-)
diff --git a/lisp/vm-ps-print.el b/lisp/vm-ps-print.el
index 09fd7095d3..7b85df6bc4 100644
--- a/lisp/vm-ps-print.el
+++ b/lisp/vm-ps-print.el
@@ -3,12 +3,10 @@
;; This file is part of VM
;;
;; Copyright (C) 1999 Robert Fenk
-;; Copyright (C) 2024-2025 The VM Developers
+;; Copyright (C) 2024-2026 The VM Developers
;;
-;; Author: Robert Fenk
-;; Status: Tested with XEmacs 21.4.15 & VM 7.18
-;; Keywords: extensions, vm, ps-print
-;; X-URL: http://www.robf.de/Hacking/elisp
+;; Original author: Robert Fenk
+;; X-URL: http://www.robf.de/Hacking/elisp
;;
;; This code is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
@@ -21,28 +19,22 @@
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
-;; along with this program; if not, write to the Free Software
-;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
-;; 02110-1301, USA.
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;;
-;; There are three new user functions for generating postscript output:
+;; There are four user functions for generating postscript output:
;; vm-ps-print-message
;; vm-ps-print-each-message
-;; vm-ps-print-message-preview
+;; vm-ps-print-message-presentation
+;; vm-ps-print-marked
;; The first one prints like vm-ps-print, but multiple messages are
;; concatenated to one printout. In contrast to this the second
-;; function creates one print job for each message. Finally the the
+;; function creates one print job for each message. The the
;; third one prints the current message as displayed in the
;; presentation buffer -- the other two functions do their own MIME
;; decoding therefore messages are always display in their default
-;; appearance.
-;;
-;; To use these functions you should put this file into your load-path
-;; and add the following lines to your .vm file:
-;;
-;; (require 'vm-ps-print)
+;; appearance. The fourth prints all marked messages.
;;
;; To redefine the default VM settings for the tool bar and menu add
;; the following line. The default is to use `vm-ps-print-message',
@@ -71,28 +63,25 @@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; group already defined in vm-vars.el
;; (defgroup vm nil
-;; "VM"
+;; "The VM mail reader."
;; :group 'mail)
-;; (defgroup vm-psprint nil
-;; "The VM ps-print lib"
+;; (defgroup vm-print nil
+;; "Options affecting printing of messages in VM."
;; :group 'vm)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;###autoload
(defcustom vm-ps-print-message-function 'ps-print-buffer-with-faces
"This should point to the function which is used for ps-printing.
The function should accept one optional argument which is a filename."
:group 'vm-print
:type 'function)
-;;;###autoload
(defcustom vm-ps-print-message-separater "\n"
"The separator between messages when printing multiple messages."
:group 'vm-print
:type 'string)
-;;;###autoload
(defcustom vm-ps-print-message-font-size 10
"The font size for the PS-output of the message text."
:group 'vm-print
@@ -100,29 +89,35 @@ The function should accept one optional argument which is
a filename."
;;----------------------------------------------------------------------------
-;;;###autoload
(defcustom vm-ps-print-message-header-lines 2
"See `ps-header-lines'."
:group 'vm-print
:type 'integer)
-;;;###autoload
(defcustom vm-ps-print-message-left-header
'(list (format "(Folder `%s')" folder-name)
(format "(%d message%s printed)" mcount (if (= mcount 1) "" "s")))
- "This variable should contain a command returning a valid `ps-left-header'."
+ ;; This documentation should match the definition of `env' in the
+ ;; function `vm-ps-print-message-internal' below.
+ "This variable should contain an ELisp expression returning a
+valid `ps-left-header'.
+The following variables are available when evaluating the value:
+ `dd-mon-yyyy' The current date
+ `folder-name' The name of the folder
+ `mcount' The number of messages to print
+ `msg' A pointer to a VM message"
:group 'vm-print
:type 'sexp)
-;;;###autoload
(defcustom vm-ps-print-message-right-header
- '(list"/pagenumberstring load" 'dd-mon-yyyy)
- "This variable should contain a command returning a valid `ps-right-header'.
-The defaults to the number of pages and the date of the printout."
+ '(list "/pagenumberstring load" 'dd-mon-yyyy)
+ "This variable should contain an ELisp expression returning a
+valid `ps-right-header'.
+The default is the number of pages and the date of the printout.
+See `vm-ps-print-message-left-header' for a list of variables it can use."
:group 'vm-print
:type 'sexp)
-;;;###autoload
(defcustom vm-ps-print-message-summary-format
(concat
"******************************************************************************\n"
(if (boundp 'vm-summary-format)
@@ -135,31 +130,31 @@ See `vm-summary-format' for a description of the
conversion specifiers."
:type 'string)
;;----------------------------------------------------------------------------
-;;;###autoload
(defcustom vm-ps-print-each-message-header-lines 2
"See `ps-header-lines'."
:group 'vm-print
:type 'integer)
-;;;###autoload
(defcustom vm-ps-print-each-message-left-header
'(list (format "(Folder `%s')" folder-name)
(format "(%s)" (vm-ps-print-tokenized-summary msg (vm-summary-sprintf
vm-ps-print-each-message-summary-format msg t))))
- "This command should return a valid `ps-left-header'.
+ "This variable should contain an ELisp expression returning a
+valid `ps-left-header'.
The default is to have the folder name and a summary according to the
-variable `vm-ps-print-each-message-summary-format' in the left header."
+variable `vm-ps-print-each-message-summary-format' in the left header.
+See `vm-ps-print-message-left-header' for a list of variables it can use."
:group 'vm-print
:type 'sexp)
-;;;###autoload
(defcustom vm-ps-print-each-message-right-header
'(list "/pagenumberstring load" 'dd-mon-yyyy)
- "This variable should contain a command returning a valid `ps-right-header'.
-The defaults to the number of pages and the date of the printout."
+ "This variable should contain an Elisp expression returning a
+valid `ps-right-header'.
+The default is the number of pages and the date of the printout.
+See `vm-ps-print-message-left-header' for a list of variables it can use."
:group 'vm-print
:type 'sexp)
-;;;###autoload
(defcustom vm-ps-print-each-message-summary-format
"Message# %n, Lines %l, Characters %c"
"The summary line for the postscript header.
@@ -181,6 +176,8 @@ MSG is a VM message pointer.
See: `vm-ps-print-message-function'"
(let* ((dd-mon-yyyy (format-time-string "%d %b %Y %T" (current-time)))
+ ;; This definition should match the documentation of
+ ;; `vm-ps-print-message-header-env' above.
(env `((dd-mon-yyyy . ,dd-mon-yyyy)
(folder-name . ,folder-name)
(mcount . ,mcount)
@@ -335,7 +332,6 @@ summary lines between messages.
See: `vm-ps-print-message-function'
`vm-ps-print-message-font-size'
- `vm-ps-print-each-message-separater'
`vm-ps-print-each-message-left-header'
`vm-ps-print-each-message-right-header'
`vm-ps-print-each-message-summary-format'
@@ -358,7 +354,6 @@ number, prompt the user for the name of the file to save in.
See: `vm-ps-print-message-function'
`vm-ps-print-message-font-size'
- `vm-ps-print-each-message-separater'
`vm-ps-print-each-message-left-header'
`vm-ps-print-each-message-right-header'
`vm-ps-print-each-message-summary-format'
