[games/palapeli] doc: Documentation updates
Antoni Bella Pérez
null at kde.org
Fri Oct 8 13:29:52 BST 2021
Git commit 4e5ec499b22c35c2b94cdf3b6d972209fa2840bb by Antoni Bella Pérez.
Committed on 08/10/2021 at 12:29.
Pushed by bellaperez into branch 'master'.
Documentation updates
* Update date and version numbers
* Remove final whitespaces
* Identation fixes
* A strong revision
* Suitable tags, punctuation and some improves
* Add tolbar icons
A +- -- doc/document-export.png
A +- -- doc/document-import.png
A +- -- doc/edit-delete.png
A +- -- doc/go-previous.png
M +828 -823 doc/index.docbook
A +- -- doc/tools-wizard.png
A +- -- doc/view-preview.png
https://invent.kde.org/games/palapeli/commit/4e5ec499b22c35c2b94cdf3b6d972209fa2840bb
diff --git a/doc/document-export.png b/doc/document-export.png
new file mode 100644
index 0000000..5816ea7
Binary files /dev/null and b/doc/document-export.png differ
diff --git a/doc/document-import.png b/doc/document-import.png
new file mode 100644
index 0000000..4c1013a
Binary files /dev/null and b/doc/document-import.png differ
diff --git a/doc/edit-delete.png b/doc/edit-delete.png
new file mode 100644
index 0000000..d973519
Binary files /dev/null and b/doc/edit-delete.png differ
diff --git a/doc/go-previous.png b/doc/go-previous.png
new file mode 100644
index 0000000..24de16f
Binary files /dev/null and b/doc/go-previous.png differ
diff --git a/doc/index.docbook b/doc/index.docbook
index 08b2647..cdb2fc8 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -9,847 +9,852 @@
]>
<book id="palapeli" lang="&language;">
- <bookinfo>
- <title>The &palapeli; Handbook</title>
- <authorgroup>
- <author>
- <firstname>Johannes</firstname>
- <surname>Löhnert</surname>
- <affiliation><address><email>loehnert_kde at gmx.de</email></address></affiliation>
- </author>
- <author>
- <firstname>Stefan</firstname>
- <surname>Majewsky</surname>
- <affiliation><address><email>majewsky at gmx.net</email></address></affiliation>
- </author>
- <author>
- <firstname>Ian</firstname>
- <surname>Wadham</surname>
- <affiliation><address><email>iandw.au at gmail.com</email></address></affiliation>
- </author>
- <!-- TRANS:ROLES_OF_TRANSLATORS -->
- </authorgroup>
+ <bookinfo>
+ <title>The &palapeli; Handbook</title>
+ <authorgroup>
+ <author>
+ <firstname>Johannes</firstname>
+ <surname>Löhnert</surname>
+ <affiliation><address><email>loehnert_kde at gmx.de</email></address></affiliation>
+ </author>
+ <author>
+ <firstname>Stefan</firstname>
+ <surname>Majewsky</surname>
+ <affiliation><address><email>majewsky at gmx.net</email></address></affiliation>
+ </author>
+ <author>
+ <firstname>Ian</firstname>
+ <surname>Wadham</surname>
+ <affiliation><address><email>iandw.au at gmail.com</email></address></affiliation>
+ </author>
+ <!-- TRANS:ROLES_OF_TRANSLATORS -->
+ </authorgroup>
- <copyright>
- <year>2009, 2010</year>
- <holder>Johannes Löhnert, Stefan Majewsky</holder>
- </copyright>
- <copyright>
- <year>2014</year>
- <holder>Ian Wadham</holder>
- </copyright>
- <legalnotice>&FDLNotice;</legalnotice>
- <date>2014-03-09</date>
- <releaseinfo>2.0 (&kde; 4.13)</releaseinfo>
+ <copyright>
+ <year>2009, 2010</year>
+ <holder>Johannes Löhnert, Stefan Majewsky</holder>
+ </copyright>
+ <copyright>
+ <year>2014</year>
+ <holder>Ian Wadham</holder>
+ </copyright>
+ <legalnotice>&FDLNotice;</legalnotice>
+ <date>2021-10-06</date>
+ <releaseinfo>2.1 (KDE Gear 21.08)</releaseinfo>
- <abstract>
- <para>This is the manual for &palapeli;, a jigsaw puzzle game based on &kde; technology.</para>
- </abstract>
- <keywordset>
- <keyword>KDE</keyword>
- <keyword>kdegames</keyword>
- <keyword>game</keyword>
- <keyword>puzzle game</keyword>
- <keyword>jigsaw puzzle</keyword>
- <keyword>palapeli</keyword>
- </keywordset>
- </bookinfo>
+ <abstract>
+ <para>This is the manual for &palapeli;, a jigsaw puzzle game.</para>
+ </abstract>
+ <keywordset>
+ <keyword>KDE</keyword>
+ <keyword>kdegames</keyword>
+ <keyword>game</keyword>
+ <keyword>puzzle game</keyword>
+ <keyword>jigsaw puzzle</keyword>
+ <keyword>Palapeli</keyword>
+ </keywordset>
+ </bookinfo>
- <chapter id="introduction">
- <title>Introduction</title>
- <para>&palapeli; is a single-player jigsaw puzzle game. With it you can create and play puzzles ranging from 4 to 10,000 pieces. This version includes facilities to assist in solving large puzzles (300 pieces or more) within the size limits of a computer screen.</para>
- <para>The main &palapeli; window is separated into two areas, the puzzle collection and the puzzle table.</para>
- <para>This manual continues by describing those two areas.</para>
- </chapter>
+ <chapter id="introduction">
+ <title>Introduction</title>
+ <para>&palapeli; is a single-player jigsaw puzzle game. With it you can create and play puzzles ranging from 4 to 10,000 pieces. This version includes facilities to assist in solving large puzzles (300 pieces or more) within the size limits of a computer screen.</para>
+ <para>The main &palapeli; window is separated into two areas, the puzzle collection and the puzzle table.</para>
+ <para>This manual continues by describing those two areas.</para>
+ </chapter>
- <chapter id="collection">
- <title>Browsing the puzzle collection</title>
- <sect1 id="play-maintain-collection">
- <title>Playing puzzles and updating the collection</title>
- <para>When you launch &palapeli; for the first time, your puzzle collection already contains some sample puzzles that come with &palapeli;. Click on one of them to start playing immediately. Later, when you have created some of your own puzzles (see below), you can also click on them to start playing.</para>
- <para>Play takes place on the puzzle table; see <link linkend="puzzletable">the section after next</link> for how to use the puzzle table.</para>
- <note><para>You can select and highlight puzzles in the puzzle list by pressing &Ctrl; and &LMB; together. Pressing the &LMB; or &RMB; without &Ctrl; opens that puzzle for playing in the puzzle table.</para>
- <para>On Apple OS X you need to double-click the &LMB; to begin playing. A single click will just select and highlight one entry in the puzzle list.</para></note>
- <para>As well as playing a puzzle, you can use the puzzle collection 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>
- <sect1 id="toolbar-collection">
- <title>Toolbar overview</title>
- <variablelist>
- <varlistentry>
- <term><guiicon>Create new puzzle</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 chapter</link> for details.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><guiicon>Delete puzzle</guiicon></term>
- <listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your collection. </action></para><warning><para>This action cannot be undone.</para></warning></listitem>
- </varlistentry>
- <varlistentry>
- <term><guiicon>Import from file</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>Export to file</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="collection">
+ <title>Browsing the puzzle collection</title>
+ <sect1 id="play-maintain-collection">
+ <title>Playing puzzles and updating the collection</title>
+ <para>When you launch &palapeli; for the first time, your puzzle collection already contains some sample puzzles that come with &palapeli;. Click on one of them to start playing immediately. Later, when you have created some of your own puzzles (see below), you can also click on them to start playing.</para>
+ <para>Play takes place on the puzzle table; see <link linkend="puzzletable">the section after next</link> for how to use the puzzle table.</para>
+ <note><para>You can select and highlight puzzles in the puzzle list by hold the &Ctrl; key and click with the &LMB;. Pressing the &LMB; or &RMB; without the &Ctrl; key opens that puzzle for playing in the puzzle table.</para>
+ <para>On &macOS; you need to double-click with the &LMB; to begin playing. A single click will just select and highlight one entry in the puzzle list.</para></note>
+ <para>As well as playing a puzzle, you can use the puzzle collection 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 icons.</para>
+ </sect1>
+ <sect1 id="toolbar-collection">
+ <title>Toolbar overview</title>
+ <variablelist>
+ <varlistentry>
+ <term><inlinemediaobject><imageobject><imagedata fileref="tools-wizard.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Create New Puzzle...</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 chapter</link> for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><inlinemediaobject><imageobject><imagedata fileref="edit-delete.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Delete Puzzle</guiicon></term>
+ <listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your collection. </action></para><warning><para>This action cannot be undone.</para></warning></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><inlinemediaobject><imageobject><imagedata fileref="document-import.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Import from File...</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><inlinemediaobject><imageobject><imagedata fileref="document-export.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Export to File...</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>Creating new puzzles</title>
- <sect1 id="creation-dialog">
- <title>The puzzle creation dialog</title>
- <para>As described in <link linkend="toolbar-collection">the previous section</link>, you can create new puzzles by clicking on the <guiicon>Create new puzzle</guiicon> button in the puzzle collection window.</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 will be sliced into pieces. Be sure to enter the correct metadata for the image: You should give attribution to the author of the image (⪚ 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 will 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 ⪚ 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>
- <sect1 id="simple-slicers">
- <title>Simple slicers</title>
- <para>&palapeli; has two simple slicers, <quote>Classic jigsaw pieces</quote> and <quote>Rectangular pieces</quote>. These slicers create simple rectangular pieces either with or without connecting plugs.</para>
- <para>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>
- <sect1 id="psc">
- <title>The advanced &i18n-psc;</title>
- <para>The &i18n-psc; produces realistic jigsaw pieces with various basic patterns:</para>
- <variablelist>
- <varlistentry>
- <term>Rectangular grid</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>Hexagonal grid</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>Irregular grid</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 &i18n-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>Approx. piece count</term>
- <listitem><para><!--FIXME add missing description here--></para></listitem>
- </varlistentry>
- <varlistentry>
- <term>Flipped edge percentage</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 <quote>alternate</quote> 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>Edge curviness</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>Plug size</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>Diversity of curviness</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>Diversity of plug position</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>Diversity of plugs</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>Dump grid image</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>
- </chapter>
+ <chapter id="create-puzzles">
+ <title>Creating new puzzles</title>
+ <sect1 id="creation-dialog">
+ <title>The puzzle creation dialog</title>
+ <para>As described in <link linkend="toolbar-collection">the previous section</link>, you can create new puzzles by clicking on the <inlinemediaobject><imageobject><imagedata fileref="tools-wizard.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Create New Puzzle...</guiicon> icon in the puzzle collection window.</para>
+ <para>Clicking this icon opens the puzzle creation dialog, which consists of three pages:</para>
+ <procedure>
+ <step><para>On the first page, select an image file which will be sliced into pieces. Be sure to enter the correct metadata for the image: You should give attribution to the author of the image (⪚ 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 will 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 ⪚ 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>
+ <sect1 id="simple-slicers">
+ <title>Simple slicers</title>
+ <para>&palapeli; has two simple slicers, <guilabel>Classic jigsaw pieces</guilabel> and <guilabel>Rectangular pieces</guilabel>. These slicers create simple rectangular pieces either with or without connecting plugs.</para>
+ <para>Both slicers allow the piece count and the aspect ratio to be adjusted. Dragging the <guilabel>Piece aspect ratio:</guilabel> 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>
+ <sect1 id="psc">
+ <title>The advanced &i18n-psc;</title>
+ <para>The &i18n-psc; produces realistic jigsaw pieces with various basic patterns:</para>
+ <variablelist>
+ <varlistentry>
+ <term><guilabel>Rectangular grid</guilabel></term>
+ <listitem><para>Contains the well-known rectangular pieces.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Cairo grid</guilabel></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><guilabel>Hexagonal grid</guilabel></term>
+ <listitem><para>Produces hexagonal pieces, arranged like honeycomb cells.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Rotrex grid</guilabel></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><guilabel>Irregular grid</guilabel></term>
+ <listitem><para>This grid is available only if you have installed <application>qvoronoi</application> from the <ulink url="https://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 &i18n-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><guilabel>Piece count:</guilabel></term>
+ <listitem><para>Here set the exact number in which the image will sliced into pieces. This option only appear if the mathematical logic of the slicer selected allows any number.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Approx. piece count:</guilabel></term>
+ <listitem><para>Here set the desired number in which the image will sliced into pieces. This option only appears if the mathematical logic of the selected slicer readjust this number.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Flipped edge percentage:</guilabel></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 <quote>alternate</quote> 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><guilabel>Edge curviness:</guilabel></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><guilabel>Plug size:</guilabel></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><guilabel>Diversity of curviness:</guilabel></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. Position the slider at the right, there may occur very curvy and very straight borders.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Diversity of plug position:</guilabel></term>
+ <listitem><para>Determines how much the position of the plug on the edge varies. Position the slider at the very left, plugs are affixed to the middle of their edge.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Diversity of plugs:</guilabel></term>
+ <listitem><para>Determines how individual the plugs look like. Position the slider 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><guilabel>Diversity of piece size:</guilabel></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><guilabel>Dump grid image:</guilabel></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>
+ </chapter>
- <chapter id="puzzletable">
- <title>Playing on the puzzle table</title>
+ <chapter id="puzzletable">
+ <title>Playing on the puzzle table</title>
- <sect1 id="puzzletable-moves">
- <title>Basic moves</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 into an image.</para>
- <para>The floating Preview window shows you what that image should be. Use a toolbar or menu action to show or hide the window. For a detailed description, see <link linkend="puzzletable-preview">The Preview window</link>.</para>
- <para>If you wish to attempt a puzzle that has 300 or more pieces, please read the chapter on <link linkend="large-puzzles">Facilities for solving large puzzles</link>, after you have read this chapter.</para>
- <para>You can move a single piece by clicking and dragging it with the &LMB;. That will leave the piece selected and highlighted. To move several pieces at once, first select and highlight them, then click and drag just one of the pieces. The rest will follow.</para>
- <para>You can select and highlight multiple pieces by holding &Ctrl; and clicking on them, or by dragging a rubberband around them with the &LMB;. You can also use &Ctrl; and &LMB; to increase or decrease the current selection one piece at a time.</para>
- <para>To remove selection and highlighting, just click on an empty spot on the puzzle table or on a piece that is not already selected.</para>
- <para>When you put one piece near a neighboring piece, both pieces will automatically snap together and become joined (1). After pieces have been snapped together, they cannot be torn apart. Another difference between &palapeli; and a real-world jigsaw puzzle is that you cannot combine two pieces that are not true neighbors.</para>
- <para>The progress bar below the puzzle table indicates your progress by counting joined pieces (2). &palapeli; will automatically save your progress after every move, so you do not have to worry about saving.</para>
- <para>You can zoom the puzzle table view in or out with the mouse wheel, the slider at the bottom right or the buttons at the bottom right (3).</para>
- <para>You can move the puzzle table view in any direction by clicking and dragging with the &RMB;.</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) to the right of the progress bar. The shade (4) around the puzzle table will darken, and pieces will now stop moving at the edges of the puzzle table area. It is still possible to adjust the size of the puzzle table area manually.</para>
- </sect1>
+ <sect1 id="puzzletable-moves">
+ <title>Basic moves</title>
+ <screenshot><mediaobject>
+ <imageobject><imagedata fileref="puzzletable1.png" format="PNG"/></imageobject>
+ <textobject><phrase>The puzzle table (detail)</phrase></textobject>
+ </mediaobject></screenshot>
+ <para>The goal of the game is to assemble the given pieces into an image.</para>
+ <para>The floating Preview window shows you what that image should be. Use a toolbar or menu item to show or hide the window. For a detailed description, see <link linkend="puzzletable-preview">The Preview window</link>.</para>
+ <para>If you wish to attempt a puzzle that has 300 or more pieces, please read the chapter on <link linkend="large-puzzles">Facilities for solving large puzzles</link>, after you have read this chapter.</para>
+ <para>You can move a single piece by clicking and dragging it with the &LMB;. That will leave the piece selected and highlighted. To move several pieces at once, first select and highlight them, then click and drag just one of the pieces. The rest will follow.</para>
+ <para>You can select and highlight multiple pieces by holding &Ctrl; and clicking on them, or by dragging a rubberband around them with the &LMB;. You can also hold the &Ctrl; key and click with the &LMB; to increase or decrease the current selection one piece at a time.</para>
+ <para>To remove selection and highlighting, just click on an empty spot on the puzzle table or on a piece that is not already selected.</para>
+ <para>When you put one piece near a neighboring piece, both pieces will automatically snap together and become joined (1). After pieces have been snapped together, they cannot be torn apart. Another difference between &palapeli; and a real-world jigsaw puzzle is that you cannot combine two pieces that are not true neighbors.</para>
+ <para>The progress bar below the puzzle table indicates your progress by counting joined pieces (2). &palapeli; will automatically save your progress after every move, so you do not have to worry about saving.</para>
+ <para>You can zoom the puzzle table view in or out with the mouse <mousebutton>wheel</mousebutton>, and at the bottom right (3) with the buttons and the slider.</para>
+ <para>You can move the puzzle table view in any direction by clicking and dragging with the &RMB;.</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 icon (5) to the right of the progress bar. The shade (4) around the puzzle table will darken, and pieces will now stop moving at the edges of the puzzle table area. It is still possible to adjust the size of the puzzle table area manually.</para>
+ </sect1>
- <sect1 id="puzzletable-preview">
- <title>The Preview window</title>
- <para>The Preview is a small window that floats
- above or to one side of the puzzle table window. It
- contains an image of the completed puzzle: the picture
- that would appear on top of the box if this was a
- real-world jigsaw puzzle.
- </para>
- <para>The window can be shown or hidden by using the
- <guiicon>Preview</guiicon> toolbar button or the
- <menuchoice><guimenu>View</guimenu><guimenuitem>
- Preview</guimenuitem></menuchoice> menu item. Its
- size, position and visible or not visible setting
- are saved and restored between runs of &palapeli;.
- </para>
- <para>Being a window, it can be freely moved around
- the desktop and resized. Its Close button will
- hide it and its Maximize button will expand or
- contract the picture rapidly.
- </para>
- <para>The Preview window has a magnification
- feature, so it need not take up much space.
- If you move the mouse over the window,
- it zooms in quickly to reveal a magnified view
- of the area under the mouse and the equivalent
- of a few pieces around it. This is very useful
- for viewing details of the puzzle and identifying
- pieces you have found, but it can be tricky to
- control, especially near the edges of the picture.
- </para>
- </sect1>
+ <sect1 id="puzzletable-preview">
+ <title>The Preview window</title>
+ <para>The Preview is a small window that floats
+ above or to one side of the puzzle table window. It
+ contains an image of the completed puzzle: the picture
+ that would appear on top of the box if this was a
+ real-world jigsaw puzzle.
+ </para>
+ <para>The window can be shown or hidden by using the
+ <inlinemediaobject><imageobject><imagedata fileref="view-preview.png" format="PNG"/>
+ </imageobject></inlinemediaobject> <guiicon>Preview</guiicon>
+ toolbar icon or the <menuchoice><guimenu>View</guimenu>
+ <guimenuitem>Preview</guimenuitem></menuchoice> menu item. Its
+ size, position and visible or not visible setting
+ are saved and restored between runs of &palapeli;.
+ </para>
+ <para>Being a window, it can be freely moved around
+ the desktop and resized. Its <guibutton>Close</guibutton>
+ button will hide it and its <guibutton>Maximize</guibutton>
+ button will expand or contract the picture rapidly.
+ </para>
+ <para>The Preview window has a magnification
+ feature, so it need not take up much space.
+ If you move the mouse over the window,
+ it zooms in quickly to reveal a magnified view
+ of the area under the mouse and the equivalent
+ of a few pieces around it. This is very useful
+ for viewing details of the puzzle and identifying
+ pieces you have found, but it can be tricky to
+ control, especially near the edges of the picture.
+ </para>
+ </sect1>
- <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>Change size of puzzle table area by dragging its edges</action></term>
- <listitem><para>By default, this action is assigned to the &LMB;.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Move pieces by dragging</action></term>
- <listitem><para>When you click and drag a puzzle piece, this piece will be moved. If multiple pieces have been 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>Move viewport by dragging</action></term>
- <listitem><para>This action moves the view of the entire puzzle table in any direction. By default, it is assigned to the &RMB;.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Select several pieces by rubberbanding</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>Select several pieces by clicking</action></term>
- <listitem><para>When you click on a puzzle piece, it will be selected or, if it was already selected, it will be deselected. It can also be used to adjust a rubberband selection. By default, this action is assigned to the &LMB; and only available when &Ctrl; is pressed.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Clear selections and highlighting</action></term>
- <listitem><para>Click on an empty spot in the puzzle table or on a piece that is not already selected.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Zoom the puzzle table view in or out</action></term>
- <listitem><para>This action is identical to clicking the buttons either side of the slider (3) on the status bar. It is assigned to the mouse wheel by default.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Switch to close-up or distant view</action></term>
- <listitem><para>This action alternates (toggles) between a close-up and distant view, at the position of the mouse pointer. It is intended mainly to provide fast zooming in large puzzles (300 pieces or more). For more detail, see <link linkend="large-puzzle-fast-zooming">Fast zooming between close-up and distant view</link>. By default, the action is assigned to the &MMB;.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Teleport pieces to or from a holder</action></term>
- <listitem><para>This action helps you collect, sort and move pieces rapidly in large puzzles (300 pieces or more) without dragging and dropping. You can use it in smaller puzzles if you wish. For more detail, see <link linkend="large-puzzle-holders">Using piece-holders</link>. By default, the action is assigned to the &LMB; and only available when &Shift; is pressed.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><action>Toggle lock state of the puzzle table area</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>
- </variablelist>
- </sect1>
+ <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>Change size of puzzle table area by dragging its edges</action></term>
+ <listitem><para>By default, this action is assigned to the &LMB;.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Move pieces by dragging</action></term>
+ <listitem><para>When you click and drag a puzzle piece, this piece will be moved. If multiple pieces have been 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>Move viewport by dragging</action></term>
+ <listitem><para>This action moves the view of the entire puzzle table in any direction. By default, it is assigned to the &RMB;.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Select several pieces by rubber banding</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>Select multiple pieces at once</action></term>
+ <listitem><para>When you click on a puzzle piece, it will be selected or, if it was already selected, it will be deselected. It can also be used to adjust a rubberband selection. By default, this action is assigned to the &LMB; and only available when &Ctrl; is pressed.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Clear selections and highlighting</action></term>
+ <listitem><para>Click on an empty spot in the puzzle table or on a piece that is not already selected.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Zoom the puzzle table view in or out</action></term>
+ <listitem><para>This action is identical to clicking the buttons either side of the slider (3) on the status bar. It is assigned to the mouse <mousebutton>wheel</mousebutton> by default.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Switch to close-up or distant view</action></term>
+ <listitem><para>This action alternates (toggles) between a close-up and distant view, at the position of the mouse pointer. It is intended mainly to provide fast zooming in large puzzles (300 pieces or more). For more detail, see <link linkend="large-puzzle-fast-zooming">Fast zooming between close-up and distant view</link>. By default, the action is assigned to the &MMB;.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Teleport pieces to or from a holder</action></term>
+ <listitem><para>This action helps you collect, sort and move pieces rapidly in large puzzles (300 pieces or more) without dragging and dropping. You can use it in smaller puzzles if you wish. For more detail, see <link linkend="large-puzzle-holders">Using piece-holders</link>. By default, the action is assigned to the &LMB; and only available when &Shift; key is pressed.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Toggle lock state of the puzzle table area</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 <mousebutton>wheel</mousebutton>, but you can enable it from <link linkend="configuration-mouseactions">the configuration dialog</link>.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
- <sect1 id="toolbars-puzzletable">
- <title>Toolbar overview</title>
- <variablelist>
- <varlistentry>
- <term><guiicon>Back to collection</guiicon></term>
- <listitem><para><action>Go back to the collection to choose another puzzle.</action> Can be used only when you are solving a puzzle.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><guiicon>Preview</guiicon></term>
- <listitem><para><action>Toggle the display of the preview window with the completed puzzle.</action></para></listitem>
- </varlistentry>
- </variablelist>
- </sect1>
- </chapter>
+ <sect1 id="toolbars-puzzletable">
+ <title>Toolbar overview</title>
+ <variablelist>
+ <varlistentry>
+ <term><inlinemediaobject><imageobject><imagedata fileref="go-previous.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Back to Collection</guiicon></term>
+ <listitem><para><action>Go back to the collection to choose another puzzle.</action> Can be used only when you are solving a puzzle.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><inlinemediaobject><imageobject><imagedata fileref="view-preview.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Preview</guiicon></term>
+ <listitem><para><action>Toggle the display of the preview window with the completed puzzle.</action></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+ </chapter>
- <chapter id="large-puzzles">
- <title>Facilities for solving large puzzles</title>
+ <chapter id="large-puzzles">
+ <title>Facilities for solving large puzzles</title>
- <sect1 id="large-puzzle-general">
- <title>General principles</title>
- <para>&palapeli; can handle large puzzles from 300 to
- 10,000 pieces, but you need some special facilities to
- help you work with them on a small screen.
- </para>
- <para>You can create a large puzzle in exactly the
- same way as a smaller puzzle. See the chapter on
- <link linkend="create-puzzles">Creating new
- puzzles</link>, but there are some things you
- need to think about before you begin. For details see
- <link linkend="large-puzzle-creation">Creating large
- puzzles - special concerns</link>.
- </para>
- <para>The Preview window is very useful in large
- puzzles: see the section about it for a
- <link linkend="puzzletable-preview">
- detailed description</link>.
- </para>
- <para>Managing space and moving around are your next
- concerns. When you zoom out to view the whole puzzle
- table, it becomes hard to see individual pieces. If
- you zoom in and find a piece you are looking for, it
- is unlikely that the place where it goes will be
- visible in the view.
- See the <link linkend="large-puzzle-space">Managing
- space and moving around</link> section for some
- solutions to these problems and others.
- </para>
- <para>Finally, you need to collect pieces and convey
- them to your solution area in some more efficient
- way than repetitive dragging and dropping over
- large distances. This is where piece-holders come in.
- </para>
- <para>When you start a large puzzle, you are given
- a holder (a small floating window) called <quote>Hand</quote>
- into which you can put pieces when and wherever
- you see them. Then you can drop them near your
- solution and work out where each piece has to go.
- This is like collecting pieces in one hand as you
- scan a large real-world jigsaw puzzle.
- </para>
- <para>You may need some systematic way to collect
- and sort pieces by common attributes (⪚ edges, sky,
- skyline, etc.) and so you can use as many holders
- as you like and give them names. Holders are saved
- continually, along with the puzzle table, which
- means you can use them to build up parts of the
- solution and store them or even to store pieces
- that you wish to put into a <quote>too hard basket</quote>
- until later. For details on how to use holders
- see the <link linkend="large-puzzle-holders">Using
- piece-holders</link> section.
- </para>
- <para>Finally, the <link linkend="puzzletable-mouseactions">Mouse interactions</link>
- section lists the two special mouse actions that
- make working with large puzzles quicker and easier:
- teleporting pieces and zooming to close-up or
- distant view.
- </para>
- </sect1>
+ <sect1 id="large-puzzle-general">
+ <title>General principles</title>
+ <para>&palapeli; can handle large puzzles from 300 to
+ 10,000 pieces, but you need some special facilities to
+ help you work with them on a small screen.
+ </para>
+ <para>You can create a large puzzle in exactly the
+ same way as a smaller puzzle. See the chapter on
+ <link linkend="create-puzzles">Creating new
+ puzzles</link>, but there are some things you
+ need to think about before you begin. For details see
+ <link linkend="large-puzzle-creation">Creating large
+ puzzles - special concerns</link>.
+ </para>
+ <para>The Preview window is very useful in large
+ puzzles: see the section about it for a
+ <link linkend="puzzletable-preview">detailed description</link>.
+ </para>
+ <para>Managing space and moving around are your next
+ concerns. When you zoom out to view the whole puzzle
+ table, it becomes hard to see individual pieces. If
+ you zoom in and find a piece you are looking for, it
+ is unlikely that the place where it goes will be
+ visible in the view.
+ See the <link linkend="large-puzzle-space">Managing
+ space and moving around</link> section for some
+ solutions to these problems and others.
+ </para>
+ <para>Finally, you need to collect pieces and convey
+ them to your solution area in some more efficient
+ way than repetitive dragging and dropping over
+ large distances. This is where piece-holders come in.
+ </para>
+ <para>When you start a large puzzle, you are given
+ a holder (a small floating window) called <quote>Hand</quote>
+ into which you can put pieces when and wherever
+ you see them. Then you can drop them near your
+ solution and work out where each piece has to go.
+ This is like collecting pieces in one hand as you
+ scan a large real-world jigsaw puzzle.
+ </para>
+ <para>You may need some systematic way to collect
+ and sort pieces by common attributes (⪚ edges, sky,
+ skyline, &etc;) and so you can use as many holders
+ as you like and give them names. Holders are saved
+ continually, along with the puzzle table, which
+ means you can use them to build up parts of the
+ solution and store them or even to store pieces
+ that you wish to put into a <quote>too hard basket</quote>
+ until later. For details on how to use holders
+ see the <link linkend="large-puzzle-holders">Using
+ piece-holders</link> section.
+ </para>
+ <para>Finally, the <link linkend="puzzletable-mouseactions">Mouse interactions</link>
+ section lists the two special mouse actions that
+ make working with large puzzles quicker and easier:
+ teleporting pieces and zooming to close-up or
+ distant view.
+ </para>
+ </sect1>
- <sect1 id="large-puzzle-creation">
- <title>Creating large puzzles - special concerns</title>
- <para>Before you create a large puzzle, you should make
- sure that the image in your source contains enough
- detail (&ie; enough megapixels). You can use a file
- utility or photo viewer/editor to find out how many
- pixels wide and high your picture is when not compressed
- by JPEG or other image format. As a rough rule of thumb,
- allow one megapixel per 1,000 pieces. That will give
- each piece about 1,000 pixels or more than 30 by 30
- pixels, making the pieces
- reasonably sharp at the edges and clear to see when you
- zoom in. You can work with fewer megapixels, but it may
- be hard to distinguish and recognize pieces during play.
- </para>
- <para>When you create or restart a large puzzle, it may
- be best to avoid using the bevel and shadowing features
- of &palapeli; (see the
- <link linkend="configuration-general">General
- settings</link> section), because they make loading
- slower and highlighting harder to see when the pieces
- in the view are very small. More prominent highlighting
- appears when shadowing is not used.
- </para>
- </sect1>
+ <sect1 id="large-puzzle-creation">
+ <title>Creating large puzzles - special concerns</title>
+ <para>Before you create a large puzzle, you should make
+ sure that the image in your source contains enough
+ detail (&ie; enough megapixels). You can use a file
+ utility or photo viewer/editor to find out how many
+ pixels wide and high your picture is when not compressed
+ by JPEG or other image format. As a rough rule of thumb,
+ allow one megapixel per 1,000 pieces. That will give
+ each piece about 1,000 pixels or more than 30 by 30
+ pixels, making the pieces
+ reasonably sharp at the edges and clear to see when you
+ zoom in. You can work with fewer megapixels, but it may
+ be hard to distinguish and recognize pieces during play.
+ </para>
+ <para>When you create or restart a large puzzle, it may
+ be best to avoid using the bevel and shadowing features
+ of &palapeli; (see the
+ <link linkend="configuration-general">General
+ settings</link> section), because they make loading
+ slower and highlighting harder to see when the pieces
+ in the view are very small. More prominent highlighting
+ appears when shadowing is not used.
+ </para>
+ </sect1>
- <sect1 id="large-puzzle-space">
- <title>Managing space and moving around</title>
- <sect2 id="large-puzzle-space-allocation">
- <title>Allocating space on the puzzle table</title>
- <para>When you create or restart a puzzle, the
- pieces are shuffled and placed randomly into grid
- locations on the puzzle table. Two settings affect
- the space required, see
- <link linkend="configuration">Game Configuration</link>
- for a list of settings provided via
- <menuchoice><guimenu>Settings</guimenu>
- <guimenuitem>Configure &palapeli;...</guimenuitem>
- </menuchoice> or, on Apple OS X,
- <menuchoice><guimenu>&palapeli;</guimenu>
- <guimenuitem>Preferences...</guimenuitem></menuchoice>.
- </para>
- <para>The spacing of pieces in puzzle grids can be
- set from 1.0 to 1.5 times the height and width of
- the highest and widest pieces. Smaller settings
- pack the pieces into the view better, but larger
- ones allow more space for dragging, dropping and
- rubberbanding. The default is 1.3, but 1.1 is
- very workable in large puzzles. The setting
- applies to puzzles of all sizes, and also
- affects grids used with piece-holders (see
- <link linkend="large-puzzle-holders">Using
- piece-holders</link>) or when re-arranging
- pieces automatically on the puzzle table, using
- <menuchoice><shortcut><keycap>R</keycap></shortcut>
- <guimenu>Move</guimenu><guimenuitem>Rearrange
- pieces</guimenuitem></menuchoice>.
- </para>
- <para>The other setting provides space on the
- puzzle table of exactly the right size for
- building your solution. The default is for it
- to appear in the center, with the pieces
- distributed evenly around the outside. On
- average, this should put the pieces closest to
- where they have to go eventually. You can also
- choose to use any of the four corners or have
- no space (option None), in which case you have
- to clear space manually, perhaps by expanding
- the puzzle table area (see
- <link linkend="puzzletable-moves">Basic moves</link>).
- The solution space setting affects puzzles
- down to 20 pieces, but with fewer than 20 pieces
- solution spaces are pointless.
- </para>
- <para>As the puzzle solution progresses, pieces
- move into the solution area and leave spaces
- elsewhere. It may be helpful to pack the
- remaining pieces closer together. If so, select
- some pieces using rubberbanding or &Ctrl; and
- &LMB;, then use <menuchoice><shortcut>
- <keycap>R</keycap></shortcut>
- <guimenu>Move</guimenu>
- <guimenuitem>Rearrange pieces</guimenuitem></menuchoice>
- or simply the shortcut key (default
- <keycap>R</keycap>). The pieces are packed into
- a grid and remain selected, so that they can be
- easily moved to a better position, if required.
- This is also a way to gather together pieces
- with some common attribute, but using
- piece-holders is more powerful.
- </para>
- </sect2>
- <sect2 id="large-puzzle-fast-zooming">
- <title>Fast zooming between close-up and distant view</title>
- <para>When a puzzle is loaded, &palapeli;
- calculates distant and close-up views and
- displays the distant view, which shows the
- entire puzzle table area. The close-up view
- shows pieces at a convenient viewing size for
- your eyes and your screen and desktop. Use
- the &MMB; to switch quickly between the two
- views, at a location where the mouse is
- pointing. Then you can home in quickly on any
- piece in the puzzle table and see what shape
- it is and what part of the picture it contains.
- </para>
- <para>You can adjust the scale of either view by
- zooming manually and your setting will be
- remembered next time you switch the view by
- using the &MMB;. Puzzles of all sizes have the
- fast zooming feature, but in puzzles with less
- than 100 pieces the two views are almost the
- same as each other. In other words, the pieces
- are easy to see when you view the whole puzzle table.
- </para>
- </sect2>
- <sect2 id="large-puzzle-navigating">
- <title>Moving around in a large puzzle</title>
- <para>The hard way to move pieces in a large puzzle
- is to select them and then alternately drag the
- pieces and the puzzle table (&LMB; and &RMB;)
- until you get to your destination. A much easier
- way to do the same thing is to select the pieces,
- zoom to distant view (&MMB;, see above), drag
- the pieces to the destination in one move (&LMB;)
- and then zoom to close-up view (&MMB;). This is
- also a good way to retrieve a single stray piece,
- but dragging that tiny piece across the puzzle
- table, without losing the selection, can be
- tricky if there are thousands of pieces.
- </para>
- <para>Another way to navigate and search the puzzle
- table systematically is to zoom in on the top
- left corner (&MMB;), then use the empty spaces
- in the scroll bars to step through the table
- horizontally or vertically, one fixed-size
- <quote>page</quote> at a time. This technique is very
- effective when you are using piece-holders to
- collect pieces you are looking for. If you
- keep the close-up scale fixed and always start
- at the same place, you will always get <quote>pages</quote>
- of fixed size and contents.
- </para>
- </sect2>
- <sect2 id="large-puzzle-visibility">
- <title>Visibility of pieces in large puzzles</title>
- <para>In large jigsaw puzzles on a small screen it
- can be hard to see what you are doing. For
- example, with a 10,000 piece puzzle on a
- 1440 by 900 screen, the pieces in the distant
- view of the puzzle table are about 7 pixels
- across. At this scale, it is hard to see picture,
- color, piece-shape or even highlighting.
- </para>
- <para>&palapeli; has always had a choice of
- backgrounds and background colors and that
- helps visibility. Added to these is a more
- prominent highlighting scheme, which appears
- if you do not choose shadowing, and a setting
- to choose the color of the highlight, to
- contrast with the background and most pieces.
- Also these settings are now saved and restored
- with each puzzle. So each puzzle can have the
- background and highlighting that best suits
- its overall picture. It is worth experimenting
- with settings when you create a large puzzle,
- but you may need to reload or restart the
- puzzle before all changes can take effect.
- </para>
- </sect2>
- </sect1>
+ <sect1 id="large-puzzle-space">
+ <title>Managing space and moving around</title>
+ <sect2 id="large-puzzle-space-allocation">
+ <title>Allocating space on the puzzle table</title>
+ <para>When you create or restart a puzzle, the
+ pieces are shuffled and placed randomly into grid
+ locations on the puzzle table. Two settings affect
+ the space required, see
+ <link linkend="configuration">Game Configuration</link>
+ for a list of settings provided via
+ <menuchoice><guimenu>Settings</guimenu>
+ <guimenuitem>Configure &palapeli;...</guimenuitem>
+ </menuchoice> or, on &macOS;,
+ <menuchoice><guimenu>&palapeli;</guimenu>
+ <guimenuitem>Preferences...</guimenuitem></menuchoice>
+ menu item.
+ </para>
+ <para>The spacing of pieces in puzzle grids can be
+ set from 1.0 to 1.5 times the height and width of
+ the highest and widest pieces. Smaller settings
+ pack the pieces into the view better, but larger
+ ones allow more space for dragging, dropping and
+ rubber banding. The default is 1.3, but 1.1 is
+ very workable in large puzzles. The setting
+ applies to puzzles of all sizes, and also
+ affects grids used with piece-holders (see
+ <link linkend="large-puzzle-holders">Using
+ piece-holders</link>) or when re-arranging
+ pieces automatically on the puzzle table, using the
+ <menuchoice><shortcut><keycap>R</keycap></shortcut>
+ <guimenu>Move</guimenu><guimenuitem>Rearrange
+ Pieces</guimenuitem></menuchoice> menu item.
+ </para>
+ <para>The other setting provides space on the
+ puzzle table of exactly the right size for
+ building your solution. The default is for it
+ to appear in the center, with the pieces
+ distributed evenly around the outside. On
+ average, this should put the pieces closest to
+ where they have to go eventually. You can also
+ choose to use any of the four corners or have
+ no space (option <guilabel>None</guilabel>), in
+ which case you have to clear space manually,
+ perhaps by expanding the puzzle table area (see
+ <link linkend="puzzletable-moves">Basic moves</link>).
+ The solution space setting affects puzzles
+ down to 20 pieces, but with fewer than 20 pieces
+ solution spaces are pointless.
+ </para>
+ <para>As the puzzle solution progresses, pieces
+ move into the solution area and leave spaces
+ elsewhere. It may be helpful to pack the
+ remaining pieces closer together. If so, select
+ some pieces using rubber banding or hold the &Ctrl;
+ key and click with the &LMB;, then use the
+ <menuchoice><shortcut><keycap>R</keycap></shortcut>
+ <guimenu>Move</guimenu>
+ <guimenuitem>Rearrange Pieces</guimenuitem></menuchoice>
+ menu item or simply the shortcut (default is the
+ <keycap>R</keycap> key). The pieces are packed into
+ a grid and remain selected, so that they can be
+ easily moved to a better position, if required.
+ This is also a way to gather together pieces
+ with some common attribute, but using
+ piece-holders is more powerful.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-fast-zooming">
+ <title>Fast zooming between close-up and distant view</title>
+ <para>When a puzzle is loaded, &palapeli;
+ calculates distant and close-up views and
+ displays the distant view, which shows the
+ entire puzzle table area. The close-up view
+ shows pieces at a convenient viewing size for
+ your eyes and your screen and desktop. Use
+ the &MMB; to switch quickly between the two
+ views, at a location where the mouse is
+ pointing. Then you can home in quickly on any
+ piece in the puzzle table and see what shape
+ it is and what part of the picture it contains.
+ </para>
+ <para>You can adjust the scale of either view by
+ zooming manually and your setting will be
+ remembered next time you switch the view by
+ using the &MMB;. Puzzles of all sizes have the
+ fast zooming feature, but in puzzles with less
+ than 100 pieces the two views are almost the
+ same as each other. In other words, the pieces
+ are easy to see when you view the whole puzzle table.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-navigating">
+ <title>Moving around in a large puzzle</title>
+ <para>The hard way to move pieces in a large puzzle
+ is to select them and then alternately drag the
+ pieces and the puzzle table (&LMB; and &RMB;)
+ until you get to your destination. A much easier
+ way to do the same thing is to select the pieces,
+ zoom to distant view (&MMB;, see above), drag
+ the pieces to the destination in one move (&LMB;)
+ and then zoom to close-up view (&MMB;). This is
+ also a good way to retrieve a single stray piece,
+ but dragging that tiny piece across the puzzle
+ table, without losing the selection, can be
+ tricky if there are thousands of pieces.
+ </para>
+ <para>Another way to navigate and search the puzzle
+ table systematically is to zoom in on the top
+ left corner (&MMB;), then use the empty spaces
+ in the scroll bars to step through the table
+ horizontally or vertically, one fixed-size
+ <quote>page</quote> at a time. This technique is very
+ effective when you are using piece-holders to
+ collect pieces you are looking for. If you
+ keep the close-up scale fixed and always start
+ at the same place, you will always get <quote>pages</quote>
+ of fixed size and contents.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-visibility">
+ <title>Visibility of pieces in large puzzles</title>
+ <para>In large jigsaw puzzles on a small screen it
+ can be hard to see what you are doing. For
+ example, with a 10,000 piece puzzle on a
+ 1440 by 900 screen, the pieces in the distant
+ view of the puzzle table are about 7 pixels
+ across. At this scale, it is hard to see picture,
+ color, piece-shape or even highlighting.
+ </para>
+ <para>&palapeli; has always had a choice of
+ backgrounds and background colors and that
+ helps visibility. Added to these is a more
+ prominent highlighting scheme, which appears
+ if you do not choose shadowing, and a setting
+ to choose the color of the highlight, to
+ contrast with the background and most pieces.
+ Also these settings are now saved and restored
+ with each puzzle. So each puzzle can have the
+ background and highlighting that best suits
+ its overall picture. It is worth experimenting
+ with settings when you create a large puzzle,
+ but you may need to reload or restart the
+ puzzle before all changes can take effect.
+ </para>
+ </sect2>
+ </sect1>
- <sect1 id="large-puzzle-holders">
- <title>Using piece-holders</title>
- <sect2 id="large-puzzle-whatareholders">
- <title>What are piece-holders?</title>
- <para>Piece-holders are perhaps the most useful
- feature of &palapeli; for helping solve large
- puzzles. They are small, floating windows into
- which you can sort groups of pieces, such as
- <quote>edges</quote>, <quote>sky</quote>,
- <quote>skyline</quote> or <quote>white house on
- left</quote>. Initially they appear at a minimum size
- which is just large enough to show four pieces at
- close-up scale, so they are quite easy to fit
- in next to the main puzzle table window.
- </para>
- <para>Being windows, holders can be freely moved
- around the desktop and resized. The Close button
- will delete the holder, but only if it contains
- no pieces. The Maximize button will expand or
- contract the holder rapidly. The holder can contain
- any number of pieces (maybe hundreds). A Maximize
- action can be useful when reviewing the contents or
- constructing a sub-assembly inside the holder.
- </para>
- <para>You can have as many holders as you like.
- There is usually one which is active - outlined
- in blue. It is the target for actions such as
- transferring pieces or deleting a holder.
- </para>
- </sect2>
- <sect2 id="large-puzzle-createholders">
- <title>Creating and deleting holders</title>
- <para>When you start a large puzzle, a holder
- called <quote>Hand</quote> is created automatically.
- This may be the only holder you need with puzzles
- of 300 to 750 pieces, but you can have as many
- holders as you like, even with puzzles of less
- than 300 pieces.
- </para>
- <para>To create or delete a holder, use
- <menuchoice><shortcut><keycap>C</keycap></shortcut>
- <guimenu>Move</guimenu><guimenuitem>
- Create piece holder...</guimenuitem></menuchoice>
- or
- <menuchoice><shortcut><keycap>D</keycap></shortcut>
- <guimenu>Move</guimenu><guimenuitem>
- Delete piece holder</guimenuitem></menuchoice>, or
- simply the shortcut keys <keycap>C</keycap> and
- <keycap>D</keycap>, or the Close button to delete.
- When you create a holder, you are asked to give it
- a name, but that is not essential. Usually the
- holder is at close-up scale and you can easily see
- what kind of piece is in it.
- </para>
- <para>When you delete a holder, it must be active
- (outlined in blue) and empty of pieces. If the
- holder to be deleted is not active, click on it.
- After deletion, there is no active holder, so
- click on one of those that are left.
- </para>
- </sect2>
- <sect2 id="large-puzzle-teleporting">
- <title>Transferring pieces into and out of holders</title>
- <para>Transferring pieces by dragging and dropping
- is not possible with holders, nor is it needed.
- Instead, you can transfer pieces instantly by
- <quote>teleporting</quote>, as in <quote>Star Trek</quote>.
- Teleporting works
- by using the &Shift; and &LMB; together.
- </para>
- <para>To transfer pieces to a holder, make sure your
- target holder is active (outlined in blue),
- then select some pieces on the puzzle table
- and click with &Shift; and &LMB;. Or you can
- just click on one piece at a time with &Shift;
- and &LMB;. The transferred pieces vanish from
- the puzzle table and reappear, highlighted,
- in the holder. As they arrive, they are
- automatically packed into a grid and the last
- piece transferred is centered in the view.
- </para>
- <para>To transfer pieces out of a holder, select
- a piece or pieces inside the holder, then
- return to the puzzle table and click on an
- empty spot where you would like the piece(s)
- to appear, using &Shift; and &LMB;. Avoid
- clicking on a piece that is already on the
- puzzle table: it will send the piece to the
- holder - not what you want. If you accidentally
- do this with a large joined-up piece
- (&ie; part of your solution), there
- is a warning message and an opportunity to cancel.
- </para>
- <para>Pieces stay highlighted after teleporting.
- That allows you to reverse the action quickly
- if you accidentally transfer the wrong pieces
- or use the wrong holder. Also, on the puzzle
- table, you can easily adjust the position of
- a piece or pieces that have just arrived or move
- a piece into the solution.
- </para>
- <para>Teleporting also works between holders.
- Start as if you are going to transfer pieces
- to the puzzle table, but then use &Shift;
- and &LMB; in an empty spot in another holder.
- To reverse the process, go back to the
- original holder and click with &Shift; and
- &LMB; again.
- </para>
- </sect2>
- <sect2 id="large-puzzle-sorting">
- <title>Sorting pieces</title>
- <para>To sort pieces into holders efficiently
- as you search through a large puzzle, use the
- technique for stepping through the puzzle a
- <quote>page</quote> at a time,
- <link linkend="large-puzzle-navigating">
- as described earlier</link>, combined with
- holders and teleporting to collect pieces
- as you go. When you have scanned the whole puzzle
- table, zoom to a close-up of your solution area and
- place the pieces you have collected. Or you
- can pre-assemble pieces in holders.
- </para>
- </sect2>
- <sect2 id="large-puzzle-otherholderactions">
- <title>Other holder actions</title>
- <para>Piece-holders support all the functions
- of the puzzle table (see <link linkend="puzzletable-moves">Basic moves</link>), except
- that you can only zoom by using the scroll-wheel
- or the &MMB;.
- </para>
- <para>This means that you can use a holder as an
- extra puzzle table, if you wish. You can drag
- and drop, join pieces together, move the
- boundaries of the area, &etc; You can also
- teleport assembled pieces of any size into
- or out of a holder, but beware of overlaps
- or small pieces being hidden.
- </para>
- <para>Finally, you can use <menuchoice><shortcut>
- <keycap>A</keycap></shortcut><guimenu>Move</guimenu>
- <guimenuitem>Select all in holder</guimenuitem>
- </menuchoice>, followed by <menuchoice><shortcut>
- <keycap>R</keycap></shortcut><guimenu>Move</guimenu>
- <guimenuitem>Rearrange pieces</guimenuitem>
- </menuchoice> or &Shift; and &LMB;, to re-pack all
- the pieces in the holder or empty all the pieces
- out onto the puzzle table. Or just use the shortcut
- keys <keycap>A</keycap> or <keycap>R</keycap> on the
- currently selected holder.
- </para>
- </sect2>
- </sect1>
- </chapter>
+ <sect1 id="large-puzzle-holders">
+ <title>Using piece-holders</title>
+ <sect2 id="large-puzzle-whatareholders">
+ <title>What are piece-holders?</title>
+ <para>Piece-holders are perhaps the most useful
+ feature of &palapeli; for helping solve large
+ puzzles. They are small, floating windows into
+ which you can sort groups of pieces, such as
+ <quote>edges</quote>, <quote>sky</quote>,
+ <quote>skyline</quote> or <quote>white house on
+ left</quote>. Initially they appear at a minimum size
+ which is just large enough to show four pieces at
+ close-up scale, so they are quite easy to fit
+ in next to the main puzzle table window.
+ </para>
+ <para>Being windows, holders can be freely moved
+ around the desktop and resized. The <guibutton>Close</guibutton>
+ button will delete the holder, but only if it contains
+ no pieces. The <guibutton>Maximize</guibutton> button
+ will expand or contract the holder rapidly. The holder
+ can contain any number of pieces (maybe hundreds). A
+ maximize action can be useful when reviewing the contents
+ or constructing a sub-assembly inside the holder.
+ </para>
+ <para>You can have as many holders as you like.
+ There is usually one which is active - outlined
+ in blue. It is the target for actions such as
+ transferring pieces or deleting a holder.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-createholders">
+ <title>Creating and deleting holders</title>
+ <para>When you start a large puzzle, a holder
+ called <quote>Hand</quote> is created automatically.
+ This may be the only holder you need with puzzles
+ of 300 to 750 pieces, but you can have as many
+ holders as you like, even with puzzles of less
+ than 300 pieces.
+ </para>
+ <para>To create or delete a holder, use the
+ <menuchoice><shortcut><keycap>C</keycap></shortcut>
+ <guimenu>Move</guimenu><guimenuitem>
+ Create Piece Holder...</guimenuitem></menuchoice>
+ or <menuchoice><shortcut><keycap>D</keycap></shortcut>
+ <guimenu>Move</guimenu><guimenuitem>
+ Delete Piece Holder</guimenuitem></menuchoice> menu items, or
+ simply the <keycap>C</keycap> and <keycap>D</keycap>
+ keys, or the <guibutton>Close</guibutton> button to
+ delete. When you create a holder, you are asked to
+ give it a name, but that is not essential. Usually
+ the holder is at close-up scale and you can easily
+ see what kind of piece is in it.
+ </para>
+ <para>When you delete a holder, it must be active
+ (outlined in blue) and empty of pieces. If the
+ holder to be deleted is not active, click on it.
+ After deletion, there is no active holder, so
+ click on one of those that are left.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-teleporting">
+ <title>Transferring pieces into and out of holders</title>
+ <para>Transferring pieces by dragging and dropping
+ is not possible with holders, nor is it needed.
+ Instead, you can transfer pieces instantly by
+ <quote>teleporting</quote>, as in <quote>Star Trek</quote>.
+ Teleporting works by hold the &Shift; key and click with the &LMB;.
+ </para>
+ <para>To transfer pieces to a holder, make sure your
+ target holder is active (outlined in blue),
+ then select some pieces on the puzzle table
+ and hold the &Shift; key and click with the &LMB;. Or you can
+ just click on one piece at a time by hold the &Shift;
+ key and click with the &LMB;. The transferred pieces vanish from
+ the puzzle table and reappear, highlighted,
+ in the holder. As they arrive, they are
+ automatically packed into a grid and the last
+ piece transferred is centered in the view.
+ </para>
+ <para>To transfer pieces out of a holder, select
+ a piece or pieces inside the holder, then
+ return to the puzzle table and click on an
+ empty spot where you would like the piece(s)
+ to appear, hold the &Shift; key and click with the &LMB;. Avoid
+ clicking on a piece that is already on the
+ puzzle table: it will send the piece to the
+ holder - not what you want. If you accidentally
+ do this with a large joined-up piece
+ (&ie; part of your solution), there
+ is a warning message and an opportunity to cancel.
+ </para>
+ <para>Pieces stay highlighted after teleporting.
+ That allows you to reverse the action quickly
+ if you accidentally transfer the wrong pieces
+ or use the wrong holder. Also, on the puzzle
+ table, you can easily adjust the position of
+ a piece or pieces that have just arrived or move
+ a piece into the solution.
+ </para>
+ <para>Teleporting also works between holders.
+ Start as if you are going to transfer pieces
+ to the puzzle table, but then by hold the &Shift;
+ key and click with the &LMB; in an empty spot in
+ another holder. To reverse the process, go back
+ to the original holder and hold the &Shift; key
+ and click with the &LMB; again.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-sorting">
+ <title>Sorting pieces</title>
+ <para>To sort pieces into holders efficiently
+ as you search through a large puzzle, use the
+ technique for stepping through the puzzle a
+ <quote>page</quote> at a time,
+ <link linkend="large-puzzle-navigating">
+ as described earlier</link>, combined with
+ holders and teleporting to collect pieces
+ as you go. When you have scanned the whole puzzle
+ table, zoom to a close-up of your solution area and
+ place the pieces you have collected. Or you
+ can pre-assemble pieces in holders.
+ </para>
+ </sect2>
+ <sect2 id="large-puzzle-otherholderactions">
+ <title>Other holder actions</title>
+ <para>Piece-holders support all the functions
+ of the puzzle table (see <link linkend="puzzletable-moves">Basic moves</link>), except
+ that you can only zoom by using the scroll-<mousebutton>wheel</mousebutton>
+ or the &MMB;.
+ </para>
+ <para>This means that you can use a holder as an
+ extra puzzle table, if you wish. You can drag
+ and drop, join pieces together, move the
+ boundaries of the area, &etc; You can also
+ teleport assembled pieces of any size into
+ or out of a holder, but beware of overlaps
+ or small pieces being hidden.
+ </para>
+ <para>Finally, you can use the <menuchoice><shortcut>
+ <keycap>A</keycap></shortcut><guimenu>Move</guimenu>
+ <guimenuitem>Select all in holder</guimenuitem>
+ </menuchoice> menu item, followed by <menuchoice><shortcut>
+ <keycap>R</keycap></shortcut><guimenu>Move</guimenu>
+ <guimenuitem>Rearrange Pieces</guimenuitem>
+ </menuchoice> menu item or hold the &Shift; key and click with the
+ &LMB;, to re-pack all the pieces in the holder or empty
+ all the pieces out onto the puzzle table. Or just use the
+ <keycap>A</keycap> or <keycap>R</keycap> keys on the
+ currently selected holder.
+ </para>
+ </sect2>
+ </sect1>
+ </chapter>
- <chapter id="interface">
- <title>Interface Overview</title>
- <para>The following are &palapeli;'s menu actions, some of which are also available as toolbar buttons and shortcut keys.</para>
- <variablelist>
- <varlistentry>
- <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut><guimenu>Game</guimenu><guimenuitem>Create new puzzle...</guimenuitem></menuchoice></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 corresponding section</link> for details and also <link linkend="large-puzzle-creation">special concerns</link>, if you are going to create a puzzle with 300 or more pieces.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><guimenu>Game</guimenu><guimenuitem>Import from file...</guimenuitem></menuchoice></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><menuchoice><guimenu>Game</guimenu><guimenuitem>Export to file...</guimenuitem></menuchoice></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>
- <varlistentry>
- <term><menuchoice><guimenu>Game</guimenu><guimenuitem>Delete puzzle</guimenuitem></menuchoice></term>
- <listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your collection.</action></para><warning><para>This action cannot be undone.</para></warning></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><guimenu>Game</guimenu><guimenuitem>Restart puzzle</guimenuitem></menuchoice></term>
- <listitem><para><action>Re-shuffle all the pieces and discard the saved progress for the current puzzle.</action></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><shortcut><keycap>C</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Create piece holder...</guimenuitem></menuchoice></term>
- <listitem><para><action>Create a temporary holder for storing or sorting pieces. See <link linkend="large-puzzle-holders">Using piece-holders</link> for details of how to use a holder.</action></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><shortcut><keycap>D</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Delete piece holder</guimenuitem></menuchoice></term>
- <listitem><para><action>Delete a selected temporary holder when it is empty.</action></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><shortcut><keycap>A</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Select all in holder</guimenuitem></menuchoice></term>
- <listitem><para><action>Select all pieces in the currently selected piece-holder (outlined in blue).</action></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><shortcut><keycap>R</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Rearrange pieces</guimenuitem></menuchoice></term>
- <listitem><para><action>Rearrange selected pieces in any holder or the puzzle table by packing them into a grid.</action></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><guimenu>View</guimenu><guimenuitem>Back to collection</guimenuitem></menuchoice></term>
- <listitem><para><action>Go back to the collection to choose another puzzle.</action> Can be used only when you are solving a puzzle.</para></listitem>
- </varlistentry>
+ <chapter id="interface">
+ <title>Interface Overview</title>
+ <para>The following are &palapeli;'s menu items, some of which are also available as action icons in the toolbar and keyboard shortcuts.</para>
+ <variablelist>
+ <varlistentry>
+ <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> </shortcut> <guimenu>Game</guimenu> <guimenuitem>Create New Puzzle...</guimenuitem></menuchoice></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 corresponding section</link> for details and also <link linkend="large-puzzle-creation">special concerns</link>, if you are going to create a puzzle with 300 or more pieces.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><guimenu>Game</guimenu><guimenuitem>Import from File...</guimenuitem></menuchoice></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><menuchoice><guimenu>Game</guimenu><guimenuitem>Export to File...</guimenuitem></menuchoice></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>
+ <varlistentry>
+ <term><menuchoice><guimenu>Game</guimenu><guimenuitem>Delete Puzzle</guimenuitem></menuchoice></term>
+ <listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your collection.</action></para><warning><para>This action cannot be undone.</para></warning></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><guimenu>Game</guimenu><guimenuitem>Restart Puzzle...</guimenuitem></menuchoice></term>
+ <listitem><para><action>Re-shuffle all the pieces and discard the saved progress for the current puzzle.</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> </shortcut> <guimenu>Game</guimenu> <guimenuitem>Quit</guimenuitem></menuchoice></term>
+ <listitem><para><action>Quit</action> the &palapeli;.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><shortcut><keycap>C</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Create Piece Holder...</guimenuitem></menuchoice></term>
+ <listitem><para><action>Create a temporary holder for storing or sorting pieces. See <link linkend="large-puzzle-holders">Using piece-holders</link> for details of how to use a holder.</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><shortcut><keycap>D</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Delete Piece Holder</guimenuitem></menuchoice></term>
+ <listitem><para><action>Delete a selected temporary holder when it is empty.</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><shortcut><keycap>A</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Select All in Holder</guimenuitem></menuchoice></term>
+ <listitem><para><action>Select all pieces in the currently selected piece-holder (outlined in blue).</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><shortcut><keycap>R</keycap></shortcut><guimenu>Move</guimenu><guimenuitem>Rearrange Pieces</guimenuitem></menuchoice></term>
+ <listitem><para><action>Rearrange selected pieces in any holder or the puzzle table by packing them into a grid.</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><guimenu>View</guimenu><guimenuitem>Back to Collection</guimenuitem></menuchoice></term>
+ <listitem><para><action>Go back to the collection to choose another puzzle.</action> Can be used only when you are solving a puzzle.</para></listitem>
+ </varlistentry>
- <varlistentry>
- <term><menuchoice><guimenu>View</guimenu><guimenuitem>Preview</guimenuitem></menuchoice></term>
- <listitem><para><action>Toggle the display of the completed puzzle preview image.</action> Hover it with the mouse pointer to zoom in the image.</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 scale.</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 scale.</action></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Enable all messages</guimenuitem></menuchoice></term>
- <listitem><para><action>Allows you to enable all messages disabled by checking the <guilabel>Do not show this message again</guilabel> item in the &palapeli; confirmation dialogs.</action></para></listitem>
- </varlistentry>
- <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 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>
- <para>
- Additionally &palapeli; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
- menu items, for more information read the sections about the <ulink url="help:/fundamentals/menus.html#menus-settings">Settings Menu</ulink> and <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
- </para>
- </chapter>
+ <varlistentry>
+ <term><menuchoice><guimenu>View</guimenu><guimenuitem>Preview</guimenuitem></menuchoice></term>
+ <listitem><para><action>Toggle the display of the completed puzzle preview image.</action> Hover it with the mouse pointer to zoom in the image.</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 scale.</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 scale.</action></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Enable All Messages</guimenuitem></menuchoice></term>
+ <listitem><para><action>Allows you to enable all messages disabled by checking the <guilabel>Do not show this message again</guilabel> option in the &palapeli; confirmation dialogs.</action></para></listitem>
+ </varlistentry>
+ <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 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>
+ <para>
+ Additionally &palapeli; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
+ menu items, for more information read the sections about the <ulink url="help:/fundamentals/menus.html#menus-settings">Settings Menu</ulink> and <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
+ </para>
+ </chapter>
- <chapter id="configuration">
- <title>Game Configuration</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>General settings</title>
- <variablelist>
- <varlistentry>
- <term><guilabel>Puzzle table</guilabel></term>
- <listitem>
- <para>
- Lets you choose some parameters of the puzzle table.
- </para>
- <variablelist>
- <varlistentry>
- <term><guilabel>Background</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 the color.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><guilabel>Color for highlighting selected pieces</guilabel></term>
- <listitem><para><action>Lets you choose the highlighting color of pieces when they are selected.</action> Click on the button to the right of the label to open the <ulink url="help:/fundamentals/colors.html">Color Selector</ulink> window.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><guilabel>Space for solution</guilabel></term>
- <listitem><para><action>Lets you choose where to reserve some space on the puzzle table for building the solution.</action> No space is provided if you select option None or the puzzle has less than 20 pieces. Changes will take effect when a puzzle is created or re-started.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><guilabel>Spacing of pieces in puzzle grids (1.0-1.5)</guilabel></term>
- <listitem><para><action>Lets you choose the spacing in puzzle grids.</action> Changes in the overall puzzle spacing will take effect only when a puzzle is created or re-started.</para></listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><guilabel>Piece appearance</guilabel></term>
- <listitem><para><action>Controls the appearance of pieces on the puzzle table.</action> If &palapeli; is running slowly or puzzles take a long time to open, you can disable the graphical effects in this category and speed up everything. If you choose shadowing, highlighting is implemented by changing the color of the shadow.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><guilabel>Snapping precision</guilabel></term>
- <listitem><para><action>Lets you choose how closely neighboring pieces must be positioned before they snap together.</action> If you move the slider to the right, pieces will snap together even if they are not so close. This makes the game a bit easier to play.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect1>
- <sect1 id="configuration-mouseactions">
- <title>Mouse interaction</title>
- <para>This page of the configuration dialog allows you to change the assignments of mouse buttons and modifier keys to the actions described in <link linkend="puzzletable-mouseactions">Playing on the puzzle table, Mouse interactions</link>. Care should be taken to avoid ambiguous assignments. Three of the default assignments can go to the &LMB; because the pointer is over different areas when you use them, but the other assignments must be distinct.</para>
- <para>The interactions are divided into those that can be assigned to mouse buttons (⪚ <action>Move viewport by dragging</action>), and those that can be assigned to the mouse wheel (⪚ <action>Scroll viewport horizontally</action>).</para>
- <sect2>
- <title>Mouse buttons tab</title>
- <para>To the right of 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 wish 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>Mouse wheel tab</title>
- <para>This tab works similarly 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>If your mouse has a bidirectional mouse wheel (as most commonly found on notebook touchpads), you can take advantage of this: The button will recognize whether you turned the mouse wheel horizontally or vertically.</para></tip>
- </sect2>
- </sect1>
- </chapter>
+ <chapter id="configuration">
+ <title>Game Configuration</title>
+ <para>To open the configuration dialog, use the menu item: <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &palapeli;...</guimenuitem></menuchoice></para>
+ <sect1 id="configuration-general">
+ <title>General settings</title>
+ <variablelist>
+ <varlistentry>
+ <term><guilabel>Puzzle table</guilabel></term>
+ <listitem>
+ <para>Lets you choose some parameters of the puzzle table.</para>
+ <variablelist>
+ <varlistentry>
+ <term><guilabel>Background:</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 the color.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Color for highlighting selected pieces:</guilabel></term>
+ <listitem><para><action>Lets you choose the highlighting color of pieces when they are selected.</action> Click on the button to the right of the label to open the <ulink url="help:/fundamentals/colors.html">Color Selector</ulink> window.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Space for solution:</guilabel></term>
+ <listitem><para><action>Lets you choose where to reserve some space on the puzzle table for building the solution.</action> No space is provided if you select option <guilabel>None</guilabel> or the puzzle has less than 20 pieces. Changes will take effect when a puzzle is created or re-started.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Spacing of pieces in puzzle grids (1.0-1.5):</guilabel></term>
+ <listitem><para><action>Lets you choose the spacing in puzzle grids.</action> Changes in the overall puzzle spacing will take effect only when a puzzle is created or re-started.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Piece appearance</guilabel></term>
+ <listitem><para><action>Controls the appearance of pieces on the puzzle table.</action> If &palapeli; is running slowly or puzzles take a long time to open, you can disable the graphical effects in this category and speed up everything. If you choose shadowing, highlighting is implemented by changing the color of the shadow.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><guilabel>Snapping precision</guilabel></term>
+ <listitem><para><action>Lets you choose how closely neighboring pieces must be positioned before they snap together.</action> If you move the slider to the right, pieces will snap together even if they are not so close. This makes the game a bit easier to play.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+ <sect1 id="configuration-mouseactions">
+ <title>Mouse interaction</title>
+ <para>This page of the configuration dialog allows you to change the assignments of mouse buttons and modifier keys to the actions described in <link linkend="puzzletable-mouseactions">Playing on the puzzle table, Mouse interactions</link>. Care should be taken to avoid ambiguous assignments. Three of the default assignments can go to the &LMB; because the pointer is over different areas when you use them, but the other assignments must be distinct.</para>
+ <para>The interactions are divided into those that can be assigned to mouse buttons (⪚ <action>Move viewport by dragging</action>), and those that can be assigned to the mouse <mousebutton>wheel</mousebutton> (⪚ <action>Scroll viewport horizontally</action>).</para>
+ <sect2>
+ <title>Mouse Buttons tab</title>
+ <para>To the right of 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 wish 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 &Space; 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>Mouse Wheel tab</title>
+ <para>This tab works similarly to the previous one. When the button on the right asks for input, you have to turn the mouse <mousebutton>wheel</mousebutton> instead of clicking a mouse button. Holding modifier keys is allowed, too, with the same consequences as in the previous case.</para>
+ <tip><para>If your mouse has a bidirectional mouse <mousebutton>wheel</mousebutton> (as most commonly found on notebook touchpads), you can take advantage of this: The button will recognize whether you turned the mouse <mousebutton>wheel</mousebutton> horizontally or vertically.</para></tip>
+ </sect2>
+ </sect1>
+ </chapter>
- <chapter id="credits">
- <title>Credits and License</title>
- <para>&palapeli; aims to bring the unagitated fun and challenge of jigsaw puzzles to your desktop.</para>
- <para>The idea was first developed by Bernhard Schiffner, together with Stefan Majewsky, who was the leading developer of &palapeli;.</para>
- <para>The &i18n-psc; was contributed by Johannes Löhnert.</para>
- <para>The large-puzzle facilities were contributed by Ian Wadham.</para>
- <para>Documentation Copyright 2009, 2010 Johannes Löhnert, Stefan Majewsky and Copyright 2014 Ian Wadham.</para>
- <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
- &underFDL;
- &underGPL;
- </chapter>
+ <chapter id="credits">
+ <title>Credits and License</title>
+ <para>&palapeli; aims to bring the unagitated fun and challenge of jigsaw puzzles to your desktop.</para>
+ <para>The idea was first developed by Bernhard Schiffner, together with Stefan Majewsky, who was the leading developer of &palapeli;.</para>
+ <para>The &i18n-psc; was contributed by Johannes Löhnert.</para>
+ <para>The large-puzzle facilities were contributed by Ian Wadham.</para>
+ <para>Documentation Copyright 2009, 2010 Johannes Löhnert, Stefan Majewsky and Copyright 2014 Ian Wadham.</para>
+ <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+ &underFDL;
+ &underGPL;
+ </chapter>
- &documentation.index;
+ &documentation.index;
</book>
diff --git a/doc/tools-wizard.png b/doc/tools-wizard.png
new file mode 100644
index 0000000..cbcb274
Binary files /dev/null and b/doc/tools-wizard.png differ
diff --git a/doc/view-preview.png b/doc/view-preview.png
new file mode 100644
index 0000000..ee6a4a4
Binary files /dev/null and b/doc/view-preview.png differ
More information about the kde-doc-english
mailing list