xpdf

NAME

xpdf −
Portable Document Format (PDF) file viewer (version
4.00)

SYNOPSIS

xpdf
[options] [PDF-file [:page | +dest]]
...

xpdf
[options] -remoteremote-name [command
...]

DESCRIPTION

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.

To run xpdf,
type:

xpdf
file.pdf

where
file.pdf is your PDF file. The file name can be
followed by a page number to be displayed, prefixed with a
colon:

xpdf file.pdf
:18

or by a named
destination, prefixed with ´+’ (this is only
useful with PDF files that provide named destination
targets):

xpdf file.pdf
+destinationA

If you specify
multiple files, they will each be opened in a separate
tab:

xpdf file1.pdf
file2.pdf :18 file3.pdf

You can also
start xpdf without opening any files:

xpdf

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 xpdfrc(5) man
page for details.

OPTIONS

The following
command line options are available. All command line options
must come before any PDF files to be opened.

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.
−geometrygeometry

Set the initial window
geometry.

−titletitle

Set the window title. By
default, the title will be "xpdf: foo.pdf".

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

−papercolorcolor

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. [config file:
paperColor]

−mattecolorcolor

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. [config
file: matteColor]

−fsmattecolorcolor

Set the matte color for
full-screen mode. The color can be #RRGGBB (hexadecimal) or
a named color. [config file:
fullScreenMatteColor]

−zzoom

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. [config file:
initialZoom]

Sets the encoding to use for
text output. The encoding−name must be defined
with the unicodeMap command (see xpdfrc(5)). This
defaults to "Latin1" (which is a built-in
encoding). [config file: textEncoding]

−pwpassword

Specify the password for the
PDF file. This can be either the owner password (which will
bypass all security restrictions) or the user password.

Menu bar
The menu bar is above the tool bar. The menu items should be
self-explanatory.

Tab list
The tab list is on the left, just below the tool bar. It
lists all open tabs.

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.

The outline is
a tree-like structure of bookmarks that allows moving within
the PDF file. Not all PDF files have outlines.

Layers (a.k.a.
optional content) allow parts of the PDF content to be shown
or hidden. Not all PDF files have layers.

Attachments are
other files embedded within the PDF file. There is a
’save’ button for each attached file. Not all
PDF files have attachments.

Text
selection
Dragging the mouse with the left button held down will
highlight an arbitrary rectangle. 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.

Links
When the mouse is over a hyperlink, the link target will be
shown in a popup near the bottom of the window.

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

Mouse
bindings
The left mouse button is used to select text (see
above).

Clicking on a
link with the middle button opens the link in a new tab.

Dragging the
mouse with the middle button held down pans the window.

The right mouse
button opens a popup menu (see popupMenuCmd in
xpdfrc(5)).

Key
bindings
This section lists the default key bindings. Bindings can be
changed using the config file (see xpdfrc(5)).
control-o

Open a new PDF file via a file
requester.

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.

control-f

Find a text string. This sets
keyboard focus to the ´find’ box.

control-G

Find next occurrence.

control-C

Copy selected text to the
clipboard.

control-P

Print.

control-0
(control-zero)

Set the zoom factor to
125%.

control-+
(control-plus)

Zoom in (increment the zoom
factor by 1).

control--
(control-minus)

Zoom out (decrement the zoom
factor by 1).

control-s

Save PDF via a file
requester.

control-t

Open a new tab.

control-n

Open a new window.

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.

control-q

Quit.

control-<tab>

Next tab.

control-shift-<tab>

Previous tab.

control-?

Help.

alt-<left-arrow>

Go backward along the history
path.

alt-<right-arrow>

Go forward along the history
path.

home

Go to the top left of current page.

control-<home>

Go to the first page.

end

Go to the bottom right of current page.

control-<end>

Go to the last page.

<space> or
<PageDown>

Scroll down on the current
page; if already at bottom, move to next page.

control-<PageDown>
or control-<down-arrow>

Go to the next page. If
<ScrollLock> is active, this maintains the relative
position on the page.

<PageUp>

Scroll up on the current page;
if already at top, move to previous page.

control-<PageUp>
or control-<up-arrow>

Go to the previous page. If
<ScrollLock> is active, this maintains the relative
position on the page.

<esc>

Exit full-screen mode.

arrows

Scroll the current page.

g

Set keyboard focus to the page number entry box.

z

Set the zoom factor to ´page’ (fit page to
window).

w

Set the zoom factor to ´width’ (fit page
width to window).

Full-screen mode

Xpdf can be
placed into full-screen mode via the
−fullscreen command line option, the
´full screen’ menu item, or a binding to the
fullScreenMode or toggleFullScreenMode
command.

Full-screen
mode can be exited via the default <esc> key binding,
or via a binding to the windowMode or
toggleFullScreenModecommand.

COMMANDS

Xpdf’s
key and mouse bindings are user-configurable, using the bind
and unbind commands in the config file (see
xpdfrc(5)). The bind command allows you to bind a key
or mouse button to a sequence of one or more commands.

The following
commands are supported:

about

Open the ´about’
dialog.

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.

checkOpenFile(file)

Check that file is open
in the current tab, and open it if not.

checkOpenFileAtDest(file,dest)

Check that file is open
in the current tab, and open it if not. In either case go to
the specified named destination.

checkOpenFileAtPage(file,page)

Check that file is open
in the current tab, and open it if not. In either case go to
the specified page.

closeSidebar

Close the sidebar.

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.

closeSidebarResizeWin

Close the sidebar, resizing the
window so that the document size doesn’t change.

closeTabOrQuit

Close the tab. If this was the
last open tab, close the window. If this was the last window
open, quit.

closeWindowOrQuit

Close the window. If this was
the last open window, quit.

continuousMode

Switch to continuous view
mode.

copy

Copy selected text to the clipboard.

endPan

End a pan operation.

endSelection

End a selection.

find

Set keyboard focus to the ´find’ box.

findFirst

Find the first occurrence of
the search string.

findNext

Find the next occurrence of the
search string.

findPrevious

Find the previous occurrence of
the search string.

focusToDocWin

Set keyboard focus to the main
document window.

focusToPageNum

Set keyboard focus to the page
number text box.

followLink

Follow a hyperlink (does
nothing if the mouse is not over a link).

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.

followLinkInNewTabNoSel

Same as followLinkInNewTab, but
does nothing if there is a non-empty selection. (This is
useful as a mouse button binding.)

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.

followLinkInNewWinNoSel

Same as followLinkInNewWin, but
does nothing if there is a non-empty selection. (This is
useful as a mouse button binding.)

followLinkNoSel

Same as followLink, but does
nothing if there is a non-empty selection. (This is useful
as a mouse button binding.)

fullScreenMode

Go to full-screen mode.

goBackward

Move backward along the history
path.

goForward

Move forward along the history
path.

gotoDest(dest)

Go to a named destination.

gotoLastPage

Go to the last page in the PDF
file.

gotoPage(page)

Go to the specified page.

help

Open the help URL.

horizontalContinuousMode

Switch to horizontal continuous
view mode.

linearSelectMode

Set linear selection mode. In
this mode, the selection follows text. Non-text regions
cannot be selected.

newTab

Open an empty new tab.

newWindow

Open an empty new window.

nextPage

Go to the next page.

nextPageNoScroll

Go to the next page, with the
current relative scroll position.

nextTab

Switch to the next tab.

open

Open a PDF file in this tab, using the open dialog.

openErrorWindow

Open the error window.

openFile(file)

Open the specified file in the
current tab.

openFileAtDest(file,dest)

Open the specified file in the
current tab at the specified named destination.

openFileAtPage(file,page)

Open the specified file in the
current tab at the specified page.

openSidebar

Open the sidebar.

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.

openSidebarResizeWin

Open the sidebar, resizing the
window so that the document size doesn’t change.

pageDown

Scroll down by one
screenful.

pageUp

Scroll up by one screenful.

postPopupMenu

Display the popup menu.

prevPage

Go to the previous page.

prevPageNoScroll

Go to the previous page, with
the current relative scroll position.

prevTab

Switch to the previous tab.

print

Open the ´print’ dialog.

quit

Quit from xpdf.

reload

Reload the current PDF file.

rotateCCW

Rotate the page 90 degrees
counterclockwise.

rotateCW

Rotate the page 90 degrees
clockwise.

run(external-command-string)

Run an external command. The
following escapes are allowed in the command string:

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

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

bind x
"run(ls -l)"

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.

saveAs

Save PDF via a file requester.

saveImage

Open the ´save
image’ dialog.

scrollDown(n)

Scroll down by n
pixels.

scrollDownNextPage(n)

Scroll down by n pixels,
moving to the next page if appropriate.

scrollLeft(n)

Scroll left by n
pixels.

scrollOutlineDown(n)

Scroll the outline down by
n increments.

scrollOutlineUp(n)

Scroll the outline up by
n increments.

scrollRight(n)

Scroll right by n
pixels.

scrollToBottomEdge

Scroll to the bottom edge of
the current page, with no horizontal movement.

scrollToBottomRight

Scroll to the bottom-right
corner of the current page.

scrollToLeftEdge

Scroll to the left edge of the
current page, with no vertical movement.

scrollToRightEdge

Scroll to the right edge of the
current page, with no vertical movement.

scrollToTopEdge

Scroll to the top edge of the
current page, with no horizontal movement.

scrollToTopLeft

Scroll to the top-left corner
of the current page.

scrollUp(n)

Scroll up by n
pixels.

scrollUpPrevPage(n)

Scroll up by n pixels,
moving to the previous page if appropriate.

setSelection(pg,ulx,uly,lrx,lry)

Set the selection to the
specified coordinates on the specified page.

sideBySideContinuousMode

Switch to side-by-side
continuous view mode.

sideBySideSingleMode

Switch to side-by-side two-page
view mode.

singlePageMode

Switch to single-page view
mode.

startPan

Start a pan operation at the
current mouse position, which will scroll the document as
the mouse moves.

startSelection

Start a selection at the
current mouse position, which will be extended as the mouse
moves.

toggleContinuousMode

Toggle between continuous and
single page view modes.

toggleFullScreenMode

Toggle between full-screen and
window modes.

toggleSelectMode

Toggle between block and linear
selection mode.

toggleSidebar

Toggle the sidebar between open
and closed.

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.

toggleSidebarResizeWin

Toggle the sidebar between open
and closed, resizing the window so that the document size
doesn’t change.

windowMode

Go to window (non-full-screen)
mode.

zoomFitPage

Set the zoom factor to
fit-page.

zoomFitWidth

Set the zoom factor to
fit-width.

zoomIn

Zoom in - go to the next higher zoom factor.

zoomOut

Zoom out - go the next lower
zoom factor.

zoomPercent(z)

Set the zoom factor to
z%.

zoomToSelection

Zoom to the current
selection.

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:

# 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)’