Merge pull request #28 from Joe7M/master

Update of entry page

Author: chrisws

_build/pages/guide.markdown

@@ -244,13 +244,18 @@ Examples
 #inc:"mylib.bas"
 ...
 MyLibProc "Hi"
-*Arrays and Matrices*
-Define a 3x2 matrix
-A = [11, 12; 21, 22; 31, 32]
 ```
 
+
+### Arrays and Matrices
+
+Define a 3x2 matrix
+
+`A = [11, 12; 21, 22; 31, 32]`
+
 That creates the array
 
+
 -- --
 11 12
 21 22

_build/pages/index.markdown

@@ -2,49 +2,92 @@
 
 > one more basic
 
-::: articleRight ::
-::: articleRightInner ::
+SmallBASIC is a fast and easy to learn BASIC language interpreter ideal for everyday calculations, scripts and prototypes. SmallBASIC includes trigonometric, matrices and algebra functions, a built in IDE, a powerful string library, system, sound, graphic commands and communication via serial or sockets along with structured programming syntax.
 
+```smallbasic
+' Example for using functions in SmallBASIC
+
+s = AddStrings("My", "String")
+print s
+
+func AddStrings(a, b)
+    return a + b
+end
+```
+
+## Multi-platform
+
+SmallBASIC is released for Windows, Linux and Android. It can be build from source for many other POSIX compliant operating systems including Raspberry Pi OS for the Raspberry Pi. Thanks to the build in IDE programs can be written on your Android powered tablet or mobile phone and executed immediately ([Downloads](/pages/download.html)).
+
+Your program can be bundled with all necessary libraries to create executable files for Windows (exe-files) or Linux (AppImage). For Android a signed pkg can be created and for example distributed using Google play ([Distribute your program](/pages/distributiontool.html)).
+
+Additionally you can start programming with the online version of SmallBASIC in your browser right now: [Start online](/online/sbasic.html).
+
+## Editors, IDE and SmallBASIC versions
+
+SmallBASIC comes in three different flavors for the desktop. The SDL version offers a simple but efficient IDE and is perfect for working with graphics. The FLTK version has a great IDE. The console version doesn't offer an IDE and is text-only but works perfect with plugins like raylib or nuklear ([Downloads](/pages/download.html)).
+
+No matter which SmallBASIC version you prefer, external editors like Visual Studio Code, Geany, Sublime Text or KDE Kate can be setup for syntax highlighting or code execution ([Setup external editors](/language_support.html)).
+
+Instructions on how to use the editor in the SDL and Android version can be found in the article [Android](/pages/android.html)
+
+## Units
+
+Units are sets of functions, procedures and constants bundled in a BASIC-library and can be imported in your program. Units use their own namespace and therefore are separated from your program.
+
+```smallbasic
+' Example for importing the CSS color-name unit
+
+Import crgb as c
+
+Color c.Black, c.Tomato
+Print " Standard CSS Tomato background color "
+Color c.Black, c.LightSteelBlue
+Print " Standard CSS LightSteelBlue background color "
+
+rect 200, 200, 400, 400 COLOR c.DeepPink filled
 ```
-##############  ##    ##    ##############        
-##          ##  ##      ##  ##          ##        
-##  ######  ##  ########    ##  ######  ##        
-##  ######  ##  ##  ######  ##  ######  ##        
-##  ######  ##  ####  ##    ##  ######  ##        
-##          ##    ####      ##          ##        
-##############  ##  ##  ##  ##############        
-                ##  ##                            
-  ####  ##  ####  ##    ##  ##  ##########        
-####      ##      ##  ##      ######  ##          
-  ########  ##    ####    ########    ####        
-  ####        ####  ######      ####    ##        
-##  ##  ########  ##          ####      ##        
-                ##########  ####  ##              
-##############  ######        ####  ######        
-##          ##    ##########  ##                  
-##  ######  ##  ##  ######  ##  ######            
-##  ######  ##      ##      ########  ##          
-##  ######  ##  ####    ##      ######  ##        
-##          ##  ##          ######    ##          
-##############      ##  ##  ##  ########## 
+## Plugins
+
+Plugins are libraries written in C which extent the functionality of SmallBASIC. SmallBASIC offers an API to write your own plugins. The following plugins are part of the release version of SmallBASIC: raylib (2D and 3D game development), nuklear (GUI programming), clipboard, gifencoder and WebSockets. You can also import a plugin for the Raspberry Pi to use the GPIO ports and some additional hardware like displays or temperature sensors.
+
+```smallbasic
+' Example how to use raylib to open a window and print text.
+
+import raylib as rl
+import raylibc as c
+
+const screenWidth = 800
+const screenHeight = 450
+
+rl.InitWindow(screenWidth, screenHeight, "raylib [core] example - basic window")
+rl.SetTargetFPS(60) 
+
+while (!rl.WindowShouldClose())
+    rl.BeginDrawing()
+        rl.ClearBackground(c.RAYWHITE)
+        rl.DrawText("Congrats! You created your first window!", 190, 200, 20, c.LIGHTGRAY)
+    rl.EndDrawing()
+wend
+rl.CloseWindow()
 ```
 
-:::
-:::
+## More information
+
+Read more in the short [user guide](/pages/guide.html) or in the [SmallBASIC handbook](/pages/vade.html). See the documentation of all SmallBASIC commands in the [language reference](/pages/reference.html) or browse additional articles in the [article section](/pages/articles.html).
 
-SmallBASIC is a fast and easy to learn BASIC language interpreter ideal for everyday calculations, scripts and prototypes. SmallBASIC includes trigonometric, matrices and algebra functions, a built in IDE, a powerful string library, system, sound, and graphic commands along with structured programming syntax.
 
-[Read more](/pages/guide.html)
+## News
 
-## SmallBASIC version 12.26 has been released for Windows, Linux and web browser
+### SmallBASIC version 12.26 has been released for Windows, Linux and web browser
 
 ::: date
 | March 26, 2023
 :::
 
 For details see: [Latest release](https://github.com/smallbasic/SmallBASIC/releases/tag/12_26). Please report any issues to either the forum, email or github issues page.
 
-## SmallBASIC version 12.24 has been released for Windows, Linux and web browser
+### SmallBASIC version 12.24 has been released for Windows, Linux and web browser
 
 ::: date
 | June 20, 2022
@@ -53,7 +96,7 @@ For details see: [Latest release](https://github.com/smallbasic/SmallBASIC/relea
 For details see: [Latest release](https://github.com/smallbasic/SmallBASIC/releases/tag/v12.24). Please report any issues to either the forum, email or github issues page.
 
 
-## New article: "Language Support" provided by Joe7M
+### New article: "Language Support" provided by Joe7M
 
 ::: date
 | February 15, 2022
@@ -62,23 +105,23 @@ For details see: [Latest release](https://github.com/smallbasic/SmallBASIC/relea
 For details see: [Language Support](/pages/language_support.html)
 
 
-## SmallBASIC version 12.23 has been released
+### SmallBASIC version 12.23 has been released
 
 ::: date
 | August 31, 2021
 :::
 
 For details see: [Latest release](https://github.com/smallbasic/SmallBASIC/releases/tag/v12.23). Please report any issues to either the forum, email or github issues page.
 
-## SmallBASIC version 12.20 has been released
+### SmallBASIC version 12.20 has been released
 
 ::: date
 | January 8, 2021
 :::
 
 This release includes new loadable modules with support for [RAYLIB](https://www.raylib.com/), [Nuklear](https://github.com/Immediate-Mode-UI/Nuklear) and WebSockets. For details see: [release notes](https://github.com/smallbasic/SmallBASIC/releases/tag/v12.20). Please report any issues to either the forum, email or github issues page.
 
-## SmallBASIC version 12.19 has been released
+### SmallBASIC version 12.19 has been released
 
 ::: date
 | July 16, 2020
@@ -87,55 +130,55 @@ This release includes new loadable modules with support for [RAYLIB](https://www
 For details see: [release notes](https://github.com/smallbasic/SmallBASIC/releases/tag/12_19). Please report any issues to either the forum, email or github issues page.
 
 
-## New teaching resource: "Programming SmallBASIC" provided by Gerard Thomas Labèrnia
+### New teaching resource: "Programming SmallBASIC" provided by Gerard Thomas Labèrnia
 
 ::: date
 | April 11, 2020
 :::
 
 For details see: [Articles](/pages/articles.html)
 
-## SmallBASIC version 0.12.18 has been released
+### SmallBASIC version 0.12.18 has been released
 
 ::: date
 | March 16, 2020
 :::
 
 For details see: [release notes](https://github.com/smallbasic/SmallBASIC/releases/tag/0_12_18). Please report any issues to either the forum, email or github issues page.
 
-## SmallBASIC version 0.12.17 has been released
+### SmallBASIC version 0.12.17 has been released
 
 ::: date
 | December 22, 2019
 :::
 
 For details see: [release notes](https://github.com/smallbasic/SmallBASIC/releases/tag/0_12_17). The windows package includes sbasici.exe which is a recreation of the previous FLTK version. Please report any issues to either the forum, email or github issues page.
 
-## New discussion forum
+### New discussion forum
 
 ::: date
 | October 29, 2019
 :::
 
 The Retrogamecoding and Basicprogramming Forum is scheduled for closure on 4th of November 2019. A new forum has been created at www.syntaxbomb.com. Click the **Discuss** link above and join the discussion!
 
-## Cool new sample program, news on progress
+### Cool new sample program, news on progress
 
 ::: date
 | June 2, 2019
 :::
 
 [Read more](/posts/2019-06-02.html)
 
-## SmallBASIC version 0.12.14 has been released
+### SmallBASIC version 0.12.14 has been released
 
 ::: date
 | November 22, 2018
 :::
 
 [Read more](/pages/changelog.html)
 
-## SmallBASIC version 0.12.13 has been released
+### SmallBASIC version 0.12.13 has been released
 
 ::: date
 | September 13, 2018
@@ -147,15 +190,15 @@ The Retrogamecoding and Basicprogramming Forum is scheduled for closure on 4th o
 
 [Samples](/pages/samples.html)
 
-## Web site updated
+### Web site updated
 
 ::: date
 | March 29, 2018
 :::
 
 [Read more](/posts/2018-29-03.html)
 
-## SmallBASIC version 0.12.10 has been released
+### SmallBASIC version 0.12.10 has been released
 
 ::: date
 | December 24, 2017

_build/reference/1015-console-definekey.markdown

@@ -2,7 +2,7 @@
 
 > DEFINEKEY k, sub
 
-Binds a keystroke to a user defined function. To unbind the keystroke definition pass 0 as the `sub` argument.
+Binds a keycode `k` to a user defined sub routine `sub`. When the key is pressed, the coresponding sub routine will be called. To unbind the keycode definition pass `0` as the `sub` argument.
 
 Keycodes for PC keyboard
 
@@ -33,7 +33,7 @@ Keycodes for PC keyboard
 | Shift + A to Z   | asc("A") to asc("Z")                           |
 
 
-## Examples
+### Examples
 
 Example 1: Bind keystroke for left and right arrow key
 
@@ -57,13 +57,13 @@ wend
 ```
 
 
-Example 2: Unbind a keystroke
+### Example 2: Unbind a keystroke
 
 ```
 DEFINEKEY 0xFF04, 0
 ```
 
-Example 3: Etch-a-Sketch
+### Example 3: Etch-a-Sketch
 
 ```
 ' DEFINEKEY demo.bas  SmallBASIC 0.12.2 [B+=MGA] 2016-03-30
@@ -131,7 +131,7 @@ sub quit
 end
 ```
 
-Example 4: This example is outdated and just a reference for buttons in PALM OS
+### Example 4: This example is outdated and just a reference for buttons in PALM OS
 
 ```
 ' Note:

_build/reference/1429-graphics-showpage.markdown

@@ -1,8 +1,8 @@
 # SHOWPAGE
 
-> SHOWPAGE
+> SHOWPAGE ([n])
 
-This command is used to display pending graphics operations allowing for smooth animations.
+This command is used to display pending graphics operations allowing for smooth animations. If SHOWPAGE is used, the internal SmallBASIC graphics update mechanism is set to manual mode. To enable automatic mode again, call SHOWPAGE with the optional parameter `n = 1`. This is useful, if the FORM command is used to display GUI elements. 
 
 ### Example
 

_build/reference/1522-system-cwd.markdown

@@ -1,9 +1,11 @@
 # CWD
 
-> CWD
+> s = CWD
 
 Gets current working directory.
 
+### Example
+
 ```
 print cwd
 ```

_build/reference/525-console-form.markdown

@@ -1,6 +1,6 @@
 # FORM
 
-> FORM(formMap)
+> f = FORM(formMap)
 
 Creates a form object `f` from a MAP variable `formMap`. Form object `f` gives access to the following GUI elements:
 
@@ -22,7 +22,7 @@ In listboxes and dropdown listboxes press and hold mouse button to scroll throug
 |-------------|-------------------------------|
 | doEvents()  | Process system events for mouse and keyboard handling.
 | close()     | Closes the active FORM.
-| refresh(n)  | n = 1 Copy the UI state into the FORM input variables. n = 0 Update the UI state using the FORM input variables.
+| refresh(n)  | `n = 1` copy the UI state into the FORM input variables `f.inputs`. `n = 0` update the UI state using the FORM input variables `f.inputs`.
 
 The form object `f` may contain the following properties:
 
@@ -70,6 +70,17 @@ The type attribute can be one of the following:
 | "text"    | Single or multi-line text input.
 | "image"   | Image button.
 
+### Change or read the GUI elements
+
+Once the GUI elements are rendered on screen they can be changed for example to respond to user input. By calling `f.refresh(1)` the current state of the GUI elements will be copied to `f`. The content of `f` is rendered to screen, when calling `f.refresh(0)`. `f.inputs` is an array of MAP variables. The first element of that array is the first GUI element added to `formMap.inputs`. For example the color of the first element can be changed:
+
+```
+f.inputs[0].color = 12
+f.refresh(0)
+```
+
+To get a list of all available elements of the n-th GUI element, you can simply use `print f.inputs[n]`.
+
 ### Example 1: Creating a push button using callback function
 
 ```
@@ -174,6 +185,8 @@ l.y = 120
 l.height = 200
 l.width = 100
 l.value = "cats|dogs|fish|birds|insects"
+' alternative way is to pass an array:
+' l.value = ["cats", "dogs", "fish", "birds", "insects"]
 l.color = rgb(255, 255, 255)
 l.backgroundColor = rgb(100, 100, 100)
 
@@ -202,6 +215,8 @@ l.x = 120
 l.y = 120
 l.width = 100
 l.value = "cats|dogs|fish|birds|insects"
+' alternative way is to pass an array:
+' l.value = ["cats", "dogs", "fish", "birds", "insects"]
 l.color = rgb(255, 255, 255)
 l.backgroundColor = rgb(100, 100, 100)