.\" generated by KeyJ's html2man.py version 0.1
.TH IMPRESSIVE 1 2013-12-29 "Martin J. Fiedler" "Impressive Documentation">
.SH "NAME"
Impressive \- presentation tool with eye candy
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.B impressive
[OPTIONS...] FILES...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Impressive is a simple presentation program that displays slideshows of image files (JPEG, PNG, TIFF and BMP) or PDF documents. Rendering is done via OpenGL, which allows for some "eye candy" effects.
.PP
.SH "OPTIONS"
.IX Header "OPTIONS"
.br
\fB\-a \fI<seconds>\fR\fR or \fB\-\-auto \fI<seconds>\fR\fR 
.RS
Automatically advance to the next page after the given number of seconds. Together with the \fB\-w\fR option (described below), this can be used to create automatic slideshows.
.RE
.PP
.br
\fB\-A \fI<X>\fR:\fI<Y>\fR\fR or \fB\-\-aspect \fI<X>\fR:\fI<Y>\fR\fR 
.RS
Specifies the display aspect ratio. Normally, Impressive assumes that the pixel aspect ratio is 1:1 (square pixels), regardless of the display resolution that has been set up. If a resolution has been selected that doesn't match the display's aspect ratio, the screen will be distorted. To overcome this, this option may be used to manually specify the display aspect ratio, e.g. "\-A 16:9". Note that this option has no effect if Xpdf is used for rendering.
.RE
.PP
.br
\fB\-b\fR or \fB\-\-noback\fR 
.RS
Disabled background rendering. By default, Impressive will pre\-render all pages in a separate background thread while the presentation runs. If this option is specified, it will instead render all pages immediately on startup. This option has no effect if caching is disabled (\fB\-\-cache none\fR, see below).
.RE
.PP
.br
\fB\-B \fI<ms>\fR\fR or \fB\-\-boxfade \fI<ms>\fR\fR 
.RS
Sets the duration (in milliseconds) of the highlight box fade\-in/\:fade\-out animation. Default value: 100 ms.
.RE
.PP
.br
\fB\-c \fI<mode>\fR\fR or \fB\-\-cache \fI<mode>\fR\fR 
.RS
Specifies the page cache mode to use. Valid options are: 
.br
\fBnone\fR
.RS
Disables page caching altogether, only the current and the following page will be kept in RAM. Jumping between pages will be very slow, because Impressive will need to render the requested pages on the fly. In addition, the overview page won't be complete until every page has been shown at least once.
.RE
.br
\fBmemory\fR
.RS
Caches all page images in memory. This is the fastest method, but it requires very large amounts of memory (about 3 MiB per page at 1024x768 resolution).
.RE
.br
\fBdisk\fR
.RS
Like above, but uses a temporary file rather than memory for storage. This is the default.
.RE
.br
\fBpersistent\fR
.RS
Uses a permanent cache file for caching. This file will not be deleted when Impressive quits and will be reused on subsequent invocations. The default name for the cache file is derived like the names for Info Scripts (see below for an explanation), but with a \fB.cache\fR file name extension instead of \fB.info\fR. This method is a little bit slower than \fBdisk\fR mode, but the time span until the overview page is fully populated will be significantly decreased if Impressive is ran again with the same input files and options.
.RE
The mode name may be abbreviated at will, down to one character. Thus, \fB\-\-cache persistent\fR, \fB\-c persist\fR and even \fB\-cp\fR are all synonyms.
.RE
.PP
.br
\fB\-C \fI<filename>\fR[:\fI<X>\fR,\fI<Y>\fR]\fR or \fB\-\-cursor \fI<filename>\fR[:\fI<X>\fR,\fI<Y>\fR]\fR 
.RS
This option can be used to specify the path to an image file (typically a transparent .png) that shall be used as the mouse cursor instead of the default one. Optionally, the hotspot may be specified (this is the position inside the cursor image where the real mouse position is located). Example: \fB\-\-cursor mycursor.png:2,4\fR
.RE
.PP
.br
\fB\-\-clock\fR 
.RS
If this option is enabled, the current time will be shown instead of the elapsed time if time display is activated with the \fBT\fR key. Compatible with the \fB\-M\fR option.
.RE
.PP
.br
\fB\-d \fI<time>\fR\fR or \fB\-\-duration \fI<time>\fR\fR 
.RS
Specifies the expected run time of the presentation. The \fItime\fR parameter can be either a number of seconds or a human\-readable time like \fB1:23\fR (1 minute and 23 seconds), \fB4:56h\fR (4 hours and 56 minutes), \fB3m45s\fR (3 minutes and 45 seconds), \fB5m\fR (5 minutes) or \fB1:23:45\fR (1 hour, 23 minutes and 45 seconds).
.br
If an expected duration is specified, Impressive will show a semi\-transparent green progress bar at the lower edge of the screen, indicating how much time has already passed. If the time is up, the bar will occupy the whole edge and fade to yellow (at 125% of the expected time) to red (at 150% or more).
.RE
.PP
.br
\fB\-D \fI<ms>\fR\fR or \fB\-\-mousedelay \fI<ms>\fR\fR 
.RS
Sets the time (in milliseconds) the mouse cursor is shown in fullscreen mode if it is not moved. Default value: 3000 ms.
.RE
.PP
.br
\fB\-\-darkness \fI<percentage>\fR\fR 
.RS
Specifies how much the screen shall become darker when using highlight boxes or spotlight mode. The value is specified in percent, with 25 being the default. A value of zero would mean no darkening at all (the screen would just be blurred slightly), and a value of 100 would make everything but the highlighted parts of the screen black.
.RE
.PP
.br
\fB\-e\fR or \fB\-\-noext\fR 
.RS
OpenGL normally only supports textures with power\-of\-two dimensions. This means that for a 1024x768 screen, the actual texture size will be 1024x1024, for 1600x1200 it will even be 2048x2048. To overcome this limit and save texture memory, Impressive will automatically use the OpenGL extensions \fBGL_ARB_texture_rectangle\fR (available on most graphics cards) or \fBGL_ARB_texture_non_power_of_two\fR (available on modern graphics cards with current drivers). If these cause any trouble, the \fB\-e\fR option may be used to prevent Impressive from using the problematic extensions.
.RE
.PP
.br
\fB\-f\fR 
.RS
Sets the window/\:fullscreen mode Impressive shall start up with. This option can be specified multiple times; each times it is found, the next of the three options is selected, in the follwing order: (1.)True \fBfullscreen mode\fR, including setting the video mode. This is the default mode. (2.)\fBWindowed\fR mode, where Impressive runs in a standard window. (3.)"\fBFake\-fullscreen\fR" mode, where fullscreen is emulated by uding a window without border that fills the whole screen. Setting the display resolution is not possible in this mode. Each of these modes has a corresponding long option that enables it directly (\fB\-\-fullscreen\fR, \fB\-\-windowed\fR and \fB\-\-fake\-fullscreen\fR).
.br
.RE
.PP
.br
\fB\-\-fullscreen\fR 
.RS
Starts Impressive in fullscreen mode (the default). See the discussion of the \fB\-f\fR option for details.
.RE
.PP
.br
\fB\-\-fake\-fullscreen\fR 
.RS
Starts Impressive in "fake fullscreen" mode. See the discussion of the \fB\-f\fR option for details.
.RE
.PP
.br
\fB\-F \fI<file>\fR\fR or \fB\-\-font \fI<file>\fR\fR 
.RS
Impressive uses some kind of text OSD to overlay the current page number and title (if available) on the overview page. This option can be used to specify a TrueType font file (.ttf) to use for the OSD. If the path specified doesn't directly point to a useable font file, Impressive will try to search the system font directories. 
It
assumes that all fonts are stored below \fB/\:usr/\:share/\:fonts\fR, \fB/\:usr/\:local/\:share/\:fonts\fR or \fB/\:usr/\:X11R6/\:lib/\:X11/\:fonts/\:TTF\fR for this purpose (the latter one is useful for Mac OS X systems specifically). If this option is not specified, 
any of \fBDejaVuSans.ttf\fR or \fBVera.ttf\fR (the typical file name of Bitstream Vera Sans) 
will be used as a default.
.
.RE
.PP
.br
\fB\-g \fI<width>\fRx\fI<height>\fR[+\fI<posX>\fR+\fI<posY>\fR]\fR or \fB\-\-geometry \fI<width>\fRx\fI<height>\fR[+\fI<posX>\fR+\fI<posY>\fR]\fR 
.RS
Sets the screen size or resolution Impressive shall use (in pixels).
If \fBxrandr\fR is
installed, the default screen size for fullscreen mode is the current screen resolution; on other platforms, Impressive uses the highest resolution available to the graphics system. If a standard resolution cannot be determined, the default is 1024x768 pixels. This is also the default for windowed mode.
.br
Furthermore, if the additional parameters \fIposX\fR and \fIposY\fR are present, they specify the position of the upper\-left corner of the window (relative to the upper\-left corner of the desktop), in pixels, for windowed and fake\-fullscreen mode. The values are ignored in "true" fullscreen mode.
.RE
.PP
.br
\fB\-G \fI<gamma>\fR[:\fI<blacklevel>\fR]\fR or \fB\-\-gamma \fI<gamma>\fR[:\fI<blacklevel>\fR]\fR 
.RS
Sets up the startup gamma and (optional) black level value. The black level is the original image's intensity level (0...254) that is to be mapped to black in Impressive's output. Note that gamma and black level adjustments may be unavailable or constrained on some systems.
.RE
.PP
.br
\fB\-h\fR or \fB\-\-help\fR 
.RS
If this option is specified, Impressive writes a short command line help screen to standard output and does not start a presentation.
.RE
.PP
.br
\fB\-H\fR or \fB\-\-half\-screen\fR 
.RS
This option makes Impressive show the overview page and OSD elements on the right half of the screen only. The overview page will only show the left half of the slides as previews. Using a multi\-monitor setup with a wide virtual screen and specially crafted slides (e.g. those that can be generated with LaTeX's \fBbeamer\fR class), this makes it possible to have presenter's notes on the second screen.
.br
Note that transitions and animations are still operating on the whole screen, making some of them (like \fBPagePeel\fR) look ugly. Impressive also disables the overview zoom animation in half\-screen mode; it can be re\-enabled by explicitly setting it to another value with a later command line option (\fB\-\-zoomtime\fR).
.br
Another limitation is that the allocation of the screen halves (slides left, overview right) is fixed.
.RE
.PP
.br
\fB\-i \fI<page>\fR\fR or \fB\-\-initialpage \fI<page>\fR\fR 
.RS
Specifies the page number to start with. The default value is 1 (start with the first page). If another value is specified, the page shown by Impressive right after initialization is not the first one of the PDF or image list. Additionally, pre\-rendering (if enabled) will also start at the specified page.
.RE
.PP
.br
\fB\-I \fI<filename>\fR\fR or \fB\-\-script \fI<filename>\fR\fR 
.RS
Overrides automatic derivation of the info script filename and specifies a script file directly.
.RE
.PP
.br
\fB\-\-invert\fR 
.RS
This option makes Impressive invert the colors of each page, turning black to white and vice\-versa. Note that it is a full RGB inversion, so it will, for example, turn dark green to light purple (and vice\-versa) too.
.RE
.PP
.br
\fB\-k\fR or \fB\-\-auto\-progress\fR 
.RS
This option makes Impressive show a progress bar at the bottom of the screen, visualizing the timeout on pages that have one (either specified as a page property or using the \fB\-\-auto\fR command\-line option). Nothing is done on pages that don't have a timeout.
.br
The progress bar shown by this option takes precedence over the \fB\-\-duration\fR or \fB\-\-page\-progress\fR bars: If one of these options is specified as well, the timeout progress bar will be shown on pages with a timeout, and the other progress bar will be shown on pages without one.
.RE
.PP
.br
\fB\-l\fR or \fB\-\-listtrans\fR 
.RS
If this option is specified, Impressive writes a list of all available transition classes to standard output and does not start a presentation. Transitions that are enabled by default are marked with a star (\fB*\fR) left of the class name.
.RE
.PP
.br
\fB\-L \fI<spec>\fR\fR or \fB\-\-layout \fI<spec>\fR\fR 
.RS
Specifies the OSD layout. Read below for an explanation of this option
.RE
.PP
.br
\fB\-\-min\-box\-size \fI<pixels>\fR\fR 
.RS
This option sets the minimum size of a highlight box, in pixels. Boxes that are not this many pixels wide and high are rejected in order to prevent accidental creation of highlight boxes. The default value for this is 30 pixels.
.RE
.PP
.br
\fB\-M\fR or \fB\-\-minutes\fR 
.RS
If this option is set, Impressive will show the on\-screen timer (activated with the [T] key) only with 1 minute resolution. By default, it will show a timer with 1 second resolution.
.RE
.PP
.br
\fB\-\-nologo\fR 
.RS
This option disables the Impressive logo and version number display. Instead, the loading screen will be just black or, if background rendering is disabled, only the progress bar will be visible.
.RE
.PP
.br
\fB\-\-noclicks\fR 
.RS
If this option is enabled, switching to the previous or next page with the left and right mouse buttons is deactivated. The keyboard shortcuts are unaffected from this.
.RE
.PP
.br
\fB\-o \fI<directory>\fR\fR or \fB\-\-output \fI<directory>\fR\fR 
.RS
Do not display the presentation, but render it into a series of PNG image files inside the specified directory. The images will be generated in the current resolution as specified by the \fB\-g\fR option. This option is useful if the presentation is to be given on on a foreign PC with an old, broken or otherwise problematic Xpdf installation: By generating images of the PDF pages, is is made sure that no rendering bugs will happen on the target system.
.RE
.PP
.br
\fB\-O \fI<mode>\fR\fR or \fB\-\-autooverview \fI<mode>\fR\fR 
.RS
Enables or disables automatic derivation of whether a page shall or shall not be shown on the overview page. This feature is based on the fact that some LaTeX presentation packages tag all pages with a title (that can be read by Impressive with the help of \fBpdftk\fR), except those that contain multiple reveal steps.
.br
The following modes are available: 
.br
\fBoff\fR
.RS
Disables automatic overview mode. All pages will be shown on the overview page by default. This is also the default setting.
.RE
.br
\fBfirst\fR
.RS
All pages with a PDF title will be shown on the overview page. The purpose is to show the \fBinitial\fR state of multi\-step slides on the overview page.
.RE
.br
\fBlast\fR
.RS
All pages \fBbefore\fR a page with a PDF title will be shown on the overview page. The purpose is to show the \fBfinal\fR state of multi\-step slides on the overview page.
.RE
Again, the mode may be abbreviated arbitrarily, down to one character, just like with the \fB\-c\fR option above..
.RE
.PP
.br
\fB\-p \fI<start>\fR\-\fI<end>\fR\fR or \fB\-\-pages \fI<start>\fR\-\fI<end>\fR\fR 
.RS
Using this option, the range of the page displayed can be narrowed down. The presentation will start at the first page in the range. All pages outside of the range will not be shown on the overview page and will not be cached. However, they can be entered manually when cycling through the presentation. Due to the fact that these pages are uncached, preparation of the display will take considerably longer.
.RE
.PP
.br
\fB\-P \fI<path>\fR\fR or \fB\-\-gspath \fI<path>\fR\fR 
.RS
This option can be used to override the Xpdf /\: GhostScript path autodetection. The full path to the executable of either GhostScript (\fBgs\fR or \fBgs.exe\fR) or Xpdf's \fBpdftoppm\fR utility must be specified.
.RE
.PP
.br
\fB\-q\fR or \fB\-\-page\-progress\fR 
.RS
If this option is enabled, Impressive will show a light\-blue semi\-transparent progress bar at the lower edge of the screen that shows the position inside the presentation, i.e. the relation between the current page number and the total number of pages. Note that this progress bar will not be shown if the duration progress bar (\fB\-d\fR option) is also enabled.
.RE
.PP
.br
\fB\-Q\fR or \fB\-\-autoquit\fR 
.RS
If this option is specified, Impressive quits automatically when trying to navigate to the page after the last page or the page before the first page.
.br
This option does not have any effect if \fB\-\-wrap\fR is used.
.RE
.PP
.br
\fB\-r \fI<n>\fR\fR or \fB\-\-rotate \fI<n>\fR\fR 
.RS
Display all pages rotated by \fIn\fRx90 degrees clockwise. Try \fB\-r 1\fR or \fB\-r 3\fR if there are problems with PDFs generated by LaTeX on some Xpdf or GhostScript versions.
.RE
.PP
.br
\fB\-R \fI<X>\fRx\fI<Y>\fR\fR or \fB\-\-meshres \fI<X>\fRx\fI<Y>\fR\fR 
.RS
Most effects subdivide the visible screen into a mesh of rectangular or quadratic pieces, each with its own coordinates and alpha blend values. Using this parameter, the resolution of the subdivision mesh can be defined. The default value is 48x36. On slow machines, lower values like 24x18 or 12x9 can heavily speed up transition rendering at the cost of visual quality. On the other hand, higher values like 64x48 or 96x72 improve quality, but use much more CPU cycles.
.RE
.PP
.br
\fB\-s\fR or \fB\-\-scale\fR \fI(image input only)\fR 
.RS
If a directory with image files is used as input, Impressive will scale down images that are too big for the screen. But by default, it will not scale up smaller images to fit the screen; it will leave a black border instead. This option overrides this setting and enables upscaling of smaller images.
.RE
.PP
.br
\fB\-s\fR or \fB\-\-supersample\fR \fI(PDF input only)\fR 
.RS
This switch enables antialiasing by 4x supersampling instead of the normal multisampling method used by Xpdf or GhostScript. While this usually degrades both visual quality and performance, it may be necessary for circumventing white strips or moire\-like patterns in gradients.
.RE
.PP
.br
\fB\-S \fI<pixels>\fR\fR or \fB\-\-fontsize \fI<pixels>\fR\fR 
.RS
This option sets the size, in pixels, of the OSD font. The default value is 14.
.RE
.PP
.br
\fB\-\-spot\-radius \fI<pixels>\fR\fR 
.RS
This option sets the initial radius of the spotlight, in pixels. The default value is 64.
.RE
.PP
.br
\fB\-t \fI<ms>\fR\fR or \fB\-\-transition \fI<trans1[,trans2...]>\fR\fR 
.RS
Using this switch, the set of transitions Impressive will randomly draw at page changes can be specified. If only one transition class is specified, this class will be used for all pages that do not have another transition explicitly assigned in their page properties. Multiple transitions have to be separated by commas; they will be used in random order. The \fB\-l\fR option can be used to get a list of available transitions.
.RE
.PP
.br
\fB\-T \fI<ms>\fR\fR or \fB\-\-transtime \fI<ms>\fR\fR 
.RS
Sets the duration (in milliseconds) of page transitions. 0 (zero) disables transitions altogether. Default value: 1000 ms.
.RE
.PP
.br
\fB\-u \fI<seconds>\fR\fR or \fB\-\-poll \fI<seconds>\fR\fR 
.RS
If this option is specified, the source file or directory will be checked for changes regularly. If a change in the input PDF file or any of the image files in the input image directory is detected, the page cache will be flushed and the current page as well as the info script will be reloaded. The current page's transition will be shown between the old and the new version of the page.
.br
The new PDF file must have at least as much pages as the old one; also, it should have the same aspect ratio. If the input is a directory, image files must not have disappeared.
.RE
.PP
.br
\fB\-V \fI<pixels>\fR\fR or \fB\-\-overscan \fI<pixels>\fR\fR 
.RS
PDF files often contain tiny amounts of white borders around the edges which look bad in screen presentations. To eliminate this problem, Impressive uses "overscan": PDF files will not be rendered to fit the screen size exactly, but they will be rendered a bit larger so that the (possibly broken) borders can be cropped off. The amount of overscan, in screen pixels, can be set with this option. The default value is 3 pixels, which should remove borders in most presentations at most common screen resolutions without cropping the pages too much.
.RE
.PP
.br
\fB\-w\fR or \fB\-\-wrap\fR 
.RS
If this option is set, Impressive will "wrap" over to the first page after the last page. In other words, advancing to the next page at the end of the presentation will restart the whole presentation.
.RE
.PP
.br
\fB\-W\fR or \fB\-\-nowheel\fR 
.RS
By default, it is possible to change pages using the mouse wheel. This option disables this behavior, which can be useful to prevent spurious page changes if the mouse wheel is likely to be moved by accident.
.RE
.PP
.br
\fB\-\-windowed\fR 
.RS
Starts Impressive in windowed mode. See the discussion of the \fB\-f\fR option for details.
.RE
.PP
.br
\fB\-x\fR or \fB\-\-fade\fR 
.RS
This option enables a smooth fade\-in effect at the start of the presentation and a fade\-out effect just before Impressive quits.
.RE
.PP
.br
\fB\-X\fR or \fB\-\-shuffle\fR 
.RS
If this option is enabled, the input files will be shuffled into random order before starting the presentation. The individual pages of PDF input files will stay in their original order, though, so this option is mainly useful for image presentations.
.RE
.PP
.br
\fB\-y\fR or \fB\-\-auto\-auto\fR 
.RS
This option can be used together with \fB\-\-duration\fR to have Impressive compute a page timeout (as with the \fB\-\-auto\fR option) automatically. This results in a presentation that runs automatically, displaying each slide for the same time, so that the desired total duration will be reached (almost) exactly.
.RE
.PP
.br
\fB\-z \fI<factor>\fR\fR or \fB\-\-zoom \fI<factor>\fR\fR 
.RS
Sets the zoom factor that is used in zoom mode. It must be an integer value of at least 2. The default value is 2. Note that it might not be possible to get high\-quality zooming for large zoom factors due to hardware restrictions. Also, note that if the hardware doesn't support non\-power\-of\-two textures or if the \fB\-e\fR option is used, the number must be a power of two.
.RE
.PP
.br
\fB\-Z \fI<ms>\fR\fR or \fB\-\-zoomtime \fI<ms>\fR\fR 
.RS
Sets the duration (in milliseconds) of the overview page zoom\-in/\:zoom\-out effects. Default value: 250 ms.
.RE
.PP
.br
\fB\-\-cachefile \fI<filename>\fR\fR 
.RS
Activates persistent cache mode and specifies the name of the cache file to use.
.RE
.PP
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
Following the options, the input file name(s) must be specified. Recognized file types are PDF, JPEG, PNG, TIFF, BMP and PGM/\:PPM. If the name of a directory is put on the command line, all recognized image files (no PDF files!) in this directory will be played in alphanumeric order (case\-insensitive).
.PP
In addition, Impressive can use a text file containing a list of files or directories to show: This text file must contain at most one file name per line; every character after a hash sign (\fB#\fR) is treated as a comment and will be ignored. If such a comment is put on the same line as an image file name, it will be used as the page's title. List file names must be prefixed with an at sign (\fB@\fR) on the command line, e.g. \fBimpressive @my_list_file\fR.
.PP
Impressive will also expand wild\-card characters (\fB*\fR and \fB?\fR) if this isn't already done by the shell, but apart from that, it will not reorder the arguments. Thus, it will show the documents in the order specified at the command line.
.PP
.SH "    LAYOUT OPTIONS"
.IX Subsection "LAYOUT OPTIONS"
The OSD layout option (\fB\-L\fR/\:\fB\-\-layout\fR) accepts a string with comma\-separated \fB\fIkey\fR=\fIvalue\fR\fR pairs. The following keywords are recognized:
.br
.br
\fBalpha\fR
.RS
The opacity of the OSD text, either as a floating\-point value between 0 and 1 or a percentage between 2 and 100.
.RE
.br
\fBmargin\fR
.RS
The distance (in pixels) of the OSD text to the screen borders.
.RE
.br
\fBtime\fR
.RS
The position of the timer.
.RE
.br
\fBtitle\fR
.RS
The position of the page title in overview mode.
.RE
.br
\fBpage\fR
.RS
The position of the page number in overview mode.
.RE
.br
\fBstatus\fR
.RS
The position of the status line.
.RE
The position specifications are composed by one character that indicates whether the text shall be displayed at the top (\fBT\fR) or bottom (\fBB\fR) edge of the screen and one character that indicates whether it shall appear on the left (\fBL\fR), on the right (\fBR\fR) or centered (\fBC\fR).
.PP
For example, the default OSD layout equals the following option string:
.br
\fB    \-L margin=16,alpha=1,time=TR,title=BL,page=BR,status=TL\fR
.PP
.SH "    EXAMPLES"
.IX Subsection "EXAMPLES"
The following examples illustrate some typical command lines. They assume that Impressive can be run by simply typing "\fBimpressive\fR" on the command line. Depending on how Impressive is installed, this has to be substituted with the actual way to run Impressive (e.g. "\fBpython ~/\:impressive/\:impressive_dev.py\fR" for a fresh SVN checkout). Furthermore, the file "\fBdemo.pdf\fR" is used as the document to show here; obviously this has to be replaced by the path to the actual PDF file too.
.PP
In the simplest case, Impressive is run directly with the name of the file to show and no further parameters. This will start a full\-screen presentation with all settings at their defaults:
.br
\fB    impressive demo.pdf\fR
.PP
To just quickly check a slide deck, it might make sense to run Impressive in a small window and not full\-screen. This can be done with something like
.br
\fB    impressive \-f \-g 800x600 demo.pdf\fR
.PP
Impressive can also be used in digital signage scenarios, like displays in shop windows with a permanent slideshow. This can be achieved by having Impressive advance to the next page automatically after a specified time (e.g. 10 seconds) and re\-start the presentation from the start after the last slide:
.br
\fB    impressive \-a 10 \-w demo.pdf\fR
.PP
.SH "USAGE"
.IX Header "USAGE"
On startup, Impressive will display a black screen with the program logo at the center. If caching is enabled, but background rendering is disabled, all pages of the presentation will then be rendered once. A bar in the lower half of the screen displays the progress of this operation. Any key (except for Q and Esc) or mouse click skips this process, with the effect that Impressive will render the remaining pages on demand. Please note that the overview page will not be complete until every page has been rendered at least once. In other words, if the precaching process was skipped, placeholders will be displayed for all pages that have not been rendered yet. By default, Impressive will build up the cache in the background while the presentation runs. Thus, the progress bar will not appear and the preparation will only take the amount of time required to render the first two pages of the presentation.
.PP
After this initialization process, Impressive will switch to the first page directly and without any transition.
.SH "CONTROLS"
.IX Header "CONTROLS"
.br
\fBEsc\fR key 
.RS
Return from the currently active special mode (zoom, overview, spotlight, highlight boxes); if no such special mode is active, quit Impressive altogether.
.RE
.PP
.br
\fBQ\fR key 
.RS
Quit Impressive immediately.
.RE
.PP
.br
\fBLMB\fR (left mouse button), mouse wheel down, \fBPage Down\fR key, \fBCursor Down\fR key, \fBCursor Right\fR key or \fBSpacebar\fR 
.RS
Go to the next page (using a transition).
.RE
.PP
.br
\fBRMB\fR (right mouse button), mouse wheel up, \fBPage Up\fR key, \fBCursor Up\fR key, \fBCursor Left\fR key or \fBBackspace\fR key 
.RS
Go to the previous page (using a transition).
.RE
.PP
.br
\fBHome\fR key /\: \fBEnd\fR key 
.RS
Go directly to the first or last page of the presentation.
.RE
.PP
.br
\fBCtrl\fR key \fI(modifier)\fR 
.RS
If one of the page navigation keys (Page Up/\:Down, Cursor keys, Space, Backspace, Home, End) is pressed while the Ctrl key is held down, the destination page will be entered immediately, without a transition.
.RE
.PP
.br
\fBL\fR key 
.RS
Return to the last (most recently displayed) page. This can be used to toggle back and forth between two pages.
.RE
.PP
.br
\fBF\fR key 
.RS
Toggle fullscreen mode.
.RE
.PP
.br
\fBTab\fR key 
.RS
Zoom back to the overview page. While in overview mode, a page can be selected with the mouse and activated with the left mouse button. The right or middle mouse button or the Tab key leave overview mode \fIwithout\fR changing the current page.
.RE
.PP
.br
\fBMMB\fR (middle mouse button) 
.RS
In normal display mode, this acts like the Tab key: it zooms back to the overview page. If the page is zoomed in, it will return to normal mode.
.RE
.PP
.br
\fBLMB\fR over a PDF hyperlink 
.RS
Jump to the page referenced by the hyperlink. Two types of hyperlinks are supported: Links that point to some other page of the same document, and URL hyperlinks like Web links and e\-mail addresses. This feature is only available if \fBpdftk\fR is installed. Furthermore, \fBxdg\-open\fR from the freedesktop.org Portland project is required for URL links to work.
Please note that the hyperlink feature will not work properly when pages are rotated.
.RE
.PP
.br
click&drag with \fBLMB\fR (left mouse button) 
.RS
Create a new highlight box. While at least one highlight box is defined on the current page, the page itself will be shown in a darker and blurry rendition. Only the highlight boxes will be displayed in their original lightness and sharpness.
.br
If a page with highlight boxes is left, the boxes will be saved and restored the next time this page is shown again.
.RE
.PP
.br
\fBRMB\fR (right mouse button) over a highlight box 
.RS
If the right mouse button is clicked while the mouse cursor is above a highlight box, the box will be removed. If the last box on a page is removed, the page will turn bright and sharp again.
.RE
.PP
.br
\fBS\fR key 
.RS
Save the info script associated with the current presentation. The main purpose for this is to permanently save highlight boxes or keyboard shortcuts, so they will be restored the next time this presentation is started.
.RE
.PP
.br
\fBT\fR key 
.RS
Activate or deactivate the time display at the upper\-right corner of the screen. If the timer is activated while the very first page of the presentation is shown, it activates "time tracking" mode. In this mode, a report of all pages visited with their display duration, enter and leave times will be written to standard output. This can be very useful when preparing presentations.
.RE
.PP
.br
\fBR\fR key 
.RS
Reset the presentation timer.
.RE
.PP
.br
\fBC\fR key 
.RS
Removes ("clears") all highlight boxes from the current page.
.RE
.PP
.br
\fBReturn\fR key or \fBEnter\fR key 
.RS
Toggle spotlight mode. In this mode, the page is darkened in the same way as if highlight boxes are present, but instead of (or in addition to) the boxes, a circular "spotlight" will be shown around the mouse cursor position, following every motion of the mouse cursor.
.RE
.PP
.br
\fB+\fR /\: \fB-\fR key, \fB9\fR /\: \fB0\fR key or mouse wheel in spotlight mode 
.RS
Adjust the spotlight radius.
.RE
.PP
.br
\fBCtrl\fR+\fB9\fR or \fBCtrl\fR+\fB0\fR keys 
.RS
Resets the spotlight radius to the default value, i.e. the value that has been set up by the \fBradius\fR page property, the \fB\-\-spot\-radius\fR command\-line option or Impressive's built\-in default.
.RE
.PP
.br
\fB7\fR /\: \fB8\fR key 
.RS
Adjust the amount of darkening applied to the page in spotlight or highlight box mode.
.RE
.PP
.br
\fBCtrl\fR+\fB7\fR or \fBCtrl\fR+\fB8\fR keys 
.RS
Resets the amount of darkening in spotlight or highlight box mode to the default value, i.e. the value that has been set up by the \fBdarkness\fR page property, the \fB\-\-darkness\fR command\-line option or Impressive's built\-in default.
.RE
.PP
.br
\fBZ\fR key 
.RS
Toggle zoom mode. When this key is first pressed, the current page will zoom in. The page will be displayed at double size, but in its original resolution (i.e. it will be blurry). Impressive will re\-render the page at the new resolution if the graphics hardware supports it. During this time, Impressive will \fBnot\fR accept any input, so don't even think about clicking the mouse or pressing keys before the image gets crisp again.
.br
In zoom mode, all other functions will work as normal. Any operations that leave the current page, such as flipping the page or entering the overview screen, will leave zoom mode, too.
.RE
.PP
.br
\fB[\fR /\: \fB]\fR key 
.RS
Adjust the gamma value of the display (might not be supported on every hardware).
.RE
.PP
.br
\fB{\fR /\: \fB}\fR key 
.RS
Adjust the black level of the display (might not be supported on every hardware).
.RE
.PP
.br
\fB\\\fR key 
.RS
Revert gamma and black level back to normal.
.RE
.PP
.br
\fBO\fR key 
.RS
This will toggle the "visible on overview page" flag of the current page. The result will not be visible immediately, but it can be saved to the info script (using the \fBS\fR key) and will be in effect the next time the presentation is started.
.RE
.PP
.br
\fBI\fR key 
.RS
This will toggle the skip flag of the current page. A page marked as skipped will not be reachable with the normal forward/\:backward navigation keys.
.RE
.PP
.br
\fBB\fR /\: \fBW\fR key or \fB.\fR (dot) /\: \fB,\fR (comma) key 
.RS
Fade to black or white, respectively. This feature can be used if a whiteboard or blackboard in front of the projection area is to be used during the presentation. Using these two keys, the screen will fade into a solid color. On any keypress or mouse click, it will fade back to normal. These keys are not available in overview mode.
.RE
.PP
.br
click&drag with \fBRMB\fR (right mouse button) in zoom mode 
.RS
Move the visible part of the page in zoom mode.
.RE
.PP
.br
\fBCursor\fR keys in overview mode 
.RS
Navigate through pages.
.RE
.PP
.br
\fBAlt\fR+\fBTab\fR keys 
.RS
If Impressive is in fullscreen mode, the window will be minimized so that other applications can be used.
.RE
.PP
.PP
Any other alphanumeric (A\-z, 0\-9) or function key (F1\-F12) can be used to assign shortcuts to pages that require quick access. If one of the keys is pressed together with \fBShift\fR, the currently displayed page is associated with this key. To recall the page later, it is sufficient to press the shortcut key again. Shortcuts can be permanently stored with the \fBS\fR key.
.PP
.SH "INFO SCRIPTS"
.IX Header "INFO SCRIPTS"
Impressive offers a powerful way to customize individual presentations using so\-called info scripts. An info script is a text file having the same name and located in the same directory as the presentation file itself, except for the additional suffix \fB.info\fR. Thus, a presentation file called \fBBrandNewProduct.pdf\fR would have a info script with the name \fBBrandNewProduct.pdf.info\fR. If multiple arguments were specified on the command line, the info script will be called just \fB.info\fR (a dot file, so to speak). If a directory name was specified as the only argument, either a file called \fB\fIDirectoryName\fR.info\fR or a file called \fB.info\fR \fIinside\fR the directory will be used, depending on whether a path separator was specified at the end of the directory name or not - Impressive simply appends \fB.info\fR to whatever the input path name was.
.br
In any case, the default file name can be overridden by the \fB\-I\fR command line option.
.PP
Info scripts are actually Python scripts with full access to Impressive's global data structures and functions. (It is possible to write real interactive applications using info scripts.) Thus, they can modify a broad range of settings concerning Impressive. This manual will only cover the most basic ones.
.PP
.SH "    PAGE PROPERTIES"
.IX Subsection "PAGE PROPERTIES"
The main part of an info script defines the properties of each page. At the moment, the following properties are defined:
.PP
.br
\fBtitle\fR 
.RS
Each page can have a title that is displayed in the Impressive window's title bar. If there is no title explicitly specified in the info script, the title of the page will be extracted from PDF metadata if pdftk is installed, or the image file name will be used if the presentation is an image slideshow.
.RE
.PP
.br
\fBtransition\fR 
.RS
With this property, the transition class to be used for rendering the transition between this page and the following page can be specified. For pages lacking this property, random transitions will be chosen. A list of available transition classes can be obtained with \fBimpressive \-l\fR.
.RE
.PP
.br
\fBtranstime\fR 
.RS
This property overrides the global transition time parameter (\fB\-T\fR at the command line). It contains the integer time (in milliseconds) the transition between this page and the following page shall be shown.
.RE
.PP
.br
\fBoverview\fR 
.RS
This property holds a boolean value (0/\:\fBFalse\fR or 1/\:\fBTrue\fR) that specifies whether the page shall be included in the overview page. If this property isn't specified, it is assumed to be \fBTrue\fR.
.RE
.PP
.br
\fBskip\fR 
.RS
This boolean property can be set to 1/\:\fBTrue\fR if the page shall be skipped during the presentation.
.br
Pages with \fBoverview:True, skip:False\fR will be accessible both by cycling through the pages and using the overview page,
.br
pages with \fBoverview:True, skip:True\fR will be silently skipped in the normal page cycle, but remain accessible from the overview page,
.br
pages with \fBoverview:False, skip:False\fR will appear in the normal cycle, but not on the overview page
.br
and pages with \fBoverview:False, skip:True\fR will not be accessible at all.
.RE
.PP
.br
\fBboxes\fR 
.RS
This property stores a list of highlight box coordinates. Normally, there is no need to edit this by hand, as Impressive handles this automatically if the \fBS\fR key is pressed.
.RE
.PP
.br
\fBtimeout\fR 
.RS
If a \fBtimeout\fR property is present and the page is shown, Impressive will automatically switch to the next page after the specified number of milliseconds. Normally, the timeout will only be effective the first time the page is shown unless wrap mode is used (command\-line option \fB\-w\fR or \fB\-\-wrap\fR). This restriction makes it possible to create self\-running presentations with individual per\-page timeouts.
.RE
.PP
.br
\fBradius\fR 
.RS
This property takes an integer value that, if defined, will be used to set a new spotlight radius every time the page is entered. This overrides the current setting as defined by the \fB\-\-spot\-radius\fR command line option or run\-time adjustments. Note that the value is \fInot\fR reset to the default value after the page has been left again.
.RE
.PP
.br
\fBdarkness\fR 
.RS
This property takes an integer or floating\-point percentage value that, if defined, will be used to set the background darkness in spotlight or highlight box mode each time the page is entered. This overrides the current setting as defined by the \fB\-\-darkness\fR command line option or run\-time adjustments. Note that the value is \fInot\fR reset to the default value after the page has been left again.
.RE
.PP
.br
\fBcomment\fR 
.RS
This property can hold a string with a single line of text that will be displayed on screen while the page is shown. Display of this text can not be disabled.
.RE
.PP
.br
\fBsound\fR 
.RS
Specifies the file name of a sound file to be played (via MPlayer) when the page is first entered. Once started, the sound will be played until its end is reached, another sound or video is played, or Impressive is exited.
.RE
.PP
.br
\fBvideo\fR 
.RS
Specifies the file name of a video file to be played when the page is first entered. The video will be displayed full\-screen. Any key or mouse click stops playback, except the cursor keys, which are used to seek in the video file, and space, which can be used to pause playback. Note that this function is highly experimental and might not work reliably on every system!
.RE
.PP
.br
\fBalways\fR 
.RS
If this property is present and set to 1 or \fBTrue\fR, the media file specified in the \fBsound\fR or \fBvideo\fR properties will be played every time the page is entered, not just the first time.
.RE
.PP
.br
\fBprogress\fR 
.RS
If this property is set to zero, the presentation progress bar (which is usually set up with the \fB\-d\fR/\:\fB\-\-duration\fR command line switch) will not be shown on this page. In practice, it might be useful to hide the bar from the first page so that it is not visible during the introduction.
.RE
.PP
.br
\fBreset\fR 
.RS
If this property is set to 1 or \fBTrue\fR, the timer will be reset each time this page is left, just as if the \fBR\fR has been pressed. If the special value 2 or \fBFirstTimeOnly\fR is used, the reset will only take place if the page was shown for the first time. Again, this is particularly useful on the first page: A combination of \fBprogress:False, reset:FirstTimeOnly\fR makes it possible to set up the presentation long before it actually begins - the first page can be showed as long as desired, actual timing starts at the second page.
.RE
.PP
.br
\fBrotate\fR 
.RS
This property is a per\-page override of the global \fB\-r\fR command line option: It specifies how the page shall be rotated, in 90\-degree steps clockwise.
.RE
.PP
.br
\fBOnEnter\fR, \fBOnLeave\fR, \fBOnEnterOnce\fR, \fBOnLeaveOnce\fR 
.RS
These properties can contain a Python callable (i.e. a function reference or lambda expression) that is executed when the page is entered or left. The \fB~Once\fR variants will only be executed when the page is entered or left for the first time. The callable must not take any arguments. This feature can be used to associate arbitrary Python code with specific pages, for example to execute external programs.
.br
\fBWarning:\fR Lambda expressions cannot be properly processed by the Info Script save function (\fBS\fR key). If Impressive encounters lambda expressions when saving, it will remove them. In addition, it will not overwrite the original info script, but generate an extra file that needs to be merged withe the original script by hand.
.RE
.PP
.br
\fBkeys\fR 
.RS
This property can be assigned a dictionary that maps alphanumerical keys to Python functions. For example, \fB'keys': { 'x': SomeFunction }\fR will invoke \fBSomeFunction()\fR if the lowercase character 'x' is typed while the page is displayed. Regarding the functions, the same restrictions as for the \fBOnEnter\fR/\:\fBOnLeave\fR family apply: the function must not take any parameters and lambda functions can not be saved. Also note that it is not possible to overwrite Impressive's pre\-defined key bindings with this method.
.RE
.PP
.br
\fBinvert\fR 
.RS
This property specifies whether the colors of that page shall be inverted in the same way the \fB\-\-invert\fR command\-line switch does. It overrides the \fB\-\-invert\fR setting on a per\-page basis: If set to \fBTrue\fR, the page will always be inverted; if set to \fBFalse\fR, the page will never be inverted even if \fB\-\-invert\fR has been specified on the command line.
.RE
.PP
The properties are stored together in a Python dictionary called \fBPageProps\fR. The syntax looks like in this example:
.PP
.nf
.ne 11
\&  PageProps = {
\&    1: {
\&         'title': "Title Page",
\&         'transition': PagePeel,
\&         'sound': "background_music.mp3"
\&       },
\&    2: {
\&         'title': "Another Page",
\&         'timeout': 5000
\&       }
\&  }
.
.fi
.PP
The PageProps definition (and \fBonly\fR the PageProps definition) will be rewritten by Impressive if the \fBS\fR key is pressed. User\-defined PageProps entries will also be left untouched, except for some pretty\-printing.
.PP
.SH "    GLOBAL PRESENTATION PROPERTIES"
.IX Subsection "GLOBAL PRESENTATION PROPERTIES"
The name of the presentation is shown in the title bar of the Impressive window (if not in fullscreen mode). By default, the file name or (if available) PDF metadata title will be used for this purpose, but the presentation title can also be explicitly set by overwriting the \fBDocumentTitle\fR variable:
.br
\fB    DocumentTitle = "My Presentation"\fR
.PP
Another useful variable, \fBAvailableTransitions\fR, contains a list of all transition classes that may be used for randomly assigning transitions to pages lacking the \fBtransition\fR property. Thus, if a certain transition is undesired (either because of personal dislike or because it shall be used exclusively on pages where it is manually assigned using \fBPageProps\fR), something like the following can be written:
.br
\fB    AvailableTransitions.remove(WipeBlobs)\fR
.br
On the other side, it's possible to activate transitions that are not enabled by default:
.br
\fB    AvailableTransitions += [SlideUp, SlideDown]\fR
.br
Alternatively, \fBAvailableTransitions\fR can be completely overwritten to have the same transition (or set of transitions) assigned to all pages:
.br
\fB    AvailableTransitions = [Crossfade]\fR
.PP
.SH "    OPTION OVERRIDES"
.IX Subsection "OPTION OVERRIDES"
Another use of info scripts is overriding the default or command\-line settings on a per\-file basis. This can be done by simply overwriting one of the variables that are defined at the beginning of \fBimpressive.py\fR. Each of these variables corresponds either to a command\-line setting, or to some constant related to visual appearance or performance. So, for example, to force fullscreen mode for a presentation, write
.br
\fB    Fullscreen = True\fR
.PP
.SH "    WORKING DIRECTORIES"
.IX Subsection "WORKING DIRECTORIES"
The working directory while executing the info scripts themselves is always the directory in which the info script is stored in.
.PP
The base directory for external actions that originate from Page Properties or PDF hyperlinks is always the directory of the PDF or image file this page belongs to. In other words, if e.g. \fB'sound': "music.mp3"\fR is written in the info script for one page of \fBpresentation.pdf\fR, the file \fBmusic.mp3\fR is expected to be located in the same directory as \fBpresentation.pdf\fR.
.PP
.SH "AUTHOR"
.IX Header "AUTHOR"
Impressive and its documentation has been written mainly by Martin J. Fiedler <martin.fiedler@gmx.net>, with small portions of the code written by external contributors. See the source code file for details.
.SH "REPORTING BUGS"
.IX Header "REPORTING BUGS"
Report bugs to to <martin.fiedler@gmx.net>.