                +-------------------------------------+
                | Manual for ALT-itude Software's !U2 |
                +-------------------------------------+
                
                     This software is FREEWARE.
                It may be freely distributed so long
                  as no money is exchanged, except
                   to cover costs of distribution
                      ie post & packing or the
                        cost of the disk and
                    ALL the files are included in 
                      the distributed version.

           This software is (C) 1992-4 ALT-itude Software

You are not *required* to register your copy, but doing so will enable us to 
send you any upgrades as and when they become available, and you to send us 
your comments etc. 


1. Introduction
---------------
!U2 is a RISC OS, multi-tasking binary to ascii convertor, using uuencoding 
and uudecoding routines derived from those written by the University of 
California for UNIX-UNIX transfers. 

The raison d'etre behind such conversions is most e-mailers' inability to 
reliably handle any non-ascii characters; ie those with hex values outside 
the range &032-&127.

!U2 has two filetypes defined by it (these filetypes are subject to 
verification by Acorn - we haven't asked them and they might want us to 
use something else...):

        &00D - U2Dec - a general (binary) decoded file
        &00E - U2Enc - a U2Encoded file

A U2Enc file is, in essence, no different from an ordinary uuencoded 
file, but there are some RISC OS specific subtleties which are explained 
below. A U2Dec file is a binary file whose filetype you're not sure of.
No doubt Acorn would argue that this is what the Data filetype was
designed for, and we might feel inclined to agree.

!U2 requires the !Scrap directory to have been 'seen' before it runs.

2.Usage
-------

2.1 General
-----------
Double-click on the !U2 icon to load it, or double-click on an U2Enc file 
if !U2 has already been 'seen', this will load !U2 and begin decoding the 
file.

To encode a binary file, drag it to the icon; to decode an encoded file, 
either double-click on it or drag it to the icon. 

!U2 supports Ian Ashley's uuencoded filetype, &7FE, and treats plain text 
files (&fff) as encoded. The latter can be loaded either by dragging to the 
icon or double-clicking while holding down <CTRL>--though it may end up in
your favourite text editor instead! 

!U2 will decode files that have been encoded and then split into several, smaller files. It can do this in three ways, detailed below.

   1 Place the files in order in a file and decode in the normal way.
   2 Place the files in order in a directory and drag the directory to
     the !U2 icon. It helps if the directory and the files have similar
     name: eg. 'Picture' containing Picture/01, Picture/02,...
   3 Place the files in any order in a file and choose 'Extract' in the
     options window before decoding (see below).
     NOTE: This last is slower than the above methods, makes use of 
     <Wimp$ScrapDir> (but will tell you if it doesn't find enough free space
     to write to) and makes certain assumptions about the input file, as 
     detailed below.

2.2 Processing Options.
-----------------------
All options are set from the 'Options' submenu (unlike earlier versions 
where there were menu options as well). To make the options current, 
click on 'OK', to reset them to the previous settings, click on 'Cancel'.
Clicking on 'Save Options...' will save the options settings so that they 
will be loaded as the default settings next time !U2 is loaded. (This 
makes the settings displayed in the Options window the current settings.) 
Clicking on 'Load !Help...' loads this file into the default text editor.


2.2.1 Encoding Options
----------------------

  o <file>/uue       - names the encoded file as a (truncated) form of the 
  original filename, appended with /uue for compatibility with other
  systems (/ becomes replaced with . on UNIX/DOS systems).
  **Default=ON**
  
  o Enc_xx/uue       - names the encoded file with an incremented number.
  **Default=OFF**
  
  o Include Filetype - includes the filetype of the original file in the 
  encoding.
  **Default=ON**
  
  o Split            - split the encoding across several files. This is 
  particularly useful if you wish to encode a file which is several hundred 
  kbytes big, as most e-mailers have a maximum size of file which they will 
  mail. If set, !U2 will create a directory (called <file>~) and spread the 
  encoding across files named <file>/01, <file>/02, etc. If the original 
  file starts with '!', !U2 will replace this with a '>' so as to avoid any 
  truck with problems with application shells.
  **Default=OFF**

  o Lines, KBytes    - toggles the interpretation of the number in the 
  writeable icon below them. 1000 lines is approximately equal to 62 Kb, 
  and is the default. 
  !U2 will default to a value of 4k (66 lines) if a lower value is entered, 
  and 719k (11600) if a higher value is entered. (Don't ask why these sizes 
  were chosen---it was very late one night and they seemed reasonable 
  then...)
  **Default=Lines, 1000**

You should note that RISC OS (3.10 and earlier) allows a _maximum_ of 77 
files per directory. !U2 will inform you if you enter a value which would 
result in more than 77 parts.

To understand more the effects of the encoding options, consider the following: 

A U2Encoded Sprite with 'Split' and 'Include' selected will begin 
something like this:

+--BEGIN-Cut here-[screen part 01 of 03]----------------------+
begin ff9 screen
M'0'''!''''#\GP''[)\'''-C<F5E;@'''''''#''''#/'''''''''!,'''"L
M''''K'''''P'''''____'/___P#=W=T'W=W='+N[NP"[N[L'F9F9')F9F0!W

and end something like this:

M=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W
"!P!W
'
end
+--END-Cut here-[screen part 01 of 03]------------------------+

whereas if neither are selected it looks like this:

+--BEGIN Cut here [ screen] ------------------------------------+
begin 660 screen
M'0'''!''''#\GP''[)\'''-C<F5E;@'''''''#''''#/'''''''''!,'''"L
M''''K'''''P'''''____'/___P#=W=T'W=W='+N[NP"[N[L'F9F9')F9F0!W

and this:

M=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W=W
"!P!W
`
end
+-- END Cut here [ screen] -------------------------------------+

(In both cases the first line is a !U2 specific header line and !U2 will 
look for this if 'Extract' is selected.)

Note: some encoded files don't have a 'short' line before the `-line 
because the encoding fits exactly into an integer number of M-lines.

If you choose a size which is a little too close to a factor of the total 
encoded size, then the 'cut' lines may say the wrong number of parts, eg 
they may say 'part 03 of 04' when there _are_ only 3 parts. Don't worry 
about this - !U2 will do a full encoding or none at all. You might want to 
choose a different size, though, or inform whomever is receiving the parts 
that you really have sent all of them!

Other uudecoders will treat the hex number in the 'begin' line as the 
access codes for the file. Other Acorn uudecoders will look for the 
filetype in an extra line at the start of the file. We decided to have the 
filetype included in the 'begin' line. However, we recognise that if this 
file is decoded on a non-Acorn system, or with a different decoder then 
this might cause problems with file access, which is why you have the 
choice of including the filetype or not. 

The filename of the binary file is included in the encoding. To make things 
as easy as possible for the user, any '/'s in the Acorn filename will be 
written as '.'s in the encoded file. (!U2 retranslates these characters on 
decoding.) Not doing this would cause problems with decoding on non-Acorn 
systems. 

2.2.2 Decoding Options
----------------------
  o Original             - names the decoded binary file from the name 
  included in the 'begin' line of the encoded file. Don't use this if the 
  file doesn't have such a name in the encoding.
  **Default=ON**
  
  o Dec_xx               - names the decoded binary file with an 
  incremented number.
  **Default=OFF**
  
  o Set Decoded Filetype - sets the filetype of the decoded file, either by 
  reading it from the encoded file or by having it entered in the writeable 
  icon on the dialogue box.
  **Default=ON**
  
  o Read from input file - will cause !U2 to look for the filetype in the 
   'begin' line. Don't use this if the file was not encoded by !U2 with the 
   'Include' option set. Enter the filetype by hand as detailed below.
   **Default=OFF**

  o User defined        - will cause !U2 to look for the filetype in the 
   writeable icon. This can be entered either by clicking in the icon and 
   entering a 3-digit hex number, or by clicking MENU on the arrowed icon 
   and selecting a filetype from the filetypes menu. 
   **Default=ON, &DDC**

  o Extract             - causes !U2 to attempt to parse the encoded data
   to determine how many encoded parts are in the file and in what order. 
   If the parts are in the correct order in the file, there's no need to 
   click on this. 
   We thought about this for some time and came to the conclusion that the 
   only time you would have encoded data which had been split and then 
   assembled out of order is if you got it from either an email or netnews 
   reader, in both of which cases there will be a 'Subject: ' line for each 
   part. If there isn't, then we're very sorry, but you'll have to take 
   each piece out by hand. Sorry, but that's the way it goes. ALSO: !U2 
   assumes that the information in each Subject line contains the part 
   number in one of the following ways. As two numbers separated by a '/' 
   (which appears to be the de facto standard on most binaries newslists) 
   or as 'Part x', 'part x' or 'PART x'. If it doesn't, then either edit it 
   so it does, or extract the files by hand. If !U2 can't find the 
   information it needs, it will offer you the choice of decoding the file 
   as if the parts are in order or forgetting the whole thing.
   (Well, OK, sometimes, someone might mail you the parts without telling 
   you which are which so !U2 will also look for files of its own by looking 
   for U2Enc header lines.)
   The Hourglass LEDs will be lit while !U2 parses the input file.
   **Default=OFF.**

(When decoding from a &7FE file, 'Set Type...' should be set to 'Read'.)

!U2 will attempt to decode only the lines it sees as containing uuencoded 
data, so there's no need to strip mail headers or the like from the files.


2.3 Miscellaneous
-----------------
  o Confirm         - when set, !U2 will bring up a window containing the  
  name, icon and size of the dragged file and the processed file, and the 
  process to be performed. Clicking on 'Proceed' will start the coding, 
  'Cancel' will cancel it. While the processed file's size given is quite a 
  good estimate of the resulting file's size, it is still an estimate and 
  you should ensure there is sufficient space when coding. !U2 will tell 
  you if there isn't sufficient disk space to write the file. Note that 
  an encoded file is approximately 40% bigger than the original file.
  **Default=ON**

  o Delete Source   - does exactly what it says. Be Careful!
  **Default=OFF**     

  o Multi-Task      - allows you to get on with other things while
  !U2 processes your file. Click on the iconbar for a summary of the
  coding in process. 'Stop' on the iconbar menu stops the process. 
  When coding in multitasking mode, the 'Options' box is unattainable.
  Multitasking coding is *much* slower; in some cases taking almost 
  twice as long.
  **Default=ON**
  
3.Filetypes
-----------
In the !U2 directory is a file called 'Filetypes' which is read when !U2 
starts up. You can customise which filetypes appear by altering the lines 
as follows:

To cause !U2 to skip an existing entry, place a '+' in front of it (see 
existing file), to include a commented type, remove the '+' and to add a 
new one, simply place it before the last line (maintaining a numeric order 
would be nice, but is not essential) in the correct format which should be 
easy to deduce. !U2 will only take account of the first 50 types.

It is important that the last line:

     '+This line must be here.'

is there. If it isn't, !U2 will assume the file is corrupt and generate a 
new one, but the only entry will be '00D : U2Dec'. Similarly, if the file 
has been renamed or removed, !U2 will generate one, but it will only have 
one entry, as above.

It is VITAL that the only lines that don't start with '+' are those lines 
that contain the filetypes.

4.Copyright Notice
------------------

This release of !U2 (v2.7) contains the following files:

        !Boot
        !Help
        !Run
        !RunImage
        !Sprites
        !Sprites22
        Filetypes
        Manual          <--- this file
        Messages
        Options
        Templates

If the version you've got doesn't contain all these files, then your copy is not a legitimate copy and you should ask whomever you got your copy from 

            "WHY THE HELL NOT?"

We were going to include a Versions file but nobody *really* reads those 
files do they?

Known Problems/Niggles:
-----------------------
30th Mar 93: Seems to have a problem with the RAM disc under RISC OS 2.
25th Nov 93: If you change from 'Lines' to 'Kb' or vice versa then you'll
             also have to enter the number again before clicking on 'OK'.
 1st Jan 94: The extraction algorithm is still unperfected and there's
             a (reasonable) chance it'll screw up when you least want it 
             to--such as trying to extract the uuencoded data from a 
             dozen parts totally out of any order at all. Like it just 
             did to me :-(
             
These are the places to send comments, bug reports, compliments, 
suggestions and registration details:

    by email:       pss@liverpool.ac.uk
               I.Giblin@.sussex.ac.uk

+-------------------------------------------------------------------------+
| ALT-itude is the software house of:- Ian Giblin and Paddy Spencer       |
+-------------------------------------------------------------------------+ 
| This software is supplied 'as is' - absolutely no warranty is implied   |
| nor given. In no circumstances shall the authors be liable for any      |
| damage, loss of profits, time or data or any indirect or consequential  |
| loss arising from the use of or inability to use this software.         |
+-------------------------------------------------------------------------+

------------  Paddy Spencer, 28th Jan 1994 -----------------------------
