diff --git a/docs/about.md b/docs/about.md index a3ca27f35..3a9350ccb 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,20 +1,21 @@ # About -## About the ZX BASIC Project +## About the Boriel BASIC Project -ZX BASIC is a [BASIC](http://en.wikipedia.org/wiki/BASIC) ''cross compiler''. -It will compile BASIC programs (in your PC) for your [ZX Spectrum](http://en.wikipedia.org/wiki/Sinclair_ZX_Spectrum). -ZX BASIC is an SDK entirely written in [python](http://www.python.org). -The SDK is implemented using the [PLY](http://www.dabeaz.com/ply/) (Python Lex/Yacc) compiler tool. -It translates BASIC to Z80 assembler code, so it is easily portable to other Z80 platforms (Amstrad, MSX). -Other non Z80 targets could also be available in the future. +Boriel BASIC (formerly known as _ZX BASIC_ and _Boriel ZX BASIC_) is a [BASIC](https://en.wikipedia.org/wiki/BASIC) ''cross compiler''. +It will compile BASIC programs (in your PC) for your [ZX Spectrum](https://en.wikipedia.org/wiki/Sinclair_ZX_Spectrum). +Boriel BASIC is an SDK entirely written in [python](https://www.python.org). +The SDK is implemented using the [PLY](https://www.dabeaz.com/ply/) (Python Lex/Yacc) compiler tool. +It translates BASIC to Z80 assembler code, so it is easily portable to other Z80 platforms (Amstrad CPC, MSX). +Other non-Z80 targets could also be available in the future. -ZX BASIC syntax tries to maintain compatibility as much as possible with -[Sinclair BASIC](http://en.wikipedia.org/wiki/Sinclair_BASIC), it also have many new features, mostly taken from -[FreeBASIC](http://www.freebasic.net/wiki) dialect. +Boriel BASIC syntax tries to maintain as much compatibility as possible to that of +[Sinclair BASIC](https://en.wikipedia.org/wiki/Sinclair_BASIC), but it also has many new features, mostly taken from +[FreeBASIC](https://www.freebasic.net/wiki) dialect. ### Platform Availability -Since it is written in python, it is available for many platforms, like Windows, Linux and Mac. -You only need to have python installed on these. For windows, there also is an installable (.MSI) _compiled_ -version, which does not need python previously installed. + +Boriel BASIC is available _natively_ for Windows (32bit and 64bit) and Linux (x64). For other platforms (i.e. Mac OS) +you will need to have Python 3.12+ installed in your computer and download the version _with Python scripts_ from +the [Archive](archive.md) page. diff --git a/docs/abs.md b/docs/abs.md index 40d014e46..549460531 100644 --- a/docs/abs.md +++ b/docs/abs.md @@ -3,7 +3,7 @@ ## Syntax -``` +```basic ABS(numericExpression) ``` @@ -11,12 +11,12 @@ ABS(numericExpression) ## Description Returns the absolute value of the given argument. -Argument must be a numeric expression. Returned value has the same type as the input argument. +Argument must be a numeric expression. The returned value has the same type as the input argument. ## Examples -``` +```basic REM Absolute value LET a = -1 PRINT "Absolute value of a is "; ABS(a) diff --git a/docs/archive.md b/docs/archive.md index b2b03a8ee..003b59e2f 100644 --- a/docs/archive.md +++ b/docs/archive.md @@ -2,7 +2,7 @@ ## Source Code You can checkout the latest source code from the repository. -See [https://github.com/boriel-basic/zxbasic](http://github.com/boriel/zxbasic) for instructions on how to clone the +See [https://github.com/boriel-basic/zxbasic](http://github.com/boriel-basic/zxbasic) for instructions on how to clone the repository (git). @@ -10,7 +10,7 @@ repository (git). You can contribute to ZX BASIC by reporting possible bugs or improvement suggestions at the [forum](http://www.boriel.com/forum) or in social media. -Latest stable version is **1.18.1**. +The latest stable version is **1.18.1**. Click on the desired icon below to download the package suitable for your platform: * [win32zip @@ -36,7 +36,7 @@ in your system). ### What's new To check out what's new on every version, have a look at the -[Changelog](https://github.com/boriel/zxbasic/blob/master/Changelog.md) file. +[Changelog](https://github.com/boriel-basic/zxbasic/blob/master/CHANGELOG.md) file. ## Older versions This is the official ZX Basic archive. If you require an older ZX BASIC version, please have a look diff --git a/docs/dim.md b/docs/dim.md index b829cff52..24538d87a 100644 --- a/docs/dim.md +++ b/docs/dim.md @@ -12,7 +12,7 @@ A [type](types.md) is a name for the kind of data (`Integer`, `Byte`, `String`, DIM [,...] [AS ] [= ] ``` -Where __ can be one of **INTEGER**, **BYTE**, **FLOAT**, etc. +Where `` can be one of **INTEGER**, **BYTE**, **FLOAT**, etc. See the list of [available types](types.md). If type is not specified, **FLOAT** will be used, unless you use a suffix (usually called _sigil_) like `$` or `%`. @@ -46,7 +46,7 @@ Declaring a variable that has already been referenced in previous lines will res ### Examples of variable declarations -``` +```basic REM Declares 'a' as a 16 bit signed integer variable DIM a AS INTEGER diff --git a/docs/examples/4inarow.bas.md b/docs/examples/4inarow.bas.md index 539c4a840..42a45cefd 100644 --- a/docs/examples/4inarow.bas.md +++ b/docs/examples/4inarow.bas.md @@ -1,11 +1,11 @@ # 4 in a Row - Program: 4inarow.bas +## Program: 4inarow.bas This program first appeared in MicroHobby ZX Spectrum Spanish magazine. It has a nice AI in BASIC that plays smartly against the human in only 16Kb! -``` +```basic 0 REM From MicroHOBBY magazine, Num. 18, page 27 :') 1 BORDER 1: PAPER 1: INK 7: CLS : PRINT AT 10,10; FLASH 1;"STOP THE TAPE": PAUSE 200 5 DIM M(8,6): DIM p,pp,n as FLOAT diff --git a/docs/examples/circle.bas.md b/docs/examples/circle.bas.md index 533b3bdc4..4d3682e51 100644 --- a/docs/examples/circle.bas.md +++ b/docs/examples/circle.bas.md @@ -1,10 +1,9 @@ # Circle.Bas -``` -Program: circle.bas -``` +## Program: circle.bas -``` + +```basic REM Sample circle drawing without using the CIRCLE command DIM i, r, x, y, q as FLOAT diff --git a/docs/examples/clock.bas.md b/docs/examples/clock.bas.md index 49f0dd6cc..85f9d529d 100644 --- a/docs/examples/clock.bas.md +++ b/docs/examples/clock.bas.md @@ -1,9 +1,8 @@ # Clock.Bas -``` - Program: clock.bas -``` -``` +## Program: clock.bas + +```basic REM From the ZX Spectrum MANUAL REM A Clock program diff --git a/docs/examples/clock2.bas.md b/docs/examples/clock2.bas.md index 8ad4bbfe3..598ba2402 100644 --- a/docs/examples/clock2.bas.md +++ b/docs/examples/clock2.bas.md @@ -1,9 +1,8 @@ # Clock2.Bas -``` - Program: clock2.bas -``` -``` +## Program: clock2.bas + +```basic REM From the ZX Spectrum MANUAL REM A Clock program diff --git a/docs/examples/colors.bas.md b/docs/examples/colors.bas.md index c07325bf0..a53c4fc24 100644 --- a/docs/examples/colors.bas.md +++ b/docs/examples/colors.bas.md @@ -1,9 +1,8 @@ # Colors.bas -``` - Program: colors.bas -``` -``` +## Program: colors.bas + +```basic REM From the ZX Spectrum 48K Manual DIM m, n, c AS BYTE diff --git a/docs/examples/fact.bas.md b/docs/examples/fact.bas.md index c018eab68..8f1c70a52 100644 --- a/docs/examples/fact.bas.md +++ b/docs/examples/fact.bas.md @@ -1,9 +1,8 @@ # Fact.bas -``` - Program: fact.bas -``` -``` +## Program: fact.bas + +```vbnet REM Factorial recursive test function fact(x as ulong) as ulong diff --git a/docs/examples/flag.bas.md b/docs/examples/flag.bas.md index 2ce435ff2..ee5b9a707 100644 --- a/docs/examples/flag.bas.md +++ b/docs/examples/flag.bas.md @@ -1,10 +1,8 @@ # Flag.bas -``` - Program: flag.bas -``` +## Program: flag.bas -``` +```basic 5 REM union flag (from the ZX Spectrum Manual) 7 DIM n AS UInteger: REM Needed to avoid overflow at line 530 diff --git a/docs/examples/fractal.bas.md b/docs/examples/fractal.bas.md index 70f785fa7..b44dcd6c5 100644 --- a/docs/examples/fractal.bas.md +++ b/docs/examples/fractal.bas.md @@ -1,11 +1,10 @@ # Fractal.bas -``` -Program: fractal.bas by @Britlion -``` +## Program: fractal.bas +by @Britlion -``` +```vbnet # define width 256 # define height 192 diff --git a/docs/examples/freregustav.bas.md b/docs/examples/freregustav.bas.md index 4756ced27..20efc11d3 100644 --- a/docs/examples/freregustav.bas.md +++ b/docs/examples/freregustav.bas.md @@ -1,9 +1,8 @@ # FrereGustav.bas -``` - Program: freregustav.bas -``` -``` +## Program: freregustav.bas + +```basic REM Frere Gustav, from the ZX Spectrum 48K Manual, Chapter 19 PRINT "Frere Gustav" diff --git a/docs/examples/lines.bas.md b/docs/examples/lines.bas.md index 689598430..6bb0b9aec 100644 --- a/docs/examples/lines.bas.md +++ b/docs/examples/lines.bas.md @@ -1,10 +1,8 @@ # Lines.bas -``` - Program: lines.bas -``` +## Program: lines.bas -``` +```basic 5 REM From the ZX Spectrum manual on Drawing primitives 6 DIM x1, y1, x2, y2, c as Integer diff --git a/docs/examples/snake.bas.md b/docs/examples/snake.bas.md index ffbca05fd..30ff7201b 100644 --- a/docs/examples/snake.bas.md +++ b/docs/examples/snake.bas.md @@ -1,10 +1,8 @@ # Snake.Bas -``` - Program: snake.bas -``` +## Program: snake.bas -``` +```basic 1 REM ******************************************************************** 2 REM ZXSnake by Federico J. Alvarez Valero (2003-02-05) 10 REM This program is free software; you can redistribute it and/or modify diff --git a/docs/fastcall.md b/docs/fastcall.md index 869eeb17c..28ba17be3 100644 --- a/docs/fastcall.md +++ b/docs/fastcall.md @@ -38,5 +38,5 @@ The above function, when called with `whatLetter()` will return the ` when the inline assembly is reached. +* Note that the A register already contains `` when the inline assembly is reached. * Note that we do NOT need to put a ret opcode on the end of the assembly. The compiler will do that for us. diff --git a/docs/for.md b/docs/for.md index 3441b9b74..4f89e8aa9 100644 --- a/docs/for.md +++ b/docs/for.md @@ -55,7 +55,7 @@ Clearly, since the largest value a byte can hold is 255, it's not possible for i The variable will "wrap around" to 0 and as a result, the loop will not ever terminate. This can happen in much more subtle ways when `STEP` is used. There has to be "room" within the variable type for the iterator to exceed the terminator when it is being -incremented by amounts. +incremented by `` amounts. For example, this loop will neved end diff --git a/docs/identifier.md b/docs/identifier.md index 963b76efb..11b319bd7 100644 --- a/docs/identifier.md +++ b/docs/identifier.md @@ -38,7 +38,7 @@ Identifiers shown in bold are taken from the Sinclair BASIC (beware their meanin * [CONST](const.md) * **[CONTINUE](continue.md)** **(statement)** * **[COS](cos.md)** **(function)** -* **[DECLARE](declare.md)** **** +* **[DECLARE](declare.md)** **(modifier)** * **[DIM](dim.md)** **(statement)** * [DO](do.md) **(statement)** * **[DATA](data.md)** **(statement)** @@ -79,7 +79,7 @@ Identifiers shown in bold are taken from the Sinclair BASIC (beware their meanin * **[PAPER](paper.md)** **(statement)** * **[PAUSE](pause.md)** **(statement)** * **[PEEK](peek.md)** **(function)** -* **[PI](pi.md)** **** +* **[PI](pi.md)** **(constant)** * **[PLOT](plot.md)** **(statement)** * **[POKE](poke.md)** **(statement)** * **[PRINT](print.md)** **(statement)** @@ -91,8 +91,8 @@ Identifiers shown in bold are taken from the Sinclair BASIC (beware their meanin * **[RND](rnd.md)** **(function)** * **[SAVE](load.md)** **(statement)** * **[SGN](sgn.md)** **(function)** -* [SHL or <<](shl.md) (operator) -* [SHR or >>](shl.md) (operator) +* [SHL or <<](shl.md) (operator) +* [SHR or >>](shl.md) (operator) * **[SIN](sin.md)** **(function)** * **[SQR](sqr.md)** **(function)** * [StdCall](stdcall.md) diff --git a/docs/if.md b/docs/if.md index ffd0b1865..c49b00735 100644 --- a/docs/if.md +++ b/docs/if.md @@ -3,13 +3,14 @@ **IF** is a very powerful control flow sentence that allows you to _make decisions_ under specified conditions. ## Syntax -``` - IF expression [THEN] sentences [: END IF] +```basic + IF expression [THEN] sentences [: END IF] ``` + or -``` +```vbnet IF expression [THEN] sentences [ELSEIF expression [THEN] sentences] @@ -19,15 +20,17 @@ or END IF ``` + ### Examples -``` + +```basic IF a < 5 THEN PRINT "A is less than five" ELSE PRINT "A is greater than five" ``` Sentences might be in multiple lines: -``` +```vbnet If a < 5 Then Print "A is less than five" a = a + 5 @@ -37,8 +40,10 @@ End If ``` -Since **IF** is a _sentence_, it can be nested; however, remember that _every_ **IF** _must be closed with_ **END IF** when the line is split after **THEN** (mutiline **IF**): -``` +Since **IF** is a _sentence_, it can be nested; however, remember that _every_ **IF** _must be closed with_ +`END IF` when the line is split after **THEN** (mutiline **IF**): + +```vbnet If a < 5 Then Print "A is less than five" If a > 2 Then @@ -57,7 +62,7 @@ End If 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: -``` +```vbnet If a < 5 Then Print "A is less than five" If a > 2 Then diff --git a/docs/img/zxbasic_logo.png b/docs/img/zxbasic_logo.png new file mode 100644 index 000000000..4c68e4c36 Binary files /dev/null and b/docs/img/zxbasic_logo.png differ diff --git a/docs/index.md b/docs/index.md index 51b5a476a..e26e2f867 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,12 @@ # General * [About](about.md) -
About the ZX BASIC SDK +
About Boriel BASIC SDK -* [ChangeLog](https://github.com/boriel/zxbasic/blob/master/Changelog.md) +* [ChangeLog](https://github.com/boriel-basic/zxbasic/blob/master/CHANGELOG.md)
A reduced list of changes/bugfixes * [Installation](installation.md) -
How to install the ZX Basic SDK in your system, and prerequisites for doing so. +
How to install Boriel BASIC SDK in your system, and prerequisites for doing so. * [SDK tools](tools.md)
Tools available in the SDK. @@ -16,14 +16,15 @@ # Download -Get the latest version of ZX BASIC from the [archive](archive.md). +Get the latest version of Boriel BASIC from the [archive](archive.md). # Released programs * [Released programs](released_programs.md) -
A list of third-party released programs (mostly games) for the ZX-Spectrum developed with ZX BASIC. +
A list of third-party released programs (mostly games) for the ZX-Spectrum developed with Boriel BASIC. + +# Learning Boriel BASIC -# Learning ZX BASIC ## Language Reference * [Language syntax](syntax.md)
Language Syntax is very close to the original Sinclair BASIC, but it's expanded and enhanced. @@ -35,14 +36,14 @@ Get the latest version of ZX BASIC from the [archive](archive.md).
Comprehensive list (alphabetically ordered) of identifiers you shouldn't use as a ''variable name''. E.g. `FOR`, `PRINT`. If you want usage instructions on a statement, also look here. * [Standard libraries](library/stdlib.md) -
Standard libraries that comes bundled with the ZX Basic compiler. +
Standard libraries that comes bundled with Boriel BASIC compiler. ## Tutorials * [Programming tutorials](tutorials.md) -
A collection of third-party tutorials about development with ZX BASIC. +
A collection of third-party tutorials about development with Boriel BASIC. * [Sample Programs](sample_programs.md) -
Sample programs you can try to see what ZX BASIC looks like and how fast it runs. +
Sample programs you can try to see what Boriel BASIC looks like and how fast it runs. * [Sample Games](sample_programs.md#Game Examples)
Some little games examples. @@ -50,11 +51,11 @@ Get the latest version of ZX BASIC from the [archive](archive.md). # Help and Support * [Community Forum](http://www.boriel.com/forum) -
Have a question? Need help or comment a report a bug? Go to the [ZX BASIC forum](http://www.boriel.com/forum) +
Have a question? Need help or comment a report a bug? Go to the [Boriel BASIC forum](http://www.boriel.com/forum) # External resources -* Here you are [external resources](external_resources.md): other tools, IDEs, graphic designers and projects related to ZX BASIC. Have a look! +* Here you are [external resources](external_resources.md): other tools, IDEs, graphic designers and projects related to Boriel BASIC. Have a look! # External libraries @@ -65,10 +66,10 @@ Get the latest version of ZX BASIC from the [archive](archive.md). Embedding inline assembler in your code is pretty easy. There's a [tutorial](tutorials.md) on it. # Compiler internals -Only for true hackers: This explains how the compiler does it job, how to expand it, etc. You must be a bit crazy if you enter here... +Only for true hackers: This explains how the compiler does its job, how to expand it, etc. # Other Architectures -ZX Basic was designed from the base as a Retargeable Compiler, so it should be not hard to extend +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 diff --git a/docs/library/asc.bas.md b/docs/library/asc.bas.md index 286ea7b29..c4d08bb81 100644 --- a/docs/library/asc.bas.md +++ b/docs/library/asc.bas.md @@ -11,7 +11,7 @@ variable = asc(A$,n) ``` Where `A$` is a string variable and `N` defines which character in the string we are interested in. -##Requirements +## Requirements ASC is a library function that must be included before it can be used. Use the following directive: diff --git a/docs/library/print64x32.bas.md b/docs/library/print64x32.bas.md index 4eae5d1c9..eb25adcce 100644 --- a/docs/library/print64x32.bas.md +++ b/docs/library/print64x32.bas.md @@ -14,9 +14,9 @@ thread http://www.boriel.com/forum/wishlist/64-char-print-32-lines-version-t680. Print64x32At(y,x) ``` -Moves the print64 system's print cursor to row Y, column X. Note that 0<= x <= 63 - - that is the range of values for X can be up to 63. The range of values for Y is 0-31. -* Note that the `print64x32` system's cursor position is independent from that of the +Moves the print64 system's print cursor to row Y, column X. Note that `0 <= x <= 63` - + that is the range of values for X can be up to 63. The range of values for Y is `0-31`. +* Note that the `print64x32` system's cursor position is independent of that of the ZX Basic Print routine, or any other, such as the print42 system. @@ -41,7 +41,7 @@ An All in one function - sets the AT position, and prints the string. ## CODE -``` +```basic SUB Print64x32At(Y as uByte,X as UByte) Poke(@Print64x32XCoord),X Poke (@Print64x32XCoord+1),Y diff --git a/docs/library/puttile.md b/docs/library/puttile.md index f718e87e9..e9b514744 100644 --- a/docs/library/puttile.md +++ b/docs/library/puttile.md @@ -3,10 +3,11 @@ # putTile.bas This subroutine takes a 2X2 tile of data from the given address and copies -it to the screen co-ordinates at (x, y) - x and y in character addresses, where 0 <= x <= 31 and 0 <= y < =23. +it to the screen co-ordinates at `(x, y) - x` and `y` in character addresses, where `0 <= x <= 31` and +`0 <= y < =23`. Note that this uses pushes and pops to move the data, using the fastest known data moving algorithm for the Z80. -As a consequence, while active it uses ALL the registers, including alternates and IY and IX as well as the +As a consequence, while active it uses ALL the registers, including alternates and `IY` and `IX` as well as the Stack Pointer SP. It is kind enough to put these back for the purposes of exiting the subroutine though - ZX BASIC uses that register quite extensively. diff --git a/docs/library/randomstream.bas.md b/docs/library/randomstream.bas.md index 8a7c2220e..230236a29 100644 --- a/docs/library/randomstream.bas.md +++ b/docs/library/randomstream.bas.md @@ -95,7 +95,7 @@ end asm end function ``` -This function returns a value from zero to the specified limit number (limit <= 255). +This function returns a value from zero to the specified limit number (limit <= 255). You can therefore, for example, roll a dice by calling `randomLimit(5) + 1` to get 1-6. diff --git a/docs/library/screen.md b/docs/library/screen.md index 54976d032..01340ff92 100644 --- a/docs/library/screen.md +++ b/docs/library/screen.md @@ -34,7 +34,7 @@ PRINT AT 0, 0; "The character at 9, 10 is "; c$ ## Remarks * This function extends the one in Sinclair BASIC (and it's compatible with it) since it also allows rows 22 and 23. -* When using _--sinclair_ cmd line parameter this function is already available (i.e. no _#include _ sentence is needed) +* When using _--sinclair_ cmd line parameter this function is already available (i.e. no `#include ` sentence is needed) ## See also diff --git a/docs/on_goto.md b/docs/on_goto.md index b0c5216b6..952026c09 100644 --- a/docs/on_goto.md +++ b/docs/on_goto.md @@ -35,7 +35,7 @@ In this example, * if `X` is 0, the execution will jump to line 50 * if `X` is 1, it will jump to line 100; * if `X` is 2, it will jump to line 150. - * If `X` is outside this range, the `ON ... GOTO` sentence will be ignored.
+ * If `X` is outside this range, the `ON ... GOTO` sentence will be ignored.
The program will print _"Invalid choice"_ and ask for input again. ## Remarks diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 000000000..86d46c0a3 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,6 @@ +{% extends "base.html" %} + +{% block extrahead %} + + +{% endblock %} \ No newline at end of file diff --git a/docs/overrides/stylesheets/extra.css b/docs/overrides/stylesheets/extra.css new file mode 100644 index 000000000..1f6140e11 --- /dev/null +++ b/docs/overrides/stylesheets/extra.css @@ -0,0 +1,64 @@ +/* Import Sinclair Logo font */ +/*@font-face {*/ +/* font-family: 'Sinclair Logo';*/ +/* src: url('../fonts/sinclair-logo.otf.woff2') format('woff2');*/ +/* font-weight: normal;*/ +/* font-style: normal;*/ +/*}*/ + +/* 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 */ +} + + +[data-md-color-scheme="default"] .md-header__title { + color: #ffde06; +} + +/* Dark mode - dark gray header */ +[data-md-color-scheme="slate"] .md-header { + background-color: #333333; /* Dark gray background color */ +} + +[data-md-color-scheme="slate"] .md-header__title { + color: #af0d0d; +} + +.md-header__title { + font-family: 'Press Start 2P', cursive; + } + +/* Ensure the site name maintains its size */ +.md-header__title .md-header__ellipsis { + font-size: 1.2rem; +} + +.md-header__inner { + background-image: url('../img/zxbasic_logo.png'); + background-repeat: no-repeat; + background-position: left center; + background-size: auto 100%; +} + +/*!* Make the logo size 100% of the header *!*/ +.md-header__button.md-logo { + color: #ff000000; +} + +/* Increase font weight for headings */ +h1, h2, h3, h4, h5, h6 { + /* font-weight: 600; /* Bold */ + font-family: "Roboto Mono", sans-serif; +} + +/* 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 h6 { + font-weight: 600; /* Bold */ +} diff --git a/docs/requirements.txt b/docs/requirements.txt index d1d61d31d..46ad0a2c1 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -29,3 +29,4 @@ requests==2.32.4 six==1.16.0 urllib3==2.2.3 watchdog==6.0.0 +mkdocs-material diff --git a/docs/return.md b/docs/return.md index cb3753151..02a13c454 100644 --- a/docs/return.md +++ b/docs/return.md @@ -13,9 +13,9 @@ RETURN [] Returns in the global scope (that is, outside any function or sub) are treated as return from [GO SUB](gosub.md). -Otherwise they are considered as returning from the function or sub they are into. +Otherwise, they are considered as returning from the function or sub they are into. -> **WARNING**: Using RETURN in global scope without a GOSUB will mostly crash your program.
+> **WARNING**: Using RETURN in global scope without a GOSUB will mostly crash your program.
> Use `--stack-check` if you suspect you have this bug, to detect it. ### Example with GO SUB diff --git a/docs/rnd.md b/docs/rnd.md index 49cc699e7..cd905fb5a 100644 --- a/docs/rnd.md +++ b/docs/rnd.md @@ -10,12 +10,12 @@ rnd ## Description -Returns a number of type float in the range [0, 1) (i.e. 0 <= RND < 1), based on a random seed (see [RANDOMIZE](randomize.md)). +Returns a number of type float in the range `[0, 1)` (i.e. `0 <= RND < 1`), based on a random seed (see [RANDOMIZE](randomize.md)). ## Examples -``` +```basic REM Function to a random number in the range [first, last), or {first <= x < last}. Function rnd_range (first As Double, last As Double) As Float Function = Rnd * (last - first) + first diff --git a/docs/shl.md b/docs/shl.md index 48e35e87c..a1ac5de13 100644 --- a/docs/shl.md +++ b/docs/shl.md @@ -15,7 +15,7 @@ Bit shifts `` expression by `` bits to the left (`SHL`) or to the right (`SHR`). `SHR` can be replaced by `>>` and `SHL` by `<<` for more legibility. -The argument should be of an integer type: `uByte`, `Byte`, `uInteger`, `Integer`, `uLong` or `Long`. +The `` argument should be of an integer type: `uByte`, `Byte`, `uInteger`, `Integer`, `uLong` or `Long`. Use of bitshifting with fixed and float gives undefined results. `CAST` or `INT` should be used to convert floating point numbers into integer type numbers before use of the bit shift instructions. diff --git a/docs/syntax.md b/docs/syntax.md index 5c74ffa76..ef34de12e 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -3,17 +3,22 @@ ## Introduction This page is about the ZX BASIC language syntax. It is part of the Language Reference Guide. -ZX BASIC aims to be a modern BASIC dialect but tries to keep some (many) of the original Sinclair BASIC features for the nostalgic. So you can use it in both ways. +ZX BASIC aims to be a modern BASIC dialect but tries to keep some (many) of the original Sinclair BASIC +features for the nostalgic. So you can use it in both ways. -The BASIC dialect is mainly based in [FreeBasic](http://www.zxbasic.net/wiki/). Many of the language specifications have been taken from there. +The BASIC dialect is mainly based in [FreeBasic](https://www.freebasic.net/wiki/DocToc). +Many of the language specifications have been taken from there. ## ZX BASIC syntax overview -If you have ever programmed in legacy BASIC (either Sinclair BASIC or any other flavour) you will already know that BASIC languages are **line oriented**. Each sentence or group of sentences are separated in lines (ended with a carriage return). +If you have ever programmed in legacy BASIC (either Sinclair BASIC or any other flavour) you will already know that +BASIC languages are **line oriented**. Each sentence or group of sentences are separated in lines (ended with a +carriage return). -Nowadays this is not necessary, but ZX BASIC allows you to use lines and line numbers for compatibility (and nostalgic!) reasons: +Nowadays this is not necessary, but ZX BASIC allows you to use lines and line numbers for compatibility +(and nostalgic!) reasons: -``` +```basic 10 REM This is a comment. 20 PRINT "Hello world!" ``` @@ -22,7 +27,7 @@ Nowadays this is not necessary, but ZX BASIC allows you to use lines and line nu Other than that, line numbers are ignored (well, not exactly: line numbers are treated as [labels](labels.md)). So the previous BASIC program could be also written this way: -``` +```basic REM This is a comment. PRINT "Hello world!" ``` @@ -30,9 +35,10 @@ PRINT "Hello world!" ### Lines and sentences -Since ZX BASIC is **line oriented** this implies that the ''end of line'' (also known as ''carriage return'' or '''') is taken into account during syntax checking, and you cannot break lines in the middle of a sentence: +Since ZX BASIC is **line oriented** this implies that the ''end of line'' (also known as ''carriage return'' or ``) +is taken into account during syntax checking, and you cannot break lines in the middle of a sentence: -``` +```basic REM The following line has a syntax error PRINT "Hello world!" @@ -42,7 +48,7 @@ PRINT Other languages (like C or Pascal) allows this because they're not line oriented. If you need to break a line, use the underline character (**_**) at the end of line to tell the compiler the current line continues in the next one: -``` +```basic REM The following line is broken into two, but it's ok PRINT _ "Hello world!" @@ -51,16 +57,19 @@ PRINT _ ### Sentences and block of sentences -A sentence is the simplest BASIC instruction (e.g. **[PRINT](print.md)**). Sentences might contain ''arguments'' and can be separated by a ''colon'' (:) as in Sinclair BASIC or by ''end of line''. A ''block of sentences'' are just a group of sentences one after another. Usually the reserved word **END** denotes the end of such block. E.g. +A sentence is the simplest BASIC instruction (e.g. **[PRINT](print.md)**). Sentences might contain ''arguments'' and +can be separated by a ''colon'' (:) as in Sinclair BASIC or by ''end of line''. A ''block of sentences'' are +just a group of sentences one after another. Usually the reserved word **END** denotes the end of such block. E.g. -``` +```basic IF a > b THEN PRINT "A is greater than B" PRINT "and that's all" END IF ``` -In the previous example, everything between **[THEN](if.md)** and **[END IF](if.md)** conforms a ''block of sentences''. Some sentences (like the shown **[IF](if.md)**) works with sentences block. They are called ''compound sentences''. +In the previous example, everything between **[THEN](if.md)** and **[END IF](if.md)** conforms a ''block of sentences''. +Some sentences (like the shown **[IF](if.md)**) works with sentences block. They are called ''compound sentences''. ### Identifiers @@ -84,9 +93,10 @@ So, `C9` hex should be written as `0C9h` or `$C9`. ### Comments -As shown in the previous examples, the ''reserved word'' **REM** is used for comments and ''remarks''. However, you can also use the single quote (') character for comments instead of **REM**: +As shown in the previous examples, the ''reserved word'' **REM** is used for comments and ''remarks''. +However, you can also use the single quote (') character for comments instead of **REM**: -``` +```basic 10 REM This is a comment 20 'This is also a comment 30 PRINT "Hello world!" @@ -142,7 +152,8 @@ A blank space represents both blocks blank or paper. The complete list of possib ### Embedded color control codes -Sometimes, in a program, one might wish to embed colour control codes into strings for printing. This is possible using the same schema as Paul Dunn's BASIC IDE BASin. +Sometimes, in a program, one might wish to embed colour control codes into strings for printing. +This is possible using the same schema as Paul Dunn's BASIC IDE BASin. The escape sequences for control characters are as follows: @@ -156,11 +167,15 @@ So, for example, an embedded control code for red ink would be `\{i2}`. ## Data types -ZX Basic [types](types.md) ranges from 8 to 32 bits for integer formats. It also supports floating point format (the ZX ROM 40 bits floating point from the ROM FP Calculator) and ''Fixed'' for fixed point arithmetic. See [types page](types.md) for more information. +ZX Basic [types](types.md) ranges from 8 to 32 bits for integer formats. It also supports floating point format +(the ZX ROM 40 bits floating point from the ROM FP Calculator) and ''Fixed'' for fixed point arithmetic. +See [types page](types.md) for more information. ## Inline assembly -The Compiler supports inline assembly, starting with the ASM directive and ending with an END ASM directive. Between these two, raw z80 assembly becomes legal. This assembly data will be passed directly to the assembler as part of the compiled assembler source. +The Compiler supports inline assembly, starting with the ASM directive and ending with an END ASM directive. +Between these two, raw z80 assembly becomes legal. This assembly data will be passed directly to the assembler as part +of the compiled assembler source. Note that the rules for assembly change dramatically from standard ZX BASIC, and this mode is not for the unwary. diff --git a/docs/while.md b/docs/while.md index 6e6a97b86..0cd921282 100644 --- a/docs/while.md +++ b/docs/while.md @@ -4,14 +4,14 @@ If the given _condition_ is false the first time the inner _sentences_ are _never_ executed. ## Syntax -``` +```basic WHILE expression sentences END WHILE ``` or -``` +```basic WHILE expression sentences WEND @@ -19,16 +19,16 @@ or The first form is preferred. ## Examples -``` -While a < b - Let a = a + 1 - Poke a, 0 -End While +```basic +WHILE a < b + LET a = a + 1 + POKE a, 0 +END WHILE ``` An infinite loop: -``` +```vbnet While 1 REM An infinite loop. This will issue a warning Print "Hello world!" diff --git a/mkdocs.yml b/mkdocs.yml index 42f2a3bd8..ab4738ee4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: ZX Basic Wiki +site_name: Boriel BASIC nav: - Home: index.md - Syntax: syntax.md @@ -8,16 +8,35 @@ nav: - About: about.md theme: - name: readthedocs + name: material + #logo: img/zxbasic_logo.png + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + + # Custom CSS + custom_dir: docs/overrides docs_dir: docs markdown_extensions: - - tables - pymdownx.highlight: + linenums: true anchor_linenums: true line_spans: __span pygments_lang_class: true + - pymdownx.keys - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences