AWS.EXE v[3.5] Copyright Paul Burden 1999  DOCUMENTATION
=========================================================
FREEWARE FOR DEVELOPERS AND PEOPLE WHO LIKE DRAWING!!!!
Contact me if you like my AWS(ASCII2) at
   pburden98@yahoo.com

Originally was ASCII2.
========================================================
Contents
[0.1] Introduction/What's this for again?
[0.2] Requirements/Check list of the files
[0.3] What's New!
[1.0] Keyboard controls
[1.1] Main Menu keyboard controls
[2.0] Utilities
[2.1] ASCII Artist
[2.2] Saving your ASCII Map
[2.3] Search
[2.4] ASCII Table
[3.0] What kind of Script can this AWS run?
[3.1] Creating Scripts
[3.2] Running Scripts
[4.0] Any Errors or Bugs?
[4.1] History
[4.2] ASCII ARTIST FILE FORMAT (.AAP) (.AWS)
[4.3] Getting Started with ASCII Artist
           OPENING AN ASCII ARTIST FILE
           CONVERT AN ASCII ARTIST FILE TO TXT FORMAT
           CHOOSING COLORS AND DRAWING TEXT
           SELECTING AREAS, COPY, CHECKING POSITIONS AND PASTING
           ERASING AREAS
           FILLING AREAS
           PASTING TRANSPARENT SELECTION
           FILL OUTSIDE TRANSPARENT AREAS
           FILL INSIDE TRANSPARENT AREAS
           OPEN UP .TXT FILES PROPERLY
           FINISHING UP YOUR PICTURE
           COLORING IN SAVES TIME

[0.1] Introduction/What's this for again?
-----------------------------------------
I Created this software for people who find it hard creating
DOS based text document diagrams.

PROGRAMMERS! THIS IS "DON'T LEVEL HOME WITH OUT IT" SOFTWARE!

Once you are fimilar with the controls, you can make amazing
diagrams for your documentation.

This is a powerful ascii utility that allows you to view
the ASCII code table, you can make scripts to display
certain parts of the table rather than all of it.  There
is an ASCII drawing package added as a bonus.

This program is brillant for people who like to create
DOS based text interface GUI screens and is good for
drawing technical diagrams.

What's this for again?
~~~~~~~~~~~~~~~~~~~~~~
AWS creates quick ascii art for your txt documentation. It
displays them in color for your needs to understand the image.


[0.2] Requirements/Check list of the files
------------------------------------------
For Low Resolution 80x25
        -386 CPU minimum or Above.
        -MS-DOS 6.22 or above
        -2 Button Mouse driver. to use Ascii Artist.
        
For High Resolustion 80x40
        -386 CPU minimum or Above.
        -MS Windows 95 or MS-DOS 6.22
        -2 Button Mouse driver to use Ascii Artist.
        -Vesa driver designed for your graphic card.
        Or
        -Use MS Windows 95 MS PROMPT in Windows FULL SCREEN.

If you don't have a mouse driver installed, AWS will not let you
use Ascii Artist.

When you unzip this into a directory like "c:\AWS" check the following
files are there.

          Files         Description
      ----------------------------------
           AWS.EXE      AWS(Ascii WorkShop Program).
         MOUSE.TPU      This is required so you can use ASCII artist
        SCREEN.TPU      This is required so AWS can hide and show cursors
         GRAPH.TPU      This is required to show the graphical version of ASCII table
             *.BGI      All the .BGI files are Borland Grahics Interface files for
                        different graphic cards.
             *.AWS      The new AWS format that records the size you want save
                        as .TXT
             *.APP      All of the .AAP files are examples of ASCII Artist power.
             *.TXT      What the examples would look like in text format.
        README.TXT      THIS

[0.3] Whats New!
----------------
Version 3.5
-More examples added showing the power of Transparent filling.
-Added more painting abilities with transparent selecting.
       .You can create an ascii code background behind your
        draw image.
       .You can fill a color behind your drawn image.
-Fixed a few grammer problems.

Version 3.3e
-Fixed the alignment of the displaying the files available in open, save
 in Ascii Artist and open script from the Run script.

[1.0] Keyboard controls
======================================================================
Note : This is a case sensitive program so, make sure
the caps lock light is off.

[1.1] Main Menu keyboard controls
---------------------------------
A : ASCII ARTIST
S : Search manually
D : Display ASCII table   < BASIC TEXT MODE
G : Graphic Table hi-res  < Full screen version of ASCII TABLE.
R : Run a script

` : Exit                  < '`' is next to the left side of '1' on a
                            normal keyboard.

TIP : To exit out quickly to DOS, just keep pressing '`'.

[2.0] Utilities
======================================================================
AWS.EXE provides 4 powerful utilities which will help
with finding a particular character.

[2.1] ASCII Artist
------------------
Allows you to create nifty text pictures like this in less
time.

The information display shows you mouse axis XY coordinates.
Above top right is the ASCII tile you going to paint onto
the screen.

To draw press 1 select a Solid Block tile and then position
mouse to where you want to paint the tile and then press
"space bar".  Move the mouse while pressing spacing would be
QUICKER.

       NOTE :
       The Mouse pointer will always draw in;
          D  <--Tile drawn
           X <-- Mouse
       "D" is the tile draw and X is the mouse pointer, when
       placing a tile down, it will always be place in the
       top left side of the mouse pointer.

       This picture Below took me less than 1 minute to make.
       ͻ                                 
         A     SSS   CCC  IIIII IIIII   222                                   
        A A   S     C   C   I     I    2   2                                  
       A   A   SSS  C       I     I       2                                   
       A A A      S C       I     I      2                                    
       A   A  S   S C   C   I     I     2                                     
       A   A   SSS   CCC  IIIII IIIII  22222                                  
       ͼ                                 
        
        -----------------------------------------------------------------
        DRAWING KEYS
        -----------------------------------------------------------------
        TAB           : Changes the palette,
                                1 is SINGLE line characters
                                2 is DOUBLE line characters
                                3 is plain text code art like '\' and ''
                                4 is misc characters like arrows and text.
                                Press 't' to edit the text to be drawn.
        x             : Switch between current ascii tile and delete.        
        n             : Clear screen (Erases what you have done.
        <>            : Goto beginning/end of ASCII codes.
        ,.            : Select an ASCII code, left, right.
        SPACE BAR     : DRAW.
        ENTER         : Selects the pixel's colors and ascii code, pointed
                        by the mouse.
        []            : Changes the Foreground colour palatte.  Future
                        version will store the colours on a disk.
        {}            : Changes the background colour palette.
        ------------------------------------------------------------------
        EIDTING KEYS : CUT,COPY,PASTE, FILL, EREASING KEYS.
        ------------------------------------------------------------------
        !             : Select xy of first point of selection
        "             : Select xy of second point of selection
                     : Copy selection.
        The following start drawing from the position of the mouse.
        $             : Paste selection.
        %             : Paste transparent to background selected.
                        Possible to draw transparent circles and other
                        shapes.
                     : Fill selection with the colors and ascii code
                        selected.
        _             : Set Transparent fill.  Handy for you to set the
                        background color of the image for transparent
                        pasting. Make sure you have selected the ascii
                        code to fill.  See Getting started with
                        filling but press '_' to do transparent fill.
                        The key is located next to the 1 on the left side.
        +             : Fills the image you have drawn with the selected
                        transparent fill and ascii code.
        S             : This will show a preview of the selection size by
                        placing an S at 2 corners of selections
                        diagonally. Press S to get of the marks.
        This is handy to select the area to save as .TXT
        C             : Set's .TXT saving canvas x1, y1 position
        V             : Set's .TXT saving canvas x2, y2 position
        -----------------------------------------------------------------
        OPTION KEYS
        -----------------------------------------------------------------
        g             : Type when GOTO is displayed, xxx where xxx is the
                        desired ASCII code to select. Or you can type
                        a letter.
        t             : To set Draw text string.
                        NOTE : Have MODE4 on and 't' selected from the
                               palette to draw the text.
        n             : New drawing.
        `             : Back to main menu. Your work will still be in
                        memory when you go back to ASCII ARTIST.
                        The work is saved when you quit AWS as
                        BACKUP.AAP and BACKUP.TXT

                        NOTE : if you exit to main menu, you will loose
                        your work.
        
        s             : Save ASCII MAP as a .TXT file or AAP to record colors as well.
        o             : Open a file.  The program will
                        boot you to DOS if you add numbers in the filename.
                        It's the same with Save("s").
        d             : Default drawing character.
        r             : Change resolution.
        v             : Preview full screen of TXT file BLACK and WHITE.
        ------------------------------------------------------------------
        MOUSE DRAWING CONTROLS
        ------------------------------------------------------------------
        The mouse is used to point where to fill, paste, erase, and
        place text.

        Left button   : Draws selected ASCII code using foreground color.
        Right button  : Draws selected ASCII code using background color.

        Left button is able to draw the text when you have;
             MODE4 selected,
             Selected KEY '#' from the palette.  't' will be displayed
             which represents your text.
        NOTE : To draw the letter 't' goto 116 with either MODE 1..3
               selected.

        ------------------------------------------------------------------

        TIP : When pointing to a drawn pixel with colours on it, the ASCII
              artists display what colours you are pointing to.  To select
              it press ";" to select foreground and ":" to select background
              colour.  This is revserved for future version.
        NOTE: When viewing, the pixels you have recently draw moves up one.
              I cannot  find what's wrong but, I have managed to make
              brillant pictures without using the prview.
        
[2.2] Saving your ASCII Map
---------------------------
After drawing, press "s" to save.  A message will say enter in filename.

TIP : Save your as .AAP so you can keep editing your work.  Once you have
      finished with the .AAP you can then SAVE your as .TXT file for
      placing your picture or diagram into documents.

TO SAVE AS A FILE FOR FUTURE EDITING
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enter in for example, "HELLO.AAP" The AAP is required if you're going to
edit the drawing in future.  AAP records the colors used in the drawing.


TO SAVE AS A TEXT FILE
~~~~~~~~~~~~~~~~~~~~~~
Enter in for example, "HELLO.TXT" the TXT 

You will be able to cut and paste these .TXT files from Text Editors, into
your documents.

NOTE : Some Text Editors in Windows does not contain the correct ASCII codes,
       you will have to use EDIT provided by MS-DOS.

[2.3] Search
------------
You can search for codes, by pressing the letters on the keyboard or doing
combinations like, "CRT" AND THEN "1" pressed.

NOTE : '`' is to EXIT, on the SEARCH it displays the code for.

[2.4] ASCII Table
-----------------
The ASCII TABLE, displays all the available ASCII characters and codes
between them.

There are two ways of viewing the table, one is BASIC Text mode and
GRAPHIC MODE to display all the codes on the screen.

NOTE: The graphic table has extra codes such as Arrow keys and F1-F12
      keys.  TEXT MODE Table press SPACE BAR to page through the table.


[3.0] What kind of Script can this AWS run?
======================================================================
Any text file.
NOTE : It's best to save them as .AS2 so you know that the txt file is
made for AWS script compiler.

Look at the .AS2 examples provided

[3.1] Creating Scripts
----------------------
The AWS has a very basic compiler, which is has the following commands
available.
   COMD   WHAT IS IT?      More detailed Description.
   --------------------------------------------------------------------------
   '-'   : End script       Used to end the codes compiled table .
   '{'   : Start of comment Begin a comment command.  These aren't displayed.
   '}'   : End of comment   End a comment command.  These aren't displayed.
   ';'  : Leave a gap      Seperates the code 6 cells between '' and ';'.

   Comment symbols and minus symbols don't get displayed in the table.
  EDIT DEF.AS2 for and example of how to lay out the commands.

3.2 Running scripts
-------------------
At the main Menu;
1) Press "r" in the Main menu to select, "Run a Script".
2) Type in the filename of the script including extension and
   then press return.
A table will appear showing your customized keys.

[4.0] Any Errors or Bugs?
======================================================================
Any bugs you find please email me at pburden98@yahoo.com
This program is fully functional.  But here is a list of bugs that I
do know.
        ASCII ARTIST -With drawing text, if you move the mouse x axis to 1
                      while holding down the left button to draw, the screen
                      creates snow.  Press v to clear the snow.
                     -It cannot load .TXT files properly.  Save it as
                      .AAP if you wish to continue with the file.  Convert
                      it to .TXT when you wish to place it in a document.
                     -Sometimes you see a text cursor moving around the
                      screen fast.
                      Press 'r' twice to correct this problems.

Send an email to comment on it, MAKE SURE you have in the subject, "PJBPASTA".
That I will know that you are commenting on my programs.

[4.1] History
-------------
Version 1.0 1996
-Created a table builder, which displayed all the ASCII code in a table and
 pages.

Version 1.1 1996
-Fixed page numbering problem with Table builder.
-Got rid of the BEEP sound and added friendly words for unknown ASCII
 characters.
-Created an ASCII code finder called Search.

Version 1.2 1997
-Created a graphical version of the table builder.  It display's mose of the
 unknown key code codes like F1 keys.
-Created a built in, basic script compiler for .AS2 files

Version 2.0 1997
-Fixed the alignment problem with a generated table from a script.
-Fixed a number of bugs in the script complier to not generate the script
 language into the table builder.
-Improved the script opener, so it doesn't boot you to DOS.

Version 2.1 1998
-Added drawing capabilities.
-Created a preview viewer
-Created a GUI to display the mouse XY and ASCII Code selected
-Added Save and Open function for .TXT files, ASCII mapping Format.

Version 2.2 1999
-Added Mouse control using MOUSE.TPU
-Fixed a bundle of bugs in the SAVE and OPEN.  OPEN still does not work
 properly still.
-Fixed flicking GUI.

Version 2.3 1999
-Fixed a bunch of bugs with the mouse controller.  Corrected the alignment
 of the mouse pointing tool.
-Tidy up some code.
-Added color mapping Format file .AAP.
-Improved the preview.
-Improved the GUI to be more user friendly.
-Got rid of the cursor. using SCREEN.TPU.

Version 3.3 1999
-It can Save and Open AAP files(Ascii Artist Picture). That includes
 color.
-Improved the Palette control GUI.  It's automatically turned on now.
-It now does backups of your previous work.
-Improved the open routine to check to see if the file exists.
-Rewritten a new mappers for ASCII code and Colors.
-Added save and open cababilities for .AAP
-Added a Help screen, press '\' to activiate.
-Added backup routine to save previous worked on pictures as BACKUP.TXT
 and BACKUP.AAP
-Improved some of the drawing routine on the program itself so, you don't
 see snow alot.

Version 3.3b 1999
-Displayed text cursor when user input is required.
-Made the space bar be able to draw text.
-Added more examples, cartoon.aap, diagram.aap, diagram2.aap
-Added another Mode for plain special text drawing.
-Added a GOTO function, where you find the ASCII code you want
 and then you type it in the GOTO to select it.
-Improved the Open/Save function in ASCII Artist to
 display .AAP and .TXT files.
-Improved the Open function in Run Script to display .AS2 files.
-Made the AWS to make BACUP.AAP and BACKUP.TXT when you exit
 AWS to DOS.
-Centered mouse pointer when entering ASCII Artist.

Version 3.3c 1999
-Improved the fill to fill in text string.
-Improved the Draw mode when drawing string of text.
-Updated the README.TXT
-Changed the stupid title name and fixed some grammer problmes.
-Able to CUT, COPY AND PASTE, and fill selected areas.

Version 3.3d
-Fixed some of the mouse axis restrictions screen size.  So no more oops.
-Improved the speed of the program abit.
-Fixed the bug with the filling with draw text.
-Added a preview for pasting.  Hold down shift and then 's' to
 show the selection.

Version 3.4
-When you press 'g' and a letter it would goto that letter rather you
 having to look up the value, or you can type an ascii code.
-Stopped allowing from opening .TXT files in Ascii Artist
-Allowed you to set the size of the .TXT file. S Will not only show
 the selection you have made but the saving area for .TXT files.
 This is so you don't have to worry about having to trim the .TXT
 file's blank spaces.
-Color coded the selection and save points.
  XY Gray is the selector.
  xy Green is the canvas size for saving to .TXT
-Fixed the Draw Text problem.  It was aligned wrong by 1 pixel.

[4.2] ASCII ARTIST FILE FORMAT (.AAP)
-------------------------------------
It's possible to use this to draw backgrounds and sprites for TEXT based
games.
[PASCAL]
type
    { This is the old .AAP format }
    AAPOldRec = record
           Imap : Array[1..80,1..50] of Char; { ASCII CODE MAP }
           fgmap: Array[1..80,1..50] of integer; { Foreground color map }
           bgmap: Array[1..80,1..50] of integer; { Background color map }
           Cmap : Array[1..80,1..50] of integer; { Reserved for future }

           { The reset are reserved for future development }
           W    : integer;
           H    : integer;
           ver  : real;
    end;
    { This is the .AWS format }
    AAPRec = record
           Imap : Array[1..80,1..50] of Char; { ASCII CODE MAP }
           fgmap: Array[1..80,1..50] of integer; { Foreground color map }
           bgmap: Array[1..80,1..50] of integer; { Background color map }
           Cmap : Array[1..80,1..50] of integer; { Reserved for future }
           { These are used by my program to determine the save area
             for saving to .TXT file }
           x1   : integer;
           y1   : integer;
           x2   : integer;
           y2   : integer;
           { Reserved for future }
           ver  : real;  { This is set to 3.4 }
    end;


var
   AAPFile : File of AAPRec;  { This is for writing to the desired file. }
   AAP     : AAPRec;

[4.3] Getting Started with ASCII Artist
---------------------------------------

At DOS prompt under the AWS directory "C:\AWS" type "AWS" then <RETURN>

press 'a' to enter ASCII artist.

OPENING AN ASCII ARTIST FILE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) press 'o' to open a file.
2) Type in 'cartoon.aap' then <RETURN>
3) Press 'r' to put the display in high resolution.

CONVERT AN ASCII ARTIST FILE TO TXT FORMAT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Press 's' to save a file.
2) Type in 'cartoon.txt' then <RETURN>


CHOOSING COLORS AND DRAWING TEXT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1) Press TAB until MODE is 4.  Text should appear at the top.
2) Press 't' set the text that you want to draw and then
   type in "Are text drawing" <RETURN>
3) Press '#' to select text drawing mode.
4) Press ']' to select the desired foreground color.
5) Hold down SHIFT and then ']' to select background color.
6) Position the mouse in the center of the screen and press the
   Left button on the mouse.

SELECTING AREAS, COPY, CHECKING POSITIONS AND PASTING
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1)Position mouse to where you want to start selecting and then press '!'.
2)Position mouse to where you want to stop selecting and then press '"'.
3)Press '' to copy selection.
4)To check if you're going to place the copied selection in the correct
  position hold down shift and then "S".  The pasting will start on top
  of the "X" next to the mouse down to the "Y" at the bottom right of your
  selection
5)Position mouse to where you want to pasting and then press '$'.

ERASING AREAS
~~~~~~~~~~~~~
1)Position mouse to where you want to start selecting and then press '!'.
2)Position mouse to where you want to stop selecting and then press '"'.
3)Press 'x' to switch to DELETE mode.
4)Position mouse to where you want to start erasing and then press '`'

FILLING AREAS
~~~~~~~~~~~~~
1)Position mouse to where you want to start selecting and then press '!'.
2)Position mouse to where you want to stop selecting and then press '"'.
3)Select the desired background, foreground, and ascii code.
4)Position mouse to where you want to start filling and then press '`'.

PASTING TRANSPARENT SELECTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1)Select a rectangle.
2)Press 'x' to make sure it's null.
3)Select your desired transparent color by changing the background color
  and then position your mouse to where you want to start filling.
  DON'T USE BLACK THAT's DEFAULT FOR NORMAL PASTING
2)Draw your shape, the background color selected should be different to
  the desired transparent color.
2)Copy the area.
3)Make sure you have the background color is the same as your desired
  transparent color and then.
4)Position the mouse to where you want to start pasting the transparent
  image and then press '%' to paste transparent image.

   Have a look at these examples and examine them.
    BACK.AAP,  <This the back of your image
    TRANS.AAP, <This the transparant image.  MARGENTA PURPLE IS GOING TO BE OUT
    BACK2.AAP  <This is the result combined to together.

FILL OUTSIDE TRANSPARENT AREAS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is handy if you want to set you drawn image for transparent
pasting. This fills the background color chosen if the ascii code
selected is the same.

1) Select you your image.
   See "SELECTING AREAS, COPY, CHECKING POSITIONS AND PASTING" but
   DON'T COPY or PASTE.
2) Point to the color that you want to change Press "ENTER"
3) Press '_'
  Have a look at A.AWS, the margenta background can done without
  erasing your image.

NOTE : This won't work until you have selected your area.

FILL INSIDE TRANSPARENT AREAS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After doing the FILL OUTSIDE you can fill the background of your
image with an ascii code.

1) Press g and then type '+' <RETURN>
2) Select foreground.
3) Press '+'.
   Have a look at TRANFIL.AWS

NOTE :This won't work until you have selected your area.

OPEN UP .TXT FILES PROPERLY
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deleting useless blank lines.  Editing lines that goes past the 80 mark
on the x axis.
1)Make sure each of the lines of the text does not have a long sentances.
  For example;
  these words are at the very end of a line ->"The end.                     "
  The blanks between the "" is recorded but you should make sure that line
  does go past the x axis 80 limit.  Make sure it's
  like "The end." <- Blank deleted.
2)If the .TXT still doesn't open better try pressing <RETURN> on the .TXT
  in your editor a few times.  Then try opening it again.

2)Open up that corrected .TXT file.

FINISHING UP YOUR PICTURE
~~~~~~~~~~~~~~~~~~~~~~~~~
1) Place the mouse pointer at the first point to where you want to
   start saving and then press C.
2) Place the mouse pointer at the point to where you want to end
   the saving and then press V.
3) Then press 'S' to check if it's write.  The Green 'x' 'y' is the
   saving in area.
4) Save it as .TXT
When you open your .TXT file you shouldn't need to trim it but get
rid of the ASCII ART sentence.

COLORING IN SAVES TIME
~~~~~~~~~~~~~~~~~~~~~~
With the use of NULL and background colors you can create proffessional
drawings.  In total there is only 16 colors which you use that represents
something.  If you have a vesa driver software then you can create the
ultimate drawings.

Coloring saves time by selecting a color for each of you pics or ascii
code.

     ie    RED   = '/'
           GREEN = '\'
           BLUE  = '-'
then fill it in later with your chosen pics or ascii codes.

1)If you have vesa driver software loaded then press 'r' to change
  from 25x80 to 50x80.
2)Select the whole area for coloring.
3)Sketch you drawing on the ascii artist using the background color that
  you can see.
4)Draw over the parts that you think would be a different ascii code by
  using a different background. You can only have the maximum of
  16 colors.  Some of them you cannot see so you paint that color with
  an ascii code that is not NUL.
5)Point to the first color that you want to fill in, then press 'g' and
  choose an ascii code or use one of the MODE palletes.  Then press
  '+' to fill in.
6)Once you have fill in the colored areas with your desired ascii code.
  your picture will look proffessional.

       For examples look at any of these.

            DAGGER.AWS
             CFACE.AWS
          EVILFACE.AWS
              FACE.AWS
            ODDBOX.AWS

----------------------------------------------------------------------------
End of documentation
Written by Paul Burden. Updated : 19/3/1999


