Merge pull request #27 from Joe7M/master

Update of function reference

Author: chrisws

_build/reference.json

@@ -510,6 +510,13 @@
             "signature": "WRITE #fileN; var1 [, ...]",
             "type": "command"
         },
+        {
+            "help": "Read variables from a binary file.",
+            "keyword": "READ",
+            "nodeID": "601",
+            "signature": "READ #fileN; var1 [, ...]",
+            "type": "command"
+        },
         {
             "help": "Reads and returns a byte from file or device (Binary mode) .",
             "keyword": "BGETC",

_build/reference/1422-language-using.markdown

@@ -2,6 +2,22 @@
 
 > PRINT USING
 
-See PRINT, SPRINT
+PRINT USING uses the FORMAT function to display numbers and strings.
+
+See PRINT for more information. USG and USING are equivalent.
+
+### Example
+
+```
+a = 1000
+b = 2000
+PRINT USING "#,###.##"; a                    
+PRINT USING "#,###.## "; a; b                ' <- Format is applied to all variables         
+PRINT USING "a = #####.00  b = #####"; a; b  ' <- One formated string with placeholders for two variables
+
+' Output: 1,000.
+' Output: 1,000. 2,000.             
+' Output: a =  1000.00  b =  2000   
+```
 
 

_build/reference/1423-language-usg.markdown

@@ -2,7 +2,23 @@
 
 > PRINT USG
 
-Synonym for USING
+PRINT USG uses the FORMAT function to display numbers and strings.
+
+See PRINT for more information. USG and USING are equivalent.
+
+### Example
+
+```
+a = 1000
+b = 2000
+PRINT USG "#,###.##"; a                    
+PRINT USG "#,###.## "; a; b                ' <- Format is applied to all variables         
+PRINT USG "a = #####.00  b = #####"; a; b  ' <- One formated string with placeholders for two variables
+
+' Output: 1,000.
+' Output: 1,000. 2,000.             
+' Output: a =  1000.00  b =  2000   
+```
 
 
 

_build/reference/1428-language-bg.markdown

@@ -6,8 +6,11 @@ Play sound in the background. BG prevents the program from blocking while the so
 
 See SOUND.
 
+### Example
+
 ```
 SOUND 1000, 1000 BG
+pause
 ```
 
 

_build/reference/1432-data-array.markdown

@@ -1,130 +1,33 @@
 # ARRAY
 
-> ARRAY [var | expr]
+> A = ARRAY [s | expr]
 
-Creates a ARRAY or MAP variable from the given string or expression.
+Creates a ARRAY or MAP variable from the given string `s` or expression `expr`. The ARRAY command supports JSON (Javascript object notation) syntax. The MAP provides value-key pair access along with array or dotted notation. 
 
-The ARRAY command supports JSON (Javascript object notation) syntax. The MAP provides value-key pair access along with array or dotted notation.
-The MAP can be converted back into a JSON string using the STR command. You can test whether a variable is a MAP using the ISMAP command.
+See STR for converting a MAP variable into a JSON string.
+
+### Example 1: JSON string to MAP
 
 ```
 a = array("{Name: Alice, Age: 20}")
 print a
 print a.Name + " is " + a.Age + " years old"
+
+' Output:
+' {"Age":20,"Name":"Alice"}
+' Alice is 20 years old
 ```
 
-Instead of using ARRAY, the following shorter syntax will give the same result:
+### Example 2: JSON with nested MAP
 
 ```
-a = {Name: Alice, Age: 20}
-print a
-print a.Name + " is " + a.Age + " years old"
+a = Array("{x:1, y:3, down:{x:4, y:7}}")
+print a                                    ' Output: {"down":{"y":7,"x":4},"x":1,"y":3}
 ```
 
-The following example shows a possible JSON representation describing a person:
+### Example 3: Array string to array
 
-~~~
-{
-  "firstName": "John",
-  "lastName": "Smith",
-  "isAlive": true,
-  "age": 25,
-  "address": {
-    "streetAddress": "21 2nd Street",
-    "city": "New York",
-    "state": "NY",
-    "postalCode": "10021-3100"
-  },
-  "phoneNumbers": [
-    {
-      "type": "home",
-      "number": "212 555-1234"
-    },
-    {
-      "type": "office",
-      "number": "646 555-4567"
-    },
-    {
-      "type": "mobile",
-      "number": "123 456-7890"
-    }
-  ],
-  "children": [],
-  "spouse": null
-}
-~~~
-
-Example 1:
-
-~~~
-Def uline(text) = Cat(2) + text + Cat(-2) ' Underline text
-Cls
-? uline("1-Dimension Map Array:")
-?
-a = Array("{x:100, y:300, title:top-left}")
-? "a is:       "; a
-? "a is map?   "; Ismap(a)
-?
-? "a.x is:     "; a.x
-? "a.y is:     "; a.y
-? "a.title is: "; a.title
-?
-a.x = "N/A"
-? "a.x is now: "; a.x
-?
-?:?:? " Press any key..."
-Pause
-Cls
-? uline("1-Dimension Map Array, with 1-D Nested Map Array:")
-?
-Dim a(1 To 10, 1 To 2)
-a(5, 1) = Array("{x:1, y:3, down:{x:4, y:7}}")
-? "a(5, 1) is:            "; a(5, 1)
-? "a(5, 1) is map?        "; Ismap(a(5, 1))
-? "a is map?              "; Ismap(a)
-?
-? "a(5, 1).x is:          "; a(5, 1).x
-? "a(5, 1).y is:          "; a(5, 1).y
-? "a(5, 1).down.x is:     "; a(5, 1).down.x
-? "a(5, 1).down.y is:     "; a(5, 1).down.y
-?
-a(5, 1).down.x = "N/A"
-? "a(5, 1).down.x is now: "; a(5, 1).down.x
-?
-?:?:? " Press any key..."
-Pause
-Cls
-? uline("1-Dimension Map Array, with Two 1-D Nested Map Arrays:")
-?
-a = Array("{x:1, y:3, down:[{x:4, y:7}, {x:6, y:9}]}")
-? "a is:               "; a
-? "a is map?           "; Ismap(a)
-?
-? "a.x is:             "; a.x
-? "a.y is:             "; a.y
-? "a.down(0).x is:     "; a.down(0).x
-? "a.down(0).y is:     "; a.down(0).y
-? "a.down(1).x is:     "; a.down(1).x
-? "a.down(1).y is:     "; a.down(1).y
-?
-a.down(1).x = "N/A"
-? "a.down(1).x is now: "; a.down(1).x
-?
-?:?:? " Press any key..."
-Pause
-Cls
-? uline("Create 1-Dimension Map Array without using ARRAY Keyword:")
-?
-b.x = 40
-b.y = 50
-b.title = "Top-Left"
-? "b.x is:     "; b.x
-? "b.y is:     "; b.y
-? "b.title is: "; b.title
-?
-? "b is:       "; b
-? "b is map?   "; Ismap(b)
-?
-?:?:? " Press any key..."
-Pause
-~~~
+```
+a = Array("[1,2,3]")
+print a                 ' Output: [1,2,3]
+```

_build/reference/1439-system-chain.markdown

@@ -2,17 +2,19 @@
 
 > CHAIN source
 
-Compile and run the given source. Source can be a file name, a line of code or an array of code. Use ENV to share variables with the parent process.
+Compile and run the given source. `source` can be a file name, a line of code or an array of code. Use ENV to share variables with the parent process.
 
-Example 1: Using constants; Note: `\"` is used to create a quote inside the string
+### Example 1: Using constants
+
+Note: `\"` is used to create a quote inside the string
 
 ```
 Chain "? \"100 + 50 is: \"; 100 + 50" 
 
 ' Output: 100 + 50 is: 150
 ```
 
-Example 2: Using variables
+### Example 2: Using variables
 
 ```
 Env "SB1=6"
@@ -22,7 +24,7 @@ Chain "? Env(\"SB1\") ^ Env(\"SB2\")"
 ' Output: 36
 ```
 
-Example 3: Using an array
+### Example 3: Using an array
 
 ```
 Env "SB1=3"
@@ -38,7 +40,7 @@ Chain a
 ' Output: 3 6 9 12 15
 ```
 
-Example 4: Using a file and returning a value
+### Example 4: Using a file and returning a value
 
 ```
 ' First we have to create a bas-file to show how chain works with files
@@ -67,7 +69,7 @@ print "Return value SB1 is: "; Env("SB1");
 ' Return value SB1 is: 6
 ```
 
-Example 5:
+### Example 5:
 
 ```
 ' Create demo bas file (could be any SmallBASIC file):
@@ -101,7 +103,7 @@ Color 7:  ? "I'm The Parent Program..."
 Color 15: ? "Child program returned value: "; Env("SB1")
 ```
 
-Example 6: Creating an eval function
+### Example 6: Creating an eval function
 
 ```
 ' Dedicated to MGA.

_build/reference/1446-system-unit.markdown

@@ -7,11 +7,11 @@ Declares the source module as a unit. Units are a set of procedures, functions,
 - UNIT supports 'namespace' (Namespaces allow reuse of same names in different contexts. e.g. BitLib.Set(x) and StrLib.Set(x) are both using a function with the same name, "Set", but in different contexts).
 - While UNIT can be used as a collection of sub-routines for your own program, UNIT is particularly useful for creating a general-purpose library. General purpose libraries can be useful for many programs or projects, the same way the internal routine “PRINT” is useful for many programs, and not only for specific one.
 
-Use EXPORT to export procedured, functions, constants or variables. Only exported names can be access in the main program.
+Use EXPORT to export procedures, functions, constants or variables. Only exported names can be accessed in the main program.
 
 ### Example 1: Simple Unit
 
-First an example of the unit. Please save it with the filename "MyTestUnit.bas"
+First, an example of the unit. Please save it with the filename "MyTestUnit.bas"
 
 ```
 UNIT MyTestUnit
@@ -30,7 +30,7 @@ sub MySub(a,b)
 end
 ```
 
-Second an example on how to use the unit.
+Second, an example on how to use the unit.
 
 ```
 import MyTestUnit as u
@@ -45,13 +45,12 @@ print u.MyVar
 ```
 
 
-### Example 2: An unit for using string
+### Example 2: An unit for using strings
 
 
-The UNIT file is strlib.bas:
-
-~~~
+The UNIT file. Please save as strlib.bas.
 
+```
 ' File: strlib.bas
 ' ------------
 ' In this demo we are using UNIT to add more useful String commands to
@@ -100,12 +99,11 @@ Func Rset(s, b)
     Rset = Space(b - l) + s
   Fi
 End
-
-~~~
+```
 
 Demo file, demo.bas, which is using strlib.bas above:
 
-~~~
+```
 ' Here we declare that this file is using another UNIT file.
 ' Note: The actual file name must be in lower case for Linux OS.
 Import strlib ' (without .bas extension)
@@ -120,6 +118,6 @@ Print Strlib.Lset(Strlib.Rset("This way...", 18), 25)
 Locate 6, 30
 Print Strlib.Rset("-->>  ", 25)
 Pause
-~~~
+```
 
 

_build/reference/1526-graphics-xmax.markdown

@@ -1,9 +1,14 @@
 # XMAX
 
-> XMAX
-
-Holds the screen width in pixels
+> n = XMAX
 
+Returns the screen width in pixels.
 
+See YMAX for screen height.
 
+### Example
 
+```
+print "This window has " + XMAX + "x" + YMAX + " pixels"
+' Output: This window has 640x480 pixels
+```

_build/reference/1527-graphics-ymax.markdown

@@ -1,8 +1,17 @@
 # YMAX
 
-> YMAX
+> n = YMAX
 
-Holds the screen height in pixels.
+Returns the screen height in pixels.
+
+See XMAX for screen width.
+
+### Example
+
+```
+print "This window has " + XMAX + "x" + YMAX + " pixels"
+' Output: This window has 640x480 pixels
+```
 
 
 

_build/reference/521-console-at.markdown

@@ -2,7 +2,11 @@
 
 > AT x, y
 
-Moves the console cursor to the specified position. x,y are in pixels.
+Moves the text cursor to the specified position `[x, y]`. `x` and `y` are in pixels.
+
+See LOCATE to move the text cursor in units of characters cells.
+
+### Example
 
 ```
 at 100,100