[Tux4kids-commits] r512 - tuxmath/trunk/doc
tholy-guest at alioth.debian.org
tholy-guest at alioth.debian.org
Wed Jun 11 21:27:00 UTC 2008
Author: tholy-guest
Date: 2008-06-11 21:26:58 +0000 (Wed, 11 Jun 2008)
New Revision: 512
Modified:
tuxmath/trunk/doc/INSTALL.txt
tuxmath/trunk/doc/README.txt
Log:
Update the documentation; in particular, information on command-line options was moved to the end, since it's not needed so much anymore.
Modified: tuxmath/trunk/doc/INSTALL.txt
===================================================================
--- tuxmath/trunk/doc/INSTALL.txt 2008-05-19 21:52:32 UTC (rev 511)
+++ tuxmath/trunk/doc/INSTALL.txt 2008-06-11 21:26:58 UTC (rev 512)
@@ -4,6 +4,29 @@
December 19, 2007
+For users
+---------
+
+This document is mostly about building TuxMath on your own
+computer. If you just want to download a working copy of the program,
+then you might want to consider pre-built versions.
+
+For Linux: your distribution probably already has packages available.
+Your distributor probably has a graphical way to install tuxmath.
+Alternatively, you can use the command line to install it. For
+example, with Debian systems you can say "apt-get install tuxmath" and
+you're done.
+
+For Windows/Macs: visit http://www.tux4kids.com, click on "Released
+Files," and find the most recent package for your platform. You will
+not need the source code packages. Save the package on your
+harddrive and double-click on the icon.
+
+
+The remainder of this document is for people who want to compile TuxMath
+themselves on their own computers.
+
+
Requirements
------------
Operating System
@@ -33,12 +56,11 @@
Video Display
-------------
- TuxMath displays the game screen in a 640x480 window.
+ By default, TuxMath displays fullscreen, as long as a 640x480
+ resolution is supported by your system. TuxMath can also display
+ the game screen in a 640x480 window. F10 toggles between these
+ two modes.
- If a 640x480 resolution is supported by your system, the game can
- also display in full-screen mode(see "README.txt" or the program's
- "--usage" display).
-
When attempting to run in fullscreen mode on systems where true 640x480
resolution isn't available for some reason, the next-lowest resolution
available will be used, and the game area will be centered within a
@@ -64,7 +86,8 @@
-------------
The game is typically played using a keyboard. The numeric keypad
portion of standard PC keyboards is supported (so if there are any
- stand-alone numeric keyboards with no other keys, they SHOULD work, too).
+ stand-alone numeric keyboards with no other keys, they SHOULD
+ work, too).
Menus and options can be controlled with either the pointer or the
keyboard's arrow keys.
@@ -319,12 +342,13 @@
to do a local build, using macports is perhaps the easiest approach:
"port install tuxmath" and then wait.
- To build a .dmg, currently-supported approach is to use CMake
+ To build a .dmg, the currently-supported approach is to use CMake
(described above under Linux/Unix). You will need to have both
gettext and cmake installed on the build machine; using macports is
- the easiest way, "port install cmake gettext". "make install" will
- create the .dmg in the build directory.
+ the easiest way, "port install cmake gettext".
+ "make install" will create the .dmg in the build directory.
+
Finally, it is also possible to do the conventional "./configure;
make; make install" if you have the required libraries.
Modified: tuxmath/trunk/doc/README.txt
===================================================================
--- tuxmath/trunk/doc/README.txt 2008-05-19 21:52:32 UTC (rev 511)
+++ tuxmath/trunk/doc/README.txt 2008-06-11 21:26:58 UTC (rev 512)
@@ -2,11 +2,10 @@
An educational math tutorial game starring Tux, the Linux Penguin
-----------------------------------------------------------------
+June 11, 2008
-October 29, 2007
+For tuxmath-1.6.3
-For tuxmath-1.6.1
-
Objective
---------
In "Tux, of Math Command," you play the part of Commander Tux, as he
@@ -25,135 +24,37 @@
Configuration
-------------
- If all players are using a single account (e.g., a home computer
+ If multiple players are using a single account (e.g., a home computer
that is always logged in, or a school setting in which all students
have a single username), you may want to do some additional
- configuration---see below under "Configuring multiple users."
+ configuration---see below under "Configuring Multiple Users."
Running The Program
-------------------
Linux/Unix
----------
- Simply type the command "tuxmath" at a command prompt (eg, in an xterm).
+ Your distribution probably already has a menu entry for Tuxmath
+ under the KDE or GNOME menus. If not, depending on your graphical
+ interface or window manager, you can probably also create a
+ clickable icon which will launch the game. See your interface's
+ documentation or help screens for details.
- Depending on your graphical interface or window manager, you can
- probably also create a clickable icon which will launch the game.
- See your interface's documentation or help screens for details.
+ Alternatively, simply type the command "tuxmath" at a command
+ prompt (eg, in an xterm).
Windows
-------
Just double-click the "TuxMath.exe" icon or select "Tuxmath" in the Start
Menu. The current installer creates menu items to run tuxmath either in
Fullscreen mode or within a 640 x 480 window.
- To be prompted for command line options, run tuxmath from the "Run" dialog
- or the "C:> Command Prompt" console. Type "TuxMath.exe" followed by any
- desired options (see below). If it does not run, make sure the full path
- to the program (e.g. C:\Program Files\TuxMath\TuxMath.exe) is known to
- Windows, either through Control Panel settings or by changing to the
- directory containing TuxMath.exe before issuing the command.
MacOS
-----
- [ UNDER CONSTRUCTION ] Just double-click the "tuxmath" icon. ???
- To be prompted for command line options (see below), hold the [OPTION] key
- as you double-click the icon.
+ Double-click the "tuxmath" icon.
- Command Line Options
- --------------------
- NOTE: Tuxmath now has many pre-packaged "missions" (lessons), as well
- as four arcade-style open-ended games of progressive difficulty, so
- there is much less need to change settings. If desired, editing the
- config file is a much better way to control the behavior of Tuxmath
- than the command-line options, for the most part. However, many
- options are still supported.
- The following command-line options can be sent to the program:
- --optionfile filename - play game based on settings in the named file (see
- below for more on tuxmath config files). Tuxmath will
- look for a valid config file with a matching name in
- the following locations:
- 1. current working directory
- 2. as an absolute pathname
- 3. in the missions directory with tuxmath's
- other data files.
- 4. in the user's tuxmath options directory
- (e.g. /home/laura/.tuxmath/filename
- 5. in the user's home directory.
-
- --playthroughlist - Game consists of working through a list of questions
- -r generated based on the selected options (or defaults).
- If a comet strikes a city without being shot down by
- the player, the question is reinserted into the list
- in a random location. If the player answers all questions
- correctly before the cities are destroyed, he/she wins.
- If all cities get destroyed, the game ends in defeat.
-
- --answersfirst - to ask questions in format: ? + num2 = num3 instead of
- default format: num1 + num2 = ?.
-
- --answersmiddle - to ask questions in format: num1 + ? = num3 instead of
- default format: num1 + num2 = ?.
-
- --fullscreen - Run the game in full screen, instead of in a window,
- -f if possible.
-
- --windowed - Run the game in a 640 x 480 window.
- -w
-
- --nosound - Do not play any sounds or music.
- -s
- --quiet
- -q
-
- --nobackground - Do not display photographic backgrounds in game.
- -b (Useful on slower systems.)
-
- --keypad - Display an on-screen numeric keypad. (Useful
- -k for touch screens or in place of a physical keyboard.)
-
- --operator OP - Add an operator to the game (will cause the program
- -o OP to ignore saved option screen settings). You can
- use this switch multiple times to run the game
- with multiple operators.
-
- Valid values for "OP" are:
-
- add
- subtract
- multiply
- divide
-
- --demo - Demo mode. The game will cycle back and forth
- -d between the title and the game, and it will
- auto-play the game. The only user interaction
- can be for quitting or pausing.
-
- --allownegatives Allows subtraction answers to be less than zero.
- -n When selected, the led numbers at the top of the
- screen will include a fourth digit for the '-' sign.
- Also, if --keypad is selected, the '-' and '+' may
- be grayed-out depending if negatives are allowed.
-
-
- These command-line options display useful information, but the program
- does not attempt to start up in interactive mode.
-
- --help - Display a short help message, explaining how to
- -h play the game.
-
- --usage - Display the available command-line options.
- -u
-
- --version - Display the version of "tuxmath" you're running.
- -v
-
- --copyright - Display copyright information
- -c
-
-
-
Program Navigation
------------------
Title Screen
@@ -181,7 +82,9 @@
player's home directory (see below). At some point, the options will be
settable from within the game.
- More Options - this will be developed into the menus to set options not
+ Help: this offers a short tutorial to teach game play.
+
+ More Options: this will be developed into the menus to set options not
directly related to math questions, such as toggling the music on and off,
playing fullscreen vs. windowed, using cities vs. igloos, and the like.
Now it just has the "Demo" mode, as well as credits and project information.
@@ -197,6 +100,10 @@
How To Play
-----------
+ One of the best ways to get started is by choosing the "Help" option
+ in the main menu. This offers a tutorial for basic play. There are
+ some additional features described below.
+
Destroying Comets
-----------------
As the comets fall towards your friends, you must solve the equations.
@@ -212,7 +119,7 @@
LED display for the minus sign. The '-' and '+' keys will toggle the
minus sign on and off, respectively.
- Finally, press [ENTER / RETURN].
+ Finally, press [ENTER / RETURN] or [SPACE].
The comet that has the number you entered as its answer will
@@ -247,6 +154,15 @@
or for players who cannot use a keyboard.
+ Advancing Waves
+ ---------------
+ When all the comets are destroyed for one wave, the player
+ advances to the next. The level of difficulty generally increases
+ with each level. On Training Academy lessons, the program
+ "learns" from the player to try to adjust the difficulty, and may
+ decrease if the player has lost one or more igloos (see below).
+
+
Losing An Igloo or City
-----------------------
The default setting is to play with igloo-dwelling penguins.
@@ -260,6 +176,7 @@
second hit destroys the city. If this seems too scary or violent,
please use the penguin/igloo theme!
+
Regaining Igloos/Cities
-----------------------
When a question is answered correctly, the player earns progress toward
@@ -270,31 +187,35 @@
bonus progress bar, and one of the igloos/cities will be rebuilt after
the current wave.
+
Ending The Game
---------------
+ The default mode is now to play through a defined list of
+ questions. This mode is used in the "Training Academy" games. For
+ "Custom" games, it can be selected by setting the config file
+ 'play_through_list' parameter to 1 ('yes' or 'true'), or via the
+ "--playthroughlist" command line argument. The list is generated
+ by TuxMath based on a series of selectable parameters (selected
+ math operations, number ranges, etc). By default, the questions
+ are asked in a random order. If answered correctly, they are
+ removed. A question that is not answered correctly (allowing the
+ comet to destroy its target) will reappear in random order. If
+ all questions are successfully answered before the igloos or
+ cities have been destroyed, the player wins and a "victory" screen
+ is displayed.
- The default mode is now to play through a defined list of questions. This
- mode is used in the "Training Academy" games. For "Custom" games, it can
- be selected by setting the config file 'play_through_list' parameter
- to 1 ('yes' or 'true'), or via the "--playthroughlist" command line argument.
- The list is generated by TuxMath based on a series of selectable parameters
- (selected math operations, number ranges, etc). By default, the questions
- are asked in a random order. If answered correctly, they are removed.
- A question that is not answered correctly (allowing the comet to destroy
- its target) will reappear in random order. If all questions are successfully
- answered before the igloos or cities have been destroyed, the player wins
- and a "victory" screen is displayed.
+ Arcade-style play is also supported, in which the game continues
+ until you lose all of your igloos or cities. A GAME OVER screen
+ is then displayed. If you use one of the standard Arcade games,
+ you'll have the opportunity to put your name in a high-score
+ table. For the "Custom" games, you can select this mode by
+ setting 'play_through_list' to '0' ('no', 'false', 'off').
- The older arcade-style mode is also supported, in which the game continues
- until you lose all of your igloos or cities. A GAME OVER screen is then
- displayed. For the "Custom" games, you can select this mode by setting
- 'play_through_list' to '0' ('no', 'false', 'off').
+ By pressing Esc or clicking on the red circle in the upper right
+ corner, you can quit the game.
- By pressing Esc or clicking on the red circle in the upper right corner, you
- can quit the game.
-
- Shortcut Keys
- -------------
+ Shortcut Keys
+ -------------
The following shortcuts are supported during game play:
'F10': switches between windowed and full-screen display mode.
@@ -302,15 +223,12 @@
Training Academy" lessons allow pausing, while the "Arcade"
games do not.
Up Arrow: increase speed by 20%, if allowed.
- Down Arrow: decrease speed by 20%, if allowed. Speed changes are allowed
- when pausing is enabled.
+ Down Arrow: decrease speed by 20%, if allowed. Speed changes
+ are allowed when pausing is enabled.
'Esc': leave current game and display the menu.
- Advancing Waves
- ---------------
-
Setting Game Options
--------------------
The "Options" system remains in need of an overhaul. For now, you can
@@ -318,22 +236,28 @@
to create a "Custom" game. At some point the "Custom" settings will be
modifiable from within TuxMath.
- 1. The program reads and writes the settings to disk in a human-readable
- fashion, where they can be modified with a text editor. The file is created
- in the user's home directory within a directory called ".tuxmath" and is
- simply called "options". As an example, a user "laura" on a Unix/Linux system
- would find this at /home/laura/.tuxmath/options. The file contains
- extensive comments describing all settings. By editing and saving this file,
- very extensive control over the program is supported, particularly with
- respect to generation of math questions. There really is no need to use
+ 1. The program reads and writes the settings to disk in a
+ human-readable fashion, where they can be modified with a text
+ editor. The file contains extensive comments describing all
+ settings. By editing and saving this file, very extensive control
+ over the program is supported, particularly with respect to
+ generation of math questions. There really is no need to use
command-line options any more.
- On a Windows XP or Windows 2000 system, the config file is called "options.txt"
- and is located at C:\Documents And Settings\USER\Application Data\TuxMath\options.txt,
- where USER is the login of the current user. Note that 'Application Data' is
+ On Unix/Linux (non-Mac): the file is created in the user's home
+ directory within a directory called ".tuxmath" and is simply called
+ "options". As an example, a user "laura" on a Unix/Linux system
+ would find this at /home/laura/.tuxmath/options.
+
+ On Macs: the file can be found under tuxmath/Contents/Resources.
+
+ On a Windows XP or Windows 2000 system, the config file is called
+ "options.txt" and is located at C:\Documents And
+ Settings\USER\Application Data\TuxMath\options.txt, where USER is
+ the login of the current user. Note that 'Application Data' is
hidden by default by the operating system.
- 2. Many command-line options are supported (see above).
+ 2. Many command-line options are supported (see below).
Setting Administrative Options
@@ -341,12 +265,13 @@
"Tux, of Math Command" allows parents/teachers to control whether the game
options can be changed by the player.
- The game options are first read from a master config file in the program's
- data directory (/usr/local/share/tuxmath/missions/options on *nix if installed
- using "make install"), then overridden by the user's own /.tuxmath/options
- file if "per_user_config" is selected in the master options file.
- If "per_user_config" is deselected, the game starts up with the master
- settings. (This is somewhat under construction).
+ The game options are first read from a master config file in the
+ program's data directory (/usr/local/share/tuxmath/missions/options
+ on *nix if installed using "make install"), then overridden by the
+ user's own /.tuxmath/options file if "per_user_config" is selected
+ in the master options file. If "per_user_config" is deselected, the
+ game starts up with the master settings. (This is somewhat under
+ construction).
Game Summary Files: Tracking Players' Performance
@@ -385,7 +310,7 @@
--------------------------
In some cases, the user's log-in name is not very informative: an
example is when schools use a single username "student" for all
- students in the school. It is possible to set up Tuxmath so that it
+ students in the school. It is possible to set up TuxMath so that it
asks students to "log in" (without any password) when they first
start the game. This will insure that all gold stars, options, and
game summary files will be stored in a location specific to each
@@ -587,6 +512,125 @@
Files."
+
+
+Command Line Options
+--------------------
+ NOTE: Tuxmath now has many pre-packaged "missions" (lessons), as well
+ as four arcade-style open-ended games of progressive difficulty, so
+ there is much less need to change settings. If desired, editing the
+ config file is a much better way to control the behavior of TuxMath
+ than the command-line options, for the most part. However, many
+ options are still supported.
+
+ Tips on running from the command line:
+
+ Linux:
+ -----
+ Just open a command prompt.
+
+ Windows:
+ -------
+ To be prompted for command line options, run tuxmath from the "Run" dialog
+ or the "C:> Command Prompt" console. Type "TuxMath.exe" followed by any
+ desired options (see below). If it does not run, make sure the full path
+ to the program (e.g. C:\Program Files\TuxMath\TuxMath.exe) is known to
+ Windows, either through Control Panel settings or by changing to the
+ directory containing TuxMath.exe before issuing the command.
+
+ MacOS:
+ -----
+ [ UNDER CONSTRUCTION ] Just double-click the "tuxmath" icon. ???
+ To be prompted for command line options (see below), hold the [OPTION] key
+ as you double-click the icon.
+
+
+ The following command-line options can be sent to the program:
+ --optionfile filename - play game based on settings in the named file (see
+ below for more on tuxmath config files). Tuxmath will
+ look for a valid config file with a matching name in
+ the following locations:
+ 1. current working directory
+ 2. as an absolute pathname
+ 3. in the missions directory with tuxmath's
+ other data files.
+ 4. in the user's tuxmath options directory
+ (e.g. /home/laura/.tuxmath/filename
+ 5. in the user's home directory.
+
+ --playthroughlist - Game consists of working through a list of questions
+ -r generated based on the selected options (or defaults).
+ If a comet strikes a city without being shot down by
+ the player, the question is reinserted into the list
+ in a random location. If the player answers all questions
+ correctly before the cities are destroyed, he/she wins.
+ If all cities get destroyed, the game ends in defeat.
+
+ --answersfirst - to ask questions in format: ? + num2 = num3 instead of
+ default format: num1 + num2 = ?.
+
+ --answersmiddle - to ask questions in format: num1 + ? = num3 instead of
+ default format: num1 + num2 = ?.
+
+ --fullscreen - Run the game in full screen, instead of in a window,
+ -f if possible.
+
+ --windowed - Run the game in a 640 x 480 window.
+ -w
+
+ --nosound - Do not play any sounds or music.
+ -s
+ --quiet
+ -q
+
+ --nobackground - Do not display photographic backgrounds in game.
+ -b (Useful on slower systems.)
+
+ --keypad - Display an on-screen numeric keypad. (Useful
+ -k for touch screens or in place of a physical keyboard.)
+
+ --operator OP - Add an operator to the game (will cause the program
+ -o OP to ignore saved option screen settings). You can
+ use this switch multiple times to run the game
+ with multiple operators.
+
+ Valid values for "OP" are:
+
+ add
+ subtract
+ multiply
+ divide
+
+ --demo - Demo mode. The game will cycle back and forth
+ -d between the title and the game, and it will
+ auto-play the game. The only user interaction
+ can be for quitting or pausing.
+
+ --allownegatives Allows subtraction answers to be less than zero.
+ -n When selected, the led numbers at the top of the
+ screen will include a fourth digit for the '-' sign.
+ Also, if --keypad is selected, the '-' and '+' may
+ be grayed-out depending if negatives are allowed.
+
+
+ These command-line options display useful information, but the program
+ does not attempt to start up in interactive mode.
+
+ --help - Display a short help message, explaining how to
+ -h play the game.
+
+ --usage - Display the available command-line options.
+ -u
+
+ --version - Display the version of "tuxmath" you're running.
+ -v
+
+ --copyright - Display copyright information
+ -c
+
+
+
+
License
-------
"Tux, of Math Command" is Free Software, distributable under the
More information about the Tux4kids-commits
mailing list