NOOBS' GUIDE FOR HOW TO LOAD QL PROGRAMS:
=========================================

Everything I write for the QL will be provided in two formats:

- a microdrive image, with the extension .MDV

- a raw text file, with the extension _BAS (yes, that's an underline, not a dot). This is in Unix format, i.e. line-feed only, *not* Windows format, with a carriage return and line feed. So if you open it on Windows Notepad, it'll be a big block of text; open it on a bare-bones Linux notepad and it'll look fine. I don't have a working Mac to check, but the Mac uses carriage return only without line feed! Windows and Mac users should get a text editor that can handle all three types of files - Notepad++ for Windows and BBEdit for Mac.


QL emulators
============

QemuLator is shareware and the registered version will cost US$35 (you heard me!) but is probably the best out there. The unregistered version is very restricted, but will emulate a standard QL, running at normal speed with a 128K memory, and this is perfectly adequate for running any program I might want to write. Also note that QemuLator is the only one that presents the QL screen in its correct aspect ratio, whereby the screen is 512×256 pixels, but each pixel is 1.36 times longer than it is wide. This makes for some "interesting" switching between single and double pixels in the vertical resolution, although the registered version has a pixel smoothing routine that evens everything out, but at the cost of making the screen look like it's been smeared with Vaseline. See the QL's screen as a combination of the 4:3 aspect ratio of the TVs and monitors available in 1984, crossed with one of Sir Clive Sinclair's many eccentricities.

QPC2 will also work, emulating a QL running the SMSQ/E operating system that makes the QL look more like an old-school PC, on a screen at least twice as large as the standard QL resolution. The standard QL white-and-red monitor display will show up as its own window on this emulator, and any SuperBASIC using the WINDOW command (i.e. pretty much all of it) will be defined using the SMSQ/E window position rather than that of th standard QL window, so it's going to look a bit weird.

QLAY is an old DOS-based emulator that will run through DOSBox, and needs careful configuration of its QLAY.RC file to make it run at the correct speed - which means it's not particularly friendly to use, but that's life for an emulator last updated in 1999 and which will run on a late 1980s 386. Most of the QL's essential features are included but the sound is extremely capricious, and user-defined graphics are one feature that I find doesn't work at all. QLAYW and QL2K are Windows-based versions of QLAY, but I've never managed to get them to work.


What to do with the files on each emulator
==========================================

Using QemuLator
---------------

- Press F1 or F2 to select monitor or TV mode (though for emulation I always recommend monitor unless the program has been designed specifically for the TV).
- Click on microdrive #1 at the bottom of the window and select "Attach directory".
- In the "Browse for folder" window, find the folder where the required _BAS file is stored. This doubles as your microdrive image (without actually being one).
- ALTERNATIVELY to the above two points, if you have the registered version, click on microdrive #1 and select "MDV image...",and find the relevant .MDV file.
- In the lower QL window (the black bit at the bottom), type:
	LRUN mdv1_[filename]_BAS (it isn't case sensitive).
    
Using QPC2
----------

- As far as I can tell, the program you want to run must be located on your PC's C: drive.
- Right-click on the "dos1_" box at the top of the screen.
- Right-click on each folder to open it until the location of the _BAS file is reached.
- Right-click on the _BAS file and left-click on "Execute", then "Yes", then "Load".
- Click on the white-and-red QL window, locate the "K" cursor to the black input area and type RUN (QPC2 has already loaded the program).

Using QLAY
----------

This is assuming you already know how to work DOSBox, if you need to use it (which anything running Windows XP onwards will have to do, and it's also available for Linux and Mac.)

Also, make sure you have the QLAYT tools in the same directory (which is just QLAYT.EXE, as far as I know).

- Outside of the DOSBox environment, find the QLAY directory.
- To preserve the existing directory structure, rename QLAY.DIR to QLAY.DIR.BAK (QLAY will now not run its own startup programs, i.e. those that set up the TV mode differently, and suggest you LRUN win2_hello_bas).
- Copy the .MDV file to the QLAY directory and rename it QLAY.MDV (and rename any other microdrive image you want to keep as something else beforehand).
- Copy the _BAS file into the QLAY directory.
- Create a new folder called "files".
- Edit the file QLAY.RC and make sure these lines are included:
	-l win3@files\
	-l mdv1@qlay.mdv
- Change the -d line to "-d 2" to see the QL in 2:1 aspect ratio with the indicator lights showing, or to "-d 6" to get the window into 4:3 aspect ratio which is closer to a real QL.
- Start DOSBox, navigate to the QLAY directory and type:
	echo (filename)_bas > q.txt
	qlayt -c q.txt
	(If successful, which it should be, you will see a message:
	 "Created directory file qlay.dir with 1 files")
- Type QLAY to start the emulation (showing the screen full of memory-test shash), followed by F1/F2 for monitor or TV mode.
- To run the program from the microdrive image, type:
	LRUN mdv1_(filename)_bas
- To run the program from the raw _BAS file, type:
	LRUN win1_(filename)_bas
- To copy the file to the folder marked "files" (for archiving purposes), type:
	COPY win1_(filename)_bas TO win3_(filename)_bas
