1xpdf(1) General Commands Manual xpdf(1)
2
3
4
6 xpdf - Portable Document Format (PDF) file viewer (version 4.03)
7
9 xpdf [options] [PDF-file [:page | +dest]] ...
10
11 xpdf [options] -remote remote-name [command ...]
12
13 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
21 To run xpdf, type:
22
23 xpdf file.pdf
24
25 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
28 xpdf file.pdf :18
29
30 or by a named destination, prefixed with ´+' (this is only useful with
31 PDF files that provide named destination targets):
32
33 xpdf file.pdf +destinationA
34
35 If you specify multiple files, they will each be opened in a separate
36 tab:
37
38 xpdf file1.pdf file2.pdf :18 file3.pdf
39
40 You can also start xpdf without opening any files:
41
42 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
55 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
59 -geometry geometry
60 Set the initial window geometry.
61
62 -title title
63 Set the window title. By default, the title will be "xpdf:
64 foo.pdf".
65
66 -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
74 -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
79 -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
85 -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
90 -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
95 -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
101 -rot angle
102 Rotate pages by 0 (the default), 90, 180, or 270 degrees.
103
104 -aa yes | no
105 Enable or disable font anti-aliasing. This defaults to "yes".
106 [config file: antialias]
107
108 -aaVector yes | no
109 Enable or disable vector anti-aliasing. This defaults to "yes".
110 [config file: vectorAntialias]
111
112 -enc encoding-name
113 Sets the encoding to use for text output. The encoding-name
114 must be defined with the unicodeMap command (see xpdfrc(5)).
115 This defaults to "Latin1" (which is a built-in encoding). [con‐
116 fig file: textEncoding]
117
118 -pw password
119 Specify the password for the PDF file. This can be either the
120 owner password (which will bypass all security restrictions) or
121 the user password.
122
123 -fullscreen
124 Open xpdf in full-screen mode, useful for presentations.
125
126 -remote remote-name
127 Start Xpdf in remote server mode. See the REMOVE SERVER MODE
128 section.
129
130 -display display
131 Set the X display (only available with X11).
132
133 -cmd Print commands as they're executed (useful for debugging).
134 [config file: printCommands]
135
136 -tabstate tabstate-file
137 Sets the file used by the loadTabState and saveTabState com‐
138 mands. [config file: tabStateFile]
139
140 -cfg config-file
141 Read config-file in place of ~/.xpdfrc or the system-wide config
142 file.
143
144 -v Print copyright and version information.
145
146 -h Print usage information. (-help and --help are equivalent.)
147
149 Toolbar
150 toggle sidebar button
151 Toggles (i.e., shows or hides) the sidebar.
152
153 status indicator
154 This icon is animated while Xpdf is rendering a page. It turns
155 red when an error or warning has been issued. Clicking on it
156 opens the error dialog.
157
158 selection mode
159 This icon is an "I-beam" in linear selection mode, and an arrow
160 in block selection mode. Clicking on it toggles between the two
161 selection modes.
162
163 page number entry box
164 Move to a specific page number. Click in the box to activate
165 it, type the page number, then hit return. This will instead
166 display and accept page labels, if the "view - page labels" menu
167 item is checked.
168
169 left/right arrow buttons
170 Go backward or forward along the history path.
171
172 zoom out/in buttons
173 Zoom out or in (i.e., change magnification) incrementally.
174
175 zoom popup menu
176 Change the zoom factor (see the description of the -z option
177 above).
178
179 fit width button
180 Change the zoom factor to fit the page width to the window
181 width.
182
183 fit page button
184 Change the zoom factor to fit the page to the window size.
185
186 find entry box
187 Find a text string. Click in the box to activate it, type a
188 search string, then hit return.
189
190 find next button
191 Find the next occurrence of the search string.
192
193 find previous button
194 Find the previous occurrence of the search string.
195
196 find settings button
197 Display the current find settings: case sensitive (on/off), find
198 whole words (on/off).
199
200 Menu bar
201 The menu bar is above the toolbar. The menu items should be self-
202 explanatory.
203
204 Tab list
205 The tab list is on the left, just below the toolbar. It lists all open
206 tabs.
207
208 Outline/layers/attachments pane
209 This pane is on the left, below the tab list. The popup allows you to
210 select from outline, layers, or attachments.
211
212 The outline is a tree-like structure of bookmarks that allows moving
213 within the PDF file. Not all PDF files have outlines.
214
215 Layers (a.k.a. optional content) allow parts of the PDF content to be
216 shown or hidden. Not all PDF files have layers.
217
218 Attachments are other files embedded within the PDF file. There is a
219 'save' button for each attached file. Not all PDF files have attach‐
220 ments.
221
222 Text selection
223 In block selection mode, dragging the mouse with the left button held
224 down will highlight an arbitrary rectangle. Shift-clicking will extend
225 the selection.
226
227 In linear selection mode, dragging with the left button will highlight
228 text in reading order. Double-clicking or triple-clicking will select
229 a word or a line, respectively. Shift-clicking will extend the selec‐
230 tion.
231
232 Selected text can be copied to the clipboard (with the edit/copy menu
233 item). On X11, selected text will be available in the X selection buf‐
234 fer.
235
236 Links
237 When the mouse is over a hyperlink, the link target will be shown in a
238 popup near the bottom of the window.
239
240 Clicking on a hyperlink will jump to the link's destination. A link to
241 another PDF document will make xpdf load that document. A ´launch'
242 link to an executable program will display a dialog, and if you click
243 ´ok', execute the program. URL links are opened in a system-dependent
244 way. (On UNIX, Qt uses the $BROWSER environment variable.)
245
246 Mouse bindings
247 The left mouse button is used to select text (see above).
248
249 Clicking on a link with the middle button opens the link in a new tab.
250
251 Dragging the mouse with the middle button held down pans the window.
252
253 The right mouse button opens a popup menu (see popupMenuCmd in
254 xpdfrc(5)).
255
256 Key bindings
257 This section lists the default key bindings. Bindings can be changed
258 using the config file (see xpdfrc(5)).
259
260 control-o
261 Open a new PDF file via a file requester.
262
263 control-r
264 Reload the current PDF file. Note that Xpdf will reload the
265 file automatically (on a page change or redraw) if it has
266 changed since it was last loaded.
267
268 control-f
269 Find a text string. This sets keyboard focus to the ´find' box.
270
271 control-G
272 Find next occurrence.
273
274 control-C
275 Copy selected text to the clipboard.
276
277 control-P
278 Print.
279
280 control-0 (control-zero)
281 Set the zoom factor to 125%.
282
283 control-+ (control-plus)
284 Zoom in (increment the zoom factor by 1).
285
286 control-- (control-minus)
287 Zoom out (decrement the zoom factor by 1).
288
289 control-s
290 Save PDF via a file requester.
291
292 control-t
293 Open a new tab.
294
295 control-n
296 Open a new window.
297
298 control-w
299 Close the current tab. Closes the window if this was the last
300 open tab. Quits the application if this was the last open win‐
301 dow.
302
303 control-l
304 Toggle between full-screen and window modes.
305
306 control-q
307 Quit.
308
309 control-<tab>
310 Next tab.
311
312 control-shift-<tab>
313 Previous tab.
314
315 control-?
316 Help.
317
318 alt-<left-arrow>
319 Go backward along the history path.
320
321 alt-<right-arrow>
322 Go forward along the history path.
323
324 home Go to the top left of current page.
325
326 control-<home>
327 Go to the first page.
328
329 end Go to the bottom right of current page.
330
331 control-<end>
332 Go to the last page.
333
334 <space> or <PageDown>
335 Scroll down on the current page; if already at bottom, move to
336 next page.
337
338 control-<PageDown> or control-<down-arrow>
339 Go to the next page. If <ScrollLock> is active, this maintains
340 the relative position on the page.
341
342 <PageUp>
343 Scroll up on the current page; if already at top, move to previ‐
344 ous page.
345
346 control-<PageUp> or control-<up-arrow>
347 Go to the previous page. If <ScrollLock> is active, this main‐
348 tains the relative position on the page.
349
350 <esc> Exit full-screen mode.
351
352 arrows Scroll the current page.
353
354 g Set keyboard focus to the page number entry box.
355
356 z Set the zoom factor to ´page' (fit page to window).
357
358 w Set the zoom factor to ´width' (fit page width to window).
359
361 Xpdf can be placed into full-screen mode via the -fullscreen command
362 line option, the ´full screen' menu item, or a binding to the
363 fullScreenMode or toggleFullScreenMode command.
364
365 Entering full-screen mode automatically switches to single-page view
366 mode and to the fit-page zoom factor.
367
368 Full-screen mode can be exited via the default <esc> key binding, or
369 via a binding to the windowMode or toggleFullScreenModecommand.
370
372 Xpdf's key and mouse bindings are user-configurable, using the bind and
373 unbind commands in the config file (see xpdfrc(5)). The bind command
374 allows you to bind a key or mouse button to a sequence of one or more
375 commands.
376
377 In commands that take arguments (inside parentheses), special charac‐
378 ters (namely '(', ')', ',', and '\x01') can be escaped by preceding
379 them with a '\x01' character. This is mostly useful in things like
380 scripts that need to be able to open arbitrary PDF files, using the
381 ´openFile' command.
382
383 The following commands are supported:
384
385 about Open the ´about' dialog.
386
387 blockSelectMode
388 Set block selection mode. In this mode, the selection is a sim‐
389 ple rectangle. Any part of the page can be selected, regardless
390 of the content on the page.
391
392 checkOpenFile(file)
393 Check that file is open in the current tab, and open it if not.
394
395 checkOpenFileAtDest(file,dest)
396 Check that file is open in the current tab, and open it if not.
397 In either case go to the specified named destination.
398
399 checkOpenFileAtPage(file,page)
400 Check that file is open in the current tab, and open it if not.
401 In either case go to the specified page.
402
403 closeSidebar
404 Close the sidebar.
405
406 closeSidebarMoveResizeWin
407 Close the sidebar, resizing the window so that the document size
408 doesn't change, and moving the window so that the document stays
409 in the same place on the screen.
410
411 closeSidebarResizeWin
412 Close the sidebar, resizing the window so that the document size
413 doesn't change.
414
415 closeTabOrQuit
416 Close the tab. If this was the last open tab, close the window.
417 If this was the last window open, quit.
418
419 closeWindowOrQuit
420 Close the window. If this was the last open window, quit.
421
422 continuousMode
423 Switch to continuous view mode.
424
425 copy Copy selected text to the clipboard.
426
427 copyLinkTarget
428 Copy the target of the link under the mouse cursor to the clip‐
429 board.
430
431 endPan End a pan operation.
432
433 endSelection
434 End a selection.
435
436 expandSidebar(n)
437 Expand the sidebar by n pixels. Opens the sidebar if it is cur‐
438 rently closed.
439
440 find Set keyboard focus to the ´find' box.
441
442 findFirst
443 Find the first occurrence of the search string.
444
445 findNext
446 Find the next occurrence of the search string.
447
448 findPrevious
449 Find the previous occurrence of the search string.
450
451 focusToDocWin
452 Set keyboard focus to the main document window.
453
454 focusToPageNum
455 Set keyboard focus to the page number text box.
456
457 followLink
458 Follow a hyperlink (does nothing if the mouse is not over a
459 link).
460
461 followLinkInNewTab
462 Follow a hyperlink, opening PDF files in a new tab (does nothing
463 if the mouse is not over a link). For links to non-PDF files,
464 this command is identical to followLink.
465
466 followLinkInNewTabNoSel
467 Same as followLinkInNewTab, but does nothing if there is a non-
468 empty selection. (This is useful as a mouse button binding.)
469
470 followLinkInNewWin
471 Follow a hyperlink, opening PDF files in a new window (does
472 nothing if the mouse is not over a link). For links to non-PDF
473 files, this command is identical to followLink.
474
475 followLinkInNewWinNoSel
476 Same as followLinkInNewWin, but does nothing if there is a non-
477 empty selection. (This is useful as a mouse button binding.)
478
479 followLinkNoSel
480 Same as followLink, but does nothing if there is a non-empty
481 selection. (This is useful as a mouse button binding.)
482
483 fullScreenMode
484 Go to full-screen mode.
485
486 goBackward
487 Move backward along the history path.
488
489 goForward
490 Move forward along the history path.
491
492 gotoDest(dest)
493 Go to a named destination.
494
495 gotoLastPage
496 Go to the last page in the PDF file.
497
498 gotoPage(page)
499 Go to the specified page.
500
501 help Open the help URL.
502
503 hideToolbar
504 Hide the toolbar.
505
506 horizontalContinuousMode
507 Switch to horizontal continuous view mode.
508
509 linearSelectMode
510 Set linear selection mode. In this mode, the selection follows
511 text. Non-text regions cannot be selected.
512
513 loadTabState
514 Load the tab state file (which was written via the saveTabState
515 command), and restore the tabs listed in that file. The path
516 for the tab state file is specified with the tabStateFile set‐
517 ting (see xpdfrc(5)).
518
519 newTab Open an empty new tab.
520
521 newWindow
522 Open an empty new window.
523
524 nextPage
525 Go to the next page.
526
527 nextPageNoScroll
528 Go to the next page, with the current relative scroll position.
529
530 nextTab
531 Switch to the next tab.
532
533 open Open a PDF file in the current tab, using the open dialog.
534
535 openErrorWindow
536 Open the error window.
537
538 openFile(file)
539 Open the specified file in the current tab.
540
541 openFileAtDest(file,dest)
542 Open the specified file in the current tab at the specified
543 named destination.
544
545 openFileAtDestIn(file,dest,location)
546 Open the specified file at the specified named destination.
547 Location must be "win" for a new window or "tab" for a new tab.
548
549 openFileAtPage(file,page)
550 Open the specified file in the current tab at the specified
551 page.
552
553 openFileAtPageIn(file,page,location)
554 Open the specified file at the specified page. Location must be
555 "win" for a new window or "tab" for a new tab.
556
557 openFileIn(file,location)
558 Open the specified file. Location must be "win" for a new win‐
559 dow or "tab" for a new tab.
560
561 openIn(location)
562 Open a PDF file, using the open dialog. Location must be "win"
563 for a new window or "tab" for a new tab.
564
565 openSidebar
566 Open the sidebar.
567
568 openSidebarMoveResizeWin
569 Open the sidebar, resizing the window so that the document size
570 doesn't change, and moving the window so that the document stays
571 in the same place on the screen.
572
573 openSidebarResizeWin
574 Open the sidebar, resizing the window so that the document size
575 doesn't change.
576
577 pageDown
578 Scroll down by one screenful.
579
580 pageUp Scroll up by one screenful.
581
582 postPopupMenu
583 Display the popup menu.
584
585 prevPage
586 Go to the previous page.
587
588 prevPageNoScroll
589 Go to the previous page, with the current relative scroll posi‐
590 tion.
591
592 prevTab
593 Switch to the previous tab.
594
595 print Open the ´print' dialog.
596
597 quit Quit from xpdf.
598
599 raise Bring the xpdf window to the front.
600
601 reload Reload the current PDF file.
602
603 rotateCCW
604 Rotate the page 90 degrees counterclockwise.
605
606 rotateCW
607 Rotate the page 90 degrees clockwise.
608
609 run(external-command-string)
610 Run an external command. The following escapes are allowed in
611 the command string:
612
613 %f => PDF file name (or an empty string if no
614 file is open)
615 %b => PDF file base name, i.e., file name minus
616 the extension (or an empty string if no
617 file is open)
618 %u => link URL (or an empty string if not over
619 a URL link)
620 %p => current page number (or an empty string if
621 no file is open)
622 %x => selection upper-left x coordinate
623 (or 0 if there is no selection)
624 %y => selection upper-left y coordinate
625 (or 0 if there is no selection)
626 %X => selection lower-right x coordinate
627 (or 0 if there is no selection)
628 %Y => selection lower-right y coordinate
629 (or 0 if there is no selection)
630 %i => page containing the mouse pointer
631 %j => x coordinate of the mouse pointer
632 %k => y coordinate of the mouse pointer
633 %% => %
634
635 The external command string will often contain spaces, so the
636 whole command must be quoted in the xpdfrc file:
637
638 bind x "run(ls -l)"
639
640 The command string may not be run through a shell. It is recom‐
641 mended to keep the command simple, so that it doesn't depend on
642 specific shell functionality. For complex things, you can have
643 the command string run a shell script.
644
645 saveAs Save PDF via a file requester.
646
647 saveImage
648 Open the ´save image' dialog.
649
650 saveTabState
651 Save a list of all tabs open in this window to the tab state
652 file. For each tab, this writes the PDF file name and page num‐
653 ber (on separate lines). This file can be loaded later with the
654 loadTabState command. The path for the tab state file is speci‐
655 fied with the tabStateFile setting (see xpdfrc(5)).
656
657 scrollDown(n)
658 Scroll down by n pixels.
659
660 scrollDownNextPage(n)
661 Scroll down by n pixels, moving to the next page if appropriate.
662
663 scrollLeft(n)
664 Scroll left by n pixels.
665
666 scrollOutlineDown(n)
667 Scroll the outline down by n increments.
668
669 scrollOutlineUp(n)
670 Scroll the outline up by n increments.
671
672 scrollRight(n)
673 Scroll right by n pixels.
674
675 scrollToBottomEdge
676 Scroll to the bottom edge of the last displayed page, with no
677 horizontal movement.
678
679 scrollToBottomRight
680 Scroll to the bottom-right corner of the last displayed page.
681
682 scrollToLeftEdge
683 Scroll to the left edge of the current page, with no vertical
684 movement.
685
686 scrollToRightEdge
687 Scroll to the right edge of the current page, with no vertical
688 movement.
689
690 scrollToTopEdge
691 Scroll to the top edge of the first displayed page, with no hor‐
692 izontal movement.
693
694 scrollToTopLeft
695 Scroll to the top-left corner of the first displayed page.
696
697 scrollUp(n)
698 Scroll up by n pixels.
699
700 scrollUpPrevPage(n)
701 Scroll up by n pixels, moving to the previous page if appropri‐
702 ate.
703
704 selectLine
705 Set the selection to the line at the current mouse position.
706
707 selectWord
708 Set the selection to the word at the current mouse position.
709
710 setSelection(pg,ulx,uly,lrx,lry)
711 Set the selection to the specified coordinates on the specified
712 page.
713
714 showKeyBindings
715 Open the key bindings dialog.
716
717 showToolbar
718 Show the toolbar.
719
720 shrinkSidebar(n)
721 Shrink the sidebar by n pixels. Closes the sidebar if shrinking
722 it would go below the minimum allowed side.
723
724 sideBySideContinuousMode
725 Switch to side-by-side continuous view mode.
726
727 sideBySideSingleMode
728 Switch to side-by-side two-page view mode.
729
730 singlePageMode
731 Switch to single-page view mode.
732
733 startExtendedSelection
734 Extend the selection to the current mouse position, and continue
735 extending as the mouse moves.
736
737 startPan
738 Start a pan operation at the current mouse position, which will
739 scroll the document as the mouse moves.
740
741 startSelection
742 Start a selection at the current mouse position, which will be
743 extended as the mouse moves.
744
745 toggleContinuousMode
746 Toggle between continuous and single page view modes.
747
748 toggleFullScreenMode
749 Toggle between full-screen and window modes.
750
751 toggleSelectMode
752 Toggle between block and linear selection mode.
753
754 toggleSidebar
755 Toggle the sidebar between open and closed.
756
757 toggleSidebarMoveResizeWin
758 Toggle the sidebar between open and closed, resizing the window
759 so that the document size doesn't change, and moving the window
760 so that the document stays in the same place on the screen.
761
762 toggleSidebarResizeWin
763 Toggle the sidebar between open and closed, resizing the window
764 so that the document size doesn't change.
765
766 toggleToolbar
767 Toggle the toolbar between shown and hidden.
768
769 viewPageLabels
770 Show page labels (if the PDF file has them), rather than page
771 numbers.
772
773 viewPageNumbers
774 Show page numbers, rather than page labels.
775
776 windowMode
777 Go to window (non-full-screen) mode.
778
779 zoomFitPage
780 Set the zoom factor to fit-page.
781
782 zoomFitWidth
783 Set the zoom factor to fit-width.
784
785 zoomIn Zoom in - go to the next higher zoom factor.
786
787 zoomOut
788 Zoom out - go the next lower zoom factor.
789
790 zoomPercent(z)
791 Set the zoom factor to z%.
792
793 zoomToSelection
794 Zoom to the current selection.
795
797 Starting xpdf with the "-remote" switch puts it into remote server
798 mode. All remaining command line options are commands (see the COM‐
799 MANDS section). Subsequent invocations of "xpdf -remote" with the same
800 remote server name will send commands to the already-running instance
801 of xpdf. The "checkOpenFile" commands are useful here for things like
802 changing pages. For example:
803
804 # Start up xpdf, and open something.pdf.
805 xpdf -remote foo 'openFile(something.pdf)'
806
807 # Switch to page 7 in the already-open something.pdf. If
808 the user
809 # has closed xpdf in the meantime, this will restart it and
810 reopen
811 # the file.
812 xpdf -remote foo 'checkOpenFileAtPage(something.pdf, 7)'
813
815 The Xpdf tools use the following exit codes:
816
817 0 No error.
818
819 1 Error opening a PDF file.
820
821 2 Error opening an output file.
822
823 3 Error related to PDF permissions.
824
825 99 Other error.
826
828 The xpdf software and documentation are copyright 1996-2021 Glyph &
829 Cog, LLC.
830
832 pdftops(1), pdftotext(1), pdftohtml(1), pdfinfo(1), pdffonts(1), pdfde‐
833 tach(1), pdftoppm(1), pdftopng(1), pdfimages(1), xpdfrc(5)
834 http://www.xpdfreader.com/
835
836
837
838 28 Jan 2021 xpdf(1)