Newer
Older
tconfpy / READ-1ST.txt
OVERVIEW
--------

'tconfpy' is a configuration file parser for Python programmers. 
It has two main components:

     tconfpy.py - A pure Python module which implements the
                  configuration file parser and analyzer.

     test-tc.py - A test driver you can use to learn about
                  how 'tconfpy' works as well as for debugging
                  your own configuration files.


Documentation for both of these programs is provided in a number of
common document formats including Unix 'man' format, html, pdf,
postscript, and plain text. 

The file 'example.cfg' is a sample configuration file.  It does
nothing particularly useful, but illustrates most of the features
of the 'tconfpy' configuration language.  You can use it with the
'test-tc.py' driver to play around with the program and get some
feel for what is possible.

'tconfpy' requires Python 2.3 or later be installed on the target
system.


INSTALLATION
------------

There are three ways to install 'tconfpy' depending on your
preferences and type of system.  In each of these installation
methods you must be logged in with root authority (or
Administrator on Win32).


PREPARATION - GETTING AND EXTRACTING THE PACKAGE
------------------------------------------------

For the first two installation methods, you must first download the
latest release from:

   http://www.tundraware.com/Software/tconfpy/

Then unpack the contents by issuing the following command:

   tar -xzvf py-tconfpy-X.XXX.tar.gz   (where X.XXX is the version number)

Win32 users who do not have tar installed on their system can find
a Windows version of the program at:

    http://unxutils.sourceforge.net/



INSTALL METHOD #1 - ALL SYSTEMS (SEMI-AUTOMATED)
------------------------------------------------

Enter the directory created in the unpacking step above.  Then issue
the following command:

    python setup.py install

This will install the 'tconfpy' module and compile it.

You will manually have to copy the 'test-tc.py' program to a directory
somewhere in your executable path.  Similarly, copy the documentation
files to locations appropriate for your system.


INSTALL METHOD #2 - ALL SYSTEMS (MANUAL)
----------------------------------------

Enter the directory created in the unpacking step above.  Then,
manually copy the tconfpy.py file to a directory somewhere in your
PYTHONPATH.  The recommended location for Unix-like systems is:

    .../pythonX.Y/site-packages

For Win32 systems, the recommended location is:

    ...\PythonX.Y\lib\site-packages

Where X.Y is the Python release number.


You can pre-compile the 'tconfpy' module by starting Python interactively
and then issuing the command:

    import tconfpy


Manually copy the 'test-tc.py' program to a directory
somewhere in your executable path.  Copy the documentation
files to locations appropriate for your system.



INSTALL METHOD #3 - FreeBSD ONLY (FULLY-AUTOMATED)
--------------------------------------------------

Make sure you are logged in as root, then:

      cd /usr/ports/devel/py-tconfpy
      make install

This is a fully-automated install that puts both code and
documentation where it belongs.  After this command has completed
you'll find the license agreement and all the documentation (in the
various formats) in:

     /usr/local/share/doc/py-tconfpy

The 'man' pages will have been properly installed so either of these
commands will work:

    man tconfpy
    man test-tc


BUNDLING 'tconfpy' WITH YOUR OWN PROGRAMS
-----------------------------------------

If you write a program that depends on 'tconfpy' you'll need to ensure
that the end-users have it installed on their systems.  There are two
ways to do this:

1) Tell them to download and install the package as described above.
   This is not recommended since you cannot rely on the technical
   ability of end users to do this correctly.

2) Just include 'tconfpy.py' in your program distribution directory.
   This ensures that the module is available to your program
   regardless of what the end-user system has installed.


LICENSE
-------

Please take a moment to read through the 'tconfpy-license.txt' file
provided in the distribution.  There is no fee for non-commercial use
of 'tconfpy'.  However, commercial use requires the payment of a fee
to TundraWare Inc.


'tconfpy' MAILING LIST
----------------------

TundraWare Inc. maintains a mailing list for group discussion, questions,
and comments concerning 'tconfpy'.  To join this list, send email to:

         majordomo@tundraware.com

In the BODY (not the Subject line) of the email put one line of text:


         subscribe tconfpy-users your-email-address-goes-here



QUESTIONS, CONCERNS, BUG REPORTS
--------------------------------

Go to:  tconfpy@tundraware.com