.TH  pdfpc "1" "November 2016" "pdfpc 4\&.0\&.4"
.if !dURL \{\
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.\}
.if \n[.g] .mso www.tmac

.SH NAME
pdfpc \- PDF presenter console with multi-monitor support

.SH SYNOPSIS
.B pdfpc
[options] PDF-file

.SH DESCRIPTION
.PP
pdfpc is a GTK-based presentation viewer for GNU/Linux which uses Keynote-like
multi-monitor output to provide meta information to the speaker during the
presentation. It is able to show a normal presentation window on one screen
while showing a more sophisticated overview on the other one, providing
information like a picture of the next slide, as well as the time left in the
presentation. pdfpc processes PDF documents, which can be created using nearly
all modern presentation software.
.PP
To run pdfpc, simply type
.RS
.PP
pdfpc file.pdf
.RE
.PP
By default the presenter view appears in the primary monitor and the
presentation view in the second monitor (provided you have two
monitors).
If you want to switch displays, start with the \-s option (see below).

.SH OPTIONS
.TP
.BI "\-d, \-\-duration"=N
Duration in minutes of the presentation used for timer display. If not given or
if a value of 0 is specified, the clock just measures the time in the
presentation.
.TP
.BI "\-e, \-\-end\-time"=T
End time of the presentation. (Format: HH:MM (24h))
.TP
.BI "\-l, \-\-last\-minutes"=N
Time in minutes, from which on the timer changes its color. (Default: 5 minutes)
.TP
.BI "\-t, \-\-start\-time"=T
Start time of the presentation to be used as a countdown. (Format: HH:MM (24h))
.TP
.BI "\-C, \-\-time\-of\-day
Display the time of the day
.TP
.BI "\-s, \-\-switch\-screens"
Switch the presentation and the presenter screen.
.TP
.BI "\-c, \-\-disable\-cache"
Disable caching and pre-rendering of slides to save memory at the cost of speed.
.TP
.BI "\-z, \-\-disable\-compression"
Disable the compression of slide images to trade memory consumption for speed.
(Avg.  factor 30)
.TP
.BI "\-g, \-\-disable\-auto\-grouping"
Disable auto detection of overlay groups. (Default: enabled)
.TP
.BI "\-S, \-\-single\-screen"
Force to use only one screen
.TP
.BI "\-L, \-\-list\-actions"
List actions supported in the config file(s)
.TP
.BI "\-w, \-\-windowed"
Run in windowed mode
.TP
.BI "\-Z, \-\-size"
Size of the presentation window in width:height format (forces windowed mode)
.TP
.BI "\-n, \-\-notes"=P
Position of notes on the PDF page. Position can be either left, right, top or bottom. Disable slide auto-grouping (Default: none)
.TP
.BI "\-h, \-\-help"
Shows the help

.SH KEYBINDINGS
These are the default keybindings for pdfpc:
.TP
.B Right cursor key / Page down / Return / Space / Left mouse button
Go forward one slide
.TP
.B Shift + Right cursor key / Page down / Return / Space / Left mouse button / Mouse wheel down or right
Go forward 10 slides
.TP
.B Down cursor key
Go forward one user slide (see
.B Overlays
below)
.TP
.B Left cursor key / Page up / Right mouse button / Mouse wheel up or left
Go back one slide
.TP
.B Shift + Left cursor key / Page up / Right mouse button
Go back 10 slides
.TP
.B Up cursor key
Go back one "user slide" (see
.B Overlays
below)
.TP
.B Home
Go to the first slide
.TP
.B End
Go to the last slide
.TP
.B Backspace
Go back in history. Note that history is defined by "jump" commands, not by normal slide movement.
.TP
.B Tab / Middle mouse button
Overview mode
.TP
.B g
Input a slide number to jump to
.TP
.B Plus / Equal / KP_Add / Bracket Left
Increase Notes Font Size
.TP
.B Minus / KP_Substract / Bracket Right
Decrease Notes Font Size
.TP
.B 8
Toggle Pointer Mode
.TP
.B 7
Decrease pointer size
.TP
.B 9
Increase pointer size
.TP
.B Escape / q
Exit pdfpc
.TP
.B b
Turn off the presentation view (i.e.  fill it with a black color)
.TP
.B n
Edit note for current slide
.TP
.B f
Freeze the current presentation display (the presenter display is still
fully active)
.TP
.B o
Toggle the overlay flag for one particular slide (see Overlays
below)
.TP
.B p
Pause timer
.TP
.B r
Reset presentation (reset timer and go back to first slide)
.TP
.B e
Define end slide
.P
See
.B CONFIG FILE
below if you want to customize the keybindings.

.SH FEATURES

.SS Caching / Pre-rendering

.PP
To allow fast changes between the different slides of the presentation the PDF
pages are pre-rendered to memory.  The progress bar on the bottom of the
presenter screen indicates how many percent of the slides have been
pre-rendered already.  During the initial rendering phase this will slow down
slide changes, as most CPU power is used for the rendering process in the
background.  After the cache is fully primed however the changing of slides
should be much faster, as with normal PDF viewers.

.PP
As the pre-rendering takes a lot of memory it can be disabled using the
\-\-disable\-cache switch at the cost of speed.
.SS Cache compression

.PP
The pre-rendered and cached slides can be compressed in memory to save up some
memory.  Without compression a set of about 100 PDF pages can easily grow up to
about 1.5 GB size.  Netbooks with only 1 GB of memory would swap themselves to
death if pre-rendering is enabled in such a situation.  The compression is
enabled by default as it does not harm rendering speed in a noticeable way on
most systems.  It does however slow down pre-rendering by about a factor of two.
If you have got enough memory and want to ensure the fastest possible
pre-rendering you can disable slide compression by using the \-z switch. But be
warned using the uncompressed pre-rendering storage will use about 30 times the
memory the new compressed storage utilizes (e.g. 50 MB will become about 1.5 GB).

.SS Timer
.PP
If a duration is given (\-d option), the timer will show a countdown with the
given parameters.  If no duration is specified (or if a value of 0 is given to
the \-d option), the timer will show how much time has been spent.  The duration
is stored automatically, so you do not need to repeat it for every invocation.

.PP
The timer is started if you are navigating away from the first page for the
first time.  This feature is quite useful as you may want to show the title page
of your presentation while people are still entering the room and the
presentation has not really begun yet.  If you want to start over you can
use the \[aq]r\[aq] key which will make the presenter reset the timer.

.PP
If a duration is given, at the moment the timer reaches the defined
last-minutes value it will change color to indicate your talk is nearing its
end.  As soon as the timer reaches the zero mark (00:00:00) it will turn red
and count further down showing a negative time, to provide information on how
many minutes you are overtime.

.SS Notes

.PP
Textual notes can be displayed for each slide.  While in the presentation,
pressing \[aq]n\[aq] will allow you to take notes for the screen.  To go out of
editing mode, press the Escape key.  Note that while editing a note the
keybindings stop working, i.e.  you are not able to change slides.

.PP
The notes are stored in the given file in a plain text format, easy to edit
also from outside the program.  See the section about the pdfpc format below.

.SS Overview mode

.PP
Pressing tab you can enter the overview mode, where miniatures for the slides
are shown.  You can select one slide to jump to with the mouse or with the
arrow keys.  You can also define overlays and the end slide (see next sections)
in this mode.

.SS Overlays

.PP
Many slide preparation systems allow for overlays, i.e.  sets of slides that
are logically grouped together as a single, changing slide.  Examples include
enumerations where the single items are displayed one after another or rough
"animations", where parts of a picture change from slide to slide. Pdfpc
includes facilities for dealing with such overlays.

.PP
In this description, we will differentiate between slides (i.e.  pages in the
PDF document) and "user slides", that are the logical slides.  The standard
forward movement command (page down, enter, etc.) moves through one slide at a
time, as expected.  That means that every step in the overlay is traversed.
The backward movement command works differently depending if the current and
previous slides are part of an overlay:

.IP \[bu] 2
If the current slide is part of an overlay we just jump to the previous slide.
That means that we are in the middle of an overlay we can jump forward and
backward through the single steps of it
.IP \[bu] 2
If the current slide is not part of an overlay (or if it is the first one), but
the previous slides are, we jump to the previous user slide.  This means that
when going back in the presentation you do not have to go through every step of
the overlay, pdfpc just shows the first slide of the each
overlay.  As you normally only go back in a presentation when looking for a
concrete slide, this is more convenient.

.PP
The up and down cursor keys work on a user slide basis.
You can use them to skip the rest of an overlay or to jump to the
previous user slide, ignoring the state of the current slide.

.PP
When going through an overlay, two additional previews may be activated
in the presenter view, just below the main view, showing the next and
the previous slide in an overlay.

.PP
Pdfpc tries to find these overlays automatically by looking
into the page labels in the PDF file.  For LaTeX this works correctly at least
with the beamer class and also modifying the page numbers manually (compiling
with pdflatex).  If your preferred slide-producing method does not work
correctly with this detection, you can supply this information using the \[aq]o\[aq] key
for each slide that is part of an overlay (except the first one!).  The page
numbering is also adapted.  This information is automatically stored.

.SS End slide
.PP
Some people like to have some additional, backup slides after the last
slide in the actual presentation.
Things like bibliographic references or slides referring to specialized
questions are typical examples.
Pdfpc lets you define which is the last slide in the
actual presentation via the \[aq]e\[aq] key.
This just changes the progress display in the presenter screen, as to
have a better overview of how many slides are left.

.SS Movies
.PP
Pdfpc can play back movies included in the PDF file.  Movies may be started
and stopped by clicking within their area.  For the presenter, a progress
bar is drawn along the bottom of the movie.  This expands when the mouse
hovers over it, allowing one to seek by clicking or dragging within the
progress bar.  Switching slides automatically stops playback, and movies
will be reset after leaving and returning to a slide.

.PP
Movies may be included in PDF files as "screen annotations".  pdfpc does
not yet support options that modify the playback of these movies.  In LaTeX,
such movies may be added to a presentation with the "movie15" or "multimedia"
package. Note that the poster, autoplay, and repeat options are not yet
supported. (Also, run ps2pdf with the \-dNOSAFER flag.)

.PP
As a perhaps simpler option, pdfpc will play back movies linked from a
hyperlink of type "launch".  A query string may be added to the URL of the
movie to enable the "autostart", "loop" and "noprogress" properties, if
necessary.  (E.g., a link to "movie.avi?autostart&loop&noprogress" will add a
video that starts playing automatically, loops when it reaches the end, and
does not show the progress bar.)

In LaTeX, such links are created with

.RS
\\usepackage{hyperref}
.br
\\href{run:<movie file>}{<placeholder content>}
.RE

.PP
The movie will playback in the area taken by the placeholder content.  Using
a frame of the movie will ensure the correct aspect ratio.

.SS Pointer Mode
.PP
If needed it is possible to turn on a pointer which draws a red dot in the 
place pointed by mouse cursor on both - presenter and presentation screens. 
It is also possible to increase and decrease the pointer size. Additionally 
when the pointer is enabled it is possible to drag & drop some area of the 
presenter screen causing it to be highlighted in both views as well. Area 
outside the selected region will be dimmed.

.SS pdfpc Files
.PP
The notes and other additional information are stored in a file with the
extension "pdfpc".
When pdfpc is invoked with a PDF file, it
automatically checks for and loads the associated pdfpc file, if it exists.
This means that you normally do not have to deal with this kind of files
explicitly.
.PP
There are however cases where you may want to edit the files manually.
The most typical case is if you add or remove some slides after you have
edited notes or defined overlays.
It may be quicker to edit the pdfpc file than to re-enter the whole
information.
Future versions may include external tools for dealing with this case
automatically.
.PP
The files are plain-text files that should be fairly self-explanatory.
A couple of things to note:
.IP \[bu] 2
The slide numbers of the notes refer to user slides
.IP \[bu] 2
The [notes] sections must be the last one in the file
.IP \[bu] 2
For the programmers out there: slide indexes start at 1

.SH CONFIG FILES
.PP
The main configuration file for pdfpc is located in @SYSCONFDIR@/pdfpcrc.
Additionally, $XDG_CONFIG_DIR/pdfpc/pdfpcrc is also read, if present.

.SS Keybindings
.PP
Following commands are aceepted:
.TP
.B bind <key> <func>
Bind a key to a function
.TP
.B unbind <key>
Unbinds the given key
.TP
.B unbind_all
Unbinds all the keybindings
.TP
.B mouse <button> <func>
Binds a mouse button to a function
.TP
.B unmouse <button>
Unbinds a mouse button
.TP
.B unmouse_all
Unbinds all the mouse bindings

.P
Key names can be obtained with the help of the xev utility. Note that
names are case sensitive. Modifiers can be specified in the form
<mod>+<key> where <mod> is one of S (for shift), C (for control) and
A/M (for Alt/Meta). E.g.
.TP
bind S+Next    next10
.P
A shorthand for specifying key combinations constituting shift and an
alphabetic character is to simply give the uppercase version of the
alphabetic character. For example, to bind <shift>+r to the 'reset'
function, use
.TP
bind R reset
.P
A list of all possible functions can be obtained
via the \-L command line option.

.PP
Some configuration files for commonly used devices
(wireless presenters, Bluetooth headsets, ...)
.URL https://pdfpc.github.io/#config-files "are available" .
If your device is not
yet supported and you generated a working config file, please
contribute it (see contact information below).


.SS Options
.PP
Some permanent changes can be configured via config file. The syntax is:
.TP
.B option <option_name> <option_value>

.PP
The following option_name are allowed:

.TP
.B current-size
Percentage of the presenter screen to be used for the current slide. (int, Default 60)
.TP
.B current-height
Percentage of the height of the presenter screen to be used for the current slide. (int, Default 80)
.TP
.B next-height
Percentage of the height of the presenter screen to be used for the next slide. (int, Default 70)
.TP
.B overview-min-size
Minimum width for the overview miniatures, in pixels. (int, Default 150)
.TP
.B black-on-end
Add an additional black slide at the end of the presentation (bool, Default false)
.TP
.B switch-screens
Switch the presentation and the presenter screen. (bool, Default false)

.SS Appearance

.PP
With GTK3 it is possible to modify the appearance of pdfpc. There are two
locations where pdfpc is looking for files. The default location is
@CMAKE_INSTALL_PREFIX@/share/pixmaps/pdfpc/pdfpc.css. A user can copy
it to $XDG_CONFIG_HOME/pdfpc/pdfpc.css and change the attributes as he likes.

.SH INTEGRATION WITH OTHER TOOLS
Pdfpc provides a dbus interface that other tools can use to execute any
action listed by \fB--list-actions\fR.  The interface appears on the session bus
as \fI io.github.pdfpc\fR.

.SH BUGS

.PP
There may be a small memory leak in the program. I am trying to solve it. It
should not be too important for up to some hundreds of slides.

.PP
Other bugs can be reported at
.URL https://github.com/pdfpc/pdfpc/issues "the issue tracker" .

.SH SEE ALSO
pdfpc was previously developed by
.URL https://github.com/davvil/pdfpc "davvil" .

pdfpc is a fork of Pdf Presenter Console, available
.URL https://github.com/jakobwesthoff/Pdf-Presenter-Console "online" .
