xpdf.1

.\" Copyright 1996-2021 Glyph & Cog, LLC
.TH xpdf 1 "28 Jan 2021"
.SH NAME
xpdf \- Portable Document Format (PDF) file viewer (version 4.03)
.SH SYNOPSIS
.B xpdf
[options]
.RI [ PDF-file
.RI [: page " | +" dest "]] ..."
.PP
.B xpdf
[options]
.B -remote
.IR remote-name " [" command " ...]"
.PP
.B xpdf
[options]
.B -open
.RI "[" PDF-file "]"
.SH DESCRIPTION
.B Xpdf
is a viewer for Portable Document Format (PDF) files.  (These are also
sometimes also called \'Acrobat' files, from the name of Adobe's PDF
software.)  Xpdf uses the Qt GUI toolkit and runs on Unix, OS X, and
Windows.
.PP
To run xpdf, type:
.PP
.RS
xpdf file.pdf
.RE
.PP
where
.I file.pdf
is your PDF file.  The file name can be followed by a page number to
be displayed, prefixed with a colon:
.PP
.RS
xpdf file.pdf :18
.RE
.PP
or by a named destination, prefixed with \'+' (this is only useful
with PDF files that provide named destination targets):
.PP
.RS
xpdf file.pdf +destinationA
.RE
.PP
If you specify multiple files, they will each be opened in a separate
tab:
.PP
.RS
xpdf file1.pdf file2.pdf :18 file3.pdf
.RE
.PP
You can also start xpdf without opening any files:
.PP
.RS
xpdf
.RE
.SH CONFIGURATION FILE
Xpdf reads a configuration file at startup.  It first tries to find
the user's private config file, ~/.xpdfrc.  If that doesn't exist, it
looks for a system-wide config file, typically /usr/local/etc/xpdfrc
(but this location can be changed when xpdf is built).  See the
.BR xpdfrc (5)
man page for details.
.SH OPTIONS
The following command line options are available.  All command line
options must come before any PDF files to be opened.
.PP
Many of the options can be set with configuration file commands.
These are listed in square brackets with the description of the
corresponding command line option.
.TP
.BI \-geometry " geometry"
Set the initial window geometry.
.TP
.BI \-title " title"
Set the window title.  By default, the title will be "xpdf: foo.pdf".
.TP
.BI \-open " \fR[\fPPDF-file\fR]\fP"
This option sets up a default remote server.  If Xpdf is already
running (with the "-open" switch), the PDF file (if any) is opened in
a new tab.  If Xpdf (with the "-open" switch) is not already running,
starts Xpdf and opens the PDF file (if any).  This is useful for GUI
desktop environments, e.g., the typical double-click on a PDF file
case.
.TP
.B \-rv
Set reverse video mode.  This reverses the colors of everything except
images.  It may not always produce great results for PDF files which
do weird things with color.  This also causes the paper color to
default to black.
.TP
.BI \-papercolor " color"
Set the "paper color", i.e., the background of the page display.  The
color can be #RRGGBB (hexadecimal) or a named color.  This option will
not work well with PDF files that do things like filling in white
behind the text.
.RB "[config file: " paperColor ]
.TP
.BI \-mattecolor " color"
Set the matte color, i.e., the color used for background outside the
actual page area.  The color can be #RRGGBB (hexadecimal) or a named
color.
.RB "[config file: " matteColor ]
.TP
.BI \-fsmattecolor " color"
Set the matte color for full-screen mode.  The color can be #RRGGBB
(hexadecimal) or a named color.
.RB "[config file: " fullScreenMatteColor ]
.TP
.BI \-z " zoom"
Set the initial zoom factor.  A number specifies a zoom percentage,
where 100 means 72 dpi.  You may also specify \'page', to fit the page
to the window size, or \'width', to fit the page width to the window
width.
.RB "[config file: " initialZoom ]
.TP
.BI \-rot " angle"
Rotate pages by 0 (the default), 90, 180, or 270 degrees.
.TP
.BI \-aa " yes | no"
Enable or disable font anti-aliasing.  This defaults to "yes".
.RB "[config file: " antialias ]
.TP
.BI \-aaVector " yes | no"
Enable or disable vector anti-aliasing.  This defaults to "yes".
.RB "[config file: " vectorAntialias ]
.TP
.BI \-enc " encoding-name"
Sets the encoding to use for text output.  The
.I encoding\-name
must be defined with the unicodeMap command (see
.BR xpdfrc (5)).
This defaults to "Latin1" (which is a built-in encoding).
.RB "[config file: " textEncoding ]
.TP
.BI \-pw " password"
Specify the password for the PDF file.  This can be either the owner
password (which will bypass all security restrictions) or the user
password.
.TP
.B \-fullscreen
Open xpdf in full-screen mode, useful for presentations.
.TP
.BI \-remote " remote-name"
Start Xpdf in remote server mode.  See the REMOVE SERVER MODE section.
.TP
.BI \-display " display"
Set the X display (only available with X11).
.TP
.B \-cmd
Print commands as they're executed (useful for debugging).
.RB "[config file: " printCommands ]
.TP
.BI \-tabstate " tabstate-file"
Sets the file used by the loadTabState and saveTabState commands.
.RB "[config file: " tabStateFile ]
.TP
.BI \-cfg " config-file"
Read
.I config-file
in place of ~/.xpdfrc or the system-wide config file.
.TP
.B \-v
Print copyright and version information.
.TP
.B \-h
Print usage information.
.RB ( \-help
and
.B \-\-help
are equivalent.)
.PP
.SH CONTROLS
.SS Toolbar
.TP
.B "toggle sidebar button"
Toggles (i.e., shows or hides) the sidebar.
.TP
.B "status indicator"
This icon is animated while Xpdf is rendering a page.  It turns red
when an error or warning has been issued.  Clicking on it opens the
error dialog.
.TP
.B "selection mode"
This icon is an "I-beam" in linear selection mode, and an arrow in
block selection mode.  Clicking on it toggles between the two
selection modes.
.TP
.B "page number entry box"
Move to a specific page number.  Click in the box to activate it, type
the page number, then hit return.  This will instead display and
accept page labels, if the "view - page labels" menu item is checked.
.TP
.B "left/right arrow buttons"
Go backward or forward along the history path.
.TP
.B "zoom out/in buttons"
Zoom out or in (i.e., change magnification) incrementally.
.TP
.B "zoom popup menu"
Change the zoom factor (see the description of the \-z option above).
.TP
.B "fit width button"
Change the zoom factor to fit the page width to the window width.
.TP
.B "fit page button"
Change the zoom factor to fit the page to the window size.
.TP
.B "find entry box"
Find a text string.  Click in the box to activate it, type a search
string, then hit return.
.TP
.B "find next button"
Find the next occurrence of the search string.
.TP
.B "find previous button"
Find the previous occurrence of the search string.
.TP
.B "find settings button"
Display the current find settings: case sensitive (on/off), find whole
words (on/off).
.PP
.SS Menu bar
The menu bar is above the toolbar.  The menu items should be
self-explanatory.
.PP
.SS Tab list
The tab list is on the left, just below the toolbar.  It lists all
open tabs.
.PP
.SS Outline/layers/attachments pane
This pane is on the left, below the tab list.  The popup allows you to
select from outline, layers, or attachments.
.PP
The outline is a tree-like structure of bookmarks that allows moving
within the PDF file.  Not all PDF files have outlines.
.PP
Layers (a.k.a. optional content) allow parts of the PDF content to be
shown or hidden.  Not all PDF files have layers.
.PP
Attachments are other files embedded within the PDF file.  There is
a 'save' button for each attached file.  Not all PDF files have
attachments.
.PP
.SS Text selection
In block selection mode, dragging the mouse with the left button held
down will highlight an arbitrary rectangle.  Shift-clicking will
extend the selection.
.PP
In linear selection mode, dragging with the left button will highlight
text in reading order.  Double-clicking or triple-clicking will select
a word or a line, respectively.  Shift-clicking will extend the
selection.
.PP
Selected text can be copied to the clipboard (with the edit/copy menu
item).  On X11, selected text will be available in the X selection
buffer.
.PP
.SS Links
When the mouse is over a hyperlink, the link target will be shown in a
popup near the bottom of the window.
.PP
Clicking on a hyperlink will jump to the link's destination.  A link
to another PDF document will make xpdf load that document.  A
\'launch' link to an executable program will display a dialog, and if
you click \'ok', execute the program.  URL links are opened in a
system-dependent way.  (On UNIX, Qt uses the $BROWSER environment
variable.)
.PP
.SS Mouse bindings
The left mouse button is used to select text (see above).
.PP
Clicking on a link with the middle button opens the link in a new tab.
.PP
Dragging the mouse with the middle button held down pans the window.
.PP
The right mouse button opens a popup menu (see
.BR popupMenuCmd " in " xpdfrc (5)).
.PP
.SS Key bindings
This section lists the default key bindings.  Bindings can be changed
using the config file (see
.BR xpdfrc (5)).
.TP
.B control-o
Open a new PDF file via a file requester.
.TP
.B control-r
Reload the current PDF file.  Note that Xpdf will reload the file
automatically (on a page change or redraw) if it has changed since it
was last loaded.
.TP
.B control-f
Find a text string.  This sets keyboard focus to the \'find' box.
.TP
.B control-G
Find next occurrence.
.TP
.B control-C
Copy selected text to the clipboard.
.TP
.B control-P
Print.
.TP
.BR control-0 " (control-zero)"
Set the zoom factor to 125%.
.TP
.BR control-+ " (control-plus)"
Zoom in (increment the zoom factor by 1).
.TP
.BR control-- " (control-minus)"
Zoom out (decrement the zoom factor by 1).
.TP
.B control-s
Save PDF via a file requester.
.TP
.B control-t
Open a new tab.
.TP
.B control-n
Open a new window.
.TP
.B control-w
Close the current tab.  Closes the window if this was the last open
tab.  Quits the application if this was the last open window.
.TP
.B control-l
Toggle between full-screen and window modes.
.TP
.B control-q
Quit.
.TP
.B control-<tab>
Next tab.
.TP
.B control-shift-<tab>
Previous tab.
.TP
.B control-?
Help.
.TP
.B alt-<left-arrow>
Go backward along the history path.
.TP
.B alt-<right-arrow>
Go forward along the history path.
.TP
.B home
Go to the top left of current page.
.TP
.B control-<home>
Go to the first page.
.TP
.B end
Go to the bottom right of current page.
.TP
.B control-<end>
Go to the last page.
.TP
.BR <space> " or " <PageDown>
Scroll down on the current page; if already at bottom, move to next
page.
.TP
.BR control-<PageDown> " or " control-<down-arrow>
Go to the next page.  If <ScrollLock> is active, this maintains the
relative position on the page.
.TP
.B <PageUp>
Scroll up on the current page; if already at top, move to previous
page.
.TP
.BR control-<PageUp> " or " control-<up-arrow>
Go to the previous page.  If <ScrollLock> is active, this maintains
the relative position on the page.
.TP
.B <esc>
Exit full-screen mode.
.TP
.B arrows
Scroll the current page.
.TP
.B g
Set keyboard focus to the page number entry box.
.TP
.B z
Set the zoom factor to \'page' (fit page to window).
.TP
.B w
Set the zoom factor to \'width' (fit page width to window).
.SH Full-screen mode
Xpdf can be placed into full-screen mode via the
.B \-fullscreen
command line option, the \'full screen' menu item, or a binding to the
.B fullScreenMode
or
.B toggleFullScreenMode
command.
.PP
Entering full-screen mode automatically switches to single-page view
mode and to the fit-page zoom factor.
.PP
Full-screen mode can be exited via the default <esc> key binding,
or via a binding to the
.B windowMode
or
.BR toggleFullScreenMode command .
.SH COMMANDS
Xpdf's key and mouse bindings are user-configurable, using the bind
and unbind commands in the config file (see
.BR xpdfrc (5)).
The bind command allows you to bind a key or mouse button to a
sequence of one or more commands.
.PP
In commands that take arguments (inside parentheses), special
characters (namely '(', ')', ',', and '\\x01') can be escaped by
preceding them with a '\\x01' character.  This is mostly useful in
things like scripts that need to be able to open arbitrary PDF files,
using the \'openFile' command.
.PP
The following commands are supported:
.TP
.B about
Open the \'about' dialog.
.TP
.B blockSelectMode
Set block selection mode.  In this mode, the selection is a simple
rectangle.  Any part of the page can be selected, regardless of the
content on the page.
.TP
.BI checkOpenFile( file )
Check that
.I file
is open in the current tab, and open it if not.
.TP
.BI checkOpenFileAtDest( file, dest )
Check that
.I file
is open in the current tab, and open it if not.  In either case go to
the specified named destination.
.TP
.BI checkOpenFileAtPage( file, page )
Check that
.I file
is open in the current tab, and open it if not.  In either case go to
the specified page.
.TP
.B closeSidebar
Close the sidebar.
.TP
.B closeSidebarMoveResizeWin
Close the sidebar, resizing the window so that the document size
doesn't change, and moving the window so that the document stays in
the same place on the screen.
.TP
.B closeSidebarResizeWin
Close the sidebar, resizing the window so that the document size
doesn't change.
.TP
.B closeTabOrQuit
Close the tab.  If this was the last open tab, close the window.  If
this was the last window open, quit.
.TP
.B closeWindowOrQuit
Close the window.  If this was the last open window, quit.
.TP
.B continuousMode
Switch to continuous view mode.
.TP
.B copy
Copy selected text to the clipboard.
.TP
.B copyLinkTarget
Copy the target of the link under the mouse cursor to the clipboard.
.TP
.B endPan
End a pan operation.
.TP
.B endSelection
End a selection.
.TP
.BI expandSidebar( n )
Expand the sidebar by
.I n
pixels.  Opens the sidebar if it is currently closed.
.TP
.B find
Set keyboard focus to the \'find' box.
.TP
.B findFirst
Find the first occurrence of the search string.
.TP
.B findNext
Find the next occurrence of the search string.
.TP
.B findPrevious
Find the previous occurrence of the search string.
.TP
.B focusToDocWin
Set keyboard focus to the main document window.
.TP
.B focusToPageNum
Set keyboard focus to the page number text box.
.TP
.B followLink
Follow a hyperlink (does nothing if the mouse is not over a link).
.TP
.B followLinkInNewTab
Follow a hyperlink, opening PDF files in a new tab (does nothing if
the mouse is not over a link).  For links to non-PDF files, this
command is identical to followLink.
.TP
.B followLinkInNewTabNoSel
Same as followLinkInNewTab, but does nothing if there is a non-empty
selection.  (This is useful as a mouse button binding.)
.TP
.B followLinkInNewWin
Follow a hyperlink, opening PDF files in a new window (does nothing if
the mouse is not over a link).  For links to non-PDF files, this
command is identical to followLink.
.TP
.B followLinkInNewWinNoSel
Same as followLinkInNewWin, but does nothing if there is a non-empty
selection.  (This is useful as a mouse button binding.)
.TP
.B followLinkNoSel
Same as followLink, but does nothing if there is a non-empty selection.
(This is useful as a mouse button binding.)
.TP
.B fullScreenMode
Go to full-screen mode.
.TP
.B goBackward
Move backward along the history path.
.TP
.B goForward
Move forward along the history path.
.TP
.BI gotoDest( dest )
Go to a named destination.
.TP
.B gotoLastPage
Go to the last page in the PDF file.
.TP
.BI gotoPage( page )
Go to the specified page.
.TP
.BI help
Open the help URL.
.TP
.B hideToolbar
Hide the toolbar.
.TP
.B horizontalContinuousMode
Switch to horizontal continuous view mode.
.TP
.B linearSelectMode
Set linear selection mode.  In this mode, the selection follows text.
Non-text regions cannot be selected.
.TP
.BI loadTabState
Load the tab state file (which was written via the saveTabState
command), and restore the tabs listed in that file.  The path for the
tab state file is specified with the tabStateFile setting (see
.BR xpdfrc (5)).
.TP
.B newTab
Open an empty new tab.
.TP
.B newWindow
Open an empty new window.
.TP
.B nextPage
Go to the next page.
.TP
.B nextPageNoScroll
Go to the next page, with the current relative scroll position.
.TP
.B nextTab
Switch to the next tab.
.TP
.B open
Open a PDF file in the current tab, using the open dialog.
.TP
.B openErrorWindow
Open the error window.
.TP
.BI openFile( file )
Open the specified file in the current tab.
.TP
.BI openFileAtDest( file, dest )
Open the specified file in the current tab at the specified named
destination.
.TP
.BI openFileAtDestIn( file, dest, location )
Open the specified file at the specified named destination.  Location
must be "win" for a new window or "tab" for a new tab.
.TP
.BI openFileAtPage( file, page )
Open the specified file in the current tab at the specified page.
.TP
.BI openFileAtPageIn( file, page, location )
Open the specified file at the specified page.  Location must be "win"
for a new window or "tab" for a new tab.
.TP
.BI openFileIn( file, location )
Open the specified file.  Location must be "win" for a new window or
"tab" for a new tab.
.TP
.BI openIn( location )
Open a PDF file, using the open dialog.  Location must be "win" for a
new window or "tab" for a new tab.
.TP
.B openSidebar
Open the sidebar.
.TP
.B openSidebarMoveResizeWin
Open the sidebar, resizing the window so that the document size
doesn't change, and moving the window so that the document stays in
the same place on the screen.
.TP
.B openSidebarResizeWin
Open the sidebar, resizing the window so that the document size
doesn't change.
.TP
.B pageDown
Scroll down by one screenful.
.TP
.B pageUp
Scroll up by one screenful.
.TP
.B postPopupMenu
Display the popup menu.
.TP
.B prevPage
Go to the previous page.
.TP
.B prevPageNoScroll
Go to the previous page, with the current relative scroll position.
.TP
.B prevTab
Switch to the previous tab.
.TP
.B print
Open the \'print' dialog.
.TP
.B quit
Quit from xpdf.
.TP
.B raise
Bring the xpdf window to the front.
.TP
.B reload
Reload the current PDF file.
.TP
.B rotateCCW
Rotate the page 90 degrees counterclockwise.
.TP
.B rotateCW
Rotate the page 90 degrees clockwise.
.TP
.BI run( external-command-string )
Run an external command.  The following escapes are allowed in the
command string:
.nf

    %f => PDF file name (or an empty string if no
          file is open)
    %b => PDF file base name, i.e., file name minus
          the extension (or an empty string if no
          file is open)
    %u => link URL (or an empty string if not over
          a URL link)
    %p => current page number (or an empty string if
          no file is open)
    %x => selection upper-left x coordinate
          (or 0 if there is no selection)
    %y => selection upper-left y coordinate
          (or 0 if there is no selection)
    %X => selection lower-right x coordinate
          (or 0 if there is no selection)
    %Y => selection lower-right y coordinate
          (or 0 if there is no selection)
    %i => page containing the mouse pointer
    %j => x coordinate of the mouse pointer
    %k => y coordinate of the mouse pointer
    %% => %

.fi
The external command string will often contain spaces, so the whole
command must be quoted in the xpdfrc file:
.nf

    bind x "run(ls -l)"

.fi
The command string may not be run through a shell.  It is recommended
to keep the command simple, so that it doesn't depend on specific
shell functionality.  For complex things, you can have the command
string run a shell script.
.TP
.B saveAs
Save PDF via a file requester.
.TP
.B saveImage
Open the \'save image' dialog.
.TP
.BI saveTabState
Save a list of all tabs open in this window to the tab state file.
For each tab, this writes the PDF file name and page number (on
separate lines).  This file can be loaded later with the loadTabState
command.  The path for the tab state file is specified with the
tabStateFile setting (see
.BR xpdfrc (5)).
.TP
.BI scrollDown( n )
Scroll down by
.I n
pixels.
.TP
.BI scrollDownNextPage( n )
Scroll down by
.I n
pixels, moving to the next page if appropriate.
.TP
.BI scrollLeft( n )
Scroll left by
.I n
pixels.
.TP
.BI scrollOutlineDown( n )
Scroll the outline down by
.I n
increments.
.TP
.BI scrollOutlineUp( n )
Scroll the outline up by
.I n
increments.
.TP
.BI scrollRight( n )
Scroll right by
.I n
pixels.
.TP
.B scrollToBottomEdge
Scroll to the bottom edge of the last displayed page, with no
horizontal movement.
.TP
.B scrollToBottomRight
Scroll to the bottom-right corner of the last displayed page.
.TP
.B scrollToLeftEdge
Scroll to the left edge of the current page, with no vertical
movement.
.TP
.B scrollToRightEdge
Scroll to the right edge of the current page, with no vertical
movement.
.TP
.B scrollToTopEdge
Scroll to the top edge of the first displayed page, with no horizontal
movement.
.TP
.B scrollToTopLeft
Scroll to the top-left corner of the first displayed page.
.TP
.BI scrollUp( n )
Scroll up by
.I n
pixels.
.TP
.BI scrollUpPrevPage( n )
Scroll up by
.I n
pixels, moving to the previous page if appropriate.
.TP
.B selectLine
Set the selection to the line at the current mouse position.
.TP
.B selectWord
Set the selection to the word at the current mouse position.
.TP
.BI setSelection( pg , ulx , uly , lrx , lry )
Set the selection to the specified coordinates on the specified page.
.TP
.B showKeyBindings
Open the key bindings dialog.
.TP
.B showToolbar
Show the toolbar.
.TP
.BI shrinkSidebar( n )
Shrink the sidebar by
.I n
pixels.  Closes the sidebar if shrinking it would go below the minimum
allowed side.
.TP
.B sideBySideContinuousMode
Switch to side-by-side continuous view mode.
.TP
.B sideBySideSingleMode
Switch to side-by-side two-page view mode.
.TP
.B singlePageMode
Switch to single-page view mode.
.TP
.B startExtendedSelection
Extend the selection to the current mouse position, and continue
extending as the mouse moves.
.TP
.B startPan
Start a pan operation at the current mouse position, which will scroll
the document as the mouse moves.
.TP
.B startSelection
Start a selection at the current mouse position, which will be
extended as the mouse moves.
.TP
.B toggleContinuousMode
Toggle between continuous and single page view modes.
.TP
.B toggleFullScreenMode
Toggle between full-screen and window modes.
.TP
.B toggleSelectMode
Toggle between block and linear selection mode.
.TP
.B toggleSidebar
Toggle the sidebar between open and closed.
.TP
.B toggleSidebarMoveResizeWin
Toggle the sidebar between open and closed, resizing the window so
that the document size doesn't change, and moving the window so that
the document stays in the same place on the screen.
.TP
.B toggleSidebarResizeWin
Toggle the sidebar between open and closed, resizing the window so
that the document size doesn't change.
.TP
.B toggleToolbar
Toggle the toolbar between shown and hidden.
.TP
.B viewPageLabels
Show page labels (if the PDF file has them), rather than page numbers.
.TP
.B viewPageNumbers
Show page numbers, rather than page labels.
.TP
.B windowMode
Go to window (non-full-screen) mode.
.TP
.B zoomFitPage
Set the zoom factor to fit-page.
.TP
.B zoomFitWidth
Set the zoom factor to fit-width.
.TP
.B zoomIn
Zoom in - go to the next higher zoom factor.
.TP
.B zoomOut
Zoom out - go the next lower zoom factor.
.TP
.BI zoomPercent( z )
Set the zoom factor to
.IR z %.
.TP
.B zoomToSelection
Zoom to the current selection.
.SH REMOTE SERVER MODE
Starting xpdf with the "-remote" switch puts it into remote server
mode.  All remaining command line options are commands (see the
COMMANDS section).  Subsequent invocations of "xpdf -remote" with the
same remote server name will send commands to the already-running
instance of xpdf.  The "checkOpenFile" commands are useful here for
things like changing pages.
For example:
.PP
.RS
    # Start up xpdf, and open something.pdf.
    xpdf -remote foo 'openFile(something.pdf)'

    # Switch to page 7 in the already-open something.pdf.  If the user
    # has closed xpdf in the meantime, this will restart it and reopen
    # the file.
    xpdf -remote foo 'checkOpenFileAtPage(something.pdf, 7)'
.RE
.PP
.SH EXIT CODES
The Xpdf tools use the following exit codes:
.TP
0
No error.
.TP
1
Error opening a PDF file.
.TP
2
Error opening an output file.
.TP
3
Error related to PDF permissions.
.TP
99
Other error.
.SH AUTHOR
The xpdf software and documentation are copyright 1996-2021 Glyph &
Cog, LLC.
.SH "SEE ALSO"
.BR pdftops (1),
.BR pdftotext (1),
.BR pdftohtml (1),
.BR pdfinfo (1),
.BR pdffonts (1),
.BR pdfdetach (1),
.BR pdftoppm (1),
.BR pdftopng (1),
.BR pdfimages (1),
.BR xpdfrc (5)
.br
.B http://www.xpdfreader.com/