### barplot-1.0.1 README file

    WHAT IS BARPLOT?
    ----------------
    Barplot is a program that takes as input a scripted language that describes
    progress along various points of a continuum.  The output is scaled to the
    user's specification.  Additionally, barplot can calculate percentage of
    reported progress to an internal default accuracy of 1:10000

    Barplot can output .JPG files, and does so to a file or to stdout.  It is
    possible to have barplot generate these .JPG images "on the fly" with a
    simple .CGI or other Server-side process on a webserver.  We use this
    constantly at Gulf Interstate Engineering to model real-world progress of
    various activities in near real-time.

    This version of barplot is 1.0.00907.00

    The latest version can be found at http:\\www.gie-mis.com\barplot

    WHAT ARE THESE FILES?
    ---------------------
    This distribution consists of the following:

    	README		- What you're reading now.
    	LICENSE		- GNU Copyleft license.
    	src/		- Source code for barplot
     	 barplot.c	- barplot main program
    	 barplot.h	- barplot include file.
    	 bphelp.c	- barplot help file.
    	test.data	- Test data
    	test.jpg	- The results of running test.data :^)
    	Win32/
    	 BARPLOT.EXE	- Statically linked Win32 Binary
    	 make_barplot.bat	(simple make script for Win32 & VC 5.0)
    	Linux-ELF/
    	 barplot	- Statically linked ELF binary for Linux
    	 make_barplot.sh	(simple make script for linux)
    	Web/		- Webserver Stuff
    	 notes		- Some server notes.
    	 image_out.php3	- PHP3 script to show .JPG image inline.
    	Tutorial/
    	 tut_1.dat	- Tutorial data
    	 tut_1.jpg	- Resultant .JPG file

    	----------------------------------------------------------------
    	Binary MD5SUM Information

    	Linux-ELF
    	md5sum barplot
    		82566b1ef37f7d7e11b730e2a1caffd9  barplot

    	Win32
    	md5sum barplot.exe
    		fec6758e5ea9cd90e4e0d1b76e9b2320  barplot.exe

            ----------------------------------------------------------------
    	Note:

    	Barplot links against several other packages, and requires these
    	libraries to compile:

    	ZLIB - Zlib compression library
    	LIBPNG - PNG Library
    	GD - Graphics Draw Library
    	(Note: GD requires the jpeg library to compile)

    	The following URLs may be helpful in finding these packages:
    	zlib 	- http://www.gnu.org/gnulist/production/zlib.html
    	libpng 	- http://www.libpng.org/pub/png/libpng.html
    	gd 	- http://www.boutell.com/gd/index.html
    	libjpeg	- ftp://ftp.uu.net/graphics/jpeg/

    HOW DO I USE IT?
    ----------------
    We're going to explore the language of barplot, and see how we can
    use it for ourselves.  The following script (the typed passages
    after the '>' character) is available as /tutorial/tut_1.dat

    We want to create a file called my_1st.jpg from a file containing
    these commands.  Open your favorite editor, and create a file by
    typing in the commands that follow the '>' character below.  When
    you're finished, you will have a file that is very close to the
    tut_1.dat file, and which you can edit as we go along.

    You can type these commands in directly, if you like, by running
    barplot with the "input from stdin" filename.

    	barplot - my_1st.jpg

    TO BEGIN:

    1) Determine the size of the required output image.

       barplot generates .JPG images, and *you* have complete control over
       the size of the resultant image.  Depending on the end usage, you
       may want a small bar or a large bar.  You decide.

    	We'll choose to have a bar that is 200 x 30 (LxW) pixels.

    2) Do you want each spread (or section of bar, if there are multiple
       sections) to start with a black indicator bar?

       barplots "bar" can consist of one or more spreads, or sections,
       and the start of each section can be indicated on the bar.

    	We'll choose not to do this.  No=0, Yes=1.  So "0"

    3) Do you want to have regular "tic" marks along the length of the
       bar?  If so, how many?

       barplot indicate relative positioning by subdividing the bar into
       sections.  For example, you may wish to divide the output bar into
       quarters, or tenths.

    	We'll choose to divide the bar into fourths.  So "4".

    3b) (Optional) Generate a second image with a percent complete value?

       barplot can optionally generate two seperate .JPG files, a .JPG
       image of the bar, and a .JPG image of the percent complete value.
       This can be helpful in static reports, when you are generating a
       large number of bars at a time, and are pasting them into some
       sort of report.  You can not use this option and get meaningful
       output from stdout.

    Great, you have defined the output bar parameters!  The first line of
    input to barplot will look like this:

    BAR <length> <width> <start marks> <divisions> [percent complete image]

    >BAR 200 30 0 4

    4) Define the scale of the bar.

       barplot needs to know the beginning and end points of your overall
       bar.  If this bar represents mileage, for example, you have to
       define the start and end points of the bar.

    	Our bar represents miles from 0 to 7.5

    >BAR_MIN_MAX 0 7.5

    5) Define the background color of the bar.

       barplot needs to know the background color of the bar.  The
       background color can be any of the seven predefined colors, or
       either of the two user defined colors.  Do step 6 first if you
       wish to use a defined color as the background.

    	Our bar has a white background

    >BGCOLOR WHITE

    6) Define any unique colors you'd like to use.  This is optional.

       barplot gives you the ability to define two colors, apart from the
       predefined colors WHITE,BLUE,RED,BLACK,YELLOW,GREY and GREEN. You
       define these colors by telling barplot what color you want to
       define (COLOR1 or COLOR2) and the Red,Green,Blue values of that
       color.  For example, let's say I want a pink background COLOR1,
       I would issue this command to barplot: COLOR1 255 102 204

       NOTE: If you are going to use a unique color for your
             background, you MUST define that unique color as the first
             defined color.

    	Our bar does not require any unique colors.

    7) Define your first spread.

       Every bar has at least one spread.  A spread can take the length of the
       entire bar, or be just a small part of the bar.  It is often useful to
       know the start and end points of the spread with respect to the bar
       itself.  The spread can, optionally, have a default color for items in
       that spread.

    	Our first spread is from 0 to 3.825 miles, and we want the default
    	color of our items to be blue.

    >SPREAD 0.0000 3.825  BLUE

    8) Define data points for your spread.

       We have four data points to indicate on the spread, three are normal and
       one is, say, in trouble :^)

    >0.0379 0.9193
    >0.9193 2.2034
    >2.2034 4.4750 RED
    >4.4750 5.1250

      Note that the data does not need to fill the entire spread, and can
      represent whatever we want in the bar.

    9) End your spread

       barplot need to know when the data for your spread is finished.  The
       command for this is simple: END

    >END

    Let's define another spread.

    >SPREAD 3.825 7.5 GREEN

    and some data for that spread

    >0.1275 0.3750
    >2.2500 2.7500 YELLOW
    >2.7500 3.3750 RED

    Note how the data points relate to the SPREAD and not to the BAR itself.
    We don't need to have spread start/stop information, though.  We could
    also have written the above four lines as:
    	>SPREAD
    	>3.9525 4.2000 GREEN
    	>6.0750 6.5750 YELLOW
    	>6.5750 7.2000 RED
    and created a bar that looked identical.  Spreads are very useful when
    we get data from the field about a certain area, and the measurements
    are relative to that area only.  We don't have to do the math, barplot
    does it for us!

    End the spread
    >END

    Finally, we want to end our bar and write the file.

    >BAR_END

    Save the file and run it through barplot as follows:

    barplot <filename> my_1st.jpg

    That does it!

    A quick look at the resulting .JPG file should show it to be exactly like
    \tutorial\tut_1.jpg

    What about percent complete information?  Glad you asked :^)

    Because barplot is very flexible in presenting information to the user,
    the definition of "percent complete" can vary from bar to bar.  Is the
    user interested in the amount of BLUE represented in the bar?  Perhaps
    a more telling statistic is how much is NOT reported, or what percent is
    RED (assuming that RED means something on this bar)

    A quick statistic, how much has been reported, is given by:

    barplot <filename> NULL NULL

    This calls barplot with your data file, and tells it to *not* generate
    any .JPG files, but to calculate the representative percentage of reported
    areas.  You should get the following answer on your command line: 68.83

    To get the representative percentage of the BLUE items, do this:

    barplot <filename> NULL NULL blue

    and you get: 28.87

    barplot <filename> NULL NULL white

    gives you the UNREPORTED percentage, which is 31.17

    You can get the percentage of any combination of colors by including them
    on the command line:

    barplot <filename> NULL NULL blue red green yellow

    gives you 68.83, which is identical to leaving out the colors altogether.

    barplot <filename> NULL NULL blue green yellow

    gives you 38.84, the amount of NON-RED, reported items.

    LICENSING
    ---------
    barplot is licensed under the GNU general license, and is free software.
    barplot is linked to libraries that are also released free to the public under
    the GNU license, or similiar licenses.

    The software was developed at Gulf Interstate Engineering by Jim Delahanty.
    If you find it useful, you can drop me a note.  I welcome comments, patches,
    and suggestions for improvements.

    If you're interested in writing man pages, configure scripts or makefiles,
    by all means, be my guest!

    The following header has been prepended to all applicable files in the
    distribution:

    /****************************************************************************\
     barplot - scaled linear progress bar .JPG generator.
     Copyright (c) 2000  James Delahanty - Gulf Interstate Engineering

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

     Send comments, suggestions for improvements, any code you'd like to share
     or just random thoughts to jimd@gie.com

     or, if you'd like, you can mail them to:
    	 Jim Delahanty,
    	 c/o Gulf Interstate Engineering
    	 Suite 600
    	 1700 West Loop South
    	 Houston, TX  77027

    \****************************************************************************/