<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY palapeli "<application
>Palapeli</application
>">
<!ENTITY psc "<application
>Palapeli Slicer Collection</application
>">
<!ENTITY kappname "&palapeli;">
<!ENTITY package "kdegames">
<!ENTITY % Dutch "INCLUDE">
<!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">
	<bookinfo>
		<title
>De handboek van &palapeli;</title>
		<authorgroup>
			<author
><firstname
>Johannes</firstname
> <surname
>L&#xF6;hnert</surname
> <affiliation
><address
><email
>loehnert_kde@gmx.de</email
></address
></affiliation>
			</author>
			<author
><firstname
>Stefan</firstname
> <surname
>Majewsky</surname
> <affiliation
><address
><email
>majewsky@gmx.net</email
></address
></affiliation>
			</author>
			&Freek.de.Kruijf; 
		</authorgroup>

		<copyright>
			<year
>2009, 2010</year>
			<holder
>Johannes L&#xF6;hnert, Stefan Majewsky</holder>
		</copyright>
		<legalnotice
>&FDLNotice;</legalnotice>
		<date
>2010-11-29</date>
		<releaseinfo
>1.2</releaseinfo>

		<abstract>
			<para
>Dit is de handleiding voor &palapeli;, een legpuzzelspel gebaseerd op &kde; technologie.</para>
		</abstract>
		<keywordset>
			<keyword
>KDE</keyword>
			<keyword
>kdegames</keyword>
			<keyword
>spel</keyword>
			<keyword
>puzzel</keyword>
			<keyword
>legpuzzelspel</keyword>
			<keyword
>palapeli</keyword>
		</keywordset>
	</bookinfo>

	<chapter id="introduction">
		<title
>Inleiding</title>
		<para
>&palapeli; is a single-player jigsaw puzzle game.</para>
		<para
>The &palapeli; window is separated into two areas, the puzzle collection and the puzzle table. This manual will now continue with describing these two areas.</para>
	</chapter>

	<chapter id="collection">
		<title
>Browsing the puzzle collection</title>
		<para
>When you launch &palapeli; for the first time, your puzzle collection is preloaded with some default puzzles that come with &palapeli;. Click on one of the puzzles to immediately start playing. Playing takes place on the puzzle table; see <link linkend="puzzletable"
>the section after next</link
> for how to use the puzzle table.</para>
		<para
>Apart from selecting a puzzle, the puzzle collection can be used for the following actions:</para>
		<itemizedlist>
			<listitem
><para
><emphasis
>create</emphasis
> new puzzles from images on your disk</para
></listitem>
			<listitem
><para
><emphasis
>import</emphasis
> puzzles made by others</para
></listitem>
			<listitem
><para
><emphasis
>export</emphasis
> puzzles to share them with your friends and the world</para
></listitem>
			<listitem
><para
><emphasis
>delete</emphasis
> puzzles you do not need any more</para
></listitem>
		</itemizedlist>
		<para
>The following section shows how to perform these tasks with the toolbar buttons.</para>
		<sect1 id="toolbars-collection">
			<title
>Toolbar overview</title>
			<note
><para
>You can select puzzles in the puzzle list by pressing &Ctrl; and &LMB; together. Pressing the &LMB; or &RMB; without &Ctrl; opens the specific puzzle in the puzzle table.</para
></note>
			<variablelist>
				<varlistentry>
					<term
><guiicon
>Nieuwe puzzel aanmaken</guiicon
></term>
					<listitem>
						<para
><action
>Opens a dialog which allows you to create a puzzle from an image on your disk.</action
> See <link linkend="create-puzzles"
>the next section</link
> for details.</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term
><guiicon
>Verwijderen</guiicon
></term>
					<listitem
><para
><action
>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your library. </action
></para
><warning
><para
>Deze actie kan niet ongedaan worden gemaakt.</para
></warning
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><guiicon
>Uit bestand importeren</guiicon
></term>
					<listitem
><para
><action
>When you have received a &palapeli; puzzle file (which can usually be recognized by the file extension <literal role="extension"
>*.puzzle</literal
>), you can use this action to import it into your local collection.</action
> Puzzle files can also be played by simply clicking on them in the file manager of your choice, but after the import, the puzzle will appear in your local collection, and you can safely delete the downloaded puzzle file.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><guiicon
>Naar bestand exporteren</guiicon
></term>
					<listitem
><para
><action
>This will export the currently selected puzzles to files, in order to enable you to give them to your friends, publish them on the web, or make backup copies of your collection.</action
></para
></listitem>
				</varlistentry>
			</variablelist>
		</sect1>
	</chapter>

	<chapter id="create-puzzles">
		<title
>Nieuwe puzzels aanmaken</title>
		<para
>As described in <link linkend="collection"
>the previous section</link
>, you can create new puzzles by clicking on the <guiicon
>Create new puzzle</guiicon
> button on the puzzle collection.</para>
		<para
>Clicking this button opens the puzzle creation dialog, which consists of three pages:</para>
		<procedure>
			<step
><para
>On the first page, select an image file which shall be sliced into pieces. Be sure to enter the correct metadata for the image: You should give attribution to the author of the image (&eg; the photographer or the painter); please respect the copyright of the image author.</para
></step>
			<step
><para
>On the second page, you can select the type of pieces into which the image shall be sliced. &palapeli; comes with a collection of slicers preinstalled, but third-party slicers may also be available.</para
></step>
			<step
><para
>On the final page of the dialog, the selected slicer can be customized &eg; by choosing a different piece count or by adjusting parameters of the piece shape. The available set of options depends which slicer has been selected.</para
></step>
		</procedure>
		<para
>This manual will continue to discuss the slicers which come with &palapeli;. If you have downloaded a third-party slicer plugin for &palapeli;, please refer to the documentation of this plugin if you have trouble installing or using it on your system.</para>
		<sect1 id="psc">
			<title
>&psc;</title>
			<para
>The &psc; produces realistical jigsaw pieces with various basic patterns:</para>
			<variablelist>
				<varlistentry>
					<term
>Rechthoekig raster</term>
					<listitem
><para
>Contains the well-known rectangular pieces.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Cairo grid</term>
					<listitem
><para
>With its pentagonal pieces and unequal edge angles, it's rather hard to puzzle because the pieces fit together in an unfamiliar manner.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Hexagonaal raster</term>
					<listitem
><para
>Produces hexagonal pieces, arranged like honeycomb cells.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Rotrex grid</term>
					<listitem
><para
>Through a special composition of triangular, hexagonal and rectangular pieces, the pieces form a pattern resembling to many intersecting circles.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Onregelmatig raster</term>
					<listitem
><para
>This grid is available only if you have installed <application
>qvoronoi</application
> from the <ulink url="http://www.qhull.org"
><application
>qhull</application
> package</ulink
>. <application
>qvoronoi</application
> is used to calculate irregular piece shapes from randomly placed points.</para
></listitem>
				</varlistentry>
			</variablelist>
			<para
>The &psc; has various parameters which control the appearance of the piece edges, especially the plugs on them. Default settings are provided for all of these parameters. An additional preset mode is available which reduces the amount of parameters to a bare minimum. The following parameters are available usually:</para>
			<variablelist>
				<varlistentry>
					<term
>Ongeveer het aantal stukken</term>
					<listitem
><para
></para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Percentage omgeslagen randen</term>
					<listitem
><para
>The probability for each plug to be flipped. A plug is considered flipped if it points in the opposite direction as it would in a fully regular grid. On the rectangular grid, this results in pieces with 3 or 4 plugs pointing inwards resp. outwards. Position the slider at the very left to obtain the normal fully regular grid. In the middle, plug orientation is random. At the right, the grid is fully regular again, but with an "alternate" rule. This does <emphasis
>not</emphasis
> mean reversal of all plugs: In the alternate regular grid, for instance, each piece has four inward-pointing or four outward-pointing plugs. This setting has no effect in the irregular grid.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Kromming van randen</term>
					<listitem
><para
>Determines how curvy the edges are, &ie; how strongly the borders dent in or bulge out. Move the slider to the very left to obtain straight edge lines (except for the plugs).</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Grootte van uitstulping</term>
					<listitem
><para
>Determines the size of the plug part of each edge. The default setting (middle position of the slider) is chosen to look like a real puzzle. The slider ranges from 50% to 150% this size, which already looks obscenely large. The program tries very hard to avoid collisions between plugs. Colliding edges are reshaped multiple times and shrinked in small steps. However there still remain cases where no solution can be found, especially for large plug sizes.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Diversiteit van kromming</term>
					<listitem
><para
>Determines how much the curviness (see above) varies between edges. Move the slider to the left to make the dents and bulges look all the same. At the right, there may occur very curvy and very straight borders.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Diversiteit van uitstulpingpositie</term>
					<listitem
><para
>Determines how much the position of the plug on the edge varies. At the very left, plugs are affixed to the middle of their edge.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Diversiteit van uitstulping</term>
					<listitem
><para
>Determines how individual the plugs look like. At the very left, plugs look all the same. At the very right, each plug will be a unique piece of art crafted especially for you.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Irr.: Diversity of piece size</term>
					<listitem
><para
>Only for irregular grid: Determines how the piece size varies. A very small setting means nearly no variation; crystallite-like structure arise. Higher settings produce very small and very large pieces.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
>Raster van afbeelding dumpen</term>
					<listitem
><para
>Save an image of the grid (black edges on white background) at <filename
>~/goldberg-slicer-dump.png</filename
>. If a previous dump exists, it is overwritten.</para
></listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="legacy-slicers">
			<title
>Legacy slicers</title>
			<para
>For historical reasons, &palapeli; also includes the slicers &quot;Classic jigsaw pieces&quot; and &quot;Rectangular pieces&quot;. These slicers create simple rectangular pieces either with or without connecting plugs. Both slicers allow the piece count and the aspect ratio to be adjusted. Dragging the aspect ratio slider to the left results in tall pieces, adjusting it to the right produces wide pieces. The default selection produces approximately square pieces.</para>
		</sect1>
	</chapter>

	<chapter id="puzzletable">
		<title
>Playing on the puzzle table</title>
		<screenshot
><mediaobject>
			<imageobject
><imagedata fileref="puzzletable1.png" format="PNG"/></imageobject>
			<textobject
><phrase
>The puzzle table (detail)</phrase
></textobject>
		</mediaobject
></screenshot>
		<para
>The object of the game is to assemble the given pieces to an image.</para>
		<para
>Pieces can be freely moved by clicking and dragging them with the &LMB;. You can select multiple pieces at once by holding &Ctrl; and clicking on them, or by dragging a rubberband around them with the &LMB;.</para>
		<para
>When you put one piece near a neighboring piece, both pieces will automatically snap together (1). After having snapped together, pieces cannot be torn apart anymore. Unlike in reality, you cannot combine two pieces that are not true neighbors.</para>
		<para
>The progress bar below the puzzle table indicates your progress (2). &palapeli; will automatically save your progress after every move, so you'll normally not have to bother about saving.</para>
		<para
>With the mouse wheel, or with the slider at the bottom right (3), you can change the zoom level of the puzzle table view. By clicking and dragging with the &RMB;, you can move the puzzle table view.</para>
		<para
>The movement of the pieces is limited by the <emphasis
>puzzle table area</emphasis
>. This area is represented on the puzzle table's background by a light rectangular shade. When you move pieces to the border (4) of the puzzle table area, the area will automatically expand to give you more space for moving your puzzle pieces. Near the shaded borders, the mouse cursor changes into a double-headed arrow, indicating that you can adjust the puzzle table area by clicking there and dragging with the &LMB;.</para>
		<para
>You can lock the puzzle table area with the small button (5) right next to the progress bar. The shade (4) around the puzzle table will darken, and pieces will now stop to move at the edges of the puzzle table area. It is still possible to adjust the size of the puzzle table area manually.</para>
		<sect1 id="puzzletable-mouseactions">
			<title
>Mouse interactions</title>
			<para
>As described in the previous section, there are plenty of ways to interact with &palapeli;'s puzzle table using the mouse. You can configure freely which actions are triggered by which mouse buttons. (See <link linkend="configuration-mouseactions"
>Game Configuration</link
> section for more information on how to configure this.) The following list summarizes all possible mouse actions:</para>
			<variablelist>
				<varlistentry>
					<term
><action
>Wijzig de grootte van het puzzelbladgebied door de randen te verslepen</action
></term>
					<listitem
><para
>By default, this action is assigned to the &LMB;.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Verplaats stukken door slepen</action
></term>
					<listitem
><para
>When you click and drag a puzzle piece, this piece will be moved. If multiple pieces are selected and you click and drag one of these pieces, then all pieces are moved. By default, this action is assigned to the &LMB;.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Beeldgedeelte verplaatsen door te slepen</action
></term>
					<listitem
><para
>By default, this action is assigned to the &RMB;.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Meerdere stukken in een keer selecteren</action
></term>
					<listitem
><para
>When you click on a free area of the puzzle table instead of a puzzle piece, you can drag a rubberband. When you let the mouse button go, all pieces inside the rubberband are selected. All other pieces are deselected. By default, this action is assigned to the &LMB;.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Stukken selecteren door er op te klikken</action
></term>
					<listitem
><para
>When you click on a single puzzle piece, it will be selected. If it was already selected, it will be deselected. By default, this action is assigned to the &LMB; and only available when &Ctrl; is pressed.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Schakel de vergrendelstatus om van het tafelgebied van de puzzel</action
></term>
					<listitem
><para
>This action is identical to pressing the button (5) on the status bar. By default, this action is not assigned to any mouse button, but you can enable it from <link linkend="configuration-mouseactions"
>the configuration dialog</link
>.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Scroll viewport horizontally</action
> and <action
>Scroll viewport vertically</action
></term>
					<listitem
><para
>By default, this action is not assigned to the mouse wheel, but you can enable it from <link linkend="configuration-mouseactions"
>the configuration dialog</link
>.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><action
>Beeldgedeelte inzoomen</action
></term>
					<listitem
><para
>This action is identical to moving the slider (3) on the status bar. This action is assigned to the mouse wheel by default.</para
></listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="toolbars-puzzletable">
			<title
>Toolbar overview</title>
			<variablelist>
				<varlistentry>
					<term
><guiicon
>Puzzel herstarten</guiicon
></term>
					<listitem
><para
><action
>Discards the saved progress for this puzzle.</action
></para
></listitem>
				</varlistentry>
			</variablelist>
		</sect1>
	</chapter>

	<chapter id="interface">
		<title
>Overzicht van het interface</title>
		<para
>&palapeli;'s two areas, the puzzle collection and the puzzle table, are embedded into the menubar as tabs. There are also two menus with standard actions which are described below.</para>
		<sect1 id="settings-menu">
			<title
>Het menu <guimenu
>Instellingen</guimenu
></title>
			<variablelist>
				<varlistentry>
					<term
><menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>Show statusbar of puzzle table</guimenuitem
></menuchoice
></term>
					<listitem
><para
><action
>Toggle the display of the progress bar and buttons below the puzzle table.</action
> This action will change nothing in the puzzle collection.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><menuchoice
><guimenu
>Instellingen</guimenu
><guimenuitem
>Sneltoetsen instellen...</guimenuitem
></menuchoice
></term>
					<listitem
><para
><action
>Open a dialog where you can configure the shortcut keys</action
> for &palapeli;</para
></listitem>
				</varlistentry>
				<varlistentry id="settings-menu-configure">
					<term
><menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>Configure &palapeli;...</guimenuitem
></menuchoice
></term>
					<listitem
><para
>Open a game configuration dialog. See <link linkend="configuration"
>Game Configuration</link
> section for more details.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="help">
			<title
>Het <guimenu
>Help</guimenu
>-menu</title>
&help.menu.documentation; </sect1>
	</chapter>

	<chapter id="configuration">
		<title
>Spelconfiguratie</title>
		<para
>To open the configuration dialog, use the menubar option: <menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>Configure &palapeli;...</guimenuitem
></menuchoice
></para>
		<sect1 id="configuration-general">
			<title
><guilabel
>Algemene instellingen</guilabel
></title>
			<variablelist>
				<varlistentry>
					<term
><guilabel
>Achtergrond</guilabel
></term>
					<listitem
><para
><action
>Lets you choose another background texture for the puzzle table.</action
> If you choose a single color instead of a texture, the button besides the selection box can be used to define this single color.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><guilabel
>Uiterlijk van stukken</guilabel
></term>
					<listitem
><para
><action
>Controls the appearance of pieces on the puzzle table.</action
> If &palapeli; is running slowly, or when puzzles take very long to open, you can disable the graphical effects in this category to speed up everything.</para
></listitem>
				</varlistentry>
				<varlistentry>
					<term
><guilabel
>Precisie van in elkaar passen</guilabel
></term>
					<listitem
><para
><action
>Lets you choose how near neighbor pieces must be positioned to each other to snap together.</action
> If you move the slider more to the right, pieces will snap together even if they are not so close. This makes the game a bit simpler to handle.</para
></listitem>
				</varlistentry>
			</variablelist>
		</sect1>
		<sect1 id="configuration-mouseactions">
			<title
><guilabel
>Muisinteractie</guilabel
></title>
			<para
>This page of the configuration dialog allows you to assign the mouse interactions described in the section <link linkend="puzzletable-mouseactions"
>Playing on the puzzle table</link
> to different mouse buttons. The interactions are divided into those that can be assigned to mouse buttons (&eg; <action
>Move viewport by dragging</action
>), and those that can be assigned to the mouse wheel (&eg; <action
>Scroll viewport horizontally</action
>).</para>
			<sect2>
				<title
><guilabel
>Mouse buttons</guilabel
> tab</title>
				<para
>Next to the name of each interaction is a button with a picture of a computer mouse which shows the currently assigned action. You can configure the interaction by clicking on that button with the &LMB; and then with the mouse button which you want to assign to this interaction. If you hold modifier keys while clicking for the second time, the puzzle table will allow this interaction only while these modifiers are being held.</para>
				<tip
><para
>Instead of clicking, you can also press <keycap
>Space</keycap
> to assign the special <guilabel
>No-Button</guilabel
> to this interaction. This is only allowed if modifier keys are being held. The <guilabel
>No-Button</guilabel
> means that the modifier keys take the role of the mouse button: The interaction starts when the modifier keys are pressed, and stops when one of the modifier keys is released.</para
></tip>
			</sect2>
			<sect2>
				<title
><guilabel
>Mouse wheel</guilabel
> tab</title>
				<para
>This tab works similar to the previous one. When the button on the right asks for input, you have to turn the mouse wheel instead of clicking a mouse button. Holding modifier keys is allowed, too, with the same consequences as in the previous case.</para>
				<tip
><para
>Als uw muis een muiswiel heeft die in twee richtingen beweegt (zoals de meesten op touchpads van notebooks), dan kunt u daar uw voordeel mee doen: de knop zal herkennen of u het muiswiel horizontaal of verticaal beweegt.</para
></tip>
			</sect2>
		</sect1>
	</chapter>

	<chapter id="credits">
		<title
>Dankbetuiging en licentie</title>
		<para
>Het doel van &palapeli; om het ontspannende plezier en uitdaging van legpuzzels op uw bureaublad te brengen.</para>
		<para
>Het idee was eerst ontwikkeld door Bernhard Schiffner, samen met Stefan Majewsky, wie de huidige hoofdontwikkelaar van &palapeli; is. De &psc; is bijgedragen door Johannes L&#xF6;hnert.</para>
		<para
>Documentatie Copyright 2009, 2010 Johannes L&#xF6;hnert, Stefan Majewsky.</para>
		&meld.fouten;&vertaling.freek; 
&underFDL; &underGPL; </chapter>

	<appendix id="installation">
		<title
>Installatie</title>
		&install.intro.documentation;
		<sect1 id="Compilation">
			<title
>Compilatie en installatie</title>
&install.compile.documentation; </sect1>
	</appendix>
	&documentation.index;
</book>
