Mercurial > public > m209

annotate docs/index.rst @ 70:753974fc7619

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Minor tweaks to install instructions. Added a note on how to run the tests.
author Brian Neal <bgneal@gmail.com>
date Sun, 21 Jul 2013 14:30:12 -0500
parents 2173ac4c2d9b
children 854c5d361011
rev   line source
bgneal@51 1 .. m209 documentation master file, created by
bgneal@51 2 sphinx-quickstart on Thu Jul 4 18:12:07 2013.
bgneal@51 3 You can adapt this file completely to your liking, but it should at least
bgneal@51 4 contain the root `toctree` directive.
bgneal@51 5
bgneal@51 6 Welcome to m209's documentation!
bgneal@51 7 ================================
bgneal@51 8
bgneal@52 9 :Author: Brian Neal <bgneal@gmail.com>
bgneal@52 10 :Version: |release|
bgneal@52 11 :Date: |today|
bgneal@52 12 :Home Page: https://bitbucket.org/bgneal/m209/
bgneal@52 13 :License: MIT License (see LICENSE.txt)
bgneal@52 14 :Documentation: http://m209.readthedocs.org/
bgneal@52 15 :Support: https://bitbucket.org/bgneal/m209/issues
bgneal@52 16
bgneal@52 17 Introduction
bgneal@52 18 ------------
bgneal@52 19
bgneal@57 20 The `M-209`_ is a mechanical cipher machine used by the US military during
bgneal@57 21 World War II and up to the Korean War. The M-209 is also known as the CSP-1500
bgneal@57 22 by the US Navy. The M-209 is an example of a Hagelin device, a family of
bgneal@57 23 mechanical cipher machines created by Swedish inventor `Boris Hagelin`_, where
bgneal@57 24 it is known as the C-38.
bgneal@57 25
bgneal@52 26 ``m209`` is a complete `M-209`_ simulation library and command-line application
bgneal@52 27 written in Python 3. ``m209`` is historically accurate, meaning that it can
bgneal@52 28 exchange messages with an actual M-209 cipher machine.
bgneal@52 29
bgneal@52 30 It is hoped that this library will be useful to M-209 enthusiasts, historians,
bgneal@52 31 and students interested in cryptography.
bgneal@52 32
bgneal@52 33 ``m209`` strives to be Pythonic, easy to use, and comes with both unit tests
bgneal@52 34 and documentation. ``m209`` is a library for building applications for
bgneal@52 35 encrypting and decrypting M-209 messages. ``m209`` also ships with a simple
bgneal@52 36 command-line application that can encrypt & decrypt messages for scripting and
bgneal@52 37 experimentation.
bgneal@52 38
bgneal@56 39 Documentation
bgneal@56 40 -------------
bgneal@52 41
bgneal@56 42 Contents:
bgneal@54 43
bgneal@56 44 .. toctree::
bgneal@69 45 :maxdepth: 2
bgneal@62 46
bgneal@56 47 tutorial
bgneal@57 48 commandline
bgneal@57 49 library
bgneal@55 50
bgneal@55 51
bgneal@52 52 Requirements
bgneal@52 53 ------------
bgneal@52 54
bgneal@52 55 ``m209`` is written in Python_, specifically Python 3.3. It has no other
bgneal@52 56 requirements or dependencies.
bgneal@52 57
bgneal@52 58 Installation
bgneal@52 59 ------------
bgneal@52 60
bgneal@70 61 ``m209`` is available on the `Python Package Index`_ (PyPI).
bgneal@70 62
bgneal@70 63 You can install it using pip_::
bgneal@52 64
bgneal@52 65 $ pip install m209 # install
bgneal@52 66 $ pip install --upgrade m209 # upgrade
bgneal@52 67
bgneal@55 68 You may also download a tarball or .zip file of the latest code by visiting the
bgneal@70 69 `m209 Bitbucket page`_. Alternatively if you use Mercurial_, you can clone the
bgneal@70 70 repository with the following command::
bgneal@52 71
bgneal@52 72 $ hg clone https://bitbucket.org/bgneal/m209
bgneal@52 73
bgneal@70 74 If you did not use pip (you downloaded or cloned the code yourself), you can
bgneal@70 75 install with::
bgneal@52 76
bgneal@70 77 $ cd where-you-extracted-m209
bgneal@52 78 $ python setup.py install
bgneal@52 79
bgneal@70 80 To run the unit tests::
bgneal@70 81
bgneal@70 82 $ cd where-you-extracted-m209
bgneal@70 83 $ python -m unittest discover -b
bgneal@70 84
bgneal@52 85 Support & Source
bgneal@52 86 ----------------
bgneal@52 87
bgneal@52 88 All support takes place at the `m209 Bitbucket page`_. Please enter any
bgneal@52 89 feature requests or bugs into the `issue tracker`_.
bgneal@52 90
bgneal@68 91 .. _references-label:
bgneal@68 92
bgneal@57 93 References
bgneal@57 94 ----------
bgneal@57 95
bgneal@57 96 All of the resources listed below were useful to me in the creation of the
bgneal@57 97 ``m209`` library. In particular, I want to thank Mark J. Blair for his detailed
bgneal@57 98 explanations of the M-209's operation and procedures. The official training
bgneal@57 99 film was also highly instructive.
bgneal@57 100
bgneal@57 101 #. `M-209 at Wikipedia <http://en.wikipedia.org/wiki/M-209>`_
bgneal@57 102 #. `Mark J. Blair's Converter M-209-B <http://www.nf6x.net/2009/02/converter-m-209-b/>`_
bgneal@57 103 #. `1942 M-209 Manual <http://maritime.org/tech/csp1500inst.htm>`_
bgneal@59 104 #. `1944 M-209 Manual <http://www.ilord.com/m209manual.html>`_
bgneal@57 105 #. `Official M-209 Training Film <http://www.youtube.com/playlist?list=PLCPgncK_sTnEny2-uoTV-1_GC72zo-vKq>`_ - This is a 4 video YouTube playlist of an actual 1940's era US War Department training film. Demonstrates the M-209 and operational procedures. Very interesting!
bgneal@57 106 #. `Transcript of Training Film <http://www.ilord.com/m209-training.html>`_ -
bgneal@57 107 Transcript of the above film.
bgneal@57 108 #. `Mark J. Blair's M-209 Cipher Machine Group <http://www.nf6x.net/groups/m209group/>`_ -
bgneal@57 109 Informal club for M-209 enthusiasts. Includes detailed explanations of the
bgneal@57 110 device and how to use it. Very useful.
bgneal@57 111 #. `Dirk Rijmenants' M-209 Simulator <http://users.telenet.be/d.rijmenants/en/m209sim.htm>`_ -
bgneal@57 112 Graphical M-209 simulator
bgneal@57 113 #. `Mark J. Blair's Hagelin project suite at GitHub <https://github.com/NF6X/hagelin>`_
bgneal@57 114 - M-209 simulator written in C++
bgneal@66 115 #. `Jean-François Bouchaudy's Crypto Pages <http://www.jfbouch.fr/crypto/>`_
bgneal@57 116 - Includes another Python-based M-209 simulator and a M-209 challenge. In French.
bgneal@57 117 #. `The C-38 / M-209 Cipher Machine <http://hem.passagen.se/tan01/c38.html>`_
bgneal@57 118 - Another M-209 page. This one has useful info on creating key lists and a C-38 simulator written in C.
bgneal@57 119
bgneal@51 120 Indices and tables
bgneal@51 121 ==================
bgneal@51 122
bgneal@51 123 * :ref:`genindex`
bgneal@51 124 * :ref:`modindex`
bgneal@51 125 * :ref:`search`
bgneal@51 126
bgneal@52 127
bgneal@52 128 .. _M-209: http://en.wikipedia.org/wiki/M-209
bgneal@57 129 .. _Boris Hagelin: http://en.wikipedia.org/wiki/Boris_Hagelin
bgneal@52 130 .. _Python: http://www.python.org
bgneal@52 131 .. _Python Package Index: http://pypi.python.org/pypi/m209/
bgneal@52 132 .. _m209 Bitbucket page: https://bitbucket.org/bgneal/m209
bgneal@52 133 .. _pip: http://www.pip-installer.org
bgneal@52 134 .. _Mercurial: http://mercurial.selenic.com/
bgneal@52 135 .. _issue tracker: https://bitbucket.org/bgneal/m209/issues