      <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
      >                        Linux-Crypt                        <
      <                             by                            >
      >         Peter Jay Salzman and Rhonda Frances Bailey       >
      <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
          Copyright 1999 Peter Jay Salzman <covenant@dirac.org>   
                    Released under the GNU GPL License


Initial Notes
=============
Throughout this document, ctxt(a) means cipher text 'a' and ptxt(b) means
plain text 'b'.  You'll see mention of 'rulesets' before I explain what
rulesets are.  Hang tight.  I'll explain what rulesets are later.



Purpose
=======
This program provides tools to help you break single substitution ciphers,
(hereafter SSC), also called 'cryptograms' by newspapers and game books.  The
program is for crypto enthusiasts, and will not break the code for you.



Starting the program
====================
If you start the program without command line arguments,

	$ linux-cipher

it asks you to enter the ctxt to work on.  You can then work on the cipher.

A command line argument of -r <filename> or --read <filename> will make
linux-crypt read a file <filename> and assume that it's ctxt to be cracked.
You can then work on the cipher.   I provided sample files named
cryptosample[1-9].  Try:

	$ linux-cipher --read cryptosample1

You can also start linux-crypt with an argument -R <filename> or --restore
<filename> to restore a linux-crypt session that you previously worked on and
saved using the save command.  This allows you to work on a cipher in more
than one sitting without losing your previous work on that cipher.



The User Interface
==================
All commands like `show' and keywords like `vowel' can be completed using the
TAB key, just like the bash shell.  If what you type is not unique, the
program will guess what you mean.  If it's not correct, press TAB again and a
different word will pop up.  For instance, If you type:

	> s<TAB>

You'll see:

	> save

If you type TAB again, you'll see:

	> screen

The screen layout looks something like this:

                ---------------------------------------------
                |                              |            |
                |  KIIL AL LIKSJ LLL S         | A->O 1     |
                |  B    O     I      I         | B          |
                |                              | C          |
                |                              |            |
                |                              |            |
                |      window 1                |  window 2  |
                |                              |            |
                |                              |            |
                ---------------------------------------------
                | > L->F *                                  |
                |                window 3                   |
                ---------------------------------------------

Window 1: Shows the cipher text and your work on cracking it.
Window 2: Shows letter frequencies and letter assignments.
Window 3: Your interaction with linux-crypt (your input).



About Window 2
==============
Window 2 is on the right side of the screen and shows the frequency of ctxt.
You can sort it however you like (see below).  It also shows which ruleset
you're currently working on (see the section on rulesets).  Lastly, it shows
your letter assignments for the current ruleset (like if you set ctxt(F) to
ptxt(O).  You can change what window 2 shows:

   show initial      Show frequencies of only initial letters of words
   show letters      Show frequency of all letters
   show final        Show frequencies of only final letters or words
   sort by ctxt      Sort Window 2 by alphabetized cipher text
   sort by freq      Sort Window 2 by frequency of cipher text
   sort by ptxt      Sort Window 2 by alphabetized plain text
	ruleset n         Show your letter assignments for ruleset n



Assignments
===========
You can assign single letter rules by:

   a b                Assigns ctxt(a) to ptxt(b) in the current ruleset
   a b in 3           Assigns ctxt(a) to ptxt(b) in ruleset 3
   a b in *           Assigns ctxt(a) to ptxt(b) in all rulesets

You can also assign words to words, but you need to use the -> operator
instead of a space.

   abca->that         Assigns a->t, b->h, c->a in current ruleset
   abca->that in 4    Assigns a->t, b->h, c->a in ruleset 4
   abcd->wxyz in *    Assigns a->t, b->h, c->a in all rulesets

The word 'in' in syntactic sugar; you can leave it out.



Rulesets And Copying
====================
There are 9 rulesets numbered 1 through 9.  You can manipulate each ruleset
independently.  Why would you want to do this?  Suppose you see ctxt(YJUY).
It could either be THAT or perhaps HIGH.  You can take your current ruleset
and copy it into another ruleset:

	copy 1 to 2

This copies all your work on ruleset 1 into ruleset 2.  Now you can work on
ruleset 1 assuming ctxt(YJUY) = ptxt(HIGH) and work independently on ruleset
2 assuming ctxt(YJUY) = ptxt(THAT).  If you want to crack the code using
ruleset 1, type

	> ruleset 1

and if you want to crack the code using ruleset 2, type:

	> ruleset 2

Here are the copy command examples:

     copy 2 to 7    Copies ruleset 2 to ruleset 7
     copy 1 to *    Copies ruleset 1 to all other rulesets
	  copy to 3      Copies the current ruleset to ruleset 3

The word 'to' is syntactic sugar; it can be omitted.



Clearing assignments and rulesets
=================================
If you find that a rule, or a whole ruleset, isn't right, you can delete them.

   clear a         clear the assignment for ctxt(a) in current ruleset
   clear a in 5    clear the assignment for ctxt(a) in ruleset 5
   clear a in *    clear the assignment for ctxt(a) in all rulesets
   clear 5         clear ALL assignments in ruleset 5
   clear *         clear ALL assignments in ALL rulesets (start over)



Marking Letters
===============
As you work through a cipher, you may find that although you don't know what
a letter is, it must be a vowel or a consonant.  For instance:

     R PCXJJOP NMO UXXI GD NMO ACXVBP
     I DROPPED THE _OOK ON THE GROUND.

It's not clear whether UXXI is 'COOK' or 'BOOK'.  However, it's clear that
ctxt(U) must be a consonant.  You can give yourself a visual cue by:

   > mark u as consonant

You can also mark vowels.  Of course, you can do this independently for
different rulesets or all rulesets.

   mark U as consonant        Mark ctxt(U) as a consonant in current ruleset
   mark U as consonant in 3   Mark ctxt(U) as a consonant in ruleset 3
   mark U as consonant in *   Mark ctxt(U) as a consonant in all rulesets
   mark S as vowel            Mark ctxt(R) as a vowel in current ruleset
   mark S as vowel in 4       Mark ctxt(U) as a vowel in ruleset 4
   mark S as vowel in *       Mark ctxt(U) as a vowel in all rulesets

Also, sometimes you're confident about a particular rule.  For instance,

    V YVXR GB FXV

Clearly, ctxt(V) is either ptxt(A) or ptxt(I).  It's more likely pxtx(A)
since there are very few words that end in ptxt(I) (look at the last word).
But you have an uneasy feeling about it and would like to indicate that the
ctxt(V) -> ptxt(I) rule is iffy.  You can do:

     > mark V as weak

And linux-crypt will give you a visual cue that the ctxt(V) -> ptxt(I) rule
is not one you're confident about.  Likewise, you can mark a particular rule
as being very likely with:

     > mark J as strong

This is more powerful when you start using different rulesets.  In the
previous example, it's more likely that you dropped a book onto the floor
rather than a cook.  So in ruleset 1 you can mark the ctxt(U)->ptxt(B) rule
as strong and in ruleset 2 you can mark ctxt(U)->ptxt(C) rule as being weak.

Here's the list:

     mark U as strong
     mark U as strong in 3
     mark U as strong in *
     mark U as weak
     mark U as weak in 3
     mark U as weak in *

Lastly, you can unmark anything you've marked:

     unmark Q         Unmark Q in current ruleset
     unmark Q in 4    Unmark Q in ruleset 4
     unmark Q in *    Unmark Q in all rulesets



Saving and Restoring
====================
Suppose you're working on a cipher and it's time to go to bed.   You don't
want to quit and lose all the work you put in, so simply type:

   > save <filename>

The current state of linux-crypt will be saved to the file <filename>.lcs.
When you're ready to resume the cipher, you can start linux crypt and issue:

   > restore <filename>

or start linux-crypt with the --read or -R command line options:

   $ ./linux-crypt --restore <filename>
   $ ./linux-crypt -R <filename>

You don't have to give the .lcs extension; linux-crypt is smart enough to put
.lcs at the end of the filename if you leave it out.



Printing
========
You can print the screen by simply typing:

     > print

It currently doesn't work, and I have no idea why.



Quiting linux-crypt
===================

Surprisingly, if you type quit, linux-crypt will quit.



Command Line Arguments
======================
-g  --gtk                  Use linux-crypt gtk interface.  Not done yet.
-r  --read <filename>      Read <filename>; assume it's ctxt to be cracked.
-V  --version              Print out the version/copyright/license and exit.
-R  --restore <filename>   Restores from filename <filename>
