Dream 44/Amiga_Dream_44.iso/RiscPc/Utils/CLIGuard2.arc/!CLIGuard/!Help

Text File | 1995-01-02 | 19KB | 355 lines

CLI Guardian version 1.10
⌐ Sam Kington 27th December 1994
This program is freeware, *not* public domain ù i.e., I retain copyright (see
öBoring legal messageò)

Existing users: see the ₧le öChangesò for a list of changes since version
1.00. Thereæs quite a lot; I hope you like it ;).

Terminology note
****************

   What the hell is the CLI, you may ask? And what do I mean by öCLIò?
      Å öCLIò stands for Command Line Interface.
      Å The CLI, under RISC OS, is the prompt you get for typing in ö*
        commandsò like *Modules, *Help Commands, *Set File$Type_FFF etc.
   You can get to the CLI in two ways:
      Å By öshelling outò to the CLI ù i.e. pressing F12.
      Å By using a task window ù i.e. pressing Ctrl-F12
   But I will mostly describe the öCLIò as the F12 version ù or rather,
whenever there are pejorative connotations, itæs the non-multi-tasking
version ;).
   I will occasionally describe *commands as Écommandsæ ù I mean the same
thing.

What this program does
**********************

   CLI Guardian, as its name suggests, provides a way of avoiding shelling
out to the CLI, by making three important aspects of RISC OS
desktop-friendly: module handling, help handling, and *commands. It provides
a list of modules, that you can look at and sort in different ways, as well
as doing various things to (killing them, re-initialising them, loading them
into RAM etc.) ù hopefully, anything you would do with modules that you had
to use the CLI before, you can do with CLI Guardian. It also allows you to
view help strings, either from *Help or from BASIC, in a window, and to move,
in a pseudo-hypertext fashion, between references (for *Help only, NB). (If
youære not sure what I mean by this, see later on in this ₧le). Finally, you
can enter *commands, and either run them in a Task Window or view the output
in one of CLI Guardianæs viewers, and you can have other tasks like Director
ask CLI Guardian to run a command as well.

   When you run CLI Guardian, it puts an icon on the icon bar, and starts
building its list of modules. The machine will multitask, but will run a bit
slower, until it ₧nishes doing all this. This is only really noticeable if
youære typing away or dragging things or that sort of thing; certainly, in a
boot sequence you wonæt notice it.

   The program supports interactive help, so this documentation will only
cover the various aspects of the program that donæt ₧t in a small Help
message.

Modules
*******

   Clicking on CLI Guardianæs icon will open a list of modules to the left of
the screen. By default it will be a simple list of modules, in the standard
system order (i.e. ROM modules ₧rst, then RAM modules in the order they were
loaded), called in this program ösort by numberò. Clicking on any of the
modules will bring up a window with the various help options provided by the
module; clicking on those will bring up the appropriate help message (see
below). The window will also include any SWIs the module provides, but this
is purely for information ù it is exceedingly unlikely that there will be any
help available on them.
   Unavailable modules (i.e. unplugged or dormant ROM modules) will be
displayed in grey or in italics, depending on whether you are using the
system font or not (see öChoicesò).

   Clicking MENU on the Modules window will bring up the main menu, where you
can set the display options, perform the standard operations on modules, save
the module to disc, change the choices (colours, fonts, mouse clicks, mouse
drags), save a copy of the window to disc and rescan the modules if they get
out of synch.

   CLI Guardian knows several things about any particular module: its
öofficialò name (e.g. öColourTransò), its öfriendlyò name (e.g. öColour
Selectorò), its version number (e.g. 1.07 (15 Apr 1992), its status (e.g.
öROM (active)ò), its size, and possibly a öspecialò ₧eld (usually a copyright
notice). You can see these in the Info box off the öModuleò submenu, or by
using interactive help on the Modules window.

   You can choose to display them in various combinations in the module
window, by using the öDisplayò submenu, so you could have a sparse display of
just official module names, or a big massive display with friendly name,
size, status, version number and special ₧eld. The only limitation is that
they must be in the order öname - size - status - version - specialò, and
that you canæt have both sorts of names at the same time ù mainly because
theyære often not very different at all. I donæt think this is too much of a
problem, but if you *are* seriously miffed by this, please tell me.

   Please note that the size of a module is just the size the code takes in
the module area; it may also have workspace in the module area, the system
area, the sprite area or elsewhere, which may often be quite extensive (the
Window Manager usually uses 100K of workspace, and tracker modules also use
massive amounts).

   You can also sort the modules in various ways: sort by name (alphabetical
sort, using the official name), sort by number (standard sort, ROM modules
₧rst then RAM modules in the order they were loaded), sort by date, sort
by size and sort by version number.

   CLI Guardian will ₧nd a list of modules quite quickly, but ₧nding out the
friendly name, version etc. and sorting the modules takes longer, which is
why it will do this in the background. This lets you get at the machine
quicker, but it has the side-effect that, if you are quick enough, you will
see that some of the options are temporarily unavailable (greyed out). Also,
if you have chosen to sort the modules by version (for instance), they will
be displayed sorted by number for quite a while, until CLI Guardian ₧nishes
sorting them by version number. This happens when you ₧rst start CLI
Guardian, or when you rescan the modules. For this reason, you are
recommended to put CLI Guardian in your Boot sequence, near the end, so it
can work away when you ₧rst start up your machine and be ready when you want
to use it. The speed loss, when the machine is grinding away loading things
anyway, is not particularly noticeable.

   (Note: rescanning will also delete any current windows and give away any
claimed memory. So, if CLI Guardian grabs all the available memory ù this can
happen sometimes with strange modules ù choose örescanò.)

Help
****

   As mentioned above, clicking SELECT (by default) on the Modules window
will ₧nd all the help options supplied by the module ù help on commands,
con₧guration options, or other miscellaneous help ù and display them in a
window. Clicking on any of these options will in turn bring up a window with
the corresponding help text; clicking in that will try and ₧nd help using the
words in the line of text clicked on, and so on ad in₧nitum (or rather, until
you reach the limit of 16 windows). As mentioned previously, you are unlikely
to ₧nd any help on SWIs.

   What is actually happening, is that when you click on a line of text, CLI
Guardian passes the line to *Help, and displays the result ù even if the
actual line wasnæt *intended* to be clicked on like that. For instance, if
you click on öUtilityModuleò (or öMOS Utilitiesò if you have chosen öShow
friendly nameò), a rather large window will appear with a list of keywords,
divided into two sections, öCommandsò and öHelp onlyò. This is nothing more
than a nicer form of what you would get if you typed *Help UtilityModule from
the command line (although sometimes there may be slight differences ù CLI
Guardian is sometimes more robust with badly-written modules). However, if
you clicked on öCon₧gureò, another window would appear, with the heading
öHelp on keyword Con₧gureò and a list of Con₧gure keywords provided by
modules. If you go down to the keywords provided by öTerritory Mgrò, which
should be something like öTerritory   DST   NODST  TimeZoneò, and click on
that line, you will get a further window with four sections, öHelp on keyword
Territoryò, öHelp on keyword DSTò, etc., with the appropriate help text.

   If you click on a heading, CLI Guardian will get help on all the lines
between the heading and the next heading (or the end of the page if there
isnæt one). This works quite well for the ₧rst window you get, where the
*Commands are lined up neatly under the heading öCommandsò, but is rather
more messy in other, unformatted windows. In particular, if the word
öCommandsò features anywhere between the heading and the next one, then you
will get the output of *Help Commands ù which is quite long :(.

   To sum up: What you have here is a (rudimentary) form of hypertext. The
best way to ₧nd out what you can do with it is to experiment.

   Clicking MENU on any window other than the Modules window will bring up a
smaller window, with three options, öHelpò, öCommandò and öSaveò. The ₧rst
two are equivalent to clicking Select or Adjust on the window; the third
brings up a Save box where you can save the contents of the windows to a ₧le
or an application.

   Choosing öHelp...ò from the icon bar menu will bring up a small dialogue
box where you can enter Help keywords; clicking öOKò will bring up a Help
window in the usual manner. Note that you can also get help on BASIC keywords
with this window (but *not* by clicking in a viewer window), by selecting
öBASICò rather than öRISC OSò. By default, Shift-Select-clicking on the icon
bar icon will bring up the default Help window (i.e. with öRISC OSò
selected), and Shift-Adjust will bring up the Help window with öBASICò
selected. This is purely for convenience, of course: you can still change
mode by clicking on the icons as usual.

Commands
********

   Adjust-clicking (by default) on a viewer window (that is, any window other
than the Modules window) or the icon bar will bring up a dialogue box where
you can enter a *ácommand. The window has three main parts: the öCommandò
writable ₧eld, where you would enter the name of the actual command, four
writable ₧elds in the öArgumentsò section, where you can enter various
arguments of the command, and a set of icons.

   Note that CLI Guardian separates the öcommandò and öargumentò parts of the
*command string purely for clarity: for all intents and purposes, the command
string still behaves as one long string, rather than up to ₧ve different bits
of one. Itæs difficult to describe here, so I wonæt; itæs easiest to try it
out and see for yourself. Note however that CLI Guardian assumes arguments
are separated by spaces; this should be OK apart from a few old commands that
still accept commas, but falls down when you include spaces within an
argument. If this annoys you, sorry.

   Pressing F1 will toggle between the current command and the previous
command ù which is useful if you want to do the same command again, or a very
similar one, and donæt want to re-type it. If that isnæt enough (it usually
isnæt), then pressing F2 will show a command history in a CLI Guardian
viewer. Or rather, it will if you have Olly Bettsæ Line Editor running (and
if you donæt, you should). Alternatively, you can *Type a file which contains
your favourite commands, and use that as a history (there's a file called
öHistoryò in the CLI Guardian directory, which will be viewed if LineEditor
isnæt running).

   CLI Guardian will also accept commands from other tasks: running the
command CLIGuardCommand <command text> will do the job. Thereæs an example
Menu file for Director in the CLI Guardian directory to show you how it
works.

   If you drag a ₧le to the Commands window, the full ₧le-name will be
inserted at the end of the command (i.e. in the last argument ₧eld).
Additionally, the öHelpò button will provide help on the command (if there
isnæt any help, you might not have typed it correctly); if the command is
öSetò, öSetEvalò, öSetMacroò or öCon₧gureò, the öValueò button will show you
the current value of the variable or the con₧gure option you are about to
change. öOKò and öCancelò perform the expected actions: öCancelò stops the
whole thing, and öOKò runs the command, with the output going in a standard
CLI Guardian window. The only exception is for ödangerousò commands: things
like *Basic or *Debug that take over the machine, or things like *Map that
take a long time ù in other words commands that donæt return almost
instantaneously or depend on updating the screen regularly. These will either
be run as a separate task, or run in a Task Window.

   Finally, if you Adjust-click on a con₧guration option in one of CLI
Guardianæs viewers, CLI Guardian will insert the command öCon₧gure <option>ò,
where <option> should be replaced by the name of the option, so öCon₧gureò
would be in the command field and ö<option>ò in the ₧rst of the argument
₧elds.

   Choosing öCommand...ò from the icon bar menu will also bring up the
window.

Choices
*******

   There are various ways you can customise CLI Guardian, notably by choosing
how it displays modules (see öModulesò for more details). Other choices can
be set with the öChoicesò submenu: colours, fonts, mouse actions and mouse
drags.

   CLI Guardian uses three styles in its windows: normal style, heading style
and unavailable style. The normal style is applied to most text, the heading
style to things like öCommandsò or öHelp on keyword Con₧gureò, the
unavailable style to modules like öBBC Econetò or öJoystickò if you donæt
have the appropriate hardware. How these styles behave depends on whether you
are using outline fonts or not. If you are using the system font, CLI
Guardian uses colours to distinguish between styles (by default, red for
headings and grey for unavailable modules). If you are using outline fonts,
CLI Guardian wonæt use colours; partly because non-anti-aliased fonts look
ugly, and mainly because itæs a pain to do properly.

   The default fonts are Trinity.Medium for normal text,
Trinity.Medium.Italic for unavailable text, and Homerton.Bold for headings.
You canæt change the size because a) it would look silly, and b) itæs much
easier to assume a font is a certain size. 12 point is about the same size as
the System font, and as the point size of a font is a measure of its height
(more or less), the lines should be spaced out correctly (well, they are on
my machine, will all the fonts Iæve tried). You might get lines spilling over
the edge of the window, but I suspect that would be with strange fonts like
öFancyDressò. Obviously, Dingbats, MathGreek or other symbol fonts will look
rather silly...

   You can also change the action of various mouse clicks, assigning mouse
clicks to mouse actions, by choosing öMouse clicks...ò from the öChoicesò
submenu; a window will appear, with the available commands and the
corresponding mouse click. For instance, if you click on the icon bar icon,
you can open the Modules window, enter a Help keyword, or enter a * command;
clicking on a window can search for help on the chosen line, use that line as
a command, bring up a save box or close the window. Obviously, with several
commands available and only two mouse buttons, you have to use Shift, Ctrl or
maybe even Alt if you want to be able to do all these things with the mouse,
so you can choose which ones are the most important to you.

   You can save these choices, cancel changes, and revert to default settings
with the menu.

   Finally, you can also tell CLI Guardian to run certain commands when ₧les
of a given type are dragged to the icon. You can do this by editing the
öFileDragsò ₧le within the CLI Guardian window (there are menu options to do
this), which contains lines like the following:
      SetMacro CLIGuard$RunType_FF9 IconSprites <CLIGuard$File>
      SetMacro CLIGuard$RunType_1000 Filer_OpenDir <CLIGuard$File>
   To set the options, CLI Guardian runs the ₧le as an Obey ₧le, setting the
special variables, similar to Alias$@RunType_xxx variables.
   The variable öCLIGuard$Fileò contains the full name of the ₧le dragged to
the icon; öFF9ò or ö1000ò are the numerical values of the appropriate ₧letype
(1000 for a directory, 2000 for an application). Choosing öEdit drag ₧lesò
from the Choices window will load the ₧le into a text editor, where you can
edit and save the new ₧le; choosing öReload drag ₧lesò will run the ₧le,
setting the appropriate system variables.

Boring legal message
********************

   This application is freeware, that is, it can be distributed freely as
long as only reasonable charges are made for media and distribution. I retain
copyright on all program code and documentation.

   This software is supplied öasáisò: I make no warranty, expressed or
implied, of the merchantability of this software or its ₧tness for any
particular purpose. In no circumstances shall I be liable for any damage,
loss of pro₧ts, or any indirect or consequential loss arising out of the use
of this software or inability to use this software, even if I have been
advised of the possibility of such loss.

   In other words, if your computer crashes, blows up, you lose all your work
etc. all because of CLI Guardian (unlikely I know), donæt blame me.

About all these strange foreign characters in this ₧le
*******************************************************

   OK, so if youære reading this on a PC or a Mac or another strange machine
like that, you may be wondering what all these strange ae things are. Well,
theyære quotes (sorry, there was another one), dashes, ligatures, etc.
Honest. But not on all machines...
   Basically, character sets are only standard up to character 127, which is
basically alphanumerics and a few standard punctuation marks. Foreign
characters, typographical oddities like quotes and ligatures, and other more
obscure symbols are önon-standardò, and each computer often has its own idea
of where they should go in the character set. So donæt worry: even if itæs
hard to read on your current machine, it wonæt be on an Acorn machine. It may
look slightly strange if youære using the System font, however.
   But why am I using these strange characters in the ₧rst place? Well,
theyære in the character set and they look nice in an outine font, and Iæve
written a program called Smart Quotes (sorry for the plug) that substitutes
these sort of characters automatically, and Iæve got it turned on at the
moment...

How to contact me
*****************

All bug-reports, suggestions, comments or indeed any feedback at all will be
welcomed. Hereæs how to get to me:

E-mail     : [e-mail] during term-time
             These should be OK until June 1996
             I (probably) wonæt be at Glasgow during the holidays, but mail
             will be automatically forwarded to [e-mail], which is
             my French email address.

Snail-mail : My term-time address, at least until June 1995, is:
             Sam Kington
             Flat 2/1
             44 Hotspur Street
             Glasgow G20 8NL
             SCOTLAND

             Again, a backup is the home address ù anything that goes here will get
             to me eventually.
             Sam Kington
             Merlhiot
             24420 Savignac les Eglises
             FRANCE

Term-time is October to June, with bits off at Christmas (3 weeks) and
Easter (4 weeks).