Git commit 8b2354b52bbad9a48c481e320097509c808c150e by Antoni Bella Pérez. Committed on 14/10/2021 at 14:53. Pushed by bellaperez into branch 'master'.
Documentation updates * Update date and version numbers * Remove deprecated entities: ksirk (from kdoctools), kappname and package * Remove final whitespaces * Re-indent (more readable) * Suitable tags and more entities * Renew to Breeze gui icons A +- -- doc/ksirk/application-exit.png A +- -- doc/ksirk/document-new.png M +405 -664 doc/ksirk/index.docbook D +- -- doc/ksirk/newGame.png D +- -- doc/ksirk/quit.png A +- -- doc/ksirkskineditor/document-open.png A +- -- doc/ksirkskineditor/document-save.png M +521 -383 doc/ksirkskineditor/index.docbook D +- -- doc/ksirkskineditor/load.png D +- -- doc/ksirkskineditor/save.png https://invent.kde.org/games/ksirk/commit/8b2354b52bbad9a48c481e320097509c808c150e diff --git a/doc/ksirk/application-exit.png b/doc/ksirk/application-exit.png new file mode 100644 index 0000000..bbb54cb Binary files /dev/null and b/doc/ksirk/application-exit.png differ diff --git a/doc/ksirk/document-new.png b/doc/ksirk/document-new.png new file mode 100644 index 0000000..d377fbb Binary files /dev/null and b/doc/ksirk/document-new.png differ diff --git a/doc/ksirk/index.docbook b/doc/ksirk/index.docbook index a5b72bb..db60529 100644 --- a/doc/ksirk/index.docbook +++ b/doc/ksirk/index.docbook @@ -1,8 +1,5 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ - <!ENTITY ksirk '<application>KsirK</application>'> - <!ENTITY kappname "&ksirk;"><!-- replace ksirk here --> - <!ENTITY package "kdegames"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> ]> @@ -13,35 +10,26 @@ <title>The &ksirk; Handbook</title> <authorgroup> -<author> -<firstname>Gael</firstname> -<othername>Kleag</othername> -<surname>de Chalendar</surname> -<affiliation> -<address><email>[email protected]</email></address> -</affiliation> -</author> -<author> -<firstname>Nemanja</firstname> -<othername></othername> -<surname>Hirsl</surname> -<affiliation> -<address><email>[email protected]</email></address> -</affiliation> -</author> -<!-- TRANS:ROLES_OF_TRANSLATORS --> + <author> + <firstname>Gaël</firstname> <othername>Kleag</othername> <surname>de Chalendar</surname> + <affiliation><address><email>[email protected]</email></address></affiliation> + </author> + <author> + <firstname>Nemanja</firstname> <othername></othername> <surname>Hirsl</surname> + <affiliation><address><email>[email protected]</email></address></affiliation> + </author> + <!-- Translators: put here the copyright notice of the translation --> + <!-- TRANS:ROLES_OF_TRANSLATORS --> </authorgroup> - <copyright> -<year>2002-2012</year> -<holder>Gael de Chalendar</holder> + <year>2002-2012</year> + <holder>Gaël de Chalendar</holder> </copyright> <copyright> -<year>2013</year> -<holder>Nemanja Hirsl</holder> + <year>2013</year> + <holder>Nemanja Hirsl</holder> </copyright> -<!-- Translators: put here the copyright notice of the translation --> <!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook and in the FDL itself on how to use it. --> <legalnotice>&FDLNotice;</legalnotice> @@ -52,48 +40,28 @@ need them for translation coordination ! Please respect the format of the date (DD/MM/YYYY) and of the version (V.MM.LL), it could be used by automation scripts. Do NOT change these in the translation. --> - -<date>2013-02-17</date> -<releaseinfo>4.10.0</releaseinfo> +<date>2021-10-14</date> +<releaseinfo>KDE Gear 21.08</releaseinfo> <!-- Abstract about this handbook --> - <abstract> -<para> -&ksirk; is a computerized version of a well known strategy game. Commercial -and other Free Software versions exist but I (Gaël de Chalendar) created this game -initially as a C++ learning exercise and so, I developed it up to this point (see README for details). -</para> -<para> -In the current version, &ksirk; is a multi-player network-enabled game with an AI. -(see TODO for details) -</para> -<para> -This documentation gives the major information you need to start playing. -Please read the tooltips and the status bar messages to complete your information. A chapter explains how to create new skins for &ksirk; -</para> -<para> -The goal of the game is simply to conquer the World... It is done by attacking your neighbors -with your armies. Peaceful, isn't it :-) -</para> + <para>&ksirk; is a computerized version of a well known strategy game.</para> </abstract> <!-- This is a set of Keywords for indexing by search engines. Please at least include KDE, the KDE package it is in, the name of your application, and a few relevant keywords. --> - <keywordset> -<keyword>KDE</keyword> -<keyword>kdegames</keyword> -<keyword>game</keyword> -<keyword>strategy</keyword> -<keyword>Risk</keyword> -<keyword>free</keyword> -<keyword>GPL</keyword> -<keyword>Network</keyword> -<keyword>AI</keyword> + <keyword>KDE</keyword> + <keyword>AI</keyword> + <keyword>free</keyword> + <keyword>game</keyword> + <keyword>GPL</keyword> + <keyword>KsirK</keyword> + <keyword>network</keyword> + <keyword>risk</keyword> + <keyword>strategy</keyword> </keywordset> - </bookinfo> <!-- The contents of the documentation begin here. Label @@ -112,507 +80,340 @@ consistent documentation style across all KDE apps. --> application that explains what it does and where to report problems. Basically a long version of the abstract. Don't include a revision history. (see installation appendix comment) --> -<para> -&ksirk; is a computerized version of a well known strategy game. Commercial +<para>&ksirk; is a computerized version of a well known strategy game. Commercial and other Free Software versions exist but I (Gaël de Chalendar) created this game -initially as a C++ learning exercise and so, I developed it up to this point (see README for details). -</para> -<para> +initially as a C++ learning exercise and so, I developed it up to this point (see <filename>README</filename> for details).</para> + <screenshot> <screeninfo>Here's a screenshot of &ksirk;</screeninfo> <mediaobject> - <imageobject> - <imagedata fileref="firing-screenshot.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Screenshot</phrase> - </textobject> + <imageobject><imagedata fileref="firing-screenshot.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot</phrase></textobject> </mediaobject> </screenshot> -</para> -<para> -In the current version, &ksirk; is a multi-player network-enabled game with an AI. -(see TODO for details) -</para> -<para> -This documentation gives only the major information you need to start playing. -Please read the tooltips and the status bar messages to complete your information. -</para> -<para> -The goal of the game is simply to conquer the World... It is done by attacking your neighbors -with your armies. Peaceful, isn't it ? :-) -</para> + +<para>In the current version, &ksirk; is a multi-player network-enabled game with an AI. (see <filename>TODO</filename> for details)</para> + +<para>This documentation gives only the major information you need to start playing. Please read the tooltips and the status bar messages to complete your information.</para> + +<para>The goal of the game is simply to conquer the World... It is done by attacking your neighbors with your armies. Peaceful, isn't it ? :-)</para> </chapter> <chapter id="using-kapp"> <title>Using &ksirk;</title> <!-- This chapter should tell the user how to use your app. You should use as -many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document +many sections (Chapter, Sect1, Sect3, &etc;) as is necessary to fully document your application. --> - - <sect1 id="playing-ksirk"> <title>Playing &ksirk;</title> -<para>Preliminary note : the map can be scrolled by three methods:</para> -<itemizedlist><listitem><para>You can put your -mouse near a border of the window and the map will scroll in that direction</para></listitem> -<listitem><para>You can use your mouse wheel: with no modifier, it will scroll vertically; when pressing the &Alt; -key, it will scroll horizontally</para></listitem> -<listitem><para>You can use the keyboard arrows</para></listitem></itemizedlist> -<sect2 id="mainmenu" > -<title>Starting a game</title> -<para> -When &ksirk; starts, you are presented with a main menu. -<screenshot> - <screeninfo>The main menu of &ksirk;</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="introscreen.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Main menu</phrase> - </textobject> - </mediaobject> -</screenshot> -<variablelist> -<varlistentry> -<term> - <menuchoice> - <guimenu>New Local Game</guimenu> - </menuchoice> -</term> -<listitem> - <para> - <action>Starts a new game</action> - </para> -</listitem> -</varlistentry> -<varlistentry> -<term> - <menuchoice> - <guimenu>Play &ksirk; over Jabber Network</guimenu> - </menuchoice> -</term> -<listitem> - <para> - <action>Play &ksirk; over <ulink url="http://en.wikipedia.org/wiki/Extensible_Messaging_and_Presence_Protocol";>Jabber</ulink>. You need to register Jabber account first.</action> - </para> -</listitem> -</varlistentry> -<varlistentry> -<term> - <menuchoice> - <guimenu>New Standard TCP/IP Network Game</guimenu> - </menuchoice> -</term> -<listitem> - <para> - <action>Start a new game using <ulink url="http://en.wikipedia.org/wiki/Internet_protocol_suite";>Internet protocol suite</ulink>.</action> - </para> -</listitem> -</varlistentry> -<varlistentry> -<term> - <menuchoice> - <guimenu>Join Standard TCP/IP Network Game</guimenu> - </menuchoice> -</term> -<listitem> - <para> - <action>Join to the created by other user game using <ulink url="http://en.wikipedia.org/wiki/Internet_protocol_suite";>Internet protocol suite</ulink>.</action> - </para> -</listitem> -</varlistentry> -<varlistentry> - <term> - <menuchoice> - <guimenu>Load</guimenu> - </menuchoice> - </term> - <listitem> - <para> - <action>Use this to load a previously saved game</action> - </para> - </listitem> -</varlistentry> -<varlistentry> - <term> - <menuchoice> - <guimenu>Quit</guimenu> - </menuchoice> - </term> - <listitem> - <para> - <action>Maybe you finally don't want to play?</action> - </para> - </listitem> -</varlistentry> -</variablelist> -</para> -<para> - If you hit <guibutton>New Local Game</guibutton> you will be presented with the <guilabel>New game properties</guilabel> dialog where you will be able to choose the number of players, the skin (or theme) to use, the game type (conquer the goal or have a specific goal) and finally if this game will be played with online players or if it is purely local. New skins can be downloaded using <guibutton>Download New Skins</guibutton> button. -<screenshot> - <screeninfo>The New Game dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="newgamedialog.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>The New Game dialog</phrase> - </textobject> - </mediaobject> -</screenshot> -</para> -<para> -To start a TCP/IP network game, choose the <guilabel>New Standard TCP/IP Network Game</guilabel> option on introduction screen. After clicking this button you will be able to choose the network parameters: number of local players and TCP port on which waiting for connections. -<screenshot> - <screeninfo>Network game parameters dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="numnetplayersdialog.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Network game parameters dialog</phrase> - </textobject> - </mediaobject> -</screenshot> -</para> -<para> -Then, network players will be able to connect by choosing <guilabel>Join Standard TCP/IP Network Game</guilabel> on the introduction screen and by indicating the IP or hostname of the host and the port number you just set. -<screenshot> - <screeninfo>Joining network game dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="joinnetgame.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Joining network game dialog</phrase> - </textobject> - </mediaobject> -</screenshot> -</para> -<para> - Each connection is indicated by a new row in the <guilabel>Players</guilabel> table below the map thumbnail. -<screenshot> - <screeninfo>New player row</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="justjoined.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>New player row</phrase> - </textobject> - </mediaobject> -</screenshot> +<para>Preliminary note: the map can be scrolled by three methods:</para> -</para> -<para> -Let's suppose you keep all the default settings and hit <guibutton>Next</guibutton>. You will then setup two players, one after one. For each one, you'll choose a name, a nationality and, if you want, setup a password such that nobody else than you can reuse this player when reloading this saved game. Lastly, you will here specify if this player is played by the computer or by a human being. -<screenshot> - <screeninfo>The Player Setup dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="playersetupdialog.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>The Player Setup dialog</phrase> - </textobject> - </mediaobject> -</screenshot> -</para> -<para> - Then, after clicking <guibutton>Start</guibutton>, if you choose to play with goal, the goal of each local player is displayed, preceded by a warning such that other players looking at the same computer can discreetly turn away while the goal is being viewed. -<screenshot> - <screeninfo>The Goal Display warning message</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="displaygoalwarningmessage.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>The Goal Display warning message</phrase> - </textobject> - </mediaobject> -</screenshot> -<screenshot> - <screeninfo>The Goal Display dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="displaygoalmessage.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>The Goal Display dialog</phrase> - </textobject> - </mediaobject> -</screenshot> -</para> -</sect2> + <itemizedlist> + <listitem><para>You can put your mouse near a border of the window and the map will scroll in that direction</para></listitem> + <listitem><para>You can use your mouse wheel: with no modifier, it will scroll vertically; when pressing the &Alt; key, it will scroll horizontally</para></listitem> + <listitem><para>You can use the keyboard arrows</para></listitem> + </itemizedlist> -<sect2 id="distribution" > -<title>Distribution</title> -<para> -At the beginning of the game, countries are distributed to all the players. Each country contains -one army (represented by an infantryman) at the start. Each player has some armies to -distribute to his countries at their turn (indicated by the presence of their name and their flag in -the status bar). Note that five armies are represented by a cavalryman and 10 by -a cannon. -</para> -<para> -To put an army on one of your countries, click on it with the left mouse button. To remove an -army, click with the right button. Note, as a general rule, that you will never be able to remove -more armies than the number you placed. -<screenshot> - <screeninfo>Placing armies</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="placingarmies.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Placing armies</phrase> - </textobject> - </mediaobject> -</screenshot> + <sect2 id="mainmenu" > + <title>Starting a game</title> -</para> -<para> -When a player has distributed all there armies, the next player is automatically selected to do the -same task. When all players have finished to distributing their armies, there is two possibilities -that can be selected by two buttons showed in the right panel: -<variablelist> -<varlistentry> -<term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="recycling.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Redistribution</phrase> - </textobject> - </inlinemediaobject> - <guibutton>Recycle</guibutton> -</term> -<listitem> - <para> - <action> - One player wants to change some of his choices. The first player can then remove an army he - just put in a country with the right mouse button and put it in another one with the left mouse - button. When he finishes, he gives control to next player with the <guibutton>Valid</guibutton> button. When all - players have finished their redistribution, the two buttons are displayed again. - </action> - </para> -</listitem> -</varlistentry> -<varlistentry> -<term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="recyclingFinished.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>End of redistribution</phrase> - </textobject> - </inlinemediaobject> - <guibutton>Done</guibutton> -</term> -<listitem><para><action>The redistribution is finished and the game can continue. -</action></para></listitem> -</varlistentry> -</variablelist> + <para>When &ksirk; starts, you are presented with a main menu.</para> -</para> -</sect2> + <screenshot> + <screeninfo>The main menu of &ksirk;</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="introscreen.png" format="PNG"/></imageobject> + <textobject><phrase>Main menu</phrase></textobject> + </mediaobject> + </screenshot> -<sect2 id="fight" > -<title>Fight</title> -<para> -After the redistribution, a turn starts. Each player plays at his turn. He has the choice to: -<variablelist> - <varlistentry> - <term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="joueurSuivant.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Next player</phrase> - </textobject> - </inlinemediaobject> + <variablelist> + <varlistentry> + <term><guibutton>New Local Game</guibutton></term> + <listitem><para><action>Starts a new game.</action></para></listitem> + </varlistentry> +<!-- + <varlistentry> + <term><guibutton>Play &ksirk; over Jabber Network</guibutton></term> + <listitem><para><action>Play &ksirk; over <ulink url="https://en.wikipedia.org/wiki/XMPP";>Jabber</ulink>. You need to register Jabber account first.</action></para></listitem> + </varlistentry> +--> + <varlistentry> + <term><guibutton>New Standard TCP/IP Network Game</guibutton></term> + <listitem><para><action>Start a new game using <ulink url="https://en.wikipedia.org/wiki/Internet_protocol_suite";>Internet protocol suite</ulink>.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term><guibutton>Join Standard TCP/IP Network Game</guibutton></term> + <listitem><para><action>Join to the created by other user game using <ulink url="https://en.wikipedia.org/wiki/Internet_protocol_suite";>Internet protocol suite</ulink>.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term><guibutton>Load...</guibutton></term> + <listitem><para><action>Use this to load a previously saved game.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term><guibutton>Quit</guibutton></term> + <listitem><para><action>Maybe you finally don't want to play?</action></para></listitem> + </varlistentry> + </variablelist> + + <para>If you hit <guibutton>New Local Game</guibutton> you will be presented with the <guilabel>New game properties</guilabel> dialog where you will be able to choose the number of players, the skin (or theme) to use, the game type (conquer the goal or have a specific goal) and finally if this game will be played with online players or if it is purely local. New skins can be downloaded using <guibutton>Download New Skins</guibutton> button.</para> + + <screenshot> + <screeninfo>The New Game dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="newgamedialog.png" format="PNG"/></imageobject> + <textobject><phrase>The New Game dialog</phrase></textobject> + </mediaobject> + </screenshot> + + <para>To start a TCP/IP network game, choose the <guilabel>New Standard TCP/IP Network Game</guilabel> option on introduction screen. After pess this button you will be able to choose the network parameters: number of local players and TCP port on which waiting for connections.</para> + + <screenshot> + <screeninfo>Network game parameters dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="numnetplayersdialog.png" format="PNG"/></imageobject> + <textobject><phrase>Network game parameters dialog</phrase></textobject> + </mediaobject> + </screenshot> + + <para>Then, network players will be able to connect by choosing <guilabel>Join Standard TCP/IP Network Game</guilabel> on the introduction screen and by indicating the IP or hostname of the host and the port number you just set.</para> + + <screenshot> + <screeninfo>Joining network game dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="joinnetgame.png" format="PNG"/></imageobject> + <textobject><phrase>Joining network game dialog</phrase></textobject> + </mediaobject> + </screenshot> + + <para>Each connection is indicated by a new row in the <guilabel>Players</guilabel> table below the map thumbnail.</para> + + <screenshot> + <screeninfo>New player row</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="justjoined.png" format="PNG"/></imageobject> + <textobject><phrase>New player row</phrase></textobject> + </mediaobject> + </screenshot> + + <para>Let's suppose you keep all the default settings and hit <guibutton>Next</guibutton>. You will then setup two players, one after one. For each one, you'll choose a name, a nationality and, if you want, setup a password such that nobody else than you can reuse this player when reloading this saved game. Lastly, you will here specify if this player is played by the computer or by a human being.</para> + + <screenshot> + <screeninfo>The Player Setup dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="playersetupdialog.png" format="PNG"/></imageobject> + <textobject><phrase>The Player Setup dialog</phrase></textobject> + </mediaobject> + </screenshot> + + <para>Then, after press <guibutton>Start</guibutton>, if you choose to play with goal, the goal of each local player is displayed, preceded by a warning such that other players looking at the same computer can discreetly turn away while the goal is being viewed.</para> + + <screenshot> + <screeninfo>The Goal Display warning message</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="displaygoalwarningmessage.png" format="PNG"/></imageobject> + <textobject><phrase>The Goal Display warning message</phrase></textobject> + </mediaobject> + </screenshot> + + <screenshot> + <screeninfo>The Goal Display dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="displaygoalmessage.png" format="PNG"/></imageobject> + <textobject><phrase>The Goal Display dialog</phrase></textobject> + </mediaobject> + </screenshot> + </sect2> + + <sect2 id="distribution" > + <title>Distribution</title> + + <para>At the beginning of the game, countries are distributed to all the players. Each country contains one army (represented by an infantryman) at the start. Each player has some armies to distribute to his countries at their turn (indicated by the presence of their name and their flag in the status bar). Note that five armies are represented by a cavalryman and 10 by a cannon.</para> + + <para>To put an army on one of your countries, click on it with the &LMB;. To remove an army, click with the &RMB;. Note, as a general rule, that you will never be able to remove more armies than the number you placed.</para> + + <screenshot> + <screeninfo>Placing armies</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="placingarmies.png" format="PNG"/></imageobject> + <textobject><phrase>Placing armies</phrase></textobject> + </mediaobject> + </screenshot> + + <para>When a player has distributed all there armies, the next player is automatically selected to do the same task. When all players have finished to distributing their armies, there is two possibilities that can be selected by two buttons showed in the right panel:</para> + + <variablelist> + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="recycling.png" format="PNG"/></imageobject> + <textobject><phrase>Redistribution</phrase></textobject> + </inlinemediaobject> + <guibutton>Recycle</guibutton> + </term> + <listitem><para><action>One player wants to change some of his choices. The first player can then remove an army he just put in a country with the &RMB; and put it in another one with the &LMB;. When he finishes, he gives control to next player with the <guibutton>Valid</guibutton> button. When all players have finished their redistribution, the two buttons are displayed again.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="recyclingFinished.png" format="PNG"/></imageobject> + <textobject><phrase>End of redistribution</phrase></textobject> + </inlinemediaobject> + <guibutton>Done</guibutton> + </term> + <listitem><para><action>The redistribution is finished and the game can continue.</action></para></listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="fight" > + <title>Fight</title> + + <para>After the redistribution, a turn starts. Each player plays at his turn. He has the choice to:</para> + + <variablelist> + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="joueurSuivant.png" format="PNG"/></imageobject> + <textobject><phrase>Next player</phrase></textobject> + </inlinemediaobject> <guibutton>Next Player</guibutton> - </term> - <listitem> - <para> - <action> - The turn of the current player finishes and it's the turn of the next one. - </action> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="attackOne.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Attack 1</phrase> - </textobject> - </inlinemediaobject> - <inlinemediaobject> - <imageobject> - <imagedata fileref="attackTwo.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Attack 2</phrase> - </textobject> - </inlinemediaobject> - <inlinemediaobject> - <imageobject> - <imagedata fileref="attackThree.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Attack 3</phrase> - </textobject> - </inlinemediaobject><guibutton>Attack with one, two or three armies</guibutton> - <inlinemediaobject> - <imageobject> - <imagedata fileref="autoattack.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Auto attack</phrase> - </textobject> - </inlinemediaobject> - <guibutton>Auto attack</guibutton> - </term> - <listitem> - <para> - To attack, drag with the mouse from the attacking country and drop to the attacked one. You will then be presented with a contextual menu showing the above entries. - <screenshot> - <screeninfo>Attack menu</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="attackmenu.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Attack menu</phrase> - </textobject> - </mediaobject> - </screenshot> - For a country X to attack a country Y with x armies, 2 conditions must be fulfilled:</para> - <itemizedlist><listitem><para> the two countries must be neighbors;</para></listitem> - <listitem><para>country X must have at least x+1 armies before the attack.</para></listitem></itemizedlist> - <para> - If the attack is valid, a dialog is displayed if necessary for the defender to choose if he wants to defend with one or two armies or let the computer decide. - </para> - <para> - When the defenders choice is done, the fight will occur and be completed. This will described below. - <screenshot> - <screeninfo>Defense dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="defensedialog.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Defense dialog</phrase> - </textobject> - </mediaobject> - </screenshot> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="moveArmies.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Move armies</phrase> - </textobject> - </inlinemediaobject> - <guibutton>Move Armies from one country to another</guibutton> - </term> - <listitem> - <para> - <action> - This is the last action of a player's turn. It gives the possibility to move some armies - from one of his country to another, neighboring the first one. To choose the two - countries, please drag and drop like you use during an attack. When both countries are selected, - a slider is displayed on which you can choose how many armies there will be on each country afterwards. - </action> - </para> - </listitem> - </varlistentry> -</variablelist> -</para> -</sect2> -<sect2 id="fight-solution" > + </term> + <listitem><para><action>The turn of the current player finishes and it's the turn of the next one.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="attackOne.png" format="PNG"/></imageobject> + <textobject><phrase>Attack 1</phrase></textobject> + </inlinemediaobject> + + <inlinemediaobject> + <imageobject><imagedata fileref="attackTwo.png" format="PNG"/></imageobject> + <textobject><phrase>Attack 2</phrase></textobject> + </inlinemediaobject> + + <inlinemediaobject> + <imageobject><imagedata fileref="attackThree.png" format="PNG"/></imageobject> + <textobject><phrase>Attack 3</phrase></textobject> + </inlinemediaobject> + <guibutton>Attack with one, two or three armies</guibutton> + + <inlinemediaobject> + <imageobject><imagedata fileref="autoattack.png" format="PNG"/></imageobject> + <textobject><phrase>Auto attack</phrase></textobject> + </inlinemediaobject> + <guibutton>Auto attack</guibutton> + </term> + + <listitem><para>To attack, drag with the mouse from the attacking country and drop to the attacked one. You will then be presented with a contextual menu showing the above entries.</para> + + <screenshot> + <screeninfo>Attack menu</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="attackmenu.png" format="PNG"/></imageobject> + <textobject><phrase>Attack menu</phrase></textobject> + </mediaobject> + </screenshot> + + <para>For a country X to attack a country Y with x armies, 2 conditions must be fulfilled:</para> + + <itemizedlist> + <listitem><para>the two countries must be neighbors;</para></listitem> + <listitem><para>country X must have at least x+1 armies before the attack.</para></listitem> + </itemizedlist> + + <para>If the attack is valid, a dialog is displayed if necessary for the defender to choose if he wants to defend with one or two armies or let the computer decide.</para> + + <para>When the defenders choice is done, the fight will occur and be completed. This will described below.</para> + + <screenshot> + <screeninfo>Defense dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="defensedialog.png" format="PNG"/></imageobject> + <textobject><phrase>Defense dialog</phrase></textobject> + </mediaobject> + </screenshot> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="moveArmies.png" format="PNG"/></imageobject> + <textobject><phrase>Move armies</phrase></textobject> + </inlinemediaobject> + <guibutton>Move Armies from one country to another</guibutton> + </term> + + <listitem><para><action>This is the last action of a player's turn. It gives the possibility to move some armies from one of his country to another, neighboring the first one. To choose the two countries, please drag and drop like you use during an attack. When both countries are selected, a slider is displayed on which you can choose how many armies there will be on each country afterwards.</action></para></listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="fight-solution" > <title>Solution of the fight</title> - <para> - For each army in the fight there is a corresponding die cast. The player who rolls a higher number on the dice, whether being from the attacker or defender, wins and the one to roll a smaller number on the dice loses armies according to the number of dice thrown. - <screenshot> - <screeninfo>Attack result displayed</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="shownumberofarmies.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Attack result displayed</phrase> - </textobject> - </mediaobject> - </screenshot> - </para> - <para> - If the number of armies in the defender country reaches 0, the ownership of this country - changes to the attacker: his flag is set up and one of his attacking armies is installed in his - new country. The "Move armies" slider is displayed as for the moves of the end of the turn. - <screenshot> - <screeninfo>Invasion slider</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="invasionslider.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Invasion slider</phrase> - </textobject> - </mediaobject> - </screenshot> - </para> -</sect2> -<sect2 id="end_of_turn" > + + <para>For each army in the fight there is a corresponding die cast. The player who rolls a higher number on the dice, whether being from the attacker or defender, wins and the one to roll a smaller number on the dice loses armies according to the number of dice thrown.</para> + + <screenshot> + <screeninfo>Attack result displayed</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="shownumberofarmies.png" format="PNG"/></imageobject> + <textobject><phrase>Attack result displayed</phrase></textobject> + </mediaobject> + </screenshot> + + <para>If the number of armies in the defender country reaches 0, the ownership of this country changes to the attacker: his flag is set up and one of his attacking armies is installed in his new country. The "Move armies" slider is displayed as for the moves of the end of the turn.</para> + + <screenshot> + <screeninfo>Invasion slider</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="invasionslider.png" format="PNG"/></imageobject> + <textobject><phrase>Invasion slider</phrase></textobject> + </mediaobject> + </screenshot> + </sect2> + + <sect2 id="end_of_turn" > <title>End of the turn</title> - <para> - To finish your current turn, if you don't want to move armies, you can hit the <guibutton>Next Player</guibutton> button in the toolbar. - </para> - <para> - When everybody has played, the turn is finished. Some armies are distributed to the - players, in function of the countries they own: 1 for each group of three countries, with a - minimum of 3. There is also a bonus for players that own a complete continent, different for - each one. The values of the bonuses for the default skin are: - <table> - <title>Bonus due to the continents</title> - <tgroup cols="2"> - <thead> - <row><entry>Continent</entry><entry>Bonus</entry></row> - </thead> - <tbody> - <row><entry>North America</entry><entry>5</entry></row> - <row><entry>South America</entry><entry>2</entry></row> - <row><entry>Europe</entry><entry>5</entry></row> - <row><entry>Africa</entry><entry>3</entry></row> - <row><entry>Asia</entry><entry>7</entry></row> - <row><entry>Pacific Area</entry><entry>2</entry></row> - </tbody> - </tgroup> - </table> - </para> - <para> - When a player has finished distributing his armies, he clicks the <guibutton>Valid</guibutton> button to - allow the next player to distribute his bonus armies. As for the initial distribution, when all player - have placed their armies, they can start a new redistribution cycle or start a new turn... - </para> -</sect2> + + <para>To finish your current turn, if you don't want to move armies, you can hit the <guibutton>Next Player</guibutton> button in the toolbar.</para> + + <para>When everybody has played, the turn is finished. Some armies are distributed to the players, in function of the countries they own: 1 for each group of three countries, with a minimum of 3. There is also a bonus for players that own a complete continent, different for each one. The values of the bonuses for the default skin are:</para> + + <table> + <title>Bonus due to the continents</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Continent</entry> + <entry>Bonus</entry> + </row> + </thead> + <tbody> + <row><entry>North America</entry><entry>5</entry></row> + <row><entry>South America</entry><entry>2</entry></row> + <row><entry>Europe</entry><entry>5</entry></row> + <row><entry>Africa</entry><entry>3</entry></row> + <row><entry>Asia</entry><entry>7</entry></row> + <row><entry>Pacific Area</entry><entry>2</entry></row> + </tbody> + </tgroup> + </table> + + <para>When a player has finished distributing his armies, he clicks the <guibutton>Valid</guibutton> button to allow the next player to distribute his bonus armies. As for the initial distribution, when all player have placed their armies, they can start a new redistribution cycle or start a new turn...</para> + </sect2> + <!-- Does not work for current TCP/IP games <sect2 id="sending-messages" > <title>Sending messages to other players</title> @@ -641,69 +442,52 @@ If you play a local game and want to communicate with the other players, well, l <sect1 id="kapp-mainwindow"> <title>The main &ksirk; window</title> -<sect2> -<title>The buttons</title> -<para> -<variablelist> -<varlistentry> -<term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="quit.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Quit Game</phrase> - </textobject> - </inlinemediaobject> - <guibutton>Quit</guibutton> -</term> -<listitem><para><action> -Causes the program to quit. -</action></para></listitem> -</varlistentry> -<varlistentry> -<term> - <inlinemediaobject> - <imageobject> - <imagedata fileref="newGame.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>New Game</phrase> - </textobject> - </inlinemediaobject> - <guibutton>New Game</guibutton> -</term> -<listitem><para><action>Starts a new game. It will cause the displaying of a dialog asking -the number of players. After that, each player will be asked its name with another dialog. -</action></para></listitem> -</varlistentry> -</variablelist> -</para> + <sect2> + <title>The buttons</title> + + <variablelist> + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="application-exit.png" format="PNG"/></imageobject> + <textobject><phrase>Quit Game</phrase></textobject> + </inlinemediaobject> + <guibutton>Quit</guibutton> + </term> + <listitem><para><action>Causes the program to quit.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term> + <inlinemediaobject> + <imageobject><imagedata fileref="document-new.png" format="PNG"/></imageobject> + <textobject><phrase>New Game</phrase></textobject> + </inlinemediaobject> + <guibutton>New Game</guibutton> + </term> + <listitem><para><action>Starts a new game. It will cause the displaying of a dialog asking the number of players. After that, each player will be asked its name with another dialog.</action></para></listitem> + </varlistentry> + </variablelist> </sect2> </sect1> </chapter> <chapter id="developers"> - <title>Developer's Guide to &ksirk;</title> - - <para> - Please refer to <ulink url="http://api.kde.org/";>http://api.kde.org/</ulink> for the documentation of the API. It was quite complete but is currently a little bit outdated. There are no comments in the <filename>.cpp</filename> implementation files. - </para> - <para> - Note that I originally developed this game under &Windows; with Borland C++ and WinG. I ported - it to &Java; before converting back to C++ and &kde;. At the beginning I used French or a mix of - French and English to name the identifiers (classnames, methods, members, &etc;). I also used French for the comments. When I decided to distribute this game, I decided to convert all to english... but I am clearly not a native English speaker: please suggest or make and submit corrections, to the code comments or to this documentation - </para> - +<title>Developer's Guide to &ksirk;</title> + +<para>Please refer to <ulink url="https://api.kde.org/";>https://api.kde.org/</ulink> for the documentation of the API. It was quite complete but is currently a little bit outdated. There are no comments in the <literal role="extension">.cpp</literal> implementation files.</para> + +<para>Note that I originally developed this game under &Windows; with Borland C++ and WinG. I ported it to &Java; before converting back to C++ and &kde;. At the beginning I used French or a mix of French and English to name the identifiers (classnames, methods, members, &etc;). I also used French for the comments. When I decided to distribute this game, I decided to convert all to english... but I am clearly not a native English speaker: please suggest or make and submit corrections, to the code comments or to this documentation.</para> + </chapter> <chapter id="skins"> - <title>Creating new skins</title> - <para> - &ksirk; comes with a skin editor, named ksirkskineditor(!), that allows to edit all skin data, as soon as graphics (map, sprites, &etc;) are available in a SVG file. Please see the ksirkskineditor manual for further details. - </para> +<title>Creating new skins</title> + +<para>&ksirk; comes with a skin editor, named ksirkskineditor(!), that allows to edit all skin data, as soon as graphics (map, sprites, &etc;) are available in a &SVG; file. Please see the ksirkskineditor manual for further details.</para> + </chapter> <chapter id="faq"> @@ -716,7 +500,7 @@ the number of players. After that, each player will be asked its name with anoth <qandaset id="faqlist"> <qandaentry> <question> -<para>What will be the first question concerning &kappname;?</para> +<para>What will be the first question concerning &ksirk;?</para> </question> <answer> </answer> @@ -734,25 +518,19 @@ distribution. --> <title>Credits and License</title> -<para> -&ksirk; -</para> -<para> -Program copyright 2002-2012 Gael de Chalendar <email>[email protected]</email> -</para> -<para> -Program copyright 2013 Nemanja Hirsl <email>[email protected]</email> -</para> -<para> -Contributors: +<para>&ksirk;</para> + +<para>Program copyright 2002-2012 Gaël de Chalendar <email>[email protected]</email></para> + +<para>Program copyright 2013 Nemanja Hirsl <email>[email protected]</email></para> + +<para>Contributors: Robin Doer, -Albert Astals Cid, +&Albert.Astals.Cid;, Michal Golunski (Polish translation). </para> -<para> -Documentation copyright 2002-2008 Gael de Chalendar <email>[email protected]</email> -</para> +<para>Documentation copyright 2002-2008 Gaël de Chalendar <email>[email protected]</email></para> <!-- TRANS:CREDIT_FOR_TRANSLATORS --> @@ -775,55 +553,31 @@ Documentation copyright 2002-2008 Gael de Chalendar <email>[email protected]</email> <sect1 id="configuration"> <title>Configuration</title> -<para> - The settings menu entry opens a dialog that allows you to : - <screenshot> - <screeninfo>Preferences dialog</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="preferences.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Preferences dialog</phrase> - </textobject> - </mediaobject> - </screenshot> -</para> - <itemizedlist> - <listitem> - <para> - enable or disable the sounds ; - </para> - </listitem> - <listitem> - <para> - set the speed of the sprites (from slow to immediate) ; - </para> - </listitem> - <listitem> - <para> - enable or disable the contextual helps displayed in popups ; - </para> - </listitem> - <listitem> - <para> - show or hide the number of armies on each country. The following snapshot shows the map when the number of armies are displayed. - <screenshot> - <screeninfo>Display of the number of armies</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="shownumberofarmies.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Display of the number of armies</phrase> - </textobject> - </mediaobject> - </screenshot> - - </para> - </listitem> - </itemizedlist> +<para>The <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &ksirk;...</guimenuitem></menuchoice> menu item opens a dialog that allows you to:</para> + +<screenshot> + <screeninfo>Preferences dialog</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="preferences.png" format="PNG"/></imageobject> + <textobject><phrase>Preferences dialog</phrase></textobject> + </mediaobject> +</screenshot> +<itemizedlist> + <listitem><para>enable or disable the sounds ;</para></listitem> + <listitem><para>set the speed of the sprites (from slow to immediate) ;</para></listitem> + <listitem><para>enable or disable the contextual helps displayed in popups ;</para></listitem> + <listitem><para>show or hide the number of armies on each country. The following snapshot shows the map when the number of armies are displayed.</para> + + <screenshot> + <screeninfo>Display of the number of armies</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="shownumberofarmies.png" format="PNG"/></imageobject> + <textobject><phrase>Display of the number of armies</phrase></textobject> + </mediaobject> + </screenshot> + </listitem> +</itemizedlist> </sect1> </appendix> @@ -839,16 +593,3 @@ sgml-indent-step:0 sgml-indent-data:nil End: --> - - - - - - - - - - - - - diff --git a/doc/ksirk/newGame.png b/doc/ksirk/newGame.png deleted file mode 100644 index 92642a9..0000000 Binary files a/doc/ksirk/newGame.png and /dev/null differ diff --git a/doc/ksirk/quit.png b/doc/ksirk/quit.png deleted file mode 100644 index a9d2a72..0000000 Binary files a/doc/ksirk/quit.png and /dev/null differ diff --git a/doc/ksirkskineditor/document-open.png b/doc/ksirkskineditor/document-open.png new file mode 100644 index 0000000..0dc47ce Binary files /dev/null and b/doc/ksirkskineditor/document-open.png differ diff --git a/doc/ksirkskineditor/document-save.png b/doc/ksirkskineditor/document-save.png new file mode 100644 index 0000000..3e2293d Binary files /dev/null and b/doc/ksirkskineditor/document-save.png differ diff --git a/doc/ksirkskineditor/index.docbook b/doc/ksirkskineditor/index.docbook index b9a520f..d8a7df0 100644 --- a/doc/ksirkskineditor/index.docbook +++ b/doc/ksirkskineditor/index.docbook @@ -1,9 +1,6 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ - <!ENTITY ksirk '<application>KsirK</application>'> <!ENTITY ksirkskineditor '<application>KsirK Skin Editor</application>'> - <!ENTITY kappname "&ksirkskineditor;"> - <!ENTITY package "kdegames"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> ]> @@ -11,26 +8,21 @@ <book id="ksirkskineditor" lang="&language;"> <bookinfo> -<title>The &kappname; Handbook</title> +<title>The &ksirkskineditor; Handbook</title> <authorgroup> -<author> -<firstname>Gael</firstname> -<othername>Kleag</othername> -<surname>de Chalendar</surname> -<affiliation> -<address><email>[email protected]</email></address> -</affiliation> -</author> -<!-- TRANS:ROLES_OF_TRANSLATORS --> + <author> + <firstname>Gaël</firstname> <othername>Kleag</othername> <surname>de Chalendar</surname> + <affiliation><address><email>[email protected]</email></address></affiliation> + </author> + <!-- Translators: put here the copyright notice of the translation --> + <!-- TRANS:ROLES_OF_TRANSLATORS --> </authorgroup> - <copyright> -<year>2009</year> -<holder>Gael de Chalendar</holder> + <year>2009</year> + <holder>Gaël de Chalendar</holder> </copyright> -<!-- Translators: put here the copyright notice of the translation --> <!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook and in the FDL itself on how to use it. --> <legalnotice>&FDLNotice;</legalnotice> @@ -43,7 +35,7 @@ Change date/releaseinfo only if Don't forget to include this last date. Please respect the format of the date (YYYY-MM-DD),it is used by scripts. --> -<date>2009-05-22</date> +<date>2021-10-14</date> <!--version information of Frameworks/Plasma/Applications this documentation is valid for. Example: @@ -53,14 +45,12 @@ Applications xx.yy for docbooks released as Applications xx.yy (Applications xx.yy) for docbooks with own version released as Applications $applicationname xx.yy for applications with independent release schedule (extragear/playground) --> -<releaseinfo>4.3</releaseinfo> +<releaseinfo>KDE Gear 21.08</releaseinfo> <!-- Abstract about this handbook --> <abstract> -<para> -&ksirk; is a computerized version of a well known strategy game. It is fully skinable. This manual explains how to create new skins from scratch, using a file browser, a SVG image editor and &kappname;. -</para> + <para>&ksirk; is a computerized version of a well known strategy game. It is fully skinable. This manual explains how to create new skins from scratch, using a file browser, a &SVG; image editor and &ksirkskineditor;.</para> </abstract> <!-- This is a set of Keywords for indexing by search engines. @@ -68,15 +58,14 @@ Please at least include KDE, the KDE package it is in, the name of your application, and a few relevant keywords. --> <keywordset> -<keyword>KDE</keyword> -<keyword>kdegames</keyword> -<keyword>game</keyword> -<keyword>strategy</keyword> -<keyword>Risk</keyword> -<keyword>free</keyword> -<keyword>GPL</keyword> -<keyword>skin</keyword> -<keyword>editor</keyword> + <keyword>KDE</keyword> + <keyword>editor</keyword> + <keyword>free</keyword> + <keyword>game</keyword> + <keyword>GPL</keyword> + <keyword>risk</keyword> + <keyword>skin</keyword> + <keyword>strategy</keyword> </keywordset> </bookinfo> @@ -97,405 +86,572 @@ consistent documentation style across all KDE apps. --> application that explains what it does and where to report problems. Basically a long version of the abstract. Don't include a revision history. (see installation appendix comment) --> -<para> -&ksirk; is a computerized version of a well known strategy game. It is fully skinable. This manual explains how to create new skins from scratch, using a file browser, a SVG image editor and &kappname;. -</para> -<para> +<para>&ksirk; is a computerized version of a well known strategy game. It is fully skinable. This manual explains how to create new skins from scratch, using a file browser, a &SVG; image editor and &ksirkskineditor;.</para> + <screenshot> - <screeninfo>Here's a screenshot of &kappname;</screeninfo> + <screeninfo>Here's a screenshot of &ksirkskineditor;</screeninfo> <mediaobject> - <imageobject> - <imagedata fileref="main-snapshot.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Screenshot</phrase> - </textobject> + <imageobject><imagedata fileref="main-snapshot.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot</phrase></textobject> </mediaobject> </screenshot> -</para> -<para> -There is three main steps to create a new skin: creating the folders hierarchy; creating the graphics, all pooled inside a SVG file; and then placing sprites and naming things using &kappname;. -</para> + +<para>There is three main steps to create a new skin: creating the folders hierarchy; creating the graphics, all pooled inside a &SVG; file; and then placing sprites and naming things using &ksirkskineditor;.</para> </chapter> <chapter id="using-kapp"> <title>Creating a &ksirk; skin</title> - <para> - &ksirk; is fully skinable. For who have graphic capabilities, creating a new skin is as simple as copying an existing one, editing or changing the graphics and updating the data in a .desktop configuration file, which is done using the &kappname;. A last step is to edit the file describing what to install. - </para> - <para>All examples (text and images) are taken from the default skin of &ksirk;</para> - - <sect1 id="sdf"> - <title>Structure of folders and files</title> - <para> - <itemizedlist> - <listitem> - <para>Data/ : Data used by the program to handle the images of the skin. - <itemizedlist> - <listitem><para>CMakeLists.txt : Describes what to install.</para></listitem> - <listitem><para>onu.desktop : Main file for the description of the skin. See its description below.</para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para>Images/ : The images of the skin (map, sprites, etc.) - <itemizedlist> - <listitem><para>CMakeLists.txt : Describes what to install.</para></listitem> - <listitem><para>pool.svg : the map and all the sprites used in this skin.</para></listitem> - <listitem><para>map-mask.png : the image allowing the program to find which country the mouse is over during the game (see below).</para></listitem> - <listitem><para>*.png : the other images here are buttons images.</para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem><para>CMakeLists.txt/ : Describes what to install.</para></listitem> - <listitem><para>Sounds/ : sound files for the skin.</para></listitem> - </itemizedlist> - </para> - <sect2 id="tdd"> - <title>The Data folder</title> - <para> - This folder contains only one file, world.desktop. This file is a description of the content of the skin. It is used to describe the organization of the world and how to display it. You don't have to fill it manualy as it will be handled by the &kappname;. But, for the sake of completeness, we will now describe its structure. - </para> - <para> - An onu group contains a number of country entries, a number of nationality entries and lastly a number of continent entries. Then various groups contain the description of the different sprites, the description of the different countries, continents, nationalities and goals. - </para> - <para> - The following sections describe the content of each group. - </para> - <sect3> - <title>The onu group</title> - <para> - <table> - <title>The onu group entries</title> - <tgroup cols="2"> - <thead><row><entry>Entry name</entry><entry>Signification</entry></row></thead> - <tbody> - <row><entry>width</entry><entry>The width of the skin's map</entry></row> - <row><entry>height</entry><entry>The height of the skin's map</entry></row> - <row><entry>skinpath</entry><entry>The path of the skin relative to the application data path (e.g. skins/default)</entry></row> - <row><entry>nb-countries</entry><entry>The number of countries (42 in the default skin). There should be the same number of country groups below</entry></row> - <row><entry>nb-nationalities</entry><entry>The number of nationalities (6 in the default skin). There should be the same number of nationality groups below</entry></row> - <row><entry>nb-continents</entry><entry>The number of continents (6 in the default skin). There should be the same number of continent groups below</entry></row> - <row><entry>pool</entry><entry>The path and name of the pool file relative to the skin path (e.g. Images/pool.svg)</entry></row> - <row><entry>map-mask</entry><entry>The path and name of the map mask file relative to the skin path (e.g. Images/map-mask.png)</entry></row> - <row><entry>format-version</entry><entry>The version of the skin file format (2.0)</entry></row> - <row><entry>name</entry><entry>The display name of the skin</entry></row> - <row><entry>desc</entry><entry>The long description of the skin</entry></row> - <row><entry>fighters-flag-y-diff</entry><entry>The height difference between flags and cannons sprites</entry></row> - <row><entry>width-between-flag-and-fighter</entry><entry>The number of pixels between the left most pixel of the flag and the right most pixel of the simple cannon (when not firing nor exploding)</entry></row> - </tbody> - </tgroup> - </table> - </para> - </sect3> - <sect3> - <title>The sprites description groups</title> - <para> - Each type of sprite (flag, infantry, cavalry, cannon, firing cannon and exploding cannon) is defined by a group. Only some sprites have a width entry. This entry is used for relative positioning during animations: the cannons, firing or exploding should not "move" around the country's flag during fight. - <table> - <title>Sprite description group entries</title> - <tgroup cols="2"> - <thead><row><entry>Entry</entry><entry>Signification</entry></row></thead> - <tbody> - <row><entry>width</entry><entry>The reference width of the flag sprite frames</entry></row> - <row><entry>height</entry><entry>The reference height of the flag sprite frames</entry></row> - <row><entry>frames</entry><entry>The number of frames of the sprite</entry></row> - <row><entry>versions</entry><entry>The number of versions of the flag sprites</entry></row> - </tbody> - </tgroup> - </table> - </para> - </sect3> - <sect3> - <title>The countries description groups</title> - <para> - Each country listed in the onu group, countries entry has its own group whose label is the country name. The table below lists the entries of these groups. - </para> - <para> - <table> - <title>Country entries</title> - <tgroup cols="2"> - <thead><row><entry>Entry name</entry><entry>Signification</entry></row></thead> - <tbody> - <row><entry>id</entry><entry>The integer unique identification number of the country, must start at zero (0)</entry></row> - <row><entry>name</entry><entry>The displayed name of the country</entry></row> - <row><entry><sprite>-point</entry><entry>Each type of sprite (flag, infantry, etc.) in the country is displayed at a certain position defined by this entry made of two integers separated by a comma</entry></row> - <row><entry>neighbours</entry><entry>The list of the ids of the neighbors of the current country</entry></row> - </tbody> - </tgroup> - </table> - </para> - </sect3> - <sect3> - <title>The nationalities description groups</title> - <para> - Each nationality listed in the onu group, nationalities entry has its own group whose label is the nationality name. The table below lists the entries of these groups. - </para> - <para> - <table> - <title>Nationality entries</title> - <tgroup cols="2"> - <thead><row><entry>Entry name</entry><entry>Signification</entry></row></thead> - <tbody> - <row><entry>name</entry><entry>The name of the nationality (e.g. Japan)</entry></row> - <row><entry>leader</entry><entry>The name that will be proposed to the player choosing this nationality</entry></row> - <row><entry>flag</entry><entry>The name of the country's flag sprite element in the onu SVG file</entry></row> - </tbody> - </tgroup> - </table> - </para> - </sect3> - <sect3> - <title>The continents description groups</title> - <para> - Each continent listed in the onu group, continents entry has its own group whose label is the continent name. The table below lists the entries of these groups. - </para> - <para> - <table> - <title>Continent entries</title> - <tgroup cols="2"> - <thead><row><entry>Entry name</entry><entry>Signification</entry></row></thead> - <tbody> - <row><entry>name</entry><entry>The name of the continent (e.g. Africa)</entry></row> - <row><entry>id</entry><entry>The integer unique identification number of the continent</entry></row> - <row><entry>bonus</entry><entry>The number of armies obtained at the end of the turn by the player owning all the countries of the continent</entry></row> - <row><entry>continent-countries</entry><entry>The list of the ids of the countries inside the current continent</entry></row> - </tbody> - </tgroup> - </table> - </para> - </sect3> - <sect3> - <title>The goals description groups</title> - <para> - Each goal listed in the onu group, goals entry has its own group whose label is the goal name. The table below lists the entries of these groups. - </para> - <para> - <table> - <title>Goal entries</title> - <tgroup cols="2"> - <thead><row><entry>Entry name</entry><entry>Signification</entry></row></thead> - <tbody> - <row><entry>type</entry><entry>The type of goal. Can be continents, countries or player</entry></row> - <row><entry>nbArmiesByCountry</entry><entry>set the minimal number of armies the player will have to put on each country</entry></row> - <row><entry>nbCountries</entry><entry>set the number of countries the player must possess</entry></row> - <row><entry>nbCountriesFallback</entry><entry>For a player goal type, if the target player is killed by another one, this sets the number of countries the player will have to conquer instead</entry></row> - <row><entry>desc</entry><entry>A full text description of the goal with appropriate placeholders (needs more doc here)</entry></row> - <row><entry>continents</entry><entry>The list of continents ids the player will have to conquer</entry></row> - </tbody> - </tgroup> - </table> - </para> - </sect3> - </sect2> - <sect2 id="tid"> - <title>The Images folder</title> - <para> - This folder contains the buttons specific to &ksirk; and the pool SVG file that contains the map and all sprites. - </para> - <sect3> - <title>The pool.svg file</title> - <para> - This SVG file contains the map and all the sprites of the game. Each element is named such that the game can select and render separately each of them. - </para> - <para> - In the default skin, the sprites are flags, infantry, cavalry and cannon. Infantry represents one army, five for cavalry and ten for cannons. Cannons are also used to display fighting armies. That's why there is three kinds of cannon sprites: normal static or moving cannon, firing one and exploding one. - </para> - <para> - Each sprite image is the concatenation of the various views of the object and for each view, its frames. Views are organized vertically and frames horizontally. Where to cut the image in individual frames is found by dividing the height of the image by the number of views and the width by the number of frames. These data are found in the onu.desktop file. - <mediaobject><imageobject><imagedata fileref="cannon.png" format="PNG"/></imageobject><caption><para>An example of a sprite image: cannon.png</para></caption></mediaobject> - </para> - <para> - For armies sprites, there is three different views, from top to bottom:</para> - <itemizedlist><listitem><para>looking right</para></listitem> - <listitem><para>looking left and</para></listitem><listitem> - <para>facer</para></listitem></itemizedlist> - <para> For flags, there is only one view. All sprites backgrounds should be set to transparent. - <mediaobject><imageobject><imagedata fileref="italy.png" format="PNG"/></imageobject><caption><para>An example of a flag sprite image: italy.png</para></caption></mediaobject> - </para> - <para> - <table> - <title>The elements of the pool</title> - <tgroup cols="3"> - <thead><row><entry>Element name</entry><entry>Sample Image</entry><entry>Signification</entry></row></thead> + +<para>&ksirk; is fully skinable. For who have graphic capabilities, creating a new skin is as simple as copying an existing one, editing or changing the graphics and updating the data in a <literal role="extension">.desktop</literal> configuration file, which is done using the &ksirkskineditor;. A last step is to edit the file describing what to install.</para> + +<para>All examples (text and images) are taken from the default skin of &ksirk;.</para> + +<sect1 id="sdf"> +<title>Structure of folders and files</title> + +<itemizedlist> + <listitem><para><filename class="directory">Data/</filename> : Data used by the program to handle the images of the skin.</para> + <itemizedlist> + <listitem><para><filename>CMakeLists.txt</filename> : Describes what to install.</para></listitem> + <listitem><para><filename>onu.desktop</filename> : Main file for the description of the skin. See its description below.</para></listitem> + </itemizedlist> + </listitem> + + <listitem><para><filename class="directory">Images/</filename> : The images of the skin (map, sprites, &etc;)</para> + <itemizedlist> + <listitem><para><filename>CMakeLists.txt</filename> : Describes what to install.</para></listitem> + <listitem><para><filename>pool.svg</filename> : The map and all the sprites used in this skin.</para></listitem> + <listitem><para><filename>map-mask.png</filename> : The image allowing the program to find which country the mouse is over during the game (see below).</para></listitem> + <listitem><para><literal role="extension">*.png</literal> : The other images here are buttons images.</para></listitem> + </itemizedlist> + </listitem> + + <listitem><para><filename>CMakeLists.txt</filename> : Describes what to install.</para></listitem> + <listitem><para><filename class="directory">Sounds/</filename> : Sound files for the skin.</para></listitem> +</itemizedlist> + + <sect2 id="tdd"> + <title>The Data folder</title> + + <para>This folder contains only one file, <filename>world.desktop</filename>. This file is a description of the content of the skin. It is used to describe the organization of the world and how to display it. You don't have to fill it manualy as it will be handled by the &ksirkskineditor;. But, for the sake of completeness, we will now describe its structure.</para> + + <para>An <literal>onu</literal> group contains a number of country entries, a number of nationality entries and lastly a number of continent entries. Then various groups contain the description of the different sprites, the description of the different countries, continents, nationalities and goals.</para> + + <para>The following sections describe the content of each group.</para> + + <sect3> + <title>The <literal>onu</literal> group</title> + + <table> + <title>The <literal>onu</literal> group entries</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Entry name</entry> + <entry>Signification</entry> + </row> + </thead> <tbody> <row> - <entry>map</entry><entry><mediaobject><imageobject><imagedata fileref="map.png" format="PNG"/></imageobject></mediaobject></entry><entry>Map of the skins's world. Countries can have arbitrary shapes, but should be grouped in eye-recognizable continents, by location only or by color</entry> + <entry><literal>width</literal></entry> + <entry>The width of the skin's map.</entry> </row> <row> - <entry>italy</entry><entry><mediaobject><imageobject><imagedata fileref="italy.png" format="PNG"/></imageobject></mediaobject></entry><entry>The flag of the Italy nation. There is one such entry for each nation</entry> + <entry><literal>height</literal></entry> + <entry>The height of the skin's map.</entry> </row> <row> - <entry>infantry</entry><entry><mediaobject><imageobject><imagedata fileref="infantry.png" format="PNG"/></imageobject></mediaobject></entry><entry>Icon representing one army</entry> + <entry><literal>skinpath</literal></entry> + <entry>The path of the skin relative to the application data path (⪚ <filename>skins/default</filename>).</entry> </row> <row> - <entry>cavalry</entry><entry><mediaobject><imageobject><imagedata fileref="cavalry.png" format="PNG"/></imageobject></mediaobject></entry><entry>Icon representing five armies</entry> + <entry><literal>nb-countries</literal></entry> + <entry>The number of countries (42 in the default skin). There should be the same number of country groups below.</entry> </row> <row> - <entry>cannon</entry><entry><mediaobject><imageobject><imagedata fileref="cannon.png" format="PNG"/></imageobject></mediaobject></entry><entry>Icon representing ten armies</entry> + <entry><literal>nb-nationalities</literal></entry> + <entry>The number of nationalities (6 in the default skin). There should be the same number of nationality groups below.</entry> </row> <row> - <entry>firing</entry><entry><mediaobject><imageobject><imagedata fileref="firing.png" format="PNG"/></imageobject></mediaobject></entry><entry>Icon representing armies during a fight</entry> + <entry><literal>nb-continents</literal></entry> + <entry>The number of continents (6 in the default skin). There should be the same number of continent groups below.</entry> </row> <row> - <entry>exploding</entry><entry><mediaobject><imageobject><imagedata fileref="exploding.png" format="PNG"/></imageobject></mediaobject></entry><entry>Icon representing armies when losing a fight</entry> + <entry><literal>pool</literal></entry> + <entry>The path and name of the pool file relative to the skin path (⪚ <filename>Images/pool.svg</filename>).</entry> </row> <row> - <entry>Alaska</entry><entry><mediaobject><imageobject><imagedata fileref="alaska.png" format="PNG"/></imageobject></mediaobject></entry><entry>The shape of the Alaska country. This is used to highligth the country. There is one such shape for each country. Its color is not used. As such, the color is free.</entry> + <entry><literal>map-mask</literal></entry> + <entry>The path and name of the map mask file relative to the skin path (⪚ <filename>Images/map-mask.png</filename>).</entry> </row> <row> - <entry>reddices</entry><entry><mediaobject><imageobject><imagedata fileref="reddices.png" format="PNG"/></imageobject></mediaobject></entry><entry>The red dices used to show battles results</entry> + <entry><literal>format-version</literal></entry> + <entry>The version of the skin file format (2.0).</entry> </row> <row> - <entry>bluedices</entry><entry><mediaobject><imageobject><imagedata fileref="bluedices.png" format="PNG"/></imageobject></mediaobject></entry><entry>The blue dices used to show battles results</entry> + <entry><literal>name</literal></entry> + <entry>The display name of the skin.</entry> </row> <row> - <entry>mark1</entry><entry><mediaobject><imageobject><imagedata fileref="mark1.png" format="PNG"/></imageobject></mediaobject></entry><entry>This mark is added to fighting sprites to show the number of armies they represent, here 1. There is also a mark2 and a mark3 elements.</entry> + <entry><literal>desc</literal></entry> + <entry>The long description of the skin.</entry> + </row> + <row> + <entry><literal>fighters-flag-y-diff</literal></entry> + <entry>The height difference between flags and cannons sprites.</entry> + </row> + <row> + <entry><literal>width-between-flag-and-fighter</literal></entry> + <entry>The number of pixels between the left most pixel of the flag and the right most pixel of the simple cannon (when not firing nor exploding).</entry> </row> </tbody> - </tgroup> - </table> - </para> - </sect3> - <sect3> - <title>The map-mask.png file</title> - <para> - This is a png file representing also the map of the skins's world, but with coded colors that allows one to identify uniquely each country. Countries must have at least the same shapes as the corresponding countries on the map.png file so that users can click anywhere in a viewable country and select the good one. Countries, like little islands as Indonesia in the default map can be greater than the equivalent in the map.png file to facilitate the selection of the country. - <mediaobject> - <imageobject><imagedata fileref="map-mask.png" format="PNG"/></imageobject> - <textobject><phrase>A sample map-mask</phrase></textobject> - </mediaobject> - </para> - <para> - The blue component (in RGB model) of a country's color identifies the country: index 0 is country 0 in the onu.xml file, index 1 is country 1, &etc; White (0xFFFFFF in RGB) identifies the absence of country (sees or, why not, no man's lands). - </para> - </sect3> - <sect3> - <title>The buttons images</title> - <para>The filenames are hard-coded in the code, so they should not be modified. The table below shows all the buttons that should be provided.</para> - <table> - <title>The buttons of the &GUI;</title> - <tgroup cols="3"> - <thead><row><entry>Image</entry><entry>Filename</entry><entry>Signification</entry></row></thead> + </tgroup> + </table> + </sect3> + + <sect3> + <title>The sprites description groups</title> + + <para>Each type of sprite (flag, infantry, cavalry, cannon, firing cannon and exploding cannon) is defined by a group. Only some sprites have a width entry. This entry is used for relative positioning during animations: the cannons, firing or exploding should not "move" around the country's flag during fight.</para> + + <table> + <title>Sprite description group entries</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Entry name</entry> + <entry>Signification</entry> + </row> + </thead> <tbody> <row> - <entry><mediaobject><imageobject><imagedata fileref="newNetGame.png" format="PNG"/></imageobject></mediaobject></entry><entry>newNetGame.png</entry><entry>Tries to join a network game</entry> + <entry><literal>width</literal></entry> + <entry>The reference width of the flag sprite frames.</entry> + </row> + <row> + <entry><literal>height</literal></entry> + <entry>The reference height of the flag sprite frames.</entry> </row> <row> - <entry><mediaobject><imageobject><imagedata fileref="recycling.png" format="PNG"/></imageobject></mediaobject></entry><entry>recycling.png</entry><entry>After all players have put their armies, it is possible to modify the distributions (named recycling). This button asks to do such a redistribution</entry> + <entry><literal>frames</literal></entry> + <entry>The number of frames of the sprite.</entry> + </row> + <row> + <entry><literal>versions</literal></entry> + <entry>The number of versions of the flag sprites.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + + <sect3> + <title>The countries description groups</title> + + <para>Each country listed in the <literal>onu</literal> group, countries entry has its own group whose label is the country name. The table below lists the entries of these groups.</para> + + <table> + <title>Country entries</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Entry name</entry> + <entry>Signification</entry> </row> + </thead> + <tbody> <row> - <entry><mediaobject><imageobject><imagedata fileref="recyclingFinished.png" format="PNG"/></imageobject></mediaobject></entry><entry>recyclingFinished.png</entry><entry>Chooses not to redistribute. All clients windows must have this button clicked to really end the distribution</entry> + <entry><literal>id</literal></entry> + <entry>The integer unique identification number of the country, must start at zero (0).</entry> </row> <row> - <entry><mediaobject><imageobject><imagedata fileref="nextPlayer.png" format="PNG"/></imageobject></mediaobject></entry><entry>nextPlayer.png</entry><entry>Ends the current player's turn and switch to the next one or to the next turn if the current player was the last one</entry> + <entry><literal>name</literal></entry> + <entry>The displayed name of the country.</entry> </row> <row> - <entry><mediaobject><imageobject><imagedata fileref="attackOne.png" format="PNG"/></imageobject></mediaobject></entry><entry>attackOne.png</entry><entry>Chooses to start an attack with one army</entry> + <entry><literal><sprite>-point</literal></entry> + <entry>Each type of sprite (flag, infantry, &etc;) in the country is displayed at a certain position defined by this entry made of two integers separated by a comma.</entry> </row> <row> - <entry><mediaobject><imageobject><imagedata fileref="attackTwo.png" format="PNG"/></imageobject></mediaobject></entry><entry>attackTwo.png</entry><entry>Chooses to start an attack with two armies</entry> + <entry><literal>neighbours</literal></entry> + <entry>The list of the ids of the neighbors of the current country.</entry> </row> + </tbody> + </tgroup> + </table> + </sect3> + + <sect3> + <title>The nationalities description groups</title> + + <para>Each nationality listed in the <literal>onu</literal> group, nationalities entry has its own group whose label is the nationality name. The table below lists the entries of these groups.</para> + + <table> + <title>Nationality entries</title> + <tgroup cols="2"> + <thead> <row> - <entry><mediaobject><imageobject><imagedata fileref="attackThree.png" format="PNG"/></imageobject></mediaobject></entry><entry>attackThree.png</entry><entry>Chooses to start an attack with three armies</entry> + <entry>Entry name</entry> + <entry>Signification</entry> </row> + </thead> + <tbody> <row> - <entry><mediaobject><imageobject><imagedata fileref="defendOne.png" format="PNG"/></imageobject></mediaobject></entry><entry>defendOne.png</entry><entry>Chooses to defend an attacked country with one army</entry> + <entry><literal>name</literal></entry> + <entry>The name of the nationality (⪚ <literal>Japan</literal>).</entry> </row> <row> - <entry><mediaobject><imageobject><imagedata fileref="defendTwo.png" format="PNG"/></imageobject></mediaobject></entry><entry>defendTwo.png</entry><entry>Chooses to defend an attacked country with two armies</entry> + <entry><literal>leader</literal></entry> + <entry>The name that will be proposed to the player choosing this nationality.</entry> </row> <row> - <entry><mediaobject><imageobject><imagedata fileref="moveArmies.png" format="PNG"/></imageobject></mediaobject></entry><entry>moveArmies.png</entry><entry>Chooses to start the moving of armies between two countries (last action in the turn)</entry> + <entry><literal>flag</literal></entry> + <entry>The name of the country's flag sprite element in the <literal>onu</literal> &SVG; file.</entry> </row> </tbody> - </tgroup> - </table> - </sect3> - </sect2> - <sect2 id="tsd"> - <title>The Sounds folder</title> - <para>This folder contains three sound files:</para> - <itemizedlist><listitem><para>roll.wav played when armies are moving </para></listitem> - <listitem><para>cannon.wav played when firing and </para></listitem><listitem> - <para>crash.wav played when a cannon explodes</para></listitem></itemizedlist> - </sect2> - </sect1> - <sect1 id="using-kse"> - <title>Using the &kappname;</title> - <para>After creating the graphics in the right folder and SVG file, you just have to create countries, players, etc. and associate them with the right SVG element in the pool. This can be done with the &kappname;. Note that each part of this application is auto-described by tooltips and contextual help usualy reachable through the Ctrl+F1 shortcut.</para> - <para> - <screenshot> - <screeninfo>Here's a screenshot of &kappname;</screeninfo> - <mediaobject> - <imageobject> - <imagedata fileref="main-snapshot.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Screenshot</phrase> - </textobject> - </mediaobject> - </screenshot> - </para> - </sect1> -</chapter> + </tgroup> + </table> + </sect3> + + <sect3> + <title>The continents description groups</title> + + <para>Each continent listed in the <literal>onu</literal> group, continents entry has its own group whose label is the continent name. The table below lists the entries of these groups.</para> + + <table> + <title>Continent entries</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Entry name</entry> + <entry>Signification</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>name</literal></entry> + <entry>The name of the continent (⪚ <literal>Africa</literal>).</entry> + </row> + <row> + <entry><literal>id</literal></entry> + <entry>The integer unique identification number of the continent.</entry> + </row> + <row> + <entry><literal>bonus</literal></entry> + <entry>The number of armies obtained at the end of the turn by the player owning all the countries of the continent.</entry> + </row> + <row> + <entry><literal>continent-countries</literal></entry> + <entry>The list of the ids of the countries inside the current continent.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + + <sect3> + <title>The goals description groups</title> + + <para>Each goal listed in the <literal>onu</literal> group, goals entry has its own group whose label is the goal name. The table below lists the entries of these groups.</para> + + <table> + <title>Goal entries</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Entry name</entry> + <entry>Signification</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>type</literal></entry> + <entry>The type of goal. Can be continents, countries or player.</entry> + </row> + <row> + <entry><literal>nbArmiesByCountry</literal></entry> + <entry>Set the minimal number of armies the player will have to put on each country.</entry> + </row> + <row> + <entry><literal>nbCountries</literal></entry> + <entry>Set the number of countries the player must possess.</entry> + </row> + <row> + <entry><literal>nbCountriesFallback</literal></entry> + <entry>For a player goal type, if the target player is killed by another one, this sets the number of countries the player will have to conquer instead.</entry> + </row> + <row> + <entry><literal>desc</literal></entry> + <entry>A full text description of the goal with appropriate placeholders (needs more doc here).</entry> + </row> + <row> + <entry><literal>continents</literal></entry> + <entry>The list of continents ids the player will have to conquer.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + </sect2> + + <sect2 id="tid"> + <title>The Images folder</title> + + <para>This folder contains the buttons specific to &ksirk; and the pool &SVG; file that contains the map and all sprites.</para> + + <sect3> + <title>The <filename>pool.svg</filename> file</title> + + <para>This &SVG; file contains the map and all the sprites of the game. Each element is named such that the game can select and render separately each of them.</para> + + <para>In the default skin, the sprites are flags, infantry, cavalry and cannon. Infantry represents one army, five for cavalry and ten for cannons. Cannons are also used to display fighting armies. That's why there is three kinds of cannon sprites: normal static or moving cannon, firing one and exploding one.</para> + + <para>Each sprite image is the concatenation of the various views of the object and for each view, its frames. Views are organized vertically and frames horizontally. Where to cut the image in individual frames is found by dividing the height of the image by the number of views and the width by the number of frames. These data are found in the <filename>onu.desktop</filename> file.</para> + + <mediaobject> + <imageobject><imagedata fileref="cannon.png" format="PNG"/></imageobject> + <caption><para>An example of a sprite image: <filename>cannon.png</filename></para></caption> + </mediaobject> + + <para>For armies sprites, there is three different views, from top to bottom:</para> + + <itemizedlist> + <listitem><para>looking right</para></listitem> + <listitem><para>looking left and</para></listitem> + <listitem><para>facer</para></listitem> + </itemizedlist> + + <para>For flags, there is only one view. All sprites backgrounds should be set to transparent.</para> + <mediaobject> + <imageobject><imagedata fileref="italy.png" format="PNG"/></imageobject> + <caption><para>An example of a flag sprite image: <filename>italy.png</filename></para></caption> + </mediaobject> + <table> + <title>The elements of the pool</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Element name</entry> + <entry>Sample image</entry> + <entry>Signification</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>map</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="map.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>Map of the skins's world. Countries can have arbitrary shapes, but should be grouped in eye-recognizable continents, by location only or by color.</entry> + </row> + <row> + <entry><literal>italy</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="italy.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>The flag of the Italy nation. There is one such entry for each nation.</entry> + </row> + <row> + <entry><literal>infantry</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="infantry.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>Icon representing one army.</entry> + </row> + <row> + <entry><literal>cavalry</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="cavalry.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>Icon representing five armies.</entry> + </row> + <row> + <entry><literal>cannon</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="cannon.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>Icon representing ten armies.</entry> + </row> + <row> + <entry><literal>firing</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="firing.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>Icon representing armies during a fight.</entry> + </row> + <row> + <entry><literal>exploding</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="exploding.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>Icon representing armies when losing a fight.</entry> + </row> + <row> + <entry><literal>alaska</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="alaska.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>The shape of the Alaska country. This is used to highligth the country. There is one such shape for each country. Its color is not used. As such, the color is free.</entry> + </row> + <row> + <entry><literal>reddices</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="reddices.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>The red dices used to show battles results.</entry> + </row> + <row> + <entry><literal>bluedices</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="bluedices.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>The blue dices used to show battles results.</entry> + </row> + <row> + <entry><literal>mark1</literal></entry> + <entry><mediaobject><imageobject><imagedata fileref="mark1.png" format="PNG"/></imageobject></mediaobject></entry> + <entry>This mark is added to fighting sprites to show the number of armies they represent, here 1. There is also a mark2 and a mark3 elements.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + + <sect3> + <title>The <filename>map-mask.png</filename> file</title> + + <para>This is a png file representing also the map of the skins's world, but with coded colors that allows one to identify uniquely each country. Countries must have at least the same shapes as the corresponding countries on the <filename>map.png</filename> file so that users can click anywhere in a viewable country and select the good one. Countries, like little islands as Indonesia in the default map can be greater than the equivalent in the <filename>map.png</filename> file to facilitate the selection of the country.</para> + + <mediaobject> + <imageobject><imagedata fileref="map-mask.png" format="PNG"/></imageobject> + <textobject><phrase>A sample map-mask</phrase></textobject> + </mediaobject> + + <para>The blue component (in RGB model) of a country's color identifies the country: index 0 is country 0 in the <filename>onu.xml</filename> file, index 1 is country 1, &etc; White (0xFFFFFF in RGB) identifies the absence of country (sees or, why not, no man's lands).</para> + </sect3> + + <sect3> + <title>The buttons images</title> + + <para>The filenames are hard-coded in the code, so they should not be modified. The table below shows all the buttons that should be provided.</para> + + <table> + <title>The buttons of the &GUI;</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Image</entry> + <entry>Filename</entry> + <entry>Signification</entry> + </row> + </thead> + <tbody> + <row> + <entry><mediaobject><imageobject><imagedata fileref="newNetGame.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>newNetGame.png</filename></entry> + <entry>Tries to join a network game.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="recycling.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>recycling.png</filename></entry> + <entry>After all players have put their armies, it is possible to modify the distributions (named recycling). This button asks to do such a redistribution.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="recyclingFinished.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>recyclingFinished.png</filename></entry> + <entry>Chooses not to redistribute. All clients windows must have this button clicked to really end the distribution.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="nextPlayer.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>nextPlayer.png</filename></entry> + <entry>Ends the current player's turn and switch to the next one or to the next turn if the current player was the last one.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="attackOne.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>attackOne.png</filename></entry> + <entry>Chooses to start an attack with one army.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="attackTwo.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>attackTwo.png</filename></entry> + <entry>Chooses to start an attack with two armies.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="attackThree.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>attackThree.png</filename></entry> + <entry>Chooses to start an attack with three armies.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="defendOne.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>defendOne.png</filename></entry> + <entry>Chooses to defend an attacked country with one army.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="defendTwo.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>defendTwo.png</filename></entry> + <entry>Chooses to defend an attacked country with two armies.</entry> + </row> + <row> + <entry><mediaobject><imageobject><imagedata fileref="moveArmies.png" format="PNG"/></imageobject></mediaobject></entry> + <entry><filename>moveArmies.png</filename></entry> + <entry>Chooses to start the moving of armies between two countries (last action in the turn).</entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + </sect2> + + <sect2 id="tsd"> + <title>The Sounds folder</title> + + <para>This folder contains three sound files:</para> + + <itemizedlist> + <listitem><para><filename>roll.wav</filename> played when armies are moving </para></listitem> + <listitem><para><filename>cannon.wav</filename> played when firing and </para></listitem> + <listitem><para><filename>crash.wav</filename> played when a cannon explodes</para></listitem> + </itemizedlist> + </sect2> +</sect1> + +<sect1 id="using-kse"> +<title>Using the &ksirkskineditor;</title> + +<para>After creating the graphics in the right folder and &SVG; file, you just have to create countries, players, &etc; and associate them with the right &SVG; element in the pool. This can be done with the &ksirkskineditor;. Note that each part of this application is auto-described by tooltips and contextual help usualy reachable through the <keycombo action="simul">&Ctrl;<keycap>F1</keycap></keycombo> shortcut.</para> + +<screenshot> + <screeninfo>Here's a screenshot of &ksirkskineditor;</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="main-snapshot.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot</phrase></textobject> + </mediaobject> +</screenshot> +</sect1> +</chapter> <chapter id="commands"> <title>Command Reference</title> <sect1 id="kapp-mainwindow"> -<title>The main &kappname; window</title> -<sect2> -<title>The buttons</title> -<para> -<variablelist> - <varlistentry> - <term> +<title>The main &ksirkskineditor; window</title> + + <sect2> + <title>The buttons</title> + + <variablelist> + <varlistentry> + <term> <inlinemediaobject> - <imageobject> - <imagedata fileref="load.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Load</phrase> - </textobject> + <imageobject><imagedata fileref="document-open.png" format="PNG"/></imageobject> + <textobject><phrase>Load</phrase></textobject> </inlinemediaobject> - <guibutton>Load</guibutton> - </term> - <listitem><para><action>Causes the program to load an existing skin.</action></para> - </listitem> - </varlistentry> - <varlistentry> - <term> + <guibutton>Load...</guibutton> + </term> + <listitem><para><action>Causes the program to load an existing skin.</action></para></listitem> + </varlistentry> + + <varlistentry> + <term> <inlinemediaobject> - <imageobject> - <imagedata fileref="save.png" format="PNG"/> - </imageobject> - <textobject> - <phrase>Save</phrase> - </textobject> + <imageobject><imagedata fileref="document-save.png" format="PNG"/></imageobject> + <textobject><phrase>Save</phrase></textobject> </inlinemediaobject> - <guibutton>Save</guibutton> - </term> - <listitem> - <para><action>Saves the currently edited skin</action></para> - </listitem> - </varlistentry> -</variablelist> -</para> - -</sect2> - + <guibutton>Save</guibutton> + </term> + <listitem><para><action>Saves the currently edited skin</action></para></listitem> + </varlistentry> + </variablelist> + </sect2> </sect1> </chapter> <chapter id="developers"> - <title>Developer's Guide to &kappname;</title> - - <para> - Please refer to <ulink url="http://api.kde.org/";>http://api.kde.org/</ulink> for the documentation of the API. - </para> +<title>Developer's Guide to &ksirkskineditor;</title> + +<para>Please refer to <ulink url="https://api.kde.org/";>https://api.kde.org/</ulink> for the documentation of the API.</para> </chapter> <chapter id="faq"> @@ -514,16 +670,11 @@ distribution. --> <title>Credits and License</title> -<para> -&kappname; -</para> -<para> -Program copyright 2009 Gael de Chalendar <email>[email protected]</email> -</para> +<para>&ksirkskineditor;</para> + +<para>Program copyright 2009 Gaël de Chalendar <email>[email protected]</email></para> -<para> -Documentation copyright 2009 Gael de Chalendar <email>[email protected]</email> -</para> +<para>Documentation copyright 2009 Gaël de Chalendar <email>[email protected]</email></para> <!-- TRANS:CREDIT_FOR_TRANSLATORS --> @@ -551,16 +702,3 @@ sgml-indent-step:0 sgml-indent-data:nil End: --> - - - - - - - - - - - - - diff --git a/doc/ksirkskineditor/load.png b/doc/ksirkskineditor/load.png deleted file mode 100644 index b750520..0000000 Binary files a/doc/ksirkskineditor/load.png and /dev/null differ diff --git a/doc/ksirkskineditor/save.png b/doc/ksirkskineditor/save.png deleted file mode 100644 index d3a653c..0000000 Binary files a/doc/ksirkskineditor/save.png and /dev/null differ
