--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Mon May 28 16:37:22 2012 -0500
@@ -0,0 +1,159 @@
+=========
+Py-Enigma
+=========
+A historically accurate Enigma Machine library written in Python 3
+------------------------------------------------------------------
+
+:Author: Brian Neal <bgneal@gmail.com>
+:Version: 0.1
+:Date: May 28, 2012
+:Home Page: https://bitbucket.org/bgneal/enigma/
+:License: MIT License (see LICENSE.txt)
+:Support: https://bitbucket.org/bgneal/enigma/issues
+
+
+Overview
+--------
+
+**Py-Enigma** is a Python 3 library for simulating the `Enigma machines`_ used by
+the German armed forces (Wehrmacht) during World War 2. Py-Enigma makes it
+possible to both encrypt and decrypt messages that can be read by, or written
+to, actual Enigma machines used by the German army (Heer), air force
+(Luftwaffe), and navy (Kriegsmarine).
+
+It is my hope that library will be useful to Enigma enthusiasts, historians, and
+students interested in cryptography.
+
+Py-Enigma strives to be Pythonic, easy to use, comes with unit tests, and
+(coming soon) documentation.
+
+
+Scope
+-----
+
+The current scope of Py-Enigma is to simulate Wehrmacht Enigma machines.
+Simulation of other Enigmas, such as the various commercial, railroad, foreign,
+and Abwher (Military Intelligence) models may come later if there is enough
+interest and data available.
+
+Currently, Py-Enigma can simulate the 3 and 4 rotor Enigma machines used by the
+German army, navy, and air force.
+
+
+Quick Example
+-------------
+
+This example shows how the library can be used to decode a message using the
+procedure by employed the German army::
+   
+   from enigma.machine import EnigmaMachine
+
+   # setup machine according to specs from a daily key sheet:
+
+   machine = EnigmaMachine.from_key_sheet(
+          rotors='II IV V',
+          reflector='B',
+          ring_settings=[1, 20, 11],
+          plugboard_settings='AV BS CG DL FU HZ IN KM OW RX')
+
+   # set machine initial starting position
+   machine.set_display('WXC')
+
+   # decrypt the message key
+   msg_key = machine.process_text('KCH')
+
+   # decrypt the cipher text with the unencrypted message key
+   machine.set_display(msg_key)
+
+   ciphertext = 'NIBLFMYMLLUFWCASCSSNVHAZ'
+   plaintext = machine.process_text(ciphertext)
+
+   print(plaintext)
+
+This program prints::
+
+   THEXRUSSIANSXAREXCOMINGX
+
+
+Requirements
+------------
+
+Py-Enigma is written in Python_, specifically Python 3. It has no other
+requirements or dependencies.
+
+
+Project Status
+--------------
+
+This project is very new and is considered alpha software. However at even this
+stage it is possible to encrypt and decrypt authentic Enigma messages.
+
+
+Installation
+------------
+
+After the project gets a bit more mature I will add Py-Enigma to the `Python
+Package Index`_ (PyPI). In the meantime, you may download a tarball or .zip file
+of the latest code using the "get source" link on the `Py-Enigma Bitbucket
+page`_. Alternatively if you use Mercurial_, you can clone the repository with
+the following command::
+
+   $ hg clone https://bitbucket.org/bgneal/enigma
+
+In the very near future I will provide a ``setup.py`` script that will allow you
+to install Py-Enigma. For the time being, just place the ``enigma`` directory on
+your ``PYTHONPATH``.
+
+Documentation
+-------------
+
+I want to use Py-Enigma as a chance to learn Sphinx_, so you can expect to see
+some nicely formatted documentation coming soon. In the meantime, please read
+the source code. I commented it heavily so I could understand how the Enigma
+machine works.
+
+Support
+-------
+
+Support is provided at the `issue tracker`_ at the `Py-Enigma Bitbucket page`_.
+If you have general questions or comments, please feel free to email me (address
+at the top of this file). 
+
+And please, if you use Py-Enigma for anything, even if it is just learning,
+please let me know!
+
+
+Acknowledgements & References
+-----------------------------
+
+This software would not have been possible without the thorough and detailed
+descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
+Machines and Cryptology website`_. In particular, his `Technical Details of the
+Enigma Machine`_ page was a gold mine of information.
+
+Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
+look at his source code, I did use his simulator to check the operation of
+Py-Enigma.
+
+I would also like to recommend the photos and video at Dr. Thomas B. Perera's
+`Enigma Museum`_.
+
+Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
+
+A nice video which shows the basic components and operation of the Enigma
+Machine is on YouTube: `Nadia Baker & Enigma demo`_.
+
+
+.. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
+.. _Python: http://www.python.org
+.. _Python Package Index: http://pypi.python.org/pypi
+.. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma
+.. _Mercurial: http://mercurial.selenic.com/
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _issue tracker: https://bitbucket.org/bgneal/enigma/issues
+.. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
+.. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
+.. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
+.. _Enigma Museum: http://w1tp.com/enigma/
+.. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
+.. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc