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

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

 @{"  " link intro} Introduction
 @{"  " link usage} General usage
 @{"  " link options} ShellScr options
 @{"  " link history} ShellScr history
 @{"  " link credits} Credits

ShellScr is a program to open a full-sized shell on it's own public screen.
Copyright (C) 1997  Kyzer/CSG

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

@{"Contacting the author" link credits}
@endnode

@node intro "Introduction"
Instead  of using the shell in a window and risk clutter on your Workbench,
why not let a shell have it's own screen?

ShellScr is a tool which  opens a new PUBLIC screen  and opens a fullscreen
sized shell on it.

After  all  the  windows  on  the  public screen close, including the shell
itself, the screen closes.

@{"How to use ShellScr." link usage}
@endnode

@node usage "Using ShellScr"
ShellScr requires Workbench 2 or better to run.

The included "GetModeID" program requires asl.library from Workbench 2.1
or better to run, it also works if you have ReqTools and ReqPatch installed.

To  start  ShellScr,  simply  double-click  on  ShellScr's  icon,  or  type
"ShellScr"  at  an  already  opened shell. You will then get a new 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 @{"options" link options}.

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

If  you  shift-select  a  file  or  directory  from the Workbench, then run
ShellScr,  you  will start the shell in that directory. This will also work
if  you  select  a  file or directory, and start ShellScr on this directory
with a "ToolsDaemon" or "ToolManager"-like 'dock' program.

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.

@{"ShellScr options" link options}
@endnode

@node options "ShellScr options"
You may change how ShellScr operates using the following options.

You  may  set  them from the shell, from tooltypes of the ShellScr program,
from  the  tooltypes  of  an  icon whose default tool is ShellScr, from the
tooltypes  of  an  icon  or  drawer  that  is  multi-selected when starting
ShellScr, or from the tooltypes of an icon which is selected while starting
ShellScr  as  a  WB  command of ToolsDaemon or ToolManager, or another such
'dock' program.

@{"  " link PUBNAME} PUBNAME
@{"  " link MODEID} MODEID
@{"  " link DEPTH} DEPTH
@{"  " link TITLE} TITLE
@{"  " link CONSPEC} CONSPEC
@{"  " link NOTITLE} NOTITLE
@endnode

@node PUBNAME "PUBNAME option"
WB:	PUBNAME
Shell:	PUBNAME=NAME

This is the public name that ShellScr will give to the screen it creates.

The  standard public name is SHELL_XXXX, where XXXX is a unique ID code for
that particular shell.

You are advised _not_ to use this option unless necessary, as when you open
one  shell with a name, you cannot open another shell with that name at the
same  time. Please take a look at the program MultiCX, which has options to
create  a  'magic' public screen name for the frontmost screen, whatever it
may be.

If  you want to set the text on the screen's titlebar, please use the @{"TITLE" link TITLE}
option.
@endnode

@node MODEID "MODEID option"
WB:	MODEID
Shell:	MODEID=ID/N

This  is  the  ModeID  for  the  screenmode  you  want the screen to be. It
specifies what monitor and resolution ShellScr's screen should use.

ModeID  has  to  be a decimal number, you should use the included GetModeID
program  to  find  the  number  you  need.  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 required
MODEID value will be printed at the shell.

@{"Try out ShellScr with GetModeID" system "ShellScr MODEID=`GetModeID`"}

If  you  do not specify a ModeID, the default is to use the same screenmode
as the default public screen (usually Workbench).

Also see the @{"DEPTH" link DEPTH} option, for setting the number of colours on the screen.
@endnode


@node DEPTH "DEPTH option"
WB:	DEPTH
Shell:	DEPTH/N

This  is  a  decimal  number of how many bitplanes you want for the screen,
between  1  and  4,  or between 1 and 8 on machines with the AGA chipset or
similar  enhanced  graphics  card.  The more bitplanes, the more memory the
screen takes up. The default is 2 planes, 4 colours.

Graphics  card  owners: Note that although you can specify the shell to use
one  of  the graphics-card's screenmodes with the @{"MODEID" link MODEID} option, you cannot
get a 'highcolour' or 'truecolour' shell. I hope you don't mind!
@endnode

@node TITLE "TITLE option"
WB:	TITLE
Shell:	SCREENTITLE=TITLE

This is the text that will go in the titlebar of the screen. This option is
here, as the shell you open will not have a titlebar of it's own.

The default text in the titlebar is 'AmigaShell'.

To remove the titlebar altogether, see the @{"NOTITLE" link NOTITLE} option.
@endnode


@node CONSPEC "CONSPEC option"
WB:	CONSPEC
Shell:	CONSPEC=WINDOW

This  is  by  far the most technical setting of ShellScr. You don't have to
use this option if you don't want to!

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". If you use the ViNCEd package, a good setting is the following:

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

You may want to read the information about @{"window-size calculation" link sizing}.
@endnode


@node NOTITLE "NOTITLE option"
WB:	NOTITLE
Shell:	NOTITLE=HIDETITLE/S

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 for ShellScr 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 history "ShellScr history"
1.0:	First release

1.1:	Added options @{"PUBNAME" link PUBNAME}, @{"MODEID" link MODEID}, @{"DEPTH" link DEPTH}, @{"TITLE" link TITLE} and @{"CONSPEC" link CONSPEC}.
	Use System() instead of Execute().
	Tidied up source a bit.

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

1.3:	Now parses icon tooltypes.
	Now uses default screen's colours
	Tidied up documentation.

@{" Future development " link future}
@endnode

@node future "Future prospects for ShellScr"
ShellScr is almost complete.
The only other things I thought it could do with are:

Font option.
Internal font/screenmode requesters.
'Alternative shell' option (????)

Any further suggestions from you are _also_ welcome. @{"Send them to me." link credits}
@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.3a, based on the source
scrsh.asm  by  Kyzer/CSG,  the  RKM source clonescreen.c, and the source to
dospath.library by Stefan Becker.

Best wishes to the following people:
Frank Bunton, who asked for the colours options.
Thomas Richter, for 'fixing' WBLoad, and for ViNCEd!
Wouter van Oortmerssen, for the E language.

Contact:

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

or email: kyzer@4u.net

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