[gbrainy] Enhancements to the documentation, validates with xmllinit, and some fixes from Joe Dalton

[Jordi Mas <jmas src gnome org>]

commit 194b0986326c22dc773d0e801c7fec62c605fb29
Author: Jordi Mas <jmas softcatala org>
Date:   Tue Dec 29 17:01:22 2009 +0100

    Enhancements to the documentation, validates with xmllinit, and some fixes from Joe Dalton

 help/C/gametypes.page    |    2 +-
 help/C/history.page      |    2 +-
 help/C/index.page        |    8 ++++++--
 help/C/introduction.page |    2 +-
 help/C/playing.page      |   14 +++++++-------
 help/C/preferences.page  |    7 ++++---
 help/C/results.page      |    7 ++++---
 help/C/scoring.page      |    4 ++--
 8 files changed, 26 insertions(+), 20 deletions(-)
---
diff --git a/help/C/gametypes.page b/help/C/gametypes.page
index 3c36358..1eca37b 100644
--- a/help/C/gametypes.page
+++ b/help/C/gametypes.page
@@ -10,7 +10,7 @@
 <p><app>gbrainy</app> provides the following types of games:</p>
 <list>
 	<item><p>Logic puzzles. Games designed to challenge your reasoning and thinking skills. These games are based on sequences of elements, visual and spatial reasoning or relationships between elements.</p></item>
-	<item><p>Mental calculation. Games based on arithmetical operations designed to prove your mental calculation skills. Games that ask the player to use of multiplication, division, addition and subtraction combined in different ways.</p></item>
+	<item><p>Mental calculation. Games based on arithmetical operations designed to prove your mental calculation skills. Games that require the player to use multiplication, division, addition and subtraction combined in different ways.</p></item>
 	<item><p>Memory trainers. Games designed to challenge your short term memory. These games show collections of objects and ask the player to recall them, sometimes establishing relationships between figures, words, numbers or colors.</p></item>
 	<item><p>Verbal analogies. Games that challenge your verbal aptitude. Games that ask the player to identify cause and effect, use synonyms or antonyms, and use his vocabulary.</p></item>
 </list>
diff --git a/help/C/history.page b/help/C/history.page
index 87c3155..8ed89e1 100644
--- a/help/C/history.page
+++ b/help/C/history.page
@@ -11,6 +11,6 @@
 <media type="image" mime="image/png" src="figures/history.png"></media>
 <p>In this dialog the player can see how his performance has been evolving from every game type during the last recorded game sessions.</p>
 <p>By clicking on the <gui>Total</gui>, <gui>Logic</gui>, <gui>Memory</gui>, <gui>Mental Calculation</gui> and <gui>Verbal</gui> checkboxes the user can select which game types results are drawn on the player's game history graphic.</p>
-<p><app>gbrainy</app> saves the player game scores to be able to track player's score evolution. Using the <link type="topic" xref="preferences">Preferences</link> the user can select how many games sessions are recorded and how many games you have to play in order that the game gets stored. </p>
+<p><app>gbrainy</app> saves the player game scores to be able to track player's score evolution. Using the <link xref="preferences">Preferences</link> the user can select how many games sessions are recorded and how many games you have to play in order that the game gets stored. </p>
 
 </page>
diff --git a/help/C/index.page b/help/C/index.page
index cdb2da5..fe646aa 100644
--- a/help/C/index.page
+++ b/help/C/index.page
@@ -1,12 +1,16 @@
 <page xmlns="http://projectmallard.org/1.0/";
       type="guide"
       id="index">
-	<title>gbrainy Help</title>
-
 	<info>
+		<credit type="author">
+			<name>Jordi Mas i Hernandez</name>
+			<email>jmas softcatala org</email>
+		</credit>
 		<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
 	</info>
 
+	<title>gbrainy Help</title>
+
 	<section id="introduction" style="1column">
 	    <title>Introduction</title>
 	</section>
diff --git a/help/C/introduction.page b/help/C/introduction.page
index 64d9e5c..c0d8e97 100644
--- a/help/C/introduction.page
+++ b/help/C/introduction.page
@@ -7,7 +7,7 @@
 </info>
 <title>Introduction</title>
 <p><app>gbrainy</app> is a brain teaser game and trainer to have fun and to keep your brain trained. </p>
-<p>It features different <link type="topic" xref="gametypes">game types</link> like logic puzzles, mental calculation games, memory trainers and verbal analogies designed to test different cognitive skills. </p>
+<p>It features different <link xref="gametypes">game types</link> like logic puzzles, mental calculation games, memory trainers and verbal analogies designed to test different cognitive skills. </p>
 <p><app>gbrainy</app> relies heavily on the talent of previous puzzle masters ranging from classic puzzles from the ancient times to the ideas of more recent works like <link href="http://en.wikipedia.org/wiki/Terry_Stickels";>Terry Stickels</link> puzzles or the <link href="http://en.wikipedia.org/wiki/Dr._Brain";>Dr. Brain</link> classical game.</p>
 
 <p>The player can choose different difficulty levels making <app>gbrainy</app> enjoyable for kids, adults or senior citizens. It also features player's game history, player's personal records, tips for the player and fullscreen mode support. <app>gbrainy</app> can also be <link href="http://live.gnome.org/gbrainy/Extending";>extended</link> easily with new games developed by third parties.</p>
diff --git a/help/C/playing.page b/help/C/playing.page
index 13d4588..4049fda 100644
--- a/help/C/playing.page
+++ b/help/C/playing.page
@@ -10,9 +10,9 @@
 	<title>Starting a game</title>
 	<p>You can start a new game by clicking on the different buttons of the application toolbar.</p>
 	<media type="image" mime="image/png" src="figures/toolbar.png"></media>
-	<p>The following buttons are available:</p>	
+	<p>The following actions are associated to the buttons:</p>
 	<list>
-		<item><p><gui>All</gui>. Starts a new game playing all the available games.</p></item>
+		<item><p><gui>All</gui>. Starts a new game playing all the available game types.</p></item>
 		<item><p><gui>Logic</gui>. Starts a new game playing only logic games.</p></item>
 		<item><p><gui>Calculation</gui>. Starts a new game playing only calculation games.</p></item>
 		<item><p><gui>Memory</gui>. Starts a new game playing only memory games.</p></item>
@@ -22,9 +22,9 @@
 </section>
 
 <section id="during" style="1column">
-	<title>During the game</title>
+	<title>During the game session</title>
 
-	<p>The game starts by showing a puzzle to the user and making a question. Read always the instructions carefully. </p>
+	<p>The game session starts by showing a game and asking the user to solve it. Read always the instructions carefully. </p>
 
 	<p>At the bottom of the application (see the capture below) you have the main set of controls to interact with the game.</p>
 
@@ -32,10 +32,10 @@
 
 	<p>Once you know the answer you have to type it in the entry field next to the <gui>Answer:</gui> label.</p>
 
-	<p>Some puzzles include a tip that gives some guidance when trying to solve them. You can use the <gui>Tip</gui> button when it is enabled to get the tip.</p>
+	<p>Some games include a tip that gives some guidance when trying to solve them. You can use the <gui>Tip</gui> button when it is enabled to get the tip.</p>
 
-	<p>Once you have answered the puzzle you will be informed if you did provide the right answer. You can use the <gui>Next</gui> button to go to the next puzzle.</p>
+	<p>Once you have answered the game you will be informed if you did provide the right answer. You can use the <gui>Next</gui> button to go to the next game.</p>
 	
-	<p>You can pause the game using the <gui>Pause</gui> button and resume it later at any point.</p>
+	<p>You can pause the game session using the <gui>Pause</gui> button and resume it later at any point.</p>
 </section>
 </page>
diff --git a/help/C/preferences.page b/help/C/preferences.page
index 4eb39c3..22e75ec 100644
--- a/help/C/preferences.page
+++ b/help/C/preferences.page
@@ -11,7 +11,7 @@
 
 <section id="general" style="1column">
 	<title>General Settings</title>
-	<p>The <gui>Skip games that use colors</gui> option removes from the list of available games the games that use colors to challenge the player making it friendly to color blind users.</p>
+	<p>The <gui>Skip games that use colors</gui> option removes, from the list of available games, the games that use colors to challenge the player making it friendly to color blind users.</p>
 </section>
 
 <section id="difficulty" style="1column">
@@ -31,16 +31,17 @@
 	<p>These options affect the behaviour of memory games:</p>
 	<list>
 		<item><p><gui>Time in seconds to memorize the challenge</gui>. Establishes the time that a collection of objects is shown to allow the player to memorize it.</p></item>
-		<item><p><gui>Show countdown message</gui>. When checked shows the player a countdown message before every memory game. This is helpfully when playing different game types in a single game session because indicates to the user that should get ready to memorize the next game. Advanced players usually disable this option.</p></item>
+		<item><p><gui>Show countdown message</gui>. When checked shows the player a countdown message before every memory game. This is helpfully when playing different game types in a single game session because indicates to the user that should get ready for a memory game. Advanced players usually disable this option.</p></item>
 	</list>
 </section>
 
 <section id="history" style="1column">
     <title>Player's Game History</title>
+	<p>These options affect the behaviour of the player's game history:</p>
 	<list>
 		<item><p><gui>Minimum number of played games to store the game</gui>. Determines the number of games that a player should play in a game session to store it and make it available in the player's history.</p></item>
 		<item><p><gui>Maximum number of stored games in the player's history</gui>. Once this limit has been reach the result of the older games is removed to store the results of the new game sessions. </p></item>
-		<item><p><gui>Clear Player's Game History</gui>. Clears the player's history by removing all the previous recorded scores.</p></item>
+		<item><p><gui>Clear Player's Game History</gui>. Clears the player's game history by removing all the previous recorded sessions.</p></item>
 	</list>
 </section>
 
diff --git a/help/C/results.page b/help/C/results.page
index 8ad3fd0..6769cb2 100644
--- a/help/C/results.page
+++ b/help/C/results.page
@@ -7,9 +7,10 @@
 </info>
 
 <title>Results</title>
-<p>When you finish a game session <app>gbrainy</app> shows a summary of the results of the session.</p>
+<p>When the game session is finished <app>gbrainy</app> shows a summary of the results of the session.</p>
 <media type="image" mime="image/png" src="figures/results.png"></media>
-<p>The results shown here are computed using the <link type="topic" xref="scoring">scoring</link> algorithm that takes into account time used, tips and the number of total games.</p>
-<p>If the number of games played in the session are the minimum number defined in the preferences to store the session then the results of the game session are stored in the players' history.</p>
+<p>The results for every game type are computed using the <link xref="scoring">scoring</link> algorithm that takes into account time used, tips and the number of total games.</p>
+<p><app>gbrainy</app> keeps track of the player's personal records using the player's game history. If you have obtained a better score that in previous games for any of the game types, <app>gbrainy</app> informs that a new personal record has been set. Otherwise, general tips on how to improve when playing next games are given.</p>
+<p>If the number of games played during the session are minimum defined in the <link xref="preferences">Preferences</link> to store the session, then the results of the game session are recorded in the player's game history.</p>
 
 </page>
diff --git a/help/C/scoring.page b/help/C/scoring.page
index 58d25c3..297de64 100644
--- a/help/C/scoring.page
+++ b/help/C/scoring.page
@@ -15,7 +15,7 @@
 
 <section id="games" style="1column">
 	<title>Scoring individual games</title>
-	<p>If the player answers a game incorrectly it does not get any score for it. If the player answers the game correctly <app>gbrainy</app> scores the player considering the time used and if the played used the tip.</p>
+	<p>If the player answers a game incorrectly the player does not get any score for the answer. If the player answers the game correctly <app>gbrainy</app> scores the player considering the time used and if the played used a tip during the game.</p>
 
 	<p>When playing at medium difficulty level the player is expected to solve in the time indicated the following game types:</p>
 	<list>
@@ -38,7 +38,7 @@
 <section id="totals" style="1column">
 	<title>Computing the totals</title>
 	<p><app>gbrainy</app> keeps track of the different games types played. To compute the final score of every set of game types it sums all the results of the same game types played and then applies a factor based on the logarithm of 10 for the easy difficult level, 20 for the medium difficult level and 30 for master difficult level.</p>
-	<p>This means that to score 100% playing at medium difficult level you need to score 100% on at least 20 games of every game type played, 80 games in you have played all the games types.</p>. 	
+	<p>This means that when playing at medium difficult level to get a score of 100% you need to score 100% on at least 20 games of every game type played.</p>
 	<p>This may sound challenging but allows players to compare game scores from different sessions (in the player history) and allows to track better the progression of the player during all the games that has played.</p>
 </section>