1 .\" Copyright 1996-2007 Glyph & Cog, LLC
2 .TH xpdf 1 "27 February 2007"
4 xpdf \- Portable Document Format (PDF) file viewer for X (version 3.02)
9 .RI [ page " | +" dest ]]
12 is a viewer for Portable Document Format (PDF) files. (These are also
13 sometimes also called \'Acrobat' files, from the name of Adobe's PDF
14 software.) Xpdf runs under the X Window System on UNIX, VMS, and
17 To run xpdf, simply type:
25 is your PDF file. The file name can be followed by a number
26 specifying the page which should be displayed first, e.g.:
32 You can also give a named destination, prefixed with \'+' in place of
33 the page number. (This is only useful with PDF files that provide
34 named destination targets.)
36 You can also start xpdf without opening any files:
41 .SH CONFIGURATION FILE
42 Xpdf reads a configuration file at startup. It first tries to find
43 the user's private config file, ~/.xpdfrc. If that doesn't exist, it
44 looks for a system-wide config file, typically /usr/local/etc/xpdfrc
45 (but this location can be changed when xpdf is built). See the
49 Many of the following options can be set with configuration file
50 commands or X resources. These are listed in square brackets with the
51 description of the corresponding command line option.
54 Set the initial window geometry.
57 .RB "[X resource: " xpdf.geometry ]
60 Set the window title. By default, the title will be "xpdf: foo.pdf".
61 .RB "[X resource: " xpdf.title ]
64 Install a private colormap. This is ignored on TrueColor visuals.
65 .RB "[X resource: " xpdf.installCmap ]
68 Set the size of largest RGB cube xpdf will try to allocate. The
69 default is 5 (for a 5x5x5 cube); set to a smaller number to conserve
70 color table entries. This is ignored with private colormaps and on
72 .RB "[X resource: " xpdf.rgbCubeSize ]
75 Set reverse video mode. This reverses the colors of everything except
76 images. It may not always produce great results for PDF files which
77 do weird things with color. This also causes the paper color to
79 .RB "[X resource: " xpdf.reverseVideo ]
81 .BI \-papercolor " color"
82 Set the "paper color", i.e., the background of the page display. This
83 will not work too well with PDF files that do things like filling in
84 white behind the text.
85 .RB "[X resource: " xpdf.paperColor ]
87 .BI \-mattecolor " color"
88 Set the matte color, i.e., the color used for background outside the
89 actual page area. (There is a separate setting,
90 xpdf.fullScreenMatteColor, for full-screen mode.)
91 .RB "[X resource: " xpdf.matteColor ]
94 Set the initial zoom factor. A number specifies a zoom percentage,
95 where 100 means 72 dpi.You may also specify \'page', to fit the page
96 to the window size, or \'width', to fit the page width to the window
98 .RB "[config file: " initialZoom "; or X resource: " xpdf.initialZoom ]
101 Start in continuous view mode, i.e., with one vertical scroll bar for
103 .RB "[config file: " continuousView ]
105 .BI \-t1lib " yes | no"
106 Enable or disable t1lib (a Type 1 font rasterizer). This defaults to
108 .RB "[config file: " enableT1lib ]
110 .BI \-freetype " yes | no"
111 Enable or disable FreeType (a TrueType / Type 1 font rasterizer).
112 This defaults to "yes".
113 .RB "[config file: " enableFreeType ]
116 Enable or disable font anti-aliasing. This defaults to "yes".
117 .RB "[config file: " antialias ]
119 .BI \-aaVector " yes | no"
120 Enable or disable vector anti-aliasing. This defaults to "yes".
121 .RB "[config file: " vectorAntialias ]
124 Set the default file name for PostScript output (i.e., the name which
125 will appear in the print dialog). This can also be of the form
126 \'|command' to pipe the PostScript through a command.
127 .RB "[config file: " psFile ]
130 Set the paper size to one of "letter", "legal", "A4", or "A3". This
131 can also be set to "match", which will set the paper size to match the
132 size specified in the PDF file.
133 .RB "[config file: " psPaperSize ]
136 Set the paper width, in points.
137 .RB "[config file: " psPaperSize ]
140 Set the paper height, in points.
141 .RB "[config file: " psPaperSize ]
144 Generate Level 1 PostScript. The resulting PostScript files will be
145 significantly larger (if they contain images), but will print on Level
146 1 printers. This also converts all images to black and white.
147 .RB "[config file: " psLevel ]
149 .BI \-enc " encoding-name"
150 Sets the encoding to use for text output. The
152 must be defined with the unicodeMap command (see
154 This defaults to "Latin1" (which is a built-in encoding).
155 .RB "[config file: " textEncoding ]
157 .BI \-eol " unix | dos | mac"
158 Sets the end-of-line convention to use for text output.
159 .RB "[config file: " textEOL ]
161 .BI \-opw " password"
162 Specify the owner password for the PDF file. Providing this will
163 bypass all security restrictions.
165 .BI \-upw " password"
166 Specify the user password for the PDF file.
169 Open xpdf in full-screen mode, useful for presentations.
172 Start/contact xpdf remote server with specified name (see the
173 .B "REMOTE SERVER MODE"
176 .BI \-exec " command"
177 Execute a command (see the
179 section below) in an xpdf remote server window (with -remote only).
182 Reload xpdf remote server window (with -remote only).
185 Raise xpdf remote server window (with -remote only).
188 Kill xpdf remote server (with -remote only).
191 Print commands as they're executed (useful for debugging).
192 .RB "[config file: " printCommands ]
195 Don't print any messages or errors.
196 .RB "[config file: " errQuiet ]
198 .BI \-cfg " config-file"
201 in place of ~/.xpdfrc or the system-wide config file.
204 Print copyright and version information.
207 Print usage information.
213 Several other standard X options and resources will work as expected:
215 .BI \-display " display"
216 .RB "[X resource: " xpdf.display ]
221 .RB "[X resource: " xpdf*Foreground ]
226 .RB "[X resource: " xpdf*Background ]
231 .RB "[X resource: " xpdf*fontList ]
233 The color and font options only affect the user interface elements,
234 not the PDF display (the \'paper').
236 The following X resources do not have command line option equivalents:
238 .B xpdf.toolTipEnable
239 Enables (if set to true) or disables (if set to false) the tool-tips
240 on the toolbar buttons.
242 .B xpdf.fullScreenMatteColor
243 Sets the matte color to be used in full-screen mode. The default
246 .SS On-screen controls, at the bottom of the xpdf window
248 .B "left/right arrow buttons"
249 Move to the previous/next page.
251 .B "double left/right arrow buttons"
252 Move backward or forward by ten pages.
254 .B "dashed left/right arrow buttons"
255 Move backward or forward along the history path.
257 .B "\'Page' entry box"
258 Move to a specific page number. Click in the box to activate it, type
259 the page number, then hit return.
262 Change the zoom factor (see the description of the -z option above).
264 .B "binoculars button"
268 Bring up a dialog for generating a PostScript file. The dialog has
269 options to set the pages to be printed and the PostScript file name.
270 The file name can be \'-' for stdout or \'|command' to pipe the
271 PostScript through a command, e.g., \'|lpr'.
274 Bring up the \'about xpdf' window.
277 The space between the \'?' and \'Quit' buttons is used to show the URL
278 or external file name when the mouse is over a link.
284 Pressing the right mouse button will post a popup menu with the
288 Open a new PDF file via a file requester.
290 .B "Open in new window..."
291 Create a new window and open a new PDF file via a file requester.
294 Reload the current PDF file. Note that Xpdf will reload the file
295 automatically (on a page change or redraw) if it has changed since it
299 Save the current file via a file requester.
302 Toggles between single page and continuous view modes.
304 .B "Rotate counterclockwise"
305 Rotate the page 90 degrees counterclockwise.
307 .B "Rotate clockwise"
308 Rotate the page 90 degrees clockwise. The two rotate commands are
309 intended primarily for PDF files where the rotation isn't correctly
310 specified in the file.
312 .B "Zoom to selection"
313 Zoom in to the currently selected rectangle.
316 Close the current window. If this is the only open window, the
317 document is closed, but the window is left open (i.e., this menu
318 command won't quit xpdf).
324 If the PDF contains an outline (a.k.a., bookmarks), there will be an
325 outline pane on the left side of the window. The width of the outline
326 pane is adjustable with a vertical split bar via the knob near its
330 Dragging the mouse with the left button held down will highlight an
331 arbitrary rectangle. Any text inside this rectangle will be copied to
332 the X selection buffer.
335 Clicking on a hyperlink will jump to the link's destination. A link
336 to another PDF document will make xpdf load that document. A
337 \'launch' link to an executable program will display a dialog, and if
338 you click \'ok', execute the program. URL links call an external
344 Dragging the mouse with the middle button held down pans the window.
349 Open a new PDF file via a file requester.
352 Reload the current PDF file. Note that Xpdf will reload the file
353 automatically (on a page change or redraw) if it has changed since it
357 Redraw the current page.
360 Close the current window.
366 Find next occurrence.
372 Move to the next page. Scrolls to the top of the page, unless scroll
376 Move to the previous page. Scrolls to the top of the page, unless
377 scroll lock is turned on.
379 .BR <Space> " or " <PageDown> " or " <Next>
380 Scroll down on the current page; if already at bottom, move to next
383 .BR <Backspace> " or " <Delete> " or " <PageUp> " or " <Previous>
384 Scroll up on the current page; if already at top, move to previous
388 Move forward along the history path.
391 Move backward along the history path.
394 Scroll to top of current page.
397 Scroll to bottom of current page.
400 Scroll to first page of document.
403 Scroll to last page of document.
406 Scroll the current page.
409 Activate the page number text field ("goto page").
412 Set the zoom factor to 125%.
415 Zoom in (increment the zoom factor by 1).
418 Zoom out (decrement the zoom factor by 1).
421 Set the zoom factor to 'page' (fit page to window).
424 Set the zoom factor to 'width' (fit page width to window).
427 Toggle full-screen mode.
432 If you want to run xpdf automatically from netscape or mosaic (and
433 probably other browsers) when you click on a link to a PDF file, you
434 need to edit (or create) the files
438 in your home directory. In
451 # Use xpdf to view PDF files.
454 application/pdf; xpdf -q %s
457 Make sure that xpdf is on your executable search path.
459 When you click on a URL link in a PDF file, xpdf will execute the
460 command specified by the urlCommand config file option, replacing an
461 occurrence of \'%s' with the URL. For example, to call netscape with
462 the URL, add this line to your config file:
465 urlCommand "netscape -remote 'openURL(%s)'"
468 Xpdf's key and mouse bindings are user-configurable, using the bind and
469 unbind options in the config file (see
471 The bind command allows you to bind a key or mouse button to a
472 sequence of one or more commands.
473 .SS Available Commands
474 The following commands are supported:
477 Go to the specified page.
479 .BI gotoPageNoScroll( page )
480 Go to the specified page, with the current relative scroll position.
483 Go to a named destination.
486 Go to the last page in the PDF file.
488 .B gotoLastPageNoScroll
489 Go to the last page in the PDF file, with the current relative scroll
496 Go to the next page, with the current relative scroll position.
499 Go to the previous page.
502 Go to the previous page, with the current relative scroll position.
505 Scroll up by one screenful.
508 Scroll down by one screenful.
530 .BI scrollUpPrevPage( n )
533 pixels, moving to the previous page if appropriate.
535 .BI scrollDownPrevPage( n )
538 pixels, moving to the next page if appropriate.
541 Scroll to the top edge of the current page, with no horizontal
544 .B scrollToBottomEdge
545 Scroll to the bottom edge of the current page, with no horizontal
549 Scroll to the left edge of the current page, with no vertical
553 Scroll to the right edge of the current page, with no vertical
557 Scroll to the top-left corner of the current page.
559 .B scrollToBottomRight
560 Scroll to the bottom-right corner of the current page.
563 Move forward along the history path.
566 Move backward along the history path.
569 Set the zoom factor to
573 Set the zoom factor to fit-page.
576 Set the zoom factor to fit-width.
579 Zoom in - go to the next higher zoom factor.
582 Zoom out - go the next lower zoom factor.
585 Go to continuous view mode.
588 Go to single-page view mode.
590 .B toggleContinuousMode
591 Toggle between continuous and single page view modes.
594 Go to full-screen mode.
597 Go to window (non-full-screen) mode.
599 .B toggleFullScreenMode
600 Toggle between full-screen and window modes.
603 Open a PDF file in this window, using the open dialog.
606 Open a PDF file in a new window, using the open dialog.
609 Open a specified PDF file in this window.
611 .BI openFileInNewWin( file )
612 Open a specified PDF file in a new window.
614 .BI openFileAtDest( file , dest )
615 Open a specified PDF file in this window and go to a named
618 .BI openFileAtDestInNewWin( file , dest )
619 Open a specified PDF file in a new window and go to a named
623 Reload the current PDF file.
629 Raise the window to the front.
634 .BI run( external-command-string )
635 Run an external command. The following escapes are allowed in the
639 %f => PDF file name (or an empty string if no
641 %b => PDF file base name, i.e., file name minus
642 the extension (or an empty string if no
644 %u => link URL (or an empty string if not over
646 %x => selection upper-left x coordinate
647 (or 0 if there is no selection)
648 %y => selection upper-left y coordinate
649 (or 0 if there is no selection)
650 %X => selection lower-right x coordinate
651 (or 0 if there is no selection)
652 %Y => selection lower-right y coordinate
653 (or 0 if there is no selection)
659 Open the outline pane.
662 Close the outline pane.
665 Toggle the outline pane between open and closed.
667 .BI scrollOutlineDown( n )
668 Scroll the outline down by
672 .BI scrollOutlineUp( n )
673 Scroll the outline up by
678 Set the keyboard focus to the main document window.
681 Set the keyboard focus to the page number text box.
684 Open the 'find' dialog.
687 Finds the next occurrence of the search string (no dialog).
690 Open the 'print' dialog.
693 Open the 'about' dialog.
698 The following commands depend on the current mouse position:
701 Start a selection, which will be extended as the mouse moves.
707 Start a pan, which will scroll the document as the mouse moves
713 Display the popup menu.
716 Follow a hyperlink (does nothing if the mouse is not over a link).
718 .B followLinkInNewWin
719 Follow a hyperlink, opening PDF files in a new window (does nothing if
720 the mouse is not over a link). For links to non-PDF files, this
721 command is identical to followLink.
724 Same as followLink, but does nothing if there is a non-empty selection.
725 (This is useful as a mouse button binding.)
727 .B followLinkInNewWinNoSel
728 Same as followLinkInNewWin, but does nothing if there is a non-empty
729 selection. (This is useful as a mouse button binding.)
731 The default mouse bindings are as follows:
734 bind mousePress1 any startSelection
735 bind mouseRelease1 any endSelection followLinkNoSel
736 bind mousePress2 any startPan
737 bind mouseRelease2 any endPan
738 bind mousePress3 any postPopupMenu
739 bind mousePress4 any scrollUpPrevPage(16)
740 bind mousePress5 any scrollDownNextPage(16)
741 bind mousePress6 any scrollLeft(16)
742 bind mousePress7 any scrollRight(16)
745 The default key bindings are as follows:
748 bind ctrl-home any gotoPage(1)
749 bind home any scrollToTopLeft
750 bind ctrl-end any gotoLastPage
751 bind end any scrollToBottomRight
753 bind backspace any pageUp
754 bind delete any pageUp
755 bind pgdn any pageDown
756 bind space any pageDown
757 bind left any scrollLeft(16)
758 bind right any scrollRight(16)
759 bind up any scrollUp(16)
760 bind down any scrollDown(16)
768 bind ctrl-g any findNext
769 bind ctrl-p any print
770 bind n scrLockOff nextPage
771 bind N scrLockOff nextPage
772 bind n scrLockOn nextPageNoScroll
773 bind N scrLockOn nextPageNoScroll
774 bind p scrLockOff prevPage
775 bind P scrLockOff prevPage
776 bind p scrLockOn prevPageNoScroll
777 bind P scrLockOn prevPageNoScroll
779 bind b any goBackward
780 bind g any focusToPageNum
781 bind 0 any zoomPercent(125)
784 bind z any zoomFitPage
785 bind w any zoomFitWidth
786 bind alt-f any toggleFullScreenMode
787 bind ctrl-l any redraw
788 bind ctrl-w any closeWindow
794 Previous versions of xpdf included a "viKeys" X resource. It is no
795 longer available, but the following bindings are equivalent:
798 bind h any scrollLeft(16)
799 bind l any scrollRight(16)
800 bind k any scrollUp(16)
801 bind j any scrollDown(16)
804 .SH "REMOTE SERVER MODE"
805 Xpdf can be started in remote server mode by specifying a server name
806 (in addition to the file name and page number). For example:
809 xpdf -remote myServer file.pdf
812 If there is currently no xpdf running in server mode with the name
813 \'myServer', a new xpdf window will be opened. If another command:
816 xpdf -remote myServer another.pdf 9
819 is issued, a new copy of xpdf will not be started. Instead, the first
820 xpdf (the server) will load
822 and display page nine. If the file name is the same:
825 xpdf -remote myServer another.pdf 4
828 the xpdf server will simply display the specified page.
830 The -raise option tells the server to raise its window; it can be
831 specified with or without a file name and page number.
833 The -quit option tells the server to close its window and exit.
835 The Xpdf tools use the following exit codes:
841 Error opening a PDF file.
844 Error opening an output file.
847 Error related to PDF permissions.
852 The xpdf software and documentation are copyright 1996-2007 Glyph &
863 .B http://www.foolabs.com/xpdf/