Merge pull request #935 from dionoid/master

M2000 doc updates

docs/library/m2000.md

@@ -4,7 +4,7 @@
 
 ## Background
 
-The P2000T was Philips' first computer for the home market in the early '80s, before they later switched to manufacturing MSX computers. The P2000T was a Z80-powered machine, running at a clock speed of 2.5 MHz and was built like a tank. It featured an integrated keyboard, power supply, two cartridge slots and a very innovative and fast Mini-Cassette system (MDCR), which was fully automated and used mini tapes that could hold up to 42 kilobytes of data.
+The P2000T was Philips' first computer for the home market in the early '80s, before they later switched to manufacturing MSX computers. The P2000T was a Z80-powered home computer, running at a clock speed of 2.5 MHz and it used a Mullard SAA5050 teletext display chip to produce the video picture. The machine was built like a tank and featured an integrated keyboard, power supply, two cartridge slots and a very innovative and fast Mini-Cassette system (MDCR), which was fully automated and used mini tapes that could hold up to 42 kilobytes of data.
 
 The P2000T was reasonably popular among hobbyists and kids in elementary schools in The Netherlands, as Philips promoted the machine strongly in the science and education sectors. Because of the relatively high introductory price and the fact that its SAA5050 video chip only supported a 40 x 24 character teletext display mode, the P2000T never became the success that Philips hoped for.
 
@@ -36,11 +36,11 @@ Frontend-level settings or features that the M2000 core respects:
 |-------------------|:---------:|
 | Restart           | ✔         |
 | Screenshots       | ✔         |
-| Saves             | ✕         |
+| Saves             | ✔         |
 | States            | ✔         |
 | Rewind            | ✔         |
 | Netplay           | ✕         |
-| Core Options      | ✕         |
+| Core Options      | ✔         |
 | RetroAchievements | ✕         |
 | RetroArch Cheats  | ✕         |
 | Native Cheats     | ✕         |
@@ -63,27 +63,54 @@ Frontend-level settings or features that the M2000 core respects:
 
 The M2000 core's library name is 'M2000'.
 
+**Frontend's Save directory**
+
+| File        | Description            |
+|-------------|------------------------|
+| Default.cas | Writable cassette file, which is only created/attached when starting the M2000 core **without content** |
+
 ## Geometry and timing
 
-- The M2000 core's core provided FPS is `50`
-- The M2000 core's core provided sample rate is `30000`
-- The M2000 core's base width is `240`
-- The M2000 core's base height is `240`
-- The M2000 core's max width is `240`
-- The M2000 core's max height is `240`
-- The M2000 core's core provided aspect ratio is `4/3`
+- The M2000 core's provided FPS is `50`
+- The M2000 core's provided sample rate is `30000`
+- The M2000 core's base width is `480`
+- The M2000 core's base height is `480`
+- The M2000 core's max width is `480`
+- The M2000 core's max height is `480`
+- The M2000 core's provided aspect ratio is `4/3`
 
 ## Usage
 
-When playing P2000T games using the M2000 core, you will notice that **every** P2000T game relies on keyboard input; usually the Space key to fire and the Arrow-keys to navigate, but also for simple J/N (= Yes/No) questions or when entering the number of players.
+You can use the M2000 core for playing P2000T cassette games, but you can also use it for programming your own P2000T Basic programs.
+
+### Programming in Basic
+
+When you start the M2000 core **without content**, you will see the "Philips Cassette Basic" screen with the white cursor waiting for your input. Here you can type in your Basic program and load or save your programs. An - initially empty - cassette named `Default.cas` will be attached and stored in the M2000 Save directory. 
+You can save a program using:
+```
+csave "program name"
+```
+... and load it again using:
+```
+cload "program name"
+```
+Note that only the first(!) character of each program is used for identification, so e.g. a program named "hello world" can be loaded using `cload "h"`.
+To show the index of the cassette, press F3 or Shift + Numeric keypad 1.
+
+#### Game Focus mode
+Programming P2000T Basic using the M2000 core requires full keyboard access. This works best when the core is in **'Game Focus'** mode, which allows the M2000 core to take precedence in inputs. The easiest way to automatically enable 'Game Focus' mode for the M2000 core is in **Settings > Input** where you set the option called **Auto Enable 'Game Focus' Mode** to `Detect`. Or correspondingly in retroarch.cfg set `input_auto_game_focus = "2"`. Be aware that the default hotkey for toggling the **Game Focus** mode is the **Scroll Lock** key, which might not be present on your keyboard. If that's the case, you'll need to remap this hotkey to a more suitable key.
+
+### Playing games
+
+The P2000T didn't came with any joystick ports, so every P2000T game relies on keyboard input. Usually the Space key is used to fire and the Arrow-keys to navigate, but other keys are also used to answer simple Yes/No questions or for entering the number of players.
 
 While the P2000T didn't have any joystick ports, there was a third-party company back in the '80s who was selling I/O cartridges to which you could connect up to 2 joysticks. These cartridges basically simulated actual key presses and that is exactly what the Joypad is doing in the M2000 core.
 
 Playing P2000T games using the M2000 core usually works best in one of these three ways:
 
 1. Using **Keyboard only**
-This basically means that you play the P2000T games like most people did back in the day. Do note that because of the positional key mapping, not all keys you type will display the character you expect. However, during game-play you probably won't ever notice this.
-This way of playing works best when the core is in **'Game Focus'** mode, which allows the core to take precedence in inputs. The easiest way to automatically enable 'Game Focus' mode for the M2000 core is in **Settings > Input** where you set the option called **Auto Enable 'Game Focus' Mode** to `Detect`. Or correspondingly in retroarch.cfg set `input_auto_game_focus = "2"`. Be aware that the default hotkey for toggling the **Game Focus** mode is the **Scroll Lock** key, which might not be present on your keyboard. If that's the case, you'll need to remap it - for example to the **Tab** key.
+This basically means that you play the P2000T games like most people did back in the day. 
+This way of playing works best when the core is in **'Game Focus'** mode, like explained above.
 
 2. Using both **Keyboard** and **Joypad**
 Use the **Keyboard** to answer the game's Yes/No questions and for things like entering the number of players or typing your name for the highscore list. Then switch to the **Joypad** during actual game play.
@@ -93,9 +120,9 @@ This way of playing also works best when the core is in **'Game Focus'** mode.
 This requires the use of the On-Screen Key Selector to enter the number of players or to answer Y/N questions. See the description below on how to use the On-Screen Key Selector.
 For this way of playing the core doesn't have to be in **'Game Focus'** mode.
 
-### On-Screen Key Selector
+#### On-Screen Key Selector
 
-The On-Screen Key Selector lets you simulate key presses using your Joypad controller. This allows you to play almost all P2000T games without the need of an actual keyboard. Next to the regular Joypad mappings (i.e. Navigation keys +  Space to fire), most games will ask simple Yes/No questions or allow you to enter your name in a high score list.
+The On-Screen Key Selector lets you simulate key presses using your Joypad controller. This allows you to play almost all P2000T games without the need of an actual keyboard. Next to the regular Joypad mappings (for the Navigation keys +  Space to fire), most games will ask simple Yes/No questions or allow you to enter your name in a high score list.
 
 The On-Screen Key Selector is activated by holding your Joypad's Left Bumper/Trigger/Shoulder button. Then with the D-pad you can loop through the keys and with the A/B button you then enter the highligted key.
 
@@ -132,9 +159,24 @@ To be able to use the D-pad for horizontal movement in the emulator, you should
 
 ## Keyboard
 
-The M2000 core is using **positional** key mapping, which maps every key from a "real" keyboard to the key which has the same position on a P2000T keyboard. This makes the keyboard more comfortable to use in games that require the keys to be in the correct positions. And also this allows for pressing multiple keys simultaneously.
+### Symbolic key mapping
+The M2000 core is using **symbolic** key mapping by default, which means that - where possible - keys on the PC keyboard are mapped to corresponding P2000T keys that show the same symbol, so you basically get the key which you pressed.
+
+The special keys < START >, < STOP > and < ZOEK > are mapped as follows:
+
+| RetroKeyboard Inputs      | P2000T Keys          |
+|---------------------------|----------------------|
+| F1                        | < START >            |
+| F2                        | < STOP >             |
+| F3                        | < ZOEK >             |
+| Shift + Numpad 1          | < ZOEK >             |
+| Shift + Numpad 3          | < START >            |
+| Shift + Numpad Enter      | < STOP >             |
+
+### Positional key mapping
+Optionally, the M2000 core supports **positional** key mapping, which maps every key from a "real" keyboard to the key which has the same position/location on a P2000T keyboard. 
 
-Below you can see how the keys on the RetroKeyboard map to keys on the P2000T keyboard:
+As the layout of a P2000T keyboard differs from modern keyboards, this might cause some unexpected mappings. So below you can see how the keys on the RetroKeyboard map to positional keys on the P2000T keyboard:
 
 | RetroKeyboard Inputs      | P2000T Keys          |
 |---------------------------|----------------------|
@@ -183,14 +225,14 @@ Below you can see how the keys on the RetroKeyboard map to keys on the P2000T ke
 | Down                      | Down                 |
 | Right                     | Right                |
 | Left                      | Left                 |
-| Keypad 0 .. 9             | 0 .. 9               |
-| Keypad Period .           | Double Zero 00       |
-| Keypad Enter              | Period .             |
-| Keypad Multiply *         | Clear Line           |
-| Shift + Keypad Multiply * | Clear Page           |
-| Shift + Keypad 1          | < ZOEK >             |
-| Shift + Keypad 3          | < START >            |
-| Shift + Keypad Enter      | < STOP >             |
+| Numpad 0 .. 9             | 0 .. 9               |
+| Numpad Period .           | Double Zero 00       |
+| Numpad Enter              | Period .             |
+| Numpad Multiply *         | Clear Line           |
+| Shift + Numpad Multiply * | Clear Page           |
+| Shift + Numpad 1          | < ZOEK >             |
+| Shift + Numpad 3          | < START >            |
+| Shift + Numpad Enter      | < STOP >             |
 | F1                        | < START >            |
 | F2                        | < STOP >             |
 | F3                        | < ZOEK >             |