charma documentation
                           --------------------
Overview:

charma is designed to be used in shell scripts.  It will add or remove
characters from the start of each line in a text file.

This is useful if, for example, you want to include some formatted text in
a message you are writing.  Adding a space to the start of each line will
prevent it from being reflowed.

Similarly, if you have a uudecoded message that got quotes added to it when
saved it is quick and easy to remove the quotes with charma.

In order to make use of charma you must redirect its output, usually to a
file, and then include this in your message or whatever.

charma is most useful to use on the output of other programs but you must
first redirect the output of those programs to a temporary file.

eg. lha vv mcx221.lha > ram:temp
eg. list hd1:c > ram:listing

You could probably use the PIPE: device if you know what you're doing.  :)


Options:

If you type the name of the executable by itself the usage will be
displayed.

It should be the executable followed by an option, either a or s, (or none)
then the input filename.

	(none)	will add a space to the start of each line in the input file
		this is what the program was originally but it's grown  :)

	-a{n}	adds a space to the start of each line in the input file
		if a number is specified then n spaces will be added
		otherwise a single space is added

	-s{n}	removes (strips, subtracts) a character from the start of
		each line in the file. if number specified then n characters
		will be removed otherwise a single char removed


Examples:

These three do the same thing..

 charma text.file > ram:include.me
 charma -a text.file > ram:include.me
 charma -a1 text.file > ram:include.me

These two also do the same thing..

 charma -s text.file > ram:uudecode.me
 charma -s1 text.file > ram:uudecode.me

This one..

 charma -s2 text.file > ram:dummy

will strip the first two characters from each line in text.file, the result
of which will be a file called dummy in the ram disk.

Use the program without redirecting its output to see the results on
screen.  Be ready to hit ctrl-c if your input file is very large.  :)


Problems/bugs:

Lines of text are assumed to be no more than 80 characters long.  If you
need to process longer lines increase LENGTH in charma.h (you will, of
course, need to recompile the program after doing this).

Blank lines cause a few problems when stripping characters.  If the number
of chars to remove is greater than the line length things screw up.  This
is not really a problem as you should never encounter blank lines in normal
use(?).

If you feed it a binary file the program will gladly chew it up for you.  :)


History:

26-Nov-95  Negative numbers no longer accepted

28-Nov-95  Finally got both options working

29-Nov-95  Program renamed to charma and now fully working!


To do (maybe):

Enable fill character to be specified
Check for blank lines
Check if input file is text


Author:

If you would like to contact me for any reason try fidonet.  My internet
account will disappear in a couple of days.  :(

 Erik Austin (fidonet#3:711/431.27)

A message to me at either 3:711/431 or 3:711/431.27 (it really doesn't
matter) will get through fine.

Or you could try the old-fashioned way..

 Erik Austin
 Lot 1 Fig Tree Lane
 Caniaba  NSW  2480
 Australia


Finally:

I honestly don't think that many people will find this program useful.  If
you do then please let me know.  Writing it was good practice anyway.

If charma doesn't do quite what you want have a look at CutAndPaste.lha.
In this archive you'll find implementations of the unix cut and paste
commands.

Charma is public domain.  Do with it what thou wilt.


Disclaimer:

The author shall not be held responsible for any damages incurred through
the use of this program.