Ŀ
  ߲ ߲   ߲                                               
    ߲    ߲  ߲ ܲ   Copyright March 1994 by Mark D. Rejhon.  


Welcome to PACKANSI, the ANSI file optimizer by Mark D. Rejhon.
This is the included README file.


PURPOSE:
~~~~~~~
    PACKANSI is a program that optmizes an ANSI file.  In simpler terms,
    you get a smaller ANSI file which is faster-displaying over the modem!

    Most of the time, the improvement will be slight at about 5%.
    In some cases, the improvement can be as much as 50%!

    PACKANSI is capable of compressing both animated ANSI's and linearly
    displayed ANSI's (ANSI's that display from top to bottom)
    PACKANSI is best not used by the faint of heart, though.


OTHER PROGRAMS:
~~~~~~~~~~~~~~
    A useful supplement to PACKANSI is to use Mark Rejhon's freeware ATYPE
    version 1.03 which display ANSI and AVATAR files without the use of an
    ANSI driver.  (and it supports more ANSI codes than most ANSI drivers
    anyway)

    The package name is ATYPE103.ZIP, although the filename may vary.


HOW TO USE:
~~~~~~~~~~
    The use of this utility is straightforward if you are used to
    using DOS utilities and programs, like most ANSI artists are.
    For quick start, type "PACKANSI /?" for a command-line help screen.

    Output files of PACKANSI are given the suffix ".NEW", and doesn't
    overwrite the original ANSI files.  Note that most of the time,
    PACKANSI will produce files that are smaller, or the same size. but in
    some cases, it can actually increase the size of the file! So you need
    to experiment a bit with command line options, Keep a backup of your
    original ANSI files, just in case though! (and read the disclaimer at
    the end of this file first)

    Recommended command for animated ANSI's: PACKANSI <file>
    Recommended command for linear ANSI's: PACKANSI <file> /S /L

    COMMAND LINE OPTIONS:

    Syntax.........PACKANSI <filespec> [/L [/S]] [/O] [/Wxx] [/P] [/?]

            <filespec> is not optional, while all of the other
            command line switches in brackets []'s are optional.

    <filespec>.....The file or files you want to optimize.

            You specify the filename, or a wildcarded filename
            of the files, that you want to optimize.

            The output files of PACKANSI is the same filename, but
            with a different suffix of ".NEW".  If a file with the
            ".NEW" suffix already exists, PACKANSI reports you of
            this, and goes on to the next file.

            If PACKANSI is unable to open any file, it will abort
            with an error message in most cases.

    /?......Display a brief command-line help screen.

    /O......Overwrite existing output files.

            This causes PACKANSI to merrily overwrite any existing
            output files with the ".NEW" extension.

            If you have any original ANSI files with the ".NEW"
            extension, be VERY careful of this option!!!  It is
            probably the best to rename that ANSI file to a
            different suffix.

    /Wxx....This specifies the width of the ANSI files.

            By default, this is 80 columns, the width of the screen.
            Most of the time you should omit the option.  In rare
            cases where the ANSI file is designed to work on a screen
            of a specific width other than 80 columns, you should
            specify the width.

            For example, for a 132 column ANSI file, you should
            include /W132 with the PACKANSI command.

    /S......Compress spaces and other invisible characters.
            Must be used with the /L option below.

            This compresses long strings of spaces in ANSI files
            to a single cursor movement code that jumps over the
            spaces.  Spaces include the space, ASCII 0 and ASCII 255,
            as well as invisible characters that are exactly the
            same color as the background color.

            This is mainly good for linearly-displaying ANSI files,
            since it must be used with the /L option.  Also, many animated
            ANSI files take advantage of such spaces to overwrite existing
            data on the screen.  The use of /S on some animated ANSI files
            may produce occasional successful results, but is not
            recommended.

    /L......Activate optimizations beneficial on most linear ANSI files.

            This option causes PACKANSI to do extra optimizations that can
            make the output file size even smaller.  This option can be
            used with or without the /S option.  Use both /S and /L first
            for most likely best results on linear ANSI files you want to
            optimize.

            This option is not recommended for animated ANSI files because
            most actually increase in size, and probably also affects the
            way they look on the screen.

            TECHNICAL DETAILS ABOUT THIS OPTION (you can skip):

            Also, the /L option resets the background color to black,
            after each line of ANSI codes, to prevent background color
            bleeding problems during scrolling especially in ANSI files
            that were converted from GIF or another format.

            For those REAL ANSI artists who actually view ANSI files in a
            TEXT EDITOR and edit ANSI codes manually..... The /L option is
            a great boon because it organizes messy ANSI files to a neat
            arrangement of one line of ANSI codes per line of ANSI
            display!

            If you use the QEdit editor, it is a good idea to configure
            "Remove trailing blanks from edited lines" to "N" to prevent
            damage to the ANSI file in rare situations.  Tabs in ANSI
            files should also be avoided to prevent incompatibility
            between terminals and some text editors.
            
    /P......Preserve ANSI codes that aren't recognized by PACKANSI.

            By default, ANSI codes not recognized by PACKANSI will be
            stripped, for compatibility reasons.  If PACKANSI had problems
            with your ANSI files, and you know that the ANSI files
            contains unusual ANSI codes, try specifying the /P option to
            see if it works.  (If it doesn't then avoid using PACKANSI on
            that ANSI file)

            TECHNICAL NOTE:  Read the "How it works" section for the list
            of ANSI codes that is supported by PACKANSI.


HOW IT WORKS, TECHNICALLY:
~~~~~~~~~~~~~~~~~~~~~~~~~
    Don't read this if you're bored of technical stuff! :-)

    PACKANSI "compresses" the ANSI file by making intelligent
    substitutions of the cursor-locate and color codes, as well as
    optionally replacing redundant spaces and invisible characters with a
    single cursor-locate code.

    It takes a fair bit of knowledge about ANSI codes to understand how
    PACKANSI works, but if you arean ANSI artist yourself, you might have
    some insight into ANSI codes already.

    In simple terms, PACKANSI reads the ANSI file in very small chunks at
    a time. Everytime a cursor movement (which include carriage enters and
    linefeeds) or a color code comes up, it is remembered until the next
    "visible" or "printable" character comes up.  When this happens, it
    outputs an optimized version of the cursor locate and color code to
    the output file (which can be empty if there was detected to be no
    actual change in cursor position or color!), along with the character,
    as well as subsequent characters up to the next ANSI code (or
    invisible character).

    This also eliminates a lot of redundancy because algorithms in
    PACKANSI computes compact ANSI codes that change the current color to
    the new color, or move the cursor from its current position to a new
    cursor position.  It can even replace certain ANSI cursor locate codes
    with carriage returns and linefeeds if they are detected to be more
    efficient!

    LIST OF SUPPORTED CODES BY PACKANSI:

        PACKANSI recognizes these ANSI codes, including a subset of the
        VT102 terminal emulation.  "Esc" represents ASCII 27, and "#"
        represents an ASCII digit.

        PACKANSI recognizes these rarely used ANSI codes:

          Code          Description
          ----------    -------------------------------------------
          Esc[#@        Insert spaces
          Esc[#P        Delete characters
          Esc[#L        Insert blank lines
          Esc[#M        Delete lines
          EscM          Reverse linefeed
          EscD          Linefeed substitute
          EscE          Next line (Simulates CR LF)
          Esc[#;#r      Set scrolling zone window

        PACKANSI recognizes these commonly used ANSI codes:

          Code          Description
          ----------    -------------------------------------------
          Esc[#A        Cursor move up
          Esc[#B        Cursor move down
          Esc[#C        Cursor move right
          Esc[#D        Cursor move left
          Esc[#;#H      Cursor set position
          Esc[#;#f      Cursor set position
          Esc[#J        Clear screen (or part of it)
          Esc[#K        Clear line (or part of it)
          Esc[#;..;#m   Set attributes (color, bold, blink)
          Esc[s         Save cursor position
          Esc[u         Restore cursor position

        PACKANSI recognizes these control codes:

          Code          Description
          ----------    -------------------------------------------
          ASCII 7       Bell
          ASCII 8       Backspace
          ASCII 9       Tab (treated like a cursor move code)
          ASCII 10      LF (treated almost like a cursor move code)
          ASCII 12      Clear screen
          ASCII 13      CR (treated like a cursor move code)
          ASCII 27      Prefix for all ANSI codes.

        Any other control code is assumed to be printable.


DISCLAIMER:
~~~~~~~~~~
    First of all, the disclaimer.  This software was programmed for fun in
    spare time because of inefficiently encoded ANSI files, especially
    those that were made by some ANSI editor software like TheDraw. I can
    say that it works great on almost all ANSI files that I tested it on,
    but I won't guarantee that this program will do anything except take
    disk space on your system.

    This program is freeware.  You may distribute and use for free, in its
    unmodified form, as long as no charge is made on this program, except
    for any distribution charge that may apply.



SOURCE CODE:
~~~~~~~~~~~~
    This package comes with source code for the QuickBASIC 4.5 compiler.
    The library SUPP.LIB does not have source code available, so you will
    need to invoke this command line to load the SUPP library.

         QB.EXE /LSUPP PACKANSI.BAS

    This package will not work with the lite QBASIC included with MSDOS 5
    and MSDOS 6, the QuickBASIC 4.5 compiler is required.



CONTACT:
~~~~~~~
    [Updated June 1996] The programmer can be contacted at:

    Email:   marky@ottawa.com
    Website: http://www.marky.com/

