--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Mon Feb 17 20:28:57 2014 -0600
@@ -0,0 +1,171 @@
+======
+Purple
+======
+
+A historically accurate PURPLE simulator written in Python 3
+------------------------------------------------------------
+
+:Author: Brian Neal <bgneal@gmail.com>
+:Version: 0.1
+:Date: February 17, 2013
+:Home Page: https://bitbucket.org/bgneal/purple/
+:License: MIT License (see LICENSE.txt)
+:Documentation: This file
+:Support: https://bitbucket.org/bgneal/purple/issues
+
+``Purple`` is a Python library and command-line utility for simulating the `PURPLE
+Machine`_, a cipher machine used by the Japanese Foreign Office before and
+during the Second World War. PURPLE was the code name given to machine by U.S.
+cryptanalysts. The Japanese called the machine 97-shiki ōbun inji-ki (System 97
+Printing Machine for European Characters), and Angōki B-kata (Type B Cipher
+Machine). The machine was used for secure diplomatic communications and was an
+electromechanical stepping-switch device.
+
+This project is a Python 3 library and command-line utility for encrypting and
+decrypting text by simulating the operation of an actual PURPLE machine.
+
+
+Requirements
+############
+
+``Purple`` was written in Python_ 3, specifically 3.3.2, and has no other external
+dependencies.
+
+
+Installation
+############
+
+``Purple`` is available on the `Python Package Index`_ (PyPI). There are
+a number of ways to install to ``Purple``, detailed below. The author
+recommends you install into a virtualenv_. Setting up a virtualenv is not hard,
+but describing it is out of scope for this document. Please see the virtualenv_
+documentation for more information.
+
+You can install it using pip_::
+
+   $ pip install purple                # install
+   $ pip install --upgrade purple      # upgrade
+
+You can also visit the the `Purple Bitbucket page`_ and download an archive
+file of the latest code. Alternatively, if you use Mercurial_, you can clone
+the repository with the following command::
+
+   $ hg clone https://bitbucket.org/bgneal/purple
+
+If you did not use pip_ (you downloaded or cloned the code yourself), you can
+install with::
+
+   $ cd where-you-extracted-purple
+   $ python setup.py install
+
+To run the unit tests::
+
+   $ cd where-you-extracted-purple
+   $ python -m unittest discover
+
+
+Command-line Usage
+##################
+
+To get help on the command-line ``Purple`` utility, execute the ``purple``
+command with the ``--help`` option::
+
+   $ purple --help
+   usage: purple [-h] [-e] [-d] [-f] [-s SWITCHES] [-a ALPHABET] [-t TEXT]
+                 [-i FILE] [-g N] [-w N]
+
+   PURPLE cipher machine simulator
+
+   optional arguments:
+     -h, --help            show this help message and exit
+     -e, --encrypt         perform an encrypt operation
+     -d, --decrypt         perform a decrypt operation
+     -f, --filter          filter plaintext and provide useful substitutions
+     -s SWITCHES, --switches SWITCHES
+                           switch settings, e.g. 9-1,24,6-23
+     -a ALPHABET, --alphabet ALPHABET
+                           plugboard wiring string, 26-letters; e.g.
+                           AEIOUYBCDFGHJKLMNPQRSTVWXZ
+     -t TEXT, --text TEXT  input text to encrypt/decrypt
+     -i FILE, --input FILE
+                           file to read input text from, - for stdin
+     -g N, --group N       if non-zero, group output in N-letter groups [default:
+                           5]
+     -w N, --width N       wrap output text to N letters; a value of 0 means do
+                           not wrap [default: 70]
+
+   Supply either -e or -d, but not both, to perform either an encrypt or decrypt.
+   If the -s option is not supplied, the value of the environment variable
+   PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of
+   the environment variable PURPLE97_ALPHABET will be used. Input text is
+   supplied either by the -t or by the -f options, but not both.
+
+(TODO: Text goes here explaining the switches and alphabet settings)
+
+If you are going to be working with the same initial switch settings and
+plugboard alphabet it may be more convenient to specify them as environment
+variables instead of repeatedly using the command-line arguments ``-s`` and
+``-a``.  The examples below assume these statements have been executed::
+
+   $ export PURPLE97_SWITCHES=9-1,24,6-23
+   $ export PURPLE97_ALPHABET=NOKTYUXEQLHBRMPDICJASVWGZF
+
+The ``purple`` command operates in two modes, either encrypt (specified with
+``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can
+be specified on the command-line with the ``-t`` or ``--text`` option, or
+a read from a file (``-i`` or ``--input``).
+
+When encrypting text, the ``purple`` machine only accepts the letters A-Z, but
+also allows for "garble" letters to be indicated by using the ``-`` (dash)
+character. This means all punctuation and spaces must be either be omitted or
+input via some other convention. The ``-f`` or ``--filter`` flag, when present,
+relaxes these restrictions a bit. When this flag is on, all lowercase letters
+will be converted to uppercase, digits will be converted to words (e.g.
+5 becomes FIVE), and all other characters will be ignored.
+
+A simple encrypt example using the ``-f`` flag is given below::
+
+   $ purple -e -t "The PURPLE machine is now online" -f
+   OGIVT SIAAH MWMHT VIBYY JUOJF UE
+
+By default ``purple`` prints the output in 5-letter groups. This can be
+disabled or customized with the ``--group`` and ``--width`` options.
+
+To decrypt this message::
+
+   $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE"
+   THEPU RPLEM ACHIN EISNO WONLI NE
+
+Note that spaces are ignored on input. Again the output is produced in 5-letter
+groups and wrapped at 70 letters per line. Here is the output again with
+grouping disabled::
+
+   $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0
+   THEPURPLEMACHINEISNOWONLINE
+
+Of course you can use file redirection to capture output in a file::
+
+   $ purple -e -t "The PURPLE machine is now online" -f > secret.txt
+   $ purple -d -i secret.txt
+   THEPU RPLEM ACHIN EISNO WONLI NE
+
+
+Library Usage
+#############
+
+
+Support
+#######
+
+
+References
+##########
+
+
+.. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine)
+.. _Python: http://www.python.org
+.. _Python Package Index: http://pypi.python.org/pypi/m209/
+.. _virtualenv: http://www.virtualenv.org/
+.. _pip: http://www.pip-installer.org
+.. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/
+.. _Mercurial: http://mercurial.selenic.com/