Cadubi - Creative ASCII Drawing Utility By Ian

IMPORTANT -- Cadubi is no longer being maintained. 1.3 is a release
for licensing and documentation fixes. See:

    http://langworth.com/CadubiProject

---------------------------------------------------------------------
SYNOPSIS & AUTHOR
---------------------------------------------------------------------

CADUBI is an application written in Perl that allows you to draw
text-based images that are viewable on typical unix-based consoles.
Usually the applications that emulate these consoles support various
text modes, such as background and foreground colors, bold, and
inverse. This text art, commonly called "ASCII art," is used in
various places such as online BBSes, email and login prompts.

---------------------------------------------------------------------
REQUIREMENTS
---------------------------------------------------------------------

   * Perl 5.002 or later
       --> http://www.perl.com/CPAN/src/latest.tar.gz
       
   * Term::ReadKey module
       --> http://www.perl.com/CPAN/CPAN.html

---------------------------------------------------------------------
CONFIGURING CADUBI
---------------------------------------------------------------------

Setting up CADUBI is quite easy. If you haven't already installed
Term::ReadKey, do. The URL for Term::ReadKey is above under
"REQUIREMENTS." To learn how to install a module, see Perl FAQ 8,
under "How do I install a CPAN module?"

Next, open up the 'cadubi' and 'CADUBI.pl' files. If you're perl
executable is, for some reason, not located at /usr/bin/perl, change
the first line of each file appropriately. Save your changes.

Look in the file called 'cadubi' and examine the settings under
"SETUP." Anything catch your eye? Save changes if you made any.

Finally, make sure that the file called 'cadubi' is executable, and
put a link to it in your /usr/bin, or wherever you keep your public
executables.

---------------------------------------------------------------------
USING CADUBI
---------------------------------------------------------------------

CADUBI has a 'pen' which describes the current mode. Properties of
the pen are the painting character, foreground color, background
color, bold, inverse, and blink. Whenever you paint or use the text
mode, the characters drawn on the screen will have the properties of
the pen. The current mode of the pen is shown at the bottom of the
console and is what will be drawn on screen when you paint.

Move around the cursor with the 'i', 'j', 'k' and 'l' keys. Holding
down shift and typing these keys will move the cursor five spaces
instead of one. Pressing return/enter will move the cursor down one
line and all the way to the left of the console.

To paint the current pen on the screen, press the space bar. To
delete a character, press the delete/backspace key. You'll notice
that editing is much like common text editors, such as pico or joe.
You can also delete with the '`' key, which makes moving & painting
(right hand) and erasing (left hand) much easier.

The pen character is the character that is drawn when you paint using
the space bar. To change the character, press 'p' and then the
character you would like it to be.

To set the foreground or background colors for the cursor, press 'f'
for foreground or 'b' for background, and then a corresponding color
    code. The color codes are case-insensitive and are listed below:

     0 or N   Normal (standard text)
     1 or W   White
     2 or R   Red
     3 or G   Green
     4 or Y   Yellow
     5 or B   Blue
     6 or M   Magenta
     7 or C   Cyan
     8 or K   Black
     
If you can't remember the codes above, you can always hit control-'h'
to view the Quick Help which will display a summary of all the keys,
color codes and examples of how they look.

Typically, foreground text colors are the same as background colors,
unless the text is bold. If the text is bold, foreground colors are
usually lighter than the background color, making text easier to read
when the text has the same foreground and background color. Refer to
the Quick Help (control-'h') to see what the colors look like on your
console.

Bold and inverse are two widely-supported modes. Bold is toggled with
the 'g' key, and inverse is toggled with the 'v' key. Blink, though
regarded as highly annoying, can be toggled with by pressing
shift-'w'.

Text mode is an extremely useful feature. Once in the text mode you
can type as if you were using a normal text editor, and all the
characters drawn onscreen will use the same mode as the pen. To enter
text mode, press the 't' key. To exit, press escape.

To exit the CADUBI application, press control-'x'. Quick help can be
accessed by pressing control-'h'. In case it is needed, pressing
control-'w' will refresh the entire screen by redrawing each
character.

---------------------------------------------------------------------
READING AND WRITING FILES
---------------------------------------------------------------------

To read a file and use it with CADUBI, type control-'r'. To write
a file, type control-'o'. You will be prompted for a filename.

When CADUBI reads a file, it will only read as much that will fit in
the workspace (the area of the console minus the bottom row [status
bar]). To gain more workspace, see the '-s' operator in 'COMMAND LINE
USAGE' below.

CADUBI optimizes its output files to display properly and take up as
little space as possible. All CADUBI output can be viewed with the
'cat' utility.

---------------------------------------------------------------------
USAGE
---------------------------------------------------------------------

Usage: cadubi [OPTIONS] [FILE]

Available options:
  -h, --help              what you're looking at now
  -m, --mute              turn off beeping
  -s, --size [W] [H]      sets the size of the console for use with
                          CADUBI, where W is number of columns and H
                          is number of rows.
  -v, --version           show CADUBI version

Example:
  Will make the cadubi workspace 160 columns wide, 48 rows high,
  disable beeping, and open the file 'bacon.txt':
  
       cadubi --mute --size 160 48 bacon.txt

  Will display the version of CADUBI, copyright and author:

       cadubi -v
       
---------------------------------------------------------------------
NOTES
---------------------------------------------------------------------

Whenever you are prompted to type in information, such as the name of
a file to read/write to, you can hit escape to cancel. You can also
hit escape to get out of text mode.

When using the '-s' or '--size' command line option, make sure your
console actually _is_ that size or the text won't wrap properly and
CADUBI will look funny.

The Quick Help actually displays the file 'CADUBI.help' that is in
the same folder as 'CADUBI.pl'. That's all. Feel free to do something
creative, just remember that when you redistribute CADUBI (that is,
if you somehow feel compelled to do so), be sure to include all the
original files.

---------------------------------------------------------------------
AUTHOR
---------------------------------------------------------------------

Ian Langworth - http://langworth.com/CadubiProject

---------------------------------------------------------------------
LICENSE
---------------------------------------------------------------------

Cadubi is copyright 1999-2004 Ian Langworth

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

See: http://www.perl.com/perl/misc/Artistic.html
