tdegames/doc/ktuberling/index.docbook

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

<book lang="&language;">
<bookinfo>
<title>The &ktuberling; Handbook</title>
<authorgroup>

<author>
<firstname>Éric</firstname>
<surname>Bischoff</surname>
<affiliation>
<address>&Eric.Bischoff.mail;</address>
</affiliation></author>

<author>
<firstname>Paul</firstname>
<othername>E.</othername>
<surname>Ahlquist</surname>
<lineage>Jr.</lineage>
<affiliation>
<address>&Paul.E.Ahlquist.Jr.mail;</address>
</affiliation>
</author>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<contrib>Reviewer</contrib>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<date>2006-05-05</date>
<releaseinfo>0.05.01</releaseinfo>

<copyright>
<year>1999</year><year>2000</year><year>2002</year><year>2006</year>
<holder>Éric Bischoff</holder>
</copyright>

<copyright>
<year>2001</year>
<holder>&Paul.E.Ahlquist.Jr;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<abstract>
<para>
&ktuberling; is a game intended for small children.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KTuberling</keyword>
<keyword>game</keyword>
<keyword>children</keyword>
<keyword>tuberling</keyword>
<keyword>potato</keyword>
<keyword>penguin</keyword>
<keyword>aquarium</keyword>
</keywordset>
</bookinfo>

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

<para>
<inlinemediaobject><imageobject>
<imagedata fileref="ktuberling.png" format="PNG"/></imageobject>
</inlinemediaobject>
&ktuberling; is a game intended for small children. Of course, it may be
suitable for adults who have remained young at heart.
</para>

<para>
It is a <quote>potato editor</quote>. That means that you can drag and drop
eyes, mouths, mustache, and other parts of face and goodies onto a potato-like
guy. Similarly, you have a penguin and an aquarium on which you can drop other stuff.
</para>

<para>
There is no winner for the game. The only purpose is to make the funniest faces
you can.
</para>

<para>
There is a museum (like a <quote>Madame Tusseau</quote> gallery) where
you can find many funny examples of decorated potatoes, penguins and
aquariums. Of course, you can send your own creations to the programmer,
<ulink url="mailto:ebischoff@nerim.net">Éric Bischoff</ulink>, who will
include them in the museum if he gets some spare time.
</para>

<para>
&ktuberling; can also <quote>speak</quote>. It will spell out the name of
the objects you drag and drop. It will <quote>speak</quote> in a language
that you can choose. You can even use it to learn a bit of vocabulary
in foreign languages. Currently, &ktuberling; can <quote>speak</quote>
Danish, German, English, Spanish, French, Italian, Dutch, Portuguese, Romanian,
Serbian, Slovak, Slovenian and Swedish.
</para>
</chapter>

<chapter id="onscreen-fundamentals">
<title>On Screen Fundamentals</title>

<sect1 id="mouse-operation">
<title>Mouse Operation</title>

<para>
There are two areas in the main window:
</para>

<itemizedlist>
<listitem><para><quote>Playground</quote> area, on the left side.
</para></listitem>
<listitem><para>
<quote>Objects</quote> area, on the right side, where you select objects to
place on your playground.
</para></listitem>
</itemizedlist>

<screenshot>
<screeninfo>Main Window of &ktuberling;</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="gameboard.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="gameboard.eps"/>
</imageobject>
<textobject><phrase>Main Window</phrase></textobject>
</mediaobject>
</screenshot>

<sect2 id="place-object">
<title>Placing an Object</title>

<para>
To drag an object, move the mouse pointer to the <quote>objects</quote>
area on the right. Click on the object you want to drag, but do not release
the mouse button until you have moved the mouse pointer to the location in
the <quote>playground</quote> area where you want to drop the object.
</para>
</sect2>

<sect2 id="move-object">
<title>Moving an Object</title>
<para>
Once dropped in the <quote>playground</quote> area, an object can be moved.
Just click on the object to select it for further drag and drop. When you
click on it, it goes on top of other objects that were partially hiding it.
This trick is useful for getting the glasses and eyes placed correctly.
</para>
</sect2>

<sect2 id="remove-object">
<title>Removing an Object</title>
<para>
To remove an object that has been dropped in the <quote>playground</quote>
area, drag it back from the <quote>playground</quote> area to the
<quote>objects</quote> area.
</para>
</sect2>
</sect1>

<sect1 id="the-tool-bar">
<title>The Tool Bar</title>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="toolbar.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="toolbar.eps"/>
</imageobject>
<textobject><phrase>Toolbar</phrase></textobject>
</mediaobject>

<para>
The toolbar provides buttons for the commonly used functions.
</para>

<table>
<title>Toolbar Buttons</title>
<tgroup cols="4">

<thead>
<row>
<entry>Button</entry>
<entry>Name</entry>
<entry>Menu Equivalent</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>
  <inlinemediaobject>
  <imageobject>
  <imagedata format="PNG" fileref="button-new.png"/>
  </imageobject>
  <imageobject>
  <imagedata format="EPS" fileref="button.new.eps"/>
  </imageobject>
	<textobject><phrase>New Game Button</phrase></textobject>
  </inlinemediaobject>
  </entry>
<entry>
  <guiicon>New</guiicon></entry>
<entry>
  <link linkend="game-new"><menuchoice>
  <guimenu>Game</guimenu> <guimenuitem>New</guimenuitem></menuchoice>
  </link>
  </entry>
<entry>
Resets the <quote>playground</quote> area. This cleans all parts off the
playground so a new decoration may be created.
</entry>
</row>


<row>
<entry>
  <inlinemediaobject>
  <imageobject>
  <imagedata format="PNG" fileref="button-open.png"/>
  </imageobject>
  <imageobject>
  <imagedata format="EPS" fileref="button.open.eps"/>
  </imageobject>
	<textobject><phrase>Load Button</phrase></textobject>
  </inlinemediaobject>
  </entry>
<entry><guiicon>Load</guiicon></entry>
<entry>
  <link linkend="game-load"><menuchoice>
  <guimenu>Game</guimenu> <guimenuitem>Load...</guimenuitem></menuchoice>
  </link>
  </entry>
<entry>
Opens an existing tuberling file from the museum or from other folders.
</entry>
</row>

<row>
<entry>
  <inlinemediaobject>
  <imageobject>
  <imagedata format="PNG" fileref="button-save.png"/>
  </imageobject>
  <imageobject>
  <imagedata format="EPS" fileref="button.save.eps"/>
  </imageobject>
  <textobject><phrase>Save Button</phrase></textobject>
  </inlinemediaobject>
</entry>
<entry><guiicon>Save</guiicon></entry>
<entry>
  <link linkend="game-save"><menuchoice>
  <guimenu>Game</guimenu> <guimenuitem>Save</guimenuitem></menuchoice>
  </link>
  </entry>
<entry>
Saves your creation to your home folder, or to some other folder like
the museum if you wish. The tuberling is saved to a small file where only the
position of objects are saved.
</entry>
</row>


<row>
<entry>
  <inlinemediaobject>
  <imageobject>
  <imagedata format="PNG" fileref="button-print.png"/>
  </imageobject>
  <imageobject>
  <imagedata format="EPS" fileref="button.print.eps"/>
  </imageobject>
  <textobject><phrase>Print Button</phrase></textobject>
</inlinemediaobject>
</entry>
<entry>
<guiicon>Print</guiicon>
</entry>
<entry>
  <link linkend="game-print"><menuchoice>
  <guimenu>Game</guimenu> <guimenuitem>Print</guimenuitem></menuchoice>
  </link>
  </entry>
<entry>
Prints your picture (&PostScript; format).
</entry>
</row>

<row>
<entry>
  <inlinemediaobject>
  <imageobject>
  <imagedata format="PNG" fileref="button-undo.png"/>
  </imageobject>
  <imageobject>
  <imagedata format="EPS" fileref="button.undo.eps"/>
  </imageobject>
  <textobject><phrase>Undo Button</phrase></textobject>
  </inlinemediaobject>
  </entry>
<entry>
  <guiicon>Undo</guiicon>
  </entry>
<entry>
  <link linkend="edit-undo"><menuchoice>
  <guimenu>Edit</guimenu> <guimenuitem>Undo</guimenuitem></menuchoice>
  </link>
  </entry>
<entry>Undoes last operation.</entry>
</row>

<row>
<entry>
  <inlinemediaobject>
  <imageobject>
  <imagedata format="PNG" fileref="button-redo.png"/>
  </imageobject>
  <imageobject>
  <imagedata format="EPS" fileref="button.redo.eps"/>
  </imageobject>
  <textobject><phrase>Redo Button</phrase></textobject>
  </inlinemediaobject>
  </entry>
<entry>
<guiicon>Redo</guiicon>
</entry>
<entry>
  <link linkend="edit-redo"><menuchoice>
  <guimenu>Edit</guimenu> <guimenuitem>Redo</guimenuitem></menuchoice>
  </link>
  </entry>
<entry>
Re-does last operation.</entry>
</row>

<!--  Currently there is no HELP button on the toolbar
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata format="PNG" fileref="button-help.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="button.help.eps"/>
</imageobject>
<textobject><phrase>Help Button</phrase></textobject>
</inlinemediaobject>
</entry>
<entry>
Help
</entry>
<entry>Displays this handbook.</entry>
</row>
-->

</tbody>
</tgroup>
</table>
</sect1>

<sect1 id="the-menu-items">
<title>The Menu Items</title>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-raw.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="menu.raw.eps"/>
</imageobject>
<textobject><phrase>Menu Bar</phrase></textobject>
</mediaobject>

<sect2>
<title>The <guimenu>Game</guimenu> Menu</title>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-game.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="menu.game.eps"/>
</imageobject>
<textobject><phrase><guimenu>File</guimenu> Menu</phrase></textobject>
</mediaobject>

<variablelist>

<varlistentry id="game-new">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
 </shortcut>
<guimenu>Game</guimenu>
 <guimenuitem>New</guimenuitem>
 </menuchoice></term>
<listitem><para><action>Clears</action> the <quote>playground</quote>
area </para></listitem>
</varlistentry>

<varlistentry id="game-load">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
 </shortcut>
<guimenu>Game</guimenu>
 <guimenuitem>Load...</guimenuitem>
 </menuchoice></term>
 <listitem><para><action>Opens an existing tuberling file</action> from
the museum or from somewhere else if you wish.</para></listitem>
</varlistentry>

<varlistentry id="game-save">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>Save</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves</action> your creation. The tuberling is
saved to a small file where only the position of objects are saved.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Game</guimenu>
<guimenuitem>Save as Picture...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a graphics file</action>
containing a picture of your tuberling.  Available file formats
are XPM, JPEG, PNG and BMP.
</para></listitem>
</varlistentry>

<varlistentry id="game-print">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>Print...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Print</action> your tuberling picture using
 &PostScript; format.
</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> &ktuberling;.
</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Edit</guimenu> Menu</title>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-edit.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="menu.edit.eps"/>
</imageobject>
<textobject><phrase>Edit Menu</phrase></textobject>
</mediaobject>

<variablelist>

<varlistentry id="edit-undo">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Undo</guimenuitem>
</menuchoice></term>
<listitem><para><action>Undo</action> the last
<quote>object</quote> placement.
</para></listitem>
</varlistentry>

<varlistentry id="edit-redo">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Shift</keycap>
<keycap>Z</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Redo</guimenuitem>
</menuchoice></term>
<listitem><para><action>Re-does</action> the last <quote>object</quote>
placement.  This menu option is active only if you have previously used
<guilabel>Undo</guilabel>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Copy</guimenuitem>
</menuchoice></term>
<listitem><para><action>Copy</action> the <quote>playground</quote> area to the
clipboard.</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Playground</guimenu> Menu</title>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-playground.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="menu.playground.eps"/>
</imageobject>
<textobject><phrase><guimenu>Playground</guimenu> Menu</phrase></textobject>
</mediaobject>

<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Playground</guimenu>
<guimenuitem>Potato Guy</guimenuitem>
</menuchoice></term>
<listitem><para><action>Switches to potato playground</action>.
&ktuberling; remembers the last chosen playground the next
time it starts up.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Playground</guimenu>
<guimenuitem>Penguin</guimenuitem>
</menuchoice></term>
<listitem><para><action>Switches to penguin playground</action>.
&ktuberling; remembers the last chosen playground the next
time it starts up.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Playground</guimenu>
<guimenuitem>Aquarium</guimenuitem>
</menuchoice></term>
<listitem><para><action>Switches to aquarium playground</action>.
&ktuberling; remembers the last chosen playground the next
time it starts up.</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Speech</guimenu> Menu</title>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-speech.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="menu.speech.eps"/>
</imageobject>
<textobject><phrase><guimenu>Speech</guimenu> Menu</phrase></textobject>
</mediaobject>

<para>
Please note that you need to have tdemultimedia installed
and <command>&artsd;</command> running to be able to hear sounds.
</para>

<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Speech</guimenu>
<guimenuitem>No Sound</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles sound off</action>. &ktuberling;
remembers of this option the next time it starts up.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Speech</guimenu>
<guimenuitem>Danish</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles sound on and speaks Danish</action>.
If Danish sounds are not installed then this option is grayed out. &ktuberling;
remembers of this option the next time it starts up.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Speech</guimenu>
<guimenuitem>German</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles sound on and speaks German</action>.
If German sounds are not installed then this option is grayed out. &ktuberling;
remembers of this option the next time it starts up.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Speech</guimenu>
<guimenuitem>English</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles sound on and speaks English</action>.
If English sounds are not installed then this option is grayed out. &ktuberling;
remembers of this option the next time it starts up.</para></listitem>
</varlistentry>

<varlistentry>
<term>etc...</term>
<listitem><para>Same for the other languages.</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-settings.png"/>
</imageobject>
<textobject><phrase>Settings Menu</phrase></textobject>
</mediaobject>

<variablelist>

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

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para>Opens a standard &kde; shortcut configuration dialog, where you can change the 
keyboard shortcuts used by &ktuberling;.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Toolbars...</guimenuitem>
</menuchoice></term>
<listitem><para>Display the standard &kde; toolbar configuration dialog.</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Help</guimenu> Menu</title>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="menu-help.png"/>
</imageobject>
<imageobject>
<imagedata format="EPS" fileref="menu.help.eps"/>
</imageobject>
<textobject><phrase>Help Menu</phrase></textobject>
</mediaobject>

&help.menu.documentation;

</sect2>
</sect1>
</chapter>

&technical.reference;

<chapter id="credits_license">
<title>Credits and License</title>

<para>&ktuberling;</para>

<itemizedlist>
<listitem>
<para>John Calhoun - Original idea, original pictures and English
sounds</para>
</listitem>

<listitem>
<para>Éric Bischoff &Eric.Bischoff.mail; - &kde;
Programming</para>
</listitem>

<listitem>
<para>Fran&ccedil;ois-Xavier Duranceau <email>duranceau@free.fr</email> - Tests,
advice and help</para>
</listitem>

<listitem>
<para>Agnieszka Czajkowska <email>agnieszka@imagegalaxy.de</email> - Penguin graphics</para>
</listitem>

<listitem>
<para>Bas Willems <email>next@euronet.nl</email> - Graphics reworks and aquarium theme</para>
</listitem>

<listitem>
<para>Roger Larsson <email>roger.larsson@norran.net</email> - Sounds tuning</para>
</listitem>

<listitem>
<para>Dolores Almansa <email>dolores.almansa@corazondemaria.org</email> - Educative graphics for COR-EDUX initiative</para>
</listitem>

<listitem>
<para>Peter Silva <email>peter.silva@videotron.ca</email> - Proofreading of
the documentation</para>
</listitem>

<listitem>
<para>Paul Ahlquist &Paul.E.Ahlquist.Jr.mail; - Bettering of
documentation</para>
</listitem>
</itemizedlist> 

<para>This game is dedicated to my little daughter Sunniva Bischoff</para>

<para>Thanks to Apple Computer and to the &LinuxPPC; project for having made
ports of &Linux; to the &Mac;.  &ktuberling; would never have existed without
that!</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>


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

<sect1 id="how-to-obtain-ktuberling">
<title>How to obtain <application>ktuberling</application></title>

&install.intro.documentation;

</sect1>

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

<para>
In order to successfully compile &ktuberling;, you need &kde; 3.5.
All required libraries as well as &ktuberling; itself can be found on
&kde-ftp;.</para>

<para>
To be able to hear the sounds, you need to have tdemultimedia installed.
</para>
</sect1>

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

&install.compile.documentation;

</sect1>
</appendix>

</book>