BETA VERSION 4, RELEASE 2 (May 14, 2019) NOTES:

Note that everything in the notes for Alpha's 1 to 3, and Beta's 1-3, still apply. These will eventually all be merged into one document.

NOTE: IF YOU ARE A USER BRAND NEW TO NITROS-9/EOU, PLEASE READ THE "NitrOS9 Ease of Use - Beginners documentation.rtf", WHICH HAS THE BASIC INSTRUCTIONS FOR GETTING EOU (Ease of Use) RUNNING, AND SOME TIPS ON USING IT.

Please report any problems, bugs found, questions, etc. in the Discord NitrOS9EOU group, or via email to me @ curtisboyle@sasktel.net.

It should be noted that, for the most part, Beta 4 is "cleanup/bugfix" release (see the change log at the end of this document), although it does have some other improvements and 2 additional games as well.

QUICK NOTE ON STARTUP FILE:
The current startup file loads all system fonts, and a couple of batches of small, commonly used utilities (which makes the system seem faster once it is booted). However, if you would rather start with the bare minimum (just the one 40 column window, no utilities/fonts, etc. pre-loaded) you can simply hold down a SHIFT key while it is booting, and it will bring you to the shell much more quickly.

QUICK NOTE ABOUT GSHELL:
For programs that do not require full screen windows: For apps ran from the main GUI window, their icons are set up to run on a specific window type (ex. 320x200x4, 320x200x16, 640x200x4), that you can then resize to the minimum that application will allow. For the ones running from the Tandy menu, they also have minimum sizes, but they will always be created with the window type you are running GShell in, AT THE TIME OF LAUNCHING THEM. This means that you can change types while running, and then launch such apps, so that you can run them beside other, regular GUI apps, of the same type. This can help you if you want to run, say, Rogue next to a shell on the same screen. Rogue defaults to 640x200x4; launch it, and make it's size small enough to leave enough room for another app. Then, if you set your GShell resolution (in the pull down VIEW menu) to the same resolution/color, any of resizable Tandy apps (shell, control panel, calculator, clock) that can fit it's minimum size on the screen, will let you place it beside it.

QUICK NOTE ABOUT VCC/OVCC:
Since RUNB and BASIC09 are starting to get fully 6309 optimized, and VCC has incomplete support for the 6309, you may start hitting glitches (the hardware divided instructions in particular). This does not affect the 6809 versions. The 6309 versions will run fine on real hardware, or on MAME. 

NOTE: This is now being actively worked on (as well as making VCC cross platform). Stay tuned on the Cocolist for details and updates. NOTE: We have nothing to do with that project (called OVCC).

On the 6309 image, I have made pre-merged special RUNB (/dd/cmds/runb_alpha3) that contains the older version from Alpha 3 that shouldn't use those instructions, but it does include the new GFX2 (See below), for those of you using VCC. If you are going to go that route, do a LOAD /dd/cmds/runb_alpha3 after booting, to make sure that you have the older, more VCC compatible version loaded, and you hopefully won't hit any issues.

QUICK NOTE ON FUTURE UPDATES:
Since we are doing public Betas now, one thing we need to worry about is people making changes/additions/customizations to the images themselves. Since we are sending out hard drive images "pre-built", this would wipe out any said changes you may have done. So, this is a warning to back these up before getting the new image(s), and copy them back over afterwards. It might be easier if you create your own directory and keep all of your new stuff in it (easier to back it up). You can then either back these up to a new floppy or floppy image, or copy them to a Windows/Mac/Linux box using the varying utilities that are around for that purpose (like Toolshed, etc.). On a real Coco or MAME, you could even have a 2nd hard drive image for all of your local stuff (VCC, at this time, only supports 1 hard drive image mounted at a time).
If you go the floppy/floppy image route, and you have made your own directory of your additions, you should be able to do a CD <your directory name>, and then do MSCOPY -alm * <your backup floppy name, like /d1) #56k. This will copy all files and sub-directories (like DSAVE, but *much* faster) as long as you have enough disk space.
If you find your stuff is too big, you can try compressing them first with one of two archive compression programs (please note that both add their own extension automatically - .ar or .lzh):
AR (AR -u <archive filename> <filenames to compress>). This is faster than the other method but doesn't compress quite as well. It also only does subdirectories if you manually specify them, and can only handle a certain number of files at a time (you can do it several chunks; the -u means "update archive", which means you can create an archive with some files, and then run AR -u again with different files and it will combine them into the same archive. Extracting preserves attributes, and will create directories as needed automatically, and doesn't have a limit to the number of files you are extracting, unlike when it is compressing.
The other option is LHA. It compresses better (but slower), and has a ton more options, but is more complicated to use. I don't believe it has a (reasonable) limit to the number of files to compress. Recommended usage for our situation here is:
LHA a -xpr <archive filename> *
Again, run from your new directory, and this will automatically do all sub-directories as well. The options used are: 'a' (add to archive - will create a new one if your archive filename doesn't exist, or add any new files to an existing one). The '-xpr' is actually 3 options: x means allow extended filenames, p means to keep full paths, and r means recurse through sub-directories.
To restore, CD to the directory you want to restore into, and then LHA x -l <archive filename>. This will extract the entire archive, with paths, and show the paths on screen while it is extracting.

Quick note on Snakebyte game: I had some oddities where some get/put buffers (or fonts) appear corrupt, or it returns "buffer size too small" errors, when you run another program after running Snakebyte and quitting that game.  From what I am able to determine, it is because Snakebyte doesn't clean up it's own get/put buffers after itself, and if the next program doesn't kill it's own buffer group before sizing/reloading them, it may experience these errors. Most programs do perform get/put buffer cleanup on exit. For programmers, probably the safest way to deal with situations like this, is to have your program send a KilBuf for your get/put buffer group, for the whole group (usually, you are using your own process # for the group #, so that you know it is unique, so you would send a 1b 2a <process#> 0), and then size, load/get the buffers needed for your game. This way, you clean up after any misbehaving program that didn't do this yourself, and you can make sure your get/put buffers are the size you actually want.

In the meantime, if you quit the 2nd game (which will then usually clean that group up itself), and then relaunch it, it will be fine.

NOTE: BETA 4 RELEASE 2 HAS UPDATES FROM THE ORIGINAL BETA 4!
CHANGES FROM BETA 3:

1) Fixed GSHELL/6809 to properly make a 40/80 x 24 to be a "full screen", rather than a resizable window (was done in previous beta, but the new 6809 version got missed getting copied over to the final release).

2) Added Zack Sessions Klondike Solitaire game to /dd/games. One odd quirk - the animated cards barely show up in the 6309 version; it is drawing/erasing them too fast. You can faintly see them in the 6809 version.

3) Added the Coco/OS-9 port of the original Colossal Cave adventure game by Wille Crowther (with additions by Don Woods) (called ADVENT). There have been reports that some versions floating around are corrupt (I have seen one of those, myself); I am hoping this is the full, uncorrupted version, but I have not played through the whole game to verify. Please let us know.

4) Fixed up some fonts, and removed some duplicates. Startup time should be slightly faster, and the Rogue fonts will actually show the Rogue graphics characters.

5) Added a new utility FONTSPLIT, which will split a file with multiple fonts into separate fonts, with the font # as part of the filename. Source code, in BASIC-09, is in /dd/sourcecode/basic09/FontSplit.b09.
NOTE for DECB users: The 8x8 fonts (except the 224 character fonts) are compatible with DECB, if you load them into the right spot (and skip the 11 header bytes that NitrOS-9 uses). All 40+ of them.

6) GRFDRV and CoVDG are now both implementing Erik Gavriluk's RGB to Composite color conversion tables, which are more mathematically accurate than the original tables (at least, according to Nick Marentes). For those of you running on Composite monitors (or older TV's), please let us know if it appears to be more accurate compared to RGB mode. (Try games like Thexder, Shanghai, Smash, or graphical viewing programs like VIEW, etc.)

7) Finished cleaning up commands that were different between NitrOS-9 3.3.0 and EOU. Most are very minor changes (ATTR, DEVS, DISPLAY, ERROR, FORMAT, HELP, IRQS, MDIR, PROC, PROMPT, PWD, PXD, REBOOT, SMAP, WCREATE). 

Some others had more extensive changes:
  BACKUP (supports .DSK images)
  COBBLER (now supports variable sized clusters)
  COPY (more robust handling errors)
  DCHECK (crunched around 300 bytes in size)
  DED (supports variable sized clusters, including in bit allocation map editing)
  DISASM (add 'S' option to choose start/end offset of disassembly)
  DSAVE (adds 't' and 'n' options. I have also patched it for now to call TMOD2 (which is the new style TMODE) that it expects. A lot of 3rd party software, that we don't have source for, wanted the old style TMODE command, so that is the default on EOU. We eventually plan on making a "Fat binary" version of it (and XMODE) that will handle both syntaxes, and thus should be compatible with all programs.
  LOGIN (supports Hangup signal)
  MAKDIR (You can now create a full path of directories in one command)
  MEGAREAD (allows you specify # of 1K blocks to read)
  MFREE (works with 4 or 8K MMU blocks, minor optimizations)
  MMAP (supports 4 or 8K MMU blocks for non-Coco systems)
  PMAP (supports 4 or 8K MMU blocks, dead processes better, and is smaller)
  SHELL21 (supports Hangup signal).

Commands that have unique 6809 and 6309 versions: 
  CMP - slightly shrunk, slightly faster (both 6809 & 6309 versions)
  DIRSORT- Speed improvements to both 6809 & 6309 versions
  DEBUG - code crunched, and more verbose error reporting. Both 6809 & 6309 versions. Please Note: I have not tested all modifications to DEBUG, as I am not that familiar with it. If anyone who is familiar with it can test it, and report any bugs, please do so.
  PADROM - Initialization routine 6309 optimized.
  TOUCH - Slightly shrunk (both 6809 & 6309 versions)

And, finally, two programs with fairly extensive changes, that need some further testing (preliminary tests all seem to be working fine, but I have not covered every possibility. Please report any bugs):
  ASM - I made new edition 11's of the level 1 assembler; it has some speed optimizations (7-13% faster, depending on options, in both the 6809 and 6309 versions), and also lets you add a "-" in front of "o=<filename>" to automatically overwrite an existing object file. Since we have not tested every possible case resulting from the changes, the old edition 10 version is still there, named ASM_ED10 in the CMDS directory. If you discover a discrepancy where ASM11 is generating the object file, listing, symbol table, etc. differently than edition 10, please send the source code that caused it (and an explanation of what is different) to curtisboyle@sasktel.net, and I will see if I can fix it. (I should mention that 6309 version of edition 11 is up to 32% faster than the original 6809 edition 10 now). I should note that some previous improvements were not well documented, like that it handles label names >8 chars (as long as the first 8 are unique), output listings can now go to 132 columns, labels can be case sensitive or not, '@' signs are allowed in labels, and TAB chars are allowed to separate the fields on each line (same as spaces)
  OS9GEN - This version has the added -e option to allow fragmented boot files, some minor optimizations, and I think I fixed an existing bug in 3.3.0 that used a wrong register. This has also not been extensively tested (I use KwikGen, myself). Please let me know of any bugs.

8) Since Bill Nobel's fix to loading GRFDRV on the 6809 solved a system memory full error, the RAM disk driver and descriptors (Rammer, R0, MD) have been added back in. RAMMER has also been fixed so that MD works properly on 2 MB RAM or higher systems, and also fixes a bug if a RAM drive needed more than 127 MMU blocks. On the 6809, it is also faster. RAMMER does have some limits (when used as a regular RAM drive, with R0), that you should be aware of if you want to change your ram disk size (you can even resize it (losing all contents of the previous one, so be careful!), by doing 'DEINIZ /r0' until a DDIR command no longer shows R0 as an active device. Then you can DMODE /r0, changing parameters, INIZ /r0, then FORMAT /R0, and you will get your newly sized RAM drive).
Limits to R0:
1)  sct (sectors per track) and t0s (sectors per track on track 0) can NOT exceed 255. It will ignore anything past that.
2) The number of cylinders (cyl) multiplied by the number of sides (sid) can NOT exceed 255. It should exit with a Memory Full error if you try (even if you technically would have had enough memory to do it).

The largest RAM drive I would recommend would be 1.6 MB (6400 sectors). For that, I would recommend:
 DMODE /r0 cyl=64, sid=2 sct=20 t0s=20
(all of these values are in hexadecimal). This will give 6400 sectors free. It should be mentioned, to use the ram drive, you can use DMODE to set the parameters first (or use the default 128k settings), then type INIZ /r0... and then FORMAT /r0.

NEW NOTES FOR RELEASE 2 (MAY 14, 2019):

1) Added Mix-Up game by Don Langkamp.

2) Slight optimization of 6809 & 6309 CoWin (mainly to shrink them slightly). 

3) GShell will now let you keep moving the mouse (albeit much more choppy than normal) while loading a large directory, to help show that it has not froze (leaving the mouse sample rate full speed slows down disk access quite a bit, so this is the current compromise).

4) Thexder (specifically, the 'THEXS' part of it) has been fixed to work properly with 2 MB RAM Coco 3's (it worked previously with 256K, 512K and 1 MB RAM Coco 3's).

5) Bonk game added. It has it's own folder in the GAMES folder, since it has map files, etc. to load as you play. This program inherits the mouse settings that you are using in GShell. This is a Bustout type game written in BASIC-09, and uses the VIEW utility to load the background graphics. If you are running NitrOS-9/6309, there is a faster VIEW utility (see previous beta notes) that will load these screens quite a bit faster - but I don't have it as the default version of VIEW, as the current version has issues with .CM3 files (Coco Max III). If you have no need for viewing .CM3 files, you can enable the 6309 optimized version by doing:
CD /dd/cmds
CP -ov view-45a-6309 view

6) Source code (in C) for a slightly older version of Cocothello has been added to /dd/sourcecode/c/cocothello. Hopefully this will help inspire some of the C programmers to work on some new games by having an example of a graphical game.

L. Curtis Boyle, May 14, 2019