ps-print.el 239 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, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
4
;; 2003, 2004, 2005 Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
5

Pavel Janík's avatar
Pavel Janík committed
6 7
;; Author: Jim Thompson (was <thompson@wg2.waii.com>)
;;	Jacques Duthen (was <duthen@cegelec-red.fr>)
8
;;	Vinicius Jose Latorre <viniciusjl@ig.com.br>
Pavel Janík's avatar
Pavel Janík committed
9 10
;;	Kenichi Handa <handa@etl.go.jp> (multi-byte characters)
;; Maintainer: Kenichi Handa <handa@etl.go.jp> (multi-byte characters)
11
;;	Vinicius Jose Latorre <viniciusjl@ig.com.br>
Pavel Janík's avatar
Pavel Janík committed
12
;; Keywords: wp, print, PostScript
13 14
;; Time-stamp: <2005/06/27 00:57:22 vinicius>
;; Version: 6.6.7
Pavel Janík's avatar
Pavel Janík committed
15
;; X-URL: http://www.cpqd.com.br/~vinicius/emacs/
Kenichi Handa's avatar
Kenichi Handa committed
16

17
(defconst ps-print-version "6.6.6"
18
  "ps-print.el, v 6.6.7 <2005/06/27 vinicius>
19

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

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

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

29 30 31 32
;; 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 2, or (at your option) any later
;; version.
Richard M. Stallman's avatar
Richard M. Stallman committed
33

34 35 36 37
;; 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.
Richard M. Stallman's avatar
Richard M. Stallman committed
38

39 40 41
;; You should have received a copy of the GNU General Public License along with
;; GNU Emacs; see the file COPYING.  If not, write to the Free Software
;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Richard M. Stallman's avatar
Richard M. Stallman committed
42

43
;;; Commentary:
Richard M. Stallman's avatar
Richard M. Stallman committed
44

45
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Richard M. Stallman's avatar
Richard M. Stallman committed
46
;;
47
;; About ps-print
Richard M. Stallman's avatar
Richard M. Stallman committed
48
;; --------------
49
;;
50 51
;; This package provides printing of Emacs buffers on PostScript printers; the
;; buffer's bold and italic text attributes are preserved in the printer
52 53
;; output.  ps-print is intended for use with Emacs or XEmacs, together with a
;; fontifying package such as font-lock or hilit.
54
;;
55 56 57
;; 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.
58 59 60 61 62 63
;;
;; 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).
;;
64
;;
65
;; Using ps-print
Richard M. Stallman's avatar
Richard M. Stallman committed
66 67
;; --------------
;;
68 69
;; ps-print provides eight commands for generating PostScript images of Emacs
;; buffers:
70 71 72 73 74 75 76 77 78 79
;;
;;        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
;;
80 81 82 83
;; 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".
84 85 86
;;
;; 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
87
;;
88
;;        print      - The PostScript image is immediately sent to the printer;
Richard M. Stallman's avatar
Richard M. Stallman committed
89
;;
90 91 92 93
;;        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
94
;;
95 96 97 98 99
;; 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).
100
;;
101 102 103 104 105 106
;; 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.
107
;;
108 109
;; The word "buffer" or "region" in the command name determines how much of the
;; buffer is printed:
110 111 112 113 114
;;
;;        buffer     - Print the entire buffer.
;;
;;        region     - Print just the current region.
;;
115 116 117 118 119 120
;; 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.
121 122 123
;;
;; Two ps-print- command examples:
;;
124 125 126
;;        ps-print-buffer             - print the entire buffer, without font,
;;                                      color, or underline information, and
;;                                      send it immediately to the printer.
127
;;
128 129 130 131
;;        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.
132 133 134
;;
;;
;; Invoking Ps-Print
135
;; -----------------
Richard M. Stallman's avatar
Richard M. Stallman committed
136
;;
137
;; To print your buffer, type
Richard M. Stallman's avatar
Richard M. Stallman committed
138
;;
139
;;        M-x ps-print-buffer
Richard M. Stallman's avatar
Richard M. Stallman committed
140
;;
141 142 143
;; 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
144 145 146
;;
;;        C-u M-x ps-print-buffer
;;
147 148 149 150 151
;; 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':
152 153 154
;;
;;        C-u M-x ps-despool
;;
155 156
;; When invoked this way, `ps-despool' will prompt you for the name of the file
;; to save to.
157
;;
158 159 160
;; 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:
161 162
;;
;;   (global-set-key 'f22 'ps-spool-buffer-with-faces) ;f22 is prsc
Richard M. Stallman's avatar
Richard M. Stallman committed
163 164 165
;;   (global-set-key '(shift f22) 'ps-spool-region-with-faces)
;;   (global-set-key '(control f22) 'ps-despool)
;;
166 167
;;
;; The Printer Interface
168
;; ---------------------
169
;;
170 171 172
;; 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'.
173
;;
174 175 176
;; Make sure that they contain appropriate values for your system;
;; see the usage notes below and the documentation of these variables.
;;
177
;; The variable `ps-printer-name' determines the name of a local printer for
178 179
;; printing PostScript files.
;;
180 181 182 183 184
;; 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".
;;
185 186 187 188 189
;; 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.
190
;;       `ps-printer-name' takes its initial value from the variable
191 192 193
;;       `printer-name'.  `ps-printer-name-option' tries to guess which system
;;       Emacs is running and takes its initial value in accordance with this
;;       guess.
194
;;
195 196 197 198 199
;; 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.
;;
200 201 202 203
;; 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).
;;
204 205 206 207
;; 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).
;;
208
;; If you're using Emacs for Windows 95/98/NT or MS-DOS, don't forget to
209 210 211 212
;; 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
213
;;
214
;;
215 216
;; The Page Layout
;; ---------------
217
;;
218 219 220
;; All dimensions are floats in PostScript points.
;; 1 inch  ==       2.54  cm    ==     72       points
;; 1 cm    ==  (/ 1 2.54) inch  ==  (/ 72 2.54) points
221
;;
222 223 224 225
;; 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'.
226
;;
227 228 229 230 231 232 233 234
;; 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).
;;
235 236
;; The variable `ps-landscape-mode' determines the orientation of the printing
;; on the page: nil means `portrait' mode, non-nil means `landscape' mode.
237
;; There is no oblique mode yet, though this is easy to do in ps.
238
;;
239 240 241 242
;; 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.
243
;;
244 245
;; The variable `ps-number-of-columns' determines the number of columns both in
;; landscape and portrait mode.
246
;; You can use:
247 248 249
;; - (the standard) one column portrait mode.
;; - (my favorite) two columns landscape mode (which spares trees).
;; but also:
250
;; - one column landscape mode for files with very long lines.
251 252
;; - multi-column portrait or landscape mode.
;;
253 254 255 256
;; 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).
257 258
;;
;; The `upside-down' orientation can be used in portrait or landscape mode.
259
;;
260 261 262 263 264 265 266 267 268 269 270
;; 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).
;;
271 272 273 274 275 276
;; The variable `ps-even-or-odd-pages' specifies if it prints even/odd pages.
;;
;; Valid values are:
;;
;; nil		print all pages.
;;
277
;; even-page	print only even pages.
278
;;
279 280 281 282 283
;; odd-page	print only odd pages.
;;
;; even-sheet	print only even sheets.
;;
;; odd-sheet	print only odd sheets.
284 285 286
;;
;; Any other value is treated as nil.  The default value is nil.
;;
287 288
;; See `ps-even-or-odd-pages' for more detailed documentation.
;;
289
;;
290 291
;; Horizontal layout
;; -----------------
292
;;
293 294 295
;; The horizontal layout is determined by the variables
;; `ps-left-margin' `ps-inter-column' `ps-right-margin'
;; as follows:
296
;;
297 298 299 300 301
;;  ------------------------------------------
;;  |    |      |    |      |    |      |    |
;;  | lm | text | ic | text | ic | text | rm |
;;  |    |      |    |      |    |      |    |
;;  ------------------------------------------
302
;;
303 304 305
;; 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.
306 307
;;
;;
308 309 310 311
;; Vertical layout
;; ---------------
;;
;; The vertical layout is determined by the variables
312
;; `ps-bottom-margin' `ps-top-margin' `ps-header-offset' `ps-footer-offset'
313 314
;; as follows:
;;
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
;; |--------|        |--------|        |--------|        |--------|
;; | tm     |        | tm     |        | tm     |        | tm     |
;; |--------|        |--------|        |--------|        |--------|
;; | header |        |        |        | header |        |        |
;; |--------|        |        |        |--------|        |        |
;; | ho     |        |        |        | ho     |        |        |
;; |--------|        |        |        |--------|        |        |
;; |        |        |        |        |        |        |        |
;; | text   |   or   | text   |   or   | text   |   or   | text   |
;; |        |        |        |        |        |        |        |
;; |        |        |--------|        |--------|        |        |
;; |        |        | fo     |        | fo     |        |        |
;; |        |        |--------|        |--------|        |        |
;; |        |        | footer |        | footer |        |        |
;; |--------|        |--------|        |--------|        |--------|
;; | bm     |        | bm     |        | bm     |        | bm     |
;; |--------|        |--------|        |--------|        |--------|
332 333
;;
;; If `ps-print-header' is nil, `ps-header-offset' is not relevant.
334
;; If `ps-print-footer' is nil, `ps-footer-offset' is not relevant.
335
;; The margins represent margins in the printed paper:
336 337 338 339
;; 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.
340 341
;;
;;
342 343
;; Headers & Footers
;; -----------------
344
;;
345 346 347 348 349
;; 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:
350 351 352
;;
;;     ps-print.el                                         1/21
;;     /home/jct/emacs-lisp/ps/new                     94/12/31
353
;;
354 355
;; When printing on duplex printers, left and right are reversed so that the
;; page numbers are toward the outside (cf. `ps-spool-duplex').
356
;;
357 358 359 360 361
;; 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.
;;
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 389 390 391
;; 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.
392
;;
393 394 395 396 397 398 399 400 401 402 403
;; 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'.
;;
404 405
;; The font family and size of text in the header are determined by the
;; variables `ps-header-font-family', `ps-header-font-size' and
406 407
;; `ps-header-title-font-size' (see below).
;;
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433
;; 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.
434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
;;
;; 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")
;;
450
;; and a literal for "Curly".  Here's how `ps-left-header' should be set:
451 452 453
;;
;;     (setq ps-left-header (list 'moe-func 'larry-var "(Curly)"))
;;
454 455
;; Note that Curly has the PostScript string delimiters inside his quotes --
;; those aren't misplaced lisp delimiters!
456
;;
457 458
;; Without them, PostScript would attempt to call the undefined function Curly,
;; which would result in a PostScript error.
459
;;
460 461
;; Since most printers don't report PostScript errors except by aborting the
;; print job, this kind of error can be hard to track down.
462
;;
463
;; Consider yourself warned!
464
;;
465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485
;; 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}")))
;;
486
;;
487 488 489 490 491 492
;; 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'.
;;
493 494 495
;; `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
496 497 498 499
;; PostScript special comments, like "%%Requirements: jog\n".
;;
;; By default `ps-print-prologue-header' is nil.
;;
500 501 502 503
;; 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:
504 505 506 507
;;
;; (setq ps-print-prologue-header
;;       "%%+ numcopies(3) jog\n%%LanguageLevel: 2\n")
;;
508 509
;; The duplex requirement is inserted by ps-print (see section Duplex
;; Printers).
510 511 512 513 514 515 516 517
;;
;; 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
;;
518 519 520 521
;; 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'.
;;
522 523 524 525 526
;; `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.
527 528 529 530
;;
;; By default `ps-user-defined-prologue' is nil.
;;
;; It's strongly recommended only insert PostScript code and/or comments
531 532
;; specific for your printing system particularities.  For example, some
;; special initialization that only your printing system needs.
533 534 535 536 537 538 539 540
;;
;; 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
;;
541 542 543 544 545 546 547
;; 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"))
;;
548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564
;;
;; 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
565 566 567 568
;;			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.
569 570 571 572 573 574
;;
;; 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'.
;;
575
;;
576
;; Duplex Printers
577
;; ---------------
578
;;
579 580 581 582 583
;; 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.
;;
584 585
;; The variable `ps-spool-config' specifies who is the responsible for setting
;; duplex and page size.  Valid values are:
586 587 588 589 590 591 592 593 594 595 596 597 598 599 600
;;
;; 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'.
;;
601 602 603
;; 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,
604 605 606 607 608 609 610 611 612
;;          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
613 614 615 616
;; `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.
617
;;
618 619 620
;; 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.
621
;;
622 623 624
;; 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).
625
;;
626 627
;; The default for `ps-banner-page-when-duplexing' is nil (*don't* skip the
;; very first page).
628 629 630 631 632 633 634 635
;;
;;
;; 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.
;;
636 637
;; 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.
638 639 640 641 642
;;
;; 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).
;;
643 644
;; If variable `ps-n-up-border-p' is non-nil a border is drawn around each
;; page.  The default is t.
645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665
;;
;; 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
;;
666
;; Any other value is treated as `left-top'.
667 668
;;
;; The default value is left-top.
669
;;
670
;;
671 672 673 674 675
;; 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
676
;; sending, for example, a ^D (\004) to printer, it is sent the string "^D".
677 678 679
;;
;; Valid values for `ps-print-control-characters' are:
;;
Karl Heuer's avatar
Karl Heuer committed
680 681 682
;;  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
683 684
;;                  octal encoding.
;;
Karl Heuer's avatar
Karl Heuer committed
685
;;  control-8-bit   This is the value to use when you want an ASCII encoding of
686 687 688 689
;;                  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
690
;;  control         Only ASCII control characters have an ASCII encoding.
691 692 693
;;                  European 8-bits accented characters are printed according
;;                  the current font.
;;
Karl Heuer's avatar
Karl Heuer committed
694
;;  nil             No ASCII encoding. Any character is printed according the
695
;;                  current font.
696 697 698
;;
;; Any other value is treated as nil.
;;
699
;; The default is `control-8-bit'.
700 701 702 703
;;
;; Characters TAB, NEWLINE and FORMFEED are always treated by ps-print engine.
;;
;;
Karl Heuer's avatar
Karl Heuer committed
704 705
;; Printing Multi-byte Buffer
;; --------------------------
706
;;
707
;; See ps-mule.el for documentation.
Kenichi Handa's avatar
Kenichi Handa committed
708 709
;;
;;
710 711 712
;; Line Number
;; -----------
;;
713 714
;; 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).
715
;;
716 717 718 719
;; 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)).
;;
720 721 722 723 724 725
;; 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.
;;
726 727
;; 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
728 729 730 731 732 733
;; will look like:
;;
;;    1 one line
;;      one line
;;    3 one line
;;      one line
734
;;    5 one line
735 736 737 738 739 740 741 742 743
;;      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.
;;
744 745
;; `zebra'	specifies that only the line number of the first line in a
;;		zebra stripe is to be printed.
746 747 748 749
;;
;; Any other value is treated as `zebra'.
;; The default value is 1, so each line number is printed.
;;
750 751
;; The variable `ps-line-number-start' specifies the starting point in the
;; interval given by `ps-line-number-step'.  For example, if
752 753
;; `ps-line-number-step' is set to 3 and `ps-line-number-start' is set to 3,
;; the printing will look like:
754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772
;;
;;      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
773
;;	value of `ps-zebra-stripe-height' inclusive.
774
;;
775 776
;; The default value is 1, so the line number of the first line of each
;; interval is printed.
777
;;
778 779 780 781
;;
;; Zebra Stripes
;; -------------
;;
782 783
;; Zebra stripes are a kind of background that appear "underneath" the text and
;; can make the text easier to read.  They look like this:
784 785 786
;;
;; XXXXXXXXXXXXXXXXXXXXXXXX
;; XXXXXXXXXXXXXXXXXXXXXXXX
787 788
;; XXXXXXXXXXXXXXXXXXXXXXXX
;;
789 790 791 792
;;
;;
;; XXXXXXXXXXXXXXXXXXXXXXXX
;; XXXXXXXXXXXXXXXXXXXXXXXX
793
;; XXXXXXXXXXXXXXXXXXXXXXXX
794
;;
795
;; The blocks of X's represent rectangles filled with a light gray color.
796 797
;; Each rectangle extends all the way across the page.
;;
798 799 800
;; 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
801
;;
802
;; The variable `ps-zebra-stripes' controls whether to print zebra stripes.
803 804
;; Non-nil means yes, nil means no.  The default is nil.
;;
805 806 807 808 809
;; 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)).
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 840 841 842
;; 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          +
;;		--------     -----------     ---------     ----------------
;;
843
;; Any other value is treated as nil.
844
;;
845
;; See also section How Ps-Print Has A Text And/Or Image On Background.
846 847
;;
;;
848 849 850
;; Hooks
;; -----
;;
851
;; ps-print has the following hook variables:
852 853 854 855 856 857
;;
;; `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.
;;
858 859 860 861 862
;; `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.
;;
863
;; `ps-print-begin-page-hook'
864 865
;;    It is evaluated on each beginning of page, except in the beginning of
;;    page that `ps-print-begin-sheet-hook' is evaluated.
866 867
;;
;; `ps-print-begin-column-hook'
868 869
;;    It is evaluated on each beginning of column, except in the beginning of
;;    column that `ps-print-begin-page-hook' is evaluated or that
870
;;    `ps-print-begin-sheet-hook' is evaluated.
871 872 873
;;
;;
;; Font Managing
874 875
;; -------------
;;
876 877
;; ps-print now knows rather precisely some fonts: the variable
;; `ps-font-info-database' contains information for a list of font families
878 879 880 881 882
;; (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.
883
;;
884 885 886 887
;; 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.
888
;;
889
;; The variable `ps-font-size' determines the size (in points) of the font for
890 891
;; ordinary text, when generating PostScript.  Its value is a float or a cons
;; of floats which has the following form:
892
;;
893 894 895 896 897 898 899 900
;;    (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').
;;
901 902
;; 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').
903
;;
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927
;; 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.
928 929 930 931
;;
;; 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.
932
;;
933
;;
934
;; Adding a New Font Family
935 936
;; ------------------------
;;
937 938 939
;; 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.
940
;;
941 942
;; For example, assuming `Helvetica' is unknown, you first need to do the
;; following ONLY ONCE:
943 944 945 946
;;
;; - 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:
947
;;	`% 3 cm 20 cm moveto  10/Courier ReportFontInfo  showpage'
948
;; - delete the leading `%' (which is the PostScript comment character)
949 950
;; - replace in this line `Courier' by the new font (say `Helvetica') to get
;;   the line:
951
;;	`3 cm 20 cm moveto  10/Helvetica ReportFontInfo  showpage'
952 953 954 955 956 957 958 959
;; - 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
960 961 962 963 964 965 966 967 968 969 970
;;	   (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))
971 972
;; - Now you can use this font family with any size:
;;	(setq ps-font-family 'Helvetica)
973 974
;; - if you want to use this family in another emacs session, you must put into
;;   your `~/.emacs':
975 976 977 978
;;	(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>))
979 980
;;   or, use `ps-print-hook' (see section Hooks):
;;	(add-hook 'ps-print-hook
981 982 983
;;		  '(lambda ()
;;		     (or (assq 'Helvetica ps-font-info-database)
;;			 (setq ps-font-info-database (append ...)))))
984 985
;;
;; You can create new `mixed' font families like:
986 987 988
;;      (my-mixed-family
;;       (fonts (normal               . "Courier-Bold")
;;              (bold                 . "Helvetica")
989
;;              (italic               . "ZapfChancery-MediumItalic")
990 991 992 993 994 995
;;              (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))
996
;;
997 998 999
;; Now you can use your new font family with any size:
;;	(setq ps-font-family 'my-mixed-family)
;;
1000 1001 1002 1003 1004
;; 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.
1005 1006 1007 1008 1009 1010 1011 1012
;;
;; 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")
1013
;;              (italic               . "ZapfChancery-MediumItalic")
1014 1015 1016 1017 1018 1019 1020 1021
;;              (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.
;;
1022 1023 1024 1025
;; You can get information on all the fonts resident in YOUR printer
;; by uncommenting the line:
;;	% 3 cm 20 cm moveto  ReportAllFontInfo           showpage
;;
1026
;; The PostScript file should be sent to YOUR PostScript printer.
1027 1028
;; If you send it to ghostscript or to another PostScript printer, you may get
;; slightly different results.
1029 1030 1031 1032
;; 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.
1033 1034 1035 1036
;;
;;
;; How Ps-Print Deals With Faces
;; -----------------------------
1037
;;
1038 1039 1040 1041
;; 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.
1042
;;
1043 1044 1045
;; 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'.
1046 1047 1048
;; 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:
1049
;;
1050
;;      (setq ps-bold-faces '(my-blue-face))
1051
;;      (setq ps-italic-faces '(my-red-face))
1052
;;      (setq ps-underlined-faces '(my-green-face))
1053
;;
1054 1055
;; Faces like bold-italic that are both bold and italic should go in *both*
;; lists.
1056
;;
1057 1058 1059 1060
;; 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.
1061
;;
1062 1063 1064 1065 1066
;; 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
1067
;; `ps-always-build-face-reference' to t.
1068
;;
1069 1070 1071 1072 1073 1074 1075 1076 1077
;; 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.
1078
;; The default value is nil.
1079
;;
1080 1081 1082 1083
;;
;; How Ps-Print Deals With Color
;; -----------------------------
;;
1084 1085 1086 1087
;; 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'.
1088
;; On black/white printers, colors are displayed in gray scale.
1089
;; To turn off color output, set `ps-print-color-p' to nil.
1090 1091
;; 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.
1092 1093
;;
;;
1094 1095 1096
;; How Ps-Print Maps Faces
;; -----------------------
;;
1097 1098 1099
;; 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:
1100 1101 1102 1103 1104
;;
;;   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.
1105
;;   outline   - print characters as hollow outlines.
1106
;;
1107
;; See the documentation for `ps-extend-face'.
1108
;;
1109 1110
;; Let's, for example, remap `font-lock-keyword-face' to another foreground
;; color and bold attribute:
Richard M. Stallman's avatar