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.</P>
 103
 104 <H3><A NAME="COPIES">Printing Multiple Copies</A></H3>
 105
 106 <P>Both the <B>lp</B> and <B>lpr</B> commands have options for
 107 printing more than one copy of a file:</P>
 108
 109 <PRE CLASS="command">
 110 lp -n <I>num-copies</I> filename
 111 lpr -#<I>num-copies</I> filename
 112 </PRE>
 113
 114 <P>Copies are normally <EM>not</EM> collated for you. Use the
 115 <CODE>-o Collate=True</CODE> option to get collated copies:</P>
 116
 117 <PRE CLASS="command">
 118 lp -n <I>num-copies</I> -o Collate=True filename
 119 lpr -#<I>num-copies</I> -o Collate=True filename
 120 </PRE>
 121
 122
 123 <H2 CLASS="title"><A NAME="CANCEL">Canceling a Print Job</A></H2>
 124
 125 <P>The <A HREF="man-cancel.html">cancel(1)</A> and <A
 126 HREF="man-lprm.html">lprm(1)</A> commands cancel a print job:</P>
 127
 128 <PRE CLASS="command">
 129 cancel <I>job-id</I>
 130 lprm <I>job-id</I>
 131 </PRE>
 132
 133 <P>The <I>job-id</I> is the number that was reported to you by
 134 the <B>lp</B> command. You can also get the job ID using the <A
 135 HREF="man-lpq.html">lpq(1)</A> or <A
 136 HREF="man-lpstat.html">lpstat</A> commands:</P>
 137
 138 <PRE CLASS="command">
 139 lpq
 140 lpstat
 141 </PRE>
 142
 143
 144 <H2 CLASS="title"><A NAME="OPTIONS">Standard Printing Options</A></H2>
 145
 146 <P>The following options apply when printing all types of
 147 files.</P>
 148
 149 <H3><A NAME="MEDIA">Selecting the Media Size, Type, and Source</A></H3>
 150
 151 <P>The <CODE>-o media=xyz</CODE> option sets the media size,
 152 type, and/or source:</P>
 153
 154 <PRE CLASS="command">
 155 lp -o media=Letter filename
 156 lp -o media=Letter,MultiPurpose filename
 157 lpr -o media=Letter,Transparency filename
 158 lpr -o media=Letter,MultiPurpose,Transparency filename
 159 </PRE>
 160
 161 <P>The available media sizes, types, and sources depend on the
 162 printer, but most support the following options (case is not
 163 significant):</P>
 164
 165 <UL>
 166
 167         <LI><CODE>Letter</CODE> - US Letter (8.5x11 inches, or 216x279mm)
 168
 169         <LI><CODE>Legal</CODE> - US Legal (8.5x14 inches, or 216x356mm)
 170
 171         <LI><CODE>A4</CODE> - ISO A4 (8.27x11.69 inches, or 210x297mm)
 172
 173         <LI><CODE>COM10</CODE> - US #10 Envelope (9.5x4.125 inches, or
 174         241x105mm)
 175
 176         <LI><CODE>DL</CODE> - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)
 177
 178         <LI><CODE>Transparency</CODE> - Transparency media type or source
 179
 180         <LI><CODE>Upper</CODE> - Upper paper tray
 181
 182         <LI><CODE>Lower</CODE> - Lower paper tray
 183
 184         <LI><CODE>MultiPurpose</CODE> - Multi-purpose paper tray
 185
 186         <LI><CODE>LargeCapacity</CODE> - Large capacity paper tray
 187
 188 </UL>
 189
 190 <P>The actual options supported are defined in the printer's PPD
 191 file in the <CODE>PageSize</CODE>, <CODE>InputSlot</CODE>, and
 192 <CODE>MediaType</CODE> options. You can list them using the
 193 <B>lpoptions(1)</B> command:</P>
 194
 195 <PRE CLASS="command">
 196 lpoptions -p printer -l
 197 </PRE>
 198
 199 <H3><A NAME="ORIENTATION">Setting the Orientation</A></H3>
 200
 201 <P>The <CODE>-o landscape</CODE> option will rotate the page 90
 202 degrees to print in landscape orientation:</P>
 203
 204 <PRE CLASS="command">
 205 lp -o landscape filename
 206 lpr -o landscape filename
 207 </PRE>
 208
 209 <P>The <CODE>-o orientation-requested=N</CODE> option rotates the
 210 page depending on the value of N:</P>
 211
 212 <UL>
 213
 214         <LI><CODE>-o orientation-requested=3</CODE> - portrait
 215         orientation (no rotation)</LI>
 216
 217         <LI><CODE>-o orientation-requested=4</CODE> - landscape
 218         orientation (90 degrees)</LI>
 219
 220         <LI><CODE>-o orientation-requested=5</CODE> - reverse
 221         landscape or seascape orientation (270 degrees)</LI>
 222
 223         <LI><CODE>-o orientation-requested=6</CODE> - reverse
 224         portrait or upside-down orientation (180 degrees)</LI>
 225
 226 </UL>
 227
 228 <H3><A NAME="SIDES">Printing On Both Sides of the Paper</A></H3>
 229
 230 <P>The <CODE>-o sides=two-sided-short-edge</CODE> and <CODE>-o
 231 sides=two-sided-long-edge</CODE> options will enable two-sided
 232 printing on the printer if the printer supports it. The <CODE>-o
 233 sides=two-sided-short-edge</CODE> option is suitable for
 234 landscape pages, while the <CODE>-o
 235 sides=two-sided-long-edge</CODE> option is suitable for portrait
 236 pages:</P>
 237
 238 <PRE CLASS="command">
 239 lp -o sides=two-sided-short-edge filename
 240 lp -o sides=two-sided-long-edge filename
 241 lpr -o sides=two-sided-long-edge filename
 242 </PRE>
 243
 244 <P>The default is to print single-sided:</P>
 245
 246 <PRE CLASS="command">
 247 lp -o sides=one-sided filename
 248 lpr -o sides=one-sided filename
 249 </PRE>
 250
 251 <H3><A NAME="JOBSHEETS">Selecting the Banner Page(s)</A></H3>
 252
 253 <P>The <CODE>-o jobsheets=start,end</CODE> option sets the banner
 254 page(s) to use for a job:</P>
 255
 256 <PRE CLASS="command">
 257 lp -o job-sheets=none filename
 258 lp -o job-sheets=standard filename
 259 lpr -o job-sheets=classified,classified filename
 260 </PRE>
 261
 262 <P>If only one banner file is specified, it will be printed
 263 before the files in the job. If a second banner file is
 264 specified, it is printed after the files in the job.</P>
 265
 266 <P>The available banner pages depend on the local system
 267 configuration; CUPS includes the following banner files:</P>
 268
 269 <UL>
 270
 271         <LI><CODE>none</CODE> - Do not produce a banner page.
 272
 273         <LI><CODE>classified</CODE> - A banner page with a "classified"
 274         label at the top and bottom.
 275
 276         <LI><CODE>confidential</CODE> - A banner page with a
 277         "confidential" label at the top and bottom.
 278
 279         <LI><CODE>secret</CODE> - A banner page with a "secret" label
 280         at the top and bottom.
 281
 282         <LI><CODE>standard</CODE> - A banner page with no label at the
 283         top and bottom.
 284
 285         <LI><CODE>topsecret</CODE> - A banner page with a "top secret"
 286         label at the top and bottom.
 287
 288         <LI><CODE>unclassified</CODE> - A banner page with an
 289         "unclassified" label at the top and bottom.
 290
 291 </UL>
 292
 293 <H3><A NAME="PAGERANGES">Selecting a Range of Pages</A></H3>
 294
 295 <P>The <CODE>-o page-ranges=pages</CODE> option selects a range
 296 of pages for printing:</P>
 297
 298 <PRE CLASS="command">
 299 lp -o page-ranges=1 filename
 300 lp -o page-ranges=1-4 filename
 301 lp -o page-ranges=1-4,7,9-12 filename
 302 lpr -o page-ranges=1-4,7,9-12 filename
 303 </PRE>
 304
 305 <P>As shown above, the <CODE>pages</CODE> value can be a single page, a
 306 range of pages, or a collection of page numbers and ranges separated by
 307 commas. The pages will always be printed in ascending order, regardless
 308 of the order of the pages in the <CODE>page-ranges</CODE> option.
 309
 310 <P>The default is to print all pages.
 311
 312 <H3><A NAME="PAGESET">Selecting Even or Odd Pages</A></H3>
 313
 314 <P>Use the <CODE>-o page-set=set</CODE> option to select the even or odd pages:</P>
 315
 316 <PRE CLASS="command">
 317 lp -o page-set=odd filename
 318 lp -o page-set=even filename
 319 lpr -o page-set=even filename
 320 </PRE>
 321
 322 <P>The default is to print all pages.
 323
 324 <H3><A NAME="NUMBERUP">N-Up Printing</A></H3>
 325
 326 <P>The <CODE>-o number-up=value</CODE> option selects N-Up
 327 printing. N-Up printing places multiple document pages on a
 328 single printed page. CUPS supports 1, 2, 4, 6, 9, and 16-Up
 329 formats; the default format is 1-Up:</P>
 330
 331 <PRE CLASS="command">
 332 lp -o number-up=1 filename
 333 lp -o number-up=2 filename
 334 lp -o number-up=4 filename
 335 lpr -o number-up=16 filename
 336 </PRE>
 337
 338 <P>The <CODE>-o page-border=value</CODE> option chooses the
 339 border to draw around each page:</P>
 340
 341 <UL>
 342         <LI><CODE>-o page-border=double</CODE>; draw two hairline borders around each page</LI>
 343         <LI><CODE>-o page-border=double-thick</CODE>; draw two 1pt borders around each page</LI>
 344         <LI><CODE>-o page-border=none</CODE>; do not draw a border (default)</LI>
 345         <LI><CODE>-o page-border=single</CODE>; draw one hairline border around each page</LI>
 346         <LI><CODE>-o page-border=single-thick</CODE>; draw one 1pt border around each page</LI>
 347 </UL>
 348
 349 <P>The <CODE>-o number-up-layout=value</CODE> option chooses the
 350 layout of the pages on each output page:</P>
 351
 352 <UL>
 353         <LI><CODE>-o number-up-layout=btlr</CODE>; Bottom to top, left to right</LI>
 354         <LI><CODE>-o number-up-layout=btrl</CODE>; Bottom to top, right to left</LI>
 355         <LI><CODE>-o number-up-layout=lrbt</CODE>; Left to right, bottom to top</LI>
 356         <LI><CODE>-o number-up-layout=lrtb</CODE>; Left to right, top to bottom (default)</LI>
 357         <LI><CODE>-o number-up-layout=rlbt</CODE>; Right to left, bottom to top</LI>
 358         <LI><CODE>-o number-up-layout=rltb</CODE>; Right to left, top to bottom</LI>
 359         <LI><CODE>-o number-up-layout=tblr</CODE>; Top to bottom, left to right</LI>
 360         <LI><CODE>-o number-up-layout=tbrl</CODE>; Top to bottom, right to left</LI>
 361 </UL>
 362
 363 <H3><A NAME="FITPLOT">Scaling to Fit</A></H3>
 364
 365 <P>The <CODE>-o fitplot</CODE> option specifies that the document
 366 should be scaled to fit on the page:</P>
 367
 368 <PRE CLASS="command">
 369 lp -o fitplot filename
 370 lpr -o fitplot filename
 371 </PRE>
 372
 373 <P>The default is to use the size specified in the file.</P>
 374
 375 <BLOCKQUOTE>Note: This feature depends upon an accurate size in
 376 the print file. If no size is given in the file, the page may be
 377 scaled incorrectly!</BLOCKQUOTE>
 378
 379 <H3><A NAME="RAW">Raw or Unfiltered Output</A></H3>
 380
 381 <P>The <CODE>-o raw</CODE> option allows you to send files
 382 directly to a printer without filtering. This is sometimes
 383 required when printing from applications that provide their own
 384 "printer drivers" for your printer:</P>
 385
 386 <PRE CLASS="command">
 387 lp -o raw filename
 388 lpr -o raw filename
 389 </PRE>
 390
 391 <P>The <CODE>-l</CODE> option can also be used with the
 392 <B>lpr</B> command to send files directly to a printer:</P>
 393
 394 <PRE CLASS="command">
 395 lpr -l filename
 396 </PRE>
 397
 398
 399 <H2 CLASS="title"><A NAME="TEXTOPTIONS">Text Options</A></H2>
 400
 401 <P>CUPS supports several options that are only used when printing
 402 plain text files. These options have absolutely no effect on
 403 PostScript, PDF, HP-GL/2, or image files.</P>
 404
 405 <H3><A NAME="CPI">Setting the Number of Characters Per Inch</A></H3>
 406
 407 <P>The <CODE>-o cpi=value</CODE> option sets the number of
 408 characters per inch:</P>
 409
 410 <PRE CLASS="command">
 411 lp -o cpi=10 filename
 412 lp -o cpi=12 filename
 413 lpr -o cpi=17 filename
 414 </PRE>
 415
 416 <P>The default characters per inch is 10.</P>
 417
 418 <H3><A NAME="LPI">Setting the Number of Lines Per Inch</A></H3>
 419
 420 <P>The <CODE>-o lpi=value</CODE> option sets the number of lines
 421 per inch:</P>
 422
 423 <PRE CLASS="command">
 424 lp -o lpi=6 filename
 425 lpr -o lpi=8 filename
 426 </PRE>
 427
 428 <P>The default lines per inch is 6.</P>
 429
 430 <H3><A NAME="COLUMNS">Setting the Number of Columns</A></H3>
 431
 432 <P>The <CODE>-o columns=value</CODE> option sets the number of
 433 text columns:</P>
 434
 435 <PRE CLASS="command">
 436 lp -o columns=2 filename
 437 lpr -o columns=3 filename
 438 </PRE>
 439
 440 <P>The default number of columns is 1.</P>
 441
 442 <H3><A NAME="MARGINS">Setting the Page Margins</A></H3>
 443
 444 <P>Normally the page margins are set to the hard limits of the
 445 printer. Use the <CODE>-o page-left=value</CODE>, <CODE>-o
 446 page-right=value</CODE>, <CODE>-o page-top=value</CODE>, and
 447 <CODE>-o page-bottom=value</CODE> options to adjust the page
 448 margins:</P>
 449
 450 <PRE CLASS="command">
 451 lp -o page-left=<I>value</I> filename
 452 lp -o page-right=<I>value</I> filename
 453 lp -o page-top=<I>value</I> filename
 454 lp -o page-bottom=<I>value</I> filename
 455 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
 456 </PRE>
 457
 458 <P>The <CODE>value</CODE> argument is the margin in points; each
 459 point is 1/72 inch or 0.35mm.</P>
 460
 461 <H3><A NAME="PRETTYPRINT">Pretty Printing</A></H3>
 462
 463 <P>The <CODE>-o prettyprint</CODE> option puts a header at the
 464 top of each page with the page number, job title (usually the
 465 filename), and the date. Also, C and C++ keywords are
 466 highlighted, and comment lines are italicized:</P>
 467
 468 <PRE CLASS="command">
 469 lp -o prettyprint filename
 470 lpr -o prettyprint filename
 471 </PRE>
 472
 473 </BODY>
 474 </HTML>