home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / converters / u2_1 / !U2 / Docs / Manual < prev   
Text File  |  1995-01-12  |  17KB  |  388 lines
  1.                 +-------------------------------------+
  2.                 | Manual for ALT-itude Software's !U2 |
  3.                 +-------------------------------------+
  4.                 
  5.                     As of v3.00 !U2 is SHAREWARE:
  6.              you are allowed to try this out for a trial
  7.             period of 2 weeks, after that you must either
  8.                   register your copy or delete it.
  9.                 Read the file 'Licence' for details.
  10.  
  11.            This software is © 1992-5 ALT-itude Software
  12.  
  13.  
  14. 1. Introduction
  15. ~~~~~~~~~~~~~~~
  16. !U2 is a RISC OS, multi-tasking binary to ascii convertor, using uuencoding 
  17. and uudecoding routines.
  18.  
  19. The raison d'etre behind such conversions is most e-mailers' inability to 
  20. reliably handle any non-ascii characters; ie those with hex values outside 
  21. the range &032-&127.
  22.  
  23. !U2 defines two filetypes:
  24.  
  25.         &00D --- U2Dec --- a general (binary) decoded file
  26.         &00E --- U2Enc --- a U2Encoded file
  27.  
  28. A U2Enc file is, in essence, no different from an ordinary uuencoded 
  29. file, but there are some RISC OS specific subtleties which are explained 
  30. below. A U2Dec file is a binary file whose filetype you're not sure of.
  31. No doubt Acorn would argue that this is what the Data filetype was
  32. designed for, and we might feel inclined to agree.
  33.  
  34. !U2 requires the !Scrap directory to have been 'seen' before it runs.
  35.  
  36. If you don't feel up to reading all this then you might be relieved to learn
  37. that !U2 has interactive help available through Acorn's !Help utility.
  38.  
  39. 2.Usage
  40. ~~~~~~~
  41.  
  42. 2.1 General
  43. ~~~~~~~~~~~
  44. Double-click on the !U2 icon to load it, or double-click on a U2Enc file 
  45. if !U2 has already been 'seen', this will load !U2 and begin decoding the 
  46. file.
  47.  
  48. To encode a binary file, drag it to the icon; to decode an encoded file, 
  49. either double-click on it or drag it to the icon. 
  50.  
  51. !U2 supports Ian Ashley's uuencoded filetype, &7FE, and treats plain text 
  52. files (&fff) as encoded. The latter can be loaded by dragging to the icon.
  53.  
  54. !U2 will decode files that have been encoded and then split into several,
  55. smaller files. It can do this in three ways, detailed below.
  56.  
  57.    1 Place the files in order in a file and decode in the normal way.
  58.    2 Place the files in order in a directory and drag the directory to
  59.      the !U2 icon. It helps if the directory and the files have similar
  60.      name: eg. 'Picture' containing Picture/01, Picture/02,...
  61.    3 Place the files in any order in a file and choose 'Extract' in the
  62.      options window before decoding (see below).
  63.      NOTE: This last is slower than the above methods, makes use of 
  64.      <Wimp$ScrapDir> (but will tell you if it doesn't find enough free space
  65.      to write to) and makes certain assumptions about the input file, as 
  66.      detailed below.
  67.  
  68. When !U2 is first loaded, it checks the screen mode and sets the resources 
  69. for sprites, etc. accordingly. In the 'Info' box on the iconbar menu it will
  70. say what screen resolution !U2 is set up for. (Note: as the RISC PC sets its
  71. screens in a different manner to other RISC OS machines, and as we don't have
  72. access to one yet :-( we can't say how this will affect the running of !U2.
  73. If you find something weird happening then let us know.)
  74.  
  75. 2.2 Processing Options.
  76. ~~~~~~~~~~~~~~~~~~~~~~~
  77. All options are set from the 'Options' submenu (unlike earlier versions 
  78. where there were menu options as well). The tool buttons work as follows:
  79.  
  80.   • 'OK' makes the options as shown the current ones. 
  81.   • 'Cancel' closes the window without changing anything.
  82.   • 'Save' makes the options as shown the current ones and 
  83.     saves them to disk, to become the default when !U2 is next loaded. 
  84.   • 'Default' resets the window to show the default options !U2 is 
  85.     supplied with. 
  86.   • 'Reset' resets the window to show the current options. 
  87.   • 'Load Manual' loads this file into your default text editor.
  88.  
  89. IMPORTANT: the Options files from previous versions of !U2 are not compatible
  90. with the newer release.
  91.  
  92. 2.2.1 Encoding Options
  93. ~~~~~~~~~~~~~~~~~~~~~~
  94.  
  95.   • <file>/uue
  96.   Names the encoded file as a (truncated) form of the original filename,
  97.   appended with /uue for compatibility with other systems (/ becomes replaced
  98.   with . on UNIX/DOS systems).
  99.   **Default=ON**
  100.   
  101.   • Enc_xx/uue       
  102.   Names the encoded file with an incremented number.
  103.   **Default=OFF**
  104.   
  105.   • !U2              
  106.   Includes the filetype of the original file in the 'begin' line (see
  107.   below). This option is equivalent to the 'Include' option on earlier versions
  108.   of !U2. This may cause problems with other uudecoders which treat the numver
  109.   as an octal representation of the access codes for the original file.
  110.   **Default=ON**
  111.   
  112.   • UNIX              
  113.   Includes the filetype of the original file in a line before the 'begin'
  114.   line (see below) in order to enable trouble-free decoding on UNIX/DOS
  115.   machines.
  116.   **Default=OFF**
  117.   
  118.   • Split
  119.   Split the encoding across several files. This is particularly useful if you
  120.   wish to encode a file which is several hundred kbytes big, as some e-mailers
  121.   or netnews posters have a maximum size of file which they will mail. If set,
  122.   !U2 will create a directory (called <file>~) and spread the encoding across
  123.   files named <file>/01, <file>/02, etc. If the original file starts with '!',
  124.   !U2 will replace this with a '>' so as to avoid any truck with problems with
  125.   application shells.
  126.   **Default=OFF**
  127.  
  128.   • Lines, KBytes    
  129.   Toggles the interpretation of the number in the writeable icon below them.
  130.   1000 lines is approximately equal to 62 Kb, and is the default. !U2 will
  131.   default to a value of 4k (66 lines) if a lower value is entered, and 1440k
  132.   (23210) if a higher value is entered. (Don't ask why these sizes were chosen
  133.    --- it was very late one night and they seemed reasonable then...). The
  134.    number in the icon changes when these are clicked.
  135.   **Default=KBytes, 60**
  136.    
  137.   Clicking on the arrow icon brings up a menu with some example split
  138.   sizes; the top four given in kbytes and the lower four in lines. The two
  139.   sets are connected: eg. clicking on 62k ticks both 62k and 1000.
  140.  
  141.   You should note that RISC OS 3.10 allows a _maximum_ of 77 files per
  142.   directory (except for DOSFS, NetFS and other image file systems). !U2 will
  143.   inform you if you try to split a file across more than 77 parts.
  144.  
  145. 2.2.2 What the encoding options actually _do_
  146. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  147.   To understand more the effects of the encoding options, consider the
  148. following: 
  149.  
  150. A U2Encoded Sprite with 'Split' and '!U2' selected will begin something like
  151. this:
  152.  
  153. +--BEGIN-Cut here-[screen part 01 of 03]----------------------+
  154. begin ff9 screen
  155. M'0'''!''''#\GP''[)\'''-C<F5E;@'''''''#''''#/'''''''''!,'''"L
  156. M''''K'''''P'''''____'/___P#=W=T'W=W='+N[NP"[N[L'F9F9')F9F0!W
  157.  
  158. and end something like this:
  159.  
  160. 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
  161. "!P!W
  162. '
  163. end
  164. +--END-Cut here-[screen part 01 of 03]------------------------+
  165.  
  166. whereas if 'Split' is unselected and 'UNIX' is it looks like this:
  167.  
  168. +--BEGIN Cut here [screen] ------------------------------------+
  169. Filetype:ff9
  170. begin 660 screen
  171. M'0'''!''''#\GP''[)\'''-C<F5E;@'''''''#''''#/'''''''''!,'''"L
  172. M''''K'''''P'''''____'/___P#=W=T'W=W='+N[NP"[N[L'F9F9')F9F0!W
  173.  
  174. and this:
  175.  
  176. 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
  177. "!P!W
  178. `
  179. end
  180. +-- END Cut here [screen] -------------------------------------+
  181.  
  182. (In both cases the first line is a !U2 specific header line and !U2 will 
  183. look for this if 'Extract' is selected.)
  184.  
  185. Note: some encoded files don't have a 'short' line before the `-line 
  186. because the encoding fits exactly into an integer number of M-lines.
  187.  
  188. With earlier versions of !U2 (pre v3.00), if you chose a size which is a
  189. little too close to a factor of the total  encoded size, then there was the
  190. problem that the 'cut' lines said the wrong number of parts, eg they said
  191. 'part 03 of 04' when there _were_ only 3 parts. This has been corrected with
  192. the newer versions. (If anyone tries really hard and actually manages to
  193. still get this error, please get in touch!)
  194.  
  195. The filename of the binary file is included in the encoding. To make things 
  196. as easy as possible for the user, any '/'s in the Acorn filename will be 
  197. written as '.'s in the encoded file. (!U2 retranslates these characters on 
  198. decoding.) Not doing this would cause problems with decoding on non-Acorn 
  199. systems. 
  200.  
  201. 2.2.3 Decoding Options
  202. ~~~~~~~~~~~~~~~~~~~~~~
  203.   • Original             
  204.   Names the decoded binary file from the name included in the 'begin' line
  205.   of the encoded file. Don't use this if the file doesn't have such a name in
  206.   the encoding.
  207.   **Default=ON**
  208.   
  209.   • Dec_xx               
  210.   Names the decoded binary file with an incremented number.
  211.   **Default=OFF**
  212.   
  213.   • Set Decoded Filetype 
  214.   Sets the filetype of the decoded file, either by reading it from the
  215.   encoded file or by having it entered in the writeable icon on the dialogue
  216.   box.
  217.   **Default=ON**
  218.   
  219.   • Read 
  220.   Will cause !U2 to look for the filetype in the 'begin' line. Don't use
  221.   this if the file was not encoded by !U2 with the '!U2' option set, enter the
  222.   filetype by hand as detailed below. (When decoding from a &7FE file, 'Set
  223.   Type...' should be set to 'Read'.)
  224.   **Default=OFF**
  225.  
  226.   • User 
  227.   Will cause !U2 to look for the filetype in the writeable icon. This can be
  228.   entered either by clicking in the icon and entering a 3-digit hex number
  229.   (there's no need to type '&'), or by clicking on the arrow icon and selecting
  230.   a filetype from the filetypes menu. 
  231.   **Default=ON, &DDC**
  232.  
  233.   • Extract             
  234.   Causes !U2 to attempt to parse the encoded data to determine how many
  235.   encoded parts are in the file and in what order. If the parts are in the
  236.   correct order in the file, there's no need to click on this. 
  237.  
  238.   We thought about this for some time and came to the conclusion that the 
  239.   only time you would have encoded data which had been split and then 
  240.   assembled out of order is if you got it from either an email or netnews 
  241.   reader, in both of which cases there will be a 'Subject: ' line for each 
  242.   part. If !U2 can't find the information from it's own header lines (shown
  243.   above) then it will try and get the info it needs from the 'Subject: '
  244.   line, if there is one.If there isn't, then we're very sorry, but you'll
  245.   have to take each piece out by hand. Sorry, but that's the way it goes.
  246.   ALSO: !U2 assumes that the information in each Subject line contains the
  247.   part number in one of the following ways. As two numbers separated by a
  248.   '/' (which appears to be the de facto standard on most of the binaries
  249.   newslists). If it doesn't, then either edit it so it does, or extract the
  250.   files by hand. If !U2 can't find the information it needs, it will offer
  251.   you the choice of decoding the file as if the parts are in order or
  252.   forgetting the whole thing.
  253.  
  254.   (Well, OK, sometimes, someone might mail you the parts without telling 
  255.   you which are which so !U2 will also look for files of its own by looking 
  256.   for U2Enc header lines.)
  257.  
  258.   The Hourglass LEDs will be lit while !U2 parses the input file in
  259.   single-task mode.
  260.   **Default=OFF.**
  261.  
  262.   • Set Access         
  263.   This takes the octal number in the 'begin' line and sets the access of the
  264.   decoded file from it.
  265.   **Default=OFF**
  266.  
  267. !U2 will attempt to decode only the lines it sees as containing uuencoded
  268. data, so there's no need to strip mail headers or the like from the files.
  269.  
  270. 2.3 Miscellaneous
  271. ~~~~~~~~~~~~~~~~~
  272.   • Confirm         
  273.   When set, !U2 will bring up a window containing the  name, icon and size
  274.   of the dragged file and the processed file, and the process to be performed.
  275.   Clicking on 'OK' will start the coding, 'Cancel' will cancel it. While
  276.   the processed file's size given is quite a good estimate of the resulting
  277.   file's size, it is still an _estimate_ and you should ensure there is
  278.   sufficient space when coding. !U2 will tell you if there isn't sufficient
  279.   disk space to write the file. Note that an encoded file is approximately 40%
  280.   bigger than the original file.
  281.   **Default=ON**
  282.  
  283.   • Delete Source   
  284.   Does exactly what it says. Be Careful!
  285.   **Default=OFF**     
  286.  
  287.   • Multi-Task      
  288.   Allows you to get on with other things while !U2 processes your file. Click
  289.   on the iconbar for a summary of the coding in process. Clicking on !U2 icon
  290.   brings up a window with a summary of the process. Clicking on 'Cancel' stops
  291.   the process. When coding in multitasking mode, the 'Options' box is
  292.   unattainable. Multitasking coding is _much_ slower; in some cases taking
  293.   almost twice as long.
  294.   **Default=ON**
  295.  
  296.   • Multiples       
  297.   This option is currently unsupported.
  298.   **Default=OFF**
  299.   
  300. 3.Filetypes
  301. ~~~~~~~~~~~
  302. In the !U2 directory is a file called 'Filetypes' which is read when !U2 
  303. starts up. You can customise which filetypes appear by altering the lines 
  304. as follows:
  305.  
  306. To cause !U2 to skip an existing entry, place a '+' in front of it (see 
  307. existing file), to include a commented type, remove the '+' and to add a 
  308. new one, simply place it before the last line (maintaining a numeric order 
  309. would be nice, but is not essential) in the correct format which should be 
  310. easy to deduce. !U2 will only take account of the first 50 types.
  311.  
  312. It is important that the last line:
  313.  
  314.      '+This line must be here.'
  315.  
  316. is there. If it isn't, !U2 will assume the file is corrupt and generate a 
  317. new one, but the only entry will be '00D : U2Dec'. Similarly, if the file 
  318. has been renamed or removed, !U2 will generate one, but it will only have 
  319. one entry, as above.
  320.  
  321. It is VITAL that the only lines that don't start with '+' are those lines 
  322. that contain the filetypes.
  323.  
  324. 4.Copyright Notice
  325. ~~~~~~~~~~~~~~~~~~
  326.  
  327. This release of !U2 (v3) contains the following files:
  328.  
  329.               !Boot
  330.               !Help
  331.               !Run
  332.               !RunImage
  333.               !Sprites
  334.               !Sprites22
  335.               Filetypes
  336.               Docs.Changes
  337.               Docs.Licence
  338.  This file -> Docs.Manual          
  339.               Resource/Resource22.Messages
  340.               Resource/Resource22.Sprites
  341.               Resource/Resource22.Templates
  342.               Options
  343.         
  344.  
  345. If the version you've got doesn't contain all these files, then your copy is
  346. not a legitimate copy and you should ask whomever you got your copy from 
  347.  
  348.             "WHY THE HELL NOT?"
  349.  
  350. There is a Changes file that details changes since v2.70.
  351.  
  352. Feel free to send comments, bug reports, compliments, suggestions etc, either
  353. to the e-mail addresses below or when you _register_. (Read !U2.Licence now!)
  354.  
  355. 4. Acknowledgements
  356. ~~~~~~~~~~~~~~~~~~~
  357. Much respect to Dominic Symes for !Zap, undoubtedly the bestest text editor
  358. for RISC OS. Also to Martin Ebourne for his C mode, without which this would
  359. have been much less colourful. 
  360.  
  361. Thanks to the various people on comp.sys.acorn.tech who helped me with my
  362. problems with panes and pop-ups and other things, particularly Andy
  363. Armstrong, and the dude who wrote  get_icon_xy() whose name I can't find
  364. anymore...
  365.  
  366. +=========================================================================+
  367. |                                                                         |
  368. |   ALT-itude is: Dr. Ian Giblin     e-mail:  I.Giblin@sussex.ac.uk       |
  369. |                 Dr. Paddy Spencer  e-mail:  Paddy.Spencer@helsinki.fi   |
  370. |                                                                         |
  371. |  If you think this program is OK, check out our other P.D. work:        |
  372. |                                                                         |
  373. |      !Saviour.... desktop auto-save from almost any application         |
  374. |      !TaskKeys... intelligent desktop function key strips               |
  375. |      !AppMaker... easy construction of application shells               |
  376. |      !2048....... count file _and_ directory sizes                      |
  377. |                                                                         |
  378. |  and also the commercial !SmartCD+, available from the ARM Club.        |
  379. |                                                                         |
  380. +-------------------------------------------------------------------------+ 
  381. | © Paddy Spencer, 12th Jan 1995                                          |
  382. +-------------------------------------------------------------------------+ 
  383. | This software is supplied 'as is' --- absolutely no warranty is implied |
  384. | nor given. In no circumstances shall the authors be liable for any      |
  385. | damage, loss of profits, time or data or any indirect or consequential  |
  386. | loss arising from the use of or inability to use this software.         |
  387. +=========================================================================+
  388.