Fix colobot/colobot#1293

Rework CodeBattles, add Builder and Trainer files

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "music"]
-	path = music
-	url = https://github.com/colobot/colobot-music.git

CMakeLists.txt

@@ -1,5 +1,13 @@
 cmake_minimum_required(VERSION 2.8)
 
+option(TRANSLATIONS "Enable translations of help and level files" ON)
+
+if(TRANSLATIONS)
+    find_package(PythonInterp 2.7 REQUIRED)
+else()
+    message(STATUS "Translations disabled; only English files will be installed")
+endif()
+
 if(NOT DEFINED COLOBOT_INSTALL_DATA_DIR)
     if(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
         set(COLOBOT_INSTALL_DATA_DIR ${CMAKE_INSTALL_PREFIX}/data CACHE PATH "Colobot shared data directory")
@@ -12,6 +20,7 @@ install(DIRECTORY ai         DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
 install(DIRECTORY fonts      DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
 install(DIRECTORY icons      DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
 install(DIRECTORY models     DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
+# install(DIRECTORY models-new DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
 install(DIRECTORY sounds     DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
 install(DIRECTORY textures   DESTINATION ${COLOBOT_INSTALL_DATA_DIR})
 install(DIRECTORY            DESTINATION ${COLOBOT_INSTALL_DATA_DIR}/mods) # Empty directory
@@ -22,6 +31,6 @@ set(DATA_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR})
 add_subdirectory(help)
 add_subdirectory(levels)
 
-if(EXISTS music)
+if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/music/CMakeLists.txt)
     add_subdirectory(music)
 endif()

Jenkinsfile

@@ -0,0 +1,40 @@
+#!/usr/bin/env groovy
+
+pipeline {
+    agent { label 'colobot-build' }
+    options {
+        buildDiscarder(logRotator(artifactDaysToKeepStr: '30', artifactNumToKeepStr: '5'))
+    }
+    stages {
+        stage('Check pull request target') {
+            when { changeRequest() }
+            steps {
+                script {
+                    if (env.CHANGE_TARGET == 'master') {
+                        throw "This pull request targets the wrong branch. Please reopen the pull request targetting the dev branch."
+                    }
+                }
+            }
+        }
+        stage('Build data') {
+            steps {
+                sh 'mkdir -p build'
+                dir('build') {
+                    sh '''
+                        cmake -DCMAKE_INSTALL_PREFIX=/install -DCOLOBOT_INSTALL_DATA_DIR=/install/data ..
+                        make
+                        rm -rf install
+                        DESTDIR=. make install
+                    '''
+                }
+            }
+        }
+
+        stage('Archive data') {
+            steps {
+                sh 'rm -f data.zip'
+                zip zipFile: 'data.zip', archive: true, dir: 'build/install'
+            }
+        }
+    }
+}

README.i18n.md

@@ -1,27 +1,37 @@
 # Colobot data translation
 
 The translation of Colobot level titles, level hierarchy and help files
-is managed through [gettext](https://www.gnu.org/software/gettext/).
+is managed through translation files (`*.pot` and `*.po`) as those generated by
+[gettext](https://www.gnu.org/software/gettext/). This is achieved by
+a set of Python scripts using [polib library](https://pypi.python.org/pypi/polib).
+
+The only requirement for generating translations is standard Python 2.7+ installation
+(polib library is bundled with other script files). If you don't have Python
+installed, nothing is generated and only English files are installed.
 
 ## Level scene description files
 
-Level scene description files have english headers that are used in the
+Level scene description files have English headers that are used in the
 Colobot interface to describe the levels. Level scene description files
-are levels/$level/scene.txt and translations are handled in the
-level-specific po/ directory: levels/$levels/po/. The .pot file is the
-source translation file, the *.po files are the translations.
+are `levels/$level/scene.txt` and translations are handled in the
+level-specific `po/` directory: `levels/$levels/po/`. The `*.pot` file is the
+source translation file, the `*.po` files are the translations.
 
 ## Help files
 
-Helpfiles are divided in two categories:
-* Generic helpfiles, about the game, the objects, the syntax, etc. These
-  are stored in help/ , in four sub-categories: generic, bots, object
-  and bots.
-* Level-specific helpfiles, about the level, instructions, example
-  programs, etc. These are stored in levels/$level/help/.
+Help files are divided in two categories:
+ * Generic help files, about the game, the objects, the syntax, etc. These
+   are stored in `help/`, in 5 sub-categories: generic, bots, object, programs
+   and cbots.
+ * Level-specific help files, about the level, instructions, example
+   programs, etc. are stored like `levels/$type/$chapterXxx/$levelYyy/help/`.
+    type beeing into : missions/freemissions/exercises/challenges & battles
+ * some generics are also stored into `levels/other`
 
-Helpfiles have their source in english, always stored in the E/
-subdirectory. Every other language directory is dynamically generated in the build process from files in level's po/ directory.
+
+Help files have their source in English, always stored in the `E/`
+subdirectory. Every other language directory is dynamically generated
+in the build process from files in level's `po/` directory.
 
 ## Colobot syntax
 

ai/lady01.txt

@@ -38,11 +38,12 @@ int object::WaspCount()
 	while ( true )
 	{
 		item = retobject(i++);
-		if ( item == null )  return total;
+		if ( item == null )  break;
 
 		if ( item.category == AlienWasp )
 		{
 			total ++;
 		}
 	}
+	return total;
 }

ai/lady02.txt

@@ -64,11 +64,12 @@ int object::AlienCount()
 	while ( true )
 	{
 		item = retobject(i++);
-		if ( item == null )  return total;
+		if ( item == null )  break;
 
 		if ( item.category == AlienAnt )
 		{
 			total ++;
 		}
 	}
+	return total;
 }

ai/tant1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	turn(90);
 	while (true)

ai/tant2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	object    item;
 	

ai/tant3.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	object    item;
 	

ai/tant4.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/tant5.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/tcell1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	grab();

ai/tcell2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/tchasse1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	aim(-3);
 	while ( true )

ai/tdragst.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	point  start;
 	start = position;  // remember starting position

ai/tevite.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	while ( true )
 	{

ai/texch1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	float dir;
 

ai/texch2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	float	dir, len;
 

ai/tfollow1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	while ( true )
 	{

ai/tfor.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	for ( int i=0 ; i<6 ; i=i+1 )  // repeat 6 times
 	{

ai/tfor2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	for ( int i=0 ; i<4 ; i=i+1 )  // repeat 4 times
 	{

ai/tlaby1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	object	front, left, right;
 

ai/tlaby2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	while ( true )
 	{

ai/tmove1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	move(20);  // go to checkpoint 1
 	turn(90);

ai/tmove2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	float  dist, dir;
 

ai/tmove3.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	float  dist, dir;
 

ai/tproc1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	Square(15);
 	Square(25);

ai/tproc2.txt

@@ -7,7 +7,7 @@ void object::Part(float length)
 	}
 }
 
-extern void object::Solution( )
+extern void object::Example( )
 {
 	float	rest = 25;
 	while ( rest > 0 )

ai/tprot1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	object	item;
 	float	dir, dist;

ai/tradar1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	while ( true )
 	{

ai/tremot4b.txt

@@ -29,7 +29,7 @@ public class exchange
 	}
 
 	// Delete an order.
-	synchronized void delete()
+	synchronized void remove()
 	{
 		m_order.m_type = nan;
 	}
@@ -63,6 +63,6 @@ extern void object::Slave4( )
 		{
 			message("Unknown order");
 		}
-		list.delete();
+		list.remove();
 	}
 }

ai/tremova1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	object  item;
 	point   dest;

ai/tremova2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	for ( int i=0 ; i<3 ; i=i+1 )
 	{

ai/tremova3.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	for ( int i=0 ; i<2 ; i=i+1 )
 	{

ai/tremova4.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	object  item;
 	point   dest;

ai/tsniff.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	for ( int y=0 ; y<6 ; y=y+1 )
 	{

ai/tspid1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	aim(0);

ai/tspid2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/tspid3.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/ttit1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	move(20);

ai/ttit2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/ttrap1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	while ( true )
 	{

ai/ttrap2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution( )
+extern void object::Example( )
 {
 	while ( true )
 	{

ai/twasp1.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

ai/twasp2.txt

@@ -1,4 +1,4 @@
-extern void object::Solution()
+extern void object::Example()
 {
 	
 	object    item;

help/CMakeLists.txt

@@ -1,28 +1,36 @@
 cmake_minimum_required(VERSION 2.8)
 
-include(../i18n-tools/CommonI18N.cmake)
-include(../i18n-tools/HelpI18N.cmake)
+include(../i18n-tools/I18NTools.cmake)
 
 set(HELP_INSTALL_DATA_DIR  ${COLOBOT_INSTALL_DATA_DIR}/help)
 
 ##
 # Add help category directory
 ##
-function(add_help_category help_category_dir install_dest_dir)
-    file(GLOB help_files RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} ${help_category_dir}/E/*.txt)
-    list(SORT help_files)
-    if(PO4A AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${help_category_dir}/po/)
-        generate_help_i18n(translated_help_dirs
-                           "${help_files}"
-                           ${help_category_dir}/po
-                           ${DATA_BINARY_DIR}/help-po/${help_category_dir})
-    else()
-        set(translated_help_dirs "")
+function(add_help_category help_category_dir install_subdir)
+
+    # Always install English files
+    file(GLOB english_help_files ${help_category_dir}/E/*)
+    install(FILES ${english_help_files} DESTINATION ${HELP_INSTALL_DATA_DIR}/E/${install_subdir})
+
+    # If translations are turned on, also generate translated files
+    if(TRANSLATIONS)
+        message(STATUS "Adding translation targets for help/${help_category_dir}")
+
+        set(work_dir ${DATA_BINARY_DIR}/help-po/${help_category_dir})
+        generate_translations(translated_help_files
+                              "help"
+                              ${CMAKE_CURRENT_SOURCE_DIR}
+                              ${help_category_dir}
+                              ${help_category_dir}/po
+                              ${work_dir}
+                              "${install_subdir}")
+
+        install_preserving_relative_paths("${translated_help_files}"
+                                          ${work_dir}
+                                          ${HELP_INSTALL_DATA_DIR})
     endif()
-    install(DIRECTORY ${help_category_dir}/E/ DESTINATION ${HELP_INSTALL_DATA_DIR}/E/${install_dest_dir})
-    foreach(translated_help_dir ${translated_help_dirs})
-        install(DIRECTORY ${DATA_BINARY_DIR}/help-po/${help_category_dir}/${translated_help_dir}/ DESTINATION ${HELP_INSTALL_DATA_DIR}/${translated_help_dir}/${install_dest_dir})
-    endforeach()
+
 endfunction()
 
 
@@ -30,3 +38,4 @@ add_help_category(bots "object")
 add_help_category(cbot "cbot")
 add_help_category(generic "")
 add_help_category(object "object")
+add_help_category(programs "programs")

help/bots/E/botbc.txt

@@ -0,0 +1,32 @@
+\b;\button 193; Tracked Builder
+\image botbc 8 8;
+Tracked bot equipped with a neutron gun.
+
+\button 196; Opens a build menu with the following options :
+\button 160;   \c;\l;BotFactory\u object\factory;       \n;Robot Factory
+\button 163;   \c;\l;ResearchCenter\u object\research;   \n;Research Center
+\button 168;   \c;\l;RadarStation\u object\radar;     \n;Radar
+\button 172;   \c;\l;ExchangePost\u object\exchange;     \n;Information Exchange Post
+\button 169;   \c;\l;RepairCenter\u object\repair;     \n;Repair Center
+\button 165;   \c;\l;DefenseTower\u object\tower;     \n;Defense Tower
+\button 166;   \c;\l;AutoLab\u object\labo;          \n;Organic Matter Analyzer 
+\button 164;   \c;\l;PowerStation\u object\station;     \n;Power Station
+\button 167;   \c;\l;PowerPlant\u object\energy;       \n;Power Cell Factory
+\button 170;   \c;\l;NuclearPlant\u object\nuclear;     \n;Nuclear Plant
+\button 162;   \c;\l;Converter\u object\convert;        \n;Titanium Converter
+\button 161;   \c;\l;Derrick\u object\derrick;          \n;Derrick
+\button 174;   \c;\l;PowerCaptor\u object\captor;      \n;Parabolic Lightning Conductor
+\button 175;   \c;\l;Vault\u object\safe;            \n;Vault
+
+Tracked bots can ascend steep inclinations but they are quite slow and use a lot of energy. On flat ground for short distances, a \l;wheeled builder\u object\botbr; is a better option. When it is possible to build \l;winged bots\u object\botbj;, these represent the best solution for long distances.
+
+\t;Programming
+To program the bot's movements, use the following commands : \c;\l;move\u cbot\move;\n;, \c;\l;turn\u cbot\turn;\n;, \c;\l;motor\u cbot\motor;\n;, \c;\l;goto\u cbot\goto;\n;.
+
+To program the neutron gun, use \c;\l;build\u cbot\build;\n;.
+
+\t;Object \l;Category\u cbot\category;
+\c;TrackedBuilder\n;
+
+\t;See also
+\l;CBOT Language\u cbot;, \l;Variables\u cbot\type; and \l;Categories\u cbot\category;.

help/bots/E/botbj.txt

@@ -0,0 +1,32 @@
+\b;\button 194; Winged Builder
+\image botbj 8 8;
+Jet propelled flying bot equipped with a neutron gun.
+
+\button 196; Opens a build menu with the following options :
+\button 160;   \c;\l;BotFactory\u object\factory;       \n;Robot Factory
+\button 163;   \c;\l;ResearchCenter\u object\research;   \n;Research Center
+\button 168;   \c;\l;RadarStation\u object\radar;     \n;Radar
+\button 172;   \c;\l;ExchangePost\u object\exchange;     \n;Information Exchange Post
+\button 169;   \c;\l;RepairCenter\u object\repair;     \n;Repair Center
+\button 165;   \c;\l;DefenseTower\u object\tower;     \n;Defense Tower
+\button 166;   \c;\l;AutoLab\u object\labo;          \n;Organic Matter Analyzer 
+\button 164;   \c;\l;PowerStation\u object\station;     \n;Power Station
+\button 167;   \c;\l;PowerPlant\u object\energy;       \n;Power Cell Factory
+\button 170;   \c;\l;NuclearPlant\u object\nuclear;     \n;Nuclear Plant
+\button 162;   \c;\l;Converter\u object\convert;        \n;Titanium Converter
+\button 161;   \c;\l;Derrick\u object\derrick;          \n;Derrick
+\button 174;   \c;\l;PowerCaptor\u object\captor;      \n;Parabolic Lightning Conductor
+\button 175;   \c;\l;Vault\u object\safe;            \n;Vault
+
+Winged bots can fly across natural obstacles such as mountains or lakes but their energy supply is used up quickly. They're slow on the ground. To cover a short distance that will not call for flying, it is recommended to use a \l;wheeled builder\u object\botbr; instead.
+
+\t;Programming
+To program the bot's movements, use the following commands : \c;\l;move\u cbot\move;\n;, \c;\l;turn\u cbot\turn;\n;, \c;\l;motor\u cbot\motor;\n;, \c;\l;jet\u cbot\jet;\n;, \c;\l;goto\u cbot\goto;\n;.
+
+To program the neutron gun, use \c;\l;build\u cbot\build;\n;.
+
+\t;Object \l;Category\u cbot\category;
+\c;WingedBuilder\n;
+
+\t;See also
+\l;CBOT Language\u cbot;, \l;Variables\u cbot\type; and \l;Categories\u cbot\category;.

help/bots/E/botbr.txt

@@ -0,0 +1,32 @@
+\b;\button 192; Wheeled Builder
+\image botbr 8 8;
+Wheeled bot equipped with a neutron gun.
+
+\button 196; Opens a build menu with the following options :
+\button 160;   \c;\l;BotFactory\u object\factory;       \n;Robot Factory
+\button 163;   \c;\l;ResearchCenter\u object\research;   \n;Research Center
+\button 168;   \c;\l;RadarStation\u object\radar;     \n;Radar
+\button 172;   \c;\l;ExchangePost\u object\exchange;     \n;Information Exchange Post
+\button 169;   \c;\l;RepairCenter\u object\repair;     \n;Repair Center
+\button 165;   \c;\l;DefenseTower\u object\tower;     \n;Defense Tower
+\button 166;   \c;\l;AutoLab\u object\labo;          \n;Organic Matter Analyzer 
+\button 164;   \c;\l;PowerStation\u object\station;     \n;Power Station
+\button 167;   \c;\l;PowerPlant\u object\energy;       \n;Power Cell Factory
+\button 170;   \c;\l;NuclearPlant\u object\nuclear;     \n;Nuclear Plant
+\button 162;   \c;\l;Converter\u object\convert;        \n;Titanium Converter
+\button 161;   \c;\l;Derrick\u object\derrick;          \n;Derrick
+\button 174;   \c;\l;PowerCaptor\u object\captor;      \n;Parabolic Lightning Conductor
+\button 175;   \c;\l;Vault\u object\safe;            \n;Vault
+
+Wheels constitute a standard, fast and energy-saving mode of propulsion, which is perfectly adapted for a relatively flat terrain. Whenever the terrain gets sloped, it is advised to use a \l;winged builder\u object\botbj; instead, or, if this is impossible, a \l;tracked builder\u object\botbc;.
+
+\t;Programming
+To program the bot's movements, use the following commands : \c;\l;move\u cbot\move;\n;, \c;\l;turn\u cbot\turn;\n;, \c;\l;motor\u cbot\motor;\n;, \c;\l;goto\u cbot\goto;\n;.
+
+To program the neutron gun, use \c;\l;build\u cbot\build;\n;.
+
+\t;Object \l;Category\u cbot\category;
+\c;WheeledBuilder\n;
+
+\t;See also
+\l;CBOT Language\u cbot;, \l;Variables\u cbot\type; and \l;Categories\u cbot\category;.

help/bots/E/botbs.txt

@@ -0,0 +1,32 @@
+\b;\button 195; Legged Builder
+\image botbs 8 8;
+Ant-legged creeping bot equipped with a neutron gun.
+
+\button 196; Opens a build menu with the following options :
+\button 160;   \c;\l;BotFactory\u object\factory;       \n;Robot Factory
+\button 163;   \c;\l;ResearchCenter\u object\research;   \n;Research Center
+\button 168;   \c;\l;RadarStation\u object\radar;     \n;Radar
+\button 172;   \c;\l;ExchangePost\u object\exchange;     \n;Information Exchange Post
+\button 169;   \c;\l;RepairCenter\u object\repair;     \n;Repair Center
+\button 165;   \c;\l;DefenseTower\u object\tower;     \n;Defense Tower
+\button 166;   \c;\l;AutoLab\u object\labo;          \n;Organic Matter Analyzer 
+\button 164;   \c;\l;PowerStation\u object\station;     \n;Power Station
+\button 167;   \c;\l;PowerPlant\u object\energy;       \n;Power Cell Factory
+\button 170;   \c;\l;NuclearPlant\u object\nuclear;     \n;Nuclear Plant
+\button 162;   \c;\l;Converter\u object\convert;        \n;Titanium Converter
+\button 161;   \c;\l;Derrick\u object\derrick;          \n;Derrick
+\button 174;   \c;\l;PowerCaptor\u object\captor;      \n;Parabolic Lightning Conductor
+\button 175;   \c;\l;Vault\u object\safe;            \n;Vault
+
+A moving legged builder uses up half as much energy as a \l;wheeled builder\u object\botbr;. A legged bot is also perfectly adapted to climb the steepest slopes.
+
+\t;Programming
+To program the bot's movements, use the following commands : \c;\l;move\u cbot\move;\n;, \c;\l;turn\u cbot\turn;\n;, \c;\l;motor\u cbot\motor;\n;, \c;\l;goto\u cbot\goto;\n;.
+
+To program the neutron gun, use \c;\l;build\u cbot\build;\n;.
+
+\t;Object \l;Category\u cbot\category;
+\c;LeggedBuilder\n;
+
+\t;See also
+\l;CBOT Language\u cbot;, \l;Variables\u cbot\type; and \l;Categories\u cbot\category;.

help/bots/E/botdraw.txt

@@ -0,0 +1 @@
+TODO

help/cbot/E/abstime.txt

@@ -1,5 +1,5 @@
 \b;Instruction \c;abstime\n;
-Syntax¦:
+Syntax:
 \s;\c;abstime ( );\n;
 
 Return the time in seconds elapsed since the beginning of the mission.

help/cbot/E/acos.txt

@@ -0,0 +1,12 @@
+\b;Instruction \c;acos\n;
+Syntax:
+\s;\c;acos ( value );\n;
+
+\t;value: \c;\l;float\u cbot\float;\n;
+Number between -1 and 1 (including both).
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Arcus cosine (in degrees) of the value.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/aim.txt

@@ -1,17 +1,20 @@
 \b;Instruction \c;aim\n;
-Syntax :
-\s;\c;aim ( angle );\n;
+Syntax:
+\s;\c;aim ( y, x );\n;
 
-This instruction sets the vertical angle of the cannon. The following robots are equipped with a cannon: 
+This instruction sets the vertical and the horizontal angle of the cannon. The following robots are equipped with a cannon: 
 o  \l;Shooter\u object\botfr;
 o  \l;Orga shooter\u object\botor;
 o  \l;Phazer shooter\u object\botphaz;
 
-When controlling the robot through programming, the only way to turn the gun left or right is to turn the whole robot with the instruction \c;\l;turn\u cbot\turn;\n;.
+When controlling the robot through programming, the gun can be also turned left or right by turning the whole robot with the instruction \c;\l;turn\u cbot\turn;\n;.
 
-\t;angle: \c;\l;float\u cbot\float;\n;
+\t;y: \c;\l;float\u cbot\float;\n;
 Angle in degrees of the gun relative to the robot. A positive value orients the gun upward. For shooters and orga shooters, the angle must range from \c;-20\n; to \c;+20\n; degrees. For phazer shooters, the angle must range from \c;-20\n; to \c;45\n; degrees.
 
+\t;x: \c;\l;float\u cbot\float;\n; (default value: \c;0\n;)
+Angle in degrees of the gun relative to the robot. A positive value orients the gun to the right. The angle must range from \c;-40\n; to \c;+40\n; degrees for all shooters.
+
 \t;Return value: \c;\l;int\u cbot\int;\n;
 Zero if everything is OK, a value different from zero if the rotation could not be performed: 
 \c;== 0 \n;The gun has now got the desired orientation

help/cbot/E/array.txt

@@ -4,7 +4,7 @@ An array is basically a collection of variables of the same type or class. You c
 \s;int    [ ] a;   // an array of int
 \s;int    a [12];  // an array of int limited to 12 elements
 \s;string s[3];    // an array of 3 strings
-\s;float  xy[][];  // an 2 dimensionnal array of floats
+\s;float  xy[][];  // a 2 dimensionnal array of floats
 \n;
 Actually when the CBOT interpreter encounters an array declaration, it just creates a \c;\l;null\u cbot\null;\n; \l;reference\u cbot\pointer;:
 \c;
@@ -13,7 +13,7 @@ Actually when the CBOT interpreter encounters an array declaration, it just crea
 As soon as you put values into the array, the elements are created and the reference is initialized:
 \c;
 \s;a[2] = 213;  // a points to
-\s;             // 3 élements [0], [1] et [2]
+\s;             // 3 elements [0], [1] et [2]
 \n;
 After this operation, \c;a\n; contains a reference to the elements of the array. Elements \c;[0]\n; and \c;[1]\n; are created but not initialized because an array cannot contain empty elements. The \c;\l;sizeof\u cbot\sizeof;\n; instruction allows you to obtain the number of elements contained in an array.
 
@@ -27,5 +27,16 @@ When an array is declared with a maximum size, the program will stop as soon as
 \n;
 If you pass an array as parameter to a \l;function\u cbot\function;, the function only receives a \l;reference\u cbot\pointer; to the array. That means if you modify an array element in the function, the element of the array that has been passed the function will be actuallay modified.
 
+\b;Initialization syntax
+You can initialize a new array using the following syntax:
+\c;
+\s;type arrayName[] = { value0, value1, value2, ..., valueN };
+\n;
+Examples:
+\c;
+\s;int numbers[] = { 10, 20, 30 };
+\s;MyClass objects[] = { new MyClass(1), new MyClass(2) };
+\n;
+
 \t;See also
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/asin.txt

@@ -0,0 +1,12 @@
+\b;Instruction \c;asin\n;
+Syntax:
+\s;\c;asin ( value );\n;
+
+\t;value: \c;\l;float\u cbot\float;\n;
+Number between -1 and 1 (including both).
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Arcus sine (in degrees) of the value.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/atan.txt

@@ -0,0 +1,12 @@
+\b;Instruction \c;atan\n;
+Syntax:
+\s;\c;atan ( value );\n;
+
+\t;value: \c;\l;float\u cbot\float;\n;
+Number.
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Arcus tangent (in degrees) of the value.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/atan2.txt

@@ -0,0 +1,17 @@
+\b;Instruction \c;atan2\n;
+Syntax:
+\s;\c;atan2 ( y, x );\n;
+
+The purpose of using two arguments instead of one is to gather information on the signs of the inputs in order to return the appropriate quadrant of the computed angle, which is not possible for the single-argument \c;\l;atan();\u cbot\atan;\n; function. For example, consider a point \c;(-1, -1)\n;: \c;atan(-1/-1);\n; is \c;45.00\n; degrees, whereas \c;atan2(-1, -1);\n; is \c;-135.00\n; degrees, which is obviously more correct in this case.
+
+\t;y: \c;\l;float\u cbot\float;\n;
+Number.
+
+\t;x: \c;\l;float\u cbot\float;\n;
+Number.
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Arcus tangent (in degrees) of \c;y/x\n;.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/build.txt

@@ -0,0 +1,28 @@
+\b;Instruction \c;build\n;
+The instruction \c;build();\n; instructs the bot to build a building of the given \l;category\u cbot\category;. Currently works for \l;Grabbers\u object\botgc;, \l;Me\u object\human; and \l;Tech\u object\tech;.
+
+\b;Basic use
+This command is mostly useful in an attempt to build a fully automatised base, where an \l;astronaut\u object\human; does not need to do anything except starting a program and watching bots working. What is more, it makes beating the game by using only programming a possible task (however, it is a challenge rather for experienced gamers, who beat the whole game at least once).
+
+Here is an example of a program that looks for the nearest \l;titanium cube\u object\titan;, goes to the position and builds a \l;bot factory\u object\factory;.
+\c;
+\s; \l;object\u cbot\object; item = \l;radar\u cbot\radar;(\l;Titanium\u object\titan;);
+\s; \l;goto\u cbot\goto;(item.position);
+\s; build(\l;BotFactory\u object\factory;);
+\n;
+\b;For specialists
+Syntax:
+\s;\c;build ( cat );\n;
+
+Tells the robot to build a building using a titanium cube placed on a flat ground nearby.
+
+\t;cat: \c;\l;int\u cbot\int;\n;
+\l;Category\u cbot\category; of a building.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;build()\n;.
+\c;== 0 \n;Successfully built
+\c;!= 0 \n;Impossible to build (for example, the nearest titanium cube is too far away or the specified building is not available in the mission)
+
+\t;See also
+\l;canbuild\u cbot\canbuild;, \l;buildingenabled\u cbot\buildingenabled;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/buildingenabled.txt

@@ -0,0 +1,23 @@
+\b;Instruction \c;buildingenabled\n;
+The instruction \c;buildingenabled();\n; lets you know if a building of the given \l;category\u cbot\category; can be built in the level.
+
+\b;Basic use
+It is similar to the \c;\l;canbuild();\u cbot\canbuild;\n; instruction. However, it does not check if a required research has been done.
+\c;
+\s; \l;if\u cbot\if; (buildingenabled(\l;BotFactory\u object\factory;))
+\s; {
+\s; 	build(\l;BotFactory\u object\factory;);
+\s; }
+\n;
+\b;For specialists
+Syntax:
+\s;\c;buildingenabled ( cat );\n;
+
+\t;cat: \c;\l;int\u cbot\int;\n;
+\l;Category\u cbot\category; of a building.
+
+\t;Return value: \c;\l;bool\u cbot\bool;\n;
+\c;true\n; if the building can be built in the level even if required research has not been done, \c;false\n; otherwise.
+
+\t;See also
+\l;build\u cbot\build;, \l;canbuild\u cbot\canbuild;, \l;ResearchCenter\u object\research;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/busy.txt

@@ -0,0 +1,15 @@
+\b;Instruction \c;busy\n;
+Syntax:
+\s;\c;\l;object\u cbot\object;.busy ( );\n;
+
+Checks if the object is busy.
+
+\t;\l;object\u cbot\object;
+Any building which can take some action (e.g. \l;Converter\u cbot\convert;).
+
+\t;Return value: \c;\l;bool\u cbot\bool;\n;
+\c;\const;true\norm;\n; if the object is doing something (e.g. converting)
+\c;\const;false\norm;\n; if the object is not doing anything
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/canbuild.txt

@@ -0,0 +1,23 @@
+\b;Instruction \c;canbuild\n;
+The instruction \c;canbuild();\n; lets you know if \l;Grabbers\u object\botgc;, \l;Me\u object\human; or \l;Tech\u object\human; can build a building of the given \l;category\u cbot\category;. 
+
+\b;Basic use
+It helps to prevent errors in programs using the \c;\l;build();\u cbot\build;\n; instruction. Here is an example:
+\c;
+\s; \l;if\u cbot\if; (canbuild(\l;BotFactory\u object\factory;))
+\s; {
+\s; 	build(\l;BotFactory\u object\factory;);
+\s; }
+\n;
+\b;For specialists
+Syntax:
+\s;\c;canbuild ( cat );\n;
+
+\t;cat: \c;\l;int\u cbot\int;\n;
+\l;Category\u cbot\category; of a building.
+
+\t;Return value: \c;\l;bool\u cbot\bool;\n;
+\c;true\n; if the building can be built, \c;false\n; otherwise.
+
+\t;See also
+\l;build\u cbot\build;, \l;buildingenabled\u cbot\buildingenabled;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/canresearch.txt

@@ -0,0 +1,15 @@
+\b;Instruction \c;canresearch\n;
+Syntax:
+\s;\c;canresearch ( research );\n;
+
+Checks if the \l;research\u cbot\researches; can be done in the level.
+
+\t;research: \c;\l;int\u cbot\int;\n;
+\l;Research name\u cbot\researches;.
+
+\t;Return value: \c;\l;bool\u cbot\bool;\n;
+\const;true\norm; if the research can be done (even if it is already done, to check that, use the \l;researched\u cbot\researched; instruction)
+\const;false\norm; if the research cannot be done
+
+\t;See also
+\l;Research names\u cbot\researches;, \l;research\u cbot\research;, \l;researched\u cbot\researched;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/category.txt

@@ -1,13 +1,13 @@
 \b;Value \c;Categories\n;
 Categories represent the names of objects in the CBOT language. Everything in COLOBOT is an object: robots, buildings, raw materials, etc., even yourself.
 
-In a program, categories are always displayed on a \const;red background\norm;. If a category isn't highlighted in red, it is misspelled. Caps and lower cases should be kept as is.
+In a program, categories are always displayed like that: \const;category\norm;. If a category isn't highlighted, it is misspelled. Caps and lower cases should be kept as is.
 
-Below are the different categories available :
+Below are the different categories available:
 
-\t;Buildings :
+\t;Buildings:
 
-\button 176;   \c;\l;Houston\u object\Huston;          \n;Mission Control
+\button 176;   \c;\l;Houston\u object\huston;          \n;Mission Control
 \button 171;   \c;\l;SpaceShip\u object\base;        \n;Spaceship
 \button 160;   \c;\l;BotFactory\u object\factory;       \n;Robot Factory
 \button 163;   \c;\l;ResearchCenter\u object\research;   \n;Research Center
@@ -25,10 +25,11 @@ Below are the different categories available :
 \button 175;   \c;\l;Vault\u object\safe;            \n;Vault
        \c;\l;StartArea\u object\start;        \n;Starting Pad
        \c;\l;GoalArea\u object\goal;         \n;Finishing Pad
+       \c;\l;Target1\u object\target1;          \n;Flying target
        \c;\l;AlienNest\u object\nest;        \n;Alien Nest
 
 
-\t;Portable Objects :
+\t;Portable Objects:
 
        \c;\l;TitaniumOre\u object\titanore;          \n;Titanium Ore
        \c;\l;UraniumOre\u object\uranore;           \n;Uranium Ore
@@ -41,7 +42,7 @@ Below are the different categories available :
        \c;\l;KeyA..D\u object\key;              \n;Keys A, B, C and D
 
 
-\t;Robots :
+\t;Robots:
 
 \button 158;   \c;\l;PracticeBot\u object\bottr;            \n;Practice Bot
 \button 173;   \c;\l;TargetBot\u object\bottarg;              \n;Target Bot
@@ -66,6 +67,11 @@ Below are the different categories available :
 \button 155;   \c;\l;WingedOrgaShooter\u object\botoj;      \n;Winged Orga Shooter
 \button 156;   \c;\l;LeggedOrgaShooter\u object\botos;      \n;Legged Orga Shooter
 
+\button 192;   \c;\l;WheeledBuilder\u object\botbr;         \n;Wheeled Builder
+\button 193;   \c;\l;TrackedBuilder\u object\botbc;         \n;Tracked Builder
+\button 194;   \c;\l;WingedBuilder\u object\botbj;          \n;Winged Builder
+\button 195;   \c;\l;LeggedBuilder\u object\botbs;          \n;Legged Builder
+
 \button 149;   \c;\l;Subber\u object\botsub;                 \n;Subber
 \button 148;   \c;\l;Recycler\u object\botrecy;               \n;Recycler
 \button 157;   \c;\l;Shielder\u object\botshld;               \n;Shielder
@@ -73,7 +79,7 @@ Below are the different categories available :
 \button 147;   \c;\l;PhazerShooter\u object\botphaz;          \n;Phazer Shooter
 
 
-\t;Enemies :
+\t;Enemies:
 
        \c;\l;AlienQueen\u object\mother;         \n;Alien Queen
        \c;\l;AlienEgg\u object\egg;           \n;Alien Egg
@@ -83,7 +89,7 @@ Below are the different categories available :
        \c;\l;AlienWorm\u object\worm;          \n;Worm
 
 
-\t;Miscellaneous :
+\t;Miscellaneous:
 
 \button 136;   \c;\l;Me\u object\human;              \n;You!
        \c;\l;Mine\u object\mine;            \n;Mine
@@ -92,7 +98,7 @@ Below are the different categories available :
        \c;\l;Ruin\u object\ruin;            \n;Derelict building
 
 
-\t;Flags and Other Indicators :
+\t;Flags and Other Indicators:
 
        \c;\l;BlueFlag\u object\flag;          \n;Blue Flag
        \c;\l;RedFlag\u object\flag;           \n;Red Flag
@@ -100,9 +106,10 @@ Below are the different categories available :
        \c;\l;YellowFlag\u object\flag;        \n;Yellow Flag
        \c;\l;VioletFlag\u object\flag;        \n;Violet Flag
        \c;\l;WayPoint\u object\waypoint;          \n;Checkpoint
-       \c;\l;EnergySite\u object\enerspot;        \n;Underground Energy Deposit
-       \c;\l;TitaniumSite\u object\stonspot;      \n;Underground Titanium Deposit
-       \c;\l;UraniumSite\u object\uranspot;       \n;Underground Uranium Deposit
+       \c;\l;Target2\u object\target2;           \n;Flying checkpoint
+       \c;\l;PowerSpot\u object\enerspot;        \n;Underground Energy Deposit
+       \c;\l;TitaniumSpot\u object\stonspot;      \n;Underground Titanium Deposit
+       \c;\l;UraniumSpot\u object\uranspot;       \n;Underground Uranium Deposit
 
 \t;See also
 \l;CBOT Language\u cbot; and \l;Variables\u cbot\type;.

help/cbot/E/ceil.txt

@@ -0,0 +1,13 @@
+\b;Instruction \c;ceil\n;
+Syntax:
+\s;\c;ceil ( value );\n;
+Rounds up a number.
+
+\t;value: \c;\l;float\u cbot\float;\n;
+Number.
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Ceiling of the value, i.e. the smallest integer not less than \c;value\n;. For example, \c;ceil(2.1)\n; is \c;3.0\n;.
+
+\t;See also
+\l;round\u cbot\round;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/class.txt

@@ -1,72 +1,122 @@
 \b;Instruction \c;class\n;
-This allows you to declare a class definition using following syntax:
+This keyword allows you to create a class definition by using the following syntax:
 \c;
 \s;public class ClassName
 \s;{
 \s;	declarations;
 \s;}
 \n;
-Classes can only be \l;public\u cbot\public;, that is they can be used from all bots in a mission. Class members are also public, that is they are accessible from outside the class. Class members can be fields or functions (also called methods), for example the followin class \c;MyClass\n; contains 4 fields (a, b, x and s) and one method (MyFunction).
+\t;All Classes Are Public
+Classes can be only \l;public\u cbot\public;. This means that they can be used by all bots in a mission.
+
+\b;Class Members
+Class members are fields (\l;variables\u cbot\var;) and methods (\l;functions\u cbot\function;).
+
+For example, the following class dubbed \c;MyClass\n; contains 4 fields (\c;a\n;, \c;b\n;, \c;x\n; and \c;s\n;) and one method (\c;MyFunction\n;).
 \c;
 \s;public class MyClass
 \s;{
 \s;	int     a, b;
 \s;	float   x = 3.33;
 \s;	string  s = "hello";
-\s;	float   MyFunction( float value )
+\s;	float   MyFunction(float value)
 \s;	{
-\s;		return (value*x)-1;
+\s;		return (value * x) - 1;
 \s;	}
 \s;}
 \n;
-As shown in this exemple the class members can be initialized (\c;x=3.33\n;). You can also define a constructor which is a special method having the same name as the class name. This method will be called automatically at creation time of a class instance. You can also declare more than one method with the same name but different parameters.
+\b;Accessing Class Members
+Class members can be accessed outside of the class definition by using the \c;.\n; operator. Example:
 \c;
 \s;public class MyClass
 \s;{
+\s;	int myField = 0;
+\s;	int MyFunction()
+\s;	{
+\s;		return myField * 2;
+\s;	}
+\s;}
+\s;
+\s;extern void object::Test()
+\s;{
+\s;	MyClass myObject();
+\s;	myObject.myField = 10;
+\s;	message(myObject.MyFunction()); // 20
+\s;	MyClass mySecondObject();
+\s;	mySecondObject.myField = myObject.myField - 2;
+\s;	message(mySecondObject.MyFunction()); // 16
+\s;}
+\n;
+Class members are \l;public\u cbot\public; by default, which means that they are accessible outside of the class definition. They can also be declared as \c;\l;private\u cbot\private;\n; or \c;\l;protected\u cbot\protected;\n;. Such members can only be accessed inside of the class definition.
+
+\t;Class Members Modifiers
+Fields and methods can also be declared as \c;\l;static\u cbot\static;\n;. Methods can be additionaly declared as \c;\l;synchronized\u cbot\synchro;\n;.
+
+\t;Member Initialization
+As shown in the previous example, the class members can be initialized in the class definition (\c;int x = 3.33;\n;).
+
+Another way of initiliazing fields is by defining a constructor which is a special method having the same name as the class. This method will be called automatically at \l;creation\u cbot\new; time of a class instance. Constructors can be \l;overloaded\u cbot\function;.
+
+Example:\c;
+\s;public class MyClass
+\s;{
 \s;	int  a, b;
-\s;	void MyClass( )
+\s;	void MyClass()
 \s;	{
 \s;		a = 2;  b = 3;
 \s;	}
-\s;	void MyClass( int a, int b )
+\s;	void MyClass(int a, int b)
 \s;	{
 \s;		this.a = a;  this.b = b;
 \s;	}
 \s;}
 \n;
-In this example two constructors are declared for \c;MyClass\n;, one without parameters and the other one with two parameters. As the names of the parameters of the second constructor are the same as the names of the two members \c;a\n; et \c;b\n; we must use the \c;\l;this\u cbot\this;.a\n; and \c;\l;this\u cbot\this;.b\n; to avoid confusion with the parameters. Another more simpler solution would be to give different names to the parameters.
+
+\t;Using \c;\l;this\u cbot\this;\n;
+As the names of the parameters of the second constructor are the same as the names of the two members \c;a\n; and \c;b\n;, we must use the \c;\l;this\u cbot\this;\n; \l;reference\u cbot\pointer; to avoid confusion with the parameters' names.
+
+\b;Object Creation
+You can create objects of type \c;YourClass\n; using the \c;\l;new\u cbot\new;\n; keyword. Example:
 \c;
-\s;void Test( )
+\s;extern void object::Test()
 \s;{
-\s;	MyClass item1();      // constr. w/o parameters
-\s;	MyClass item2(4, 5);  // constr. with 2 parameters
-\s;	MyClass item3;        // no constructor called,
-\s;                          // therefore item3 == null
+\s;	MyClass object1();       // Call default constructor (without parameters)
+\s;	MyClass object2(4, 5);   // Call constructor with two int parameters
+\s;	MyClass object3;         // No constructor called, object3 == null
+\s;	object3 = new MyClass(); // We call constructor now, object3 != null
 \s;}
 \n;
-You can also define a destructor. This must be a \c;void\n; fonction without parameters that has the same name as the class name but prefixed by the ~ character. The destructor is called automatically as soon as the class instance is no more referenced by anyone.
+
+\b;Object Destruction
+You can also define a destructor. This must be a \c;\l;void\u cbot\void;\n; fonction without parameters, which has the same name as the class but prefixed with the \c;~\n; character. The destructor is called automatically as soon as the class instance is no more referenced by anyone. Example:
 \c;
 \s;public class MyClass
 \s;{
 \s;	static private int counter = 0; // instance counter
 \s;	void  MyClass( )
 \s;	{
-\s;		counter ++;  // one instance more
+\s;		counter++;  // one instance more
 \s;	}
 \s;	void ~MyClass( )
 \s;	{
-\s;		counter --;  // one instance less
+\s;		counter--;  // one instance less
 \s;	}
 \s;}
-\s;void Test()
+\s;extern void object::Test()
 \s;{
-\s;	MyClass item1( );  // counter = 1
-\s;	MyClass item2( );  // counter = 2
-\s;	item1 = null;      // counter = 1
-\s;}                      // counter = 0
+\s;	                   // counter == 0
+\s;	MyClass item1( );  // counter == 1
+\s;	MyClass item2( );  // counter == 2
+\s;	item1 = null;      // counter == 1
+\s;}
+\s;// counter == 0
 \n;
-If you pass a class instance as parameter to a \l;function\u cbot\function;, the function only receives a \l;reference\u cbot\pointer; to the instance. That means if you modify the instance in the function, the instance that has been passed to the function will be actuallay modified.
+\b;Passing Objects to Functions
+Objects in CBOT are passed by \l;reference\u cbot\pointer;. This means that when an object is passed to a \l;function\u cbot\function;, the function receives a copy of a pointer to the instance, not a copy of the object, so any modifications on the object will be visible outside of the function.
+
+\b;Inheritance
+A class can inherit public and protected members of another class by using the \c;\l;extends\u cbot\extends;\n; keyword.
 
 \t;See also
-\c;\l;public\u cbot\public;\n;, \c;\l;private\u cbot\private;\n;, \c;\l;static\u cbot\static;\n;, \c;\l;synchronized\u cbot\synchro;\n;, \c;\l;new\u cbot\new;\n;, \c;\l;reference\u cbot\pointer;\n;, \c;\l;this\u cbot\this;\n;
+\c;\l;public\u cbot\public;\n;, \c;\l;private\u cbot\private;\n;, \c;\l;protected\u cbot\protected;\n;, \c;\l;static\u cbot\static;\n;, \c;\l;synchronized\u cbot\synchro;\n;, \c;\l;new\u cbot\new;\n;, \c;\l;reference\u cbot\pointer;\n;, \c;\l;this\u cbot\this;\n;, \c;\l;super\u cbot\super;\n;, \c;\l;extends\u cbot\extends;\n;
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/close.txt

@@ -1,5 +1,5 @@
 \b;Instruction \c;close\n;
-Close a file opened previously with \c;\l;open\u cbot\open;\n;. This is a method of the \c;\l;file\u cbot\file;\n; class; therefore you cannot write  \c;close()\n; but only \c;handle.close()\n;¦:
+Close a file opened previously with \c;\l;open\u cbot\open;\n;. This is a method of the \c;\l;file\u cbot\file;\n; class; therefore you cannot write  \c;close()\n; but only \c;handle.close()\n;:
 \c;
 \s;	handle.close();
 \n;

help/cbot/E/colors.txt

@@ -0,0 +1,28 @@
+\b;Value \c;Colors\n;
+Color names are used to define a specific color to use. They can be passed to functions like \l;pendown\u cbot\pendown; or \l;pencolor\u cbot\pencolor;.
+
+In a program, colors are always displayed on a \const;red background\norm;. If a color isn't highlighted in red, it is misspelled. Caps and lower cases should be kept as is.
+
+Below are the different colors available:
+
+\c;\const;White\norm;\n;
+\c;\const;Black\norm;\n;
+\c;\const;Gray\norm;\n;
+\c;\const;LightGray\norm;\n;
+\c;\const;Red\norm;\n;
+\c;\const;Pink\norm;\n;
+\c;\const;Purple\norm;\n;
+\c;\const;Orange\norm;\n;
+\c;\const;Yellow\norm;\n;
+\c;\const;Beige\norm;\n;
+\c;\const;Brown\norm;\n;
+\c;\const;Skin\norm;\n;
+\c;\const;Green\norm;\n;
+\c;\const;LightGreen\norm;\n;
+\c;\const;Blue\norm;\n;
+\c;\const;LightBlue\norm;\n;
+
+You can also draw colored symbols:
+
+\c;\const;BlackArrow\norm;\n;
+\c;\const;RedArrow\norm;\n;

help/cbot/E/cond.txt

@@ -1,29 +1,5 @@
 \b;Conditions
 A condition is a special \l;expression\u cbot\expr; that returns a \l;boolean\u cbot\bool; value, that can only be either \c;\l;true\u cbot\true;\n; or \c;\l;false\u cbot\false;\n;. With a condition, you can choose f. ex. if the instructions in a \c;\l;while\u cbot\while;\n; loop must be repeated again, or if the instruction in a \c;\l;if\u cbot\if;\n; bloc must be executed.
-Here are some operators that you can use in conditions to compare two values :
-
-\c;a == b  \n;\c;a\n; equals \c;b\n;
-\c;a != b  \n;\c;a\n; is different from \c;b\n;
-\c;a <  b  \n;\c;a\n; smaller than \c;b\n;
-\c;a <= b  \n;\c;a\n; smaller than or equal to \c;b\n;
-\c;a >  b  \n;\c;a\n; greater than \c;b\n;
-\c;a >= b  \n;\c;a\n; greater than or equal to \c;b\n;
-
-For example :
-
-\c;12 == 12  \n;returns true
-\c;45 != 47  \n;returns true 
-\c;99 == 98  \n;returns false
-\c;12 <  -1  \n;returns false
-\c;12 >= 10  \n;returns true 
-\c;12 >= 12  \n;returns true 
-
-\t;Remarque
-Be careful not to confuse the equality comparison \c;==\n; with the assignment of a \l;variable\u cbot\var; \c;=\n;.
-
-\c;a == b\n; is an expression that compares \c;a\n; with \c;b\n;.
-\c;a = b\n; is an expression that copies the value of \c;b\n; into \c;a\n;.
 
 \t;See also
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.
-

help/cbot/E/cos.txt

@@ -0,0 +1,12 @@
+\b;Instruction \c;cos\n;
+Syntax:
+\s;\c;cos ( angle );\n;
+
+\t;angle: \c;\l;float\u cbot\float;\n;
+Angle in degrees.
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Cosine of the angle.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/deletef.txt

@@ -1,9 +1,9 @@
 \b;Instruction \c;deletefile\n;
 The deletefile instruction deletes an existing file in the files/ folder. 
 
-Files can only be deleted in the files/ folder which is located in the folder where Colobot has been installed. You cannot not delete files that are located elsewhere than in the files/ folder.
+Files can only be deleted in the files/ folder which is located in the folder inside Colobot save directory. You cannot not delete files that are located elsewhere than in the files/ folder.
 
-Syntax¦:
+Syntax:
 \s;\c;deletefile ( filename );\n;
 
 \t;See also

help/cbot/E/delinfo.txt

@@ -1,11 +1,11 @@
 \b;Instruction \c;deleteinfo\n;
-Syntax¦:
+Syntax:
 \s;\c;deleteinfo ( name, power );\n;
 
 Delete an existing information in the closest \l;information exchange post\u object\exchange;.
 
 \t;name: \c;string\n;
-Name of the information to be deleted. This name is a string: it must be written in quotation marks "¦".
+Name of the information to be deleted. This name is a string: it must be written in quotation marks "".
 
 \t;power: \c;float\n;
 Power of the transmitter, which corresponds to the maximal distance between the sender and the exchange post. If the distance is longer, the information won't be deleted. Default value is 10 metres.

help/cbot/E/destroy.txt

@@ -0,0 +1,16 @@
+\b;Instruction \c;destroy\n;
+Syntax:
+\s;\c;\l;object\u cbot\object;.destroy ( );\n;
+
+Destroys an object.
+
+\t;\l;object\u cbot\object;
+\l;Destroyer\u object\destroy;.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;destroy()\n;.
+\c;== 0 \n;The operation of destroying of an object was started
+\c;!= 0 \n;The instruction could not be done (e.g. nothing to destroy)
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/detect.txt

@@ -0,0 +1,28 @@
+\b;Instruction \c;detect\n;
+With the instruction \c;detect();\n;, you can look for objects like \l;enemies\u object\mother;, bots, buildings or raw materials, which are in front of the bot. It is a simpler version of \c;\l;radar\u cbot\radar;();\n;.
+
+\b;For specialists
+Syntax:
+\s;\c;detect ( cat );\n;
+
+Detects the nearest object of the specified \l;category\u cbot\category; being in front of the bot. It is similar to the following instruction:
+\s;\c;radar(cat, 0, 45, 0, 20);\n;
+
+\t;cat: \c;\l;int\u cbot\int;\n;
+o \l;Category\u cbot\category; of the objects that should be detected. For example, when you are looking for an ant, write \c;radar(AlienAnt)\n;. 
+o \l;Array\u cbot\array; of categories of the objects that should be detected. For example, when you are looking only for grabbers:\c;
+\s;int bots[4];
+\s;bots[0] = WheeledGrabber;
+\s;bots[1] = TrackedGrabber;
+\s;bots[2] = WingedGrabber;
+\s;bots[3] = LeggedGrabber;
+\s;object nearestGrabber = radar(bots);
+\n;
+o Keyword \const;Any\norm; if you are looking for any object (including even plants and so on).
+
+\t;Return value: \c;\l;bool\u cbot\bool;\n;
+\const;true\norm; if the object was found
+\const;false\norm; if the object was not found
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/eof.txt

@@ -1,9 +1,9 @@
 \b;Instruction \c;eof\n;
-Test the end of file condition of an open file. This is a method of the \c;\l;file\u cbot\file;\n; class; therefore you cannot write  \c;eof()\n; but only \c;handle.eof()\n;¦:
+Test the end of file condition of an open file. This is a method of the \c;\l;file\u cbot\file;\n; class; therefore you cannot write  \c;eof()\n; but only \c;handle.eof()\n;:
 \c;
 \s;	if ( handle.eof() )  
 \n;
-Example¦:
+Example:
 \c;
 \s;	while ( not handle.eof() )
 \s;	{

help/cbot/E/errmode.txt

@@ -2,7 +2,7 @@
 The \c;errmode();\n; instruction allows you to chose if the program should stop when an error occurs in one of the following instructions: \c;\l;goto\u cbot\goto;\n;, \c;\l;move\u cbot\move;\n;, \c;\l;grab\u cbot\grab;\n;, \c;\l;drop\u cbot\drop;\n;, etc.
 
 \b;For specialists
-Syntax¦:
+Syntax:
 \s;\c;errmode ( mode );\n;
 
 Normally the program is stopped when an error occurs. If you use the instruction \c;errmode(0);\n; at the beginning of the program, the instructions listed above return a value different from zero if the instruction could not be performed.
@@ -12,14 +12,14 @@ Error treatment mode.
 \c;0\n; -> continues program execution and returns a non zero value
 \c;1\n; -> stops the program (default behavior)
 
-Exemple 1¦:
+Example 1:
 \s;\c;errmode(0);
 \s;while ( goto(pos) != 0 )
 \s;{
 \s;	wait(2);
 \s;}
 \n;
-Exemple 2¦:
+Example 2:
 \s;\c;errmode(0);
 \s;int err;
 \s;err = goto(pos);

help/cbot/E/expr.txt

@@ -1,88 +1,198 @@
 \b;Expressions
-Expressions can include the following operators: 
+Expressions are used for various calculations with many different variables, which return the desired result. What distinguishes them from standard instructions are operators, which are described below.
 
+Specifically speaking, an expression is an ordered series of operations which yield a result. Operations consist of operators, which are special \l;functions\u cbot\function; \c;T f(t1 x1, t2 x2, ..., tn xn)\n;, where \c;xi\n; is a value of type \c;ti\n;, and \c;T\n; is the result type. For example, \c;float +(float a, float b)\n; returns a sum of values \c;a\n; and \c;b\n;. Note: Operators are a part of the CBOT language and they cannot be defined in program. Also, the operators cannot be used as usual \l;functions\u cbot\function;, they need to be written using a special notation depending on the operator, for example \c;a+b\n;.
+
+In nearly all operations, \l;constants\u cbot;, \l;variables\u cbot\var;, \l;functions\u cbot\function; returning non-\l;void\u cbot\void; type and also other operations can be used as values.
+
+\b;Binary operations
+Assuming that \c;a\n;, \c;b\n; can be values of declared and initialized variables of types \c;t1\n; and \c;t2\n;, the binary operations can be described as follows:
+\s;\c;r = a op b\n;
+Where \c;r\n; is the result of the operation and \c;op\n; is a binary operator which works with values of types \c;t1\n; and \c;t2\n;.
+
+\t;Order of operations
+Let \c;a op1 b op2 c\n; be a legal expression, then the following rules apply:
+o If \c;op1 == op2\n; or \c;op1\n; is as strong as \c;op2\n; or \c;op1\n; is stronger than \c;op2\n;, first calculate \c;a op1 b\n; and store its result in a temporary variable \c;r\n;, then calculate \c;r op2 c\n;, which is the final result of the expression.
+o If \c;op1\n; is weaker than \c;op2\n;, first calculate \c;b op2 c\n; and store its result in a temporary variable \c;r\n;, then calculate \c;a op1 r\n;, which is the final result of the expression.
+
+Note: an operation can be made stronger by surrounding it in brackets, so for example assuming that \c;op1\n; is weaker than \c;op2\n;, in an expression \c;(a op1 b) op2 c\n; the \c;a op1 b\n; operation will be executed first.
+
+Tip: always use brackets if you are not sure about the order of operations, do not try to remember how strong are each of the operators. Generally it should be fairly obvious.
+
+Here is a complicated example, which uses arithemtic operations described below, showing how expressions are calculated:
+\c;Assume a, b, c, d, x, y, z, e are all initialized variables of type float or int. Then the following expression should be calculated the following way:
+  a * b + c - d / x % (y * z) - e =
+= r1 + c - d / x % (y * z) - e    = , r1 = a * b
+= r2 - d / x % (y * z) - e        = , r2 = r1 + c
+= r2 - r3 % (y * z) - e           = , r3 = d / x
+= r2 - r3 % r4 - e                = , r4 = y * z
+= r2 - r5 - e                     = , r5 = r3 % r4
+= r6 - e                          = , r6 = r2 - r5
+= r7                                , r7 = r6 - e
+r7 is the final result of this expression.
+\n;
+
+\b;Assignment operator
+\c;=\n; is the assignment operator. It is used to store the result of an expression in a variable.
+
+On the left side of this operator there must be so called l-value and on the right side - r-value. L-values are just \l;variables\u cbot\var;\n;, r-values are expressions or just usual values. This makes the assignment operator kind of special, because what is l-value is pretty restrictive (it cannot be an expression, constant and so on, only single variable). Also, the type of l-value must match the type of r-value (unless a conversion is possible, for example assigning a \c;\l;float\u cbot\float;\n; to \c;\l;int\u cbot\int;\n;).
+
+Note: it may be not obvious at first, but notice that \c;=\n; is an *operator* not an instruction. This mean that it can be used in the middle of an other expression! The result of \c;=\n; is the value which was assigned to the l-value - the result of the expression on the right. Example:
+\c;
+\s; float a;
+\s; float b = 2.0 * (a = 4.0); // b == 8.0
+\n;
+This example is actually really confusing, but this property is actually useful, because it lets doing something like this:
+\c;
+\s; float a, b, c, d, e;
+\s; a = b = c = d = e = 1.0; // a == b == c == d == e == 1.0
+\n;
+\b;Basic arithmetic operations
+Binary operators below are working with fundamental number types (\c;\l;int\u cbot\int;\n;, \c;\l;float\u cbot\float;\n;).
+
+\t;List
 \c;+\n;  addition
 \c;-\n;  subtraction
 \c;*\n;  multiplication
 \c;/\n;  division
 \c;%\n;  remainder of the division (only for the type \c;\l;int\u cbot\int;\n;)
 
-With the addition operator \c;+\n;, you can not only add numbers, you can also append \l;strings\u cbot\string;.
+\t;Notes
+o The \c;*\n;, \c;/\n;, \c;%\n; are all stronger than \c;+\n; and \c;-\n;.
+o The result \l;type\u cbot\type; is always \c;\l;float\u cbot\float;\n;. If \c;a\n; or \c;b\n; are of type \c;\l;int\u cbot\int;\n;, they are automatically converted to \c;\l;float\u cbot\float;\n;. Note: this means that results of intermediate calculations tends to be as precise as possible, the precision is lost only during converting the final (\c;\l;float\u cbot\float;\n;) result to \c;\l;int\u cbot\int;\n;, for example by the assignment \c;=\n; operator.
+
+\t;Real life examples
 \c;
-\s;	int    i = 12+3;      // returns 15
-\s;	string s = "a"+"bc";  // returns "abc"
-\s;	int    i = 2-5;       // returns -3
-\s;	float  f = 3.01*10;   // returns 30.1
-\s;	int    i = 5/3;       // returns 1
-\s;	float  f = 5/3;       // returns 1.67
-\s;	float  f = 5/0;       // returns an error
-\s;	int    i = 13%5;      // returns 3
-\s;	int    i = -8%3;      // returns -2
+\s; int    i = 12 + 3;      // i == 15
+\s; int    i = 2 - 5;       // i == -3
+\s; 
+\s; float  f = 3.01 * 10;   // f == 30.1
+\s; 
+\s; int    i = 5 / 3;       // i == 1 (automatic conversion to int)
+\s; float  f = 5 / 3;       // f == 1.67
+\s; float  f = 5 / 0;       // returns an error (division by zero)
+\s; 
+\s; int    i = 13 % 5;      // i == 3
+\s; int    i = -8 % 3;      // i == -2
+\s; 
+\s; float  f = sin(90) * i; // f == -2.0
+\s; 
 \n;
-An expression can include constants or \l;variables\u cbot\var;. For example:
-
-\s;\c;	12+dist\n;
-
-Multiplications and divisions are performed before additions and subtractions. In order to be sure that the operations are performed in the right order, use brackets: 
-\c;
-\s;	12*a+b/c \n;is equivalent to\c; (12*a)+(b/c)
-\s;	2.5*(dist+range)
-\n;
-In order to improve readability, you can put as many spaces as you want: 
-\c;
-\s;	12*a + b/c
-\s;	2.5 * (dist+range)
-\n;
-Here is a list of mathematical functions: 
-
-\c;sin(angle)    \n;sinus
-\c;cos(angle)    \n;cosinus
-\c;tan(angle)    \n;tangent
-\c;asin(value)   \n;arc-sinus
-\c;acos(value)   \n;arc-cosinus
-\c;atan(value)   \n;arc-tangente
-\c;sqrt(value)   \n;square root
-\c;pow(x, y)     \n;x power y
-\c;rand()        \n;random value ranging between 0 and 1
-
-Angles are in degrees.
-
-\t;Compound assignment operators (for specialists)
-Besides the \c;=\n; operators for variable assignment there are several compound-assignment operators.
+\t;Compound assignment operators
+Besides the \c;=\n; operator for variable assignment there are several compound-assignment operators.
 
 The compound-assignment operators combine the \c;=\n; assignment operator with another binary operator such as \c;+\n; or \c;-\n;. Compound-assignment operators perform the operation specified by the additional operator and then assign the result to the left operand. For example, a compound-assignment expression such as
-
-\c;\s;expression1 += expression2
-  
+\s;\c;lvalue += expression\n;
 is equivalent to
+\s;\c;lvalue = lvalue + expression\n;
 
-\c;\s;expression1 = expression1 + expression2
-
+\t;List
 \c;+=\n;  addition
 \c;-=\n;  subtraction
 \c;*=\n;  multiplication
 \c;/=\n;  division
 \c;%=\n;  remainder of the division (only for the type \c;\l;int\u cbot\int;\n;)
 
-\t;Prefix and posfix increment- and decrement operators (for specialists)
+\b;String concatenation
+If at least one of the values used with the \c;+\n; operator is a \l;string\u cbot\string;, then the operation of concatenation is performed. The result of the operator is then a string, which is created by joining end-to-end the string and the other value. If the other value is not a string, then it is converted to string beforehand.
+
+\t;Examples
+\c;
+\s;	string s = "a" + "bc";  // returns "abc"
+\s;	string s = 1 + "bc";    // returns "1bc"
+\s;	string s = 2.5 + "bc";  // returns "2.5bc"
+\s;	string s = "a" + true;  // returns "atrue"
+\n;
+Tip: the properties of the concatenation \c;+\n; operator is useful with the \l;message();\u cbot\message; function, because it does not work with other types than string. An empty string can be used together with a value in order to create a string, which actually can be passed to the \l;message();\u cbot\message; function:
+\c;
+\s; float pi = 3.14;
+\s; // message(pi); // does not work
+\s; message(""+pi);
+\n;
+\b;Comparison operators
+Comparison operators work with values of type \l;float\u cbot\bool; and they always return a \l;bool\u cbot\bool;. They are mainly used in \l;conditions\u cbot\cond;.
+
+\t;List
+\c;a == b  \n;\c;a\n; equals \c;b\n;
+\c;a != b  \n;\c;a\n; is different from \c;b\n;
+\c;a <  b  \n;\c;a\n; smaller than \c;b\n;
+\c;a <= b  \n;\c;a\n; smaller than or equal to \c;b\n;
+\c;a >  b  \n;\c;a\n; greater than \c;b\n;
+\c;a >= b  \n;\c;a\n; greater than or equal to \c;b\n;
+
+\t;Examples
+\c;12 == 12  \n;returns true
+\c;45 != 47  \n;returns true 
+\c;99 == 98  \n;returns false
+\c;12 <  -1  \n;returns false
+\c;12 >= 10  \n;returns true 
+\c;12 >= 12  \n;returns true 
+
+\t;Remark
+Be careful not to confuse the equality comparison \c;==\n; with the assignment of a \l;variable\u cbot\var; \c;=\n;.
+
+\c;a == b\n; is an expression that compares \c;a\n; with \c;b\n;.
+\c;a = b\n; is an expression that copies the value of \c;b\n; into \c;a\n;.
+
+\b;Logical operators
+Logical operators work with values of type \l;bool\u cbot\bool; and they always return a \l;bool\u cbot\bool;. They are mainly used in \l;conditions\u cbot\cond;.
+
+\t;List
+\c;!a      \n;not \c;a\n;
+\c;a && b  \n;\c;a\n; and \c;b\n;
+\c;a || b  \n;\c;a\n; or \c;b\n;
+
+\t;Examples
+\c;!false        \n;returns true
+\c;true && false \n;returns false 
+\c;true || false \n;returns true
+
+\b;Ternary operator
+The ternary operator is nothing more than a syntax sugar. It is also known as "inline if". It might be confusing at first, because its syntax is a little more complicated than other operators. It can be described as follows:
+\c;(condition) ? (result when true) : (result when false)\n;
+Brackets are not needed.
+
+Firstly, the condition is valued and then the first result is returned if the condition is true, otherwise the second result is returned.
+
+\t;Example
+\s;\c;float c = ((3.0 > 2.0) ? 10.0 : -10.0); // c == 10.0\n;
+
+\b;Bitwise operators
+Bitwise operators are similar to the logical operator, because they are operating on bits (which can be only 0 or 1, conditions can have a value only of false or true). So in theory, they should be working with basically any type of variable, because each value in the computer must be stored as a sequence of bits.
+
+\t;List
+\c;a & b  \n;\c;a\n; AND \c;b\n;
+\c;a | b  \n;\c;a\n; OR \c;b\n;
+\c;a ^ b  \n;\c;a\n; XOR \c;b\n;
+\c;a >> b  \n;shift bits of \c;a\n; to the right \c;b\n; times
+\c;a << b  \n;shift bits of \c;a\n; to the left \c;b\n; times
+
+\t;Examples
+\c;2 & 1         \n;returns 0
+\c;2 | 1         \n;returns 3
+\c;2 ^ 2         \n;returns 0
+\c;2 >> 1        \n;returns 1
+\c;2 << 1        \n;returns 4
+
+\b;Prefix and postfix increment- and decrement operators
 The operators \c;++\n; and \c;--\n; allow you to increment (++) or to decrement (--) a variable in very compact and efficient manner.
 
 For example to increment the variable \c;a\n; you can write
-\c;\s;	a++ ;
-\n;instead of
-\c;\s;	a = a + 1 ;
+\s;\c;a++;\n;
+instead of
+\s;\c;a = a + 1;\n;
+
+The result of the operation \c;a++\n; is the value of the variable \c;a\n; *before* the increment. If you use the prefix operator \c;++a\n; the result of the operation is the value of the variable \c;a\n; *after* the increment. The same holds for the \c;--\n; decrement operator.
+
+\t;Examples
+\c;
+\s; a = 2;
+\s; b = a++;
+\s; // now b contains 2 and a contains 3
+
+\s; a = 2;
+\s; b = ++a;
+\s; // now b contains 3 and a contains 3
 \n;
-The value of the expression \c;a++\n; is the value of the variable \c;a\n; before the increment. If you use the prefix operator \c;++a\n; the value of the expression is the value of the variable \c;a\n; after the increment. The same holds for the \c;--\n; decrement operator.
-
-Examples:
-\c;\s;	a = 2 ;
-\s;	b = a++ ;
-\s;	// now b contains 2 and a contains 3
-
-\c;\s;	a = 2 ;
-\s;	b = ++a ;
-\s;	// now b contains 3 and a contains 3
-\n;
-
 \t;See also
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/extends.txt

@@ -0,0 +1,107 @@
+\b;Keyword \c;extends\n;
+This keyword is used in a \c;\l;class\u cbot\class;\n; definition when we want the class to inherit members from another class. The class which is extended we usually call a parent or base, the extending class we call a child.
+
+\t;Example
+\c;
+\s;public class Parent
+\s;{
+\s;	void foo()
+\s;	{
+\s;		message("foo");
+\s;	}
+\s;}
+\s;
+\s;public class Child extends Parent
+\s;{
+\s;	void bar()
+\s;	{
+\s;		message("bar");
+\s;	}
+\s;}
+\s;
+\s;extern void object::Test()
+\s;{
+\s;	Child child();
+\s;	child.foo(); // Will show "foo"
+\s;	child.bar(); // Will show "bar"
+\s;}
+\n;
+
+\b;Inherited Members
+Only \c;\l;public\u cbot\public;\n; and \c;\l;protected\u cbot\protected;\n; members are inherited. \c;\l;private\u cbot\private;\n; members are directly inaccessible even for a child, although they can be accessed indirectly through inherited methods.
+
+Constructors and destructors are not inherited, however, they can be overriden.
+
+\b;Method Overriding
+Inherited methods can be overriden (redefined) in the child class definition. Example:
+\c;
+\s;public class Parent
+\s;{
+\s;	void foo()
+\s;	{
+\s;		message("foo");
+\s;	}
+\s;}
+\s;
+\s;public class Child extends Parent
+\s;{
+\s;	void foo()
+\s;	{
+\s;		message("bar");
+\s;	}
+\s;}
+\s;
+\s;extern void object::Test()
+\s;{
+\s;	Child child();
+\s;	child.foo(); // Will show "bar"
+\s;}
+\n;
+A parent's method can be called inside an overriden method by using the \c;\l;super\u cbot\super;\n; keyword.
+
+\b;Polymorphism
+\c;\l;Reference\u cbot\pointer;\n; of type Parent can point to an object of type Child. However, such a pointer can't be used to access a child member. In order to access a child member, it must be assured that the Parent reference really points to a Child object. If that's the case, it can be safely copied to a pointer of type Child, which has access to the child members.
+
+\t;Example
+\c;
+\s;public class Parent
+\s;{
+\s;	void foo()
+\s;	{
+\s;		message("foo");
+\s;	}
+\s;}
+\s;
+\s;public class Child extends Parent
+\s;{
+\s;	void foo()
+\s;	{
+\s;		message("bar");
+\s;	}
+\s;	void bar()
+\s;	{
+\s;		message("foo bar");
+\s;	}
+\s;}
+\s;
+\s;extern void object::Test()
+\s;{
+\s;	Parent people[2];
+\s;	people[0] = new Parent();
+\s;	people[1] = new Child();
+\s;	for (int i = 0; i < 2; ++i)
+\s;	{
+\s;		people[i].foo();
+\s;	}
+\s;	//people[1].bar(); // Error
+\s;	Child child = people[1];
+\s;	child.bar(); // OK
+\s;}
+\n;
+
+\b;Multiple Inheritance
+A child cannot have multiple parents, however, a parent can have many children.
+
+\t;See also
+\c;\l;class\u cbot\class;\n;, \c;\l;public\u cbot\public;\n;, \c;\l;private\u cbot\private;\n;, \c;\l;protected\u cbot\protected;\n;, \c;\l;new\u cbot\new;\n;, \c;\l;reference\u cbot\pointer;\n;, \c;\l;this\u cbot\this;\n;, \c;\l;super\u cbot\super;\n;
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/factory.txt

@@ -0,0 +1,22 @@
+\b;Instruction \c;factory\n;
+Syntax:
+\s;\c;\l;object\u cbot\object;.factory ( cat, program );\n;
+
+Starts a construction of a bot of the given \l;category\u cbot\category; and runs the specified program on it after the construction is finished.
+
+\t;\l;object\u cbot\object;
+\l;BotFactory\u object\factory;
+
+\t;cat: \c;\l;int\u cbot\int;\n;
+\l;Category\u cbot\category; of the robot to construct.
+
+\t;program: \c;\l;string\u cbot\string;\n; (default value: \c;""\n;)
+Program that will be run on the bot after factory finishes the construction. This can be either a \l;public\u cbot\public; \l;function\u cbot\function;, a \l;filename\u cbot\file; or just a raw source code.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;factory()\n;.
+\c;== 0 \n;The construction successfully started
+\c;!= 0 \n;The construction could not be started (e.g. no \l;Titanium\u object\titan; in the factory, the bot is not researched)
+
+\t;See also
+\l;researched\u cbot\researched;, \l;wait\u cbot\;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/file.txt

@@ -5,10 +5,10 @@ This type is used for accessing files in the files/ folder.
 \n;
 Use the syntax above for declaring a file handle. You must use () to create an instance of the \c;file\n; class. Without the () the handle would have the value \c;\l;null\u cbot\null;\n;.
 
-Files can only be created and opened in the files/ folder which is located in the folder where Colobot has been installed. You cannot not create or open files elsewhere than in the files/ folder.
+Files can only be created and opened in the files/ folder which is located in the folder inside Colobot save directory. You cannot not create or open files elsewhere than in the files/ folder.
 
 \b;For specialists
-\c;file\n; is actually not a simple type but a class. \c;open\n;, \c;close\n;, \c;writeln\n; etc. are methods of the \c;file\n; class. This is the reason why we always write \c;handle.method()\n;¦:
+\c;file\n; is actually not a simple type but a class. \c;open\n;, \c;close\n;, \c;writeln\n; etc. are methods of the \c;file\n; class. This is the reason why we always write \c;handle.method()\n;:
 \c;
 \s;	handle.open("test.txt", "w");
 \s;	handle.close();

help/cbot/E/flatgrnd.txt

@@ -1,5 +1,5 @@
 \b;Instruction \c;flatground\n;
-Syntax¦:
+Syntax:
 \s;\c;flatground ( center, rmax );\n;
 
 Calculates the maximal radius of a flat zone on which a building ca be built.

help/cbot/E/flatspace.txt

@@ -0,0 +1,26 @@
+\b;Instruction \c;flatspace\n;
+Syntax:
+\s;\c;flatspace ( center, flatmin, rmin, rmax, dist );\n;
+
+Determines the position of the nearest free space with at least \c;flatmin\n; of flat ground around a given position. Works similar to \c;\l;space();\u cbot\space;\n;. Useful for finding a place for a \l;building\u cbot\category;.
+
+\t;center: \c;\l;point\u cbot\point;\n;
+Desired position of the free space.
+
+\t;flatmin: \c;\l;float\u cbot\float;\n;
+Minimum radius of flat ground around the desired position.
+
+\t;rmin: \c;\l;float\u cbot\float;\n; (default value: \c;8\n;)
+Minimum distance from the desired position.
+
+\t;rmax: \c;\l;float\u cbot\float;\n; (default value: \c;50\n;)
+Maximum distance from the desired position.
+
+\t;dist: \c;\l;float\u cbot\float;\n; (default value: \c;4\n;)
+Required distance between two free spaces.
+
+\t;Return: \c;\l;point\u cbot\point;\n;
+Position of the free space.
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/floor.txt

@@ -0,0 +1,13 @@
+\b;Instruction \c;floor\n;
+Syntax:
+\s;\c;floor ( value );\n;
+Rounds down a number.
+
+\t;value: \c;\l;float\u cbot\float;\n;
+Number.
+
+\t;Return value: \c;\l;float\u cbot\float;\n;
+Floor of the value, i.e. the largest integer not greater than \c;value\n;. For example, \c;floor(2.9)\n; is \c;2.00\n;.
+
+\t;See also
+\l;round\u cbot\round;, \l;programming\u cbot;, \l;types\u cbot\type; and \l;expressions\u cbot\expr;.

help/cbot/E/for.txt

@@ -8,16 +8,16 @@ Syntax:
 This instruction allows you to execute a certain number of times the instructions contained in the \l;block\u cbot\bloc;.
 
 \t;\c;before\n;
-This instruction is executed before the first loop instance.
+This set of instructions is executed before the first loop instance.
 
 \t;\c;condition\n;
 This \l;condition\u cbot\cond; determines if another instance of the loop must be executed. It is tested before every instance of the loop. 
 
 \t;\c;end\n;
-This instruction is executed at the end of every instance of the loop. 
+This set of instructions is executed at the end of every instance of the loop. 
 
 Example: count from 1 to 4
-\c;\s;\c;for ( i = 0 ; i <= 4 ; i++ )
+\c;\s;\c;for ( i = 1 ; i <= 4 ; i++ )
 \s;{
 \s;	message(i) ;
 \s;}
@@ -35,6 +35,19 @@ Do not put a \l;semicolon\u cbot\term; at the end of the line \c;for ( )\n;.
 
 The instructions \c;\l;break\u cbot\break;\n; and \c;\l;continue\u cbot\continue;\n; can be useful inside a block following the instruction \c;for \n;.
 
+\t;Executing more instructions
+In the \c;before\n; and \c;end\n; part of a \c;for\n; loop you can specify more than one instruction by using comma. Example:
+\c;
+\s;int i = 0;
+\s;int j;
+\s;for (i++, j = 2; i < 3 && j > 0; i++, j--)
+\s;{
+\s;    message(i);
+\s;    message(j);
+\s;}
+\n;
+The output of the above code is \c;1 2 2 1\n;.
+
 \t;See also
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.
 

help/cbot/E/function.txt

@@ -1,8 +1,22 @@
 \b;Functions
-With functions you can divide your program into several parts, each of them will execute a specific task.
-Let's imagine following program¦:
+Function, simply put, is an instruction created by you.
+
+\b;Main function
+You probably already know how to create a function. Every program in CBOT must have a main function, which looks like this:
 \c;
-\s;extern void object::Remote( )
+\s;extern void object::ProgramName()
+\s;{
+\s;	
+\s;	// instructions
+\s;	
+\s;}
+\n;
+Nothing but a name can be changed in the main function. The keyword \c;\l;extern\u cbot\extern;\n; distinguishes the main function from others.
+
+\b;Basic use
+With functions you can divide your program into several parts. Each of them will execute a specific task. For example, see the following program:
+\c;
+\s;extern void object::Remote()
 \s;{
 \s;	send("order", 1, 100);
 \s;	wait(5);
@@ -14,14 +28,15 @@ Let's imagine following program¦:
 \s;	wait(5);
 \s;}
 \n;
-\c;send\n; and \c;wait\n; are repeated several times. So it would be a good thing if we created a function that executes these two instructions:
+\c;\l;send\u cbot\send;\n; and \c;\l;wait\u cbot\wait;\n; are repeated several times. So it would be a good thing if we created a function that executes these two instructions:
 \c;
-\s;void object::SendToPost( float op )
+\s;void SendToPost(float op)
 \s;{
 \s;	send("order", op, 100);
 \s;	wait(5);
 \s;}
-\s;extern void object::Remote( )
+\s;
+\s;extern void object::Remote()
 \s;{
 \s;	SendToPost(1);
 \s;	SendToPost(3);
@@ -29,17 +44,35 @@ Let's imagine following program¦:
 \s;	SendToPost(4);
 \s;}
 \n;
-A function can have paramteters¦:
+Now the program is much easier to read. It is a good practice to split the program into several functions with self-describing names.
+
+\b;Syntax
 \c;
-\s;void Example( int a, float x, string s )
+\s;result_type FunctionName(optional_parameters)
+\s;{
+\s;	body
+\s;}
 \n;
-The \c;Exemple\n; function will reveive un integer \c;a\n;, a floating point number \c;x\n; and a string \c;s\n;. Parameters are "passed by value", that is the values of parameter variables in a function are copies of the values the caller specified as variables. If you pass an \c;int\n; to a function, its parameter is a copy of whatever value was being passed as argument, and the function can change its parameter value without affecting values in the code that invoked the function.
+Result \l;type\u cbot\type; should be \l;void\u cbot/void; if the function does not give any. Body is just a set of instructions. Function name must be created with the exact same rules applied to \l;variables\u cbot\var;.
 
-If you pass a \l;class\u cbot\class; instance or an \l;array\u cbot\array; as parameter to a function, the function only receives a \l;reference\u cbot\pointer; to the instance or the array. That means if you modify the instance or the array in the function, the instance or the array that has been specified by the caller will be actuallay modified.
-
-A function can also return a result with the \c;\l;return\u cbot\return;\n; instruction. Therefore the function must be declared no longer as void but as a type:
+\t;Parameters
+A function can have parameters:
 \c;
-\s;float Mean( float a, float b )
+\s;void Example(int a, float x, string s)
+\s;{
+\s;	message(a);
+\s;	message(x);
+\s;	message(s);
+\s;}
+\n;
+The \c;Example\n; function will receive an \l;integer\u cbot\int; \c;a\n;, a \l;floating point number\u cbot\float; \c;x\n; and a \l;string\u cbot\string; \c;s\n;. Parameters are "passed by value", that is the values of parameter variables in a function are copies of the values the caller specified as variables. If you pass an \c;\l;int\u cbot\int;\n; to a function, its parameter is a copy of whatever value was being passed as the argument, and the function can change its parameter value without affecting values in the code that invoked the function.
+
+If you pass a \l;class\u cbot\class; instance or an \l;array\u cbot\array; as parameter to a function, the function only receives a \l;reference\u cbot\pointer; to the instance or the array. That means if you modify the instance or the array in the function, the instance or the array that has been specified by the caller will be actually modified.
+
+\t;Result
+A function can also return a result with the \c;\l;return\u cbot\return;\n; instruction. Therefore the function must be declared no longer as \c;\l;void\u cbot\void;\n; but as an other \l;type\u cbot\type;:
+\c;
+\s;float Average(float a, float b)
 \s;{
 \s;	return (a+b)/2;
 \s;}
@@ -47,39 +80,87 @@ A function can also return a result with the \c;\l;return\u cbot\return;\n; inst
 \s;extern void object::Test( )
 \s;{
 \s;	float value;
-\s;	value = Mean(2, 6);
-\s;	message( value );  // will display 4
+\s;	value = Average(2, 6);
+\s;	message(value);  // will display 4
 \s;}
 \n;
-Some other examples¦:
+Some other examples:
 \c;
-\s;float Pi( )
+\s;float Pi()
 \s;{
 \s;	return 3.1415;
 \s;}
 \s;
-\s;string Sign( float a )
+\s;string Sign(float a)
 \s;{
-\s;	if ( a > 0 )  return "positive";
-\s;	if ( a < 0 )  return "négative";
+\s;	if (a > 0)  return "positive";
+\s;	if (a < 0)  return "negative";
 \s;	return "null";
 \s;}
 \n;
-You can declare several functions with the same name but different parameters¦:
+
+\b;Overloading
+You can declare several functions with the same name but different parameters:
 \c;
-\s;float Pythagoras( float a, float b )
+\s;float Pythagoras(float a, float b)
 \s;{
 \s;	return sqrt((a*a)+(b*b));
 \s;}
 \s;
-\s;float Pythagoras( float a, float b, float c )
+\s;float Pythagoras(float a, float b, float c)
 \s;{
 \s;	return sqrt((a*a)+(b*b)+(c*c));
 \s;}
 \n;
-CBOT will call either the one or the other function depending on the paramteres passed.
+CBOT will call either the one or the other function depending on the parameters passed. They must be distinguishable, i.e. you can't declare two functions with the same name and parameter types in the exact same order, e.g. declaring \c;int Pythagoras(float b, float a)\n; will result in error. Note that result type does not matter.
 
+\b;Public Functions
 You can also declare a function \l;public\u cbot\public; so it can be used by other bots.
 
+\b;object::
+Declaring a function as a part of the \l;object\u cbot\object; namespace gives it access to \c;\l;this\u cbot\this;\n; \l;pointer\u cbot\pointer;, in other words, to all available properties of the robot which the program is run on.
+\c;
+\s;void object::Example()
+\s;{
+\s;	message(this.category);
+\s;}
+\n;
+
+\b;Default Parameters
+Last function parameters can have default values that can be omitted when calling.
+\c;
+\s;float Add(float a = 0.0, float b = 0.0)
+\s;{
+\s;	return a + b;
+\s;}
+\s;
+\s;// Somewhere in the main program...
+\s;Add(); // Will return 0.0
+\s;Add(2.0); // Will return 2.0
+\s;Add(2.0, 3.0); // Will return 5.0
+\s;// ...
+\n;
+
+\t;Default Parameters and Overloading
+Functions with default parameters still can be overloaded, one must only ensure that function calls are not ambiguous. For example, consider the following code:
+\c;
+\s;float Add(float a = 0.0, float b = 0.0)
+\s;{
+\s;	return a + b;
+\s;}
+\s;
+\s;string Add(string a = "", string b = "")
+\s;{
+\s;	return a + b;
+\s;}
+\s;
+\s;// Somewhere in the main program...
+\s;Add(); // Compilation error: ambiguous call
+\s;Add(""); // Ok
+\s;Add(0.0); // Ok
+\s;// ...
+\n;
+Note that in the above example overloading causes the first default parameter to be useless as caller needs to pass it anyway in order to distinguish the two functions.
+
 \t;See also
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/goto.txt

@@ -24,7 +24,7 @@ Flight altitude for \l;winged bots\u object\botgj;. The altitude is useful only
 This parameter tells the bot how it must reach the goal: 
 \c;0\n;  stops exactly at the goal position
 \c;1\n;  goes close to the goal position, without stopping.
-If no value is given, \c;1\n; (precision) is the default value. 
+If no value is given, \c;0\n; (precision) is the default value.
 
 \t;Return value: \c;\l;int\u cbot\int;\n;
 Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;goto()\n;.

help/cbot/E/object.txt

@@ -1,5 +1,5 @@
 \b;Type \c;object\n;
-Use this type for variables that contain the characteristics of an object, be it a bot, a building, some raw material, an enemy, etc. 
+Use this type for variables that contain the characteristics of an object, be it a bot, a building, some raw material, an enemy, etc. Here are all properties of an object: 
 
 \c;\l;int\u cbot\int;    object.category     \n;\l;Category\u cbot\category; of the object
 \c;\l;point\u cbot\point;  object.position     \n;Position of the object (x,y,z)
@@ -13,6 +13,10 @@ Use this type for variables that contain the characteristics of an object, be it
 \c;\l;float\u cbot\float;  object.lifeTime     \n;Lifetime of the object
 \c;object object.energyCell   \n;Power cell on the bot
 \c;object object.load         \n;Object carried by the bot
+\c;\l;int\u cbot\int;    object.team         \n;The object's team (see \l;code battles\u battles;)
+\c;\l;point\u cbot\point;  object.velocity     \n;Velocity of the object
+
+Also, some objects have additional methods (instructions). See them in \l;the main list\u cbot; in the \c;"Instructions specific for some objects" section.
 
 \s;\c;category\n;
 The \n;\l;category\u cbot\category; of an object allows you to know what it is, f. ex. what kind of bot, building, enemy, etc.
@@ -53,6 +57,12 @@ If the bot has bot no power cell, \c;energyCell\n; returns \c;null\n;.
 \s;\c;load\n;
 This information also returns the description of a whole object: the description of the object carried by a \l;grabber\u object\botgr;. If it carries nothing, \c;load\n; returns \c;null\n;.
 
+\s;\c;team\n;
+The bot's team. Used in \l;code battles\u battles;. If the object has no team assigned (e.g. in no team-based levels, the object being a resource), this is equal to \c;0\n;.
+
+\s;\c;velocity\n;
+Current velocity of the object. Should be treated as a three-dimensional vector.
+
 \b;Examples
 The type \c;object\n; returns the special value \c;\l;null\u cbot\null;\n; when the object does not exist. For example:
 \c;
@@ -65,6 +75,7 @@ The type \c;object\n; returns the special value \c;\l;null\u cbot\null;\n; when
 \s;	{
 \s;	}
 \n;
+
 \t;See also
 \l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.
 

help/cbot/E/open.txt

@@ -1,9 +1,9 @@
 \b;Instruction \c;open\n;
-Open a text file in the files/ folder. This is a method of the \c;\l;file\u cbot\file;\n; class. This is the reason why we always write \c;handle.open()\n;¦:
+Open a text file in the files/ folder. This is a method of the \c;\l;file\u cbot\file;\n; class. This is the reason why we always write \c;handle.open()\n;:
 \c;
 \s;	handle.open("test.txt", "w");
 \n;
-To open a file, proceed as follows¦:
+To open a file, proceed as follows:
 \c;
 \s;	file handle();
 \s;	handle.open("filename", "w");
@@ -12,8 +12,9 @@ To open a file, proceed as follows¦:
 \n;
 \c;"r"\n; mode: open for reading.
 \c;"w"\n; mode: open for writing.
+\c;"a"\n; mode: open for appending.
 
-Files can only be created and opened in the files/ folder which is located in the folder where Colobot has been installed. You cannot not create or open files that are located elsewhere than in the files/ folder.
+Files can only be created and opened in the files/ folder which is located in the folder inside Colobot save directory. You cannot not create or open files that are located elsewhere than in the files/ folder.
 
 \t;See also
 \c;\l;file\u cbot\file;\n;, \c;\l;close\u cbot\close;\n;, \c;\l;readln\u cbot\readln;\n;, \c;\l;writeln\u cbot\writeln;\n; and \c;\l;eof\u cbot\eof;\n;.

help/cbot/E/openfile.txt

@@ -1,10 +1,11 @@
 \b;Instruction \c;openfile\n;
-\c;openfile();\n; opens an text file in the files/ folder. This is not a method of the \c;\l;file\u cbot\file;\n; class but openfile returne a \l;reference\u cbot\pointer; to a new instance of the file class. You must supply two parameters, the filename and the opening mode.
+\c;openfile();\n; opens an text file in the files/ folder. This is not a method of the \c;\l;file\u cbot\file;\n; class but openfile returns a \l;reference\u cbot\pointer; to a new instance of the file class. You must supply two parameters, the filename and the opening mode.
 \c;
 \s;file handle = openfile("filename", "r");
 \n;
 \c;"r"\n; mode: open for reading.
 \c;"w"\n; mode: open for writing.
+\c;"w"\n; mode: open for appending.
 
 
 \t;See also

help/cbot/E/pencolor.txt

@@ -0,0 +1,15 @@
+\b;Instruction \c;pencolor\n;
+Syntax:
+\s;\c;pencolor ( color );\n;
+The instruction \c;pencolor();\n; instructs the bot to change the color of the pencil.
+
+\t;color: \c;\l;int\u cbot\int;\n; (default value: \c;Black\n;)
+\l;Color name\u cbot\colors;.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;pencolor();\n;.
+\c;== 0 \n;The color was changed
+\c;!= 0 \n;The instruction did not work
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/pendown.txt

@@ -0,0 +1,18 @@
+\b;Instruction \c;pendown\n;
+Syntax:
+\s;\c;pendown ( color, width );\n;
+The instruction \c;pendown();\n; instructs the bot to have the pen down, so it starts drawing.
+
+\t;color: \c;\l;int\u cbot\int;\n; (default value: \c;Black\n;)
+\l;Color name\u cbot\colors;.
+
+\t;width: \c;\l;float\u cbot\float;\n; (default value: \c;0.5\n;)
+Width of the pen. The width cannot be higher than \c;1.0\n; and cannot be lower than \c;0.0\n;. Passing a higher value will result in the width being the highest possible and passing a lower value will result in the width being the lowest possible.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;pendown();\n;.
+\c;== 0 \n;The pen is now down
+\c;!= 0 \n;The instruction did not work
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/penup.txt

@@ -0,0 +1,12 @@
+\b;Instruction \c;penup\n;
+Syntax:
+\s;\c;penup ( );\n;
+The instruction \c;penup();\n; instructs the bot to have the pen up, so it stops drawing. The pen is up by default, so it should be used only after using \c;\l;pendown\u cbot\pendown;\n;.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;penup();\n;.
+\c;== 0 \n;The pen is now up
+\c;!= 0 \n;The instruction did not work
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.

help/cbot/E/penwidth.txt

@@ -0,0 +1,15 @@
+\b;Instruction \c;penwidth\n;
+Syntax:
+\s;\c;penwidth ( color );\n;
+The instruction \c;penwidth();\n; instructs the bot to change the width of the pencil.
+
+\t;width: \c;\l;float\u cbot\float;\n;
+Width of the pen. The width cannot be higher than \c;1.0\n; and cannot be lower than \c;0.0\n;. Passing a higher value will result in the width being the highest possible and passing a lower value will result in the width being the lowest possible.
+
+\t;Return value: \c;\l;int\u cbot\int;\n;
+Normally an error stops the program. You can prevent the program from stopping on errors by using the \c;\l;errmode\u cbot\errmode;(0)\n; instruction. A value different from zero if an error occurred is then returned by \c;penwidth();\n;.
+\c;== 0 \n;The width was changed
+\c;!= 0 \n;The instruction did not work
+
+\t;See also
+\l;Programming\u cbot;, \l;types\u cbot\type; and \l;categories\u cbot\category;.