<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
	<!ENTITY showimg '<application>ShowImg</application>'>
	<!ENTITY kapp "&showimg;">
	<!ENTITY % addindex "IGNORE">
	<!ENTITY % English "INCLUDE"> <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>

<title>&showimg; Documentation</title>

<!-- Author info ___________________________________________________________ -->
<authorgroup>
<author>
	<firstname>Richard</firstname>
	<surname>Groult</surname>
	<affiliation>
		<address><email>ric@jalix.org</email></address>
	</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<!-- Copyright info ________________________________________________________ -->
<copyright>
	<year>2000</year>
	<year>2001</year>
	<holder>Richard Groult</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2001-12-18</date>
<releaseinfo>1.01.05</releaseinfo>


<!-- Keywords ______________________________________________________________ -->
<keywordset>
	<keyword>KDE</keyword>
	<keyword>showimg</keyword>
	<keyword>image</keyword>
	<keyword>picture</keyword>
	<keyword>viewer</keyword>
	<keyword>graphics</keyword>
	<keyword>browser</keyword>
	<keyword>thumbnails</keyword>
</keywordset>


<!-- Abstract ______________________________________________________________ -->
<abstract>
<para>
&showimg; is a full featured picture viewer for KDE 2.x
</para>
</abstract>


</bookinfo>


<!-- Introduction __________________________________________________________ -->
<chapter id="introduction">
<title>Introduction</title>

<para>
&showimg; is a picture viewer designed to run under KDE 2.x. I wanted to make 
an application that would gather the features I desired and that other picture 
viewers didn't have.
</para>
<para>
&showimg; supports many picture formats and features special functions such as
slideshows and duplicate files detection. See the <link linkend="features">
features section</link> to know more.
</para>
</chapter>


<!-- Features ______________________________________________________________ -->
<chapter id="features">
<title>&showimg; features</title>

<para>Here's what &showimg; can do :</para>

<itemizedlist>
	<listitem>
		<para>Image browsing (in list mode, thumbnail mode or one by one)</para>
	</listitem>
	<listitem>
		<para>Supports many image formats :  <acronym>JPEG</acronym>, 
		<acronym>GIF</acronym>, <acronym>PNG</acronym> (alpha channel support), 
		<acronym>MNG</acronym>, 
		<acronym>BMP</acronym>, <acronym>TIFF</acronym>, <acronym>XPM</acronym>, 
		<acronym>XBM</acronym> and <acronym>PNM</acronym> (<acronym>PBM</acronym>, 
		<acronym>PGM</acronym> and <acronym>PPM</acronym>)</para>
	</listitem>
	<listitem>
		<para>Full Screen mode</para>
	</listitem>
	<listitem>
		<para>Slideshow function</para>
	</listitem>
	<listitem>
		<para>Duplicate files detection</para>
	</listitem>
	<listitem>
		<para>Drag'n'drop support for file manipulations (within &showimg; and 
		with external programs such as &konqueror;)</para>
	</listitem>
	<listitem>
		<para>Mouse wheel support</para>
	</listitem>
 <listitem>
		<para>Zip support (Zip files can be browsed as directories)</para>
	</listitem>
	<listitem>
		<para><glossterm linkend="gloss-exif">Exif</glossterm> support</para>
	</listitem>
	<listitem>
		<para>Batch format conversion</para>
	</listitem>
	<listitem>
		<para>Thumbnails can be <glossterm linkend="gloss-cached">cached</glossterm> 
		in a .pics directory</para>
	</listitem>
	<listitem>
		<para>Each interface panel (<link linkend="browser-panel">Browser panel
		</link>, <link linkend="file-list">File list</link> and 
		<link linkend="preview-panel">Preview panel</link>) can be moved and 
		resized</para>
	</listitem>
</itemizedlist>

</chapter>


<!-- User interface ________________________________________________________ -->
<chapter id="user-interface">
<title>User interface</title>

<sect1 id="main-window">
<title>Main Window</title>

<screenshot>
	<screeninfo>Here's a screenshot of &showimg;</screeninfo>
	
	<mediaobject>
		<imageobject>
			<imagedata fileref="main-window.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Main window</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>The &showimg; main window consists of three panels :</para>

<itemizedlist>
	<listitem>
		<para>The <link linkend="browser-panel">Browser panel</link></para>
	</listitem>
	<listitem>
		<para>The <link linkend="file-list">File list</link></para>
	</listitem>
	<listitem>
		<para>The <link linkend="preview-panel">Preview panel</link></para>
	</listitem>
</itemizedlist>

<para>Follow the links for detailed descriptions.</para>

</sect1>

<sect1 id="toolbar">
<title>Toolbar</title>

<itemizedlist>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-back.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Back</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Back
		</para>
		<para>Displays the previously viewed folder and its contents in the File 
		list</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-forward.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Forward</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Forward
		</para>
		<para>Advances you to a folder you previously viewed. You need to have used
		the Back button for the Forward button to be active.</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-copy.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Copy</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Copy
		</para>
		<para>Copies the image file currently displayed to the clipboard. This won't 
		work with files that are contained in a zip archive.</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-paste.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Paste</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Paste
		</para>
		<para>Pastes the image file from the clipboard to the current directory. If 
		several directories are selected, the file is pasted into the default one (
		its path is displayed on the title bar).
		</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-rotate-left.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Rotate Left</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Rotate Left
		</para>
		<para>Rotates the image 90 degrees counter clockwise</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-rotate-right.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Rotate Right</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Rotate Right
		</para>
		<para>Rotates the image 90 degrees clockwise</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-horiz-flip.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Horizontal Flip</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Horizontal Flip
		</para>
		<para>Flips the image horizontally</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-vert-flip.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Vertical Flip</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Vertical Flip
		</para>
		<para>Flips the image vertically (mirror)</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-slide-show.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Slide Show</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Slide Show
		</para>
		<para>Displays images as a slide show presentation</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-prev-image.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Previous Image</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Previous Image
		</para>
		<para>Displays the previous image in the file list</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-next-image.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Next Image</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Next Image
		</para>
		<para>Displays the next image in the file list</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-reload.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Reload</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Reload
		</para>
		<para>Reload the selected directories</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-toggle-thumbs.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Toggle Thumbnails</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Toggle Thumbnails
		</para>
		<para>Displays files with icons or thumbnails</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-stop-thumbs.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Stop Thumbnails Generation</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Stop Thumbnails Generation
		</para>
		<para>Stops the thumbnails generation in the file list</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-fullscreen.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Full Screen Mode</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Full Screen Mode
		</para>
		<para>Switch to Full Screen Mode</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-zoom-in.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Zoom In</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Zoom In
		</para>
		<para>Increases the size of the current image</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-zoom-out.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Zoom In</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Zoom In
		</para>
		<para>Reduces the size of the current image</para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-zoom-fit-screen.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Fit to Screen</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Fit to Screen
		</para>
		<para>Displays the image at the largest size that fits the 
		<link linkend="preview-panel">Preview panel</link></para>
	</listitem>
	<listitem>
		<para>
			<guiicon><inlinemediaobject>
				<imageobject>
					<imagedata fileref="but-zoom-original.png" format="PNG"/>
				</imageobject>
				<textobject>
					<phrase>Original Size</phrase>
				</textobject>
			</inlinemediaobject></guiicon>
			Original Size
		</para>
		<para>Displays the image at normal size</para>
	</listitem>
</itemizedlist>
		
</sect1>

</chapter>


<!-- Using showimg _________________________________________________________ -->
<chapter id="using-showimg">
<title>Using &showimg;</title>
<para>Please note that all the key combinations and panel locations that are 
described here can be customized.</para>

<sect1 id="browsing">
<title>Browsing</title>

<sect2 id="browser-panel">
<title>Browser panel</title>

<para>
At the top left corner of the main window is the Browser panel.
From here you can browse all your filesystem hierarchy to select the 
directories and compressed files you want &showimg; to scan. Just clibk an item 
with the &LMB; to select it and the image files it contains will be showned in 
the <link linkend="file-list">File list</link>.
</para>
<para>
You can select several items (directories and/or compressed files), just click 
them while holding the <keycap>Ctrl</keycap> key. Their content will be merged 
in the <link linkend="file-list">File list</link>.
</para>

</sect2>

<sect2 id="file-list">
<title>File list</title>

<para>
At the bottom left corner of the main window is the File list.
This panel lists the picture files that are contained in the item(s) selected in 
the <link linkend="browser-panel">Browser panel</link>. Files can be displayed 
as icons or as thumbnails, just switch between these two modes with the 
<guibutton>Toggle Thumbnails</guibutton> button . Click on a file to display it 
in the <link linkend="preview-panel">Preview panel</link>.
</para>

</sect2>

<sect2 id="preview-panel">
<title>Preview panel</title>

<para>
This is the panel where pictures are displayed. 
</para>

</sect2>



</sect1>

<sect1 id="viewing">
<title>Viewing</title>

<para>
Pictures can be viewed in the <link linkend="preview-panel">Preview panel</link> 
or in Full Screen Mode. Switch between these two modes with the 
<keycombo action="simul"><keycap>Enter</keycap></keycombo> key or the 
<guibutton>Full Screen Mode</guibutton> button.
</para>

<sect2 id="zooming">
<title>Zooming</title>

<para>
You can zoom in a specified area by selecting it with the &LMB; : simply draw a 
rectangle to zoom in. Click anywhere on the picture to restore the zoom factor. 
You can also use 
<keycombo action="simul"><keycap>Ctrl</keycap><keycap>+</keycap></keycombo> 
and
<keycombo action="simul"><keycap>Ctrl</keycap><keycap>-</keycap></keycombo> 
to zoom in and out.
</para>

</sect2>

<sect2 id="scrolling">
<title>Scrolling</title>

<para>
While in zoom mode, hold down the &MMB; and move your mouse around to scroll the 
picture.
</para>

</sect2>
</sect1>

<sect1 id="tools">
<title>Tools</title>

<sect2 id="rename-series">
<title>Rename Series</title>

<para>From the <link linkend="file-list">File list</link>, you can rename a 
selected range of files according to a specific pattern.</para>

<para>
	The pattern can (and should) contain some special characters :
	<itemizedlist>
		<listitem>
			<para><emphasis>#</emphasis> Counter. Place it where you want numbers to 
			appear in the file name. Include several '#' if you want leading zeros to 
			be generated when needed. Use the <guilabel>Start Index</guilabel> value 
			to change the counter starting number.</para>
		</listitem>
		<listitem>
			<para><emphasis>$</emphasis> Old file name. Place it where you want the 
			old file name to be inserted (without extension).</para>
		</listitem>
		<listitem>
			<para><emphasis>%</emphasis> Lower case old file name. Same as '$', but 
			converts the old file name to lower case.</para>
		</listitem>
	</itemizedlist>
</para>

<para>
Please note that the pattern doesn't have to include the file extension.
</para>


<para>	Here is an example :</para>	
<informalexample>
	<itemizedlist>
		<listitem><para>Apple.jpg</para></listitem>
		<listitem><para>Sheep.jpg</para></listitem>
		<listitem><para>Tree.jpg</para></listitem>
	</itemizedlist>
</informalexample>

<para>	If we use a pattern such as pic_$_#, this file serie
	will be renamed as : </para>	
<informalexample>	
	<itemizedlist>
		<listitem><para>pic_Apple_1.jpg</para></listitem>
		<listitem><para>pic_Sheep_2.jpg</para></listitem>
		<listitem><para>pic_Tree_3.jpg</para></listitem>
	</itemizedlist>
</informalexample>

</sect2>
</sect1>

</chapter>


<!-- FAQ ___________________________________________________________________ -->
<chapter id="faq">
<title>Questions and Answers</title>

<qandaset id="faqlist">
<qandaentry>
	<question>
		<para>The mouse wheel doesn't work like it should.</para>
	</question>
	<answer>
		<para>Check that IMWheel isn't running. As QT now has mouse wheel support,
		IMWheel is useless and causes problems in &showimg;.</para>
	</answer>
</qandaentry>
</qandaset>

</chapter>


<!-- Credits and License ___________________________________________________ -->
<chapter id="credits">
<title>Credits and License</title>

<para>
&showimg;
</para>
<para>
	Program copyright 2000-2001 Richard Groult
	<email>richard.groult@jalix.org</email>
</para>

<para>
Contributors:
<itemizedlist>
	<listitem>
		<para>Valerie (icon design)
		<email>valerie.frappart@jalix.org</email></para>
	</listitem>
	<listitem>
		<para>Jean-Philippe Martin (icon design)
		<email>jeanphilippemartin@club-internet.fr</email></para>
	</listitem>
	<listitem>
		<para>Benoist Gaston (beta-test and translation)
		<email>bgaston@laposte.net</email></para>
	</listitem>
	<listitem>
		<para>Romain Vallet (beta-test and documentation)
		<email>romain.vallet@jalix.org</email></para>
	</listitem>
	<listitem>
		<para>Alain Bidaud (web server administration and website design)</para>
	</listitem>
	<listitem>
		<para>Hape Schaal (german translation) 
		<email>hp.news@gmx.de</email></para>
	</listitem>
	<listitem>
		<para>Lots of people (Bug reports, advices and encouragements :)</para>
	</listitem>
</itemizedlist>
</para>

<para>
Documentation copyright 2001 Romain Vallet 
<email>romain.vallet@jalix.org</email>
</para>

&underFDL;
&underGPL;

</chapter>


<!-- Installation __________________________________________________________ -->
<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kapp">
<title>How to obtain &showimg;</title>
<para>
	&showimg; is a project from the Jalix association
	<ulink url="http://www.jalix.org">http://www.jalix.org</ulink>.
	&showimg; can be found on the official website
	<ulink url="http://www.jalix.org/projects/showimg">http://www.jalix.org/projects/showimg</ulink>.
</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
	In order to successfully use &showimg;, you need KDE 2.2 and ImageMagick. zlib 
	library is required in order to enable the zip archive browsing feature.
</para>

<para>
	Required libraries:
	<itemizedlist>
		<listitem>
			<para>
			ImageMagick can be found on
			<ulink url="http://www.imagemagick.org">http://www.imagemagick.org</ulink>.
			</para>
		</listitem>

		<listitem>
			<para>
			zlib can be found on
			<ulink url="http://www.gzip.org/zlib">http://www.gzip.org/zlib</ulink>.
			</para>
		</listitem> 		
	</itemizedlist>
</para>

<para>
	You can find a list of changes at 
	<ulink url="http://www.jalix.org/projects/showimg">http://www.jalix.org/projects/showimg</ulink>.
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and installation</title>

<para>
	In order to compile and install &showimg; on your system, decompress the 
	archive file and type the following :
	<screen width="40">
		<prompt>%</prompt> <userinput><command>./configure</command></userinput>
		<prompt>%</prompt> <userinput><command>make</command></userinput>
		<prompt>%</prompt> <userinput><command>make install</command></userinput>
	</screen>
</para>

<para>Since &showimg; uses autoconf and automake you should have not trouble
compiling it.
Should you run into problems please report them to the author.</para>

</sect1>

</appendix>


<!-- Glossary ______________________________________________________________ -->
<appendix id="glossary">
<title>Glossary</title>

<glosslist>
	<glossentry id="gloss-exif">
		<glossterm>Exif Metadata</glossterm>
		<glossdef>
			<para><acronym>EXIF</acronym> Metadata (Exchangeable Image File) 
			refers to digital camera storage of image information using 
			<acronym>EXIF</acronym> compressed files. <acronym>EXIF</acronym> 
			compressed files use the baseline <acronym>JPEG</acronym> 
			<acronym>DCT</acronym> format. The image data can be read by any 
			application supporting <acronym>JPEG</acronym>, including web browsers, 
			desktop presentation applications, document creation applications 
			processor.</para>
		</glossdef>
	</glossentry>
	<glossentry id="gloss-cached">
		<glossterm>Cached thumbnails</glossterm>
		<glossdef>
			<para>Cached thumbnails are stored in a .pics directory so that they can 
			be quickly displayed in the <link linkend="file-list">File list</link>
			(rather than &showimg; regenerating them each time you browse images).
			</para>
		</glossdef>
	</glossentry>
</glosslist>

</appendix>

&documentation.index;

</book>