Mercurial > public > m209

changeset 64:72e0bda6df40

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Split key list docs into own source file.
author Brian Neal <bgneal@gmail.com>
date Sat, 20 Jul 2013 13:26:25 -0500
parents a56fca44e0ed
children 256b3f3e35e9
files docs/keylist.rst docs/library.rst
diffstat 2 files changed, 179 insertions(+), 175 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/keylist.rst	Sat Jul 20 13:26:25 2013 -0500
@@ -0,0 +1,176 @@
+Key lists
+---------
+
+Key lists are represented as a named tuple called ``KeyList``.
+
+.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)
+
+   As a named tuple, ``KeyList`` has the following attributes:
+
+   * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
+     the range ``AA`` - ``ZZ``
+   * ``lugs`` - a string representing the drum lug settings; see below
+   * ``pin_list`` - a list of six strings which represent key wheel pin
+     settings; see below
+   * ``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 format
+~~~~~~~~~~~~~~~~~~~
+
+Drum lug settings are often conveniently represented as strings consisting of
+at most 27 whitespace-separated pairs of integers separated by dashes. For
+example::
+
+   lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'
+
+Each integer pair must be in the form ``m-n`` where m & n are integers
+between 0 and 6, inclusive. Each integer represents a lug position where
+0 is a neutral position, and 1-6 correspond to key wheel positions. If
+m & n are both non-zero, they cannot be equal.
+
+If a string has less than 27 pairs, it is assumed all remaining bars have both
+lugs in the neutral (0) positions.
+
+Order of the pairs within the string does not matter.
+
+To reduce typing and to aid in readability, an alternate shortcut notation is
+supported::
+
+   lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'
+
+Any pair that is suffixed by ``*k``, where k is a positive integer, means there
+are ``k`` copies of the preceeding lug pair combination. For example, these two
+strings describe identical drum configurations::
+
+   lugs1 = '2-4 2-4 2-4 0-1 0-1'
+   lugs2 = '2-4*3 0-1*2'
+
+Key wheel pin settings
+~~~~~~~~~~~~~~~~~~~~~~
+
+Key wheel pin settings are represented as iterables of letters whose pins are
+slid to the "effective" position (to the right). Letters not appearing in this
+sequence are considered to be in the "ineffective" position (to the left). If
+None or empty, all pins are set to be ineffective.
+
+Examples::
+
+   all_ineffective = ''
+   wheel1 = 'ABDEFHIJMQSUXZ'
+   wheel2 = 'EINPQRTVXZ'
+   wheel3 = 'DEFGIKNOSUX'
+   wheel4 = 'BFGJKRS'
+   wheel5 = 'ABCDFGHIJMPS'
+   wheel6 = 'ADEFHIJKN'
+
+Key list example
+~~~~~~~~~~~~~~~~
+
+An example of using the :class:`~m209.keylist.KeyList` is:
+
+.. code-block:: python
+
+   from m209.keylist import KeyList
+
+   key_list1 = KeyList(
+          indicator='AA',
+          lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6',
+          pin_list=[
+              'FGIKOPRSUVWYZ',
+              'DFGKLMOTUY',
+              'ADEFGIORTUVX',
+              'ACFGHILMRSU',
+              'BCDEFJKLPS',
+              '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
+
--- a/docs/library.rst	Fri Jul 19 20:29:45 2013 -0500
+++ b/docs/library.rst	Sat Jul 20 13:26:25 2013 -0500
@@ -5,179 +5,7 @@
 ``m209`` library as part of their own application. This documentation covers
 the major classes and functions.
 
-Key lists
----------
+.. toctree::
+   :maxdepth: 3
 
-Key lists are represented as a named tuple called ``KeyList``.
-
-.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)
-
-   As a named tuple, ``KeyList`` has the following attributes:
-
-   * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
-     the range ``AA`` - ``ZZ``
-   * ``lugs`` - a string representing the drum lug settings; see below
-   * ``pin_list`` - a list of six strings which represent key wheel pin
-     settings; see below
-   * ``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 format
-~~~~~~~~~~~~~~~~~~~
-
-Drum lug settings are often conveniently represented as strings consisting of
-at most 27 whitespace-separated pairs of integers separated by dashes. For
-example::
-
-   lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'
-
-Each integer pair must be in the form ``m-n`` where m & n are integers
-between 0 and 6, inclusive. Each integer represents a lug position where
-0 is a neutral position, and 1-6 correspond to key wheel positions. If
-m & n are both non-zero, they cannot be equal.
-
-If a string has less than 27 pairs, it is assumed all remaining bars have both
-lugs in the neutral (0) positions.
-
-Order of the pairs within the string does not matter.
-
-To reduce typing and to aid in readability, an alternate shortcut notation is
-supported::
-
-   lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'
-
-Any pair that is suffixed by ``*k``, where k is a positive integer, means there
-are ``k`` copies of the preceeding lug pair combination. For example, these two
-strings describe identical drum configurations::
-
-   lugs1 = '2-4 2-4 2-4 0-1 0-1'
-   lugs2 = '2-4*3 0-1*2'
-
-Key wheel pin settings
-~~~~~~~~~~~~~~~~~~~~~~
-
-Key wheel pin settings are represented as iterables of letters whose pins are
-slid to the "effective" position (to the right). Letters not appearing in this
-sequence are considered to be in the "ineffective" position (to the left). If
-None or empty, all pins are set to be ineffective.
-
-Examples::
-
-   all_ineffective = ''
-   wheel1 = 'ABDEFHIJMQSUXZ'
-   wheel2 = 'EINPQRTVXZ'
-   wheel3 = 'DEFGIKNOSUX'
-   wheel4 = 'BFGJKRS'
-   wheel5 = 'ABCDFGHIJMPS'
-   wheel6 = 'ADEFHIJKN'
-
-Key list example
-~~~~~~~~~~~~~~~~
-
-An example of using the :class:`~m209.keylist.KeyList` is:
-
-.. code-block:: python
-
-   from m209.keylist import KeyList
-
-   key_list1 = KeyList(
-          indicator='AA',
-          lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6',
-          pin_list=[
-              'FGIKOPRSUVWYZ',
-              'DFGKLMOTUY',
-              'ADEFGIORTUVX',
-              'ACFGHILMRSU',
-              'BCDEFJKLPS',
-              '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
-
+   keylist