

              --------------------------------------------------
             |   ######## ##     ##  ####### ##       ##        |
             |  ##        ##     ## ##       ##       ##        |
             |   #######  ## ###### ## ####  ##       ##        |
             |         ## ##     ## ##       ##       ##        |
             |  ########  ##     ##  #######  #######  #######  |
             |--------------------------------------------------|
             |     Multitasking Operating System for HP48GX     |
              --------------------------------------------------

                       Version 3.0 Beta 2.4 (c) 1997,98

                          by Stephane Cocquereaumont
                               & Philippe Dedieu

                           from Bordeaux - FRANCE! ;)




INDEX
-----

        1. Introduction

                1.1 What is SHELL OS ?
                1.2 Features

        2. Infos

                2.1 Version
		2.2 Copyright
                2.3 Authors
		2.4 Contribution

        3. Installation

        4. General informations

                4.1 Display
                4.2 Keyboard
                4.3 System Console
		4.3 Clipboard
                4.4 Power manager
                
        5. The file manager : Filer

	6. The text editor : TeD

	7. The graphic editor : EasyPaint

	8. RPL compatibility

	9. Xmodem

        10. SHELL customisations

                10.1 Startup
                10.2 SHELL.ini
		10.3 Batch files
		10.4 Splash Screen
		10.5 Changing the font		

        11. Programming
                




1. Introduction
===============

1.1 What is SHELL OS ?
----------------------

SHELL OS is a general multitasking OS for the HP48GX. It is to be placed on 
a 32Kb or 128Kb RAM card in the slot 1 of your calculator.

The SHELL's authors goal is to transform the HP48 into a handheld computer 
with multitasking OS and friendly user interface.

Note that SHELL do not use any part of the HP48 ROM and is therefore totally 
independant with the built-in operating system, but access to the previous
OS is provided by the RPL switcher.


1.2 Features
------------

- Real multitasking
- Friendly user interface
- Files management and memory usage improved
- Display using 4*6 Font
- Double buffered display
- Fast bank-switching (particularly useful for large RAM Cards users)
- Screen splitting
- Clipboard handling for copy/paste between applications
- Fully customizable
- Around 1 hundred routines available and documented for ASM programmers
- Handling of routines libraries (like DLL)
- Slot 1 soft protection
- All this, and more, for just about 32Kb...


2. Infos
========

2.1 Version
-----------

Note : This version is still a beta, which implies that there might remain
few bugs that will, of course, be fixed for the final version.

Check out the SHELL OS official website for new versions and updates.

http:\\www.mygale.org/11/shellos


2.2 Copyright
-------------

All files of the SHELL package are Copyright (c) 1997,98 by Stephane 
Cocquereaumont and Philippe Dedieu unless otherwise noted.

The SHELL Package is distributed in the public domain in the hope that it
will be useful, but is provided `as is' and is subject to change without
notice. No warranty of any kind is made with regard to the software or
documentation.  The authors shall not be liable for for any error for
incidental or consequential damages in connection with the software and the 
documentation.

Permission to copy the whole, unmodified SHELL package is granted provided
that the copies are not made or distributed for resale (excepting nominal
copying fees).


2.3 Authors
-----------

For any comments, suggestions or bug report, you can post a message to
comp.sys.hp48, or reach the authors at :

<SHELL3@CARAMAIL.COM>

or 

<SHELL3@RTEL.fr>


2.4 Contribution
----------------

To contribute to the SHELL project, you can add a link on your Homepage
(if you have one) or simply send a e-mail to encourage us...


3. Installation
===============

- Make sure that a writeable 32Kb or 128Kb RAM card is present in port 1

- Load the file SHELL.DIR

- Check that the CRC of the directory is : #338Eh

- Go into the directory

- Launch Install

The data present in port 1 will be lost, but all the data in port 0 and 
VAR will be saved.

To go back to the RPL OS, go into the RPL directory and launch RPLswitcher.


4. General usage informations
=============================

4.1 Keyboard
------------

System keys :

        - [ON]-[C] : System REBOOT
	- [ON]-[+] : Increase contrast 
	- [ON]-[-] : Decrease contrast
	- [ON]-[Up]/[Down] : Move the splitted screen
        - [ON]-[NXT] : Switches to the next application in memory
        - [ON]-[Right] : Swap between the current and previous application
        - [ON]-[<=] : Kill current application and all its data
        - [ON]-[0]..[9] : Switches to the corresponding application, in the 
                          same order as in memory


Note : if you press the [<=] key during startup, SHELL.ini and Startup file
will be ignored.

Standard application keys :

        - [ENTER] : Main menu
        - [ON] [ON] (double ON) : Cancel
        - [RS] [ON] : Off
        - [+/-] : Toggle selection mode
        - [STO] : (Copy), Store current selection in clipboard 
        - [RS] [STO] : (Paste), Paste clipboard in application 


4.2 System Console
------------------

It is designed to launch programs, as well as to modify the system variables.

Note that the only program always loaded in memory is the system console
because it is loaded by the kernel on startup and it can't be killed.

The current directory is displayed in the header.

The syntax used is similar to the DOS/UNIX command line.

The command names are in lower case.

List of the commands currently available : 

	- Clear screen : cls
	- List of files in current directory : ls, dir
	- Change directory : cd filename
	- Load without running application : load filename
	- Amount of available memory : mem
	- List of applications in memory : ps
	- Go to the parent directory : updir, cd..
	- Current OS version : ver	


When entering the name of a file, this file is evaluated by the console in 
this way :

	Launch application (PRG)
	Enter directory	(DIR)
	Run batch file (TXT)
	Load library (LIB)
	Load driver (DRV)
	Load font (FNT)	

It is possible to modify the value of systems variable by typing the variable 
name, the equate character '=' and the variable value as follows : 
variable = value

List of variables :     Beep (yes, no)
                        ShowClock (yes, no)
                        CursorStyle (0, 1)
                        AutoPowerOff (yes, no)
                        Delay (0..255)
                        Prompt (0..255)
                        Contrast (0..30)

For example, to change cursor style, enter : CursorStyle=1


4.3 The clipboard
-----------------

The clipboard is designed to easily tranfer any type of data between 
applications, the standard keys to use it are [STO] to copy to clipboard
and [RS] [STO] to copy from clipboard.


4.5 The power manager
---------------------

The power manager shut down the HP48 if no key is pressed during a certain 
time depending of the value of the system variable (Delay).

It can be desactivated by setting AutoPowerOff=no in the SHELL.ini file.


4.6 The clock manager
---------------------

The clock is usually displayed in the top right corner of the screen.

The clock display can be desactivated by setting ShowClock=no.


5. The file manager : Filer
===========================

Filer is a very fast and powerful file manager, it is designed to replace
the console in most case.

By default the file manager is launched on startup (see the Startup section). 


Display :
---------

        - The header display the current path
        - "Unit" field display the current unit
        - "Free" field display the space available in the current unit, this 
          value is video inverted if unit is write protected
        - "Tagged" field is the sum of sizes of tagged objects (not usable 
          in this version)

Keys :
------

        [Up]            : Move up the selection bar
        [Down]          : Move down the selection bar
	[Left]		: Go to parent directory
        [Right]  	: Swap between directory and tree view
	[RS]+[Up]	: Go to the top of the list
	[RS]+[Down]	: Go to the end of the list
        [NXT]           : Change current unit to the next unit
        [0]..[9]        : Set current unit
        [EVAL]          : Evaluate file/enter directory 
        [DEL]           : Delete file
        [STO]           : Store the current file in the clipboard
        [RS] [STO]      : Copy the clipboard in the current directory
        [ENTER]         : Menu


Menu :
------

        File	
                Run             Evaluate the current file
                Purge           Purge current file
                Make Dir        Make a new directory in the current directory
                Rename          Rename current file
		Format unit	Format current unit (clear)
                Exit            Exit Filer
        Edit
                Copy            Copy current file into clipboard
                Cut             Copy and purge current file
                Paste           Copy clipboard into current directory
        ?
		Infos		Infos on current file and mem available
                About           Copyright infos


Filer.ini :
-----------

The File.ini file is read each time the filer is launched.

MKLikeKeys (default=no) : Used to set the MKLikeKeys mode, when it's on, the
right key is used to enter directory.

Confirm (default=yes) : If on, a yes/no input box is displayed when you press
the [DEL] key to delete a file or a directory.

SelChar (default=#2A) : ASCII code for the selection character, used for 
multiple selection.

 
6. The text editor : TeD
========================

The text editor is designed to create, view or modify text documents.

Features :
----------

	- Picture insertion
	- Tabulator support
	- Handling of underlined, inverted, italic attributes 
	- Ascii table
	- Topic list
	

Display :
---------

        - The header display the name of the edited file

Keys :
------

        [Arrows]        : Move cursor
	[Alpha]		: Toggle Alpha mode
	[LS]+key	: Invert case for one key
	[LS]+[Alpha]	: Invert case
	[RS]+key	: Specials characters (dependent of character set)
        [DEL]           : Delete characters by the right
	[<=]		: Delete characters by the left
	[RS]+[Up]	: Go to the top of the text
	[RS]+[Down]	: Go to the end of the text
	[RS]+[Left]	: Go to the begining of the line
	[RS]+[Right]	: Go to the end of the line
	[RS]+[DEL]	: Delete all characters by the right
	[RS]+[Up]	: Delete all characters by the left
	[+/-]		: Toggle selection mode
        [STO]           : Store the current file in the clipboard
        [RS] [STO]      : Copy the clipboard in the current directory as "Clip"
        [ENTER]         : Menu	  


Menu : 
------

        File	
                New		Create a new text file	
                Open		Open a file
                Save&Quit	Save current file and exit TeD
                Exit            Exit TeD without saving file
        Edit
		Cut		Copy to clipboard and delete selection
                Copy            Copy selection clipboard
                Paste           Paste clipboard to cursor position
		Delete		Delete selection
	Style
		Invert		Insert a invert attribute 
		Underlined	Insert a underlined attribute
		Italic		Insert a italic attribute

	Tools	
		Find		Find a string
		Topic List	List of "Topics" (lines begining with "*")
		Ascii Table	Ascii chooser

        ?
               	Help		Display help box
		About           Copyright infos


How to :
--------

* How to insert graphic into text :

TeD permit to insert graphics simply by using the clipboard :

	- Run EasyPaint
	- Open or create the picture
	- Copy the area wanted into clipboard
	- Swap to TeD
	- Paste the picture at the position of the cursor...


* How to merge texts :

TeD permit to merge texts files by using the clipboard and the Filer

	- Open the first file with TeD
	- Run the Filer
	- Copy the second file into clipboard
	- Swap to TeD
	- Paste the clipboard at the end of the file...


* How to extract a portion of text :

	- Open the file containing the portion of text with TeD
	- Select the portion of text
	- Copy it into clipboard
	- Run the Filer
	- Select the unit/directory 
	- Paste the portion of text
	- Rename the Clip file to the name wanted...


7. The graphic editor : EasyPaint
=================================

EasyPaint is a mini graphic editor, the current version is very limited.


Display :
---------

	The current version display only 131*64 N&B pictures

Keys :
------

        [Arrows]        : Move cursor
        [RS]+[Arrows]	: Move cursorto extremes positions
	[B]		: Draw a box
        [C]		: Draw a circle (centered on the cursor)
	[+]/[-]		: Increase/decrease the size of the circle 
			  or PixOn/PixOff
	[L]             : Draw a line
	[F]		: Fill area
	[+/-]		: Toggle selection mode 
        [STO]           : Store the current selection in the clipboard
        [RS] [STO]      : Paste the clipboard
        [ENTER]         : Menu	  


Menu : 
------

        File	
                Open		Open a picture
                Save            Save current file
                Exit            Exit EasyPaint
        Edit
	        Copy		Store the current selection in the clipboard
        	Paste		Paste the clipboard
		Insert		Insert a picture
		Insert Text	Insert a string
	Tools	
		Line		Draw a line
		Circle		Draw a circle
		Box		Draw a box
		Fill		Fill a area
		Erase		Erase picture
        ?
         	Help		Display help box
		About           Copyright infos


8. RPL compatibility
====================

The RPL switcher is a program which permit to go back to the built-in OS
(RPL OS).

Under RPL, a program called STARTSHELL is used to return to SHELL OS.

On startup a file called RPLcomp is launched, it "patch" the kernel to 
redirect it when access to RPL ports is done.


9. Xmodem
=========

In this version you can't modify the baud rate or do transfert with
the IR port, in the next version the program will detect the port and the
baud rate automatically.


Xsend :

Select the file to send, and press [ENTER], when the transfer is finished,
a beep occur and the program exit.


Xrecv :

If the file is recognized as a SHELL file, you have not to enter the name
of the file (unlike Xmodem standard implementation), if the file is not a 
valid SHELL file, it is stored as BIN with the name "?".


10. SHELL customisations
========================


10.1 SHELL.ini
--------------

The file SHELL.ini contains the default values of the various system 
variables listed above. The file is read at each new startup.


10.2 Startup
------------

The file named Startup contains a list of commands to be executed at each 
new startup. (see system console)

All the commands preceded by a "*" are ignored.

All the commands preceded by a "@" are no written on the console screen.


10.3 Batch files
----------------

Batch file are simply text files with list of commands (see system console),
if they are evaluated, all the commands will be processed by the command
interpreter and transmitted to the kernel.

You can create your own batch files, but actually the command interpreter
is not finished (remember : this is a beta), and there are very few commands
available.


10.4 Splash Screen
------------------

On startup, the picture file Splash is displayed, by default it contains
copyright infos on SHELL OS.

This file can be replaced to display custom picture.

Or, if you need memory, you can delete it ! 


10.5 Changing the font
----------------------

To replace the default font by an other, simply evaluate the file containing
the font.

A directory containing fonts is availaible on the SHELL Official Website.


11. Programming
===============

Programming under SHELL OS will be possible for everyone when the developer
pack will be release (soon).


                                                                                                                                                                                          