home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 2 / crawlyvol2.bin / utility / archiver / esscd63 / esscode.txt < prev    next >
Text File  |  1994-11-10  |  23KB  |  514 lines
  1.                           E S S - C o d e   6 . 3
  2.                           """""""""""""""""""""""""
  3.  
  4.                      Copyright 1993, 1994, Michel Forget
  5.                      
  6.                            Electric Storm Software      
  7.  
  8.     ---------------------------------------------------------------------
  9.     Atari (Mega) ST/STe / STfm / TT / Falcon ASCII <--> BINARY Conversion
  10.  
  11.                           MultiTOS / Mag!X / Geneva                         
  12.     ---------------------------------------------------------------------
  13.                 
  14.                 * * * I M P O R T A N T   N O T I C E ! * * *
  15.  
  16.      As a direct result of the growing investment of time and effort
  17.      placed into this application, ESS-Code is now a SHAREWARE product.
  18.  
  19.      Users who register ESS-Code will receive a disk with the latest
  20.      version of ESS-Code (optimized), and a registered (optimized,
  21.      personalized) version of MasterBrowse (which also includes MasterPrint,
  22.      AutoDate, ACC-Pad, ShadowTerm II, and a coupon for a free catalog from
  23.      Suzy B's Software and a $3 credit toward the purchase of a disk from
  24.      the Suzy B's Software collection).
  25.  
  26.      The continued development of ESS-Code depends _solely_ on user
  27.      contributions; if no such contributions are received, this
  28.      application will not be developed further.
  29.  
  30.      For more information on registration, please read the "Registration"
  31.      section of this manual.
  32.  
  33.                 * * * * * * * * * * * * * * * * * * * * * * *
  34.  
  35.      *-----------------------------------------------------------------*
  36.      | For information about the distribution of ESS-Code, please read |
  37.      | the section of this manual entitled "Distribution".             |
  38.      *-----------------------------------------------------------------*
  39.  
  40.                                  - CONTENTS -
  41.  
  42.                         I. INTRODUCTION
  43.  
  44.                        II. REGISTRATION
  45.  
  46.                       III. INSTALLING & USING ESS-CODE
  47.                           
  48.                        IV. OPTIONS
  49.                            A. Confirm Termination
  50.                            B. Confirm Overwrites
  51.                            C. Progress Displays
  52.                            D. Unix Line Termination
  53.                            E. TOS 1.4 File Selector
  54.                            F. AutoSave Options
  55.                            G. Use Fast SHIP Encoding
  56.                            I. Include Paths
  57.                            J. Specify Segments
  58.                            K. Select Target
  59.                            L. Segmentation
  60.                            
  61.                         V. ACKNOWLEDGEMENTS
  62.                        
  63.                        VI. DISCLAIMER
  64.                         
  65.                       VII. DISTRIBUTION
  66.                        
  67.                      VIII. CONTACTING THE AUTHOR
  68.                       
  69.                        IX. THE ART OF BINARY <-> ASCII CONVERSION
  70.  
  71.                         X. CLOSING
  72.  
  73.  
  74. I. INTRODUCTION
  75. -=-=-=-=-=-=-=-
  76.  
  77.     This program was designed to allow computer users to exchange binary
  78. files over computer networks that do not support the transmission of
  79. binary data.  This can be done by converting the binary file to an ASCII
  80. file, then converting the ASCII file back to its original binary state
  81. after transmission.
  82.  
  83.     There are four popular methods of conversion; UUEncoding/UUDecoding,
  84. MIME-Encoding/MIME-Decoding, BTOA-Encoding/BTOA-Decoding, and SHIP-Encoding/
  85. SHIP-Decoding.  Since each of these conversion methods is an accepted
  86. standard, there are a wide variety of encoding/decoding utilities for
  87. every computer platform.
  88.  
  89.     If output size is not an issue, the best conversion method to use is
  90. UUEncoding/UUDecoding.  This method is fast, reliable, and allows large
  91. files to be segmented (and re-assembled) automatically.
  92.  
  93.     If output size is an issue, however, the best conversion method to use
  94. is MIME-Encoding/MIME-Decoding.  This conversion method is not very fast,
  95. but produces very compact output.  It is rapidly replacing UUEncoding/
  96. UUDecoding as the conversion method of choice, because it is has all of
  97. the power of UUEncoding/UUDecoding and is nearly as widely supported.
  98.  
  99.     Why should you use ESS-Code instead of one of the many other utilities
  100. currently available?
  101.  
  102.     Here are six good reasons:
  103.     
  104.         1)  SPEED - ESS-Code is much faster than other coding programs
  105.             that I have tested.  In some cases, the difference is as much
  106.             as 469%!  (Yes, that is correct.)
  107.             
  108.         2)  APPEARANCE - ESS-Code uses GEM!  This means that you are given
  109.             a nicely formatted progress display (which shows the output file,
  110.             the input file, the currently active parameters, the source and
  111.             destination path, and a "percentage" meter in both numeric and
  112.             graphic form that indicates how much of the current file
  113.             has been processed.  Since it is a GEM program, you can access
  114.             your desk accessories at any time, and set your options using
  115.             pull-down menus.  ESS-Code uses NON-MODAL window dialogs and
  116.             alert boxes, so you can use your accessories or applications
  117.             (or even other ESS-Code dialog boxes) while inside a dialog box!
  118.             With MultiTOS, all dialog boxes (and alert boxes) can be
  119.             iconified.
  120.  
  121.         3)  FLEXABILITY - ESS-Code supports UUEncoding, UUDecoding,
  122.             BTOA-Encoding, BTOA-Decoding, SHIP-Encoding, SHIP-Decoding,
  123.             MIME-Encoding, MIME-Decoding, RAW-Splitting, and RAW-Concatening
  124.             of files.  All of your file conversion needs are handled by one
  125.             program.  Should the need arise, ESS-Code can even execute as a
  126.             TOS program (with a TOS interface).
  127.  
  128.         4)  COMPATIBILITY - While conversion methods have remained roughly
  129.             the same, the Atari ST has not.  ESS-Code has support for the
  130.             ARGV command line standard that Atari has adopted, as well as
  131.             support for the default command line standard used by older ST
  132.             systems.
  133.  
  134.         5)  OPTIONS - ESS-Code has more options than any other encoding or
  135.             decoding program available for the Atari.
  136.  
  137.         6)  HELP - Using the ST-Guide HyperText accessory, the entire
  138.             ESS-Code manual is available at any time from within
  139.             ESS-Code.
  140.  
  141.  
  142. II. REGISTRATION
  143. -=-=-=-=-=-=-=-=
  144.  
  145. OR:  Why should I send this person money if I have the program already?
  146.  
  147.     I would like to start this section of the manual by saying I am not
  148. going to try to make you feel guilty; I would like to say it, but I will
  149. not.
  150.  
  151.     Like many authors of Shareware products, I have come to learn that
  152. very few people register Shareware software.  I do not know why; I can
  153. only guess the reasons.  The reasons do not really matter, though,
  154. because the end result is always the same.  On GEnie, MasterBrowse is
  155. regularly downloaded by over 150 users.  The numbers are much the same
  156. for CompuServe and Delphi, and much higher on the Internet.  Only 34
  157. people have registered MasterBrowse, though.
  158.  
  159.     I hope that more people elect to register ESS-Code.  There are many
  160. incentives to do so, but the largest incentive of all is this; there
  161. will be no further development of this product unless some registrations
  162. are received.  I cannot say it any more clearly; I love to write software
  163. for this system, but I cannot continue to do it without your support.
  164.  
  165.     Users who register ESS-Code will receive an optimized version of
  166. ESS-Code, a registered (and optimized) version of the popular text
  167. file viewer MasterBrowse, a series of utilities (AutoDate, ACC-Pad,
  168. MasterPrint, ShadowTerm II, and a coupon for a free catalog from
  169. Suzy B's Software.
  170.  
  171.     To register ESS-Code, send $15 (Canadian/US) to:
  172.  
  173.     Michel Forget
  174.     12209 Dovercourt Avenue
  175.     Edmonton, Alberta
  176.     CANADA
  177.     T5L 4E1
  178.  
  179.     If you do not live in North America (and you are writing to this 
  180. address instead of the address for users in the United Kingdom), please
  181. send an international money order or the equivalent of $15 in your own
  182. currency.  Please do not send a personal cheque unless you live in North
  183. America.
  184.  
  185.     If you live in the United Kingdom, you can send 14 UKPounds (cheque
  186. or money order) to Denesh Bhabuta:
  187.  
  188.      ESS (c/o Denesh Bhabuta)
  189.      203 Parr Lane
  190.      Unsworth
  191.      Bury
  192.      Lancashire
  193.      BL9 8JW
  194.  
  195. III. INSTALLING & USING ESS-CODE
  196. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  197.  
  198.     ESS-Code is a very versatile application, so there are several ways that
  199. it can be invoked:
  200.         
  201.     1)  The simplest way to use ESS-Code is to execute ESSCODE.PRG and then
  202.         select the options you would like to use and initiate an encoding
  203.         or decoding operation.
  204.  
  205.     2)  If you have a hard disk, you may want to install ESSCODE.PRG an an
  206.         application.  For best results, please ensure that the current
  207.         directory is set to "top window".  Since TOS 1.2 does not handle
  208.         installed applications correctly, it may be neccessary to edit
  209.         the DESKTOP.INF file (add the full pathname of ESS-Code to the
  210.         line containing the filename ESSCODE.PRG).
  211.  
  212.     3)  ESS-Code can also be installed on the desktop as an icon; this
  213.         allows an entire group of files to be processed in a single
  214.         pass.  Simply drag the desired files to the ESS-Code icon and
  215.         release the mouse button.  ESS-Code will _automatically_ decide
  216.         which files should be encoded and which files should be decoded.
  217.         Depending on your preferences, ESS-Code will also decide which
  218.         conversion method to use or ask which conversion method should be
  219.         used.
  220.  
  221.     4)  ESS-Code can easily be invoked from a command line interpreter.
  222.         Commands are not case-sensitive, but must be in the correct 
  223.         order and contain the correct number of arguments.  If ESS-Code
  224.         is invoked this way, it will use a TOS interface, which conforms
  225.         to the emerging standard among GEM archiver utilities.
  226.  
  227.         -uue     source destination_file
  228.         -uud     source destination_file
  229.         -btoa    source destination_file
  230.         -atob    source destination_file
  231.         -ship    source destination_path
  232.         -unship  destination_file source [source ...]
  233.         -mime    source destination_file
  234.         -unmime  source destination_file
  235.  
  236.         This method of invoking ESS-Code is not reliable when used with
  237.         segmented input/output.
  238.  
  239. IV. OPTIONS
  240. -=-=-=-=-=-
  241.  
  242.     There are several options that can be set to control how ESS-Code
  243. behaves:
  244.  
  245.     A. Confirm Termination - This option determines whether or not
  246.        ESS-Code will ask for confirmation before terminating.
  247.  
  248.     B. Confirm Overwrites - This option determines how ESS-Code will
  249.        behave if an existing file will be overwritten by an encoding
  250.        or decoding operation; if it is enabled, you will be given the
  251.        option of aborting the operation.
  252.  
  253.     C. Progress Displays - This option determines whether or not ESS-Code
  254.        will show progress displays.  Other than saving screen space, there
  255.        is no real advantage to turning progress displays off.
  256.  
  257.     D. Unix Line Termination - This option will force ESS-Code to terminate
  258.        ASCII lines with a linefeed (Unix) instead of a linefeed/carriage
  259.        return (IBM/Atari).
  260.  
  261.     E. TOS 1.4 File Selector - If this option is enabled, ESS-Code will
  262.        display prompts in the file selector.
  263.  
  264.     F. AutoSave Options - If this option is activated, ESS-Code will save
  265.        your options when you exit the program.  
  266.     
  267.     G. Use Fast SHIP Encoding - If this option is enabled, ESS-Code will
  268.        use an alternate (faster but less efficient) conversion method
  269.        during SHIP-Encoding operations.
  270.  
  271.     H. Include Paths - If this option is used, ESS-Code will include the
  272.        complete path of the source file in the encoded data.  Thus, when
  273.        decoding, the file will be written to the same path.  This option
  274.        should usually not be used, since it is unlikely that the system
  275.        that will receive the file will have the same directory structure
  276.        as your system.
  277.  
  278.     I. Specify Segments - This option (when selected) causes ESS-Code to
  279.        prompt the user for the name and location (using the file selector)
  280.        of each piece of the file to be UUDecoded.  This option will mainly
  281.        be of interest to users of Hermes UUCP or UPoint, who will no longer
  282.        have to copy messages out of their news directory, and then waste
  283.        time renaming the segments.
  284.     
  285.     J. Select Target - This option allows you to choose the destination
  286.        path for any encoding/decoding operation.  This option is mainly
  287.        for floppy users who want to decode to a ramdisk or a second floppy
  288.        disk and CLI users (who must specify a destination on the command
  289.        line).
  290.  
  291.        For those who would like the file selector to always be opened to
  292.        the same path (which is especially useful for people who always
  293.        extract files to the same place) the environment variable
  294.        "ESS_DPATH" can be defined; it should contain a "\" terminated
  295.        pathname.
  296.  
  297.     K. Default Conversion Method - This option determines which conversion
  298.        method ESS-Code will use when processing a group of files (such as
  299.        when the user selects "Process Batch" or when ESS-Code is passed
  300.        files on the command line).
  301.  
  302.     L. Segmentation - An encoded file can be divided into pieces, which
  303.        will be automatically joined together when being decoded.  This
  304.        makes it easier for network mailing software to process the
  305.        encoded file.  You can choose one of the preset sizes, or set your
  306.        own.  (Unless you are sure it will work, you should not use
  307.        segment sizes larger than 50K).
  308.  
  309.  
  310. V. ACKNOWLEDGEMENTS
  311. -=-=-=-=-=-=-=-=-=-
  312.  
  313.     There are many people who are deserving of recognition for their aid
  314. in creating this application:
  315.  
  316.     First, I would like to thank Steve Yelvington, the author of UUCODER
  317. 1.0 (the program on which ESS-Code was based).
  318.  
  319.     Another person deserving of recognition is Christian Grunenberg, the
  320. author of the excellent EnhancedGEM Library which is the core of ESS-Code.
  321. Christian is also responsible for the solving of the Falcon problems; his
  322. observations were absolutely correct, and solved the problems completely
  323. when I was almost ready to give up.
  324.  
  325.     I would also like to thank Ofir Gal, Traci J. Ingram, Gerhard Hoelscher,
  326. Carsten Friehe, Manfred Ssykor, the users of the MausNet, the users of the
  327. Internet, Mark Adler, Steve Wells, Michael Mies, John G. Myers, and RSA
  328. Data Security Incorporated.  In addition, I would like to thank the fine
  329. people of the GEM-List, who have contributed greatly to my understanding
  330. of the way the Atari operating system works.
  331.    
  332.  
  333. VI. DISCLAIMER
  334. -=-=-=-=-=-=-=
  335.  
  336.     ESS-Code does not come with any warranty, express or implied.  If you
  337. use ESS-Code, you do so at your own risk.  Neither the author of ESS-Code
  338. (Michel Forget) nor any other party will accept responsability for any
  339. equipment damage, data loss, or other unforseen consequence of the use or
  340. mis-use of ESS-Code.
  341.  
  342.  
  343. VII. DISTRIBUTION
  344. -=-=-=-=-=-=-=-=-
  345.  
  346.     There are two limitations placed on the distribution of ESS-Code:
  347.  
  348.     1) When distributed, ESS-Code must contain all files found in the
  349.        original archive.
  350.  
  351.     2) ESS-Code may not be distributed on the cover disk of any magazine
  352.        without the express written permission of the author.  This
  353.        limitation does not apply to electronic (or non-profit)
  354.        magazines.
  355.  
  356.  
  357. VIII. CONTACTING THE AUTHOR
  358. -=-=-=-=-=-=-=-=-=-=-=-=-=-
  359.  
  360.     If you would like to contact me with bug reports, suggestions, or
  361. comments, you can do so through the following addresses (in order of
  362. personal preference):
  363.  
  364. Internet:  mforget@elfhaven.ersys.edmonton.ab.ca
  365.            mforget@worldgate.edmonton.ab.ca
  366.  
  367.     Mail:  Michel Forget
  368.            12209 Dovercourt Avenue
  369.            Edmonton, Alberta
  370.            CANADA
  371.            T5L 4E1
  372.  
  373.  
  374. IX. THE ART OF BINARY <-> ASCII CONVERSION
  375. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  376.  
  377.      ESS-Code is an extremely flexible application; this section of the
  378. manual discusses (in detail) each of the four conversion methods supported
  379. by ESS-Code, and compares them.
  380.  
  381.      UUEncode/UUDecode
  382.      -----------------
  383.  
  384.      SYNOPSIS --          Speed:  Very Fast
  385.                       Expansion:  Poor (25%-30%)
  386.                    Segmentation:  Yes
  387.                  Reconstruction:  Automatic
  388.                  
  389.      This method of conversion is one of the first to gain popularity,
  390. and is thus one of the most widely accepted/used conversion methods to
  391. date.  It is supported on every computer platform, and provides reasonably
  392. good error checking.  It is very fast, but not very efficient.  The main
  393. advantages of using this conversion method are the speed, the ability to
  394. break up the output generated into small segments, and the ability to
  395. automatically reconstruct the segmented output.  The main (perhaps only)
  396. disadvantage of using this conversion method is that it generates output
  397. that is 25% (or more) larger than the original binary information.
  398.  
  399.      BTOA-Encode/BTOA-Decode
  400.      -----------------------
  401.  
  402.      SYNOPSIS --          Speed:  Slow
  403.                       Expansion:  Good (20%-25%)
  404.                    Segmentation:  No
  405.                  Reconstruction:  Manual
  406.  
  407.      While this method of conversion is popular, it is not as widely
  408. used/accepted as UUEncode/UUDecode.  It is vastly slower than UUEncode/
  409. UUDecode, but it generates more compact output.  The main advantage of
  410. using this conversion method is that it provides slightly better error
  411. checking that UUEncode/UUDecode.  There are numerous disadvantages, though,
  412. such as the lack of automatic segmentation or reconstruction.
  413.  
  414.      SHIP-Encode/SHIP-Decode
  415.      -----------------------
  416.  
  417.      SYNOPSIS --          Speed:  Average
  418.                       Expansion:  Good (20%-25%)
  419.                    Segmentation:  Yes
  420.                  Reconstruction:  Semi-Automatic
  421.  
  422.      While this conversion method is not as widely accepted/used as any of
  423. the other conversion methods, it is used extensively on HP-UNIX platforms.
  424. It is faster than BTOA-Encode/BTOA-Decode, and offers a nearly identical
  425. expansion rate, but has very light error checking.  It can create segmented
  426. output, and has semi-automaic reconstruction of segmented output.  There
  427. are two variations of this conversion method; the 'Fast' conversion
  428. algorithm is somewhat faster than the default conversion algorithm, but
  429. (oddly) has a nearly identical expansion rate.
  430.  
  431.      MIME-Encode/MIME-Decode
  432.      -----------------------
  433.  
  434.      SYNOPSIS --          Speed:  Fast
  435.                       Expansion:  Average (20%-30%)
  436.                    Segmentation:  Yes
  437.                  Reconstruction:  Automatic
  438.  
  439.      This conversion method is rapidly becoming more popular than any
  440. other conversion method to date.  It is fast, but has a low expansion
  441. rate.  This conversion method, like UUEncode/UUDecode, has very good
  442. error checking.  It can generate segmented output, and reconstruct
  443. that output with no user intervention.  One of the main advantages to
  444. using this conversion method is that it is supported on nearly every
  445. computer platform; UNIX, Macintosh, IBM, Amiga, Atari, and others.
  446.  
  447.      The Exact Figures
  448.      -----------------
  449.  
  450.      Conversion Utility:  ESS-Code 6.3
  451.                           Electric Storm Software
  452.                           (Shareware)
  453.  
  454.      Archive #1: COMA_210.ZIP
  455.  
  456.                  Orginal      UUE        BTOA       SHIP       MIME
  457.                --------------------------------------------------------
  458.           Size | 256,695  | 355,276  | 321,079  | 321,422  | 343,520  |
  459.           Time | MM.SS.XX | 00.28.57 | 02.00.24 | 01.28.50 | 00.52.38 |
  460.                --------------------------------------------------------
  461.  
  462.      Archive #2: EGEMSOZX.LZH
  463.  
  464.                  Orginal      UUE        BTOA       SHIP       MIME
  465.                --------------------------------------------------------
  466.           Size | 166,715  | 233,505  | 211,131  | 211,235  | 225,937  |
  467.           Time | MM.SS.XX | 00.20.55 | 01.20.59 | 00.59.41 | 00.36.45 |
  468.                --------------------------------------------------------
  469.  
  470.      Archive #3: LPR_UTL3.ZOO
  471.  
  472.                  Orginal      UUE        BTOA       SHIP       MIME
  473.                --------------------------------------------------------
  474.           Size | 117,911  | 165,181  | 149,080  | 149,412  | 159,961  |
  475.           Time | MM.SS.XX | 00.15.11 | 00.58.59 | 00.43.22 | 00.26.52 |
  476.                --------------------------------------------------------
  477.  
  478.      Conclusions
  479.      -----------
  480.  
  481.      Each of the four conversion methods is acceptable, but your specific
  482. situation may indicate which of the four conversion methods is best for
  483. you.  The average user will probably prefer to use UUEncode/UUDecode, since
  484. it is the fastest of the four conversion methods, and offers automatic
  485. segmentation and automatic reconstruction of segmented output.  People who
  486. use UNIX often should probably consider using MIME-Encoding; it is very
  487. common on UNIX systems, and is rapidly replacing all other conversion
  488. methods.  If you are paying for data transfer by the kilobyte, though,
  489. SHIP-Encoding is probably the best solution for you.  It creates extremely
  490. compact output, and offers automatic segmentation and semi-automatic
  491. reconstruction of segmented output.  The error checking is light, but this
  492. is usually not a problem.
  493.  
  494. X. CLOSING
  495. -=-=-=-=-=
  496.  
  497.    I hope that you are pleased with ESS-Code, and decide to continue using
  498. it after you have experimented with it.
  499.  
  500.     I have invested more than a year of my life in the creation of this
  501. program, though, so I _also_ hope that you will seriously consider sending
  502. in the requested donation.
  503.  
  504.     If the Atari is going to remain a viable system in the future, it needs
  505. more Shareware, Donation-Ware, Freeware, and Public Domain applications to
  506. compensate for the lack of commercial products available.  In order to make
  507. programming for the Atari viable, though, the Atari community needs to show
  508. support for the programmers of these applications.
  509.  
  510.                                                    -Michel Forget
  511.                                                     Electric Storm Software
  512.                                                     November 11, 1994
  513.  
  514.