Merge pull request #336 from boriel/docs

Docs

Author: boriel

docs/cls.md

@@ -0,0 +1,39 @@
+#CLS
+
+##Syntax
+
+```
+ CLS
+```
+
+##Description
+
+`CLS` is short for *CLear Screen*, and will do just that: it will clear the screen, setting the background
+with the current [PAPER](paper.md) color, and placing the Screen Cursor at (0, 0) - screen top-leftmost corner.
+
+
+##Examples
+
+```
+REM sets the screen black, and INK white
+BORDER 0: PAPER 0: INK 7
+CLS
+PRINT "White text on black background"
+```
+
+
+##Remarks
+
+* This sentence is compatible with Sinclair BASIC 
+
+##See also
+
+* [PRINT](print.md)
+* [AT](at.md)
+* [PAPER](paper.md)
+* [BORDER](border.md)
+* [INVERSE](inverse.md)
+* [INK](ink.md)
+* [ITALIC](italic.md)
+* [BOLD](bold.md)
+* [OVER](over.md)

docs/print.md

@@ -0,0 +1,124 @@
+#PRINT
+
+##Syntax
+
+```
+ PRINT [<item>][;]
+```
+
+##Description
+
+`PRINT` is a sentence used to output information on the screen. The ZX Spectrum screen is divided in 24 rows (numbered
+from 0 to 23), and 32 columns (numbered from 0 to 31). So it's composed of 24 x 32 = 96 cells. Cells are referred by
+its coordinate (row, column), being (0, 0) the top-leftmost cell, and (23, 31) the bottom-rightmost one.
+
+There's a _hidden cursor_ on the screen that points to the coordinate where the next character will be printed.
+Each time something is printed, a _carriage return_ is also printed and the screen cursor is advanced to 
+the next line (row):
+
+```
+PRINT "I'M ON ONE LINE"
+PRINT "I'M ON THE NEXT ONE"
+```
+
+If you don't want this to happen, you can add a semicolon (;) at the end of the `PRINT` sentence, and the next
+printed expression will still be on the same line:
+
+```
+PRINT "I'M ON ONE LINE";
+PRINT "... AND I'M ALSO ON THE SAME LINE"
+PRINT "AND I'M ON A NEW LINE"
+```
+Notice the first `PRINT` ends with a semicolon to avoid _carriage return_. Executing a single `PRINT` will just
+advance the cursor to the next line.
+
+> **NOTE**: when the cursor reaches the end of the screen, it will **scroll upwards** all rows 1 position.
+
+Let's prints numbers from 0 to 25 and see what happens:
+
+```
+CLS: REM Clears screeen and puts the cursor at the top-leftmost corner
+FOR i = 0 TO 25
+  PRINT i
+NEXT i
+```
+You'll see that number 0 and 1 are gone (they were shifted up and went out of the screen).
+
+> **NOTE**: When the screen is cleared with [CLS](cls.md), the cursor is set to its default position (0, 0),
+> that is, the top-leftmost screen corner.
+    
+`PRINT` can print everything that is a _single_ expression (also called an _item_).
+That is, strings (like in the previous example), numbers, variable values, and array elements
+(it can not print an entire array; that's not a `single` element but a collection):
+
+For example:
+
+```
+LET a = 5
+PRINT "Variable 'a' contains the value: ";
+PRINT a
+```
+
+Indeed, if you want to chain several expressions one after another you can _chain_ them in a single PRINT sentence
+using semicolons:
+```
+LET a = 5
+PRINT "Variable 'a' contains the value: "; a
+```
+
+## Changing the print position
+You can change the current _cursor_ position using the [AT](at.md) modifier:
+
+```
+PRINT AT 5, 0; "This message starts at ROW 5"
+PRINT AT 10, 10; "This message starts at ROW 10, COLUMN 10"
+```
+
+Again, you can chain all `PRINT` _items_ using semicolon:
+
+```
+PRINT AT 5, 0; "ROW 5"; AT 10, 10; "ROW 10, COLUMN 10"
+```
+
+## Changing appearance
+You can temporarily override the aspect of the items printed using them inline:
+
+```
+CLS
+FOR i = 1 to 7
+  PRINT AT i, 0; PAPER 0; INK i; "PRINT AT ROW "; i; " WITH INK "; i
+NEXT i
+```
+
+See the related commands section for further info.
+
+##Examples
+
+```
+REM Prints a letter in the 10th row of the screen moving from left to right
+CLS
+FOR i = 0 TO 31
+  PRINT AT 10, i; "A"
+  PAUSE 10
+  PRINT AT 10, i; " ": REM Erases the letter
+NEXT i
+```
+
+
+##Remarks
+
+* This sentence is compatible with Sinclair BASIC but _expands_ it, since it allows printing at rows 22 and 23
+  (all 24 rows are available to the programmer). Traditionally, Sinclair BASIC only allows to print at rows 0..21.
+* You can use [ITALIC](italic.md) and [BOLD](bold.md) modifiers (not available in Sinclair BASIC)
+
+##See also
+
+* [CLS](cls.md)
+* [AT](at.md)
+* [PAPER](paper.md)
+* [BORDER](border.md)
+* [INVERSE](inverse.md)
+* [INK](ink.md)
+* [ITALIC](italic.md)
+* [BOLD](bold.md)
+* [OVER](over.md)

docs/return.md

@@ -0,0 +1,47 @@
+#RESTORE
+
+
+##Syntax
+```
+RETURN [<expr>]
+```
+**RETURN** statement is used in 3 cases:
+
+1. When returning from a [GO SUB](gosub.md) sentence
+2. When returning (exiting) from a [SUB](sub.md) (a subroutine)
+3. When returning (exiting) from a [FUNCTION](function.md). In this case a return value must be specified.
+
+
+Returns in the global scope (that is, outside any function or sub) are treated as return from [GO SUB](gosub.md).
+Otherwise they are considered as returning from the function or sub they are into.
+
+> **WARNING**: Using RETURN in global scope without a GOSUB will mostly crash your program. <br>
+> Use `--stack-check` if you suspect you have this bug, to detect it.
+
+### Example with GO SUB
+
+```
+10 LET number = 10
+20 GOSUB 1000 : REM calls the subroutine
+30 LET number = 20
+40 GOSUB 1000 : REM calls the subroutine again
+100  END : REM the program must end here to avoid entering the subroutine without using GOSUB
+1000 REM Subroutine that prints number + 1
+1010 PRINT "number + 1 is "; number + 1
+1020 RETURN : REM return to the caller
+```
+
+This will output:
+
+```
+number + 1 is 11
+number + 1 is 21
+```
+
+##Remarks
+* This statement is Sinclair BASIC compatible.
+
+##See also
+* [GO SUB](gosub.md)
+* [FUNCTION](function.md)
+* [SUB](sub.md)

library/memcopy.bas

@@ -59,7 +59,7 @@ end sub
 '
 ' Copies block of memory from source to dest.
 ' Source and destiny blocks should not overlap.
-' This sub is slighly faster than memmove
+' This sub is slightly faster than memmove
 ' ----------------------------------------------------------------
 sub fastcall MemCopy(source as uinteger, dest as uinteger, length as uinteger)
 	asm