[thirdparty/cups.git] / doc / help / options.html

<HTML>
<!-- SECTION: Getting Started -->
<HEAD>
	<TITLE>Printing and Options</TITLE>
</HEAD>
<BODY>

<P>CUPS provides both the System V (<A
HREF="man-lp.html">lp(1)</A>) and Berkeley (<A
HREF="man-lpr.html">lpr(1)</A>) printing commands for printing
files. In addition, it supported a large number of standard and
printer-specific options that allow you to control how and where
files are printed.</P>


<H2 CLASS="title"><A NAME="BASICS">Printing Files</A></H2>

<P>CUPS understands many different types of files directly,
including text, PostScript, PDF, and image files. This allows you
to print from inside your applications or at the command-line,
whichever is most convenient! Type either of the following
commands to print a file to the default (or only) printer on the
system:</P>

<PRE CLASS="command">
lp filename
lpr filename
</PRE>

<H3><A NAME="PRINTER">Choosing a Printer</A></H3>

<P>Many systems will have more than one printer available to the
user. These printers can be attached to the local system via a
parallel, serial, or USB port, or available over the network. Use
the <A HREF="man-lpstat.html">lpstat(1)</A> command to see a list
of available printers:</P>

<PRE CLASS="command">
lpstat -p -d
</PRE>

<P>The <CODE>-p</CODE> option specifies that you want to see a
list of printers, and the <CODE>-d</CODE> option reports the
current default printer or class.</P>

<P>Use the <CODE>-d</CODE> option with the <B>lp</B> command to
print to a specific printer:</P>

<PRE CLASS="command">
lp -d printer filename
</PRE>

<P>or the <CODE>-P</CODE> option with the <B>lpr</B> command:</P>

<PRE CLASS="command">
lpr -P printer filename
</PRE>

<H3><A NAME="DEFAULT">Setting the Default Printer</A></H3>

<P>If you normally use a particular printer, you can tell CUPS to
use it by default using the <A
HREF="man-lpoptions.html">lpoptions(1)</A> command:</P>

<PRE CLASS="command">
lpoptions -d printer
</PRE>

<H3><A NAME="PIPE">Printing the Output of a Program</A></H3>

<P>Both the <B>lp</B> and <B>lpr</B> commands support printing
from the standard input:</P>

<PRE CLASS="command">
program | lp
program | lp -d printer
program | lpr
program | lpr -P printer
</PRE>

<P>If the program does not provide any output, then nothing will
be queued for printing.</P>

<H3><A NAME="WITHOPTIONS">Specifying Printer Options</A></H3>

<P>For many types of files, the default printer options may be
sufficient for your needs. However, there may be times when you
need to change the options for a particular file you are
printing.</P>

<P>The <B>lp</B> and <B>lpr</B> commands allow you to pass
printer options using the <CODE>-o</CODE> option:</P>

<PRE CLASS="command">
lp -o landscape -o scaling=75 -o media=A4 filename.jpg
lpr -o landscape -o scaling=75 -o media=A4 filename.jpg
</PRE>

<P>The available printer options vary depending on the printer.
The standard options are described in the "<A
HREF="#OPTIONS">Standard Printing Options</A>" section
below. Printer-specific options are also available and can be
listed using the <B>lpoptions</B> command:</P>

<PRE CLASS="command">
lpoptions -p printer -l
</PRE>

<H3><A NAME="INSTANCES">Creating Saved Options</A></H3>

<P>Saved options are supported in CUPS through <em>printer
instances</em>. Printer instances are, as their name implies, copies
of a printer that have certain options associated with them. Use the
<B>lpoptions</B> command to create a printer instance:</P>

<PRE CLASS="command">
lpoptions -p printer/instance -o name=value ...
</PRE>

<P>The <CODE>-p printer/instance</CODE> option provides the name of
the instance, which is always the printer name, a slash, and the
instance name which can contain any printable characters except
space and slash. The remaining options are then associated with the
instance instead of the main queue. For example, the following
command creates a duplex instance of the LaserJet queue:</P>

<PRE CLASS="command">
lpoptions -p LaserJet/duplex -o sides=two-sided-long-edge
</PRE>

<P>Instances <em>do not</em> inherit lpoptions from the main
queue.</P>

<H3><A NAME="COPIES">Printing Multiple Copies</A></H3>

<P>Both the <B>lp</B> and <B>lpr</B> commands have options for
printing more than one copy of a file:</P>

<PRE CLASS="command">
lp -n <I>num-copies</I> filename
lpr -#<I>num-copies</I> filename
</PRE>

<P>Copies are normally <EM>not</EM> collated for you. Use the
<CODE>-o Collate=True</CODE> option to get collated copies:</P>

<PRE CLASS="command">
lp -n <I>num-copies</I> -o Collate=True filename
lpr -#<I>num-copies</I> -o Collate=True filename
</PRE>


<H2 CLASS="title"><A NAME="CANCEL">Canceling a Print Job</A></H2>

<P>The <A HREF="man-cancel.html">cancel(1)</A> and <A
HREF="man-lprm.html">lprm(1)</A> commands cancel a print job:</P>

<PRE CLASS="command">
cancel <I>job-id</I>
lprm <I>job-id</I>
</PRE>

<P>The <I>job-id</I> is the number that was reported to you by
the <B>lp</B> command. You can also get the job ID using the <A
HREF="man-lpq.html">lpq(1)</A> or <A
HREF="man-lpstat.html">lpstat</A> commands:</P>

<PRE CLASS="command">
lpq
lpstat
</PRE>


<H2 CLASS="title"><A NAME="OPTIONS">Standard Printing Options</A></H2>

<P>The following options apply when printing all types of
files.</P>

<H3><A NAME="MEDIA">Selecting the Media Size, Type, and Source</A></H3>

<P>The <CODE>-o media=xyz</CODE> option sets the media size,
type, and/or source:</P>

<PRE CLASS="command">
lp -o media=Letter filename
lp -o media=Letter,MultiPurpose filename
lpr -o media=Letter,Transparency filename
lpr -o media=Letter,MultiPurpose,Transparency filename
</PRE>

<P>The available media sizes, types, and sources depend on the
printer, but most support the following options (case is not
significant):</P>

<UL>

	<LI><CODE>Letter</CODE> - US Letter (8.5x11 inches, or 216x279mm)

	<LI><CODE>Legal</CODE> - US Legal (8.5x14 inches, or 216x356mm)

	<LI><CODE>A4</CODE> - ISO A4 (8.27x11.69 inches, or 210x297mm)

	<LI><CODE>COM10</CODE> - US #10 Envelope (9.5x4.125 inches, or
	241x105mm)

	<LI><CODE>DL</CODE> - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)

	<LI><CODE>Transparency</CODE> - Transparency media type or source

	<LI><CODE>Upper</CODE> - Upper paper tray

	<LI><CODE>Lower</CODE> - Lower paper tray

	<LI><CODE>MultiPurpose</CODE> - Multi-purpose paper tray

	<LI><CODE>LargeCapacity</CODE> - Large capacity paper tray

</UL>

<P>The actual options supported are defined in the printer's PPD
file in the <CODE>PageSize</CODE>, <CODE>InputSlot</CODE>, and
<CODE>MediaType</CODE> options. You can list them using the
<B>lpoptions(1)</B> command:</P>

<PRE CLASS="command">
lpoptions -p printer -l
</PRE>

<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>

<PRE CLASS="command">
lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I> filename
lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I>in filename
lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I>cm filename
lp -o media=Custom.<I>WIDTH</I>x<I>LENGTH</I>mm filename
</PRE>

<P>where "WIDTH" and "LENGTH" are the width and length of the media in points, inches, centimeters, or millimeters, respectively.</P>


<H3><A NAME="ORIENTATION">Setting the Orientation</A></H3>

<P>The <CODE>-o landscape</CODE> option will rotate the page 90
degrees to print in landscape orientation:</P>

<PRE CLASS="command">
lp -o landscape filename
lpr -o landscape filename
</PRE>

<P>The <CODE>-o orientation-requested=N</CODE> option rotates the
page depending on the value of N:</P>

<UL>

	<LI><CODE>-o orientation-requested=3</CODE> - portrait
	orientation (no rotation)</LI>

	<LI><CODE>-o orientation-requested=4</CODE> - landscape
	orientation (90 degrees)</LI>

	<LI><CODE>-o orientation-requested=5</CODE> - reverse
	landscape or seascape orientation (270 degrees)</LI>

	<LI><CODE>-o orientation-requested=6</CODE> - reverse
	portrait or upside-down orientation (180 degrees)</LI>

</UL>

<H3><A NAME="SIDES">Printing On Both Sides of the Paper</A></H3>

<P>The <CODE>-o sides=two-sided-short-edge</CODE> and <CODE>-o
sides=two-sided-long-edge</CODE> options will enable two-sided
printing on the printer if the printer supports it. The <CODE>-o
sides=two-sided-short-edge</CODE> option is suitable for
landscape pages, while the <CODE>-o
sides=two-sided-long-edge</CODE> option is suitable for portrait
pages:</P>

<PRE CLASS="command">
lp -o sides=two-sided-short-edge filename
lp -o sides=two-sided-long-edge filename
lpr -o sides=two-sided-long-edge filename
</PRE>

<P>The default is to print single-sided:</P>

<PRE CLASS="command">
lp -o sides=one-sided filename
lpr -o sides=one-sided filename
</PRE>

<H3><A NAME="JOBSHEETS">Selecting the Banner Page(s)</A></H3>

<P>The <CODE>-o jobsheets=start,end</CODE> option sets the banner
page(s) to use for a job:</P>

<PRE CLASS="command">
lp -o job-sheets=none filename
lp -o job-sheets=standard filename
lpr -o job-sheets=classified,classified filename
</PRE>

<P>If only one banner file is specified, it will be printed
before the files in the job. If a second banner file is
specified, it is printed after the files in the job.</P>

<P>The available banner pages depend on the local system
configuration; CUPS includes the following banner files:</P>

<UL>

	<LI><CODE>none</CODE> - Do not produce a banner page.

	<LI><CODE>classified</CODE> - A banner page with a "classified"
	label at the top and bottom.

	<LI><CODE>confidential</CODE> - A banner page with a
	"confidential" label at the top and bottom.

	<LI><CODE>secret</CODE> - A banner page with a "secret" label
	at the top and bottom.

	<LI><CODE>standard</CODE> - A banner page with no label at the
	top and bottom.

	<LI><CODE>topsecret</CODE> - A banner page with a "top secret"
	label at the top and bottom.

	<LI><CODE>unclassified</CODE> - A banner page with an
	"unclassified" label at the top and bottom.

</UL>


<H3><A NAME="OUTPUTORDER">Specifying the Output Order</A></H3>

<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>


<H3><A NAME="PAGERANGES">Selecting a Range of Pages</A></H3>

<P>The <CODE>-o page-ranges=pages</CODE> option selects a range
of pages for printing:</P>

<PRE CLASS="command">
lp -o page-ranges=1 filename
lp -o page-ranges=1-4 filename
lp -o page-ranges=1-4,7,9-12 filename
lpr -o page-ranges=1-4,7,9-12 filename
</PRE>

<P>As shown above, the <CODE>pages</CODE> value can be a single page, a
range of pages, or a collection of page numbers and ranges separated by
commas. The pages will always be printed in ascending order, regardless
of the order of the pages in the <CODE>page-ranges</CODE> option.

<P>The default is to print all pages.

<H3><A NAME="PAGESET">Selecting Even or Odd Pages</A></H3>

<P>Use the <CODE>-o page-set=set</CODE> option to select the even or odd pages:</P>

<PRE CLASS="command">
lp -o page-set=odd filename
lp -o page-set=even filename
lpr -o page-set=even filename
</PRE>

<P>The default is to print all pages.

<H3><A NAME="NUMBERUP">N-Up Printing</A></H3>

<P>The <CODE>-o number-up=value</CODE> option selects N-Up
printing. N-Up printing places multiple document pages on a
single printed page. CUPS supports 1, 2, 4, 6, 9, and 16-Up
formats; the default format is 1-Up:</P>

<PRE CLASS="command">
lp -o number-up=1 filename
lp -o number-up=2 filename
lp -o number-up=4 filename
lpr -o number-up=16 filename
</PRE>

<P>The <CODE>-o page-border=value</CODE> option chooses the
border to draw around each page:</P>

<UL>
	<LI><CODE>-o page-border=double</CODE>; draw two hairline borders around each page</LI>
	<LI><CODE>-o page-border=double-thick</CODE>; draw two 1pt borders around each page</LI>
	<LI><CODE>-o page-border=none</CODE>; do not draw a border (default)</LI>
	<LI><CODE>-o page-border=single</CODE>; draw one hairline border around each page</LI>
	<LI><CODE>-o page-border=single-thick</CODE>; draw one 1pt border around each page</LI>
</UL>

<P>The <CODE>-o number-up-layout=value</CODE> option chooses the
layout of the pages on each output page:</P>

<UL>
	<LI><CODE>-o number-up-layout=btlr</CODE>; Bottom to top, left to right</LI>
	<LI><CODE>-o number-up-layout=btrl</CODE>; Bottom to top, right to left</LI>
	<LI><CODE>-o number-up-layout=lrbt</CODE>; Left to right, bottom to top</LI>
	<LI><CODE>-o number-up-layout=lrtb</CODE>; Left to right, top to bottom (default)</LI>
	<LI><CODE>-o number-up-layout=rlbt</CODE>; Right to left, bottom to top</LI>
	<LI><CODE>-o number-up-layout=rltb</CODE>; Right to left, top to bottom</LI>
	<LI><CODE>-o number-up-layout=tblr</CODE>; Top to bottom, left to right</LI>
	<LI><CODE>-o number-up-layout=tbrl</CODE>; Top to bottom, right to left</LI>
</UL>

<H3><A NAME="FITPLOT">Scaling to Fit</A></H3>

<P>The <CODE>-o fitplot</CODE> option specifies that the document
should be scaled to fit on the page:</P>

<PRE CLASS="command">
lp -o fitplot filename
lpr -o fitplot filename
</PRE>

<P>The default is to use the size specified in the file.</P>

<BLOCKQUOTE>Note: This feature depends upon an accurate size in
the print file. If no size is given in the file, the page may be
scaled incorrectly!</BLOCKQUOTE>

<H3><A NAME="RAW">Raw or Unfiltered Output</A></H3>

<P>The <CODE>-o raw</CODE> option allows you to send files
directly to a printer without filtering. This is sometimes
required when printing from applications that provide their own
"printer drivers" for your printer:</P>

<PRE CLASS="command">
lp -o raw filename
lpr -o raw filename
</PRE>

<P>The <CODE>-l</CODE> option can also be used with the
<B>lpr</B> command to send files directly to a printer:</P>

<PRE CLASS="command">
lpr -l filename
</PRE>


<H2 CLASS="title"><A NAME="TEXTOPTIONS">Text Options</A></H2>

<P>CUPS supports several options that are only used when printing
plain text files. These options have absolutely no effect on
PostScript, PDF, HP-GL/2, or image files.</P>

<H3><A NAME="CPI">Setting the Number of Characters Per Inch</A></H3>

<P>The <CODE>-o cpi=value</CODE> option sets the number of
characters per inch:</P>

<PRE CLASS="command">
lp -o cpi=10 filename
lp -o cpi=12 filename
lpr -o cpi=17 filename
</PRE>

<P>The default characters per inch is 10.</P>

<H3><A NAME="LPI">Setting the Number of Lines Per Inch</A></H3>

<P>The <CODE>-o lpi=value</CODE> option sets the number of lines
per inch:</P>

<PRE CLASS="command">
lp -o lpi=6 filename
lpr -o lpi=8 filename
</PRE>

<P>The default lines per inch is 6.</P>

<H3><A NAME="COLUMNS">Setting the Number of Columns</A></H3>

<P>The <CODE>-o columns=value</CODE> option sets the number of
text columns:</P>

<PRE CLASS="command">
lp -o columns=2 filename
lpr -o columns=3 filename
</PRE>

<P>The default number of columns is 1.</P>

<H3><A NAME="MARGINS">Setting the Page Margins</A></H3>

<P>Normally the page margins are set to the hard limits of the
printer. Use the <CODE>-o page-left=value</CODE>, <CODE>-o
page-right=value</CODE>, <CODE>-o page-top=value</CODE>, and
<CODE>-o page-bottom=value</CODE> options to adjust the page
margins:</P>

<PRE CLASS="command">
lp -o page-left=<I>value</I> filename
lp -o page-right=<I>value</I> filename
lp -o page-top=<I>value</I> filename
lp -o page-bottom=<I>value</I> filename
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
</PRE>

<P>The <CODE>value</CODE> argument is the margin in points; each
point is 1/72 inch or 0.35mm.</P>

<H3><A NAME="PRETTYPRINT">Pretty Printing</A></H3>

<P>The <CODE>-o prettyprint</CODE> option puts a header at the
top of each page with the page number, job title (usually the
filename), and the date. Also, C and C++ keywords are
highlighted, and comment lines are italicized:</P>

<PRE CLASS="command">
lp -o prettyprint filename
lpr -o prettyprint filename
</PRE>

</BODY>
</HTML>
Commit	Line	Data
4744bd90	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
b86bc4cf	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>
4744bd90	108
f42414bf	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
4744bd90	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
b86bc4cf	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
4744bd90	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
b86bc4cf	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
4744bd90	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>