comparison lisp/ps-print.el @ 47328:ac7145660745

Many doc fixes.

47327:94b3c6a53104

Vinicius's last change version -- this file may have been edited as part of
Emacs without changes to the version number.  When reporting bugs, please also
report the version of Emacs, if any, that ps-print was distributed with.

Please send all bug fixes and enhancements to
	Vinicius Jose Latorre <[e-mail]>.
")

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify it under
;; the terms of the GNU General Public License as published by the Free

As an example for `ps-user-defined-prologue' setting:

   ;; Setting for HP PostScript printer
   (setq ps-user-defined-prologue
	 (concat \"<</DeferredMediaSelection true /PageSize [612 792] \"
		 \"/MediaPosition 2 /MediaType (Plain)>> setpagedevice\"))
"
  :type '(choice :menu-tag "User Defined Prologue"
		 :tag "User Defined Prologue"
		 (const :tag "none" nil) string symbol)
  :group 'ps-print-miscellany)

ps-print always inserts the %%Requirements: comment, so if you need to insert
more requirements put them first in `ps-print-prologue-header' using the
\"%%+\" comment.  For example, if you need to set numcopies to 3 and jog on
requirements and set %%LanguageLevel: to 2, do:

(setq ps-print-prologue-header
      \"%%+ numcopies(3) jog\\n%%LanguageLevel: 2\\n\")

The duplex requirement is inserted by ps-print (see `ps-spool-duplex').

Do not forget to terminate the string with \"\\n\".

	 "-d")
	(t
	 "-P" ))
  "*Option for `ps-printer-name' variable (see it).

On Unix-like systems, if it's been used lpr utility, it should be the string
\"-P\"; if it's been used lp utility, it should be the string \"-d\".

On MS-DOS and MS-Windows systems, if it's been used print utility, it should be
the string \"/D:\".

For any other printing utility, see the proper manual or documentation.

Set to \"\" or nil, if the utility given by `ps-lpr-command' needs an empty
option printer name option.

Any other value is treated as nil, that is, an empty printer name option.

This variable is used only when `ps-printer-name' is a non-empty string."
  :type '(choice :menu-tag "Printer Name Option"

  "*Non-nil means print in landscape mode."
  :type 'boolean
  :group 'ps-print-page)

(defcustom ps-print-upside-down nil
  "*Non-nil means print upside-down (that is, it's rotated by 180 grades)."
  :type 'boolean
  :version "21.1"
  :group 'ps-print-page)

(defcustom ps-selected-pages nil
  "*Specify which pages to print.

If it's nil, all pages are printed.

If it's a list, the list element may be an integer or a cons cell (FROM . TO)
designating FROM page to TO page; any invalid element is ignored, that is, an
integer lesser than one or if FROM is greater than TO.

Otherwise, it's treated as nil.

After ps-print processing `ps-selected-pages' is set to nil.  But the latest
`ps-selected-pages' is saved in `ps-last-selected-pages' (see it for
documentation).  So you can restore the latest selected pages by using
`ps-last-selected-pages' or by calling `ps-restore-selected-pages' command (see
it for documentation).

See also `ps-even-or-odd-pages'."
  :type '(repeat :tag "Selected Pages"
		 (radio :tag "Page"
			(integer :tag "Number")

		 (const top-left)  (const bottom-left)
		 (const top-right) (const bottom-right))
  :group 'ps-print-n-up)

(defcustom ps-number-of-columns (if ps-landscape-mode 2 1)
  "*Specify the number of columns"
  :type 'number
  :group 'ps-print-miscellany)

(defcustom ps-zebra-stripes nil
  "*Non-nil means print zebra stripes.

PAGES may be a number or a cons cell (FROM . TO) designating FROM page to TO
page.
If PAGES is nil, print background image on all pages.

X, Y, XSCALE, YSCALE and ROTATION may be a floating point number, an integer
number or a string. If it is a string, the string should contain PostScript
programming that returns a float or integer value.

For example, if you wish to print an EPS image on all pages do:

   '((\"~/images/EPS-image.ps\"))"

PAGES may be a number or a cons cell (FROM . TO) designating FROM page to TO
page.
If PAGES is nil, print background text on all pages.

X, Y, FONTSIZE, GRAY and ROTATION may be a floating point number, an integer
number or a string. If it is a string, the string should contain PostScript
programming that returns a float or integer value.

For example, if you wish to print text \"Preliminary\" on all pages do:

   '((\"Preliminary\"))"

  "*Vertical space in points (1/72 inch) between the main text and the header."
  :type 'number
  :group 'ps-print-vertical)

(defcustom ps-header-line-pad 0.15
  "*Portion of a header title line height to insert between the header frame
and the text it contains, both in the vertical and horizontal directions."
  :type 'number
  :group 'ps-print-vertical)

(defcustom ps-footer-offset (/ (* 72  1.0) 2.54) ; 1.0 cm
  "*Vertical space in points (1/72 inch) between the main text and the footer."
  :type 'number
  :group 'ps-print-vertical)

(defcustom ps-footer-line-pad 0.15
  "*Portion of a footer title line height to insert between the footer frame
and the text it contains, both in the vertical and horizontal directions."
  :type 'number
  :group 'ps-print-vertical)

;;; Header/Footer setup

	 affects the left margin.
	 Besides all that, if your printer does not have the paper size
	 specified by setpagedevice, your printing will be aborted.
	 So, if you need to use setpagedevice, set `ps-spool-config' to
	 `setpagedevice', generate a test file and send it to your printer; if
	 the printed file isn't ok, set `ps-spool-config' to nil."
  :type '(choice :menu-tag "Spool Config"
		 :tag "Spool Config"
		 (const lpr-switches) (const setpagedevice)
		 (const :tag "nil" nil))
  :group 'ps-print-headers)

     (size . 10.0)
     (line-height . 11.45)
     (space-width . 2.2)
     (avg-char-width . 4.10811))
    )
  "*Font info database: font family (the key), name, bold, italic, bold-italic,
reference size, line height, space width, average character width.
To get the info for another specific font (say Helvetica), do the following:
- create a new buffer
- generate the PostScript image to a file (C-u M-x ps-print-buffer)
- open this file and delete the leading `%' (which is the PostScript comment

   `ps-time-stamp-hh:mm:ss'		Return time as \"17:28:31\".

   `ps-time-stamp-mon-dd-yyyy'		Return date as \"Jun 18 2001\".

You can also create your own time stamp function by using `format-time-string'
(which see)."
  :type '(repeat (choice :menu-tag "Right Header"
			 :tag "Right Header"
			 string symbol))
  :group 'ps-print-headers)

   `ps-time-stamp-hh:mm:ss'		Return time as \"17:28:31\".

   `ps-time-stamp-mon-dd-yyyy'		Return date as \"Jun 18 2001\".

You can also create your own time stamp function by using `format-time-string'
(which see)."
  :version "21.1"
  :type '(repeat (choice :menu-tag "Right Footer"
			 :tag "Right Footer"
			 string symbol))
  :group 'ps-print-headers)

;;;###autoload
(defun ps-print-buffer (&optional filename)
  "Generate and print a PostScript image of the buffer.

Interactively, when you use a prefix argument (C-u), the command prompts the
user for a file name, and saves the PostScript image in that file instead of
sending it to the printer.

Noninteractively, the argument FILENAME is treated as follows: if it is nil,
send the image to the printer.  If FILENAME is a string, save the PostScript

;;;###autoload
(defun ps-despool (&optional filename)
  "Send the spooled PostScript to the printer.

Interactively, when you use a prefix argument (C-u), the command prompts the
user for a file name, and saves the spooled PostScript image in that file
instead of sending it to the printer.

Noninteractively, the argument FILENAME is treated as follows: if it is nil,
send the image to the printer.  If FILENAME is a string, save the PostScript

  (interactive (list (ps-print-preprint current-prefix-arg)))
  (ps-do-despool filename))

;;;###autoload
(defun ps-line-lengths ()
  "Display the correspondence between a line length and a font size, using the
current ps-print setup.
Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | head"
  (interactive)
  (ps-line-lengths-internal))

;;;###autoload

  (or (face-underline-p face)
      (memq face ps-underlined-faces)))


(defun ps-prologue-file (filenumber)
  "If prologue FILENUMBER exists and is readable, returns contents as string.

Note: No major/minor-mode is activated and no local variables are evaluated for
      FILENUMBER, but proper EOL-conversion and character interpretation is
      done!"
  (let ((filename (convert-standard-filename

(defvar ps-black-white-faces-alist nil
  "Alist of symbolic faces used for black/white PostScript printers.
An element of this list has the same form as `ps-print-face-extension-alist'
(which see).

Don't change this list directly; instead,
use `ps-extend-face' and `ps-extend-face-list'.
See documentation for `ps-extend-face' for valid extension symbol.
See also documentation for `ps-print-color-p'.")

x-dimension, of the text it has printed, and thus affects the point at
which long lines wrap around."
  (get font-sym 'avg-char-width))

(defun ps-line-lengths-internal ()
  "Display the correspondence between a line length and a font size,
using the current ps-print setup.
Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | head"
  (let* ((ps-font-size-internal
	  (or ps-font-size-internal
	      (ps-get-font-size 'ps-font-size)))
	 (ps-header-font-size-internal

47328:ac7145660745

Vinicius's last change version -- this file may have been edited as part of
Emacs without changes to the version number.  When reporting bugs, please also
report the version of Emacs, if any, that ps-print was distributed with.

Please send all bug fixes and enhancements to
	Vinicius Jose Latorre <[e-mail]>.")

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify it under
;; the terms of the GNU General Public License as published by the Free

As an example for `ps-user-defined-prologue' setting:

   ;; Setting for HP PostScript printer
   (setq ps-user-defined-prologue
	 (concat \"<</DeferredMediaSelection true /PageSize [612 792] \"
		 \"/MediaPosition 2 /MediaType (Plain)>> setpagedevice\"))"
  :type '(choice :menu-tag "User Defined Prologue"
		 :tag "User Defined Prologue"
		 (const :tag "none" nil) string symbol)
  :group 'ps-print-miscellany)

ps-print always inserts the %%Requirements: comment, so if you need to insert
more requirements put them first in `ps-print-prologue-header' using the
\"%%+\" comment.  For example, if you need to set numcopies to 3 and jog on
requirements and set %%LanguageLevel: to 2, do:

 (setq ps-print-prologue-header
      \"%%+ numcopies(3) jog\\n%%LanguageLevel: 2\\n\")

The duplex requirement is inserted by ps-print (see `ps-spool-duplex').

Do not forget to terminate the string with \"\\n\".

	 "-d")
	(t
	 "-P" ))
  "*Option for `ps-printer-name' variable (see it).

On Unix-like systems, if `lpr' is in use, this should be the string
\"-P\"; if `lp' is in use, this should be the string \"-d\".

On MS-DOS and MS-Windows systems, if `print' is in use, this should be
the string \"/D:\".

For any other printing utility, see its documentation.

Set this to \"\" or nil, if the utility given by `ps-lpr-command' needs an empty
printer name option.

Any other value is treated as nil, that is, an empty printer name option.

This variable is used only when `ps-printer-name' is a non-empty string."
  :type '(choice :menu-tag "Printer Name Option"

  "*Non-nil means print in landscape mode."
  :type 'boolean
  :group 'ps-print-page)

(defcustom ps-print-upside-down nil
  "*Non-nil means print upside-down (that is, rotated by 180 degrees)."
  :type 'boolean
  :version "21.1"
  :group 'ps-print-page)

(defcustom ps-selected-pages nil
  "*Specify which pages to print.

If nil, print all pages.

If a list, the lists element may be an integer or a cons cell (FROM . TO)
designating FROM page to TO page; any invalid element is ignored, that is, an
integer less than one or if FROM is greater than TO.

Otherwise, it's treated as nil.

After ps-print processing `ps-selected-pages' is set to nil.  But the
latest `ps-selected-pages' is saved in `ps-last-selected-pages' (which
see).  So you can restore the latest selected pages by using
`ps-last-selected-pages' or with the `ps-restore-selected-pages'
command (which see).

See also `ps-even-or-odd-pages'."
  :type '(repeat :tag "Selected Pages"
		 (radio :tag "Page"
			(integer :tag "Number")

		 (const top-left)  (const bottom-left)
		 (const top-right) (const bottom-right))
  :group 'ps-print-n-up)

(defcustom ps-number-of-columns (if ps-landscape-mode 2 1)
  "*Specify the number of columns."
  :type 'number
  :group 'ps-print-miscellany)

(defcustom ps-zebra-stripes nil
  "*Non-nil means print zebra stripes.

PAGES may be a number or a cons cell (FROM . TO) designating FROM page to TO
page.
If PAGES is nil, print background image on all pages.

X, Y, XSCALE, YSCALE and ROTATION may be a floating point number, an integer
number or a string.  If it is a string, the string should contain PostScript
programming that returns a float or integer value.

For example, if you wish to print an EPS image on all pages do:

   '((\"~/images/EPS-image.ps\"))"

PAGES may be a number or a cons cell (FROM . TO) designating FROM page to TO
page.
If PAGES is nil, print background text on all pages.

X, Y, FONTSIZE, GRAY and ROTATION may be a floating point number, an integer
number or a string.  If it is a string, the string should contain PostScript
programming that returns a float or integer value.

For example, if you wish to print text \"Preliminary\" on all pages do:

   '((\"Preliminary\"))"

  "*Vertical space in points (1/72 inch) between the main text and the header."
  :type 'number
  :group 'ps-print-vertical)

(defcustom ps-header-line-pad 0.15
  "*Portion of a header title line height to insert.
The insertion is done between the header frame and the text it contains,
both in the vertical and horizontal directions."
  :type 'number
  :group 'ps-print-vertical)

(defcustom ps-footer-offset (/ (* 72  1.0) 2.54) ; 1.0 cm
  "*Vertical space in points (1/72 inch) between the main text and the footer."
  :type 'number
  :group 'ps-print-vertical)

(defcustom ps-footer-line-pad 0.15
  "*Portion of a footer title line height to insert.
The insertion is done between the footer frame and the text it contains,
both in the vertical and horizontal directions."
  :type 'number
  :group 'ps-print-vertical)

;;; Header/Footer setup

	 affects the left margin.
	 Besides all that, if your printer does not have the paper size
	 specified by setpagedevice, your printing will be aborted.
	 So, if you need to use setpagedevice, set `ps-spool-config' to
	 `setpagedevice', generate a test file and send it to your printer; if
	 the printed file isn't OK, set `ps-spool-config' to nil."
  :type '(choice :menu-tag "Spool Config"
		 :tag "Spool Config"
		 (const lpr-switches) (const setpagedevice)
		 (const :tag "nil" nil))
  :group 'ps-print-headers)

     (size . 10.0)
     (line-height . 11.45)
     (space-width . 2.2)
     (avg-char-width . 4.10811))
    )
  "*Font info database.
Each element comprises: font family (the key), name, bold, italic, bold-italic,
reference size, line height, space width, average character width.
To get the info for another specific font (say Helvetica), do the following:
- create a new buffer
- generate the PostScript image to a file (C-u M-x ps-print-buffer)
- open this file and delete the leading `%' (which is the PostScript comment

   `ps-time-stamp-hh:mm:ss'		Return time as \"17:28:31\".

   `ps-time-stamp-mon-dd-yyyy'		Return date as \"Jun 18 2001\".

You can also create your own time stamp function by using `format-time-string'
\(which see)."
  :type '(repeat (choice :menu-tag "Right Header"
			 :tag "Right Header"
			 string symbol))
  :group 'ps-print-headers)

   `ps-time-stamp-hh:mm:ss'		Return time as \"17:28:31\".

   `ps-time-stamp-mon-dd-yyyy'		Return date as \"Jun 18 2001\".

You can also create your own time stamp function by using `format-time-string'
\(which see)."
  :version "21.1"
  :type '(repeat (choice :menu-tag "Right Footer"
			 :tag "Right Footer"
			 string symbol))
  :group 'ps-print-headers)

;;;###autoload
(defun ps-print-buffer (&optional filename)
  "Generate and print a PostScript image of the buffer.

Interactively, when you use a prefix argument (\\[universal-argument]), the command prompts the
user for a file name, and saves the PostScript image in that file instead of
sending it to the printer.

Noninteractively, the argument FILENAME is treated as follows: if it is nil,
send the image to the printer.  If FILENAME is a string, save the PostScript

;;;###autoload
(defun ps-despool (&optional filename)
  "Send the spooled PostScript to the printer.

Interactively, when you use a prefix argument (\\[universal-argument]), the command prompts the
user for a file name, and saves the spooled PostScript image in that file
instead of sending it to the printer.

Noninteractively, the argument FILENAME is treated as follows: if it is nil,
send the image to the printer.  If FILENAME is a string, save the PostScript

  (interactive (list (ps-print-preprint current-prefix-arg)))
  (ps-do-despool filename))

;;;###autoload
(defun ps-line-lengths ()
  "Display the correspondence between a line length and a font size.
Done using the current ps-print setup.
Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | head"
  (interactive)
  (ps-line-lengths-internal))

;;;###autoload

  (or (face-underline-p face)
      (memq face ps-underlined-faces)))


(defun ps-prologue-file (filenumber)
  "If prologue FILENUMBER exists and is readable, return contents as string.

Note: No major/minor-mode is activated and no local variables are evaluated for
      FILENUMBER, but proper EOL-conversion and character interpretation is
      done!"
  (let ((filename (convert-standard-filename

(defvar ps-black-white-faces-alist nil
  "Alist of symbolic faces used for black/white PostScript printers.
An element of this list has the same form as `ps-print-face-extension-alist'
\(which see).

Don't change this list directly; instead,
use `ps-extend-face' and `ps-extend-face-list'.
See documentation for `ps-extend-face' for valid extension symbol.
See also documentation for `ps-print-color-p'.")

x-dimension, of the text it has printed, and thus affects the point at
which long lines wrap around."
  (get font-sym 'avg-char-width))

(defun ps-line-lengths-internal ()
  "Display the correspondence between a line length and a font size.
Done using the current ps-print setup.
Try: pr -t file | awk '{printf \"%3d %s\n\", length($0), $0}' | sort -r | head"
  (let* ((ps-font-size-internal
	  (or ps-font-size-internal
	      (ps-get-font-size 'ps-font-size)))
	 (ps-header-font-size-internal