Merge pull request #30 from astralaster/main

Fix links.

.github/workflows/docs.yml

@@ -18,4 +18,4 @@ jobs:
           key: ${{ github.ref }}
           path: .cache
       - run: pip install mkdocs-material
-      - run: mkdocs gh-deploy --force
+      - run: mkdocs gh-deploy --strict --force

docs/VDP.md

@@ -119,6 +119,6 @@ Any VDU command that is the VDP does not recognise (such as `VDU 2` when running
 
 For more information on these commands and a full list, please consult the `VDU 23` section of the [VDU Commands](vdp/VDU-Commands.md) document.  This includes the [Bitmap and Sprite API](vdp/Bitmaps-API.md).
 
-Amongst this you will also find [system commands](vdp/System-Commands.md), which start with `VDU 23, 0` and are unique to the Agon platform.  Within the system commands set you will find the [Audio API](vdp/Enhanced-Audio-API.md), and [Buffered Commands API](vdp/Buffered-Commands-API).
+Amongst this you will also find [system commands](vdp/System-Commands.md), which start with `VDU 23, 0` and are unique to the Agon platform.  Within the system commands set you will find the [Audio API](vdp/Enhanced-Audio-API.md), and [Buffered Commands API](vdp/Buffered-Commands-API.md).
 
 

docs/vdp/Bitmaps-API.md

@@ -2,7 +2,7 @@
 
 VDU 23, 27 is reserved for the bitmap, sprite, and mouse cursor functionality.
 
-As of VDP 1.04, the bitmap system is integrated with the [Buffered Commands API](vdp/Buffered-Commands-API.md).  Bitmap data is stored in buffers, and can be manipulated using the Buffered Commands API on the VDP.
+As of VDP 1.04, the bitmap system is integrated with the [Buffered Commands API](Buffered-Commands-API.md).  Bitmap data is stored in buffers, and can be manipulated using the Buffered Commands API on the VDP.
 
 
 ## Bitmaps
@@ -13,7 +13,7 @@ Acorn only actually had two VDU commands for what it called "sprites", which in
 
 The approach taken on Agon (initially at least) was to redefine the "define bitmap from screen" command to instead allow the uploading of a binary bitmap image.  In doing so, the parameters of the command changed, and the bitmap identifier was lost from the command parameters.  Instead, on the Agon, you need to always perform a "select bitmap" command before any other bitmap commands to set the bitmap being used.  Additionally on the Agon, prior to Console8 VDP 2.2.0, plotting bitmaps could only be performed with a custom command, and not with the standard `PLOT` commands.
 
-As of Console8 VDP 2.2.0, it is now possible to use Acorn GXR style "sprite" code on an Agon.  The `PLOT` code for drawing bitmaps is now supported, and bitmap command 1 can now be used to capture screen data into a bitmap identically to the GXR.  The documentation on the [`PLOT` command](vdp/PLOT-Command.md) (`VDU 25`) explains how to use it to draw bitmaps.
+As of Console8 VDP 2.2.0, it is now possible to use Acorn GXR style "sprite" code on an Agon.  The `PLOT` code for drawing bitmaps is now supported, and bitmap command 1 can now be used to capture screen data into a bitmap identically to the GXR.  The documentation on the [`PLOT` command](PLOT-Commands.md) (`VDU 25`) explains how to use it to draw bitmaps.
 
 In addition to GXRs two commands, the Agon VDP has several other commands for managing bitmaps, and additional commands to manage "sprites".
 
@@ -49,7 +49,7 @@ The width and height of the bitmap must be given in pixels, and must match the n
 
 It should be noted that whilst the image format supported by this command is for full 24-bit colour images with 256 levels of transparency (alpha) per pixel, the Agon hardware is only capable of displaying 2-bits per colour channel.  The graphics system also does not really support transparency, so any non-zero alpha value is interpreted as "fully visible".  Data loaded via this command remains in RGBA8888 format on the VDP, but is converted on the fly when the bitmap is drawn to the screen.
 
-(As RGBA8888 is a very wasteful format, given the hardware limitations, other options are now available.  Loading bitmaps with this command can take a long time, and it is not possible to intersperse other commands, such as showing progress on-screen, whilst the data is being sent.  There are however alternative ways of managing the data which avoids these issues.  Please see the section on "Using buffers for bitmaps" in the [Buffered Commands API](vdp/Buffered-Commands-API.md) document for more information.)
+(As RGBA8888 is a very wasteful format, given the hardware limitations, other options are now available.  Loading bitmaps with this command can take a long time, and it is not possible to intersperse other commands, such as showing progress on-screen, whilst the data is being sent.  There are however alternative ways of managing the data which avoids these issues.  Please see the section on "Using buffers for bitmaps" in the [Buffered Commands API](Buffered-Commands-API.md) document for more information.)
 
 ### `VDU 23, 27, 1, n, 0, 0;`: Capture screen data into bitmap n *
 
@@ -63,7 +63,7 @@ To be clear, this command should be performed _after_ two "move" style PLOT comm
 
 If a bitmap with the given ID already exists then it will be overwritten, and similarly if a buffer was already defined with the ID 64000+`n` then that will be overwritten too.
 
-Up to and including the Console8 VDP 2.5.0 release, the bitmap data captured using this command will be stored in "native" format.  The nature of the "native" format varies depending on the screen mode.  For all screen modes the bitmap will use 1 byte per pixel, but the data within that byte varies.  In 64 colour modes, the data is essentially in RGB222 with no alpha channel.  It is possible to convert bitmaps captured in 64 colour modes to RGBA2222 format by using the OR operation of the "adjust" command from the [Buffered Commands API](vdp/Buffered-Commands-API.md), ORing all the bytes in the bitmap's buffer with `&C0` to set the pixel alpha bits to be "opaque", and then re-creating the bitmap from the corresponding buffer to be RGBA2222 (format 1).  For all other screen modes, the byte represents a palette index.  An unfortunate effect of this is that a bitmap captured in one screen mode may not be compatible with other screen modes.
+Up to and including the Console8 VDP 2.5.0 release, the bitmap data captured using this command will be stored in "native" format.  The nature of the "native" format varies depending on the screen mode.  For all screen modes the bitmap will use 1 byte per pixel, but the data within that byte varies.  In 64 colour modes, the data is essentially in RGB222 with no alpha channel.  It is possible to convert bitmaps captured in 64 colour modes to RGBA2222 format by using the OR operation of the "adjust" command from the [Buffered Commands API](Buffered-Commands-API.md), ORing all the bytes in the bitmap's buffer with `&C0` to set the pixel alpha bits to be "opaque", and then re-creating the bitmap from the corresponding buffer to be RGBA2222 (format 1).  For all other screen modes, the byte represents a palette index.  An unfortunate effect of this is that a bitmap captured in one screen mode may not be compatible with other screen modes.
 
 Also up to and including the Console8 VDP 2.5.0 release, bitmaps captured with this command would use "exclusive" coordinates, and so would be 1 pixel shorter and narrower than the area defined by the graphics cursor positions.  (This is _not_ consistent with the behaviour of this command on Acorn systems.)
 
@@ -79,13 +79,13 @@ The bitmap is created in the buffer with the ID 64000+`n`, where `n` is the 8-bi
 
 ### `VDU 23, 27, 3, x; y;`: Draw current bitmap on screen at pixel position x, y
 
-Prior to Agon Console8 VDP 2.2.0, this was the only way to draw a bitmap on-screen.  On more up to date VDP versions is strongly recommended that you use the appropriate [PLOT command](vdp/PLOT-Commands.md) instead.
+Prior to Agon Console8 VDP 2.2.0, this was the only way to draw a bitmap on-screen.  On more up to date VDP versions is strongly recommended that you use the appropriate [PLOT command](PLOT-Commands.md) instead.
 
 Before this command can be used, a bitmap must be selected using `VDU 23, 27, 0, n`, where `n` is the 8-bit ID of the bitmap to be drawn, or using `VDU 23, 27, &20, bufferId;` using a 16-bit buffer ID.
 
 The x and y parameters give the pixel position on the screen at which the top left corner of the bitmap will be drawn.  This is in contrast to `PLOT` commands which will (by default) use OS Coordinates, where the origin is at the bottom left of the screen and the screen is always considered to have the dimensions 1280x1024.
 
-Please note that this command does not obey the current graphics viewport or the currently selected coordinate system.  The bitmap will be drawn at the given pixel position, and will _not_ be clipped by the viewport.  To draw bitmaps with clipping, you are advised to use the appropriate bitmap [PLOT commands](vdp/PLOT-Commands.md) instead.
+Please note that this command does not obey the current graphics viewport or the currently selected coordinate system.  The bitmap will be drawn at the given pixel position, and will _not_ be clipped by the viewport.  To draw bitmaps with clipping, you are advised to use the appropriate bitmap [PLOT commands](PLOT-Commands.md) instead.
 
 ### `VDU 23, 27, &20, bufferId;`: Select bitmap using a 16-bit buffer ID *
 

docs/vdp/Buffered-Commands-API.md

@@ -52,7 +52,7 @@ VDU 23, 27, &20, bufferId;              : REM Select bitmap (using a buffer ID)
 VDU 23, 27, &21, width; height; format  : REM Create bitmap from buffer
 ```
 
-More extensive information on the bitmap and sprites API calls can be found in the [bitmaps and sprites documentation](vdp/Bitmaps-API.md).
+More extensive information on the bitmap and sprites API calls can be found in the [bitmaps and sprites documentation](Bitmaps-API.md).
 
 Until the "create bitmap" call has been made the buffer cannot be used as a bitmap.  That is because the system needs to understand the dimensions of the bitmap, as well as the format of the data.  Usually this only needs to be done once.  The format is given as an 8-bit value, with the following values supported:
 
@@ -82,7 +82,7 @@ Much like with bitmaps, it is advisable to send samples over to the VDP in multi
 
 In contrast to bitmaps, the sound system can play back samples that are spread over multiple blocks, so there is no need to consolidate buffers.  As a result of this, the sample playback system is also more tolerant of modifications being made to the buffer after a sample has been created from it, even if the sample is currently playing.  It should be noted that splitting a buffer may result in unexpected behaviour if the sample is currently playing, such as skipping to other parts of the sample.
 
-Full information on the sound system can be found in the [audio API documentation](vdp/Enhanced-Audio-API.md).
+Full information on the sound system can be found in the [audio API documentation](Enhanced-Audio-API.md).
 
 Once you have a buffer that contains block(s) that are ready to be used for a sound sample, the following command must be used to indicate that a sample should be created from that buffer:
 

docs/vdp/Enhanced-Audio-API.md

@@ -13,7 +13,7 @@ Examples are given in BBC BASIC.
 
 A common source of errors when sending commands to the VDP from BASIC via VDU commands is to forget to use a `;` after a number to indicate a 16-bit value should be sent.  If you see unexpected behaviour from your BASIC code that is the most likely source of the problem.
 
-When a command is processed the VDP may send a message back to MOS with the status of that command.  (Generally a return value of `1` indicates success, and `0` failure, but there are some exceptions to this, most notably the Status command.  Not all audio comments return a status.)  When the MOS receives an audio command status value it will set the audio bit of the VDP protocol flags to indicate that an audio message has been received.  It also sets two [system variable values](MOS-API.md#system-variables), `sysvar_audioChannel` and `sysvar_audioSuccess` with the results of the command.  `sysvar_audioChannel` is the channel number, and `sysvar_audioSuccess` provides the status of that command.  These values can be read using a `mos_sysvars` API call, or an [OSBYTE call from BASIC as documented here](BBC-BASIC-for-Agon.md#accessing-the-mos-system-variables).
+When a command is processed the VDP may send a message back to MOS with the status of that command.  (Generally a return value of `1` indicates success, and `0` failure, but there are some exceptions to this, most notably the Status command.  Not all audio comments return a status.)  When the MOS receives an audio command status value it will set the audio bit of the VDP protocol flags to indicate that an audio message has been received.  It also sets two [system variable values](../MOS-API.md#system-variables), `sysvar_audioChannel` and `sysvar_audioSuccess` with the results of the command.  `sysvar_audioChannel` is the channel number, and `sysvar_audioSuccess` provides the status of that command.  These values can be read using a `mos_sysvars` API call, or an [OSBYTE call from BASIC as documented here](../BBC-BASIC-for-Agon.md#accessing-the-mos-system-variables).
 
 It should be noted that VDP protocol flags are not automatically cleared by MOS, so it is the responsibility of the application to clear the audio bit of the VDP protocol flags before sending a command.  At present there is no way to do this directly from BBC BASIC.
 
@@ -141,7 +141,7 @@ Prior to Console8 VDP 2.5.0 this command did not return a status.
 
 These commands are used to manage samples on the VDP which can be assigned to a channel as a waveform for playback.
 
-Sample data is stored in buffers on the VDP, and can be manipulated using the [buffered commands API](vdp/Buffered-Commands-API.md).
+Sample data is stored in buffers on the VDP, and can be manipulated using the [buffered commands API](Buffered-Commands-API.md).
 
 When a negative number is used in place of the channel number then the command is referring directly to a sample, rather than a channel.  Samples referenced in this manner are, by default, stored in buffers in the range 64256-64383 (`&FB00`-`&FB7F`).  To map a negative sample number to a buffer range, you need to negate it, subtract 1, and then add it to 64256.  This means sample number -1 is stored in buffer 64256, -2 is stored in buffer 64257, and so on.  Any buffer however can be used for sample data, using commands listed below that explicitly reference a buffer ID.
 
@@ -155,7 +155,7 @@ Sample commands 5, 3 and above were added in the Console8 VDP 2.2.0 release.
 
 This command is used to transfer a sample over to the VDP for later playback.
 
-As sample data can be long, rather than using this command, you are advised instead to upload your sample data to a buffer on the VDP in multiple blocks using the [buffered commands API](vdp/Buffered-Commands-API.md) and then use command 5, 2 (documented below) to indicate that the data within a buffer is a sound sample.  That approach also allows for the use of different formats of sample data.
+As sample data can be long, rather than using this command, you are advised instead to upload your sample data to a buffer on the VDP in multiple blocks using the [buffered commands API](Buffered-Commands-API.md) and then use command 5, 2 (documented below) to indicate that the data within a buffer is a sound sample.  That approach also allows for the use of different formats of sample data.
 
 When using this command, the sample data is assumed to be 8-bit signed PCM samples at 16kHz.  The sample data is sent as a series of bytes of the given length.
 
@@ -184,7 +184,7 @@ A simple example of how to send a sample to the VDP using this command is as fol
 
 NB This example can be very slow as it sends the sample data byte-by-byte, taking just over 1s to send 2kb of data.  During this time your computer will be unresponsive, and it is not possible to output to screen any kind of progress as any such `PRINT` command will be interpretted as part of the sample data.  Unfortunately at present there is no way to send data in bulk to the VDP from BBC BASIC, or to read chunks of files into memory in one go.  For faster transfer of sample data you will need to write a program in assembly language and make use of file access APIs from MOS and the RST #18 vector to send larger chunks of data to the VDP.
 
-The [VDP Buffered Commands API](vdp/Buffered-Commands-API.md) provides an alternative example of sending sample data to the VDP which allows for progress to be reported whilst the sample is being uploaded.
+The [VDP Buffered Commands API](Buffered-Commands-API.md) provides an alternative example of sending sample data to the VDP which allows for progress to be reported whilst the sample is being uploaded.
 
 As noted above, this command will return 1 on success or 0 for failure.  In the event of a failure the VDP will ignore and discard the sample data being sent to it.
 
@@ -206,7 +206,7 @@ This command will return 1 on success or 0 for failure.
 
 This command is used to indicate that the data in the given buffer is a sound sample.  The channel number will be ignored for the purposes of this command, but will be used in the return result.
 
-The buffer ID is a 16-bit value giving the buffer number to use for the sample.  The buffer must have been created using the [buffered commands API](vdp/Buffered-Commands-API.md) before this command is called.
+The buffer ID is a 16-bit value giving the buffer number to use for the sample.  The buffer must have been created using the [buffered commands API](Buffered-Commands-API.md) before this command is called.
 
 The format is a single byte giving the format of the sample data.  The following formats are supported: