home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / assembler / thesource / volume4 / utilities / s-text.lha / S-Text.doc < prev    next >
Encoding:
Text File  |  1993-02-15  |  6.1 KB  |  149 lines
  1.    
  2.  
  3.                              S - TEXT  V1.1 
  4.  
  5.                           Self-Displaying Text
  6.  
  7.    Normally to read a text you call "Type <File>" at a CLI - whereupon the
  8.  start of it promptly scrolls off the screen - or you can dig out a text
  9.  reader or editor and load the file into it (the new WorkBench Ed is handy). 
  10.  Calling from Workbench the icon for the text file must raise a suitable 
  11.  reader.  No problem in any of this.
  12.  
  13.    But would it not be better to do away with the separate reader, use 
  14.  compressed texts to save space and have the text start up an internal
  15.  reader and display itself.  
  16.  
  17.    Programmes such as T3E and Txt2Exe go part of
  18.  the way, they can be executed from a CLI without using the command 'type',
  19.  however they write directly into the CLI, there is no way of moving around
  20.  in the text, they can't be started from WorkBench, they have never heard
  21.  of compression; in effect the only gain is that the word 'type' does not
  22.  have to be used.  I suspect that such programs are not used very often.  
  23.  
  24.    So let us draw up a spec for a self-displaying text program:
  25.  
  26.     It must be possible to produce the executable text without re-compiling.
  27.  
  28.     It must display text in a reader having, as a minimum, the commands Page
  29.     Up, Page Down, Line Up, Line Down, Start of file, End of file, Quit.
  30.  
  31.     The executable must be capable of being run from both WorkBench & CLI.
  32.  
  33.     It must be possible to recover the original file unblemished.
  34.  
  35.     Compression should be used where appropriate.
  36.  
  37.     Size of the executable file must never be more than 1000 bytes greater
  38.     than the bare uncompressed text, and should normally be a lot smaller.
  39.  
  40.     Escape codes for text color and style must be handled properly.   
  41.  
  42.    Hence S-Text.
  43.  
  44.    S-Text first adds a display header (994 bytes).  Then it checks whether
  45.   the text is compressed (P-Compress format); if so adds a decompression
  46.   header (1000 bytes) as well,  otherwise the file is compressed - a check
  47.   is made as to whether the gain is greater than the size of the
  48.   decompression header - if not the uncompressed version is used.
  49.   Decompression header is added where it is needed.
  50.  
  51.    The original can be recovered by executing (displaying) the file and
  52.   saving it with the S key.  
  53.  
  54.    Small text files under about 2K will not be compressed and will end up
  55.   some 1K larger.  Larger files will be compressed and if the original size
  56.   was more than about 4K the executable will be smaller than the original
  57.   in spite of the added headers.
  58.  
  59.    Fine - but are there any real advantages over simple compressed text +
  60.   text reader?
  61.  
  62.     Disk space:   With good decompressing readers at upwards of 15K you
  63.         must have a fair number of texts on the disk before you beat the
  64.         S-Text files, and since the P-Compress compression used is a lot
  65.         more efficient than the commonly used PowerPacker, you may never
  66.         catch up!
  67.  
  68.     Convenience:  No fiddling around with icon Default Tools.
  69.    
  70.     Portability:   The text can be transferred anywhere without worrying
  71.         over whether a suitable reader is available, or changing icons.
  72.  
  73.     Speed: At a CLI it is a lot quicker to type "S-Text.doc" than for
  74.         example "dh0:c/MuchMore S-text.doc" 
  75.  
  76.    Perhaps the real point is that it gives you a file that can be moved 
  77.   from disk to disk without having to even consider whether suitable
  78.   decompressing readers are on them, and can distribute without having to
  79.   consider whether recipients have any means of decompressing.
  80.  
  81.    The obvious disadvantage lies in the limited facilities offered by the
  82.   header.  It would be nice to include scrolling and search, but these
  83.   would cause an unaceptable blowout in size.
  84.  
  85.    This version has a couple of limitations :
  86.  
  87.     A 'RAW' window is used which comes with a WINDOWSIZING gadget that
  88.   can't be removed under V1.3. This limits the number of characters in a
  89.   line (width is limited to your screen size - normally 640) to 77 chars.
  90.   Beyond this the line will word-wrap.
  91.  
  92.    Escape code characters in a line, although handled correctly, are
  93.   counted in the line's length and may cause early word-wrapping.
  94.     
  95.  
  96.                            INSTRUCTIONS 
  97.  
  98.    Very very simple:
  99.  
  100.    To create the text executable open a CLI and type:
  101.  
  102.                  S-Text <textfile> <outfile>
  103.  
  104.    The <outfile> must be different from <textfile>, you cannot directly
  105.   replace texts with their executable offspring.  It is a good idea to add
  106.   an extension (.se) to the outfile to distinguish it from a primitive
  107.   non- executable text.
  108.  
  109.    For Workbench use provide the executable with a TOOL type icon.
  110.  
  111.    To view the text treat the file just like any other executable:
  112.  
  113.      At a CLI type the name, use RUN if you wish.
  114.      From Workbench double-click the icon.
  115.  
  116.    When called an S-Text file will open a window matching your current screen
  117.   and display the first page of text (to avoid lines scrolling off it assumes
  118.   that a LACEd screen will be using a font of the size of Topaz11). To move
  119.   around in the text use the named keys of the numeric pad, or (for machines
  120.   like the Amiga 600, which has no numeric pad,) the ordinary number keys:
  121.  
  122.        1  End of text                2  Line down
  123.        3  Page down                  7  Start of text
  124.        8  Line up                    9  Page up
  125.  
  126.      To save the text in its original uncompressed form press S or s. A file
  127.   "Txt" will be opened in RAM.  This can be viewed in any normal reader and
  128.   may be useful where additional facilities such as `search' are needed.
  129.  
  130.      To quit press Esc.   
  131.  
  132.      
  133.           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  134.  
  135.     S-Text is Freeware.  It may be copied and distributed freely and used
  136.    without charge for non-commercial purposes.  Authority for commercial
  137.    use should be obtained from the author below.
  138.  
  139.     No responsibility can be accepted for any loss occasioned by use of the
  140.    programme.
  141.  
  142.      Comments, suggestions, bug-reports all welcome.
  143.  
  144.    Chas A. Wyndham,
  145.    1265 Canning Mills Road,
  146.    Roleystone,
  147.    WA 6111.
  148.    Australia 
  149.