xpdf man page

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

Synopsis

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

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.

-geometry geometry

Set the initial window geometry.

-title title

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.

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

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

-fsmattecolor color

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

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

-aa yes | no

Enable or disable font anti-aliasing.  This defaults to "yes". [config file: antialias]

-aaVector yes | no

Enable or disable vector anti-aliasing.  This defaults to "yes". [config file: vectorAntialias]

-enc encoding-name

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]

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

-fullscreen

Open xpdf in full-screen mode, useful for presentations.

-display display

Set the X display (only available with X11).

-cmd

Print commands as they're executed (useful for debugging). [config file: printCommands]

-cfg config-file

Read config-file in place of ~/.xpdfrc or the system-wide config file.

-v

Print copyright and version information.

-h

Print usage information. (-help and --help are equivalent.)

Controls

Tool bar

´page' entry box

Move to a specific page number.  Click in the box to activate it, type the page number, then hit return.

left/right arrow buttons

Go backward or forward along the history path.

zoom out/in buttons

Zoom out or in (i.e., change magnification) incrementally.

zoom popup menu

Change the zoom factor (see the description of the -z option above).

fit width button

Change the zoom factor to fit the page width to the window width.

fit page button

Change the zoom factor to fit the page to the window size.

working/error 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.

´find' box

Find a text string.  Click in the box to activate it, type a search string, then hit return.

find next button

Find the next occurrence of the search string.

find previous button

Find the previous occurrence of the search string.

find settings button

Display the current find settings: case sensitive (on/off), find whole words (on/off).

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.

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

Entering full-screen mode automatically switches to single-page view mode and to the fit-page zoom factor.

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.

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.

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)"
saveAs

Save PDF via a file requester.

saveImage

Open the ´save image' dialog.

scrollDown(n)

Scroll down by n pixels.

scrollDownPrevPage(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.

Exit Codes

The Xpdf tools use the following exit codes:

0

No error.

1

Error opening a PDF file.

2

Error opening an output file.

3

Error related to PDF permissions.

99

Other error.

Author

The xpdf software and documentation are copyright 1996-2017 Glyph & Cog, LLC.

See Also

pdftops(1), pdftotext(1), pdftohtml(1), pdfinfo(1), pdffonts(1), pdfdetach(1), pdftoppm(1), pdftopng(1), pdfimages(1), xpdfrc(5)
http://www.xpdfreader.com/

Referenced By

groffer(1), linuxdoc(1), pdftopng(1), pdftosrc(1), sgml2latex(1), xpdfrc(5).

10 Aug 2017