Merge pull request #1018 from boriel-basic/docs

Docs

Author: boriel

docs/external_resources.md

@@ -9,7 +9,7 @@ Other people contribute to it creating alternative IDEs, libraries, tools and ut
 ### Tommy Gun
 A free IDE created by [Tony Thompson](http://www.users.on.net/~tonyt73). This powerful tool is designed to create
 generic 8-bit and 16-bit projects, and can be set up to be used with ZX Basic.
-Have a look at the [TommyGun files](https://sourceforge.net/projects/tommygun/files/) page.
+Have a look at the [TommyGun files](https://sourceforge.net/projects/tommygun/files/) or [source code](https://github.com/tonyt73/TommyGun) pages.
 
 To integrate ZX Basic with Tommy Gun, please follow this [tutorial](https://forum.boriel.com/showthread.php?tid=110).
 
@@ -25,7 +25,7 @@ further information. The documentation of it is very well maintained.
 
 * [Multipaint](http://multipaint.kameli.net/), a Java-based graphics editor that allows you to draw pictures with the color limitations of some typical screen formats from 8-bit computer platforms, like ZX Spectrum, C64 and Plus/4 high-resolution and multicolor, MSX 1 and Amstrad CPC0.
 
-* [ZX-Paintbrush] (https://zx-modules.de/), a Windows graphics editor specifically for ZX-Spectrum screen formats, including multicolor.
+* [ZX-Paintbrush](https://zx-modules.jimdofree.com/), a Windows graphics editor specifically for ZX-Spectrum screen formats, including multicolor.
 
 ## Utilities
 Other generic utilities not above are:
@@ -45,13 +45,13 @@ There are several external engines that can be used within compiler to achieve e
 * [FASE](https://forum.boriel.com/showthread.php?tid=568)
   (or [here](https://forum.boriel.com/showthread.php?tid=575)), a sprite, tile and map engine.
 * [Nirvana](https://spectrumcomputing.co.uk/entry/30001/ZX-Spectrum/NIRVANA_ENGINE)
-  (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x2 (30x22 chars) graphics engine.
+  (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x2 (30x22 chars) graphics engine.
 * [Nirvana+](https://spectrumcomputing.co.uk/entry/30002/ZX-Spectrum/NIRVANA_ENGINE)
-  (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x2 (32x23 chars) graphics engine.
+  (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x2 (32x23 chars) graphics engine.
 * [Bifrost*](https://spectrumcomputing.co.uk/entry/27405/ZX-Spectrum/BIFROST*_ENGINE)
-  (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x1 (18x18 chars) graphics engine.
+  (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x1 (18x18 chars) graphics engine.
 * [Bifrost*2](https://spectrumcomputing.co.uk/entry/30003/ZX-Spectrum/BIFROST*2_ENGINE)
-  (or [https://www.ime.usp.br/~einar/bifrost/ here]), a multicolour 8x1 (20x22 chars) graphics engine.
+  (or [here](https://www.ime.usp.br/~einar/bifrost/)), a multicolour 8x1 (20x22 chars) graphics engine.
 * [Zxodus\]\[Engine](https://spectrumcomputing.co.uk/entry/26639/ZX-Spectrum/ZXodus_Engine)
   (or [here](https://forum.boriel.com/showthread.php?tid=568)), a 3d maze and RPG engine with
   multicolour 8x1 (18x18 chars) support.

docs/for.md

@@ -10,7 +10,6 @@
 ## Parameters
 
 * _iterator_: a variable identifier that is used to iterate from an initial value to an end value.
-* _datatype_: If specified, the variable iterator will automatically be declared with the type datatype.
 * _startvalue_: an expression that denotes the starting value of the iterator.
 * _endvalue_: an expression used to compare with the value of the iterator.
 * _stepvalue_: an expression that is added to the iterator after every iteration.

docs/function.md

@@ -80,5 +80,6 @@ that can be ignored.
 * [ASM](asm.md)
 * [END](end.md)
 * [RETURN](return.md)
+* [DECLARE](declare.md)
 * [ByREF](byref.md)
 * [ByVAL](byval.md)

docs/identifier.md

@@ -9,7 +9,7 @@ Note that there are a number of common statements that you may find in ZX BASIC
 
 ## Reserved Identifiers
 
-The following identifiers are _reserved words_, and can't be used as variables, functions or labels. Reserved identifiers are _case insensitive_ (it doesn't matter whether you write them in upper or lower case letters, or a mix of them). So **PRINT**, **print** and **PrInT** means all the same in ZX BASIC. On the other hand, non-reserved words can be either case sensitive or not (depending on the [options](options.md)) in effect.
+The following identifiers are _reserved words_, and can't be used as variables, functions or labels. Reserved identifiers are _case insensitive_ (it doesn't matter whether you write them in upper or lower case letters, or a mix of them). So **PRINT**, **print** and **PrInT** means all the same in ZX BASIC. On the other hand, non-reserved words can be either case sensitive or not (depending on the [options](zxb.md#command-line-options) in effect).
 
 Identifiers shown in bold are taken from the Sinclair BASIC (beware their meaning here might be different, however). Some of them has been marked as _statements_, _functions_ or _operators_:
 
@@ -120,7 +120,7 @@ You should also avoid defining (with a SUB or FUNCTION command) routines with th
 * **[CSRLIN (Library Function)](library/csrlin.md)** **(function)**
 * [HEX (Library Function)](library/hex.md) **(function)**
 * [HEX16 (Library Function)](library/hex.md) **(function)**
-* **[INPUT (Library Function)](library/input.md)** **(function)**
+* **[INPUT42 (Library Function)](library/input42.md)** **(function)**
 * **[GetKey (Library Function)](library/keys/getkey.md)** **(function)**
 * **[MultiKeys (Library Function)](library/keys/multikeys.md)** **(function)**
 * **[GetKeyScanCode (Library Function)](library/keys/getkeyscancode.md)** **(function)**

docs/library/attr.md

@@ -31,5 +31,5 @@ PRINT AT 0, 0; "The attribute of screen position 9, 10 is "; s
 ## See also
 
 * [ CSRLIN ](csrlin.md)
-* [ POS](pos.md)
+* [ POS ](pos.md)
 * [ AT ](../at.md)

docs/library/csrlin.md

@@ -2,6 +2,7 @@
 
 ## Syntax
 
+
 ```
 CSRLIN()
 ```
@@ -14,6 +15,7 @@ Returns the row (line) position of the text cursor (0 means the top line).
 
 CSRLIN is a library function to be included with the following command:
 
+
 ```
 # include <csrlin.bas>
 ```

docs/library/hex.md

@@ -0,0 +1,37 @@
+# HEX/HEX16/HEX8
+
+## Syntax
+
+
+```basic
+A$ = hex(n32)
+B$ = hex16(n16)
+C$ = hex8(n8)
+```
+Where `n32` is a 32-bit ULONG, `n16` is a 16-bit UINTEGER and `n8` is an 8-bit UBYTE.
+
+## Description
+
+* HEX:
+Takes one _32_ bit unsigned integer number and returns an 8 chars str containing the HEX string representation.
+* HEX16:
+Takes one _16_ bit unsigned integer number and returns a 4 chars str containing the HEX string representation.
+* HEX8:
+Takes one _8_ bit unsigned integer number and returns a 2 chars str containing the HEX string representation.
+
+## Requirements
+
+HEX, HEX16 and HEX8 can be included with the following command:
+
+```
+#include <hex.bas>
+```
+
+## Remarks
+
+* This function is not available in Sinclair BASIC.
+* Avoid recursive / multiple inclusion when calling this function.
+* HEX16 ad HEX8 both call HEX to perform conversion, but differ in the size of the string they return.
+
+## See also
+

docs/library/input42.md

@@ -0,0 +1,35 @@
+# Input42.bas
+
+## INPUT42
+
+Simple INPUT routine (not as powerful as Sinclair BASIC's), but this one uses the PRINT42 routine.
+Issues a cursor to the screen, waits for the user to type and returns the user's input through PRINT42 when the user presses ENTER.
+
+## Syntax
+
+```basic
+A$ = INPUT42(MaxChars)
+```
+MaxChars is the number of characters the INPUT42 function will accept as a maximum. It is a UINTEGER and thus has a maximum value of 65535.
+
+## Requirements
+
+INPUT42 is a library function that must be included before it can be used. Use the following directive:
+
+```
+# include <input42.bas>
+```
+
+## Remarks
+
+* Note that this function ALWAYS RETURNS A STRING, which is very different from Sinclair BASIC's INPUT statement.
+* This function places the Input cursor at the last print position, not at the bottom of the screen. Remember that ZX Basic allows access to all 24 screen lines, so PRINT AT 24,0; sets the PRINT cursor to the bottom of the screen.
+* Avoid recursive / multiple inclusion
+* The input subroutine DOES NOT act like ZX Spectrum INPUT command
+* Uses ZX SPECTRUM ROM
+
+## See also
+
+* [ INKEY ](../inkey.md)
+* [ INPUT ](../input.md)
+* [ PRINT42 ](print42.bas.md)

docs/operators.md

@@ -39,10 +39,8 @@ which is _wrong_. If in doubt, use always parenthesis to enforce the desired eva
 
 ## Logical Operators
 
-Logicals operators are like in ZX Spectrum Basic. Their result can be either _False_ (which is represented with 0)
-or _True_, which might be any other value. <u>Don't expect _True_ value number to be always **1**</u>.
-If you need 0/1 values for boolean evaluations, use `--strict-boolean` [compiler option](zxb.md#Command Line Options).
-This might add a little overhead to boolean evaluations, tough.
+Logicals operators are like in ZX Spectrum Basic. Their result can be either False
+(which is represented with 0) or True (represented by 1).
 
 Operator arguments must be numbers and the result is an unsigned byte value. For binary operators,
 if arguments are of different types they are [converted](cast.md) to a common type before being evaluated:

docs/sub.md

@@ -1,6 +1,5 @@
 # SUB
 
-
 ZX Basic allows function and subroutines declarations. Sinclair Basic does not allow named subroutines, only calls with the GOSUB command.
 
 A subroutine defined with the SUB statement is invoked directly. Unlike a [FUNCTION](function.md), a SUB does not return a value. This is the fundamental difference between code defined with SUB and code defined with FUNCTION. Other than that, the setup for SUB and FUNCTION are almost identical.
@@ -71,3 +70,4 @@ It will also issue a warning (perhaps you forgot to call it?), that can be ignor
 * [ASM](asm.md)
 * [END](end.md)
 * [RETURN](return.md)
+* [DECLARE](declare.md)