--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/procedure.rst	Sun Jul 21 14:03:55 2013 -0500
@@ -0,0 +1,143 @@
+StdProcedure Class
+==================
+
+The ``StdProcedure`` class encapsulates the encrypting and decrypting
+procedures outlined in :ref:`references-label`. In particular, see
+references [5] and [7]. This class takes care of the high level details of
+inserted various message indicators into an encrypted message, and stripping
+them off during decrypt. These message indicators tell the recipient what key
+list and initial key wheel settings to use when configuring their M-209 for
+decrypt.
+
+.. class:: m209.procedure.StdProcedure([m_209=None[, key_list=None]])
+
+   :param m_209: an instance of a :class:`~m209.converter.M209` can optionally be
+      provided to the procedure object. If ``None`` the procedure object
+      will create one for internal use.
+   :param key_list: an instance of a :class:`~m209.keylist.KeyList` can be
+      provided if known ahead of time. Before an encrypt or decrypt operation
+      can be performed, a key list must be provided. This can be done after
+      object creation via :meth:`set_key_list`. Note that the ``letter_check``
+      attribute of the :class:`~m209.keylist.KeyList` is not accessed by the
+      procedure object, and can be ``None`` if not known.
+
+Before an :meth:`encrypt` operation can be performed, a valid key list must be
+installed, either during procedure object construction, or by the
+:meth:`set_key_list` method.
+
+Decrypt operations are performed in a 3-step process.
+
+#. First, a call to the :meth:`set_decrypt_message` method passes the message
+   to be decrypted to the procedure and establishes the parameters to be used
+   for the actual :meth:`decrypt` operation. These decrypt parameters are
+   returned to the caller.
+
+#. The caller can examine the decrypt parameters to determine which key list
+   must be installed before a successful :meth:`decrypt` operation can be
+   carried out. The caller may call :meth:`get_key_list` to examine the
+   currently installed key list. It is up to the caller to obtain the required
+   key list and install it with :meth:`set_key_list`, if necessary. This is
+   done by ensuring the installed key list indicator matches the
+   ``key_list_ind`` field of the decrypt parameters.
+
+#. Finally :meth:`decrypt` can be called. If the procedure does not have the
+   key list necessary to decrypt the message, a ``ProcedureError`` is
+   raised.
+
+``StdProcedure`` objects have the following methods:
+
+   .. method:: get_key_list()
+
+      :returns: the currently installed :class:`~m209.keylist.KeyList` object
+         or ``None`` if one has not been set
+
+   .. method:: set_key_list(key_list)
+
+      Establishes the :class:`~m209.keylist.KeyList` to be used for future
+      :meth:`encrypt` and :meth:`decrypt` operations
+
+      :param key_list: the new :class:`~m209.keylist.KeyList` to use
+
+   .. method:: encrypt(plaintext[, spaces=True[, ext_msg_ind=None[, sys_ind=None]]])
+      :noindex:
+
+      Encrypts a plaintext message using the installed
+      :class:`~m209.keylist.KeyList` and by following the standard procedure.
+      The encrypted text with the required message indicators are returned as
+      a string.
+
+      :param plaintext: the input string to be encrypted
+      :param spaces: if ``True``, space characters in the input plaintext are
+         allowed and will be replaced with ``Z`` characters before encrypting
+      :param ext_msg_ind: this is the external message indicator, which, if
+         supplied, must be a valid 6-letter string of key wheel settings. If not
+         supplied, one will be generated randomly.
+      :param sys_ind: this is the system indicator, which must be a string of length
+         1 in the range ``A`` - ``Z``, inclusive. If ``None``, one is chosen at random.
+      :returns: the encrypted text with the required message indicators
+      :raises ProcedureError: if the procedure does not have
+         a :class:`~m209.keylist.KeyList` or the input indicators are invalid
+         
+   .. method:: set_decrypt_message(msg)
+
+      Prepare to decrypt the supplied message.
+
+      :param msg: the messsage to decrypt. The message can be grouped into
+         5-letter groups separated by spaces or accepted without spaces.
+      :returns: a ``DecryptParams`` named tuple to the caller (see below)
+      
+      The ``DecryptParams`` named tuple has the following attributes:
+
+      * ``sys_ind`` - the system indicator
+      * ``ext_msg_ind`` - the external message indicator
+      * ``key_list_ind`` - the key list indicator
+      * ``ciphertext`` - the cipher text with all indicators removed
+
+      The caller should ensure the procedure instance has the required
+      :class:`~m209.keylist.KeyList` before calling :meth:`decrypt`. The
+      ``key_list_ind`` attribute of the returned ``DecryptParams`` named tuple
+      identifies the key list that should be installed with
+      :meth:`set_key_list`.
+
+   .. method:: decrypt()
+      :noindex:
+
+      Decrypt the message set in a previous :meth:`set_decrypt_message` call. The
+      resulting plaintext is returned as a string.
+
+      :returns: the decrypted plaintext as a string
+      :raises ProcedureError: if the procedure instance has not been
+         previously configured with the required :class:`~m209.keylist.KeyList`
+         via :meth:`set_key_list`
+
+Here is a simple interactive example of performing an encrypt operation. Here
+we choose a random key list from our key list file, and use random indicators:
+
+>>> from m209.keylist.config import read_key_list
+>>> from m209.procedure import StdProcedure
+>>> 
+>>> key_list = read_key_list('m209keys.cfg')
+>>> proc = StdProcedure(key_list=key_list)
+>>> ct = proc.encrypt('ORDER THE PIZZA AT TWELVE HUNDRED HOURS')
+>>> ct
+'YYGBM ENNHT VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX YYGBM ENNHT'
+>>>
+
+The first and last two groups of this message contain the indicators. Here we
+can see the system indicator was ``Y``, the external message indicator is
+``GBMENN``, and the key list indicator is ``HT``.
+
+An example session for decrypting the above message might look like:
+
+>>> proc = StdProcedure()
+>>> ct = 'YYGBM ENNHT VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX YYGBM ENNHT'
+>>> params = proc.set_decrypt_message(ct)
+>>> params
+DecryptParams(sys_ind='Y', ext_msg_ind='GBMENN', key_list_ind='HT', ciphertext='VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX')
+>>> key_list = read_key_list('m209keys.cfg', params.key_list_ind)
+>>> proc.set_key_list(key_list)
+>>> pt = proc.decrypt()
+>>> pt
+'ORDER THE PI  A AT TWELVE HUNDRED HOURS '
+>>> 
+