User manual

doc/help/conf.py

@@ -19,25 +19,25 @@
 
 # General information about the project.
 project = 'Tanglet'
-copyright = ' 2021 Graeme Gott'
+copyright = ' 2026 Graeme Gott'
 author = 'Graeme Gott'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.6'
+version = '3.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.6.0'
+release = '3.0.3'
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [ 'sphinxcontrib.email' ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
@@ -70,7 +70,7 @@
 
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
-html_title = 'Tanglet'
+html_title = 'Tetzle'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -98,3 +98,6 @@
 
 # If true, Sphinx will add “permalinks” for each heading and description environment.
 html_permalinks = False
+
+# Setting to display email adresses as obfuscated mailto links, needs sphinxcontrib-email
+email_automode = True

doc/help/configuration.rst

@@ -1,2 +1,57 @@
+.. _configuration:
+
 Game Configuration
-==================
+******************
+
+To configure :program:`Tanglet`, open the :menuselection:`Settings` menu. You see the
+following entries:
+
+:menuselection:`Show &Maximum Score` – you can choose between three options for
+the status line at the bottom of the window:
+
+* :menuselection:`&Never` – You see word lengths and the count of words found
+  for each length.
+
+* :menuselection:`&End Of Game` – At the end of the game, you see the contained
+  words per word length and the count of words found by you.
+
+* :menuselection:`&Always`: The behavior described for
+  :menuselection:`&End Of Game` is always visible.
+
+The visibility of the word count status bar can be toggled with
+:menuselection:`Show Word &Counts`.
+
+:menuselection:`Show Missed &Words` – In addition to the list of found words
+on the left, an extra tab named :guilabel:`Missed` will de displayed. This tab
+is inactive until the game ends.
+
+:menuselection:`&Board Language` – You can change the board language by
+clicking on the drop-down list and choose from the available languages. Besides
+that, you have some extra options:
+
+.. figure:: ./figures/tanglet_board_language.png
+
+You can change the file paths to :guilabel:`Dice`, :guilabel:`Word List` and
+:guilabel:`Dictionary` by entering the file paths manually or click on the
+respective :guilabel:`Choose…` buttons to open a file chooser dialog. To set
+all entries back to the defaults, click on :guilabel:`Defaults` in the bottom
+left corner of the window. As usual, you can stop editing the preferences with
+the :guilabel:`Cancel` button, and apply the changes with :guilabel:`OK`. Your
+changes will be applied after the next start of :program:`Tanglet`.
+
+Under :menuselection:`Application &Language`, you can change the language of
+the user interface. The settings window opens with the button
+:guilabel:`<System language>`. Click on it to change the desired language from
+the drop-down menu. Again, your changes will be applied after the next start of
+:program:`Tanglet`.
+
+.. note::
+     Maybe the following command is known to you for opening an application
+     with different language settings:
+
+     .. code-block::
+
+        export LC_ALL=C && tanglet
+
+     This doesn't work correctly in :program:`Tanglet`. To change the user interface
+     language, we recommend to use the configuration option described above.

doc/help/credits.rst

@@ -1,6 +1,10 @@
 Credits and License
-===================
+*******************
 
-Program copyright 2009-2021 Graeme Gott <graeme@gottcode.org>
+Program copyright 2009-2026 :email:`Graeme Gott <graeme@gottcode.org>`
 
-This program is licensed under the terms of the `GNU General Public License <http://www.gnu.org/licenses/gpl.html>`_.
+User manual written by :email:`Graeme Gott <graeme@gottcode.org>` and
+:email:`Mario Blättermann <mario.blaettermann@gmail.com>`
+
+This program is licensed under the terms of the
+`GNU General Public License <http://www.gnu.org/licenses/gpl.html>`_.

doc/help/howtoplay.rst

@@ -1,22 +1,40 @@
-How to Play
-===========
-
-Using the Mouse
----------------
-
-**Select a word:** Click on the letters of a word.
-
-**Make a guess:** Click on the last selected letter.
-
-**Erase letters:** Click on an earlier selected letter.
+.. _howtoplay:
 
-**Clear the word:** Click twice on the first selected letter.
-
-Using the Keyboard
-------------------
-
-**Select a word:** Type the letters of a word.
-
-**Make a guess:** Press Enter.
-
-**Clear the word:** Press Ctrl+Backspace.
+How to Play
+***********
+
++----------------+-------------------------------------------+------------------------------+
+| Action         | Using the mouse                           | Using the keyboard           |
++================+===========================================+==============================+
+| Select a word  | Click on the letters of a word.           | Type the letters of a word.  |
++----------------+-------------------------------------------+------------------------------+
+| Make a guess   | Click on the last selected letter.        | Press :kbd:`Enter`.          |
++----------------+-------------------------------------------+------------------------------+
+| Erase letters  | Click on an earlier selected letter.      | Press :kbd:`Backspace`.      |
++----------------+-------------------------------------------+------------------------------+
+| Clear the word | Click twice on the first selected letter. | Press :kbd:`Ctrl+Backspace`. |
++----------------+-------------------------------------------+------------------------------+
+
+
+Once you found an acceptable word, it will be displayed in the list left to the
+board. In case you find the word *again*, it will be highlighted in this list.
+If the word can be extended with one or more letters, click on it to display it
+again on the board, and you can add more letters to create a new word.
+
+When you hover the mouse pointer over one of the accepted words in the list,
+a popup displays the word in eventually different spellings and how many points
+you have earned for this word.
+
+.. I remember, there was such an icon in previous versions...
+
+   When you hover the mouse pointer over one of the accepted words in the list,
+   a clickable book icon will be displayed, which leads you to the appropriate
+   entry in Wiktionary.
+
+The wordlist has a tab :guilabel:`Missed`, which is inactive during the game
+play. When the game is over, you can click on it to see the words which you
+haven't found.
+
+.. note::
+     When closing the game without it has ended, the same game at the same
+     score will be opened when **Tanglet** starts next time.

doc/help/index.rst

@@ -1,9 +1,9 @@
 Tanglet User Manual
-===================
+*******************
 
 Tanglet |release|
 
-Copyright © 2009-2021 Graeme Gott
+Copyright © 2009-2026 :email:`Graeme Gott <graeme@gottcode.org>`
 
 Abstract
 --------

doc/help/introduction.rst

@@ -1,2 +1,132 @@
+.. _introduction:
+
 Introduction
-============
+************
+
+:program:`Tanglet` is a single player word finding game based on
+`Boggle <https://en.wikipedia.org/wiki/Boggle>`__. The object of the game is to
+list as many words as you can before the time runs out. There are several timer
+modes that determine how much time you start with, and if you get extra time
+when you find a word.
+
+You can join letters horizontally, vertically, or diagonally in any direction
+to make a word, so as long as the letters are next to each other on the board.
+However, you can not reuse the same letter cells in a single word. Also, each
+word must be at least three letters on a normal board, and four letters on a
+large board.
+
+-----------------
+Starting the game
+-----------------
+
+You can start the game using the application menu of your desktop environment.
+Open the application menu and choose :menuselection:`Games --> Tanglet` or open
+a quick start prompt using :kbd:`Alt-F2` and start typing *tanglet*, then click
+on the application name found.
+
+When :program:`Tanglet` starts, two board sizes are available, 4x4 and 5x5.
+Click on one of them to apply. In the drop-down list right to
+:guilabel:`Amount Of Words`, you can choose between more or less words
+contained in the board. Try out how it results in the created word counts in
+the board, in many cases, with a 5x5 board, you get more than 1000 contained
+words. The other drop-down list :guilabel:`Minimum Word Length` lets you choose
+between acceptable character counts. The minimally configurable word length
+depends on the board let's say 5, then words with 4 letters, which actually
+exists, won't be accepted by :program:`Tanglet`.
+
+
+Finally you can choose between different game modes:
+
+.. figure:: ./figures/tanglet_change_modes.png
+
+The following modes are available:
+
+* :guilabel:`Allotment` – Game ends after 30 guesses.
+
+* :guilabel:`Classic` – Counts fown from 3 minutes.
+
+* :guilabel:`Discipline` – Counts down from 30 seconds and increases on correct
+  guesses.
+
+* :guilabel:`Refill` – Counts down from 30 seconds and refills on correct
+  guesses.
+
+* :guilabel:`Stamina` – Counts down from 45 seconds and pauses on correct
+  guesses.
+
+* :guilabel:`Strikeout` – Game ends after 3 incorrect guesses.
+
+* :guilabel:`Tanglet` – Counts down from 30 seconds and increases or decreases
+  on guesses.
+
+* :guilabel:`Unlimited` – Game ends when all words are found.
+
+-----------------
+Menu bar overview
+-----------------
+
+*Game* menu
+-----------
+
+* :menuselection:`New &Game` – Starts a new game. If a previous game is still
+  running, you will asked for confirmation to stop that game.
+
+* :menuselection:`&New Roll` – Starts a new game in the same mode as the
+  currently running one. Again, you will asked for confirmation to stop that
+  game.
+
+* :menuselection:`&Choose…` – Lets you start a game which has been saved
+  previously. A file chooser dialog will be opened where you can search for the
+  desired game file.
+
+* :menuselection:`&Share` – Lets you save the game in a file. A file chooser
+  dialog will be opened where you can choose for a file name and directory.
+  Although it is possible, keep the :guilabel:`File type` entry unchanged. We
+  don't recommend to save files with another extension than :file:`.tanglet`.
+
+* :menuselection:`&End` – End the game. You will asked for confirmation to stop
+  the game.
+
+* :menuselection:`&Pause` – Pause the game. Probably you need this for
+  time-limited games. When pausing a game, the whole window content disappears.
+  After clicking anywhere in the window, the pause ends and the content comes
+  back. Note, also when the window losts the focus, the window content
+  disappears.
+
+* :menuselection:`&Details` – Shows details about the running game, such as the
+  board size, the word density and length, the game type and a short
+  description of that game.
+
+* :menuselection:`&High Scores` – Shows the High Scores. The initial view shows
+  the High Scores for the type of the currently running game. To view the High
+  Scores for the other game types, click on the vertical tab bar on the left.
+
+* :menuselection:`&Quit` – Quits the game and the application.
+
+
+*Settings* menu
+---------------
+
+See :ref:`configuration` about how to use the entries of the
+:menuselection:`&Settings` menu.
+
+
+
+*Help* menu
+-----------
+
+* :menuselection:`&Controls` – Shows a brief summary of the usage. In fact,
+  the same as described in :ref:`howtoplay`.
+
+.. For the upcoming user manual; mnemonic needs to be added later
+
+* :menuselection:`User &manual` – Opens this user manual in your configured
+  standard browser. The opened application is out of the scope of
+  :program:`Tanglet`; if you like to use a different browser or HTML viewer,
+  you need to configure this in the settings of your desktop environment.
+
+* :menuselection:`&About` – Shows a brief summary, including the version number
+  of :program:`Tanglet`.
+
+* :menuselection:`About &Qt` – Shows a description of
+  `Qt <https://www.qt.io/>`__, which is the code base of :program:`Tanglet`.

doc/help/locales/de/LC_MESSAGES/configuration.po

@@ -1,23 +1,25 @@
-# SOME DESCRIPTIVE TITLE.
+# German translation of the Tanglet user manual
 # Copyright (C)  2021 Graeme Gott
 # This file is distributed under the same license as the Tanglet package.
-# FIRST AUTHOR <EMAIL@ADDRESS>, 2021.
 #
-#, fuzzy
+# Mario Blättermann <mario.blaettermann@gmail.com>, 2021.
 msgid ""
 msgstr ""
 "Project-Id-Version: Tanglet 1.6\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2021-04-26 15:30-0400\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
+"PO-Revision-Date: 2021-04-27 19:27+0200\n"
+"Last-Translator: Mario Blättermann <mario.blaettermann@gmail.com>\n"
+"Language-Team: German <debian-l10n-german@lists.debian.org>\n"
 "MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=utf-8\n"
+"Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 2.9.0\n"
+"Language: de\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"X-Generator: Lokalize 21.04.0\n"
 
 #: ../configuration.rst:2
 msgid "Game Configuration"
-msgstr ""
+msgstr "Einstellungen des Spiels"