doc/help/options.html

   1 <HTML>
   2 <!-- SECTION: Getting Started -->
   3 <HEAD>
   4         <TITLE>Printing and Options</TITLE>
   5 </HEAD>
   6 <BODY>
   7
   8 <P>CUPS provides both the System V (<A
   9 HREF="man-lp.html">lp(1)</A>) and Berkeley (<A
  10 HREF="man-lpr.html">lpr(1)</A>) printing commands for printing
  11 files. In addition, it supported a large number of standard and
  12 printer-specific options that allow you to control how and where
  13 files are printed.</P>
  14
  15
  16 <H2 CLASS="title"><A NAME="BASICS">Printing Files</A></H2>
  17
  18 <P>CUPS understands many different types of files directly,
  19 including text, PostScript, PDF, and image files. This allows you
  20 to print from inside your applications or at the command-line,
  21 whichever is most convenient! Type either of the following
  22 commands to print a file to the default (or only) printer on the
  23 system:</P>
  24
  25 <PRE CLASS="command">
  26 lp filename
  27 lpr filename
  28 </PRE>
  29
  30 <H3><A NAME="PRINTER">Choosing a Printer</A></H3>
  31
  32 <P>Many systems will have more than one printer available to the
  33 user. These printers can be attached to the local system via a
  34 parallel, serial, or USB port, or available over the network. Use
  35 the <A HREF="man-lpstat.html">lpstat(1)</A> command to see a list
  36 of available printers:</P>
  37
  38 <PRE CLASS="command">
  39 lpstat -p -d
  40 </PRE>
  41
  42 <P>The <CODE>-p</CODE> option specifies that you want to see a
  43 list of printers, and the <CODE>-d</CODE> option reports the
  44 current default printer or class.</P>
  45
  46 <P>Use the <CODE>-d</CODE> option with the <B>lp</B> command to
  47 print to a specific printer:</P>
  48
  49 <PRE CLASS="command">
  50 lp -d printer filename
  51 </PRE>
  52
  53 <P>or the <CODE>-P</CODE> option with the <B>lpr</B> command:</P>
  54
  55 <PRE CLASS="command">
  56 lpr -P printer filename
  57 </PRE>
  58
  59 <H3><A NAME="DEFAULT">Setting the Default Printer</A></H3>
  60
  61 <P>If you normally use a particular printer, you can tell CUPS to
  62 use it by default using the <A
  63 HREF="man-lpoptions.html">lpoptions(1)</A> command:</P>
  64
  65 <PRE CLASS="command">
  66 lpoptions -d printer
  67 </PRE>
  68
  69 <H3><A NAME="PIPE">Printing the Output of a Program</A></H3>
  70
  71 <P>Both the <B>lp</B> and <B>lpr</B> commands support printing
  72 from the standard input:</P>
  73
  74 <PRE CLASS="command">
  75 program | lp
  76 program | lp -d printer
  77 program | lpr
  78 program | lpr -P printer
  79 </PRE>
  80
  81 <P>If the program does not provide any output, then nothing will
  82 be queued for printing.</P>
  83
  84 <H3><A NAME="WITHOPTIONS">Specifying Printer Options</A></H3>
  85
  86 <P>For many types of files, the default printer options may be
  87 sufficient for your needs. However, there may be times when you
  88 need to change the options for a particular file you are
  89 printing.</P>
  90
  91 <P>The <B>lp</B> and <B>lpr</B> commands allow you to pass
  92 printer options using the <CODE>-o</CODE> option:</P>
  93
  94 <PRE CLASS="command">
  95 lp -o landscape -o scaling=75 -o media=A4 filename.jpg
  96 lpr -o landscape -o scaling=75 -o media=A4 filename.jpg
  97 </PRE>
  98
  99 <P>The available printer options vary depending on the printer.
 100 The standard options are described in the "<A
 101 HREF="#OPTIONS">Standard Printing Options</A>" section
 102 below. Printer-specific options are also available and can be
 103 listed using the <B>lpoptions</B> command:</P>
 104
 105 <PRE CLASS="command">
 106 lpoptions -p printer -l
 107 </PRE>
 108
 109 <H3><A NAME="INSTANCES">Creating Saved Options</A></H3>
 110
 111 <P>Saved options are supported in CUPS through <em>printer
 112 instances</em>. Printer instances are, as their name implies, copies
 113 of a printer that have certain options associated with them. Use the
 114 <B>lpoptions</B> command to create a printer instance:</P>
 115
 116 <PRE CLASS="command">
 117 lpoptions -p printer/instance -o name=value ...
 118 </PRE>
 119
 120 <P>The <CODE>-p printer/instance</CODE> option provides the name of
 121 the instance, which is always the printer name, a slash, and the
 122 instance name which can contain any printable characters except
 123 space and slash. The remaining options are then associated with the
 124 instance instead of the main queue. For example, the following
 125 command creates a duplex instance of the LaserJet queue:</P>
 126
 127 <PRE CLASS="command">
 128 lpoptions -p LaserJet/duplex -o sides=two-sided-long-edge
 129 </PRE>
 130
 131 <P>Instances <em>do not</em> inherit lpoptions from the main
 132 queue.</P>
 133
 134 <H3><A NAME="COPIES">Printing Multiple Copies</A></H3>
 135
 136 <P>Both the <B>lp</B> and <B>lpr</B> commands have options for
 137 printing more than one copy of a file:</P>
 138
 139 <PRE CLASS="command">
 140 lp -n <I>num-copies</I> filename
 141 lpr -#<I>num-copies</I> filename
 142 </PRE>
 143
 144 <P>Copies are normally <EM>not</EM> collated for you. Use the
 145 <CODE>-o Collate=True</CODE> option to get collated copies:</P>
 146
 147 <PRE CLASS="command">
 148 lp -n <I>num-copies</I> -o Collate=True filename
 149 lpr -#<I>num-copies</I> -o Collate=True filename
 150 </PRE>
 151
 152
 153 <H2 CLASS="title"><A NAME="CANCEL">Canceling a Print Job</A></H2>
 154
 155 <P>The <A HREF="man-cancel.html">cancel(1)</A> and <A
 156 HREF="man-lprm.html">lprm(1)</A> commands cancel a print job:</P>
 157
 158 <PRE CLASS="command">
 159 cancel <I>job-id</I>
 160 lprm <I>job-id</I>
 161 </PRE>
 162
 163 <P>The <I>job-id</I> is the number that was reported to you by
 164 the <B>lp</B> command. You can also get the job ID using the <A
 165 HREF="man-lpq.html">lpq(1)</A> or <A
 166 HREF="man-lpstat.html">lpstat</A> commands:</P>
 167
 168 <PRE CLASS="command">
 169 lpq
 170 lpstat
 171 </PRE>
 172
 173
 174 <H2 CLASS="title"><A NAME="OPTIONS">Standard Printing Options</A></H2>
 175
 176 <P>The following options apply when printing all types of
 177 files.</P>
 178
 179 <H3><A NAME="MEDIA">Selecting the Media Size, Type, and Source</A></H3>
 180
 181 <P>The <CODE>-o media=xyz</CODE> option sets the media size,
 182 type, and/or source:</P>
 183
 184 <PRE CLASS="command">
 185 lp -o media=Letter filename
 186 lp -o media=Letter,MultiPurpose filename
 187 lpr -o media=Letter,Transparency filename
 188 lpr -o media=Letter,MultiPurpose,Transparency filename
 189 </PRE>
 190
 191 <P>The available media sizes, types, and sources depend on the
 192 printer, but most support the following options (case is not
 193 significant):</P>
 194
 195 <UL>
 196
 197         <LI><CODE>Letter</CODE> - US Letter (8.5x11 inches, or 216x279mm)
 198
 199         <LI><CODE>Legal</CODE> - US Legal (8.5x14 inches, or 216x356mm)
 200
 201         <LI><CODE>A4</CODE> - ISO A4 (8.27x11.69 inches, or 210x297mm)
 202
 203         <LI><CODE>COM10</CODE> - US #10 Envelope (9.5x4.125 inches, or
 204         241x105mm)
 205
 206         <LI><CODE>DL</CODE> - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)
 207
 208         <LI><CODE>Transparency</CODE> - Transparency media type or source
 209
 210         <LI><CODE>Upper</CODE> - Upper paper tray
 211
 212         <LI><CODE>Lower</CODE> - Lower paper tray
 213
 214         <LI><CODE>MultiPurpose</CODE> - Multi-purpose paper tray
 215
 216         <LI><CODE>LargeCapacity</CODE> - Large capacity paper tray
 217
 218 </UL>
 219
 220 <P>The actual options supported are defined in the printer's PPD
 221 file in the <CODE>PageSize</CODE>, <CODE>InputSlot</CODE>, and
 222 <CODE>MediaType</CODE> options. You can list them using the
 223 <B>lpoptions(1)</B> command:</P>
 224
 225 <PRE CLASS="command">
 226 lpoptions -p printer -l
 227 </PRE>
 228
 229 <P>When <CODE>Custom</CODE> is listed for the <CODE>PageSize</CODE> option, you can specify custom media sizes using one of the following forms:</P>
 230
 231 <PRE CLASS="command">
 232 lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I> filename
 233 lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I>in filename
 234 lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I>cm filename
 235 lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I>mm filename
 236 </PRE>
 237
 238 <P>where "WIDTH" and "LENGTH" are the width and length of the media in points, inches, centimeters, or millimeters, respectively.</P>
 239
 240
 241 <H3><A NAME="ORIENTATION">Setting the Orientation</A></H3>
 242
 243 <P>The <CODE>-o landscape</CODE> option will rotate the page 90
 244 degrees to print in landscape orientation:</P>
 245
 246 <PRE CLASS="command">
 247 lp -o landscape filename
 248 lpr -o landscape filename
 249 </PRE>
 250
 251 <P>The <CODE>-o orientation-requested=N</CODE> option rotates the
 252 page depending on the value of N:</P>
 253
 254 <UL>
 255
 256         <LI><CODE>-o orientation-requested=3</CODE> - portrait
 257         orientation (no rotation)</LI>
 258
 259         <LI><CODE>-o orientation-requested=4</CODE> - landscape
 260         orientation (90 degrees)</LI>
 261
 262         <LI><CODE>-o orientation-requested=5</CODE> - reverse
 263         landscape or seascape orientation (270 degrees)</LI>
 264
 265         <LI><CODE>-o orientation-requested=6</CODE> - reverse
 266         portrait or upside-down orientation (180 degrees)</LI>
 267
 268 </UL>
 269
 270 <H3><A NAME="SIDES">Printing On Both Sides of the Paper</A></H3>
 271
 272 <P>The <CODE>-o sides=two-sided-short-edge</CODE> and <CODE>-o
 273 sides=two-sided-long-edge</CODE> options will enable two-sided
 274 printing on the printer if the printer supports it. The <CODE>-o
 275 sides=two-sided-short-edge</CODE> option is suitable for
 276 landscape pages, while the <CODE>-o
 277 sides=two-sided-long-edge</CODE> option is suitable for portrait
 278 pages:</P>
 279
 280 <PRE CLASS="command">
 281 lp -o sides=two-sided-short-edge filename
 282 lp -o sides=two-sided-long-edge filename
 283 lpr -o sides=two-sided-long-edge filename
 284 </PRE>
 285
 286 <P>The default is to print single-sided:</P>
 287
 288 <PRE CLASS="command">
 289 lp -o sides=one-sided filename
 290 lpr -o sides=one-sided filename
 291 </PRE>
 292
 293 <H3><A NAME="JOBSHEETS">Selecting the Banner Page(s)</A></H3>
 294
 295 <P>The <CODE>-o jobsheets=start,end</CODE> option sets the banner
 296 page(s) to use for a job:</P>
 297
 298 <PRE CLASS="command">
 299 lp -o job-sheets=none filename
 300 lp -o job-sheets=standard filename
 301 lpr -o job-sheets=classified,classified filename
 302 </PRE>
 303
 304 <P>If only one banner file is specified, it will be printed
 305 before the files in the job. If a second banner file is
 306 specified, it is printed after the files in the job.</P>
 307
 308 <P>The available banner pages depend on the local system
 309 configuration; CUPS includes the following banner files:</P>
 310
 311 <UL>
 312
 313         <LI><CODE>none</CODE> - Do not produce a banner page.
 314
 315         <LI><CODE>classified</CODE> - A banner page with a "classified"
 316         label at the top and bottom.
 317
 318         <LI><CODE>confidential</CODE> - A banner page with a
 319         "confidential" label at the top and bottom.
 320
 321         <LI><CODE>secret</CODE> - A banner page with a "secret" label
 322         at the top and bottom.
 323
 324         <LI><CODE>standard</CODE> - A banner page with no label at the
 325         top and bottom.
 326
 327         <LI><CODE>topsecret</CODE> - A banner page with a "top secret"
 328         label at the top and bottom.
 329
 330         <LI><CODE>unclassified</CODE> - A banner page with an
 331         "unclassified" label at the top and bottom.
 332
 333 </UL>
 334
 335
 336 <H3><A NAME="OUTPUTORDER">Specifying the Output Order</A></H3>
 337
 338 <P>The <CODE>-o outputorder=normal</CODE> and <CODE>-o outputorder=reverse</CODE> options specify the order of the pages. Normal order prints page 1 first, page 2 second, and so forth. Reverse order prints page 1 last.</P>
 339
 340
 341 <H3><A NAME="PAGERANGES">Selecting a Range of Pages</A></H3>
 342
 343 <P>The <CODE>-o page-ranges=pages</CODE> option selects a range
 344 of pages for printing:</P>
 345
 346 <PRE CLASS="command">
 347 lp -o page-ranges=1 filename
 348 lp -o page-ranges=1-4 filename
 349 lp -o page-ranges=1-4,7,9-12 filename
 350 lpr -o page-ranges=1-4,7,9-12 filename
 351 </PRE>
 352
 353 <P>As shown above, the <CODE>pages</CODE> value can be a single page, a
 354 range of pages, or a collection of page numbers and ranges separated by
 355 commas. The pages will always be printed in ascending order, regardless
 356 of the order of the pages in the <CODE>page-ranges</CODE> option.
 357
 358 <P>The default is to print all pages.
 359
 360 <H3><A NAME="PAGESET">Selecting Even or Odd Pages</A></H3>
 361
 362 <P>Use the <CODE>-o page-set=set</CODE> option to select the even or odd pages:</P>
 363
 364 <PRE CLASS="command">
 365 lp -o page-set=odd filename
 366 lp -o page-set=even filename
 367 lpr -o page-set=even filename
 368 </PRE>
 369
 370 <P>The default is to print all pages.
 371
 372 <H3><A NAME="NUMBERUP">N-Up Printing</A></H3>
 373
 374 <P>The <CODE>-o number-up=value</CODE> option selects N-Up
 375 printing. N-Up printing places multiple document pages on a
 376 single printed page. CUPS supports 1, 2, 4, 6, 9, and 16-Up
 377 formats; the default format is 1-Up:</P>
 378
 379 <PRE CLASS="command">
 380 lp -o number-up=1 filename
 381 lp -o number-up=2 filename
 382 lp -o number-up=4 filename
 383 lpr -o number-up=16 filename
 384 </PRE>
 385
 386 <P>The <CODE>-o page-border=value</CODE> option chooses the
 387 border to draw around each page:</P>
 388
 389 <UL>
 390         <LI><CODE>-o page-border=double</CODE>; draw two hairline borders around each page</LI>
 391         <LI><CODE>-o page-border=double-thick</CODE>; draw two 1pt borders around each page</LI>
 392         <LI><CODE>-o page-border=none</CODE>; do not draw a border (default)</LI>
 393         <LI><CODE>-o page-border=single</CODE>; draw one hairline border around each page</LI>
 394         <LI><CODE>-o page-border=single-thick</CODE>; draw one 1pt border around each page</LI>
 395 </UL>
 396
 397 <P>The <CODE>-o number-up-layout=value</CODE> option chooses the
 398 layout of the pages on each output page:</P>
 399
 400 <UL>
 401         <LI><CODE>-o number-up-layout=btlr</CODE>; Bottom to top, left to right</LI>
 402         <LI><CODE>-o number-up-layout=btrl</CODE>; Bottom to top, right to left</LI>
 403         <LI><CODE>-o number-up-layout=lrbt</CODE>; Left to right, bottom to top</LI>
 404         <LI><CODE>-o number-up-layout=lrtb</CODE>; Left to right, top to bottom (default)</LI>
 405         <LI><CODE>-o number-up-layout=rlbt</CODE>; Right to left, bottom to top</LI>
 406         <LI><CODE>-o number-up-layout=rltb</CODE>; Right to left, top to bottom</LI>
 407         <LI><CODE>-o number-up-layout=tblr</CODE>; Top to bottom, left to right</LI>
 408         <LI><CODE>-o number-up-layout=tbrl</CODE>; Top to bottom, right to left</LI>
 409 </UL>
 410
 411 <H3><A NAME="FITPLOT">Scaling to Fit</A></H3>
 412
 413 <P>The <CODE>-o fitplot</CODE> option specifies that the document
 414 should be scaled to fit on the page:</P>
 415
 416 <PRE CLASS="command">
 417 lp -o fitplot filename
 418 lpr -o fitplot filename
 419 </PRE>
 420
 421 <P>The default is to use the size specified in the file.</P>
 422
 423 <BLOCKQUOTE>Note: This feature depends upon an accurate size in
 424 the print file. If no size is given in the file, the page may be
 425 scaled incorrectly!</BLOCKQUOTE>
 426
 427 <H3><A NAME="RAW">Raw or Unfiltered Output</A></H3>
 428
 429 <P>The <CODE>-o raw</CODE> option allows you to send files
 430 directly to a printer without filtering. This is sometimes
 431 required when printing from applications that provide their own
 432 "printer drivers" for your printer:</P>
 433
 434 <PRE CLASS="command">
 435 lp -o raw filename
 436 lpr -o raw filename
 437 </PRE>
 438
 439 <P>The <CODE>-l</CODE> option can also be used with the
 440 <B>lpr</B> command to send files directly to a printer:</P>
 441
 442 <PRE CLASS="command">
 443 lpr -l filename
 444 </PRE>
 445
 446
 447 <H2 CLASS="title"><A NAME="TEXTOPTIONS">Text Options</A></H2>
 448
 449 <P>CUPS supports several options that are only used when printing
 450 plain text files. These options have absolutely no effect on
 451 PostScript, PDF, HP-GL/2, or image files.</P>
 452
 453 <H3><A NAME="CPI">Setting the Number of Characters Per Inch</A></H3>
 454
 455 <P>The <CODE>-o cpi=value</CODE> option sets the number of
 456 characters per inch:</P>
 457
 458 <PRE CLASS="command">
 459 lp -o cpi=10 filename
 460 lp -o cpi=12 filename
 461 lpr -o cpi=17 filename
 462 </PRE>
 463
 464 <P>The default characters per inch is 10.</P>
 465
 466 <H3><A NAME="LPI">Setting the Number of Lines Per Inch</A></H3>
 467
 468 <P>The <CODE>-o lpi=value</CODE> option sets the number of lines
 469 per inch:</P>
 470
 471 <PRE CLASS="command">
 472 lp -o lpi=6 filename
 473 lpr -o lpi=8 filename
 474 </PRE>
 475
 476 <P>The default lines per inch is 6.</P>
 477
 478 <H3><A NAME="COLUMNS">Setting the Number of Columns</A></H3>
 479
 480 <P>The <CODE>-o columns=value</CODE> option sets the number of
 481 text columns:</P>
 482
 483 <PRE CLASS="command">
 484 lp -o columns=2 filename
 485 lpr -o columns=3 filename
 486 </PRE>
 487
 488 <P>The default number of columns is 1.</P>
 489
 490 <H3><A NAME="MARGINS">Setting the Page Margins</A></H3>
 491
 492 <P>Normally the page margins are set to the hard limits of the
 493 printer. Use the <CODE>-o page-left=value</CODE>, <CODE>-o
 494 page-right=value</CODE>, <CODE>-o page-top=value</CODE>, and
 495 <CODE>-o page-bottom=value</CODE> options to adjust the page
 496 margins:</P>
 497
 498 <PRE CLASS="command">
 499 lp -o page-left=<I>value</I> filename
 500 lp -o page-right=<I>value</I> filename
 501 lp -o page-top=<I>value</I> filename
 502 lp -o page-bottom=<I>value</I> filename
 503 lpr -o page-left=<I>value</I> -o page-right=<I>value</I> -o page-top=<I>value</I> -o page-bottom=<I>value</I> filename
 504 </PRE>
 505
 506 <P>The <CODE>value</CODE> argument is the margin in points; each
 507 point is 1/72 inch or 0.35mm.</P>
 508
 509 <H3><A NAME="PRETTYPRINT">Pretty Printing</A></H3>
 510
 511 <P>The <CODE>-o prettyprint</CODE> option puts a header at the
 512 top of each page with the page number, job title (usually the
 513 filename), and the date. Also, C and C++ keywords are
 514 highlighted, and comment lines are italicized:</P>
 515
 516 <PRE CLASS="command">
 517 lp -o prettyprint filename
 518 lpr -o prettyprint filename
 519 </PRE>
 520
 521 </BODY>
 522 </HTML>