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