ps-print.el 228 KB
Newer Older
Pavel Janík's avatar
Pavel Janík committed
1
;;; ps-print.el --- print text from the buffer as PostScript
2

3
;; Copyright (C) 1993-2012  Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
4

Pavel Janík's avatar
Pavel Janík committed
5 6
;; Author: Jim Thompson (was <thompson@wg2.waii.com>)
;;	Jacques Duthen (was <duthen@cegelec-red.fr>)
7
;;	Vinicius Jose Latorre <viniciusjl@ig.com.br>
Vinicius Jose Latorre's avatar
Vinicius Jose Latorre committed
8 9
;;	Kenichi Handa <handa@m17n.org> (multi-byte characters)
;; Maintainer: Kenichi Handa <handa@m17n.org> (multi-byte characters)
10
;;	Vinicius Jose Latorre <viniciusjl@ig.com.br>
Pavel Janík's avatar
Pavel Janík committed
11
;; Keywords: wp, print, PostScript
12
;; Version: 7.3.5
Vinicius Jose Latorre's avatar
Vinicius Jose Latorre committed
13
;; X-URL: http://www.emacswiki.org/cgi-bin/wiki/ViniciusJoseLatorre
Kenichi Handa's avatar
Kenichi Handa committed
14

15 16
(defconst ps-print-version "7.3.5"
  "ps-print.el, v 7.3.5 <2009/12/23 vinicius>
17

18
Vinicius's last change version -- this file may have been edited as part of
19 20
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.
21 22

Please send all bug fixes and enhancements to
23
	Vinicius Jose Latorre <viniciusjl@ig.com.br>.")
Richard M. Stallman's avatar
Richard M. Stallman committed
24

Richard M. Stallman's avatar
Richard M. Stallman committed
25
;; This file is part of GNU Emacs.
Richard M. Stallman's avatar
Richard M. Stallman committed
26

27 28 29 30 31 32 33 34 35 36 37 38
;; 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 Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Richard M. Stallman's avatar
Richard M. Stallman committed
39

40
;;; Commentary:
Richard M. Stallman's avatar
Richard M. Stallman committed
41

42
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Richard M. Stallman's avatar
Richard M. Stallman committed
43
;;
44
;; About ps-print
Richard M. Stallman's avatar
Richard M. Stallman committed
45
;; --------------
46
;;
47 48
;; This package provides printing of Emacs buffers on PostScript printers; the
;; buffer's bold and italic text attributes are preserved in the printer
49 50
;; output.  ps-print is intended for use with Emacs or XEmacs, together with a
;; fontifying package such as font-lock or hilit.
51
;;
52 53 54
;; ps-print uses the same face attributes defined through font-lock or hilit to
;; print a PostScript file, but some faces are better seeing on the screen than
;; on paper, specially when you have a black/white PostScript printer.
55 56 57 58 59 60
;;
;; ps-print allows a remap of face to another one that it is better to print,
;; for example, the face font-lock-comment-face (if you are using font-lock)
;; could have bold or italic attribute when printing, besides foreground color.
;; This remap improves printing look (see How Ps-Print Maps Faces).
;;
61
;;
62
;; Using ps-print
Richard M. Stallman's avatar
Richard M. Stallman committed
63 64
;; --------------
;;
65 66
;; ps-print provides eight commands for generating PostScript images of Emacs
;; buffers:
67 68 69 70 71 72 73 74 75 76
;;
;;        ps-print-buffer
;;        ps-print-buffer-with-faces
;;        ps-print-region
;;        ps-print-region-with-faces
;;        ps-spool-buffer
;;        ps-spool-buffer-with-faces
;;        ps-spool-region
;;        ps-spool-region-with-faces
;;
77 78 79 80
;; These commands all perform essentially the same function: they generate
;; PostScript images suitable for printing on a PostScript printer or
;; displaying with GhostScript.  These commands are collectively referred to as
;; "ps-print- commands".
81 82 83
;;
;; The word "print" or "spool" in the command name determines when the
;; PostScript image is sent to the printer:
Richard M. Stallman's avatar
Richard M. Stallman committed
84
;;
85
;;        print      - The PostScript image is immediately sent to the printer;
Richard M. Stallman's avatar
Richard M. Stallman committed
86
;;
87 88 89 90
;;        spool      - The PostScript image is saved temporarily in an Emacs
;;                     buffer.  Many images may be spooled locally before
;;                     printing them.  To send the spooled images to the
;;                     printer, use the command `ps-despool'.
Richard M. Stallman's avatar
Richard M. Stallman committed
91
;;
92 93 94 95 96
;; The spooling mechanism was designed for printing lots of small files (mail
;; messages or netnews articles) to save paper that would otherwise be wasted
;; on banner pages, and to make it easier to find your output at the printer
;; (it's easier to pick up one 50-page printout than to find 50 single-page
;; printouts).
97
;;
98 99 100 101 102 103
;; ps-print has a hook in the `kill-emacs-hook' so that you won't accidentally
;; quit from Emacs while you have unprinted PostScript waiting in the spool
;; buffer.  If you do attempt to exit with spooled PostScript, you'll be asked
;; if you want to print it, and if you decline, you'll be asked to confirm the
;; exit; this is modeled on the confirmation that Emacs uses for modified
;; buffers.
104
;;
105 106
;; The word "buffer" or "region" in the command name determines how much of the
;; buffer is printed:
107 108 109 110 111
;;
;;        buffer     - Print the entire buffer.
;;
;;        region     - Print just the current region.
;;
112 113 114 115 116 117
;; The -with-faces suffix on the command name means that the command will
;; include font, color, and underline information in the PostScript image, so
;; the printed image can look as pretty as the buffer.  The ps-print- commands
;; without the -with-faces suffix don't include font, color, or underline
;; information; images printed with these commands aren't as pretty, but are
;; faster to generate.
118 119 120
;;
;; Two ps-print- command examples:
;;
121 122 123
;;        ps-print-buffer             - print the entire buffer, without font,
;;                                      color, or underline information, and
;;                                      send it immediately to the printer.
124
;;
125 126 127 128
;;        ps-spool-region-with-faces  - print just the current region; include
;;                                      font, color, and underline information,
;;                                      and spool the image in Emacs to send to
;;                                      the printer later.
129 130 131
;;
;;
;; Invoking Ps-Print
132
;; -----------------
Richard M. Stallman's avatar
Richard M. Stallman committed
133
;;
134
;; To print your buffer, type
Richard M. Stallman's avatar
Richard M. Stallman committed
135
;;
136
;;        M-x ps-print-buffer
Richard M. Stallman's avatar
Richard M. Stallman committed
137
;;
138 139 140
;; or substitute one of the other seven ps-print- commands.  The command will
;; generate the PostScript image and print or spool it as specified.  By giving
;; the command a prefix argument
141 142 143
;;
;;        C-u M-x ps-print-buffer
;;
144 145 146 147 148
;; it will save the PostScript image to a file instead of sending it to the
;; printer; you will be prompted for the name of the file to save the image to.
;; The prefix argument is ignored by the commands that spool their images, but
;; you may save the spooled images to a file by giving a prefix argument to
;; `ps-despool':
149 150 151
;;
;;        C-u M-x ps-despool
;;
152 153
;; When invoked this way, `ps-despool' will prompt you for the name of the file
;; to save to.
154
;;
155 156 157
;; Any of the `ps-print-' commands can be bound to keys; I recommend binding
;; `ps-spool-buffer-with-faces', `ps-spool-region-with-faces', and
;; `ps-despool'.  Here are the bindings I use on my Sun 4 keyboard:
158 159
;;
;;   (global-set-key 'f22 'ps-spool-buffer-with-faces) ;f22 is prsc
Richard M. Stallman's avatar
Richard M. Stallman committed
160 161 162
;;   (global-set-key '(shift f22) 'ps-spool-region-with-faces)
;;   (global-set-key '(control f22) 'ps-despool)
;;
163 164
;;
;; The Printer Interface
165
;; ---------------------
166
;;
167 168 169
;; The variables `ps-lpr-command' and `ps-lpr-switches' determine what command
;; is used to send the PostScript images to the printer, and what arguments to
;; give the command.  These are analogous to `lpr-command' and `lpr-switches'.
170
;;
171 172 173
;; Make sure that they contain appropriate values for your system;
;; see the usage notes below and the documentation of these variables.
;;
174
;; The variable `ps-printer-name' determines the name of a local printer for
175 176
;; printing PostScript files.
;;
177 178 179 180 181
;; The variable `ps-printer-name-option' determines the option used by some
;; utilities to indicate the printer name, it's used only when
;; `ps-printer-name' is a non-empty string.  If you're using lpr utility to
;; print, for example, `ps-printer-name-option' should be set to "-P".
;;
182 183 184 185 186
;; NOTE: `ps-lpr-command' and `ps-lpr-switches' take their initial values from
;;       the variables `lpr-command' and `lpr-switches'.  If you have
;;       `lpr-command' set to invoke a pretty-printer such as `enscript', then
;;       ps-print won't work properly.  `ps-lpr-command' must name a program
;;       that does not format the files it prints.
187
;;       `ps-printer-name' takes its initial value from the variable
188 189 190
;;       `printer-name'.  `ps-printer-name-option' tries to guess which system
;;       Emacs is running and takes its initial value in accordance with this
;;       guess.
191
;;
192 193 194 195 196
;; The variable `ps-print-region-function' specifies a function to print the
;; region on a PostScript printer.
;; See definition of `call-process-region' for calling conventions.  The fourth
;; and the sixth arguments are both nil.
;;
197 198 199 200
;; The variable `ps-manual-feed' indicates if the printer will manually feed
;; paper.  If it's nil, automatic feeding takes place.  If it's non-nil, manual
;; feeding takes place.  The default is nil (automatic feeding).
;;
201 202 203 204
;; The variable `ps-end-with-control-d' specifies whether C-d (\x04) should be
;; inserted at end of PostScript generated.  Non-nil means do so.  The default
;; is nil (don't insert).
;;
205
;; If you're using Emacs for Windows 95/98/NT or MS-DOS, don't forget to
206 207 208 209
;; customize the following variables: `ps-printer-name',
;; `ps-printer-name-option', `ps-lpr-command', `ps-lpr-switches' and
;; `ps-spool-config'.  See these variables documentation in the code or by
;; typing, for example, C-h v ps-printer-name RET.
Gerd Moellmann's avatar
Gerd Moellmann committed
210
;;
211
;;
212 213
;; The Page Layout
;; ---------------
214
;;
215 216 217
;; All dimensions are floats in PostScript points.
;; 1 inch  ==       2.54  cm    ==     72       points
;; 1 cm    ==  (/ 1 2.54) inch  ==  (/ 72 2.54) points
218
;;
219 220 221 222
;; The variable `ps-paper-type' determines the size of paper ps-print formats
;; for; it should contain one of the symbols: `a4' `a3' `letter' `legal'
;; `letter-small' `tabloid' `ledger' `statement' `executive' `a4small' `b4'
;; `b5'.
223
;;
224 225 226 227 228 229 230 231
;; If variable `ps-warn-paper-type' is nil, it's *not* given an error if
;; PostScript printer doesn't have a paper with the size indicated by
;; `ps-paper-type', instead it uses the default paper size.  If variable
;; `ps-warn-paper-type' is non-nil, it's given an error if PostScript printer
;; doesn't have a paper with the size indicated by `ps-paper-type'.  It's used
;; when `ps-spool-config' is set to `setpagedevice' (see section Duplex
;; Printers).  The default value is non-nil (it gives an error).
;;
232 233
;; The variable `ps-landscape-mode' determines the orientation of the printing
;; on the page: nil means `portrait' mode, non-nil means `landscape' mode.
234
;; There is no oblique mode yet, though this is easy to do in ps.
235
;;
236 237 238 239
;; In landscape mode, the text is NOT scaled: you may print 70 lines in
;; portrait mode and only 50 lines in landscape mode.  The margins represent
;; margins in the printed paper: the top margin is the margin between the top
;; of the page and the printed header, whatever the orientation is.
240
;;
241 242
;; The variable `ps-number-of-columns' determines the number of columns both in
;; landscape and portrait mode.
243
;; You can use:
244 245 246
;; - (the standard) one column portrait mode.
;; - (my favorite) two columns landscape mode (which spares trees).
;; but also:
247
;; - one column landscape mode for files with very long lines.
248 249
;; - multi-column portrait or landscape mode.
;;
250 251 252 253
;; The variable `ps-print-upside-down' determines other orientation for
;; printing page: nil means `normal' printing, non-nil means `upside-down'
;; printing (that is, the page is rotated by 180 grades).  The default value is
;; nil (`normal' printing).
254 255
;;
;; The `upside-down' orientation can be used in portrait or landscape mode.
256
;;
257 258 259 260 261 262 263 264 265 266 267
;; The variable `ps-selected-pages' specifies 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.  The default value is
;; nil (print all pages).  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).
;;
268 269 270 271 272 273
;; The variable `ps-even-or-odd-pages' specifies if it prints even/odd pages.
;;
;; Valid values are:
;;
;; nil		print all pages.
;;
274
;; even-page	print only even pages.
275
;;
276 277 278 279 280
;; odd-page	print only odd pages.
;;
;; even-sheet	print only even sheets.
;;
;; odd-sheet	print only odd sheets.
281 282 283
;;
;; Any other value is treated as nil.  The default value is nil.
;;
284 285
;; See `ps-even-or-odd-pages' for more detailed documentation.
;;
286
;;
287 288
;; Horizontal layout
;; -----------------
289
;;
290 291 292
;; The horizontal layout is determined by the variables
;; `ps-left-margin' `ps-inter-column' `ps-right-margin'
;; as follows:
293
;;
294 295 296 297 298
;;  ------------------------------------------
;;  |    |      |    |      |    |      |    |
;;  | lm | text | ic | text | ic | text | rm |
;;  |    |      |    |      |    |      |    |
;;  ------------------------------------------
299
;;
300 301 302
;; If `ps-number-of-columns' is 1, `ps-inter-column' is not relevant.
;; Usually, lm = rm > 0 and ic = lm
;; If (ic < 0), the text of adjacent columns can overlap.
303 304
;;
;;
305 306 307 308
;; Vertical layout
;; ---------------
;;
;; The vertical layout is determined by the variables
309
;; `ps-bottom-margin' `ps-top-margin' `ps-header-offset' `ps-footer-offset'
310 311
;; as follows:
;;
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328
;; |--------|        |--------|        |--------|        |--------|
;; | tm     |        | tm     |        | tm     |        | tm     |
;; |--------|        |--------|        |--------|        |--------|
;; | header |        |        |        | header |        |        |
;; |--------|        |        |        |--------|        |        |
;; | ho     |        |        |        | ho     |        |        |
;; |--------|        |        |        |--------|        |        |
;; |        |        |        |        |        |        |        |
;; | text   |   or   | text   |   or   | text   |   or   | text   |
;; |        |        |        |        |        |        |        |
;; |        |        |--------|        |--------|        |        |
;; |        |        | fo     |        | fo     |        |        |
;; |        |        |--------|        |--------|        |        |
;; |        |        | footer |        | footer |        |        |
;; |--------|        |--------|        |--------|        |--------|
;; | bm     |        | bm     |        | bm     |        | bm     |
;; |--------|        |--------|        |--------|        |--------|
329 330
;;
;; If `ps-print-header' is nil, `ps-header-offset' is not relevant.
331
;; If `ps-print-footer' is nil, `ps-footer-offset' is not relevant.
332
;; The margins represent margins in the printed paper:
333 334 335 336
;; the top margin is the margin between the top of the page and the printed
;; header, whatever the orientation is;
;; the bottom margin is the margin between the bottom of the page and the
;; printed footer, whatever the orientation is.
337 338
;;
;;
339 340
;; Headers & Footers
;; -----------------
341
;;
342 343 344 345 346
;; ps-print can print headers at the top of each column or at the top of each
;; page; the default headers contain the following four items: on the left, the
;; name of the buffer and, if the buffer is visiting a file, the file's
;; directory; on the right, the page number and date of printing.  The default
;; headers look something like this:
347 348 349
;;
;;     ps-print.el                                         1/21
;;     /home/jct/emacs-lisp/ps/new                     94/12/31
350
;;
351 352
;; When printing on duplex printers, left and right are reversed so that the
;; page numbers are toward the outside (cf. `ps-spool-duplex').
353
;;
354 355 356 357 358
;; Headers are configurable:
;; To turn them off completely, set `ps-print-header' to nil.
;; To turn off the header's gaudy framing box,
;; set `ps-print-header-frame' to nil.
;;
359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388
;; The variable `ps-header-frame-alist' specifies header frame properties
;; alist.  Valid frame properties are:
;;
;;   fore-color		Specify the foreground frame color.
;;			It should be a float number between 0.0 (black color)
;;			and 1.0 (white color), a string which is a color name,
;;			or a list of 3 float numbers which corresponds to the
;;			Red Green Blue color scale, each float number between
;;			0.0 (dark color) and 1.0 (bright color).
;;			The default is 0 ("black").
;;
;;   back-color		Specify the background frame color (similar to
;;			fore-color).  The default is 0.9 ("gray90").
;;
;;   shadow-color	Specify the shadow color (similar to fore-color).
;;			The default is 0 ("black").
;;
;;   border-color	Specify the border color (similar to fore-color).
;;			The default is 0 ("black").
;;
;;   border-width	Specify the border width.
;;			The default is 0.4.
;;
;; Any other property is ignored.
;;
;; Don't change this alist directly, instead use customization, or `ps-value',
;; `ps-get', `ps-put' and `ps-del' functions (see them for documentation).
;;
;; To print only one header at the top of each page, set
;; `ps-print-only-one-header' to t.
389
;;
390 391 392 393 394 395 396 397 398 399 400
;; To switch headers, set `ps-switch-header' to:
;;
;;    nil	Never switch headers.
;;
;;    t		Always switch headers.
;;
;;    duplex	Switch headers only when duplexing is on, that is, when
;;		`ps-spool-duplex' is non-nil (see Duplex Printers).
;;
;; Any other value is treated as t.  The default value is `duplex'.
;;
401 402
;; The font family and size of text in the header are determined by the
;; variables `ps-header-font-family', `ps-header-font-size' and
403 404
;; `ps-header-title-font-size' (see below).
;;
405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
;; The variable `ps-header-line-pad' determines the 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: .5 means half a line.
;;
;; Page numbers are printed in `n/m' format, indicating page n of m pages; to
;; omit the total page count and just print the page number, set
;; `ps-show-n-of-n' to nil.
;;
;; The amount of information in the header can be changed by changing the
;; number of lines.  To show less, set `ps-header-lines' to 1, and the header
;; will show only the buffer name and page number.  To show more, set
;; `ps-header-lines' to 3, and the header will show the time of printing below
;; the date.
;;
;; To change the content of the headers, change the variables `ps-left-header'
;; and `ps-right-header'.
;; These variables are lists, specifying top-to-bottom the text to display on
;; the left or right side of the header.  Each element of the list should be a
;; string or a symbol.  Strings are inserted directly into the PostScript
;; arrays, and should contain the PostScript string delimiters '(' and ')'.
;;
;; Symbols in the header format lists can either represent functions or
;; variables.  Functions are called, and should return a string to show in the
;; header.  Variables should contain strings to display in the header.  In
;; either case, function or variable, the PostScript string delimiters are
;; added by ps-print, and should not be part of the returned value.
431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446
;;
;; Here's an example: say we want the left header to display the text
;;
;;     Moe
;;     Larry
;;     Curly
;;
;; where we have a function to return "Moe"
;;
;;     (defun moe-func ()
;;       "Moe")
;;
;; a variable specifying "Larry"
;;
;;     (setq larry-var "Larry")
;;
447
;; and a literal for "Curly".  Here's how `ps-left-header' should be set:
448 449 450
;;
;;     (setq ps-left-header (list 'moe-func 'larry-var "(Curly)"))
;;
451 452
;; Note that Curly has the PostScript string delimiters inside his quotes --
;; those aren't misplaced lisp delimiters!
453
;;
454 455
;; Without them, PostScript would attempt to call the undefined function Curly,
;; which would result in a PostScript error.
456
;;
457 458
;; Since most printers don't report PostScript errors except by aborting the
;; print job, this kind of error can be hard to track down.
459
;;
460
;; Consider yourself warned!
461
;;
462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482
;; ps-print also print footers.  The footer variables are: `ps-print-footer',
;; `ps-footer-offset', `ps-print-footer-frame', `ps-footer-font-family',
;; `ps-footer-font-size', `ps-footer-line-pad', `ps-footer-lines',
;; `ps-left-footer', `ps-right-footer' and `ps-footer-frame-alist'.  These
;; variables are similar to those one that control headers.
;;
;; The variables `ps-print-only-one-header' and `ps-switch-header' also control
;; the footer (The same way that control header).
;;
;; As a footer example, if you want to have a centered page number in the
;; footer but without headers, set:
;;
;;    (setq ps-print-header nil
;;          ps-print-footer t
;;          ps-print-footer-frame nil
;;          ps-footer-lines 1
;;          ps-right-footer nil
;;          ps-left-footer
;;          (list (concat "{pagenumberstring dup stringwidth pop"
;;                        " 2 div PrintWidth 2 div exch sub 0 rmoveto}")))
;;
483
;;
484 485 486 487 488 489
;; PostScript Prologue Header
;; --------------------------
;;
;; It is possible to add PostScript prologue header comments besides that
;; ps-print generates by setting the variable `ps-print-prologue-header'.
;;
490 491 492
;; `ps-print-prologue-header' may be a string or a symbol function which
;; returns a string.  Note that this string is inserted on PostScript prologue
;; header section which is used to define some document characteristic through
493 494 495 496
;; PostScript special comments, like "%%Requirements: jog\n".
;;
;; By default `ps-print-prologue-header' is nil.
;;
497 498 499 500
;; 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:
501 502 503 504
;;
;; (setq ps-print-prologue-header
;;       "%%+ numcopies(3) jog\n%%LanguageLevel: 2\n")
;;
505 506
;; The duplex requirement is inserted by ps-print (see section Duplex
;; Printers).
507 508 509 510 511 512 513 514
;;
;; Do not forget to terminate the string with "\n".
;;
;; For more information about PostScript document comments, see:
;;    PostScript Language Reference Manual (2nd edition)
;;    Adobe Systems Incorporated
;;    Appendix G: Document Structuring Conventions -- Version 3.0
;;
515 516 517 518
;; It is also possible to add an user defined PostScript prologue code before
;; all generated prologue code by setting the variable
;; `ps-user-defined-prologue'.
;;
519 520 521 522 523
;; `ps-user-defined-prologue' may be a string or a symbol function which
;; returns a string.  Note that this string is inserted after `ps-adobe-tag'
;; and PostScript prologue comments, and before ps-print PostScript prologue
;; code section.  That is, this string is inserted after error handler
;; initialization and before ps-print settings.
524 525 526 527
;;
;; By default `ps-user-defined-prologue' is nil.
;;
;; It's strongly recommended only insert PostScript code and/or comments
528 529
;; specific for your printing system particularities.  For example, some
;; special initialization that only your printing system needs.
530 531 532 533 534 535 536 537
;;
;; Do not insert code for duplex printing, n-up printing or error handler,
;; ps-print handles this in a suitable way.
;;
;; For more information about PostScript, see:
;;    PostScript Language Reference Manual (2nd edition)
;;    Adobe Systems Incorporated
;;
538 539 540 541 542 543 544
;; 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"))
;;
545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561
;;
;; PostScript Error Handler
;; ------------------------
;;
;; ps-print instruments generated PostScript code with an error handler.
;;
;; The variable `ps-error-handler-message' specifies where the error handler
;; message should be sent.
;;
;; Valid values are:
;;
;; none			catch the error and *DON'T* send any message.
;;
;; paper		catch the error and print on paper the error message.
;;			This is the default value.
;;
;; system		catch the error and send back the error message to
562 563 564 565
;;			printing system.  This is useful only if printing
;;			system send back an email reporting the error, or if
;;			there is some other alternative way to report back the
;;			error from the system to you.
566 567 568 569 570 571
;;
;; paper-and-system	catch the error, print on paper the error message and
;;			send back the error message to printing system.
;;
;; Any other value is treated as `paper'.
;;
572
;;
573
;; Duplex Printers
574
;; ---------------
575
;;
576 577 578 579 580
;; If you have a duplex-capable printer (one that prints both sides of the
;; paper), set `ps-spool-duplex' to t.
;; ps-print will insert blank pages to make sure each buffer starts on the
;; correct side of the paper.
;;
581 582
;; The variable `ps-spool-config' specifies who is the responsible for setting
;; duplex and page size.  Valid values are:
583 584 585 586 587 588 589 590 591 592 593 594 595 596 597
;;
;; lpr-switches    duplex and page size are configured by `ps-lpr-switches'.
;;                 Don't forget to set `ps-lpr-switches' to select duplex
;;                 printing for your printer.
;;
;; setpagedevice   duplex and page size are configured by ps-print using the
;;                 setpagedevice PostScript operator.
;;
;; nil             duplex and page size are configured by ps-print *not* using
;;                 the setpagedevice PostScript operator.
;;
;; Any other value is treated as nil.
;;
;; The default value is `lpr-switches'.
;;
598 599 600
;; WARNING: The setpagedevice PostScript operator affects ghostview utility
;;          when viewing file generated using landscape.  Also on some
;;          printers, setpagedevice affects zebra stripes; on other printers,
601 602 603 604 605 606 607 608 609
;;          setpagedevice 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.
;;
;; The variable `ps-spool-tumble' specifies how the page images on opposite
;; sides of a sheet are oriented with respect to each other.  If
610 611 612 613
;; `ps-spool-tumble' is nil, produces output suitable for binding on the left
;; or right.  If `ps-spool-tumble' is non-nil, produces output suitable for
;; binding at the top or bottom.  It has effect only when `ps-spool-duplex' is
;; non-nil.  The default value is nil.
614
;;
615 616 617
;; Some printer system prints a header page and forces the first page be
;; printed on header page back, when using duplex.  If your printer system has
;; this behavior, set variable `ps-banner-page-when-duplexing' to t.
618
;;
619 620 621
;; When `ps-banner-page-when-duplexing' is non-nil, it prints a blank page as
;; the very first printed page.  So, it behaves as the very first character of
;; buffer (or region) is ^L (\014).
622
;;
623 624
;; The default for `ps-banner-page-when-duplexing' is nil (*don't* skip the
;; very first page).
625 626 627 628 629 630 631 632
;;
;;
;; N-up Printing
;; -------------
;;
;; The variable `ps-n-up-printing' specifies the number of pages per sheet of
;; paper.  The value specified must be between 1 and 100.  The default is 1.
;;
633 634
;; NOTE: some PostScript printer may crash printing if `ps-n-up-printing' is
;; set to a high value (for example, 23).  If this happens, set a lower value.
635 636 637 638 639
;;
;; The variable `ps-n-up-margin' specifies the margin in points between the
;; sheet border and the n-up printing.  The default is 1 cm (or 0.3937 inches,
;; or 28.35 points).
;;
640 641
;; If variable `ps-n-up-border-p' is non-nil a border is drawn around each
;; page.  The default is t.
642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662
;;
;; The variable `ps-n-up-filling' specifies how page matrix is filled on each
;; sheet of paper.  Following are the valid values for `ps-n-up-filling' with a
;; filling example using a 3x4 page matrix:
;;
;;  left-top   1  2  3  4         left-bottom    9  10 11 12
;;             5  6  7  8                        5  6  7  8
;;             9  10 11 12                       1  2  3  4
;;
;;  right-top  4  3  2  1         right-bottom   12 11 10 9
;;             8  7  6  5                        8  7  6  5
;;             12 11 10 9                        4  3  2  1
;;
;;  top-left   1  4  7  10        bottom-left    3  6  9  12
;;             2  5  8  11                       2  5  8  11
;;             3  6  9  12                       1  4  7  10
;;
;;  top-right  10 7  4  1         bottom-right   12 9  6  3
;;             11 8  5  2                        11 8  5  2
;;             12 9  6  3                        10 7  4  1
;;
663
;; Any other value is treated as `left-top'.
664 665
;;
;; The default value is left-top.
666
;;
667
;;
668 669 670 671 672
;; Control And 8-bit Characters
;; ----------------------------
;;
;; The variable `ps-print-control-characters' specifies whether you want to see
;; a printable form for control and 8-bit characters, that is, instead of
673
;; sending, for example, a ^D (\004) to printer, it is sent the string "^D".
674 675 676
;;
;; Valid values for `ps-print-control-characters' are:
;;
Karl Heuer's avatar
Karl Heuer committed
677 678 679
;;  8-bit           This is the value to use when you want an ASCII encoding of
;;                  any control or non-ASCII character. Control characters are
;;                  encoded as "^D", and non-ASCII characters have an
680 681
;;                  octal encoding.
;;
Karl Heuer's avatar
Karl Heuer committed
682
;;  control-8-bit   This is the value to use when you want an ASCII encoding of
683 684 685 686
;;                  any control character, whether it is 7 or 8-bit.
;;                  European 8-bits accented characters are printed according
;;                  the current font.
;;
Karl Heuer's avatar
Karl Heuer committed
687
;;  control         Only ASCII control characters have an ASCII encoding.
688 689 690
;;                  European 8-bits accented characters are printed according
;;                  the current font.
;;
Karl Heuer's avatar
Karl Heuer committed
691
;;  nil             No ASCII encoding. Any character is printed according the
692
;;                  current font.
693 694 695
;;
;; Any other value is treated as nil.
;;
696
;; The default is `control-8-bit'.
697 698 699 700
;;
;; Characters TAB, NEWLINE and FORMFEED are always treated by ps-print engine.
;;
;;
Karl Heuer's avatar
Karl Heuer committed
701 702
;; Printing Multi-byte Buffer
;; --------------------------
703
;;
704
;; See ps-mule.el for documentation.
Kenichi Handa's avatar
Kenichi Handa committed
705 706
;;
;;
707 708 709
;; Line Number
;; -----------
;;
710 711
;; The variable `ps-line-number' specifies whether to number each line;
;; non-nil means do so.  The default is nil (don't number each line).
712
;;
713 714 715 716
;; The variable `ps-line-number-color' specifies the color for line number.
;; See `ps-zebra-color' for documentation.  The default is "black" (or 0.0, or
;; '(0.0 0.0 0.0)).
;;
717 718 719 720 721 722
;; The variable `ps-line-number-font' specifies the font for line number.
;; The default is "Times-Italic".
;;
;; The variable `ps-line-number-font-size' specifies the font size in points
;; for line number.  See `ps-font-size' for documentation.  The default is 6.
;;
723 724
;; The variable `ps-line-number-step' specifies the interval that line number
;; is printed.  For example, if `ps-line-number-step' is set to 2, the printing
725 726 727 728 729 730
;; will look like:
;;
;;    1 one line
;;      one line
;;    3 one line
;;      one line
731
;;    5 one line
732 733 734 735 736 737 738 739 740
;;      one line
;;      ...
;;
;; Valid values are:
;;
;; integer	an integer that specifies the interval that line number is
;;		printed.  If it's lesser than or equal to zero, it's used the
;;		value 1.
;;
741 742
;; `zebra'	specifies that only the line number of the first line in a
;;		zebra stripe is to be printed.
743 744 745 746
;;
;; Any other value is treated as `zebra'.
;; The default value is 1, so each line number is printed.
;;
747 748
;; The variable `ps-line-number-start' specifies the starting point in the
;; interval given by `ps-line-number-step'.  For example, if
749 750
;; `ps-line-number-step' is set to 3 and `ps-line-number-start' is set to 3,
;; the printing will look like:
751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
;;
;;      one line
;;      one line
;;    3 one line
;;      one line
;;      one line
;;    6 one line
;;      one line
;;      one line
;;    9 one line
;;      one line
;;      ...
;;
;; The values for `ps-line-number-start':
;;
;;    * If `ps-line-number-step' is an integer, must be between 1 and the value
;;	of `ps-line-number-step' inclusive.
;;
;;    * If `ps-line-number-step' is set to `zebra', must be between 1 and the
770
;;	value of `ps-zebra-stripe-height' inclusive.
771
;;
772 773
;; The default value is 1, so the line number of the first line of each
;; interval is printed.
774
;;
775 776 777 778
;;
;; Zebra Stripes
;; -------------
;;
779 780
;; Zebra stripes are a kind of background that appear "underneath" the text and
;; can make the text easier to read.  They look like this:
781 782 783
;;
;; XXXXXXXXXXXXXXXXXXXXXXXX
;; XXXXXXXXXXXXXXXXXXXXXXXX
784 785
;; XXXXXXXXXXXXXXXXXXXXXXXX
;;
786 787 788 789
;;
;;
;; XXXXXXXXXXXXXXXXXXXXXXXX
;; XXXXXXXXXXXXXXXXXXXXXXXX
790
;; XXXXXXXXXXXXXXXXXXXXXXXX
791
;;
792
;; The blocks of X's represent rectangles filled with a light gray color.
793 794
;; Each rectangle extends all the way across the page.
;;
795 796 797
;; The height, in lines, of each rectangle is controlled by the variable
;; `ps-zebra-stripe-height', which is 3 by default.  The distance between
;; stripes equals the height of a stripe.
Karl Heuer's avatar
Karl Heuer committed
798
;;
799
;; The variable `ps-zebra-stripes' controls whether to print zebra stripes.
800 801
;; Non-nil means yes, nil means no.  The default is nil.
;;
802 803 804 805 806
;; The variable `ps-zebra-color' controls the zebra stripes gray scale or RGB
;; color.  It should be a float number between 0.0 (black color) and 1.0 (white
;; color), a string which is a color name, or a list of 3 numbers which
;; corresponds to the Red Green Blue color scale.
;; The default is 0.95 (or "gray95", or '(0.95 0.95 0.95)).
807
;;
808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839
;; The variable `ps-zebra-stripe-follow' specifies how zebra stripes continue
;; on next page.  Visually, valid values are (the character `+' at right of
;; each column indicates that a line is printed):
;;
;;		   `nil'        `follow'        `full'        `full-follow'
;; Current Page --------     -----------     ---------     ----------------
;;		1  XXXXX +   1  XXXXXXXX +   1  XXXXXX +   1  XXXXXXXXXXXXX +
;;		2  XXXXX +   2  XXXXXXXX +   2  XXXXXX +   2  XXXXXXXXXXXXX +
;;		3  XXXXX +   3  XXXXXXXX +   3  XXXXXX +   3  XXXXXXXXXXXXX +
;;		4        +   4           +   4         +   4                +
;;		5        +   5           +   5         +   5                +
;;		6        +   6           +   6         +   6                +
;;		7  XXXXX +   7  XXXXXXXX +   7  XXXXXX +   7  XXXXXXXXXXXXX +
;;		8  XXXXX +   8  XXXXXXXX +   8  XXXXXX +   8  XXXXXXXXXXXXX +
;;		9  XXXXX +   9  XXXXXXXX +   9  XXXXXX +   9  XXXXXXXXXXXXX +
;;		10       +   10          +
;;		11       +   11          +
;;		--------     -----------     ---------     ----------------
;;    Next Page --------     -----------     ---------     ----------------
;;		12 XXXXX +   12          +   10 XXXXXX +   10               +
;;		13 XXXXX +   13 XXXXXXXX +   11 XXXXXX +   11               +
;;		14 XXXXX +   14 XXXXXXXX +   12 XXXXXX +   12               +
;;		15       +   15 XXXXXXXX +   13        +   13 XXXXXXXXXXXXX +
;;		16       +   16          +   14        +   14 XXXXXXXXXXXXX +
;;		17       +   17          +   15        +   15 XXXXXXXXXXXXX +
;;		18 XXXXX +   18          +   16 XXXXXX +   16               +
;;		19 XXXXX +   19 XXXXXXXX +   17 XXXXXX +   17               +
;;		20 XXXXX +   20 XXXXXXXX +   18 XXXXXX +   18               +
;;		21       +   21 XXXXXXXX +
;;		22       +   22          +
;;		--------     -----------     ---------     ----------------
;;
840
;; Any other value is treated as nil.
841
;;
842
;; See also section How Ps-Print Has A Text And/Or Image On Background.
843 844
;;
;;
845 846 847
;; Hooks
;; -----
;;
848
;; ps-print has the following hook variables:
849 850 851 852 853 854
;;
;; `ps-print-hook'
;;    It is evaluated once before any printing process.  This is the right
;;    place to initialize ps-print global data.
;;    For an example, see section Adding a New Font Family.
;;
855 856 857 858 859
;; `ps-print-begin-sheet-hook'
;;    It is evaluated on each beginning of sheet of paper.
;;    If `ps-n-up-printing' is equal to 1, `ps-print-begin-page-hook' is never
;;    evaluated.
;;
860
;; `ps-print-begin-page-hook'
861 862
;;    It is evaluated on each beginning of page, except in the beginning of
;;    page that `ps-print-begin-sheet-hook' is evaluated.
863 864
;;
;; `ps-print-begin-column-hook'
865 866
;;    It is evaluated on each beginning of column, except in the beginning of
;;    column that `ps-print-begin-page-hook' is evaluated or that
867
;;    `ps-print-begin-sheet-hook' is evaluated.
868 869 870
;;
;;
;; Font Managing
871 872
;; -------------
;;
873 874
;; ps-print now knows rather precisely some fonts: the variable
;; `ps-font-info-database' contains information for a list of font families
875 876 877 878 879
;; (currently mainly `Courier' `Helvetica' `Times' `Palatino'
;; `Helvetica-Narrow' `NewCenturySchlbk').  Each font family contains the font
;; names for standard, bold, italic and bold-italic characters, a reference
;; size (usually 10) and the corresponding line height, width of a space and
;; average character width.
880
;;
881 882 883 884
;; The variable `ps-font-family' determines which font family is to be used for
;; ordinary text.  If its value does not correspond to a known font family, an
;; error message is printed into the `*Messages*' buffer, which lists the
;; currently available font families.
885
;;
886
;; The variable `ps-font-size' determines the size (in points) of the font for
887 888
;; ordinary text, when generating PostScript.  Its value is a float or a cons
;; of floats which has the following form:
889
;;
890 891 892 893 894 895 896 897
;;    (LANDSCAPE-SIZE . PORTRAIT-SIZE)
;;
;; Similarly, the variable `ps-header-font-family' determines which font family
;; is to be used for text in the header.
;;
;; The variable `ps-header-font-size' determines the font size, in points, for
;; text in the header (similar to `ps-font-size').
;;
898 899
;; The variable `ps-header-title-font-size' determines the font size, in
;; points, for the top line of text in the header (similar to `ps-font-size').
900
;;
901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924
;; The variable `ps-line-spacing' determines the line spacing, in points, for
;; ordinary text, when generating PostScript (similar to `ps-font-size').  The
;; default value is 0 (zero = no line spacing).
;;
;; The variable `ps-paragraph-spacing' determines the paragraph spacing, in
;; points, for ordinary text, when generating PostScript (similar to
;; `ps-font-size').  The default value is 0 (zero = no paragraph spacing).
;;
;; To get all lines with some spacing set both `ps-line-spacing' and
;; `ps-paragraph-spacing' variables.
;;
;; The variable `ps-paragraph-regexp' specifies the paragraph delimiter.  It
;; should be a regexp or nil.  The default value is "[ \t]*$", that is, an
;; empty line or a line containing only spaces and tabs.
;;
;; The variable `ps-begin-cut-regexp' and `ps-end-cut-regexp' specify the start
;; and end of a region to cut out when printing.
;;
;; As an example, variables `ps-begin-cut-regexp' and `ps-end-cut-regexp' may
;; be set to "^Local Variables:" and "^End:", respectively, in order to leave
;; out some special printing instructions from the actual print.  Special
;; printing instructions may be appended to the end of the file just like any
;; other buffer-local variables.  See section "Local Variables in Files" on
;; Emacs manual for more information.
925 926 927 928
;;
;; Variables `ps-begin-cut-regexp' and `ps-end-cut-regexp' control together
;; what actually gets printed.  Both variables may be set to nil in which case
;; no cutting occurs.  By default, both variables are set to nil.
929
;;
930
;;
931
;; Adding a New Font Family
932 933
;; ------------------------
;;
934 935 936
;; To use a new font family, you MUST first teach ps-print this font, i.e., add
;; its information to `ps-font-info-database', otherwise ps-print cannot
;; correctly place line and page breaks.
937
;;
938 939
;; For example, assuming `Helvetica' is unknown, you first need to do the
;; following ONLY ONCE:
940 941 942 943
;;
;; - create a new buffer
;; - generate the PostScript image to a file (C-u M-x ps-print-buffer)
;; - open this file and find the line:
944
;;	`% 3 cm 20 cm moveto  10/Courier ReportFontInfo  showpage'
945
;; - delete the leading `%' (which is the PostScript comment character)
946 947
;; - replace in this line `Courier' by the new font (say `Helvetica') to get
;;   the line:
948
;;	`3 cm 20 cm moveto  10/Helvetica ReportFontInfo  showpage'
949 950 951 952 953 954 955 956
;; - send this file to the printer (or to ghostscript).
;;   You should read the following on the output page:
;;
;;     For Helvetica 10 point, the line height is 11.56, the space width is 2.78
;;     and a crude estimate of average character width is 5.09243
;;
;; - Add these values to the `ps-font-info-database':
;;   (setq ps-font-info-database
957 958 959 960 961 962 963 964 965 966 967
;;	   (append
;;	    '((Helvetica			; the family key
;;	       (fonts (normal      . "Helvetica")
;;		      (bold        . "Helvetica-Bold")
;;		      (italic      . "Helvetica-Oblique")
;;		      (bold-italic . "Helvetica-BoldOblique"))
;;	       (size . 10.0)
;;	       (line-height . 11.56)
;;	       (space-width . 2.78)
;;	       (avg-char-width . 5.09243)))
;;	    ps-font-info-database))
968 969
;; - Now you can use this font family with any size:
;;	(setq ps-font-family 'Helvetica)
970 971
;; - if you want to use this family in another emacs session, you must put into
;;   your `~/.emacs':
972 973 974 975
;;	(require 'ps-print)
;;	(setq ps-font-info-database (append ...)))
;;   if you don't want to load ps-print, you have to copy the whole value:
;;	(setq ps-font-info-database '(<your stuff> <the standard stuff>))
976 977
;;   or, use `ps-print-hook' (see section Hooks):
;;	(add-hook 'ps-print-hook
978
;;		  (lambda ()
979 980
;;		     (or (assq 'Helvetica ps-font-info-database)
;;			 (setq ps-font-info-database (append ...)))))
981 982
;;
;; You can create new `mixed' font families like:
983 984 985
;;      (my-mixed-family
;;       (fonts (normal               . "Courier-Bold")
;;              (bold                 . "Helvetica")
986
;;              (italic               . "ZapfChancery-MediumItalic")
987 988 989 990 991 992
;;              (bold-italic          . "NewCenturySchlbk-BoldItalic")
;;              (w3-table-hack-x-face . "LineDrawNormal"))
;;       (size . 10.0)
;;       (line-height . 10.55)
;;       (space-width . 6.0)
;;       (avg-char-width . 6.0))
993
;;
994 995 996
;; Now you can use your new font family with any size:
;;	(setq ps-font-family 'my-mixed-family)
;;
997 998 999 1000 1001
;; Note that on above example the `w3-table-hack-x-face' entry refers to a face
;; symbol, so when printing this face it'll be used the font `LineDrawNormal'.
;; If the face `w3-table-hack-x-face' is remapped to use bold and/or italic
;; attribute, the corresponding entry (bold, italic or bold-italic) will be
;; used instead of `w3-table-hack-x-face' entry.
1002 1003 1004 1005 1006 1007 1008 1009
;;
;; Note also that the font family entry order is irrelevant, so the above
;; example could also be written:
;;      (my-mixed-family
;;       (size . 10.0)
;;       (fonts (w3-table-hack-x-face . "LineDrawNormal")
;;              (bold                 . "Helvetica")
;;              (bold-italic          . "NewCenturySchlbk-BoldItalic")
1010
;;              (italic               . "ZapfChancery-MediumItalic")
1011 1012 1013 1014 1015 1016 1017 1018
;;              (normal               . "Courier-Bold"))
;;       (avg-char-width . 6.0)
;;       (space-width . 6.0)
;;       (line-height . 10.55))
;;
;; Despite the note above, it is recommended that some convention about
;; entry order be used.
;;
1019 1020 1021 1022
;; You can get information on all the fonts resident in YOUR printer
;; by uncommenting the line:
;;	% 3 cm 20 cm moveto  ReportAllFontInfo           showpage
;;
1023
;; The PostScript file should be sent to YOUR PostScript printer.
1024 1025
;; If you send it to ghostscript or to another PostScript printer, you may get
;; slightly different results.
1026 1027 1028 1029
;; Anyway, as ghostscript fonts are autoload, you won't get much font info.
;;
;; Note also that ps-print DOESN'T download any font to your printer, instead
;; it uses the fonts resident in your printer.
1030 1031 1032 1033
;;
;;
;; How Ps-Print Deals With Faces
;; -----------------------------
1034
;;
1035 1036 1037 1038
;; The ps-print-*-with-faces commands attempt to determine which faces should
;; be printed in bold or italic, but their guesses aren't always right.  For
;; example, you might want to map colors into faces so that blue faces print in
;; bold, and red faces in italic.
1039
;;
1040 1041 1042
;; It is possible to force ps-print to consider specific faces bold, italic or
;; underline, no matter what font they are displayed in, by setting the
;; variables `ps-bold-faces', `ps-italic-faces' and `ps-underlined-faces'.
1043 1044 1045
;; These variables contain lists of faces that ps-print should consider bold,
;; italic or underline; to set them, put code like the following into your
;; .emacs file:
1046
;;
1047
;;      (setq ps-bold-faces '(my-blue-face))
1048
;;      (setq ps-italic-faces '(my-red-face))
1049
;;      (setq ps-underlined-faces '(my-green-face))
1050
;;
1051 1052
;; Faces like bold-italic that are both bold and italic should go in *both*
;; lists.
1053
;;
1054 1055 1056 1057
;; ps-print keeps internal lists of which fonts are bold and which are italic;
;; these lists are built the first time you invoke ps-print.
;; For the sake of efficiency, the lists are built only once; the same lists
;; are referred in later invocations of ps-print.
1058
;;
1059 1060 1061 1062 1063
;; Because these lists are built only once, it's possible for them to get out
;; of sync, if a face changes, or if new faces are added.  To get the lists
;; back in sync, you can set the variable `ps-build-face-reference' to t, and
;; the lists will be rebuilt the next time ps-print is invoked.  If you need
;; that the lists always be rebuilt when ps-print is invoked, set the variable
1064
;; `ps-always-build-face-reference' to t.
1065
;;
1066 1067 1068 1069 1070 1071 1072 1073 1074
;; If you need to print without worrying about face background color, set the
;; variable `ps-use-face-background' which specifies if face background should
;; be used.  Valid values are:
;;
;;    t		always use face background color.
;;    nil	never use face background color.
;;    (face...)	list of faces whose background color will be used.
;;
;; Any other value will be treated as t.
1075
;; The default value is nil.
1076
;;
1077 1078 1079 1080
;;
;; How Ps-Print Deals With Color
;; -----------------------------
;;
1081 1082 1083 1084
;; ps-print detects faces with foreground and background colors defined and
;; embeds color information in the PostScript image.
;; The default foreground and background colors are defined by the variables
;; `ps-default-fg' and `ps-default-bg'.
1085
;; On black/white printers, colors are displayed in gray scale.
1086
;; To turn off color output, set `ps-print-color-p' to nil.
1087 1088
;; You can also set `ps-print-color-p' to 'black-white to have a better looking
;; on black/white printers.  See also `ps-black-white-faces' for documentation.
1089
;;
1090 1091 1092 1093 1094 1095
;; ps-print also detects if the text foreground and background colors are
;; equals when `ps-fg-validate-p' is non-nil.  In this case, if these colors
;; are used, no text will appear.  You can use `ps-fg-list' to give a list of
;; foreground colors to be used when text foreground and background colors are
;; equals.  It'll be used the first foreground color in `ps-fg-list' which is
;; different from the background color.  If `ps-fg-list' is nil, the default
Lute Kamstra's avatar
Lute Kamstra committed
1096
;; foreground color is used.
1097
;;
1098
;;
1099 1100 1101
;; How Ps-Print Maps Faces
;; -----------------------
;;
1102 1103 1104
;; As ps-print uses PostScript to print buffers, it is possible to have other
;; attributes associated with faces. So the new attributes used by ps-print
;; are:
1105 1106 1107 1108 1109
;;
;;   strikeout - like underline, but the line is in middle of text.
;;   overline  - like underline, but the line is over the text.
;;   shadow    - text will have a shadow.
;;   box       - text will be surrounded by a box.
1110
;;   outline   - print characters as hollow outlines.
1111
;;
1112
;; See the documentation for `ps-extend-face'.
1113
;;
1114