Merge pull request #458 from boriel/docs

Docs

Author: boriel

docs/architectures/bitwiselogic.md

@@ -0,0 +1,94 @@
+#Bitwise Operators
+
+ZX Basic allows Bit Manipulation (bitwise), on every integer type (from 8 to 32 bits).
+
+| **BITWISE OPERATORS** |
+|: ---------------------------- :|
+| bAND |
+| bOR  |
+| bNOT |
+| bXOR |
+
+Except bNOT, all the others require two integral (Byte, Ubyte, Integer, UInteger, Long, ULong) operands.
+The operation will be applied bit by bit.
+
+---
+##bAND
+
+Performs the _Bitwise Conjunction_ and returns 1 for every bit if and only if both bits are 1.
+
+| a  | b  | result |
+|:----:|:----:|:------:|
+|  0  | 0  |  0 |
+|  0  | 1  | 0 |
+|  1  | 0  |  0 |
+|  1  | 1  |  1 |
+
+###Example
+
+Binary "mask" that will get only the 4 rightmost bits 0 1 2 3 of a number:
+
+`PRINT BIN 01110111 bAND BIN 00001111` will print 3, which is 0111`
+
+---
+
+## bOR
+
+Performs the _Bitwise Disjunction_ and returns 1 if any of the arguments is 1.
+
+| a  | b  | result |
+|:----:|:----:|:------:|
+|  0  | 0 |  0 |
+|  0  | 1  | 1 |
+|  1  | 0 |  1 |
+|  1  | 1  |  1 |
+
+###Example
+
+Ensure an ASCII letter is always in lowercase:
+
+`PRINT CHR$(CODE "A" OR BIN 10000)` will print `a` because lowercase letters have bit 5 set.
+
+---
+
+## bNOT
+
+Performs the _Bitwise Negation_ and returns _1_ if the arguments is _0_ and vice versa. 
+Basically it flips all the bits in an integer number.
+
+| a  |result |
+|:----:|:------:|
+|  0  | 1  |
+|  1  | 0  |
+
+
+###Example
+
+Invert the first cell (upper-leftmost) in the screen:
+
+```
+PRINT AT 0, 0; "A";
+FOR i = 0 TO 3
+    POKE 16384 + 256 * i, bNOT PEEK(16384 + 256 * i)
+NEXT
+```
+---
+
+#bXOR
+
+Performs a logical XOR and returns 1 if one and only one of the arguments is 1, 0 if both bits are the same.
+In essence, returns 1 ONLY if one of the arguments is 1. 
+
+| a  | b  | result |
+|:----:|:----:|:------:|
+|  0  | 0 |  0 |
+|  0  | 1  | 1 |
+|  1  | 0 |  1 |
+|  1  | 1  |  0 |
+---
+
+###Example
+
+Flips an ASCII letter from lower to uppercase and vice versa
+
+`PRINT CHR$(CODE "A" bXOR BIN 10000)`

docs/bitwiselogic.md

@@ -26,7 +26,9 @@ and no access is specified, it's supposed to be `ByRef` (arrays cannot be passed
 ByRef allows us to pass arrays to [FUNCTION](function.md) or [SUB](sub.md):
 
 ```
-REM arrays passed to functions can be of *any dimensions*. Use LBOUND and UBOUND to detect dimensions!
+REM arrays passed to functions can be of *any dimensions*.
+REM Use LBOUND and UBOUND to detect dimensions!
+
 FUNCTION maxValue(ByRef a() as Ubyte) As UByte
   DIM i as UInteger
   DIM result As UByte = 0 
@@ -40,8 +42,8 @@ DIM myArray(4) As UByte = {4, 3, 1, 2, 5}
 PRINT "Max value is "; maxValue(myArray)
 ```
 
-In this example, is `ByRef` was omitted, it will be used by default, since the parameter was an array.
-Arrays cannot be passed [ByVAL](byval.md).
+When passing arrays like in this example, if `ByRef` can be omitted.
+Arrays parameters cannot be passed to a function using [ByVAL](byval.md).
 
 `ByRef` is also useful to return values in the parameters. [RETURN](return.md) allows to return a single value
 from a [FUNCTION](function.md), but we can return several values by storing the result in those parameters.

docs/byref.md

@@ -51,4 +51,6 @@ In fact, if the compiler detects the programmer is using `CHR(x) + CHR(y)`, it m
 
 ##See Also
 
+* [CODE](code.md)
 * [STR](str.md)
+* [VAL](val.md)

docs/chr.md

@@ -1,40 +1,42 @@
 #Installation
 
 ##Installation of ZX Basic SDK
-ZX Basic SDK comes in two flavours:
+ZX Basic SDK comes two several flavours:
 
-* Multiplatform (Linux / Windows / Mac) python scripts. This is the main distribution and recommended for everyone.
-* Windows .MSI Installer.
-
-The latest is only for Windows users who are not able or very lazy to use python scripts directly. This .MSI distribution is not updated as often as the Multiplatform one, but has the advantage of not requiring to have the python interpreter previously installed.
+* OS Specific binary package (the recommended way).<br />
+  For Windows, Mac OS and Linux
+* Multiplatform python scripts (will require Python 3.8+ to be installed in your system)
 
 ###Prerequisites
-For the _Multi-platform_ bundle, you will need the [python](http://www.python.org) interpreter **version 3.5** or
-higher installed on your system (Linux and Mac OS X users will probably have it already installed since
-it is very common on those operating systems).
-For Windows users, there's also a python interpreter from [ActiveState](http://www.activestate.com),
-the [ActivePython](http://www.activestate.com/store/download.aspx?prdGUID=b08b04e0-6872-4d9d-a722-7a0c2dea2758)
-interpreter, 100% python compatible (Windows users who choose the .ZIP package distribution does not need to install
-any python interpreter).
+For the _Multi-platform_ bundle, you will need a [python](http://www.python.org) interpreter **version 3.8** or
+higher installed in your system (Linux and Mac OS X users will probably have it already).
 
 ###Downloading
-To get the latest version of the ZX BASIC SDK, go to the [Download Page](http://www.boriel.com/files/zxb/),
-and get the `tar.gz` or `.ZIP` file you want. The .ZIP files are _Multiplatform_ (Linux / Windows / Mac), except those
-with the `win32` suffix, which are for Windows only.
-
-###Installing
-Installing the .MSI distribution is pretty straightforward:
-They **do not require any installation**. Just uncompress the SDK tree in a directory of your choice and make sure
-that folder is included in your PATH environment variable.
+To get the latest version of the ZX BASIC SDK, head to [Download Page](https://zxbasic.readthedocs.io/en/docs/archive/),
+and get the file you want.
 
+###Installation
+Installation is pretty straightforward: Just uncompress the SDK tree in a directory of your choice and make sure
+the folder is included in your PATH environment variable.
 
 ##Testing your installation
-For the .ZIP distribution, type **zxb.py** (in windows you can type **zxb**).
+For the binary distribution type **zxbc** (ensure this file is in your PATH).
 You should see something like:
 ```
- >zxb.py
- Usage: zxb.py <input file> [options]
+ >zxbc
+ Usage: zxbc <input file> [options]
  
- zxb.py: error: missing input file. (Try -h)
+ zxbc: error: missing input file. (Try -h)
+```
+
+For the python distribution type **zxbc.py** (in windows you can type **zxbc**).
+You should see something like:
 ```
+ >zxbc.py
+ Usage: zxbc.py <input file> [options]
+ 
+ zxbc.py: error: missing input file. (Try -h)
+```
+
 Ok, the compiler is working (or it seems so). Now you should proceed to the following section to learn about its usage.
+

docs/installation.md

@@ -1,6 +1,7 @@
 #Operators
 
-Operators in ZX Basic ranges from arithmetical and logical to bitwise ones.
+Operators in ZX Basic can be arithmetical, logical and [bitwise](bitwiselogic.md) ones.
+For bitwise operators checks the [Bitwise Operators](bitwiselogic.md) page.
 
 ## Arithmetic Operators