Merge pull request #470 from paulscottrobson/apidocs

API in Markdown, prelim version

.gitignore

@@ -47,7 +47,6 @@ firmware/sources/interface/*.o
 *.dump
 *.log
 *.aux
-documents/release/api.*
 documents/release/basic.pdf
 basic/scripts/__pycache__/tokens.cpython-311.pyc
 firmware/common/include/data/prompt.h

firmware/common/config/display/group2_console.inc

@@ -27,10 +27,10 @@ GROUP 2 Console
     FUNCTION 1 Read Character
         *(DPARAMS) = KBDGetKey();
     DOCUMENTATION
-        Read and remove a key press from the keyboard queue into \Param{0}.
+        Read and remove a key press from the keyboard queue into Parameter:0.
         This is the ASCII value of the keystroke.
-        If there are no key presses in the queue, \Param{0} will be zero.
-        \newline
+        If there are no key presses in the queue, Parameter:0 will be zero.
+
         Note that this Function is best for text input, but not for games.
         Function 7,1 is more optimal for games, as this only detects key presses,
         you cannot check whether the key is currently down or not.
@@ -39,40 +39,38 @@ GROUP 2 Console
         *(DPARAMS) = KBDIsKeyAvailable() ? 0xFF: 0;
     DOCUMENTATION // Function 2 is key available in queue
         Check to see if the keyboard queue is empty.
-        If it is, \Param{0} will be \MonoSp{$FF}, otherwise it will be \MonoSp{$00}.
+        If it is, Parameter:0 will be $FF, otherwise it will be $00
 
     FUNCTION 3 Read Line
         CONGetScreenLine(DSPGetInt16(DCOMMAND,4));
     DOCUMENTATION
-        Input the current line below the cursor into \Param{0,1} as a length-prefixed string;
+        Input the current line below the cursor into Parameters:0,1 as a length-prefixed string;
         and move the cursor to the line below. Handles multiple-line input.
 
     FUNCTION 4 Define Hotkey
         *DERROR = KBDSetFunctionKey(*(DCOMMAND+4),DSPGetString(DCOMMAND,6));
     DOCUMENTATION
-        Define the function key F1..F10 (\MonoSp{$01..$0A}) specified in \Param{0} to emit the
-        length-prefixed string stored at the memory location specified in \Param{2,3}.
-        For example, in a block of in-line assembly within a BASIC program,
-        the string: \MonoSp{06,12,108,105,115,116,13} would clear the screen (\MonoSp{12}),
-        then list the program (\MonoSp{108}='l',\MonoSp{105}='i',\MonoSp{115}='s',\MonoSp{116}='t',\MonoSp{13}='ENTER').
-        \newline F11 and F12 cannot currently be defined.
+        Define the function key F1..F10 specified in Parameter:0 as 1..10 to emit the
+        length-prefixed string stored at the memory location specified in Parameters:2,3.
+
+        F11 and F12 cannot currently be defined.
 
     FUNCTION 5 Define Character
         *DERROR = CONUpdateUserFont(DPARAMS);
     DOCUMENTATION
-        Define a font character specified in \Param{0} within the range of 192..255.
-        Fill bits 0..5 (columns) of \Param{1..7} (rows) with the character bitmap.
+        Define a font character specified in Parameter:0 within the range of 192..255.
+        Fill bits 0..5 (columns) of Parameters:1..7 (rows) with the character bitmap.
 
     FUNCTION 6 Write Character
         CONWrite(*DPARAMS);
     DOCUMENTATION
-        Write the character specified in \Param{0} to the console at the cursor position.
-        Refer to Section \#\ref{console-codes} "Console Codes" for details.
+        Write the character specified in Parameter:0 to the console at the cursor position.
+        Refer to Section "Console Codes" for details.
 
     FUNCTION 7 Set Cursor Pos
         *DERROR = CONSetCursorPosition(DPARAMS[0],DPARAMS[1]);
     DOCUMENTATION
-        Move the cursor to the screen character cell \Param{0} (X), \Param{1} (Y).
+        Move the cursor to the screen character cell Parameter:0 (X), Parameter:1 (Y).
 
     FUNCTION 8 List Hotkeys
         KBDShowFunctionKeys();
@@ -82,7 +80,7 @@ GROUP 2 Console
     FUNCTION 9 Screen Size
         CONGetScreenSizeChars(&DPARAMS[0],&DPARAMS[1]);
     DOCUMENTATION
-        Returns the console size in characters, in \Param{0} (height) and \Param{1} (width).
+        Returns the console size in characters, in Parameter:0 (height) and Parameter:1 (width).
 
     FUNCTION 10 Insert Line
         CONInsertLine(DPARAMS[0]);
@@ -103,18 +101,18 @@ GROUP 2 Console
         CONGetCursorPosition(&DPARAMS[0],&DPARAMS[1]);
     DOCUMENTATION
         Returns the current screen character cell of the cursor
-        in \Param{0} (X), \Param{1} (Y).
+        in Parameter:0 (X), Parameter:1 (Y).
 
     FUNCTION 14 Clear Region
         CONClearArea(DPARAMS[0],DPARAMS[1],DPARAMS[2],DPARAMS[3]);
     DOCUMENTATION
         Erase all characters within the rectangular region specified
-        in \Param{0,1} (begin X,Y) and \Param{2,3} (end X,Y).
+        in Parameters:0,1 (begin X,Y) and Parameters:2,3 (end X,Y).
 
     FUNCTION 15 Set Text Color
         CONSetForeBackColour(DPARAMS[0],DPARAMS[1]);
     DOCUMENTATION
-        Sets the foreground colour to \Param{0} and the background colour to \Param{1}.
+        Sets the foreground colour to Parameter:0 and the background colour to Parameter:1.
 
     FUNCTION 16 Cursor Inverse
         CONReverseCursorBlock();

firmware/common/config/display/group5_graphics.inc

@@ -24,77 +24,72 @@ GROUP 5 Graphics
         Configure the global graphics system settings.
         Not all parameters are relevant for all graphics commands;
         but all parameters will be set by this command. So mind their values.
-        Refer to Section \#\ref{subsec:graphics-settings} "Graphics Settings" for details.
-        \newline
-        \ParamsBytes{Graphics Settings}{AND}{XOR}{Fill}{Extent}
-                                       {Flip}{unused}{\textit{unused}}{\textit{unused}}
-        \newline
-        \ParamBits{$FF08 - Flip Axis Flags}{0}{0}{0}{0}{0}{0}{Vertical}{Horizontal}
+        Refer to Section "Graphics Settings" for details.
+
+        The parameters are And, Or, Fill Flag, Extent, and Flip. Bit 0 of flip
+        sets the horizontal flip, Bit 1 sets the vertical flip.
 
     FUNCTION 2 Draw Line
         GFXGraphicsCommand(2,DCOMMAND);
     DOCUMENTATION
         Draw a line between the screen coordinates specified
-        in  \Param{0,1},\Param{2,3} (begin X,Y)
-        and \Param{4,5},\Param{6,7} (end X,Y).
-        \newline
-        \ParamsBytes{Draw Line Parameters}{X  lo}{X  hi}{Y  lo}{Y  hi}
-                                          {X' lo}{X' hi}{Y' lo}{Y' hi}
+        in  Parameters:0,1,Parameters:2,3 (begin X,Y)
+        and Parameters:4,5,Parameters:6,7 (end X,Y).
 
     FUNCTION 3 Draw Rectangle
         GFXGraphicsCommand(3,DCOMMAND);
     DOCUMENTATION
         Draw a rectangle spanning the screen coordinates specified
-        in  \Param{0,1},\Param{2,3} (corner X,Y)
-        and \Param{4,5},\Param{6,7} (opposite corner X,Y).
+        in  Parameters:0,1,Parameters:2,3 (corner X,Y)
+        and Parameters:4,5,Parameters:6,7 (opposite corner X,Y).
 
     FUNCTION 4 Draw Ellipse
         GFXGraphicsCommand(4,DCOMMAND);
     DOCUMENTATION
         Draw an ellipse spanning the screen coordinates specified
-        in  \Param{0,1},\Param{2,3} (corner  X,Y)
-        and \Param{4,5},\Param{6,7} (opposite corner X,Y).
+        in  Parameters:0,1,Parameters:2,3 (corner  X,Y)
+        and Parameters:4,5,Parameters:6,7 (opposite corner X,Y).
 
     FUNCTION 5 Draw Pixel
         GFXGraphicsCommand(5,DCOMMAND);
     DOCUMENTATION
         Draw a single pixel at the screen coordinates specified
-        in \Param{0,1},\Param{2,3} (X,Y).
+        in Parameters:0,1,Parameters:2,3 (X,Y).
 
     FUNCTION 6 Draw Text
         GFXGraphicsCommand(6,DCOMMAND);
     DOCUMENTATION
         Draw the length-prefixed string of text stored
-        at the memory location specified in \Param{4,5}
-        at the screen character cell specified in \Param{0,1},\Param{2,3} (X,Y).
+        at the memory location specified in Parameters:4,5
+        at the screen character cell specified in Parameters:0,1,Parameters:2,3 (X,Y).
 
     FUNCTION 7 Draw Image
         GFXGraphicsCommand(7,DCOMMAND);
     DOCUMENTATION
-        Draw the image with image ID in \Param{4}
-        at the screen coordinates \Param{0,1},\Param{2,3} (X,Y).
+        Draw the image with image ID in Parameter:4
+        at the screen coordinates Parameters:0,1,Parameters:2,3 (X,Y).
         The extent and flip settings influence this command.
 
     FUNCTION 8 Draw Tilemap
         *DERROR = TMPDrawTileMap(DCOMMAND);
     DOCUMENTATION
         Draw the current tilemap at the screen coordinates specified
-        in \Param{0,1},\Param{2,3} (top-left X,Y)
-        and \Param{4,5},\Param{6,7} (bottom-right X,Y)
+        in Parameters:0,1,Parameters:2,3 (top-left X,Y)
+        and Parameters:4,5,Parameters:6,7 (bottom-right X,Y)
         using current graphics settings.
 
     FUNCTION 32 Set Palette
         GFXSetPalette(DPARAMS[0],DPARAMS[1],DPARAMS[2],DPARAMS[3]);
     DOCUMENTATION
-        Set the palette colour at the index spcified in \Param{0}
-        to the values in \Param{1},\Param{2},\Param{3} (RGB).
+        Set the palette colour at the index spcified in Parameter:0
+        to the values in Parameter:1,Parameter:2,Parameter:3 (RGB).
 
     FUNCTION 33 Read Pixel
         GFXGraphicsCommand(33,DCOMMAND);
     DOCUMENTATION
         Read a single pixel at the screen coordinates specified
-        in \Param{0,1},\Param{2,3} (X,Y).
-        When the routine completes, the result will be in \Param{0}. If sprites are in use, this will be the 
+        in Parameters:0,1,Parameters:2,3 (X,Y).
+        When the routine completes, the result will be in Parameter:0. If sprites are in use, this will be the 
         background only (0..15), if sprites are not in use it may return (0..255)
 
     FUNCTION 34 Reset Palette
@@ -106,58 +101,60 @@ GROUP 5 Graphics
         TMPSelectTileMap(cpuMemory+DSPGetInt16(DCOMMAND,4),DSPGetInt16(DCOMMAND,6),DSPGetInt16(DCOMMAND,8));
     DOCUMENTATION
         Set the current tilemap.
-        \Param{0,1} is the memory address of the tilemap,
-        and \Param{2,3},\Param{4,5} (X,Y) specifies the offset into the tilemap,
+        Parameters:0,1 is the memory address of the tilemap,
+        and Parameters:2,3,Parameters:4,5 (X,Y) specifies the offset into the tilemap,
         in units of pixels, of the top-left pixel of the tile.
 
     FUNCTION 36 Read Sprite Pixel
         GFXGraphicsCommand(36,DCOMMAND);
     DOCUMENTATION
         Read Pixel from the sprite layer at the screen coordinates
-        specified in \Param{0,1},\Param{2,3} (X,Y).
-        When the routine completes, the result will be in \Param{0}.
-        Refer to Section \#\ref{graphics-colors} "Pixel Colors" for details.
+        specified in Parameters:0,1,Parameters:2,3 (X,Y).
+        When the routine completes, the result will be in Parameter:0.
+        Refer to Section "Pixel Colors" for details.
 
     FUNCTION 37 Frame Count
         *((uint32_t *)DPARAMS) = RNDGetFrameCount();
     DOCUMENTATION
-        Deposit into \Param{0..3},
+        Deposit into Parameters:0..3,
         the number of v-blanks (full screen redraws) which have occurred since power-on.
         This is updated at the start of each v-blank period.
 
     FUNCTION 38 Get Palette
         GFXGetPalette(DPARAMS[0],&DPARAMS[1],&DPARAMS[2],&DPARAMS[3]);
     DOCUMENTATION
-        Get the palette colour at the index spcified in \Param{0}.
-        Values are returned in \Param{1},\Param{2},\Param{3} (RGB).
+        Get the palette colour at the index spcified in Parameter:0.
+        Values are returned in Parameter:1,Parameter:2,Parameter:3 (RGB).
 
     FUNCTION 39 Write Pixel
         GFXSetDrawColour(DPARAMS[4]);GFXGraphicsCommand(5,DCOMMAND);
     DOCUMENTATION
-        Write Pixel index \Param{4} to the screen coordinate specified in 
-        \Param{0,1},\Param{2,3} (X,Y).
+        Write Pixel index Parameter:4 to the screen coordinate specified in 
+        Parameters:0,1,Parameters:2,3 (X,Y).
 
     FUNCTION 64 Set Color
         GFXSetDrawColour(DPARAMS[0]);
     DOCUMENTATION
         Set Color
-        \newline Sets the current drawing colour to \Param{0}
+        Sets the current drawing colour to Parameter:0
 
     FUNCTION 65 Set Solid Flag
         GFXSetSolidFlag(DPARAMS[0]);
     DOCUMENTATION
         Set Solid Flag
-        \newline Sets the solid flag to \Param{0}, which indicates either solid fill (for shapes) or solid background (for images and fonts)
+
+        Sets the solid flag to Parameter:0, which indicates either solid fill (for shapes) or solid background (for images and fonts)
 
     FUNCTION 66 Set Draw Size
         GFXSetDrawSize(DPARAMS[0]);
     DOCUMENTATION
         Set Draw Size
-        \newline Sets the drawing scale for images and fonts to \Param{0}
+
+        Sets the drawing scale for images and fonts to Parameter:0
 
     FUNCTION 67 Set Flip Bits
         GFXSetFlipBits(DPARAMS[0]);
     DOCUMENTATION
         Set Flip Bits
-        \newline Sets the flip bits for drawing images. Bit 0 set causes a horizontal flip, bit 1 set causes a vertical flip.
+        Sets the flip bits for drawing images. Bit 0 set causes a horizontal flip, bit 1 set causes a vertical flip.
 

firmware/common/config/display/group6_sprites.inc

@@ -26,30 +26,29 @@ GROUP 6 Sprites
     FUNCTION 2 Sprite Set
         *DERROR = SPRUpdate(DPARAMS);
     DOCUMENTATION
-        Set or update the sprite specified in \Param{0}.
-        \newline
-        \ParamsBytes{Sprite Parameters}{Sprite}{X lo}{X hi}{Y lo}{Y hi}{Image}{Flip}{Anchor}
-        \newline
-        \SpriteParamBits{$FF09 - Image Parameters}{0}{32-bit}{Index}
-        \newline
-        \ParamBits{$FF0A - Flip Axis Flags}{0}{0}{0}{0}{0}{0}{Vertical}{Horizontal}
-        \newline values that are $80 or $8080 are not updated.
+        Set or update the sprite specified in Parameter:0.
+
+        The parameters are : Sprite Number, X Low, X High, Y Low, Y High, Image, Flip and Anchor and Flags
+
+        Bit 0 of flags specifies 32 bit sprites.
+
+        Values that are $80 or $8080 are not updated.
 
     FUNCTION 3 Sprite Hide
         SPRHide(DPARAMS);
     DOCUMENTATION
-        Hide the sprite specified in \Param{0}.
+        Hide the sprite specified in Parameter:0.
 
     FUNCTION 4 Sprite Collision
         DPARAMS[0] = SPRCollisionCheck(DERROR,DPARAMS[0],DPARAMS[1],DPARAMS[2]);
     DOCUMENTATION
-        \Param{0} is non-zero if the distance is less than or equal to \Param{2}
-        between the center of the sprite with index specified in \Param{0}
-        and the center of the sprite with index specified in \Param{1} .
+        Parameter:0 is non-zero if the distance is less than or equal to Parameter:2
+        between the center of the sprite with index specified in Parameter:0
+        and the center of the sprite with index specified in Parameter:1 .
 
     FUNCTION 5 Sprite Position
         *DERROR = SPRGetSpriteData(DPARAMS);
     DOCUMENTATION
-        Deposit into \Param{1..4}, the screen coordinates of the sprite
-        with the index specified in \Param{0}.
+        Deposit into Parameters:1..4, the screen coordinates of the sprite
+        with the index specified in Parameter:0.
 

firmware/common/config/display/group9_turtle.inc

@@ -22,20 +22,20 @@ GROUP 9 Turtle Graphics
         TTLInitialise(DPARAMS[0]);
     DOCUMENTATION
         Initialise the turtle graphics system.
-        \Param{0} is the sprite number to use for the turtle,
+        Parameter:0 is the sprite number to use for the turtle,
         as the turtle graphics system “adopts” one of the sprites.
         The icon is not currently re-definable, and initially the turtle is hidden.
 
     FUNCTION 2 Turtle Turn
         TTLRotate(DSPGetInt16(DCOMMAND,4));
     DOCUMENTATION
-        Turn the turtle right by \Param{0}\Param{1} degrees. Show if hidden. To turn left, turn by a negative amount.
+        Turn the turtle right by Parameter:0,1 degrees. Show if hidden. To turn left, turn by a negative amount.
 
     FUNCTION 3 Turtle Move
         TTLMove(DSPGetInt16(DCOMMAND,4),DCOMMAND[6],DCOMMAND[7]);
     DOCUMENTATION
-        Move the turtle forward by \Param{0}\Param{1} degrees, drawing in colour \Param{2},
-        pen down flag in \Param{3}. Show if hidden.
+        Move the turtle forward by Parameter:0,1 degrees, drawing in colour Parameter:2,
+        pen down flag in Parameter:3. Show if hidden.
 
     FUNCTION 4 Turtle Hide
         TTLHide();

firmware/common/config/mathematics/group4_binary.inc

@@ -87,6 +87,6 @@
 		}
 		*DPARAMS = r;
 	DOCUMENTATION
-		\Param{0} := Register 1 compare Register2 : returns $FF, 0, 1 for less equal and greater.
-		\newline
+		Parameter:0 := Register 1 compare Register2 : returns $FF, 0, 1 for less equal and greater.
+
 		Note: float comparison is approximate because of rounding.

firmware/common/config/mathematics/group4_other.inc

@@ -20,12 +20,12 @@
 	FUNCTION 33 String to Number
 		MATHConvertStringToNumber(DCOMMAND);
 	DOCUMENTATION
-		Convert the length prefixed string at \Param{4,5} to a constant in Register1.
+		Convert the length prefixed string at Parameters:4,5 to a constant in Register1.
 
 	FUNCTION 34 Number to String
 		MATHConvertNumberToString(DCOMMAND);
 	DOCUMENTATION
-		Convert the constant in Register1 to a length prefixed string which is stored at \Param{4,5}
+		Convert the constant in Register1 to a length prefixed string which is stored at Parameters:4,5
 
 	FUNCTION 35 Set Degree/Radian Mode
 		MATHSetAngleMeasure(DPARAMS[0] != 0);