Merge pull request boriel-basic#644 from boriel/docs

Docs

docs/cast.md

@@ -1,24 +1,24 @@
-#CAST
+# CAST
 
-##Syntax
+## Syntax
 
 ```
 CAST (type,numeric value)
 CAST (type,variable)
 CAST (type,function(data))
 ```
 
-##Description
+## Description
 
 Returns a value of the [type](types.md) specified with a value equivalent to the item specified, if that is possible.
 
-##Remarks
+## Remarks
 
 * This function can lose precision if used indiscriminately.
 For example, CAST(Integer,PI) returns 3, losing precision on the value of PI.
 * This function is NOT Sinclair Compatible.
 
-##See also
+## See also
 
 * [Types](types.md)
 

docs/if.md

@@ -1,8 +1,8 @@
-#IF ... END IF
+# IF ... END IF
 
 **IF** is a very powerful control flow sentence that allows you to _make decisions_ under specified contitions.
 
-##Syntax
+## Syntax
 ```
  IF expression [THEN] sentences [: END IF]
 
@@ -19,7 +19,7 @@ or
  END IF
 
 ```
-###Examples
+### Examples
 ```
 IF a < 5 THEN PRINT "A is less than five" ELSE PRINT "A is greater than five"
 ```
@@ -53,7 +53,7 @@ End If
 ```
 
 
-##Using ELSEIF
+## Using ELSEIF
 In the example above, you see that nesting an **IF** inside another one could be somewhat verbose and error prone. It's better to use 
 the **ELSEIF** construct. So the previous example could be rewritten as:
 
@@ -71,12 +71,12 @@ End If
 ```
 
 
-##Remarks
+## Remarks
 * This sentence is **extended** allowing now multiline IFs and also compatible with the Sinclair BASIC version.
 * Starting from version 1.8 onwards the trailing **END IF** is not mandatory for single-line IFs, for compatibility with Sinclair BASIC
 * The **THEN** keyword can be omitted, but keep in mind this might reduce code legibility.
 
-##See Also
+## See Also
 * [WHILE ... END WHILE](while.md)
 * [DO ... LOOP](do.md)
 * [FOR ... NEXT](for.md)

docs/in.md

@@ -0,0 +1,37 @@
+# IN
+
+
+## Syntax
+
+```
+IN <port number>
+```
+
+
+## Description
+
+Returns the byte value read in the given port.
+Argument must be a numeric expression. Returned value type is [Ubyte](types.md#Ubyte).
+
+## Examples
+
+```
+REM Port 254
+DIM i AS UInteger
+CLS
+PRINT "PRESS ANY KEY TO CHANGE THE READ VALUE"
+
+FOR i = 1 to 10000
+  PRINT AT 10, 0; IN 254;
+NEXT
+```
+
+
+## Remarks
+
+* This function is 100% Sinclair BASIC Compatible
+* If the given argument type is not `UInteger`, it will be [converted](cast.md) to `UInteger` before operating with it.
+
+## See also
+
+* [OUT](out.md)

docs/library/fsin.bas.md

@@ -22,20 +22,17 @@ FUNCTION fSin(num as FIXED) as FIXED
 DIM quad as byte
 DIM est1,dif as uByte
 
-num = num MOD 360 
 'This change made now that MOD works with FIXED types.
-'This is much faster than the repeated subtraction method for large angles (much > 360) 
+'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.
 
-while num>=360
-  num=num-360
-end while
-
-while num<0
-  num=num+360
-end while
+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
@@ -63,7 +60,7 @@ 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 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
@@ -86,4 +83,3 @@ FUNCTION fTan(num as FIXED) as FIXED
     return fSin(num)/fSin(90-num)
 END FUNCTION
 ```
-

docs/library/fsqrt.bas.md

@@ -3,7 +3,7 @@
 ##fSqrt
 
 ZX BASIC uses the ZX Spectrum ROM routine to calculate many of the floating point math functions.
-Unfortunately, some of the functions are notoriously slow. Square root being one of them - 
+Unfortunately, some of the functions are notoriously slow. Square root being one of them -
 there wasn't enough space in the original ROM design to do a good routine, so they cheated.
 They calculate x<sup>0.5</sup> instead, and roll straight into the exponent routine.
 It turns out that though this works, it's exceptionally slow.
@@ -22,21 +22,23 @@ REM By Britlion
 
 FUNCTION FASTCALL fSqrt (radicand as FLOAT) as FLOAT
 ASM
+        push namespace core
+
         ; FLOAT value arrives in A ED CB
         ; A is the exponent.
-          AND   A               ; Test for zero argument 
+          AND   A               ; Test for zero argument
           RET   Z               ; Return with zero.
-          
+
           ;Strictly we should test the number for being negative and quit if it is.
           ;But let's assume we like imaginary numbers, hmm?
           ; If you'd rather break it change to a jump to an error below.
           ;BIT   7,E          ; Test the bit.
-          ;JR    NZ,REPORT       ; back to REPORT_A 
+          ;JR    NZ,REPORT       ; back to REPORT_A
                                 ; 'Invalid argument'
           RES 7,E               ; Now it's a positive number, no matter what.
-          
+
           call __FPSTACK_PUSH   ; Okay, We put it on the calc stack. Stack contains ABS(x)
-                    
+
           ;   Halve the exponent to achieve a good guess.(accurate with .25 16 64 etc.)
 
                                 ; Remember, A is the exponent.
@@ -50,32 +52,34 @@ ASM
 ASIS:     XOR   $80             ; restore sign.
           call __FPSTACK_PUSH   ; Okay, NOW we put the guess on the stack
           rst  28h   ; ROM CALC    ;;guess,x
-          DEFB $C3              ;;st-mem-3              
-          DEFB $02              ;;delete                
-
-SQRLOOP:  DEFB  $31             ;;duplicate             
-          DEFB  $E3             ;;get-mem-3             
-          DEFB  $C4             ;;st-mem-4              
-          DEFB  $05             ;;div                   
-          DEFB  $E3             ;;get-mem-3             
-          DEFB  $0F             ;;addition              
-          DEFB  $A2             ;;stk-half              
-          DEFB  $04             ;;multiply              
-          DEFB  $C3             ;;st-mem-3              
-          DEFB  $E4             ;;get-mem-4             
-          DEFB  $03             ;;subtract              
-          DEFB  $2A             ;;abs                   
-          DEFB  $37             ;;greater-0             
-          DEFB  $00             ;;jump-true             
-
-          DEFB  SQRLOOP - $     ;;to sqrloop              
-
-          DEFB  $02             ;;delete                
-          DEFB  $E3             ;;get-mem-3             
+          DEFB $C3              ;;st-mem-3
+          DEFB $02              ;;delete
+
+SQRLOOP:  DEFB  $31             ;;duplicate
+          DEFB  $E3             ;;get-mem-3
+          DEFB  $C4             ;;st-mem-4
+          DEFB  $05             ;;div
+          DEFB  $E3             ;;get-mem-3
+          DEFB  $0F             ;;addition
+          DEFB  $A2             ;;stk-half
+          DEFB  $04             ;;multiply
+          DEFB  $C3             ;;st-mem-3
+          DEFB  $E4             ;;get-mem-4
+          DEFB  $03             ;;subtract
+          DEFB  $2A             ;;abs
+          DEFB  $37             ;;greater-0
+          DEFB  $00             ;;jump-true
+
+          DEFB  SQRLOOP - $     ;;to sqrloop
+
+          DEFB  $02             ;;delete
+          DEFB  $E3             ;;get-mem-3
           DEFB  $38             ;;end-calc              sqr x.
 
           jp __FPSTACK_POP
-          
+
+          pop namespace
+
 END ASM
 END FUNCTION
 ```

docs/out.md

@@ -0,0 +1,39 @@
+# OUT
+
+
+## Syntax
+
+```
+OUT <port number>, <value>
+```
+
+
+## Description
+
+Sends the byte value to the given port.
+Arguments must be a numeric expressions. Port will be converted to `UInteger`
+and value will be truncated to `UByte`.
+
+## Examples
+
+```
+REM Port 254
+DIM i AS UInteger
+CLS
+
+FOR i = 1 to 10000
+  OUT 254, i
+NEXT
+```
+
+
+## Remarks
+
+* This function is 100% Sinclair BASIC Compatible
+* If the given port is not of type`UInteger`, it will be [converted](cast.md) to `UInteger` before operating with it.
+* If the given value is not of type`Ubyte`, it will be [converted](cast.md) to `UByte` before operating with it.
+
+
+## See also
+
+* [IN](in.md)