update real and string docs

Author: braindigitalis

docpages/basic-language-reference/functions/integer/02_INDEX.md

@@ -43,7 +43,7 @@
 - \subpage PEEKQ
 - \subpage PEEKW
 - \subpage RADIX
-- \subpage READ
+- \subpage IREAD
 - \subpage RGB
 - \subpage RND
 - \subpage SECOND

docpages/basic-language-reference/functions/integer/READ.md

@@ -1,4 +1,4 @@
-\page READ READ Function
+\page IREAD READ Function
 
 ```basic
 READ(integer-variable)

docpages/basic-language-reference/functions/real/03_INDEX.md

@@ -16,4 +16,5 @@
 - \subpage REALVAL
 - \subpage ROUND
 - \subpage SIN
+- \subpage SQR
 - \subpage TAN

docpages/basic-language-reference/functions/real/ACS.md

@@ -1,7 +1,55 @@
 \page ACS ACS Function
-```
+
+```basic
 ACS(real-expression)
 ```
-Returns the arc cosine (inverse cosine) of the provided expression, in radians.
 
-The input must be between -1 and 1.
+Returns the **arc cosine** (inverse cosine) of the given expression, in **radians**.
+The input must be between `-1` and `1`.
+
+---
+
+### Examples
+
+```basic
+PRINT ACS(1)
+```
+
+Produces `0`.
+
+```basic
+PRINT ACS(0)
+```
+
+Produces approximately `1.570796` (π/2).
+
+```basic
+PRINT ACS(-1)
+```
+
+Produces approximately `3.141593` (π).
+
+```basic
+REM Validate a cosine identity
+angle# = 0.75
+PRINT ACS(COS(angle#))
+```
+
+Produces the original angle (within floating point accuracy).
+
+---
+
+### Notes
+
+* Argument range: `-1 ≤ x ≤ 1`. Values outside this range cause an error.
+* Return range: `0 ≤ result ≤ π` radians.
+* To convert the result to degrees, multiply by `180 / PI`.
+* Inverse functions:
+
+  * \ref ASN "ASN" (arc sine)
+  * \ref ATN "ATN" (arc tangent)
+
+---
+
+**See also:**
+\ref COS "COS" · \ref ASN "ASN" · \ref ATN "ATN" · \ref TAN "TAN"

docpages/basic-language-reference/functions/real/ASN.md

@@ -1,7 +1,55 @@
 \page ASN ASN Function
-```
+
+```basic
 ASN(real-expression)
 ```
-Returns the arc sine (inverse sine) of the provided expression, in radians.
 
-The input must be between -1 and 1.
+Returns the **arc sine** (inverse sine) of the given expression, in **radians**.
+The input must be between `-1` and `1`.
+
+---
+
+### Examples
+
+```basic
+PRINT ASN(0)
+```
+
+Produces `0`.
+
+```basic
+PRINT ASN(1)
+```
+
+Produces approximately `1.570796` (π/2).
+
+```basic
+PRINT ASN(-1)
+```
+
+Produces approximately `-1.570796` (-π/2).
+
+```basic
+REM Validate a sine identity
+angle# = 0.5
+PRINT ASN(SIN(angle#))
+```
+
+Produces the original angle (within floating point accuracy).
+
+---
+
+### Notes
+
+* Argument range: `-1 ≤ x ≤ 1`. Values outside this range cause an error.
+* Return range: `-π/2 ≤ result ≤ π/2` radians.
+* To convert the result to degrees, multiply by `180 / PI`.
+* Inverse functions:
+
+  * \ref ACS "ACS" (arc cosine)
+  * \ref ATN "ATN" (arc tangent)
+
+---
+
+**See also:**
+\ref SIN "SIN" · \ref ACS "ACS" · \ref ATN "ATN" · \ref TAN "TAN"

docpages/basic-language-reference/functions/real/ATAN.md

@@ -1,7 +1,53 @@
 \page ATAN ATAN Function
-```
+
+```basic
 ATAN(real-expression)
 ```
-Returns the arc tangent of the provided expression (in radians).
 
-The result will be between `-PI#/2` and `PI#/2`.
+Returns the **arc tangent** (inverse tangent) of the given expression, in **radians**.
+
+The result will always lie between `-PI#/2` and `PI#/2`.
+
+---
+
+### Examples
+
+```basic
+PRINT ATAN(0)
+```
+
+Produces `0`.
+
+```basic
+PRINT ATAN(1)
+```
+
+Produces approximately `0.785398` (π/4).
+
+```basic
+PRINT ATAN(-1)
+```
+
+Produces approximately `-0.785398` (-π/4).
+
+```basic
+REM Validate a tangent identity
+angle# = 0.3
+PRINT ATAN(TAN(angle#))
+```
+
+Produces the original angle (within floating point accuracy).
+
+---
+
+### Notes
+
+* Input range: any real number is valid.
+* Return range: `-π/2 ≤ result ≤ π/2` radians.
+* To convert the result to degrees, multiply by `180 / PI`.
+* For quadrant-aware arc tangent with two arguments (x,y), use \ref ATAN2 "ATAN2".
+
+---
+
+**See also:**
+\ref TAN "TAN" · \ref ATAN2 "ATAN2" · \ref ACS "ACS" · \ref ASN "ASN"

docpages/basic-language-reference/functions/real/ATAN2.md

@@ -1,7 +1,58 @@
 \page ATAN2 ATAN2 Function
-```
+
+```basic
 ATAN2(real-y, real-x)
 ```
-Returns the arc tangent of y / x, using the signs of both arguments to determine the correct quadrant.
 
-The result will be between `-PI#` and `PI#`.
+Returns the **arc tangent of y ÷ x**, using the signs of both arguments to determine the correct **quadrant** of the angle.
+The result is given in **radians**, in the range `-PI#` to `PI#`.
+
+---
+
+### Examples
+
+```basic
+PRINT ATAN2(1, 1)
+```
+
+Produces approximately `0.785398` (π/4).
+
+```basic
+PRINT ATAN2(1, -1)
+```
+
+Produces approximately `2.356194` (3π/4).
+
+```basic
+PRINT ATAN2(-1, -1)
+```
+
+Produces approximately `-2.356194` (-3π/4).
+
+```basic
+PRINT ATAN2(-1, 1)
+```
+
+Produces approximately `-0.785398` (-π/4).
+
+```basic
+REM Compute angle of a vector
+dx# = 3
+dy# = 4
+angle# = ATAN2(dy#, dx#)
+PRINT "Angle = "; angle#; " radians"
+```
+
+---
+
+### Notes
+
+* Unlike \ref ATAN "ATAN", which only returns results in `-π/2 … π/2`, `ATAN2` resolves the full circle by considering both `x` and `y` signs.
+* Input range: both arguments may be any real numbers.
+* Return range: `-π ≤ result ≤ π` radians.
+* To convert to degrees, multiply by `180 / PI`.
+
+---
+
+**See also:**
+\ref ATAN "ATAN" · \ref SIN "SIN" · \ref COS "COS" · \ref TAN "TAN"

docpages/basic-language-reference/functions/real/CEIL.md

@@ -1,7 +1,45 @@
 \page CEIL CEIL Function
-```
+
+```basic
 CEIL(real-expression)
 ```
-Rounds the provided value up to the nearest integer.
 
-For example, CEIL(3.2) returns 4.
+Rounds the provided real value **upwards** to the nearest integer.
+The result is the smallest integer greater than or equal to the input.
+
+---
+
+### Examples
+
+```basic
+PRINT CEIL(3.2)
+```
+
+Produces `4`.
+
+```basic
+PRINT CEIL(-3.2)
+```
+
+Produces `-3`.
+
+```basic
+REM Use CEIL to calculate number of pages needed
+items = 23
+perPage = 10
+pages = CEIL(items / perPage)
+PRINT "Pages required = "; pages
+```
+
+---
+
+### Notes
+
+* Always rounds **towards positive infinity**.
+* Return type is a 64-bit integer.
+* Differs from \ref INT "INT", which truncates towards zero, and \ref ROUND "ROUND", which rounds to the nearest integer.
+
+---
+
+**See also:**
+\ref FLOOR "FLOOR" · \ref INT "INT" · \ref ROUND "ROUND"

docpages/basic-language-reference/functions/real/COS.md

@@ -1,6 +1,54 @@
 \page COS COS Function
+
 ```basic
 COS(real-expression)
 ```
-Returns the cosine of the provided expression
 
+Returns the **cosine** of the given angle, where the angle is expressed in **radians**.
+
+---
+
+### Examples
+
+```basic
+PRINT COS(0)
+```
+
+Produces `1`.
+
+```basic
+PRINT COS(PI# / 2)
+```
+
+Produces approximately `0`.
+
+```basic
+PRINT COS(PI#)
+```
+
+Produces `-1`.
+
+```basic
+REM Plot cosine values for multiples of 45 degrees
+FOR d = 0 TO 360 STEP 45
+    r# = d * PI# / 180
+    PRINT "COS("; d; "°) = "; COS(r#)
+NEXT
+```
+
+---
+
+### Notes
+
+* Argument is in **radians**. Convert degrees to radians with:
+
+  ```basic
+  radians# = degrees * PI# / 180
+  ```
+* Return value is a real number between `-1` and `1`.
+* Related inverse function: \ref ACS "ACS".
+
+---
+
+**See also:**
+\ref SIN "SIN" · \ref TAN "TAN" · \ref ACS "ACS" · \ref ATAN "ATAN"