Add AUTHORS (generated by update-copyright.py) to .gitignore.

[igor.git] / README

diff --git a/README b/README
index 6b73aae5e5ab9158a00674c12995ee3c9e525751..0166c1eb808aaaad2d4926ef9e5988be6cadb1c1 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,13 @@
-igor: Interface for reading binary IGOR files.
+====
+Igor
+====
 
-Read Igor Binary Waves (.ibw) and ... written by WaveMetrics' IGOR
-package.
+:Authors: W. Trevor King <wking@tremily.us>;
+          Paul Kienzle <paul.kienzle@nist.gov>
+:License: GNU General Public License, version 3+
+
+Python parsers for Igor Binary Waves (.ibw) and Packed Experiment
+(.pxp) files written by WaveMetrics' IGOR Pro software.
 
 Installation
 ============
@@ -9,6 +15,9 @@ Installation
 Packages
 --------
 
+If `igor` already exists in your package manager's repository, you
+should install `igor` in the usual way.
+
 Gentoo
 ~~~~~~
 
@@ -22,7 +31,7 @@ overlay`_.  Install with::
 Dependencies
 ------------
 
-If you're installing by hand or packaging calibcant for another
+If you're installing by hand or packaging `igor` for another
 distribution, you'll need the following dependencies:
 
 ===========  =================  ============================
@@ -45,12 +54,30 @@ standard::
 
     $ python setup.py install
 
+You can also automate this installation with pip_.
+
+    $ pip install igor
 
 Usage
 =====
 
-See the module docstrings for simple examples.
+See the docstrings and unit tests for examples using the Python API.
+The package also installs to scripts, ``igorbinarywave.py`` and
+``igorpackedexperiment.py`` which can be used to dump files to stdout.
+For details on their usage, use the ``--help`` option.  For example::
+
+  $ igorbinarywave.py --help
+
+For users transitioning from igor.py_, there's a compatibility module
+exposing the old interface.  Just change::
+
+  import igor
+
+to::
 
+  import igor.igorpy as igor
+
+in your calling code.
 
 Testing
 =======
@@ -59,21 +86,41 @@ Run internal unit tests with::
 
     $ nosetests --with-doctest --doctest-tests igor test
 
+The data in the ``test/data`` directory is in the Git repository, but
+it is not bundled with the source code.  If you want the test data,
+you'll have to clone the Git repository or download a snapshot.
 
 Licence
 =======
 
 This project is distributed under the `GNU General Public License
-Version 3`_ or greater.
+Version 3`_ or greater, see the ``COPYING`` file distributed with the
+project for details.
 
+Maintenance
+===========
 
-Author
-======
+Maintainer
+----------
 
 W. Trevor King
 wking@tremily.us
 Copyright 2008-2012
 
+Release procedure
+-----------------
+
+When a new version of the package is ready, increment __version__
+in ``igor/__init__.py`` and run update-copyright_::
+
+    $ update-copyright.py
+
+to update the copyright blurbs.  Then run::
+
+    $ python setup.py sdist upload
+
+This will place a new version on PyPI.
+
 
 .. _layman: http://layman.sourceforge.net/
 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
@@ -83,5 +130,8 @@ Copyright 2008-2012
 .. _Matplotlib: http://matplotlib.sourceforge.net/
 .. _Nose: http://somethingaboutorange.com/mrl/projects/nose/
 .. _Git: http://git-scm.com/
-.. _homepage: http://blog.tremily.us/posts/calibcant/
+.. _homepage: http://blog.tremily.us/posts/igor/
+.. _pip: http://pypi.python.org/pypi/pip
+.. _igor.py: http://pypi.python.org/pypi/igor.py
 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.txt
+.. _update-copyright: http://blog.tremily.us/posts/update-copyright/