Beginners notes for NitrOS-9 “EASE OF USE” image ALPHA VERSION 1

THIS IS ALPHA DOCUMENTATION, FOR THE ALPHA VERSION OF THE NITROS-9 EASE OF USE PACKAGE. PLEASE SEND FEEDBACK TO
L. CURTIS BOYLE (curtisboyle at sasktel dot net),
BILL NOBEL (b_nobel at hotmail dot com),
AND DAVID LADD (davidwladd at gmail dot com).
We want to try and make this package as easy to use/understand as possible.

The NitrOS-9 “EASE OF USE” project's goal is to make available a “pre set-up” version of NitrOS-9, so that the beginner NitrOS-9 user does not have to worry about setting up a boot disk/file, setting up MultiVue (the GUI program), set up programs to have their needed file(s) set up in specific directories, etc.

It is meant to be “point and click”, and have (almost) all programs set up to run from a command prompt without having to change between various CMDS directories, etc.

It is also meant to have more robust HELP than the stock OS-9 help has; by including various 3rd party apps/utilities, etc.

This by no means indicates that a power user can't use this package - they can do everything from the command line like they are used to, if they wish.

With a lot of really useful extra commands compared to stock OS-9 Level II.

It should be mentioned that, in order to make the experience as painless as possible, that their are system requirements for this package that are higher than the stock OS-9 Level II.

We are also, for the first release, limiting the hardware supported to 4 basic configurations, that we feel are the most common for people that have wanted to try NitrOS-9 out.

We will likely expand this in the future, but for now it is easier for use to maintain/test/get feedback from less versions.

System requirements for this version are:
- A Coco 3 with 512k, either 6809 or 6309, with a CocoSDC, OR
- A Coco 3 emulator (MAME or VCC) set up as a Coco 3 with the specs above, but replacing the CocoSDC with a hard drive emulation (built into both emulators.

Because the 6309 version of NitrOS-9 has extra features, and is faster, if you have the hardware to support it, we would highly recommend installing that version.

The hard drive images (6809 and 6309) are common between real hardware and the two emulators; the emulators also include a floppy image (containing the main boot, with the emulated hard drive drivers), that will then kick into the hard drive image.

So, on an emulator, you must mount the file “63SDC.DSK” into floppy drive 0, and mount the file “63SDC.VHD” into hard drive 0.

Then, type DOS to boot.

For the CocoSDC, you need only copy the 63SDC.VHD file onto your SD card, and after you have fired up the Coco with that card in the CocoSDC, change to that drive image, and type DOS.

If you have Coco Explorer, you can use it's menu system to select the card as well.

If you plan to be using NitrOS-9 a lot, you can set up the CocoSDC to automatically mount that image when you turn the Coco on.

Upon booting, you will first encounter the “NitrOS-9 BOOT” screen.

All of stuff that flies by on the screen is a listing of all of the system modules, as they are loaded, and is mainly meant for debugging, and you shouldn't need to pay much attention to them (and it does give you something to look at while the system is booting).

After the operating system is loaded, the screen will clear to black on white, 40 column text, and it will load in large library of graphical fonts (48 as of this writing), paint patterns, mouse cursors, etc. that are used by the GUI and other programs.

It will then prompt you for the time (these first releases will use the software clock), fire up two more (80 column) windows in the background, display the current monitor type NitrOS-9 is defaulted to (currently RGB), and then give you instructions on how to change the monitor type, and how to start up Multi-Vue, for the point and click mouse interface.

We should also mention that we have defaulted the initial boot screen to 32 columns, and the main window (called “/term”) is defaulted to 40 columns.

This is help users running on RF or composite screens, so they can read the text easily.

The GUI (called “Multi-Vue”, and the main program to start it called “GShell” (short for “Graphical Shell”), also default to 320×200 resolution for the same reason.

Two other windows are currently fired up by default that are 80×25, so people with RGB monitors can choose those to start on if they wish.

Quick notes on special keys in NitrOS-9 I will group these into 3 sections: Universal (keys that do special things no matter what program you are in), SHELL (the main SHELL command prompt), and MULTI-VUE (the GUI).

This is not a complete list (see the manuals, available online at the Coco Archive at http://www.colorcomputerarchive.com), but the most common ones that you will find yourself using a lot.

NOTE: I will be listing the keys from an actual Coco 3; consult your emulator documentation to see what equivalent key(s) will do the same thing (whether it be Windows, Mac or Linux).

Also, emulators like MAME¹⁾ allow you to change these, anyways.

Key repeat is on by default, turned on (hold down a key, and after a short delay, it will start repeating).

You can change this in the Control Panel in GSHELL, both to change the delay length and the repeat speed, and even shut if completely off.

Programs can also do this themselves, if they wish.

<CLEAR> = Go forward to the next window.

These can be completely separate full screen windows, or multiple windows on the same screen.

<SHIFT-CLEAR> = Go backwards to the previous window.

<CTRL-CLEAR> - Toggles the “keyboard mouse” on or off (the system boots with it off).

This will change the normal function of the 4 arrow keys, and the F1/F2 keys, to simulate a mouse.

The four arrow keys move the mouse in the four directions (you can hold 2 down at once to move diagonally), and F1 and F2 are the left (red) mouse/joystick button and right (black) joystick/button respectively.

Most programs only need F1, as a lot of people back in the 1980's when OS-9 Level II was released, still had the older 1 button joysticks or mice.

While the keyboard mouse is on, the arrows jump 8 pixels each time you hit one.

If you hold <CTRL> and an arrow at the same time, the mouse cursor will jump to the far edge of the screen corresponding to which arrow you hit.

If you hold <SHIFT> and an arrow at the same time, you will move 1 pixel at a time.

Please note - if you are running on a graphic window, but just printing text, the keyboard mouse overrides the normal functions of the arrow keys (like backspacing, etc.).

If you find that you can't backspace, and you see the mouse cursor on the screen, hitting <CTRL>-<CLEAR> will switch back to normal keyboard mode.

<CTRL-0> (that is a zero, not the letter 'O').

This toggles the CAPSLOCK on and off (the system boots with it off).

This forces all text you type to uppercase.

<CTRL-W> - when listing text files to the screen, this will Pause the display (like <SHIFT>-<@> in Disk Basic).

Any other key un-pauses.

There are some other <CTRL> keys used to generate special symbols that the Coco keyboard doesn't directly support (an example is <CTRL-minus> to do an underscore); you can find those in the OS-9 Commands section of the OS-9 Level II manual, in Appendix D "OS-9 Keyboard Control Functions"²⁾, so I won't repeat all of them here.

Shellplus 2.2A is the default shell we have installed.

It has some special features, like command history, that are incredibly useful as a time saver.

It also allows users to change the default prompts, and we have picked (as a default) one that give you a lot of info about the window you are looking at, without taking up too much room.

Each window with a shell on it will show you 1) the window name (like “/term”, the process # (like “02”), and the data directory you are currently in (like “/dd”).

By default, we have command line history enabled in the shell with full editing keys.

This means that you can bring up previous commands you have used on this particular window/shell, and re-use them (or edit them), without having to retype the whole thing.

You can see these by tapping the UP ARROW (to go backwards through your command history), or DOWN ARROW (to go forwards through your command history).

(this is similar to as you see on Linux, Windows and OSX command lines).

You can use the line verbatim again by hitting <SHIFT-RIGHT ARROW> to go the end of the line, and then hit <ENTER>.

You can also edit the line, using the following keys:
<LEFT ARROW> - move left one character
<RIGHT ARROW> - move right one character
<SHIFT-LEFT ARROW> - move to beginning of line
<SHIFT-RIGHT ARROW> - move to end of line
<CTRL-LEFT ARROW> - delete character at current character position; shift rest of line left.
<CTRL-RIGHT ARROW> - insert character at current character position; shift rest of line right.
<ENTER> - accept current line up to current position as is, and execute it.
<UP ARROW> - abort current line edit, go back up one line in command history
<DOWN ARROW> - abort current line edit, go forward one line in command history

Note: One difference with Windows command prompts - hitting <ENTER> in the middle of line will cut the command off at that position and execute it; Windows will take the whole line.

If have made edits but want to use the remaining part of the line verbatim, simply hit <SHIFT-RIGHT ARROW> first and then <ENTER>.

A further note: The editing keys listed above (but not the history keys) are actually universal to all programs that do the equivalent of an INPUT or LINE INPUT (ie asking for a line of input at a time, not just a single character).

So other programs, whether they are written in assembly, C, Pascal, BASIC-09, etc. will all allow those editing keys - but they will be based on the last previous input ONLY.

Some programs can also “pre-load” the text buffer with default text, and display it, with you able to edit that using the keys above, as well.

SHELL also has a special “enable wildcards” character (:) that, if you put it as the beginning of the line, will enable SHELL wildcarding (? for single character wildcard match, * for multi-character wildcard match, and [a-b] for a single character wildcard match within a certain ASCII range ([a-b] would mean that the character has to be an 'a' or 'b'; [0-9] means it would have to be a numeric digit, etc.).

There are some limitations to SHELL wildcards that you should be aware of, though:

1) They only work for commands that accept multiple filenames as parameters on the command line

2) The internal buffer that SHELLPLUS uses to generate a wildcard file list is limited in size (I think around 2k)

3) If you send them to a program/utility that does it's own internal wildcarding, you may confuse that program.

Some commands that do use it well are DEL, CP, and TOUCH.

Most of the time, you will simply be using your mouse/joystick (or even keyboard mouse) to select menus, programs, folders, drives, etc.

But, there are some special keys you can use as well, while in GShell:
<Q> - Quit GShell.

This will ask you if you are sure; you can use the mouse to answer, or hit <Y> or <N>.

This is the same as File→Quit.

<S> - makes an overlay window with a shell in it, so that you can run a command line.

Type EX to quit the shell once you are done.

<$> - makes a resizable window shell on a different screen (same as File→Shell menu)

<?> - Calls HELP command for the currently selected file and displays it in an overlay window (same as selecting a file with a single click, and then clicking the question mark in the upper right part of GShell).

If there is no help for the file, it will say “No help available”

< = > - Refreshes currently selected directory.

Under NitrOS-9, vs. the original OS-9 Level II, it should do this automatically, if a file has been added/deleted/changed.

Sometimes it will miss if you have an overlay SHELL running on top of GShell at the exact moment a file has changed.

<SHIFT-UP ARROW> - will go up a page of icons (if there is a page up to go to).

Same as clicking the up arrow on the right.

<SHIFT-DOWN ARROW> - will go down a page of icons (if there is a page down to go to).

Same as clicking the down arrow on the right.

When you first fire GShell up, it reads it's environment file (which is a list of default settings, etc.), and then displays the floppy and/or hard drives it knows about on the left side.

(There is also a printer, and a trash can).

You select a drive (make sure you have a disk in it, if it is a floppy!) by pointing the mouse cursor to it, and left clicking once.

You will then see a display of the files/folders/applications on it, which you can scroll through using the up and down arrows on the far right side.

To select a file/folder/application, left click it once (it will highlight it), and then you can click on the Files menu and do various things to it (depending on the type, some selections will be non-bold and not accessible to you), such as list the file, copy it, get statistics on it, rename it, delete it, etc.

There is also a Sort option, to force a directory to sort alphabetically.

If you follow the OS-9 “Standard”³⁾, then directories will be all uppercase and will show up first, as well as AIF (Application Interface Files - these are used for apps, like the old PIF files from back in Windows 3.xx days) files, and then all other files.

There will be folders (also known as sub-directories) that contain more files, data files (which look like little pieces of paper with their corner folded), regular program files (which look like mini-GShell windows), and AIF program files (which will actually have unique icons).

Once again, left clicking once will then let you select the Files menu and perform actions on them; you can also click the < ? > (question mark) in the upper right corner to get help on a program file (if help is available in the help database - warning: this is a work in progress).

If you see a program icon (generic or AIF), you can double-Left click it to launch the program.

Some programs will then immediately run (like most of the game icons in the Games folder), others will prompt you for parameters to pass to the program first, in an overlay window.

(The game Shanghai will do this: you can hit <Enter> to run with no parameters (default tile set), or type '-f=cards.til' or '-f=traffic.til' (do not include the quote characters) to select an alternate tile set).

A lot of programs will create their own full sized screen all to themselves.

A few, and most of the 'Tandy Menu' mini-applications (the funny looking 'X' type thingie left of the 'Files' menu - it is meant to look like a miniature version of the TC (Tandy Corporation) logo) will allow you to resize and/or put more than one program on the same screen.

These will show a box that you move around with the mouse (to position where you want the upper left corner to be), and at the same time shows you the minimum size the window has to be for that program.

Once you have the upper left corner where you want it, left click once to lock it in place, and then drag the mouse to resize it to the size you want.

Once you have the size you want, left click again to run the program in your new window.

Note: A few games support running in resizable windows, but this early alpha doesn't have those set up yet.

Two I can mention that are forthcoming are Rogue and Zone Runner.

If you get a circle with a slash through it as your mouse cursor, that means that you can't place the window at it's current location (NitrOS-9 does not currently allow overlapping windows), so you will have to pick a different spot/size.

It should be noted that, even with a 512K Coco 3, some games take a large amount of RAM, and you may not be able to run too many of those at the same time.

It should also be noted that some programs/games are smart enough to know that they are not the currently active window, and will either pause or sleep until you make them the active window again… but others will run full bore in the background while you are doing something else.

This early alpha only currently has some Demos (in the DEMOS folder), one utility (in the SYS folder), a font demo to show all the fonts (in the GFX_APPS folder), and 11 games (in the GAMES folder) currently ready to go for double-click to run.

Many more will be coming before beta releases, and the final release.

We are thinking of having this package automatically start up GShell on boot - if we do do that, would it be best to fire it up on the starting window, or one of the secondary windows that get fired up as it boots? ⁴⁾

When printing text on a graphics window - 8×8 fonts display a LOT faster than 6×8 fonts do - although they fit less text on each line.

A full screen window will show 40 columns for a 320 pixel wide screen, and 80 columns for a 640 pixel wide screen, when using an 8×8 font; you will get 53 and 106 columns respectively with 6×8 fonts.

Please be aware that not all programs check this properly, and those that don't will assume 8×8 fonts at all times.

- Hardware text screens are the fastest of all; especially on a 6309 based system.

Utilities like LIST (which lists text files) are much faster in these modes under NitrOS-9 than under Disk BASIC.

- For GSHELL - the default icons are all 4 color, so the two 4 color view modes (320×200 and 640×200) display and update much faster than the 16 color mode (which has to dynamically convert between 4 to 16 color on the fly).

- <CTRL-E> is usually used to abort a program (unless it has over rode that - kind of like ON BRK in Coco 3 BASIC), but if the program has done funky things like turn the cursor off, or shut off screen echo, or turned page pause on, etc., those weird settings will likely stay that way on the window you are on.

Try to quit a program through it's own quitting mechanism (Quit menu, etc). to avoid this.

If a program gets “stuck” and you can't get it stop no matter what, you can <CLEAR> to another shell window, then type PROC to get a list of processes.

Find the program name on the window that is running amok, and then type KILL <process #> to forcefully abort it.

The same problems with hitting <CTRL-E> listed above will apply, though.

- On a real Coco, hitting the RESET button once will immediately reload the NitrOS9 boot file and relaunch NitrOS9.

Hitting it twice will boot back to BASIC.

- If you want to change the defaults for Multi-Vue, you can use one of the text editors included (not all documentation is on for all of these yet).

Probably the easiest it use is called ED, and it uses a mouse.

To edit the Multi-Vue/GShell configuration file, you will need to go to a SHELL window, and type the following:

CD /dd/sys
ed env.file

Most of the settings are documented in the Multi-Vue manual⁵⁾ on the Coco archive⁶⁾, and you should set them to how your system is set up (like whether your mouse/joystick is in the left or right port, whether you have a high-res mouse interface, your keyboard repeat delay/speed, and monitor type), but there are also some new ones that you may find useful:

GSHPAL0=r,g,b
GSHPAL1=r,g,b
GSHPAL2=r,g,b
GSHPAL3=r,g,b

The above 4 settings set the first four palettes that GShell itself uses, without changing the system wide default palettes.

The RGB lettings are exactly the same as used by PALET0= from the manual, and elsewhere in the env.file.

NOTE: These should be set with color 0 as the darkest (usually black), and brightening as you go until color 3 is the brightest (usually white).

This is preserve the 3D look in the menu bars, and also for some graphics viewing programs coming soon that you can incorporate into your own programs.

As long as you go from dark to light for GSHPAL colors 0 to 3, you should be fine.

DEFTYPE=<window type>
Window type can be: 6 (320×200, 4 color), 7 (640×200, 4 color) or 8 (320×200, 16 color).

This tells GShell what mode to start in when you first fire it up.

Set this to your liking; we currently have it as type 6.

- While a lot of people just hit <ENTER> for the date and time, it is sometimes useful to enter them in, so any files you edit (even if you are unaware of it - like high score save files, etc.) are more easily findable by recent written to date/times.

- For viewing manuals in the /dd/docs directory, we highly recommend using the VU utility.

NOTE:
Two copies of this documentation are in /dd/docs as well.

NitrOS9-Beginner_docs.txt is the plain text version that you can load into a text editor, LIST, run MORE or VU on, etc.

NitrOS9-Beginner_docs.os9 is an experiment - native OS9 formatted documentation.

Use LIST on this one; it should automatically switch to an 80×25 graphics window, switch to a slightly shorter font (so the letters don't run together vertically) and then have bolding, underlining, and even an italic or two.

You can pause the listing either with <CTRL-W>, or by typing TMODE PAUSE before you LIST it.

Well, that's it for quick and dirty notes for now.

Please let me know if you have any questions, need any clarification, any suggestions for me to make this easier to understand for beginners, etc.

L. Curtis Boyle curtisboyle at sasktel dot net Alpha 1 documentation 11/22/2017

Return to NitrOS-9 Ease of Use :: Tandy Color Computer