$Id: README,v 1.7 2008/01/02 19:37:40 syzdek Exp $

Roman Numeral Conversion API
Copyright (C) 2007, 2008 David M. Syzdek

Contents
========
   I. Introduction
  II. Reporting Problems
 III. Roman Numerals
  IV. Obtaining the Source
   V. Compiling and Installing
  VI. Programming Examples


I. Introduction
---------------

This package was developed to provide an easy method of including Roman Numeral
values in the output of programs written in C/C++.  There are example programs
that demonstrates the use of the functions included in the library.  The
utilities `romannum' and `romandate' show possible uses for the functions as
well as provide silly tools to play with.


II. Reporting Problems
----------------------

Please report problems regarding this package using the SourceForge Tracker.
The Tracker page for this project is available here:

	
	http://sourceforge.net/tracker/?group_id=211070
	

If the Tracker is too confusing, time consuming, detailed, arbitrary, ridiculous,
chaotic, organized, purlple, "I don't speak your crazy moon-language."; send the
request to:

	
	syzdek@users.sourceforge.net
	


III. Roman Numerals
-------------------

A simple chart is included below showing the values for Roman Numeral symbols. This
chart is also included in the `romannum' command and in the roman.7 man page.

   Roman Numerals:
    Symbol    Value              Name
      N     0  (zero)          (nullae) *
      I     1  (one)           (unus)
      V     5  (five)          (quinque)
      X    10  (ten)           (decem)
      L    50  (fifty)         (quinquaginta)
      C   100  (one hundred)   (centum)
      D   500  (five hundred)  (quingenti)
      M  1000  (one thousand)  (mille)
   
   * Non-standard Roman numeral used by St. Bede.

A bar placed across the top of a Roman Numeral implies that the value shoud be
multiplied by 1000.  However, this utility does not use this notation since
there is not an acceptable manner of representing this notation using ASCII
characters.

More information on Roman Numerals can be found on the following web sites:

	http://en.wikipedia.org/wiki/Roman_numerals
	http://www.novaroma.org/via_romana/numbers.html


IV. Obtaining the Source
------------------------

This project is hosted on SourceForge.  The source code can be downloaded from the
following web page:

	
	https://sourceforge.net/projects/roman/
	

The latest source code can be retieved from CVS using the following commands:

	CVSROOT=:pserver:anonymous@roman.cvs.sourceforge.net:/cvsroot/roman
	export CVSROOT
	cvs -z3 checkout -P roman

This should create a directory called `roman' which contains the latest
development source.


V. Compiling and Installing
---------------------------

This project uses GNU Autoconf, GNU Automake, and GNU Libtool in order to ease
porting source across multiple platforms.  As of this writing the source was 
known to compile for the following platforms:

	Apple OS X 10.5.1
	Slackware Linux 11.0
	Windows 2000 (using MinGW32)

The easist way to compile the source on a Unix platform is to run the following:

	gzip -cd roman-x.x.x.tar.gz | tar -xvf -
	cd roman-x.x.x
	./configure
	make
	make install

For more information on building and installing using configure, please read the
INSTALL file.

The Windows binaries that are released on SourceForge are cross-compiled on
OS X using MinGW32.  How to cross-compile is beyond the scope of this document
however the following should work if your environment is set up correctly:

	gzip -cd roman-x.x.x.tar.gz | tar -xvf -
	cd roman-x.x.x
	./configure --prefix=/tmp/roman-mingw32 --disable-shared \
	            --bindir=/tmp/roman-mingw32 --host=i386-mingw32
	make
	make install

Removing the `--disable-shared' option will create a DLL library which must
be in the same directory as the executables that use it. I am a Unix developer,
so I am not familiar with the development tools available on Windows.  If you
have questions about developing on Windows, please see the MSDN.  If there is
an error in how I generate Windows libraries, please let me know and I will
try to correct it in the next release.


VI. Programming Examples
------------------------

The first example demonstrates generating Roman Numeral strings from an integer:

	/* compile with gcc -lroman -o test1 test1.c */
	#include <stdio.h>
	#include <roman.h>

	int main(void);

	int main(void)
	{
	   const char * roman;
	   roman = int2roman(3132);
	   if (!(roman))
	   {
	      perror("int2roman()");
	      return(1);
	   };
	   printf("Roman Numeral: %s\n", roman);
	   return(0);
	}

If the above program is run on a Posix system, the output should be similiar
to the following:

	syzdek@tacntock$ gcc -lroman -o test1 test1.c
	syzdek@tacntock$ ./test1 
	Roman Numeral: MMMCXXXII
	syzdek@tacntock$

The second example demonstrates converting a Roman Numeral string into an integer:

	/* compile with gcc -lroman -o test2 test2.c */
	#include <stdio.h>
	#include <roman.h>

	int main(void);

	int main(void)
	{
	   int num;
	   num = roman2int("MMMCXXXII");
	   if (num < 0)
	   {
	      perror("roman2int()");
	      return(1);
	   };
	   printf("Number: %i\n", num);
	   return(0);
	}


If the above program is run on a Posix system, the output should be similiar
to the following:

	syzdek@tacntock$ gcc -lroman -o test2 test2.c
	syzdek@tacntock$ ./test2 
	Number: 3132
	syzdek@tacntock$

Additional examples are included in the `examples' directory.


=============================================================================

Please enjoy this project.

Sincerely,
David M. Syzdek