<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&okular;">
  <!ENTITY package "kdegraphics">
  <!ENTITY kpdf "<application>KPDF</application>">
  <!ENTITY PDF "<acronym>PDF</acronym>">
  <!ENTITY % English "INCLUDE">
  <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">
	<bookinfo>
		<title>The &okular; Handbook</title>
		<authorgroup>
			<author>
				<firstname>Albert</firstname>
				<surname>Astals Cid</surname>
				<affiliation>
					<address><email>aacid@kde.org</email></address>
				</affiliation>
			</author>
			<author>
				<firstname>Pino</firstname>
				<surname>Toscano</surname>
				<affiliation>
					<address><email>pino@kde.org</email></address>
				</affiliation>
			</author>
			<!-- TRANS:ROLES_OF_TRANSLATORS -->
		</authorgroup>
		<legalnotice>&FDLNotice;</legalnotice>
		<date>2009-01-25</date>
		<releaseinfo>0.8</releaseinfo>
		<!-- Abstract about this handbook -->
		<abstract>
			<para>&okular; is a &kde; universal document viewer based on &kpdf; code.</para>
		</abstract>
		<keywordset>
			<keyword>KDE</keyword>
			<keyword>okular</keyword>
			<keyword>pdf</keyword>
			<keyword>ps</keyword>
			<keyword>tiff</keyword>
			<keyword>djvu</keyword>
			<keyword>dvi</keyword>
			<keyword>chm</keyword>
			<keyword>xps</keyword>
		</keywordset>
	</bookinfo>
	<chapter id="introduction">
		<title>Introduction</title>
		<para>&okular; is a &kde; universal document viewer based on the code of the &kpdf; application.
			Although being based on &kpdf; code, &okular; has some unique features such as overview mode,
			improved presentation support and annotation support.
		</para>
<!--
		<para>
			The PDF format is widely used for publishing documents that are
			mostly not meant to be edited again. &okular; is only a viewer
			for these files and therefore it doesn't provide any functionality
			to edit or create PDF documents.
		</para>
-->
	</chapter>
	<chapter id="use">
		<title>Basic Usage</title>
		<sect1 id="opening">
			<title>Opening Files</title>
			<para>
				To view any supported file in &okular;, select <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem>
				</menuchoice>, choose a supported file in the dialogue and click <guibutton>Open</guibutton>.
				Your file should now be displayed in the main window.
			</para>
			<para>
				If you have already opened files in &okular; before, you can quickly access them by selecting them in
				the <menuchoice><guimenu>File</guimenu><guisubmenu>Open Recent</guisubmenu></menuchoice> menu.
			</para>
			<para>
				After having a file opened you probably want to read it and therefore navigate through it. Go to the
				<link linkend="navigating">next section</link> to learn more about this.
			</para>
		</sect1>
		<sect1 id="navigating">
			<title>Navigating</title>
			<para>This section describes how you can navigate through a document in &okular;.</para>
			<para>
				There are multiple ways of scrolling the viewing area. One is to use the 
				<keycap>Up Arrow</keycap> and <keycap>Down Arrow</keycap> keys. You may also use
				the scrollbar, your mousewheel or the <keycap>Page Up</keycap> and <keycap>Page Down</keycap>
				keys.
			</para>
			<para>
				Another way is to hold the &LMB; down at any place on the document while dragging the mouse in the
				opposite direction of where you want to move. This procedure only works if the Browse Tool is
				enabled, which you can select by choosing <menuchoice><guimenu>Tools</guimenu><guimenuitem>Browse Tool
				</guimenuitem></menuchoice>.
			</para>
			<para>
				The navigation panel on the left side of the screen enables two more ways of navigating
				through a document:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						If you click on a page thumbnail the viewing area will be brought to
						that page.
					</para>
				</listitem>
				<listitem>
					<para>
						If the document has a table of contents, clicking on a table
						of contents item will bring the document to to the page linked to that
						item.
					</para>
				</listitem>
			</itemizedlist>
			<para>
				Some documents have links. In this case you can click on them and the view will
				change to the page it links to. If the link is to a web page or some
				other document the default &kde; handler for that format will be invoked.
			</para>
			<para>
				Additionally, you may use the following functionality to quickly move to specific places
				in the document:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						You can go to the first page of the document using 
						<keycombo action="simul">&Ctrl;<keycap>Home</keycap></keycombo> or
						using 
						<menuchoice>
							<guimenu>Go</guimenu>
							<guimenuitem>First Page</guimenuitem>
						</menuchoice>.
					</para>
				</listitem>
				<listitem>
					<para>
						You can go to the last page of the document using 
						<keycombo action="simul">&Ctrl;<keycap>End</keycap></keycombo> or
						using 
						<menuchoice>
							<guimenu>Go</guimenu>
							<guimenuitem>Last Page</guimenuitem>
						</menuchoice>.
					</para>
				</listitem>
				<listitem>
					<para>
						You can go forward in the document using <keycap>Space</keycap> or <keycap>Page Down</keycap>.
						To go to the next page of the document use the <guibutton>Next Page</guibutton> Toolbar
						button or 
						<menuchoice>
							<guimenu>Go</guimenu>
							<guimenuitem>Next Page</guimenuitem>
						</menuchoice> in the menubar.
					</para>
				</listitem>
				<listitem>
					<para>
						You can go back in the document using <keycap>Backspace</keycap> or <keycap>Page Up</keycap>.
						To go to the previous page of the document use <guibutton>Previous Page</guibutton> Toolbar
						button or 
						<menuchoice>
							<guimenu>Go</guimenu>
							<guimenuitem>Previous Page</guimenuitem>
						</menuchoice> in the menubar.
					</para>
				</listitem>
			</itemizedlist>
		</sect1>
		<sect1 id="presentationMode">
			<title>Presentation Mode</title>
			<para>
				The Presentation mode represents another way to view documents in &okular;. It can be
				enabled in
				<menuchoice><guimenu>View</guimenu><guimenuitem>Presentation</guimenuitem></menuchoice>.
				It shows the document on a page per page basis. The pages are shown with
				zoom to page, that means all the page is visible. 
			</para>
			<note>
				<para>
					&PDF; documents can even specify that they are always opened in presentation mode.
				</para>
			</note>
			<para>
				When in presentation mode, you have an helper bar located on the top of the screen. Just move
				the mouse cursor to the top of the screen to make it appear.
			</para>
			<para>
				To navigate between
				pages you may use the &LMB; (next page) and the &RMB; (previous page), the mouse
				wheel, the arrow icons or the line edit in the top bar,
				or the keys specified in the <link linkend="navigating">Navigating</link>
				section.
			</para>
			<para>
				You can exit presentation mode at any time by pressing the <keycap>ESC</keycap> key or clicking
				the <guiicon>Quit</guiicon> icon in the top bar.
			</para>
			<para>
				You can also draw on the current page with a pencil. Click on the
				<guilabel>Toggle Drawing Mode</guilabel> icon in the top bar to enable or disable the possibility
				of draw in the presentation mode. The drawings are cleared automatically when switching to
				another page, or manually selecting the <guilabel>Erase Drawings</guilabel> icon in the top bar.
			</para>
			<para>
				The presentation mode has support for more than one screen in a multi-monitor configuration. 
				With more than one screen a new button will appear in the top bar, with the icon of a screen: 
				this is a drop down box that allows you to move the presentation to any of the other available screens.
			</para>
			<para>
				Presentation mode has some configuration options, you can find their
				description in the chapter <link linkend="configpresentation">Configuring &okular;</link>.
			</para>
		</sect1>
	</chapter>

	<chapter id="advanced">
		<title>&okular; Advanced Features</title>
		<sect1 id="embedded-files">
			<title>Embedded Files</title>
			<para>
				If the current document has some files embedded in it, when you open it a yellow bar
				will appear above the page view to notify you about the embedded files.  
			</para>
			<screenshot>
				<screeninfo>The embedded files bar</screeninfo>
				<mediaobject>
					<imageobject>
						<imagedata fileref="embedded-files-bar.png" format="PNG" />
					</imageobject>
					<textobject>
						<phrase>The embedded files bar</phrase>
					</textobject>
				</mediaobject>
			</screenshot>
			<para>
				In this case, you can either click on the link in the text of the bar or choose
				<menuchoice><guimenu>File</guimenu><guimenuitem>Embedded Files</guimenuitem></menuchoice>
				to open the embedded files dialog. The dialog allows you to view the embedded files and
				to extract them.
			</para>
		</sect1>
		<sect1 id="annotations">
			<title>Annotations</title>
			<para>
				&okular; allows you to review and annotate your documents. Annotations created in &okular; are saved internally in the local data folder for each user.
			</para>
			<para>
				Since &kde; 4.2, &okular; has the "document archiving" feature. This is an &okular;-specific format for carrying the document plus various metadata related to it (currently only annotations). You can save a "document archive" from the open document by choosing <menuchoice><guimenu>File</guimenu><guisubmenu>Export As</guisubmenu><guimenuitem>Document Archive</guimenuitem></menuchoice>. To open an &okular; document archive, just open it with &okular; as it would be &eg; a &PDF; document.
			</para>
				<note>
					<para>
						Due to DRM limitations (typically with &PDF; documents), adding, editing some properties
						or removing annotations could not be possible.
					</para>
				</note>
			<sect2 id="annotations-add">
				<title>Adding annotations</title>
				<para>
					To add some annotations to the document, you have to activate the annotating toolbar.
					This is done by either selecting
					<menuchoice><guimenu>Tools</guimenu><guimenuitem>Review</guimenuitem></menuchoice> or
					pressing <keycap>F6</keycap>. Once the annotating toolbar is shown, just press one of
					its buttons to start constructing that annotation.
				</para>
				<note>
					<para>
						The annotating toolbar can be docked in any side of the viewing area: just drag it to
						move it to another place.
					</para>
				</note>
				<note>
					<para>
						Activating the annotating toolbar will make you switch to the Normal Mode.
					</para>
				</note>
				<para>
					You can stop the construction any time by pressing again on the button of the
					annotation you are constructing.
				</para>
				<para>
					The newly constructed annotation will have as author the author you set in the
					<guilabel>Identity</guilabel> page in &okular;s
					<link linkend="configure">configuration</link> dialog.
				</para>
			</sect2>
			<sect2 id="annotations-remove">
				<title>Removing annotations</title>
				<para>
					To remove an annotation, just click on it with the &RMB;, and select
					<guimenuitem>Delete</guimenuitem>.
				</para>
				<para>
					When removing the annotation, its window will be closed if open.
				</para>
				<note>
					<para>
						This option could not be enabled because the document does not allow removing
						annotations.
					</para>
				</note>
			</sect2>
			<sect2 id="annotations-edit">
				<title>Editing annotations</title>
				<para>
					To edit an annotation, click on it with the &RMB; and select
					<guimenuitem>Properties</guimenuitem>. A dialog will appear with the general
					annotation settings (like color and opacity, author, &etc;) and the settings specific
					to that annotation type.
				</para>
				<para>
					To move an annotation, hold down the &Ctrl; key, move the mouse pointer on it and 
					then start dragging with the &LMB;.
				</para>
				<note>
					<para>
						Depending on the document permissions (typically with &PDF; documents), some options
						can be disabled.
					</para>
				</note>
			</sect2>
		</sect1>
	</chapter>
			
	<chapter id="primary-menu-items">
		<title>The Menubar</title>

		<sect1 id="menufile">
			<title>The <guimenu>File</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut>
								<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
							</shortcut>
							<guimenu>File</guimenu>
							<guimenuitem>Open...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Open</action> a supported file or okular archive. If there is already an opened file it will be closed. For more information, see the section about <link linkend="opening">Opening Files</link>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guisubmenu>Open Recent</guisubmenu>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Open</action> a file which was used previously from a
							submenu. If a file is currently being displayed it
							will be	closed. For more information, see the section about 
							<link linkend="opening">Opening Files</link>.
						</para>
					</listitem>
				</varlistentry>
				<!--
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>G</keycap></shortcut>
							<guimenu>File</guimenu>
							<guimenuitem>Get Books From Internet...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>to be written</para>
					</listitem>
				</varlistentry>
				<-->
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guimenuitem>Import PostScript as &PDF;...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Open</action> a PostScript file and convert it to &PDF;.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guimenuitem>Save As...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Save</action> the currently open file under a different name using the document backend. With the &PDF; backend (Poppler >= 0.8 required) it is possible to save the document with the changed values of the form fields.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guimenuitem>Save Copy As...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Save</action> a copy of the currently open file under a different name 
						without using the current document backend.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>F5</keycap></shortcut>
							<guimenu>File</guimenu>
							<guimenuitem>Reload</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Reload</action> the currently open file.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></shortcut>
							<guimenu>File</guimenu>
							<guimenuitem>Print...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Print</action> the currently displayed document.
						</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guimenuitem>Print Preview...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Show a preview</action> of how the currently displayed
							document would be printed with the default options.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guimenuitem>Properties</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Display some basic information</action> about the document, such as
							title, author, creation date, and details about the fonts used. The available information
							depends on the type of document.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guimenuitem>Embedded Files...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Show the files embedded</action> in the document, if the document has any.
							For more information, see the section about the
							<link linkend="embedded-files">Embedded Files</link>.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>File</guimenu>
							<guisubmenu>Export As</guisubmenu>
						</menuchoice>
					</term>
					<listitem>
						<para>This item contains the export formats the current document can be exported to.
						The first entry for all kind of documents is always <guimenuitem>Plain Text...</guimenuitem></para>
						<para>The second entry is <guimenuitem>Document Archive</guimenuitem>, which allows you to save the document with your annotations into an &okular;-specific archive format. Thus it is easily possible to share the original document and your annotations with other &okular; users or work with them collaboratively.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut>
							<guimenu>File</guimenu>
							<guimenuitem>Quit</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Close</action> &okular;.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>

		<sect1 id="menuedit">
			<title>The <guimenu>Edit</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut>
							<guimenu>Edit</guimenu>
							<guimenuitem>Copy</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Copy</action> the currently selected text in 
						<guibutton>Text Selection</guibutton> mode to the clipboard.</para>
					</listitem>
				</varlistentry>
			</variablelist>

			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut>
							<guimenu>Edit</guimenu>
							<guimenuitem>Select All</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Selects</action> all the text (if the document provides it). This works only in 
						<guibutton>Text Selection</guibutton> mode.</para>
					</listitem>
				</varlistentry>
			</variablelist>

			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut>
							<guimenu>Edit</guimenu>
							<guimenuitem>Find...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							Show the find bar on the bottom of the viewing area that allows you to
							<action>search for a string in the document</action>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>F3</keycap></shortcut>
							<guimenu>Edit</guimenu>
							<guimenuitem>Find Next</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>Try to <action>find the previous searched string again</action> in the document.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		
		<sect1 id="menuview">
			<title>The <guimenu>View</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>P</keycap></keycombo></shortcut>
							<guimenu>View</guimenu>
							<guimenuitem>Presentation</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Activates</action> the Presentation Mode. For more information, see the
							section about <link linkend="presentationMode">Presentation Mode</link>.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo></shortcut>
							<guimenu>View</guimenu>
							<guimenuitem>Zoom In</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Increase the magnification</action> of the document view.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo></shortcut>
							<guimenu>View</guimenu>
							<guimenuitem>Zoom Out</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Decrease the magnification</action> of the document view.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guimenuitem>Fit Width</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Change the magnification</action> of the document
							view to a value that makes the pages' width equal to the document
							view's width.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guimenuitem>Fit Page</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Change the magnification</action> of the document view
							to a value that makes at least one whole page visible.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guimenuitem>Continuous</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Enable the continuous page mode</action>. In continuous mode,
							all pages of the document are shown, and you can scroll through
							them without having to use the <menuchoice><guimenu>Go</guimenu>
							<guimenuitem>Previous Page</guimenuitem></menuchoice> and
							<menuchoice><guimenu>Go</guimenu><guimenuitem>Next Page</guimenuitem>
							</menuchoice> options.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guisubmenu>View Mode</guisubmenu>
						</menuchoice>
					</term>
					<listitem>
						<para>This submenu makes you choose the view mode for the pages. The possible
							options are: <guimenuitem>Single Page</guimenuitem> (only one page per row),
							<guimenuitem>Facing Pages</guimenuitem> (two pages per row, in a book style) and
							<guimenuitem>Overview</guimenuitem> (the number of columns is the one
							specified in the <link linkend="configure">&okular; settings</link>).</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guisubmenu>Orientation</guisubmenu>
						</menuchoice>
					</term>
					<listitem>
						<para>
							This submenu allows you to <action>changes the orientation</action>
							of the pages of the document.
						</para>
						<note>
							<para>
								The rotation is applied to the orientation of every page.
							</para>
						</note>
						<para>
							You can select <guimenuitem>Original Orientation</guimenuitem> to restore
							the orientation of the document, discarding all the rotations applied
							manually.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guisubmenu>Page Size</guisubmenu>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Changes the size of the pages</action> of the document.
						</para>
						<note>
							<para>
								This submenu is active only if the current type of document
								supports different page sizes.
							</para>
						</note>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guimenuitem>Trim Margins</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							Remove the white border of pages when viewing pages.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>View</guimenu>
							<guimenuitem>Show/Hide Forms</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Show or hides the display</action> of the form fields of the
							document.
						</para>
						<note>
							<para>
								This menu item is active only if the current document has form
								fields.
							</para>
						</note>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>

		<sect1 id="menugo">
			<title>The <guimenu>Go</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>Backspace</keycap></shortcut>
							<guimenu>Go</guimenu>
							<guimenuitem>Previous Page</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>View the previous page</action> of the document.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>Space</keycap></shortcut>
							<guimenu>Go</guimenu>
							<guimenuitem>Next Page</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>View the next page</action> of the document.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>Home</keycap></keycombo></shortcut>
							<guimenu>Go</guimenu>
							<guimenuitem>First Page</guimenuitem>
					  </menuchoice>
					</term>
					<listitem>
						<para><action>Go to the first page</action> of the document.</para>
				  </listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>End</keycap></keycombo></shortcut>
							<guimenu>Go</guimenu>
							<guimenuitem>Last Page</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Go to the last page</action> of the document.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Go</guimenu>
							<guimenuitem>Back in the Document</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Go back to the previous view</action> of the document.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Go</guimenu>
							<guimenuitem>Forward in the Document</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Move forward to the next view</action> of the document. This only works if you have already moved back before.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></shortcut>
							<guimenu>Go</guimenu>
							<guimenuitem>Go to Page...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>Open a dialog which allows you to <action>go to any page</action> of the document.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>

		<sect1 id="menubookmarks">
			<title>The <guimenu>Bookmarks</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></shortcut>
							<guimenu>Bookmarks</guimenu>
							<guimenuitem>Add/Remove Bookmark</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>
							<action>Add or remove a bookmark for the current page</action>.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Bookmarks</guimenu>
							<guimenuitem>Previous Bookmark</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Go to the previous bookmarked page</action>, or do nothing if there
							are no bookmarked pages prior to the current one.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Bookmarks</guimenu>
							<guimenuitem>Next Bookmark</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Go to the next bookmarked page</action>, or do nothing if there
							are no bookmarked pages after the current one.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Bookmarks</guimenu>
							<guimenuitem>No Bookmarks</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>This is an always disabled action that appears in this menu only if the current document has 
						no bookmarks. Otherwise a list of all bookmarked pages is displayed here. Clicking on these bookmarks
						allows you to go directly to the associated pages.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>

		<sect1 id="menutools">
			<title>The <guimenu>Tools</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>1</keycap></keycombo></shortcut>
							<guimenu>Tools</guimenu>
							<guimenuitem>Browse Tool</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>The mouse will have its normal behaviour, &LMB; for dragging the document and following links and &RMB; for adding bookmarks and fit to width.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>2</keycap></keycombo></shortcut>
							<guimenu>Tools</guimenu>
							<guimenuitem>Zoom Tool</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>The mouse will work as a zoom tool. Clicking &LMB; and dragging will zoom the view to the selected area, clicking &RMB; will bring the document back to the previous zoom.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>3</keycap></keycombo></shortcut>
							<guimenu>Tools</guimenu>
							<guimenuitem>Selection Tool</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>The mouse will work as a select tool. In that mode clicking &LMB; and dragging will give the option of copying the text/image of current selected area to the clipboard, speak a text or to save an image to a file.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>4</keycap></keycombo></shortcut>
							<guimenu>Tools</guimenu>
							<guimenuitem>Text Selection Tool</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>The mouse will work as a text selection tool. In that mode clicking &LMB; and
							dragging will give the option of selecting the text of the document. Then, just
							click with the &RMB; to copy to the clipboard or speak the current selection.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>F6</keycap></shortcut>
							<guimenu>Tools</guimenu>
							<guimenuitem>Review</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Open the review toolbar</action>. The review toolbar allows you to add
							annotations on the document you are reading. For more information, please see the
							section about <link linkend="annotations">Annotations</link>.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Tools</guimenu>
							<guimenuitem>Speak Whole Document</guimenuitem>
						</menuchoice>
					</term>
					<term>
						<menuchoice>
							<guimenu>Tools</guimenu>
							<guimenuitem>Speak Current Page</guimenuitem>
						</menuchoice>
					</term>
					<term>
						<menuchoice>
							<guimenu>Tools</guimenu>
							<guimenuitem>Stop Speaking</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>These items allow you to speak the whole document or just the current page and stop speaking using the &kde; Text-to-Speech system <application>KTTS</application>.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>

		<sect1 id="settings-menu">
			<title>The <guimenu>Settings</guimenu> Menu</title>
			<variablelist>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo></shortcut>
							<guimenu>Settings</guimenu>
							<guimenuitem>Show Menubar</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Toggle the Menubar display</action> on and off. Once
						hidden it can be made visible using the &RMB; menu.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Settings</guimenu>
							<guimenuitem>Show Toolbar</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Toggle the Toolbar display</action> on and off.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycap>F7</keycap></shortcut>
							<guimenu>Settings</guimenu>
							<guimenuitem>Show Navigation Panel</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Toggle the navigation panel</action> on and off.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo></shortcut>
							<guimenu>Settings</guimenu>
							<guimenuitem>Full Screen Mode</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para><action>Enables the full screen mode</action>. Note that
							full screen mode is different from <link
								linkend="presentationMode">presentation mode</link> insofar as the
							only peculiarity of full screen mode is that it hides the window
							decorations, the menubar and the toolbar.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Settings</guimenu>
							<guimenuitem>Configure Shortcuts...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>Opens a window that lets you <action>configure the keyboard
							shortcuts</action> for many menu commands.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Settings</guimenu>
							<guimenuitem>Configure Toolbars...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>Opens a window that lets you choose which icons are visible
							in the toolbar.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Settings</guimenu>
							<guimenuitem>Configure Backends...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>Opens the <link linkend="configure">Backend Configuration</link>
							window.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<menuchoice>
							<guimenu>Settings</guimenu>
							<guimenuitem>Configure &okular;...</guimenuitem>
						</menuchoice>
					</term>
					<listitem>
						<para>Opens the <link linkend="configure">Configure</link>
							window.</para>
					</listitem>
				</varlistentry>
				
			</variablelist>
		</sect1>
		<sect1 id="menuhelp">
			<title>The <guimenu>Help</guimenu> Menu</title>
			&help.menu.documentation;
		</sect1>
		
	</chapter>
	<chapter id="configure">
		<title>Configuring &okular;</title>
		<sect1 id="configindex">
			<title>General configuration</title>
			<para>
				You can configure &okular; by choosing <menuchoice><guimenu>Settings</guimenu>
				<guimenuitem>Configure &okular;...</guimenuitem></menuchoice>.
				The configuration dialogue is split into five sections. This chapter describes the available
				options in detail.
			</para>
			<itemizedlist>
				<listitem>
					<para><link linkend="configgeneral">General</link></para>
				</listitem>
				<listitem>
					<para><link linkend="configaccessibility">Accessibility</link></para>
				</listitem>
				<listitem>
					<para><link linkend="configperformance">Performance</link></para>
				</listitem>
				<listitem>
					<para><link linkend="configpresentation">Presentation</link></para>
				</listitem>
				<listitem>
					<para><link linkend="configidentity">Identity</link></para>
				</listitem>
			</itemizedlist>
			<screenshot>
				<screeninfo>The configuration dialogue</screeninfo>
				<mediaobject>
					<imageobject>
						<imagedata fileref="configure.png" format="PNG" />
					</imageobject>
					<textobject>
						<phrase>The configuration dialogue</phrase>
					</textobject>
				</mediaobject>
			</screenshot>
			<para>
				Depending on the currently installed backends, the <menuchoice><guimenu>Settings</guimenu>
				<guimenuitem>Configure Backends...</guimenuitem></menuchoice> menu item could be enabled.
				This particular configuration dialogue holds the configurations of the backends that can
				actually be configured.
			</para>
		</sect1>
		<sect1 id="configgeneral">
			<title>General</title>
			<variablelist>
				<varlistentry>
					<term><guilabel>Show scrollbars</guilabel></term>
					<listitem>
						<para>Whether to show scrollbars for the document view.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Link the thumbnails with the page</guilabel></term>
					<listitem>
						<para>Whether the thumbnails view should always display the current
							page or not.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Show hints and info messages</guilabel></term>
					<listitem>
						<para>Whether to show some informative messages on startup, file
							load, &etc;.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Obey DRM limitations</guilabel></term>
					<listitem>
						<para>Whether &okular; should obey <firstterm>DRM</firstterm>
							(Digital Rights Management) restrictions. DRM limitations are used
							to make it impossible to perform certain actions with &PDF; documents,
							such as copying content to the clipboard. Note that in some configurations
							of &okular;, this option is not available.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Reload document on file change</guilabel></term>
					<listitem>
						<para>Whether opened files should be automatically checked for
							changes and updated, if necessary.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Show backend selection dialog</guilabel></term>
					<listitem>
						<para>Whether &okular; should ask the user which backend to use in case of more
							than one backend able to open the current file. If unchecked, &okular; will
							use the backend with the highest priority.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Center first page</guilabel></term>
					<listitem>
						<para>Whether the first page should be centered or aligned to the left when
							displaying the pages in facing and overview mode.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Overview columns</guilabel></term>
					<listitem>
						<para>
							This options represent the number of columns to use in the overview mode.
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="configaccessibility">
			<title>Accessibility</title>
			<variablelist>
				<varlistentry>
					<term><guilabel>Draw border around links</guilabel></term>
					<listitem>
						<para>Whether to draw a border around links.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Change colors</guilabel></term>
					<listitem>
						<para><action>Enables</action> the color changing options.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Invert Colors</guilabel></term>
					<listitem>
						<para><action>Inverts</action> colors on the view, &ie; black objects will be shown white.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Change Paper Color</guilabel></term>
					<listitem>
						<para><action>Changes</action> the paper's color, &ie; the document's background.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Change Dark &amp; Light Colors</guilabel></term>
					<listitem>
						<para><action>Changes</action> the dark and light color to your preference, that means 
							black will not be rendered as black but as the selected dark color and white
							will not be rendered as white but as the selected light color.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Convert to Black &amp; White</guilabel></term>
					<listitem>
						<para><action>Converts</action> the document to black and white. You can set the
							threshold and the contrast. Setting the threshold to a higher value
							will result in darker grays used.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="configperformance">
			<title>Performance</title>
			<variablelist>
				<varlistentry>
					<term><guilabel>Enable transparency effects</guilabel></term>
					<listitem>
						<para>Draw selections and other special graphics using
							transparency effects. Disable the option to draw them using
							outline or opaque fill styles and increase speed on selections.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Enable background generation</guilabel></term>
					<listitem>
						<para>Use a background thread to generate the pages. By disabling
							this option the user interface will become less reactive (will be blocked
							if necessary), but pages will be displayed a bit faster.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Memory Usage</guilabel></term>
					<listitem>
						<para>&okular; can achieve best performance by tuning the memory usage, based on your system and your tastes.
							The more memory you let it to use, the faster the program will behave. The Default profile is good
							for every system, but you can prevent &okular; from using more memory than necessary by selecting the Low
							profile, or let it get the most out of your system using Aggressive.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="configpresentation">
			<title>Presentation</title>
			<variablelist>
				<varlistentry>
					<term><guilabel>Advance every</guilabel></term>
					<listitem>
						<para>Enables automatic advancing of pages given a time period.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Loop after last page</guilabel></term>
					<listitem>
						<para>When navigating on presentation mode and going past the last page the first page will appear.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Background color</guilabel></term>
					<listitem>
						<para>The color that will fill the part of the screen not covered by the page when on presentation mode.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Pencil color</guilabel></term>
					<listitem>
						<para>The color of the pencil used when drawing on the pages during the presentation mode.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Mouse cursor</guilabel></term>
					<listitem>
						<para>Whether the mouse should be always hidden, always shown or hidden after a small time of inactivity.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Show progress indicator</guilabel></term>
					<listitem>
						<para>Whether to show a progress circle that shows the current page and the total number of pages on the upper
							right corner of the presentation screen everytime you change the page.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Show summary page</guilabel></term>
					<listitem>
						<para>Whether to show a summary page at the beginning of the presentation with the title, author and number of pages of the document.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Default transition</guilabel></term>
					<listitem>
						<para>The transition effect between page and page if the document does not specify one. Set this to <guilabel>Random
							Transition</guilabel> to make &okular; randomly choose one of the available effects.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Placement</guilabel></term>
					<listitem>
						<para>In this section you can select the <guilabel>Screen</guilabel> used to display the presentation.</para> 
						<para><guilabel>Current Screen</guilabel> is same screen of the &okular; window that starts the presentation mode.</para>
						<para><guilabel>Default Screen</guilabel> is the screen marked as default in the xinerama configuration.</para>
						<para><guilabel>Screen 0</guilabel>, <guilabel>Screen 1</guilabel> &etc; are the available screens.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="configidentity">
			<title>Identity</title>
			<variablelist>
				<varlistentry>
					<term><guilabel>Author</guilabel></term>
					<listitem>
						<para>The author of the contents added on a document.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="configeditor">
			<title>Editor</title>
			<variablelist>
				<varlistentry>
					<term><guilabel>Editor</guilabel></term>
					<listitem>
						<para>Choose the editor you want to launch when &okular; wants to open a source file. 
						This is the case when the document has references to the various points (usually row and column number) of sources it was generated from. The &DVI; format supports natively the addition of the information about the sources the LaTeX document was generated from. A similar system exists for &PDF; documents, called <acronym>pdfsync</acronym>, which stores these extra information in an external file named after the &PDF; file itself (for example <filename>mydocument.pdfsync</filename> for <filename>mydocument.pdf</filename>).	
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><guilabel>Command</guilabel></term>
					<listitem>
						<para>This is the command and its parameters to invoke the selected editor with the source file of the actual document.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
	</chapter>
	<chapter id="credits">
		<title>Credits and License</title>
		
		<itemizedlist>
			<title>Program Copyright:</title>
			<listitem><para>Albert Astals Cid<email>aacid@kde.org</email> </para></listitem>
			<listitem><para>Pino Toscano <email>pino@kde.org</email> Current maintainer</para></listitem>
			<listitem><para>Enrico Ros<email>eros.kde@email.it</email> &kpdf; developer</para></listitem>
		</itemizedlist>

		<itemizedlist>
			<title>Documentation Copyright:</title>
			<listitem><para>Albert Astals Cid<email>aacid@kde.org</email> Author</para></listitem>
			<listitem><para>Titus Laska<email>titus.laska@gmx.de</email> Some updates and additions</para></listitem>
			<listitem><para>Pino Toscano <email>pino@kde.org</email></para></listitem>
		</itemizedlist>
		<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
		&underFDL;
		&underGPL;
	</chapter>

	<appendix id="installation">
		<title>Installation</title>
		<sect1 id="getting-kapp">
			<title>How to obtain &okular;</title>
			&install.intro.documentation;
		</sect1>
		<sect1 id="compilation">
			<title>Compilation and Installation</title>
			<note>
				<para>
					If you are reading this help in the &khelpcenter;, &okular; has already been
					installed on this system and you do not need install it anymore.
				</para>
			</note>
			&install.compile.documentation;
		</sect1>
	</appendix>
	&documentation.index; 
</book>


<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

// vim:ts=2:sw=2:tw=78:noet
-->
