1xpdf(1) General Commands Manual xpdf(1)
2
6 xpdf - Portable Document Format (PDF) file viewer (version 4.02)
7
9 xpdf [options] [PDF-file [:page | +dest]] ...
10 xpdf [options] -remote remote-name [command ...]
12 xpdf [options] -open [PDF-file]
14
16 Xpdf is a viewer for Portable Document Format (PDF) files. (These are
17 also sometimes also called ´Acrobat' files, from the name of Adobe's
18 PDF software.) Xpdf uses the Qt GUI toolkit and runs on Unix, OS X,
19 and Windows.
20 To run xpdf, type:
22 xpdf file.pdf
24 where file.pdf is your PDF file. The file name can be followed by a
26 page number to be displayed, prefixed with a colon:
27 xpdf file.pdf :18
29 or by a named destination, prefixed with ´+' (this is only useful with
31 PDF files that provide named destination targets):
32 xpdf file.pdf +destinationA
34 If you specify multiple files, they will each be opened in a separate
36 tab:
37 xpdf file1.pdf file2.pdf :18 file3.pdf
39 You can also start xpdf without opening any files:
41 xpdf
43
45 Xpdf reads a configuration file at startup. It first tries to find the
46 user's private config file, ~/.xpdfrc. If that doesn't exist, it looks
47 for a system-wide config file, typically /usr/local/etc/xpdfrc (but
48 this location can be changed when xpdf is built). See the xpdfrc(5)
49 man page for details.
50
52 The following command line options are available. All command line
53 options must come before any PDF files to be opened.
54 Many of the options can be set with configuration file commands. These
56 are listed in square brackets with the description of the corresponding
57 command line option.
58 -geometry geometry
60 Set the initial window geometry.
61 -title title
63 Set the window title. By default, the title will be "xpdf:
64 foo.pdf".
65 -open [PDF-file]
67 This option sets up a default remote server. If Xpdf is already
68 running (with the "-open" switch), the PDF file (if any) is
69 opened in a new tab. If Xpdf (with the "-open" switch) is not
70 already running, starts Xpdf and opens the PDF file (if any).
71 This is useful for GUI desktop environments, e.g., the typical
72 double-click on a PDF file case.
73 -rv Set reverse video mode. This reverses the colors of everything
75 except images. It may not always produce great results for PDF
76 files which do weird things with color. This also causes the
77 paper color to default to black.
78 -papercolor color
80 Set the "paper color", i.e., the background of the page display.
81 The color can be #RRGGBB (hexadecimal) or a named color. This
82 option will not work well with PDF files that do things like
83 filling in white behind the text. [config file: paperColor]
84 -mattecolor color
86 Set the matte color, i.e., the color used for background outside
87 the actual page area. The color can be #RRGGBB (hexadecimal) or
88 a named color. [config file: matteColor]
89 -fsmattecolor color
91 Set the matte color for full-screen mode. The color can be
92 #RRGGBB (hexadecimal) or a named color. [config file:
93 fullScreenMatteColor]
94 -z zoom
96 Set the initial zoom factor. A number specifies a zoom percent‐
97 age, where 100 means 72 dpi. You may also specify ´page', to
98 fit the page to the window size, or ´width', to fit the page
99 width to the window width. [config file: initialZoom]
100 -aa yes | no
102 Enable or disable font anti-aliasing. This defaults to "yes".
103 [config file: antialias]
104 -aaVector yes | no
106 Enable or disable vector anti-aliasing. This defaults to "yes".
107 [config file: vectorAntialias]
108 -enc encoding-name
110 Sets the encoding to use for text output. The encoding-name
111 must be defined with the unicodeMap command (see xpdfrc(5)).
112 This defaults to "Latin1" (which is a built-in encoding). [con‐
113 fig file: textEncoding]
114 -pw password
116 Specify the password for the PDF file. This can be either the
117 owner password (which will bypass all security restrictions) or
118 the user password.
119 -fullscreen
121 Open xpdf in full-screen mode, useful for presentations.
122 -remote remote-name
124 Start Xpdf in remote server mode. See the REMOVE SERVER MODE
125 section.
126 -display display
128 Set the X display (only available with X11).
129 -cmd Print commands as they're executed (useful for debugging).
131 [config file: printCommands]
132 -cfg config-file
134 Read config-file in place of ~/.xpdfrc or the system-wide config
135 file.
136 -v Print copyright and version information.
138 -h Print usage information. (-help and --help are equivalent.)
140
142 Toolbar
143 toggle sidebar button
144 Toggles (i.e., shows or hides) the sidebar.
145 status indicator
147 This icon is animated while Xpdf is rendering a page. It turns
148 red when an error or warning has been issued. Clicking on it
149 opens the error dialog.
150 selection mode
152 This icon is an "I-beam" in linear selection mode, and an arrow
153 in block selection mode. Clicking on it toggles between the two
154 selection modes.
155 page number entry box
157 Move to a specific page number. Click in the box to activate
158 it, type the page number, then hit return. This will instead
159 display and accept page labels, if the "view - page labels" menu
160 item is checked.
161 left/right arrow buttons
163 Go backward or forward along the history path.
164 zoom out/in buttons
166 Zoom out or in (i.e., change magnification) incrementally.
167 zoom popup menu
169 Change the zoom factor (see the description of the -z option
170 above).
171 fit width button
173 Change the zoom factor to fit the page width to the window
174 width.
175 fit page button
177 Change the zoom factor to fit the page to the window size.
178 find entry box
180 Find a text string. Click in the box to activate it, type a
181 search string, then hit return.
182 find next button
184 Find the next occurrence of the search string.
185 find previous button
187 Find the previous occurrence of the search string.
188 find settings button
190 Display the current find settings: case sensitive (on/off), find
191 whole words (on/off).
192 Menu bar
194 The menu bar is above the toolbar. The menu items should be self-
195 explanatory.
196 Tab list
198 The tab list is on the left, just below the toolbar. It lists all open
199 tabs.
200 Outline/layers/attachments pane
202 This pane is on the left, below the tab list. The popup allows you to
203 select from outline, layers, or attachments.
204 The outline is a tree-like structure of bookmarks that allows moving
206 within the PDF file. Not all PDF files have outlines.
207 Layers (a.k.a. optional content) allow parts of the PDF content to be
209 shown or hidden. Not all PDF files have layers.
210 Attachments are other files embedded within the PDF file. There is a
212 'save' button for each attached file. Not all PDF files have attach‐
213 ments.
214 Text selection
216 Dragging the mouse with the left button held down will highlight an
217 arbitrary rectangle. Selected text can be copied to the clipboard
218 (with the edit/copy menu item). On X11, selected text will be avail‐
219 able in the X selection buffer.
220 Links
222 When the mouse is over a hyperlink, the link target will be shown in a
223 popup near the bottom of the window.
224 Clicking on a hyperlink will jump to the link's destination. A link to
226 another PDF document will make xpdf load that document. A ´launch'
227 link to an executable program will display a dialog, and if you click
228 ´ok', execute the program. URL links are opened in a system-dependent
229 way. (On UNIX, Qt uses the $BROWSER environment variable.)
230 Mouse bindings
232 The left mouse button is used to select text (see above).
233 Clicking on a link with the middle button opens the link in a new tab.
235 Dragging the mouse with the middle button held down pans the window.
237 The right mouse button opens a popup menu (see popupMenuCmd in
239 xpdfrc(5)).
240 Key bindings
242 This section lists the default key bindings. Bindings can be changed
243 using the config file (see xpdfrc(5)).
244 control-o
246 Open a new PDF file via a file requester.
247 control-r
249 Reload the current PDF file. Note that Xpdf will reload the
250 file automatically (on a page change or redraw) if it has
251 changed since it was last loaded.
252 control-f
254 Find a text string. This sets keyboard focus to the ´find' box.
255 control-G
257 Find next occurrence.
258 control-C
260 Copy selected text to the clipboard.
261 control-P
263 Print.
264 control-0 (control-zero)
266 Set the zoom factor to 125%.
267 control-+ (control-plus)
269 Zoom in (increment the zoom factor by 1).
270 control-- (control-minus)
272 Zoom out (decrement the zoom factor by 1).
273 control-s
275 Save PDF via a file requester.
276 control-t
278 Open a new tab.
279 control-n
281 Open a new window.
282 control-w
284 Close the current tab. Closes the window if this was the last
285 open tab. Quits the application if this was the last open win‐
286 dow.
287 control-l
289 Toggle between full-screen and window modes.
290 control-q
292 Quit.
293 control-<tab>
295 Next tab.
296 control-shift-<tab>
298 Previous tab.
299 control-?
301 Help.
302 alt-<left-arrow>
304 Go backward along the history path.
305 alt-<right-arrow>
307 Go forward along the history path.
308 home Go to the top left of current page.
310 control-<home>
312 Go to the first page.
313 end Go to the bottom right of current page.
315 control-<end>
317 Go to the last page.
318 <space> or <PageDown>
320 Scroll down on the current page; if already at bottom, move to
321 next page.
322 control-<PageDown> or control-<down-arrow>
324 Go to the next page. If <ScrollLock> is active, this maintains
325 the relative position on the page.
326 <PageUp>
328 Scroll up on the current page; if already at top, move to previ‐
329 ous page.
330 control-<PageUp> or control-<up-arrow>
332 Go to the previous page. If <ScrollLock> is active, this main‐
333 tains the relative position on the page.
334 <esc> Exit full-screen mode.
336 arrows Scroll the current page.
338 g Set keyboard focus to the page number entry box.
340 z Set the zoom factor to ´page' (fit page to window).
342 w Set the zoom factor to ´width' (fit page width to window).
344
346 Xpdf can be placed into full-screen mode via the -fullscreen command
347 line option, the ´full screen' menu item, or a binding to the
348 fullScreenMode or toggleFullScreenMode command.
349 Entering full-screen mode automatically switches to single-page view
351 mode and to the fit-page zoom factor.
352 Full-screen mode can be exited via the default <esc> key binding, or
354 via a binding to the windowMode or toggleFullScreenModecommand.
355
357 Xpdf's key and mouse bindings are user-configurable, using the bind and
358 unbind commands in the config file (see xpdfrc(5)). The bind command
359 allows you to bind a key or mouse button to a sequence of one or more
360 commands.
361 The following commands are supported:
363 about Open the ´about' dialog.
365 blockSelectMode
367 Set block selection mode. In this mode, the selection is a sim‐
368 ple rectangle. Any part of the page can be selected, regardless
369 of the content on the page.
370 checkOpenFile(file)
372 Check that file is open in the current tab, and open it if not.
373 checkOpenFileAtDest(file,dest)
375 Check that file is open in the current tab, and open it if not.
376 In either case go to the specified named destination.
377 checkOpenFileAtPage(file,page)
379 Check that file is open in the current tab, and open it if not.
380 In either case go to the specified page.
381 closeSidebar
383 Close the sidebar.
384 closeSidebarMoveResizeWin
386 Close the sidebar, resizing the window so that the document size
387 doesn't change, and moving the window so that the document stays
388 in the same place on the screen.
389 closeSidebarResizeWin
391 Close the sidebar, resizing the window so that the document size
392 doesn't change.
393 closeTabOrQuit
395 Close the tab. If this was the last open tab, close the window.
396 If this was the last window open, quit.
397 closeWindowOrQuit
399 Close the window. If this was the last open window, quit.
400 continuousMode
402 Switch to continuous view mode.
403 copy Copy selected text to the clipboard.
405 endPan End a pan operation.
407 endSelection
409 End a selection.
410 expandSidebar(n)
412 Expand the sidebar by n pixels. Opens the sidebar if it is cur‐
413 rently closed.
414 find Set keyboard focus to the ´find' box.
416 findFirst
418 Find the first occurrence of the search string.
419 findNext
421 Find the next occurrence of the search string.
422 findPrevious
424 Find the previous occurrence of the search string.
425 focusToDocWin
427 Set keyboard focus to the main document window.
428 focusToPageNum
430 Set keyboard focus to the page number text box.
431 followLink
433 Follow a hyperlink (does nothing if the mouse is not over a
434 link).
435 followLinkInNewTab
437 Follow a hyperlink, opening PDF files in a new tab (does nothing
438 if the mouse is not over a link). For links to non-PDF files,
439 this command is identical to followLink.
440 followLinkInNewTabNoSel
442 Same as followLinkInNewTab, but does nothing if there is a non-
443 empty selection. (This is useful as a mouse button binding.)
444 followLinkInNewWin
446 Follow a hyperlink, opening PDF files in a new window (does
447 nothing if the mouse is not over a link). For links to non-PDF
448 files, this command is identical to followLink.
449 followLinkInNewWinNoSel
451 Same as followLinkInNewWin, but does nothing if there is a non-
452 empty selection. (This is useful as a mouse button binding.)
453 followLinkNoSel
455 Same as followLink, but does nothing if there is a non-empty
456 selection. (This is useful as a mouse button binding.)
457 fullScreenMode
459 Go to full-screen mode.
460 goBackward
462 Move backward along the history path.
463 goForward
465 Move forward along the history path.
466 gotoDest(dest)
468 Go to a named destination.
469 gotoLastPage
471 Go to the last page in the PDF file.
472 gotoPage(page)
474 Go to the specified page.
475 help Open the help URL.
477 hideToolbar
479 Hide the toolbar.
480 horizontalContinuousMode
482 Switch to horizontal continuous view mode.
483 linearSelectMode
485 Set linear selection mode. In this mode, the selection follows
486 text. Non-text regions cannot be selected.
487 loadTabState
489 Load the tab state file (which was written via the saveTabState
490 command), and restore the tabs listed in that file. The path
491 for the tab state file is specified with the tabStateFile set‐
492 ting (see xpdfrc(5)).
493 newTab Open an empty new tab.
495 newWindow
497 Open an empty new window.
498 nextPage
500 Go to the next page.
501 nextPageNoScroll
503 Go to the next page, with the current relative scroll position.
504 nextTab
506 Switch to the next tab.
507 open Open a PDF file in the current tab, using the open dialog.
509 openErrorWindow
511 Open the error window.
512 openFile(file)
514 Open the specified file in the current tab.
515 openFileAtDest(file,dest)
517 Open the specified file in the current tab at the specified
518 named destination.
519 openFileAtDestIn(file,dest,location)
521 Open the specified file at the specified named destination.
522 Location must be "win" for a new window or "tab" for a new tab.
523 openFileAtPage(file,page)
525 Open the specified file in the current tab at the specified
526 page.
527 openFileAtPageIn(file,page,location)
529 Open the specified file at the specified page. Location must be
530 "win" for a new window or "tab" for a new tab.
531 openFileIn(file,location)
533 Open the specified file. Location must be "win" for a new win‐
534 dow or "tab" for a new tab.
535 openIn(location)
537 Open a PDF file, using the open dialog. Location must be "win"
538 for a new window or "tab" for a new tab.
539 openSidebar
541 Open the sidebar.
542 openSidebarMoveResizeWin
544 Open the sidebar, resizing the window so that the document size
545 doesn't change, and moving the window so that the document stays
546 in the same place on the screen.
547 openSidebarResizeWin
549 Open the sidebar, resizing the window so that the document size
550 doesn't change.
551 pageDown
553 Scroll down by one screenful.
554 pageUp Scroll up by one screenful.
556 postPopupMenu
558 Display the popup menu.
559 prevPage
561 Go to the previous page.
562 prevPageNoScroll
564 Go to the previous page, with the current relative scroll posi‐
565 tion.
566 prevTab
568 Switch to the previous tab.
569 print Open the ´print' dialog.
571 quit Quit from xpdf.
573 reload Reload the current PDF file.
575 rotateCCW
577 Rotate the page 90 degrees counterclockwise.
578 rotateCW
580 Rotate the page 90 degrees clockwise.
581 run(external-command-string)
583 Run an external command. The following escapes are allowed in
584 the command string:
585 %f => PDF file name (or an empty string if no
587 file is open)
588 %b => PDF file base name, i.e., file name minus
589 the extension (or an empty string if no
590 file is open)
591 %u => link URL (or an empty string if not over
592 a URL link)
593 %p => current page number (or an empty string if
594 no file is open)
595 %x => selection upper-left x coordinate
596 (or 0 if there is no selection)
597 %y => selection upper-left y coordinate
598 (or 0 if there is no selection)
599 %X => selection lower-right x coordinate
600 (or 0 if there is no selection)
601 %Y => selection lower-right y coordinate
602 (or 0 if there is no selection)
603 %i => page containing the mouse pointer
604 %j => x coordinate of the mouse pointer
605 %k => y coordinate of the mouse pointer
606 %% => %
607 The external command string will often contain spaces, so the
609 whole command must be quoted in the xpdfrc file:
610 bind x "run(ls -l)"
612 The command string may not be run through a shell. It is recom‐
614 mended to keep the command simple, so that it doesn't depend on
615 specific shell functionality. For complex things, you can have
616 the command string run a shell script.
617 saveAs Save PDF via a file requester.
619 saveImage
621 Open the ´save image' dialog.
622 saveTabState
624 Save a list of all tabs open in this window to the tab state
625 file. For each tab, this writes the PDF file name and page num‐
626 ber (on separate lines). This file can be loaded later with the
627 loadTabState command. The path for the tab state file is speci‐
628 fied with the tabStateFile setting (see xpdfrc(5)).
629 scrollDown(n)
631 Scroll down by n pixels.
632 scrollDownNextPage(n)
634 Scroll down by n pixels, moving to the next page if appropriate.
635 scrollLeft(n)
637 Scroll left by n pixels.
638 scrollOutlineDown(n)
640 Scroll the outline down by n increments.
641 scrollOutlineUp(n)
643 Scroll the outline up by n increments.
644 scrollRight(n)
646 Scroll right by n pixels.
647 scrollToBottomEdge
649 Scroll to the bottom edge of the last displayed page, with no
650 horizontal movement.
651 scrollToBottomRight
653 Scroll to the bottom-right corner of the last displayed page.
654 scrollToLeftEdge
656 Scroll to the left edge of the current page, with no vertical
657 movement.
658 scrollToRightEdge
660 Scroll to the right edge of the current page, with no vertical
661 movement.
662 scrollToTopEdge
664 Scroll to the top edge of the first displayed page, with no hor‐
665 izontal movement.
666 scrollToTopLeft
668 Scroll to the top-left corner of the first displayed page.
669 scrollUp(n)
671 Scroll up by n pixels.
672 scrollUpPrevPage(n)
674 Scroll up by n pixels, moving to the previous page if appropri‐
675 ate.
676 setSelection(pg,ulx,uly,lrx,lry)
678 Set the selection to the specified coordinates on the specified
679 page.
680 showToolbar
682 Show the toolbar.
683 shrinkSidebar(n)
685 Shrink the sidebar by n pixels. Closes the sidebar if shrinking
686 it would go below the minimum allowed side.
687 sideBySideContinuousMode
689 Switch to side-by-side continuous view mode.
690 sideBySideSingleMode
692 Switch to side-by-side two-page view mode.
693 singlePageMode
695 Switch to single-page view mode.
696 startPan
698 Start a pan operation at the current mouse position, which will
699 scroll the document as the mouse moves.
700 startSelection
702 Start a selection at the current mouse position, which will be
703 extended as the mouse moves.
704 toggleContinuousMode
706 Toggle between continuous and single page view modes.
707 toggleFullScreenMode
709 Toggle between full-screen and window modes.
710 toggleSelectMode
712 Toggle between block and linear selection mode.
713 toggleSidebar
715 Toggle the sidebar between open and closed.
716 toggleSidebarMoveResizeWin
718 Toggle the sidebar between open and closed, resizing the window
719 so that the document size doesn't change, and moving the window
720 so that the document stays in the same place on the screen.
721 toggleSidebarResizeWin
723 Toggle the sidebar between open and closed, resizing the window
724 so that the document size doesn't change.
725 toggleToolbar
727 Toggle the toolbar between shown and hidden.
728 viewPageLabels
730 Show page labels (if the PDF file has them), rather than page
731 numbers.
732 viewPageNumbers
734 Show page numbers, rather than page labels.
735 windowMode
737 Go to window (non-full-screen) mode.
738 zoomFitPage
740 Set the zoom factor to fit-page.
741 zoomFitWidth
743 Set the zoom factor to fit-width.
744 zoomIn Zoom in - go to the next higher zoom factor.
746 zoomOut
748 Zoom out - go the next lower zoom factor.
749 zoomPercent(z)
751 Set the zoom factor to z%.
752 zoomToSelection
754 Zoom to the current selection.
755
757 Starting xpdf with the "-remote" switch puts it into remote server
758 mode. All remaining command line options are commands (see the COM‐
759 MANDS section). Subsequent invocations of "xpdf -remote" with the same
760 remote server name will send commands to the already-running instance
761 of xpdf. The "checkOpenFile" commands are useful here for things like
762 changing pages. For example:
763 # Start up xpdf, and open something.pdf.
765 xpdf -remote foo 'openFile(something.pdf)'
766 # Switch to page 7 in the already-open something.pdf. If
768 the user
769 # has closed xpdf in the meantime, this will restart it and
770 reopen
771 # the file.
772 xpdf -remote foo 'checkOpenFileAtPage(something.pdf, 7)'
773
775 The Xpdf tools use the following exit codes:
776 0 No error.
778 1 Error opening a PDF file.
780 2 Error opening an output file.
782 3 Error related to PDF permissions.
784 99 Other error.
786
788 The xpdf software and documentation are copyright 1996-2019 Glyph &
789 Cog, LLC.
790
792 pdftops(1), pdftotext(1), pdftohtml(1), pdfinfo(1), pdffonts(1), pdfde‐
793 tach(1), pdftoppm(1), pdftopng(1), pdfimages(1), xpdfrc(5)
794 http://www.xpdfreader.com/
795 25 Sep 2019 xpdf(1)