Merge pull request #15 from Joe7M/master

Update of command references

Author: chrisws

_build/pages/escape.markdown

@@ -1,19 +1,16 @@
 # Escape codes
 
-SmallBASIC supports a number of escape codes for controlling the display. The codes allow you to set foreground and background colors, change the font and also set underline and inverse text display.
+SmallBASIC supports a number of escape codes for controlling the display. The codes allow you to set foreground and background colors, change the font and also set underline and inverse text display. The escape codes are based on [ANSI Codes](http://en.wikipedia.org/wiki/ANSI_escape_code).
 
-The escape codes are based on [ANSI Codes](http://en.wikipedia.org/wiki/ANSI_escape_code). SmallBASIC also support a number of additional codes which are not part of the standard.
-
-Escape sequences start with the characters ESC (ASCII 27d / 1Bh / 033o )  and [ (left bracket). This sequence is called CSI for  "Control Sequence Introducer".
-
-The supported standard codes are:
+## The supported standard codes are:
 
 ```
   \a      beep
   \t      tab (20 px)
   \r      return
   \n      next line
-  \xC     clear screen (new page)
+  \"      quote "
+  \\      Backslash \
   \e[K    clear to end of line
   \e[nG   move to column n
   \e[s    save cursor position
@@ -30,23 +27,69 @@ The supported standard codes are:
   \e[nm   n colors - 30..37 foreground, 40..47 background
 ```
 
-Useful non-standard codes include:
+## Using the escape codes directly
 
-```
-  \003    end of text (flush buffer)
-  \m      scroll to the top
-  \<1     select backscreen 1
-  \<2     select backscreen 2
-  \>1     select frontscreen 1
-  \<2     select frontscreen 2
+The instead of "\e" the CHR command is useful for obtaining and printing the escape character (ASCII 27)
+
+```Freebasic
+PRINT CHR(27) + "[1mTHIS IS BOLD" + CHR(27) + "[0m"
+PRINT CHR(27) + "[3mThis is italic"  + CHR(27) + "[0m"
+PRINT CHR(27) + "[4mThis is underline"
+
+PRINT "\e[32mGreen text"
+PRINT "\e[32m\e[47mGreen text on white background"
+PRINT "First line\nSecond Line"
 ```
 
-The CHR command is useful for obtaining and printing the escape character (ASCII 27)
+## Using the EscapeCode Unit
 
-For example:
+The EscapeCode Unit makes it easier to use the escape codes and to deal with the different colors for foreground and background. The uint can be downloaded  or copy pasted from the [SmallBASIC Github website](https://github.com/smallbasic/smallbasic.plugins/blob/master/units/EscapeCodes.bas). Please save the unit in the same directory as you basic file.
 
+Here an example on how to use the unit.
+
+```Freebasic
+' SmallBASIC 12.25
+' Example for using UNIT "EscapeCodes"
+' For more information see: https://smallbasic.github.io/pages/escape.html
+
+import EscapeCodes as esc
+
+print "FORMATING TEXT:"
+print
+print esc.NORMAL + "WITHOUT ANY FORMAT " + esc.ITALIC + "ITALIC " + esc.ITALIC_OFF + esc.BOLD + "BOLD " + esc.BOLD_OFF + esc.UNDERLINE + "UNDERLINE " + esc.UNDERLINE_OFF + esc.REVERSE + "REVERSE" + esc.REVERSE_OFF
+print
+print "USE COLORS:"
+print
+print esc.BG_BLACK   + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_RED     + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_GREEN   + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_YELLOW  + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_BLUE    + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_MAGENTA + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_CYAN    + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.BG_WHITE   + esc.BLACK + "  BLACK  " + esc.RED + "   RED   " + esc.GREEN + "  GREEN  " + esc.YELLOW + " YELLOW " + esc.BLUE + "  BLUE    " + esc.MAGENTA + " MAGENTA " + esc.CYAN + "  CYAN  " + esc.WHITE + "  WHITE  " + esc.NORMAL
+print esc.NORMAL
+print "USE COLORS AND FORMATS:"
+print
+print esc.NORMAL + esc.BOLD + esc.UNDERLINE + esc.GREEN + esc.BG_WHITE + "BOLD + UNDELINE + COLOR" + esc.NORMAL
+print
+print "CONTROL THE CURSOR:"
+print
+print esc.MOVE_TO_COLUMN(4) + "MOVE TO COLUMN 4"
+print "TABS:" + esc.TB + "ONE TAB" + esc.TB + esc.TB + "TWO MORE TABS"
+print "YOU SHOULD NOT READ THIS" + esc.RET + "RETURN TO BEGIN OF LINE "
+print "FIRST LINE" + esc.NEXTLINE + "NEXT LINE"
+print esc.SAVECURSOR + "YOU SHOULD NOT READ THIS" 
+print esc.RESTORECURSOR + esc.CLEAR_LINE + "SAVE AND RESTORE THE CURSOR POSITION"
+print
+print "OTHER:"
+print
+print esc.QUOTE + "YOU CAN USE QUOTES" + esc.QUOTE
+print esc.BP + "A BEEP SHOULD BE AUDIBLE"
 ```
-10 PRINT CHR(27) + "[1mTHIS IS BOLD" + CHR(27) + "[0m"
-20 PRINT CHR(27) + "[3mThis is italic"  + CHR(27) + "[0m"
-30 PRINT CHR(27) + "[4mThis is underline"
-```
+
+## Escape codes in SmallBASIC console version
+
+In the console version of SmallBASIC (sbasic.exe or sbasic) most of the escape codes, for example [ANSI Codes at wikipedia](http://en.wikipedia.org/wiki/ANSI_escape_code), can be used in version 12.25 or later. The support of the escape codes depends on the operating system and the terminal you are using.
+
+

_build/pages/guide.markdown

@@ -103,6 +103,14 @@ Strings may be appended to one another using the + operator.
 b = "Hello, " + "world!"
 ```
 
+```
+b = """This is
+a string
+over several lines
+with line breaks"""
+```
+
+
 ### Constants {#Constants}
 
 Constant variables can be declared by using the keyword CONST.
@@ -204,12 +212,13 @@ Sets parameters of the compiler. Where [parameter]{.code}
 * COMMAND cmdstr Sets the [COMMAND$]{.code} string to [var]{.code} (useful for debug reasons)
 * GRMODE [widthxheight[xbpp]] Sets the graphics mode flag (-g option) or sets the preferred screen resolution. Example: (Clie HiRes)
 
-~~~
-OPTION PREDEF GRMODE 320x320x16
-~~~
+  ~~~
+  OPTION PREDEF GRMODE 320x320x16
+  ~~~
 
 * TEXTMODE Sets the text mode flag (-g- option)
 * CSTR Sets as default string style the C-style special character encoding ('\\')
+* ANTIALIAS off : Disable anti-aliasing for drawing commands like CIRCEL or LINE
 
 ### Meta-commands {#Meta}
 

_build/reference.json

@@ -1322,7 +1322,7 @@
             "type": "function"
         },
         {
-            "help": "Inverse cosine.",
+            "help": "Inverse hyperbolic cosine.",
             "keyword": "ACOSH",
             "nodeID": "708",
             "signature": "ACOSH (x)",
@@ -1336,7 +1336,7 @@
             "type": "function"
         },
         {
-            "help": "Inverse cotangent.",
+            "help": "Inverse hyperbolic cotangent.",
             "keyword": "ACOTH",
             "nodeID": "710",
             "signature": "ACOTH (x)",
@@ -1350,7 +1350,7 @@
             "type": "function"
         },
         {
-            "help": "Inverse co secant.",
+            "help": "Inverse hyperbolic co secant.",
             "keyword": "ACSCH",
             "nodeID": "712",
             "signature": "ACSCH (x)",
@@ -1364,7 +1364,7 @@
             "type": "function"
         },
         {
-            "help": "Inverse secant.",
+            "help": "Inverse hyperbolic secant.",
             "keyword": "ASECH",
             "nodeID": "714",
             "signature": "ASECH (x)",
@@ -1378,7 +1378,7 @@
             "type": "function"
         },
         {
-            "help": "Inverse sine.",
+            "help": "Inverse hyperbolic sine.",
             "keyword": "ASINH",
             "nodeID": "716",
             "signature": "ASINH (x)",
@@ -1399,7 +1399,7 @@
             "type": "function"
         },
         {
-            "help": "Inverse tangent.",
+            "help": "Inverse hyperbolic tangent.",
             "keyword": "ATANH",
             "nodeID": "719",
             "signature": "ATANH (x)",
@@ -1427,7 +1427,7 @@
             "type": "function"
         },
         {
-            "help": "Cosine.",
+            "help": "Hyperbolic cosine.",
             "keyword": "COSH",
             "nodeID": "723",
             "signature": "COSH (x)",
@@ -1441,7 +1441,7 @@
             "type": "function"
         },
         {
-            "help": "Cotangent.",
+            "help": "Hyperbolic cotangent.",
             "keyword": "COTH",
             "nodeID": "725",
             "signature": "COTH (x)",
@@ -1455,7 +1455,7 @@
             "type": "function"
         },
         {
-            "help": "Co secant.",
+            "help": "Hyperbolic co secant.",
             "keyword": "CSCH",
             "nodeID": "727",
             "signature": "CSCH (x)",
@@ -1623,7 +1623,7 @@
             "type": "function"
         },
         {
-            "help": "Secant.",
+            "help": "Hyperbolic secant.",
             "keyword": "SECH",
             "nodeID": "751",
             "signature": "SECH (x)",
@@ -1672,7 +1672,7 @@
             "type": "function"
         },
         {
-            "help": "Sine.",
+            "help": "Hyperbolic sine.",
             "keyword": "SINH",
             "nodeID": "758",
             "signature": "SINH (x)",
@@ -1693,21 +1693,28 @@
             "type": "function"
         },
         {
-            "help": "Mean deviation.",
+            "help": "Standard deviation.",
+            "keyword": "STATSTD",
+            "nodeID": "1800",
+            "signature": "STATSTD (...)",
+            "type": "function"
+        },
+        {
+            "help": "Mean absolute deviation around arithmetic mean.",
             "keyword": "STATMEANDEV",
             "nodeID": "761",
             "signature": "STATMEANDEV (...)",
             "type": "function"
         },
         {
-            "help": "Sample spread.",
+            "help": "Biased sample variance.",
             "keyword": "STATSPREADP",
             "nodeID": "762",
             "signature": "STATSPREADS (...)",
             "type": "function"
         },
         {
-            "help": "Population spread.",
+            "help": "Unbiased sample variance.",
             "keyword": "STATSPREADS",
             "nodeID": "763",
             "signature": "STATSPREADP (...)",

_build/reference/1425-language-try.markdown

@@ -2,12 +2,39 @@
 
 > TRY
 
-The TRY statement introduces a TRY/CATCH BLOCK
+__TRY__
 
+The TRY statement introduces a TRY/CATCH block.
 
+__CATCH [var | expr]__
 
-Note:
-If this demo program crashes... then run it again. It seems that TRY / CATCH block might be unstable within a function or sub... (?)
+The CATCH statement is used to CATCH an run-time error. This is typically used with errors raised when calling a file system command that cannot be completed, for example attempting to open a non-existent file.
+
+The CATCH statement has two modes. You can supply a variable argument to store the error string. Alternatively you can supply an expression. When the raised error matches the (String) expression, the error will be caught.
+
+When using the expression mode, you can supply a succession of CATCH statements to handle various error messages separately.
+
+__END TRY__
+
+The END TRY statement marks the end of a TRY/CATCH block.
+
+
+### Example 1: Opening a non-existing file for reading
+
+```
+try
+    ' DON'T use existing file for demo.
+    open "try demo.tmp" for input  as #1
+catch err
+    print err; " "
+    ' Some error handling could be implemented here
+    ' i.e: if(err = "...") then ...
+end try
+
+print "This point is reach, even if opening the file was not possible"
+```
+
+### Example 2: Advanced error handling for opening files
 
 ~~~
 
@@ -21,7 +48,7 @@ Func opens(filename, mode)
     Case "input" : Open filename For Input  As #fn
     Case "output": Open filename For Output As #fn
     Case "append": Open filename For Append As #fn
-    Case Else: ? "opens(): Bad open mode at line " + Progline: Pause: Stop
+    Case Else: ? "opens(): Bad open mode at line " + Progline: Stop
     End Select
     opens = fn ' file opened, return file-handle (integer 1 to 256)
   Catch err
@@ -72,8 +99,14 @@ If fn Then
   ? lines;
   Close #fn
 Fi
-Pause
-
 ~~~
 
+### Example 3: Open COM-Port
 
+```
+try
+  open "com2000:" AS #1
+catch err
+  ? "in catch: open failed";err
+end try
+```

_build/reference/1426-language-catch.markdown

@@ -2,11 +2,9 @@
 
 > CATCH [var | expr]
 
-The CATCH statement is used to CATCH an run-time error.
+The CATCH statement is used to CATCH a run-time error. This is typically used with errors raised when calling a file system command that cannot be completed, for example attempting to open a non-existent file.
 
-This is typically used with errors raised when calling a file system command that cannot be completed, for example attempting to open a non-existent file.
+The CATCH statement has two modes. You can supply a variable argument to store the error string. Alternatively you can supply an expression. When the raised error matches the (String) expression, the error will be caught. When using the expression mode, you can supply a succession of CATCH statements to handle various error messages separately.
 
-The CATCH statement has two modes. You can supply a variable argument to store the error string. Alternatively you can supply an expression.
-
-When the raised error matches the (String) expression, the error will be caught. When using the expression mode, you can supply a succession of CATCH statements to handle various error messages separately.
+For more information and examples please see TRY.
 

_build/reference/1428-language-bg.markdown

@@ -2,7 +2,13 @@
 
 > SOUND frq, dur [, vol] [BG]
 
-Play sound in the background. This prevent the program from blocking while the sound plays.
+Play sound in the background. BG prevents the program from blocking while the sound plays.
+
+See SOUND.
+
+```
+SOUND 1000, 1000 BG
+```