@database ShellScr.guide
@author Kyzer/CSG
@$VER: ShellScr.guide 1.2 (04.08.97)
@remark you can read this in a text viewer, if you need to.
@node main "ShellScr v1.2 documentation"

@{u}ShellScr v1.2@{uu}

 @{"  " link intro} Introduction
 @{"  " link usage} Usage
 @{"  " link history} Program history
 @{"  " link future} Future development
 @{"  " link credits} Credits

@{"Read me ViNCEd users!" link VNC}

*** begin anti-american text

COPYRIGHT: THE AUTHOR HOLDS ALL COPYRIGHTS ON THIS SOFTWARE AND ITS
ACCOMPANYING DOCUMENTATION AND SOURCE. THE AUTHOR SPECIFIES THAT ALL
USERS ARE ALLOWED TO REDISTRIBUTE THE PROGRAM PROVIDED THAT THEY DO NOT
CHARGE ANYTHING BEYOND REDISTRIBUTION FEES, AND ALSO THAT THEY DISTRIBUTE
THE SOFTWARE IN IT'S ENTIRETY, WHICH IS THE UNMODIFIED FILES SHELLSCR,
SHELLSCR.INFO, SHELLSCR.GUIDE AND SHELLSCR.E

SHELLSCR MAY BE USED IN COMMERCIAL PACKAGES PROVIDED THE AUTHOR IS
CREDITED AND ALL FILES ARE INCLUDED UNMODIFIED. ANY PART OF THE SOURCE
CODE MAY BE USED FOR ANY PURPOSE.

DISCLAIMER: SHELLSCR IS 100% SYSTEM GUIDE COMPLIANT. ANY COMPUTER FAILURE
CAUSING OR NOT CAUSING LOSS OF DATA OR OTHERWISE RELATING TO OR NOT
RELATING TO THE USAGE OF SHELLSCR IS THE FAULT OF BAD USER CONFIGURATION OF
SHELLSCR AND OTHER THIRD-PARTY SOFTWARE. SHELLSCR IS NOT PROVIDED WITH ANY
WARRANTY DUE TO THE FACT IT IS GIVEN TO THE USER FREE OF CHARGE.

*** end anti-american text

@endnode
@node intro "Introduction"
ShellScr is a tool I have been using for years.
Finally, I have decided to release it to the public.

ShellScr simply opens a new PUBLIC screen and puts a full screen-sized shell
on it, allowing fun things like 80 column shells in topaz8/hires.

Unlike, say, ViNCEd's screen option, it creates a _public_ screen!

ShellScr opens a public screen and puts a console window on it, using the
NewShell command.

After all the windows on the public screen close, the screen closes.

Sweet and simple, and programmed in Amiga E for stability.
@endnode

@node usage "Usage"
ShellScr requires Workbench 2 or better. What doesn't nowadays?

Simply double-click on ShellScr's icon, or type "ShellScr" at a shell.
You will then get a shell on it's own screen. The screen is a clone of
the default public screen (usually the Workbench screen), but this can be
changed with @{"shell arguments" link args}.

If you shift-select a file or directory from the Workbench, then run
ShellScr, you will start the shell in that directory.

You can launch as many copies of ShellScr as you want.

The shell can be closed at any time, by pressing CTRL-\\ or typing
'EndShell' at the shell prompt. However, the screen will only close when
all the windows on it are closed. Usually the shell is the only window,
so the screen goes away when the shell does.

There are @{"shell arguments" link args} to customise ShellScr, but no tooltypes. Sorry.

I suggest running ShellScr from the shell for the moment, as you cannot
define tooltypes for ShellScr.
If you have a program like ToolsDaemon or ToolManager, then
USE IT!
@endnode

@node args "ShellScr's shell arguments"
PUBNAME=NAME,MODEID=ID/N,DEPTH/N,SCREENTITLE=TITLE,CONSPEC=WINDOW,HIDETITLE=NOTITLE

PUBNAME:  This is the name you wish to give to the public screen, so you
          can access it from other programs, etc. The default is SHELL_blah
          where blah is a *unique* ID code for that particular shell.

MODEID/N: This is the ModeID for the screenmode you want the screen to be.
          It is a DECIMAL number, I suggest using the program @{"GetModeID" link getmodeid}
          I have included to find the right number you need. The screen's
          width and height will be the default for that ModeID. If you do
          not specify a ModeID, the default is to use the same screenmode
          as the default public screen (usually Workbench)

DEPTH/N:  This is a decimal number of how many bitplanes you want for the
          screen, between 1 and 8. The more bitplanes, the more memory the
          screen takes up. The default is 2 planes, 4 colours.

TITLE:    This is the title of the screen. You should use this as you will
          not be able to see the window's title. Default is 'AmigaShell'.

CONSPEC:  This is the specification of the console window to open on the
          public screen. It should contain two "%s" signs which will be
          replaced by ShellScr for certain values. The first "%s" will be
          changed to the coordinates and size of the window, in the format
          "l/t/w/h", eg "0/11/640/253" on a 640x256 screen. The second "%s"
          will be changed into the name of the public screen we are using.
          The window should be a backdrop borderless gadgetless window with
          no title. For example, the default is "CON:%s//BACKDROP/NOBORDER/
          SCREEN%s", I use ViNCEd with "VNC:%s//SCREEN%s/NOCLOSE/BACKDROP/
          NOBORDER/NOBUTTONS/SHELL".
          The longest CONSPEC allowed is 256 characters, any longer than
          this and it will be truncated.

NOTITLE:  This specifies that the screen should have no titlebar whatsoever,
          so you get the entire screen. @{"Window-size calculation" link sizing} takes this
          into account. Note that the normal CON: window looks ugly with
          this option! It is best reserved for a handler like VNC: that
          really will use the full screen.
@endnode

@node sizing "Window-size calculation"
The window size calculation is as follows:

First, the width of the window is always the entire width of the screen.

Now, if you are happy with the default CON: window, and do not specify an
alternative CONSPEC, then the vertical height of the window will be
height_of_the_screen - 3, due to the fact that CON: looks best with this
setting, its unusable titlebar is covered by the screen titlebar.

If you use a custom CONSPEC, ShellScr makes no such assumptions and uses
height_of_the_screen - height_of_the_titlebar as the vertical size, if you
use the new NOTITLE option then there is no titlebar and you get the whole
screen for the shell.
@endnode

@node GetModeID
To use this program, you need v38 or better of asl.library
Run it from the shell, and a ScreenMode requester will appear on the
Workbench screen. Select the mode you want and then click on 'OK'.
The requester will close and the MODEID value will be printed at the shell.
@endnode

@node VNC
ShellScr complements ViNCEd very well, and VNC *still* can't open its own
public screen... :)

This is the CONSPEC that I use myself (long!):

VNC:%s//SCREEN%s/SHELL/BACKDROP/NOBORDER/NOCLOSE/NOSIZE/NODRAG/NODEPTH/MENU/NOPROPX/NOPROPY/NOBUTTONS/NOICONIFY
@endnode

@node future "Future developments"
In the future, I may or may not add these options.

- Tooltypes parsing

- A Magic Workbench styled icon.

- Any other options the public (you!) wants me to add.
@endnode

@node history "Program History"
1.0:	First release

1.1:	Added options PUBNAME, MODEID, DEPTH, TITLE and CONSPEC
	Use System() instead of Execute()
	Tidied up source a bit

1.2:	Made a few more checks on stuff
	Added NOTITLE option
	Better windowsize calculation
	Now sets currentdir and paths properly from Workbench.
@endnode

@node credits "Credits"
ShellScr was concieved from the assembler program 'scrsh' by Kyzer/CSG.

ShellScr was written by Kyzer/CSG in Amiga E 3.1i, based on the source
scrsh.asm by Kyzer/CSG, the RKM source clonescreen.c, and the source to
dospath.library by Stefan Becker.

Contact:

Kyzer/CSG,
49 Fairview Road,
AB22 8ZG, Scotland.

or email: kyzer@4u.net

Incitement Works plc, http://www.abdn.ac.uk/~u13sac/
@endnode