Merge pull request #70 from AgonConsole8/feat/mos3-beta1

Documentation update for MOS 3.0 beta 1

Author: stevesims

.gitignore

@@ -1,2 +1,3 @@
 venv
+site
 .DS_Store

docs/BBC-BASIC-for-Agon.md

@@ -237,9 +237,9 @@ The assembler will only compile 8-bit Z80 code and there are currently no plans
 
 For the most part, the MOS is transparent to BASIC; most of the operations via the MOS and VDP are accessed via normal BBC BASIC statements, with the following exceptions:
 
-### Accessing the MOS system variables
+### Accessing the MOS SysVars
 
-MOS has a small system variables area which is in an area of RAM outside of its 64K segment. To access these, you will need to do an OSBYTE call
+MOS has a small area of memory for system state variables area which is in an area of RAM outside of its 64K segment. To access these, you will need to do an OSBYTE call
 
 Example: Print the least significant byte of the internal clock counter
 ```
@@ -248,7 +248,7 @@ Example: Print the least significant byte of the internal clock counter
 30 PRINT USR(&FFF4)
 ```
 
-Documentation for the full list of system variables can be found in the [MOS API documentation](MOS-API.md).
+Documentation for the full list of system variables can be found in the [MOS API documentation](MOS-API.md#sysvars).
 
 ### Running star commands with variables
 

docs/MOS-API.md

@@ -4,7 +4,7 @@ The MOS is a command line Machine Operating System, similar to CP/M or DOS, that
 
 It also provides the [MOS API](MOS-API.md) for programmers to use that provides some basic facilities for file I/O and other common operations for BBC BASIC and other third-party applications.
 
-This documentation explains the general features of MOS, as well as commands it offers and how to use them.  It covers the Quark 1.04 version of MOS, and the later Console8 MOS versions up to and including 3.0 Alpha 3.  Versions of MOS prior to Quark 1.04 may be missing some features described below.
+This documentation explains the general features of MOS, as well as commands it offers and how to use them.  It covers the Quark 1.04 version of MOS, and the later Console8 MOS releases up to and including MOS 3.0.  Versions of MOS prior to Quark 1.04 may be missing some features described below.
 
 ## System Requirements
 
@@ -18,7 +18,7 @@ Technically MOS will work without an SD card, but you won't be able to do much w
 
 MOS supports the use of an SD card to store files and programs.  The SD card must be formatted as FAT32, and must be 32GB or less in size.  MOS supports automatically running a script file on boot and a way of adding new commands.
 
-### Moslets
+### Moslets
 
 "Moslets" are a special type of program that are intended to extend the functionality of MOS by adding in new commands.
 
@@ -73,7 +73,7 @@ NB:  This assumes that MOS is still talking to the VDP, as it is the VDP that is
 
 MOS provides a command line interface (CLI) that allows you to interact with the Agon file system and perform some basic control over your Agon computer.
 
-The MOS CLI is loosely inspired by the Acorn MOS present in the BBC Micro and later Acorn computer systems like the Archimedes.
+The MOS CLI is loosely inspired by the Acorn MOS present in the BBC Micro and later Acorn computer systems like the Archimedes.  The features and facilities supported by the MOS command line have evolved over time, with MOS 3.0 supporting many more commands than earlier versions of MOS.
 
 MOS works alongside the Agon's VDP, using the facilities of the VDP to display text on the screen and accept input from the keyboard.  The VDP provides some useful facilities, such as a "paged mode" that will stop the screen from scrolling until you press the `SHIFT` key to continue, or `ESCAPE` to exit.  Paged mode can be toggled on and off by pressing `CTRL+N` and `CTRL+O` respectively.
 
@@ -87,7 +87,7 @@ The MOS CLI line editor will also provide some basic command history, keeping tr
 
 The Console8 MOS 2.2.0 release also adds support for pressing the `PAGE UP` and `PAGE DOWN` keys to quickly step through the command history.
 
-Also added to the 2.2.0 release is "tab completion".  If you start typing a command and then press the `TAB` key, MOS will attempt to complete the command for you.  This includes both built-in commands, moslets found in the `mos` folder, programs found in the current directory, and programs found in the `bin` folder.  In MOS 3.0 onwards, the tab completion uses the `Run$Path` variable to determine where to look for commands.
+Also added to the 2.2.0 release is "tab completion".  If you start typing a command and then press the `TAB` key, MOS will attempt to complete the command for you.  This includes both built-in commands, moslets found in the `mos` folder, programs found in the current directory, and programs found in the `bin` folder, or file names within the current directory.  In MOS 3.0 onwards, the tab completion uses the `Run$Path` variable to determine where to look for commands.
 
 There is also support for programmable function keys in the 2.2.0 release.  For more information on that see the [`Hotkey` command](mos/Star-Commands.md#hotkey).
 
@@ -109,6 +109,8 @@ MOS offsets a number of inbuilt commands that allow you to interact with the Ago
 
 The various commands available in MOS are described in the [MOS Command Reference](mos/Star-Commands.md).
 
+The command interpreter in MOS, as of MOS 3.0, has become fairly sophisticated.  It will support user-defined [commands aliases](mos/System-Variables.md#command-aliases), and the use of [system variables](mos/System-Variables.md).  As well as the ability to run [moslets](#moslets) and program files directly (as [described above](#the-run-path)) it can now also directly run any file that has a ["run type"](mos/System-Variables.md#file-type-variables) set up for it by simply typing the name of the file.
+
 ## MOS System Variables
 
 From MOS 3.0 onwards, MOS supports the concept of [system variables](mos/System-Variables.md).  These can be used for user programs, as well as providing ways to gain information about the system and control the behaviour of MOS.

docs/MOS.md

@@ -183,9 +183,12 @@ Using this command you can set the function keys `F1-F12` on your to perform a s
 1. If no parameters are provided, then the current hotkeys will be displayed.
 2. If a function key number `n` is provided alone without a command string, then the current command assigned to that function key will be cleared.
 3. If a function key number `n` and a command string are provided, then the command string will be assigned to that function key.
-    - If the command string includes `%s` then the current input line will be substituted in place of `%s`.
+    - If the command string includes `%s` then the current input line will be substituted in place of `%s`
+    - MOS 3.0 supports more sophisticated [argument substitution](Argument-Substitution.md) options
 
-As of MOS 3, hotkeys are stored using [system variables](System-Variables.md#hotkeys), and can be defined using the `Set` or `SetMacro` commands.  They also support more sophisticated [argument substitution](Argument-Substitution.md) options.
+Pressing a function key that has a hotkey definition set will result in the current input line being replaced with the defined hotkey string and "return" being automatically pressed.
+
+As of MOS 3.0, hotkeys are stored using [system variables](System-Variables.md#hotkeys), and can be defined using the `Set` or `SetMacro` commands.  Via the use of `Set` or `SetMacro` you can define hotkeys that do not automatically press "return".
 
 ## `If`
 

docs/mos/Star-Commands.md

@@ -60,11 +60,13 @@ If an application is started up using an `obey` file, then often the obey file w
 
 ## Command aliases
 
-If you set up a system variable in the format `Alias$Name` then this will set up a new command alias that can be used from the command line with the given name.  For example, one could add a new `mode` command using `*set Alias$Mode vdu 22 %0`.
+If you set up a system variable in the format `Alias$Name` then this will set up a new command alias that can be used from the command line with the given name.  For example, one could add a new `mode` command using `*set Alias$Mode vdu 22 %0`.  This would allow you to run the command `mode 1` to change the screen mode to mode 1.  The command will be expanded to `vdu 22 1` when the command is run.
 
 Aliases support [argument substitution](Argument-Substitution.md).  Any unused arguments (beyond the last used argument) will be automatically appended to the end of the resultant command.
 
-In MOS 3.0 an alias can be only a single command and cannot be a sequence of commands.  If you wish to create a sequence of commands you can use an obey file, potentially using an alias to run the obey file.  Support for multiple commands in an alias may be added in a future version of MOS.
+An alias can include multiple commands, separated by carriage return characters (`|M`).  If one command in an alias sequence fails, the rest of the commands will not be executed, and the error reported.
+
+As an alias will append any unused arguments to the end of the command, the example above for a `mode` command is actually flawed.  Whilst `mode 1` would result in a `vdu 22 1` command, `mode 1 2 3 4` would result in the command `vdu 22 1 2 3 4` which is still technically a valid VDU command, but would send 3 extra bytes to the VDP, performing a `VDU 2`, `VDU 3` and `VDU 4` commands (enable printer, disable printer, and "write text at text cursor"), and is unlikely to be the intended behaviour.  Therefore a better version of the command would be `*set Alias$Mode vdu 22 %0|M#`.  This splits the alias into two separate commands, the first being a `vdu 22` passing in the first argument, and the second command will be a `#` with all other arguments following it.  The command interpreter considers commands beginning with a `#` to be a comment, and will ignore it.
 
 
 ## File type variables
@@ -73,10 +75,12 @@ System variables are used to define how certain files should be loaded or run wh
 
 These aliases are named in the format `Alias$@LoadType_extension` or `Alias$@RunType_extension`, where the `extension` matches the filing system extension for that file type.  Load and run aliases also support [argument substitution](Argument-Substitution.md).  The system defines a few such aliases, for instance `Alias$@RunType_obey` is set to `Obey %*0`.
 
-Attempting to load or run a file with an extension that does not have a corresponding alias will result in the system (using `LoadFile` or `RunFile`) will result in an `Invalid command` error.
+Attempting to load or run a file with an extension that does not have a corresponding alias (using `LoadFile` or `RunFile`) will result in an `Invalid command` error.
 
 The system will set a variable named either `LastFile$Run` or `LastFile$Load` to the alias expansion that was used to run or load the file.
 
+The load and run aliases are executed in exactly the same way as command aliases.  They can therefore also contain mutiple commands, separated by carriage return characters (`|M`), and will automatically append any unused arguments to the end of the expanded command string.
+
 
 ## CLI
 
@@ -105,8 +109,13 @@ Hotkey definitions support [argument substitution](Argument-Substitution.md).  A
 
 If a hotkey definition is set as a macro variable (using `SetMacro`), then the system will expand the macro when the hotkey is pressed.
 
-In MOS 3.0 a hotkey can be only a single command and cannot be a sequence of commands.  If you wish to create a sequence of commands you can use an obey file, potentially using a hotkey to run the obey file.  Support for multiple commands in a hotkey may be added in a future version of MOS.
+A hotkey definition that ends with a carriage return character (`|M`) will automatically press return when the hotkey is pressed.  When used in a CLI this means the command will execute immediately.  Hotkeys set using the `*hotkey` will automatically append a carriage return to the end of the command.
+
+In MOS 3.0, whilst a hotkey variable can technically contain multiple lines, split by `|M`, the system will only use the first line of the variable, and the rest will be discarded.  This limitation is due to how the MOS line editor works.
+
+If you wish to create a hotkey that can run a sequence of commands then there are two options.  Firstly you could create an obey file, and define a hotkey to run the obey file passing in all the arguments.  Alternatively you could define a command alias that can run a sequence of commands, and define a hotkey to use that alias.  Please note that both of these options are only really suitable for running multiple MOS commands, and cannot be used for multi-line input in other environments such as the BBC BASIC command line.
 
+Support for multiple commands in a hotkey may be added in a future version of MOS.
 
 ## System
 

docs/mos/System-Variables.md

@@ -404,7 +404,7 @@ Works just like "Call a buffer" (command 1), except that it also accepts an adva
 
 Works just like the "Conditional call a buffer" command (command 6), except that it also accepts an advanced offset.
 
-<h2 id="command-13">Command 13: Copy blocks from multiple buffers into a single buffer</h2>
+## Command 13: Copy blocks from multiple buffers into a single buffer {#command-13}
 
 `VDU 23, 0, &A0, targetBufferId; 13, sourceBufferId1; sourceBufferId2; ... 65535;`
 
@@ -813,7 +813,7 @@ The various different values that pixels will be mapped to should immediately fo
 When a buffer is used for mapping data, that buffer must exist, and must contain a single block of at least the number of values required for the given number of bits per pixel.
 
 
-<h2 id="command-80">Command 80: Set a buffer to be used for a callback</h2>
+## Command 80: Set a buffer to be used for a callback {#command-80}
 
 `VDU 23, 0, &A0, bufferId; 80, type;`
 

docs/vdp/Buffered-Commands-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 state variable values](../MOS-API.md#sysvars), `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-sysvars).
 
 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.