Merge pull request #986 from boriel-basic/docs

Docs

Author: boriel

docs/cos.md

@@ -14,7 +14,7 @@ Argument must be a numeric expression in radians units. Returned value type is [
 
 ## Examples
 
-```
+```basic
 REM Cosine value
 PRINT "Cosine value of a is "; COS(a)
 ```
@@ -30,4 +30,4 @@ PRINT "Cosine value of a is "; COS(a)
 * [SIN](sin.md) and [ASN](asn.md)
 * [TAN](tan.md) and [ATN](atn.md)
 * [ACS](acs.md)
-*  Faster library option for lower accuracy trigonometry for games: [FCOS](fsin.bas.md)
+*  Faster library option for lower accuracy trigonometry for games: [FCOS](library/fsin.bas.md)

docs/index.md

@@ -1,4 +1,5 @@
-# General
+## General
+
 * [About](about.md)
 <br />About Boriel BASIC SDK
 
@@ -14,18 +15,17 @@
 * [Command line options](zxb.md#Command_Line_Options)
 <br />Command line options table for the compiler (zxb)
 
-# Download
-
+## Download
 Get the latest version of Boriel BASIC from the [archive](archive.md).
 
-# Released programs
+## Released programs
 
 * [Released programs](released_programs.md)
 <br />A list of third-party released programs (mostly games) for the ZX-Spectrum developed with Boriel BASIC.
 
-# Learning Boriel BASIC
+## Learning Boriel BASIC
 
-## Language Reference
+### Language Reference
 * [Language syntax](syntax.md)
 <br />Language Syntax is very close to the original Sinclair BASIC, but it's expanded and enhanced.
 
@@ -38,7 +38,7 @@ Get the latest version of Boriel BASIC from the [archive](archive.md).
 * [Standard libraries](library/stdlib.md)
 <br />Standard libraries that comes bundled with Boriel BASIC compiler.
 
-## Tutorials
+### Tutorials
 * [Programming tutorials](tutorials.md)
 <br />A collection of third-party tutorials about development with Boriel BASIC.
 
@@ -48,31 +48,32 @@ Get the latest version of Boriel BASIC from the [archive](archive.md).
 * [Sample Games](sample_programs.md#Game Examples)
 <br />Some little games examples.
 
-# Help and Support
+## Help and Support
 
 * [Community Forum](http://www.boriel.com/forum)
 <br />Have a question? Need help or comment a report a bug? Go to the [Boriel BASIC forum](http://www.boriel.com/forum)
 
-# External resources
+## External resources
 
 * Here you are [external resources](external_resources.md): other tools, IDEs, graphic designers and projects related to Boriel BASIC. Have a look!
 
-# External libraries
+### External libraries
 
 * [Library](library.md)
 <br />Library of functions and subroutines you can use in your programs. You might find them really useful.
 
-# Inline assembler
+## Inline assembler
 Embedding inline assembler in your code is pretty easy. There's a [tutorial](tutorials.md) on it.
 
-# Compiler internals
+## Compiler internals
 Only for true hackers: This explains how the compiler does its job, how to expand it, etc.
+This is `work in progress`.
 
-# Other Architectures
+## Other Architectures
 Boriel BASIC was designed from the base as a Retargeable Compiler, so it should be not hard to extend
 it to other architectures. This is `work in progress`. See [other architectures](other_architectures.md) for more info.
 
-# Contributing
+## Contributing
 You can issue a Pull Request to the [GitHub repository](https://github.com/boriel/zxbasic), report bugs in the forum
 when using the compiler, suggest new features...
 

docs/library/fsin.bas.md

@@ -2,84 +2,91 @@
 
 ## Introduction
 
+This function implements fast `Fixed` point `sin`, `cos` and `tan` functions.
+The ones that uses `Float` type (calling the Sinclair ROM) are much slower as FP Calculations
+are expensive. This variant is less precise but more suitable for games, for example.
+
 `fSin` is the basis for the alternatives, since `COS(x)` can be calculated
-from `SIN(x)` and `TAN(x)` from `COS(x)` and `SIN(x)`.
+from `SIN(x)` and `TAN(x)` as `SIN(x)` / `COS(x)`.
+
+!!! info "Note"
+    This library is already bundled with Boriel BASIC.<br />
+    To use it just add `#include <fmath.bas>`
+    at the beginning of your program.
 
 The functions should be accurate to about 0.25%, and significantly faster.
 If you need a lot of trig in your code, and it doesn't need to be pinpoint accuracy, these are good alternatives.
-Note that they more or less acknowledge they are less accurate by returning values of type `Fixed` instead of type `Float`.
-I did this because it should be fine for the actual accuracy returned,
+Note that they more or less acknowledge they are less accurate by returning values of type `Fixed` instead
+of type `Float`.
+It should be fine for the actual accuracy returned,
 and `Fixed` numbers process faster and smaller than `Float` ones.
 
-* Note that you need only include `fSin` if you only want Sines, but you need fSin to use `fCos` or `fTan`.
+* Note that you need only include `fSin` if you only want Sines, but you need `fSin` to use `fCos` or `fTan`.
 
 * Note that these functions use degrees, not radians.
 
 ## SINE Function
 
-```
+```vbnet
 FUNCTION fSin(num as FIXED) as FIXED
-DIM quad as byte
-DIM est1,dif as uByte
-
-'This change made now that MOD works with FIXED types.
-'This is much faster than the repeated subtraction method for large angles (much > 360)
-'while having some tiny rounding errors that should not significantly affect our results.
-'Note that the result may be positive or negative still, and for SIN(360) might come out
-'fractionally above 360 (which would cause issued) so the below code still is required.
-
-IF num >= 360 THEN
-  num = num MOD 360
-ELSEIF num < 0 THEN
-  num = 360 - ABS(num) MOD 360
-END IF
-
-IF num>180 then
-  quad=-1
-  num=num-180
-ELSE
-  quad=1
-END IF
-
-IF num>90 then num=180-num
-
-num=num/2
-dif=num : rem Cast to byte loses decimal
-num=num-dif : rem so this is just the decimal bit
-
-
-est1=PEEK (@sinetable+dif)
-dif=PEEK (@sinetable+dif+1)-est1 : REM this is just the difference to the next up number.
-
-num=est1+(num*dif): REM base +interpolate to the next value.
-
-return (num/255)*quad
-
-
-sinetable:
-asm
-DEFB 000,009,018,027,035,044,053,062
-DEFB 070,079,087,096,104,112,120,127
-DEFB 135,143,150,157,164,171,177,183
-DEFB 190,195,201,206,211,216,221,225
-DEFB 229,233,236,240,243,245,247,249
-DEFB 251,253,254,254,255,255
-end asm
+  DIM quad as byte
+  DIM est1,dif as uByte
+
+  'This change made now that MOD works with FIXED types.
+  'This is much faster than the repeated subtraction method for large angles (much > 360)
+  'while having some tiny rounding errors that should not significantly affect our results.
+  'Note that the result may be positive or negative still, and for SIN(360) might come out
+  'fractionally above 360 (which would cause issued) so the below code still is required.
+
+  IF num >= 360 THEN
+    num = num MOD 360
+  ELSEIF num < 0 THEN
+    num = 360 - ABS(num) MOD 360
+  END IF
+
+  IF num > 180 then
+    quad = -1
+    num = num - 180
+  ELSE
+    quad = 1
+  END IF
+
+  IF num > 90 THEN num = 180 - num
+
+  num = num / 2
+  dif = num : REM Cast to byte loses decimal
+  num = num - dif : REM so this is just the decimal bit
+
+  est1 = PEEK(@sinetable + dif)
+  dif = PEEK(@sinetable + dif + 1) - est1 : REM this is just the difference to the next up number.
+  num = est1 + (num * dif) : REM base + interpolate to the next value.
+
+  Return (num / 255) * quad
+
+  sinetable:
+  Asm
+    DEFB 000,009,018,027,035,044,053,062
+    DEFB 070,079,087,096,104,112,120,127
+    DEFB 135,143,150,157,164,171,177,183
+    DEFB 190,195,201,206,211,216,221,225
+    DEFB 229,233,236,240,243,245,247,249
+    DEFB 251,253,254,254,255,255
+  End Asm
 END FUNCTION
 ```
 
 ## COSINE Function
 
-```
+```vbnet
 FUNCTION fCos(num as FIXED) as FIXED
-    return fSin(90-num)
+    Return fSin(90 - num)
 END FUNCTION
 ```
 
 ## TANGENT Function
 
-```
+```vbnet
 FUNCTION fTan(num as FIXED) as FIXED
-    return fSin(num)/fSin(90-num)
+    Return fSin(num) / fSin(90 - num)
 END FUNCTION
 ```

docs/overrides/stylesheets/extra.css

@@ -9,21 +9,29 @@
 /* Apply Sinclair Logo font to the main header */
 /* Light mode - very light yellow header */
 [data-md-color-scheme="default"] .md-header {
-  background-color: #264eb2; /* Very light yellow background color */
+  background-color: #d0d6da; /* Very light yellow background color */
+  height: 4rem;
 }
 
 
 [data-md-color-scheme="default"] .md-header__title {
-  color: #ffde06;
+  color: #23231c;
+  padding-left: 2rem;
 }
 
 /* Dark mode - dark gray header */
 [data-md-color-scheme="slate"] .md-header {
   background-color: #333333; /* Dark gray background color */
+  /*background-image: url('../img/boriel-basic-sinclair.png');*/
+  /*background-repeat: no-repeat;*/
+  /*background-position: center center;*/
+  /*background-size: auto 90%;*/
+  height: 4rem;
 }
 
 [data-md-color-scheme="slate"] .md-header__title {
   color: #af0d0d;
+  padding-left: 2rem;
 }
 
 .md-header__title {
@@ -40,11 +48,13 @@
   background-repeat: no-repeat;
   background-position: left center;
   background-size: auto 100%;
+  height: 100%;
 }
 
 /*!* Make the logo size 100% of the header *!*/
 .md-header__button.md-logo {
   color: #ff000000;
+  height: 100%;
 }
 
 /* Increase font weight for headings */
@@ -54,11 +64,16 @@ h1, h2, h3, h4, h5, h6 {
 }
 
 /* Target Material theme specific heading classes if any */
-.md-typeset h1, 
-.md-typeset h2, 
-.md-typeset h3, 
-.md-typeset h4, 
-.md-typeset h5, 
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4,
+.md-typeset h5,
 .md-typeset h6 {
   font-weight: 600; /* Bold */
 }
+
+.md-typeset .admonition,
+.md-typeset details {
+  font-size: 0.75rem
+}

docs/types.md

@@ -1,6 +1,6 @@
 # Types
 
-## Introductions
+## Introduction
 
 Although ZX BASIC was originally designed with ZX Spectrum in mind, it is a three-stage _retargeable_ compiler. This means it should not be difficult to hack ZX BASIC SDK to compile for other target machines (E.g. Commodore 64) or current machines (PC) or even virtual machines like Java or .NET. Porting ZX BASIC to other Z80 architectures like Amstrad or MSX should be almost straightforward (only the library.asm should need some work to use different ROM routines).
 
@@ -25,14 +25,14 @@ They can be _unsigned_ (their value is always 0 or positive) or _signed_ (can ta
 ZX Basic integer types sizes are 8, 16 and 32 bits. Unsigned types have the prefix _U_.
 
 
-| Type name | Size (bytes) | Signed? | Range | Description |
-|:-----------|:-----:|:--------:|:------:|:-------------|
-| Byte | 1 | yes | -128..127  | 8 bits signed integer  |
-| UByte| 1 | no | 0..255  | 8 bits unsigned integer  |
-| Integer | 2 | yes | -32768..32767 | 16 bits signed integer |
-| UInteger | 2 | no | 0..65535 | 16 bits unsigned integer |
-| Long | 4 | yes |  <small>−2,147,483,648 .. +2,147,483,647</small> | 32 bit signed integer |
-| ULong | 4 | yes | <small>0 .. 4,294,967,295</small>| 32 bit unsigned integer |
+| Type name | Size (bytes) | Signed? |                      Range                      | Description              |
+|:----------|:------------:|:-------:|:-----------------------------------------------:|:-------------------------|
+| Byte      |      1       |   yes   |                    -128..127                    | 8 bits signed integer    |
+| UByte     |      1       |   no    |                     0..255                      | 8 bits unsigned integer  |
+| Integer   |      2       |   yes   |                  -32768..32767                  | 16 bits signed integer   |
+| UInteger  |      2       |   no    |                    0..65535                     | 16 bits unsigned integer |
+| Long      |      4       |   yes   | <small>−2,147,483,648 .. +2,147,483,647</small> | 32 bit signed integer    |
+| ULong     |      4       |   yes   |        <small>0 .. 4,294,967,295</small>        | 32 bit unsigned integer  |
 
 
 ### Decimals
@@ -41,7 +41,7 @@ Their sizes are 32 bit for `Fixed` type and 40 bits for `Float` one.
 
 #### Fixed
 32 bit Fixed Point decimal. First 16 bits are the integer part, whilst remaining 16 contains the decimal one.
-Ranges from -32767.9999847 to 32767.9999847 with a precision of 1 / 2^16 (0.000015 approx.).
+Ranges from `-32767.9999847` to `32767.9999847` with a precision of 1 / 2<sup>16</sup> (0.000015 approx.).
 Fixed points decimal are less precise than Floating ones, but much faster and requires
 less space (1 byte less). Also, their range is much limited.
 They're usually used on screen drawing when Floating point is too slow and decimal
@@ -50,7 +50,8 @@ calculations are required.
 #### Float
 Floating point type is **identical** to the Sinclair BASIC one.
 It requires 5 bytes (1 byte for exponent, 4 bytes for mantissa).
-Read the ZX Spectrum manual or [here](http://www.worldofspectrum.org/ZXBasicManual/zxmanchap24.html).
+Read the [Chapter 24 of the ZX Spectrum manual](http://www.worldofspectrum.org/ZXBasicManual/zxmanchap24.html)
+for further information.
 
 >To store the number in the computer, we use five bytes, as follows:
 >
@@ -75,7 +76,7 @@ At this moment, ZX BASIC is not an <abbr title="Object Oriented Programming">OOP
 Vars are _scalar_ variables. Scalar variables are those which store a single value.
 Almost all variables are scalars:
 
-```
+```basic
 REM A simple scalar variable
 DIM a = 3
 ```
@@ -85,7 +86,7 @@ DIM a = 3
 Unlike scalars, array variables can hold more than a single value at once.
 You access a single value within the array container using an integer _index_:
 
-```
+```basic
 REM An array variable
 DIM a(1 TO 10) AS UBYTE
 LET a(3) = 5: REM pick a(3) cell and store the number 5 in it
@@ -97,7 +98,7 @@ Unlike the above, [labels](labels.md) are not variables.
 They refer to memory positions. Line numbers are also treated as labels and they are completely optional:
 
 
-```
+```basic
 10 REM here '10' is a Label
  5 REM here '5' is another label, so the number order does not matter
    REM Line numbers are optional. So this line is ok either.