path: root/doc/kghostview/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
 "dtd/kdex.dtd" [
  <!ENTITY kappname "&kghostview;">
  <!ENTITY package "kdegraphics">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>
<book lang="&language;">

<bookinfo>
<title>The &kghostview; Handbook</title>
<authorgroup>
<author>
<firstname>Pamela</firstname>
<surname>Roberts</surname>
<affiliation>
<address>&Pamela.Roberts.mail;</address>
</affiliation>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2001</year> <year>2002</year>
<holder>&Pamela.Roberts;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2006-02-28</date>
<releaseinfo>0.20</releaseinfo>

<abstract>
<para>&kghostview; displays and prints &PostScript; (<literal
role="extension">.ps</literal>, <literal
role="extension">.eps</literal>) and Portable Document Format
(<literal role="extension">.pdf</literal>) files.</para>
<para>This document describes &kghostview; version 0.20</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>linux</keyword>
<keyword>postscript</keyword>
<keyword>ghostview</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&kghostview; displays and prints &PostScript; (<literal
role="extension">.ps</literal>, <literal
role="extension">.eps</literal>) and Portable Document Format (<literal
role="extension">.pdf</literal>) files. It is a port to &kde; of Tim
Theisen's <application>Ghostview</application> program which uses Alladin
<application>Ghostscript</application> to view documents prepared in
<trademark class="registered">Adobe</trademark>'s &PostScript; page
description language. &PostScript; is the major page description language
for printing on &UNIX; systems and this application can be used to preview
material intended for printing or for reading documents online.
</para>

<para>
You can use &kghostview; with all recent versions of
<application>Ghostscript</application>. Newer versions offer much
improved performance which you can take advantage of with &kghostview;.
</para>

<para>
If a document does not conform to the <trademark
class="registered">Adobe</trademark> document structuring convention the
functionality of the viewer is limited. For example, if there is no
table of contents, skipping around the document and marking pages is not
possible.
</para>

</chapter>


<chapter id="fundamentals">
<title>Fundamentals</title>

<para>
This section describes what you see in the main &kghostview; window, the
actions of the Toolbar buttons and how to use the Page List.
</para>

<para>
You can open multiple instances of &kghostview; to view multiple
documents. The titlebar at the top of a window shows you the name of
the document in that window.
</para>

<para>
The main area displays a page of the current document. If the page is
too large to fit inside the window, scrollbars are automatically added
to the sides of the display, although these can be disabled with the
<guimenu>Settings</guimenu> menu.
</para>
<para>
Note that the Toolbar and the Page List can be hidden with the <link
linkend="settings">Settings</link> menu options to give more space on
the screen for the content area.
</para>

<para>
You can scroll up and down in a page with the <keysym>Up
Arrow</keysym> and <keysym>Down Arrow</keysym> keys, or use the
<menuchoice><guimenu>View</guimenu><guimenuitem>Read Up</guimenuitem></menuchoice> 
(<keycap>PageUp</keycap>) and <menuchoice><guimenu>View</guimenu>
<guimenuitem>Read Down</guimenuitem></menuchoice> 
(<keycap>PageDown</keycap>) options to scroll through the entire document.
</para>

<para>The
<guibutton>Read Up</guibutton> and <guibutton>Read Down</guibutton> 
-Toolbar buttons do what they say, or you can go
immediately to any page with a &LMB; click on the appropriate entry in
the Page List.
</para>

<para>
If selected in the <guimenu>Settings</guimenu> menu a Page List will be
displayed at the left side of the window. This list has two columns: the
first may contain a flag indicating that the page has been marked, the
second contains the page numbers. You can use this page list to navigate
through the document or to mark pages for printing.
</para>

<para>
You can toggle the <quote>page marked</quote> flag for the currently
displayed page with <keycombo
action="simul">&Ctrl;&Shift;<keycap>M</keycap></keycombo> or for
any page by &LMB; clicking on it in the Page List. You can also clear or
change your page marks using the context menu that is activated by
&RMB; clicking anywhere in the Page List area or by selecting the <link
linkend="menuedit">Edit</link> menu.
</para>

</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 file. If a file
is currently being displayed it will be closed.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Open Recent</guimenuitem>
</menuchoice></term>
<listitem><para><action>Open</action> a file selected from a combo box of
recently opened files. If a file is currently being displayed it will be
closed.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save As...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Save</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.
The Print dialog box will let you choose to print all or selected
(marked) pages.</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Document Info</guimenuitem>
</menuchoice></term>
<listitem><para><action>Display</action> some basic information about
the document.</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> down &kghostview;.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="menuedit">
<title>The <guimenu>Edit</guimenu> Menu</title>

<note>
<para>
You can also get this menu by &RMB; clicking anywhere in the Page List
area.
</para>
</note>

<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Shift;
<keycap>M</keycap></keycombo></shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Mark Current Page</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the page marked
flag</action> for the current page.</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Mark All Pages</guimenuitem>
</menuchoice></term>
<listitem><para><action>Set the page marked
flag</action> for all pages of the document.</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Mark Even Pages</guimenuitem>
</menuchoice></term>
<listitem><para><action>Set the page marked
flag</action> for all even numbered pages in the document. Used in
conjunction with <guimenuitem>Mark Odd Pages</guimenuitem> or
<guimenuitem>Toggle Page Marks</guimenuitem> this provides a convenient way of
double-sided printing a document on a single sided printer</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Mark Odd Pages</guimenuitem>
</menuchoice></term>
<listitem><para><action>Set the page marked
flag</action> for all odd numbered pages in the document.</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Toggle Page Marks</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the page marked
flags</action> for all pages in the document.</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Remove Page Marks</guimenuitem>
</menuchoice></term>
<listitem><para><action>Clear the page marked
flags</action> for all pages in the document.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="view">
<title>The <guimenu>View</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycap>F5</keycap>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Reload</guimenuitem>
</menuchoice></term>
<listitem><para><action>Re-render</action> the current document page.</para>
</listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>M</keycap></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Maximize</guimenuitem></menuchoice>
</term>
<listitem>
<para>This option maximizes the &kghostview; window.</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;
<keycap>F</keycap></keycombo></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Full Screen Mode</guimenuitem></menuchoice>
</term>
<listitem>
<para>This option maximizes the &kghostview; window and the currently shown page.
Even the window decorations (titlebar &etc;) are temporarily removed.
To switch back to normal window mode, press the <keycap>ESC</keycap> key or 
the shortcut <keycombo action="simul">&Ctrl;&Shift;
<keycap>F</keycap></keycombo> again, or open the context menu with a &RMB; click
and select <guimenuitem>Exit Full Screen Mode</guimenuitem>.
</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Orientation</guimenuitem>
</menuchoice></term>
<listitem><para><action>Change the orientation</action> of the
displayed page. You can choose between <guimenuitem>Auto</guimenuitem>,
<guimenuitem>Portrait</guimenuitem>,
<guimenuitem>Landscape</guimenuitem>, <guimenuitem>Upside
Down</guimenuitem> and <guimenuitem>Seascape</guimenuitem> which is like
<guimenuitem>Landscape</guimenuitem> but the other way up.</para> </listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Paper Size</guimenuitem>
</menuchoice></term>
<listitem><para>Lets you view the document as if it
were printed on different <action>paper sizes</action> without changing the
scale. You should normally choose <guimenuitem>Auto</guimenuitem>.</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>
<guimenu>View</guimenu>
<guimenuitem>Zoom</guimenuitem>
</menuchoice></term>
<listitem><para>
<action>Select a predefined zoom factor.</action>
</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 to Page Width</guimenuitem>
</menuchoice></term>
<listitem><para><action>Scale</action> the display so a page width fits
exactly across the main display area.</para> </listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>S</keycap></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Fit to Screen</guimenuitem>
</menuchoice></term>
<listitem><para><action>Scale</action> the display so the entire page fits
exactly across the main display area.</para> </listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>PageUp</keycap></keycombo></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Previous Page</guimenuitem>
</menuchoice></term>
<listitem><para>View the <action>previous page</action> of the
document.</para> </listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>PageDown</keycap></keycombo></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Next Page</guimenuitem>
</menuchoice></term>
<listitem><para>View the <action>next page</action> of the
document.</para> </listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>Home</keycap></keycombo></shortcut>
<guimenu>View</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>View</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>View</guimenu>
<guimenuitem>Go to Page</guimenuitem>
</menuchoice></term>
<listitem><para><action>Go to a selected page</action> of the
document.</para> </listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>PageUp</keycap></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Read Up</guimenuitem>
</menuchoice></term>
<listitem><para><action>Scroll backwards</action> through the
document.</para> </listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>PageDown</keycap></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Read Down</guimenuitem>
</menuchoice></term>
<listitem><para><action>Scroll forwards</action> through the
document.</para> </listitem> </varlistentry>

</variablelist>

</sect1>

<sect1 id="settings">
<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/Hide Menubar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles the menubar on/off.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show/Hide Toolbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the Toolbar display</action> on
and off.</para></listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show/Hide Statusbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the Status bar display</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>This option maximizes the &kghostview; window and the currently shown page.
Even the window decorations (titlebar &etc;) are temporarily removed.
To switch back to normal window mode, press the <keycap>ESC</keycap> key or 
the shortcut <keycombo action="simul">&Ctrl;&Shift;
<keycap>F</keycap></keycombo> again, or open the context menu with a &RMB; click
and select <guimenuitem>Exit Full Screen Mode</guimenuitem>.
</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a dialog for changing the shortcuts.</action>
Using this option you can change the standard key shortcut for &kghostview;'s commands
or create new ones.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Toolbars...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a dialog for configuring the toolbar.</action> You
can add and remove toolbuttons for &kghostview;'s commands with this
option.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show/Hide Scrollbars</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the horizontal and vertical scrollbars</action>
on and off.</para></listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Page List</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the Page List</action>
on and off.</para></listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Page Labels</guimenuitem>
</menuchoice></term>
<listitem><para>If this is selected the <action>name (if any) of the
current page is displayed in the Status Bar</action>.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Watch File</guimenuitem>
</menuchoice></term>
<listitem><para>If this is selected the display will
<action>automatically update</action> if the document file
changes.</para></listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>No Flicker</guimenuitem>
</menuchoice></term>
<listitem><para>
If this is selected the display will start showing objects instantly as they are rendered, 
otherwise the whole page is rendered off-screen and then displayed.
</para></listitem> </varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure &kghostview;...</guimenuitem>
</menuchoice></term>
<listitem><para>Brings up the &kghostview;
<link linkend="config-dialog"><action>configuration dialog</action>
box</link>.</para></listitem> </varlistentry>

</variablelist>

</sect1>

<sect1 id="help">
<title>The <guimenu>Help</guimenu> Menu</title>

&help.menu.documentation;

</sect1>
</chapter>

<chapter id="config-dialog">
<title>Configuration</title>

<para>
The configuration dialog box is accessed with the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
&kghostview;...</guimenuitem></menuchoice> option. It has two pages;
<guilabel>General</guilabel> and <guilabel>Ghostscript
Configuration</guilabel>
</para>

<sect1 id="general-settings">
<title>General Settings</title>

<para>
You can select <guilabel>Enable anti-aliasing of fonts and
images</guilabel> to get smoothly rendered text, but note that
anti-aliasing is memory intensive and slower than straightforward
rendering of fonts. Early versions of
<application>Ghostscript</application> could not perform anti-aliasing.
</para>

<para>
Select <guilabel>Use platform fonts</guilabel> if you wish to use your
native system fonts rather than those that come with
<application>Ghostscript</application>.
</para>

<para>
Turn <guilabel>Show Ghostscript messages in a separate box</guilabel>
on if you want to be informed of any output or error messages
generated by the <application>Ghostscript</application> interpreter.
</para>

<para>
You can choose whether &kghostview; uses a
<guilabel>Monochrome</guilabel>, <guilabel>Grayscale</guilabel> or
<guilabel>Color</guilabel> <guilabel>Palette</guilabel> for the display.
</para>

</sect1>

<sect1 id="ghostscript-config">
<title><application>Ghostscript</application> Configuration</title>

<para>
In this dialog box page you can set the name of the
<application>Ghostscript</application> <guilabel>Interpreter:</guilabel>
executable and the <guilabel>Non-antialiasing arguments:</guilabel> and
the <guilabel>Antialiasing arguments:</guilabel> passed to it. The
default settings should be suitable for most systems.
</para>

</sect1>

</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kghostview;
</para>

<itemizedlist>
<title>Program Copyright:</title>
<listitem><para>&Mark.Donohoe; &Mark.Donohoe.mail; (original author) 1998
</para></listitem>
<listitem><para>&David.Sweet; &David.Sweet.mail;
Maintainer 1999-2000
</para></listitem>
<listitem><para>&Wilco.Greven; &Wilco.Greven.mail;
Current maintainer
</para></listitem>
<listitem><para>&David.Faure; &David.Faure.mail; (basis for
shell)</para>
</listitem>
<listitem><para>Daniel Duley <email>mosfet@kde.org</email> (port to
Kparts)</para>
</listitem>
<listitem><para>&Espen.Sand; &Espen.Sand.mail; (dialog boxes)</para>
</listitem>
</itemizedlist>


<para>
Documentation copyright 2001, 2002 &Pamela.Roberts;
&Pamela.Roberts.mail;
</para>


<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->

&underGPL;        	 <!-- GPL License -->


</chapter>

<appendix id="installation">
<title>Installation</title>

<para>
&kghostview; is part of the &kde; 3 project, details of which can be found at
<ulink url="http://www.kde.org">http://www.kde.org</ulink>.
</para>

<para>
To use &kghostview;, you must have the <application>Ghostscript</application>
program as well as &kde; 3 installed on your machine. The
<application>Ghostscript</application> home page is at
<ulink url="http://www.cs.wisc.edu/~ghost/">http://www.cs.wisc.edu/~ghost/</ulink>
</para>

<para>
Most distributions will include &kghostview;, but if you want to roll your own
the source code can be found in the &package; package on &kde-ftp;, the main
ftp site of the &kde; project.</para>

<!--
<para>
To see if a later version of &kghostview; has been released, you can
take a look in <ulink
url="http://apps.kde.com">http://apps.kde.com</ulink>. </para>
-->

&install.compile.documentation;

</appendix>

&documentation.index;

</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->