# HG changeset patch
# User Brian Neal <bgneal@gmail.com>
# Date 1374283785 18000
# Node ID a56fca44e0ed09b9c795a789383e7906eda12b3a
# Parent  42d7e5410dbd0afc9d65b51f8ea732c473c3612c
Added more key list docs.

diff -r 42d7e5410dbd -r a56fca44e0ed docs/library.rst
--- a/docs/library.rst	Thu Jul 18 21:09:36 2013 -0500
+++ b/docs/library.rst	Fri Jul 19 20:29:45 2013 -0500
@@ -22,8 +22,8 @@
    * ``letter_check`` - a string representing the letter check used to verify
      operator settings; if unknown this can be ``None`` or an empty string
    
-Lug settings string format
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Lug settings format
+~~~~~~~~~~~~~~~~~~~
 
 Drum lug settings are often conveniently represented as strings consisting of
 at most 27 whitespace-separated pairs of integers separated by dashes. For
@@ -71,10 +71,10 @@
    wheel5 = 'ABCDFGHIJMPS'
    wheel6 = 'ADEFHIJKN'
 
-Key List Example
+Key list example
 ~~~~~~~~~~~~~~~~
 
-An example of using the :py:class:`m209.keylist.KeyList` is:
+An example of using the :class:`~m209.keylist.KeyList` is:
 
 .. code-block:: python
 
@@ -92,3 +92,92 @@
               'EFGHIJLMNP'
           ],
           letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')
+
+Key list file I/O
+~~~~~~~~~~~~~~~~~
+
+Key lists can be stored in files in config file ("INI") style format using
+functions found in the ``m209.keylist.config`` module.
+
+.. function:: m209.keylist.config.read_key_list(fname[, indicator=None])
+
+    Reads key list information from the file given by ``fname``.
+
+    Searches the config file for the key list with the given indicator. If
+    found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if
+    not found.
+
+    If ``indicator`` is ``None``, a key list is chosen from the file at random.
+
+.. function:: m209.keylist.config.write(fname, key_lists)
+
+    Writes the key lists to the file named ``fname`` in config file format.
+
+    ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects.
+
+Key list file format
+++++++++++++++++++++
+
+An example key list file in config file format is presented below. The label
+for each section of the file is the key list indicator.
+
+::
+
+   [CA]
+   lugs = 0-5*5 0-6*2 1-0*7 1-2 1-3*3 1-6 2-0 3-0*3 3-5*2 3-6 4-5
+   wheel1 = ABCDFGHJLOPRVWYZ
+   wheel2 = BCDEIJKPQSUVX
+   wheel3 = ACDGLNQRSTUV
+   wheel4 = FGHIJNQRSU
+   wheel5 = DEIJOQS
+   wheel6 = BCDEILMNOP
+   check = RGPRO RTYOO TWYSN GXTPF PNWIH P
+
+   [CD]
+   lugs = 0-4*4 0-5 1-0*7 1-2*2 1-4*3 2-0*2 2-4*2 2-6*2 3-0*4
+   wheel1 = AEFHIKMPQRSUVZ
+   wheel2 = ABFGHINORSUVZ
+   wheel3 = BDEHJKLMNOQRSU
+   wheel4 = CDEFGHJKMRU
+   wheel5 = FGHIJOQS
+   wheel6 = EGIJKLP
+   check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H
+
+Generating key lists
+~~~~~~~~~~~~~~~~~~~~
+
+The ``m209`` library contains a function to pseudo-randomly generate a key list
+that is based on the procedure described in the 1944 M-209 manual.
+
+.. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS])
+
+   The only required parameter is ``indicator``, the two-letter indicator for
+   the key list.
+
+   If successful, a :class:`~m209.keylist.KeyList` object is returned.
+
+   If a :class:`~m209.keylist.KeyList` could not be generated
+   a ``KeyListGenError`` exception is raised.
+
+   The algorithm is heuristic-based and makes random decisions based upon the
+   1944 procedure. The actual procedure is loosely specified in the manual, and
+   much is left up to the human operator. It is possible that the algorithm
+   cannot find a solution to meet the key list requirements specified in the
+   manual, in which case it simply tries again up to some set of limits. These
+   limits can be tweaked using the optional parameters to the algorithm. If no
+   solution is found after exhausting the limits, a ``KeyListGenError`` is
+   raised.
+
+   The optional parameters are:
+
+   * ``lug_selection`` - a list of 6 integers used to drive the lug settings
+     portion of the algorithm. If not supplied, a list of 6 integers is chosen
+     from data tables that appear in the 1944 manual. For more information on
+     the requirements for these integers, see the manual.
+
+   * ``max_lug_attempts`` - the maximum number of times to attempt to create
+     lug settings before giving up
+
+   * ``max_pin_attempts`` - the maximum number of times to attempt to generate
+     key wheel pin settings before giving up
+