ps-print.el 222 KB
Newer Older
Mark Oteiza's avatar
Mark Oteiza committed
1
;;; ps-print.el --- print text from the buffer as PostScript -*- lexical-binding: t -*-
2

Paul Eggert's avatar
Paul Eggert committed
3
;; Copyright (C) 1993-2019 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>)
viniciusjl's avatar
viniciusjl committed
7
;;	Vinicius Jose Latorre <viniciusjl.gnu@gmail.com>
8
;;	Kenichi Handa <handa@gnu.org> (multi-byte characters)
9
;; Maintainer: Vinicius Jose Latorre <viniciusjl.gnu@gmail.com>
Pavel Janík's avatar
Pavel Janík committed
10
;; Keywords: wp, print, PostScript
11
;; Version: 7.3.5
Vinicius Jose Latorre's avatar
Vinicius Jose Latorre committed
12
;; X-URL: http://www.emacswiki.org/cgi-bin/wiki/ViniciusJoseLatorre
Kenichi Handa's avatar
Kenichi Handa committed
13

14 15
(eval-when-compile (require 'cl-lib))

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

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

Please send all bug fixes and enhancements to
viniciusjl's avatar
viniciusjl committed
24
	bug-gnu-emacs@gnu.org and Vinicius Jose Latorre <viniciusjl.gnu@gmail.com>.")
Richard M. Stallman's avatar
Richard M. Stallman committed
25

Richard M. Stallman's avatar
Richard M. Stallman committed
26
;; This file is part of GNU Emacs.
Richard M. Stallman's avatar
Richard M. Stallman committed
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
39
;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
Richard M. Stallman's avatar
Richard M. Stallman committed
40

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

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