\documentclass[11pt]{article}

% \renewcommand{\thepage}{}

\input{macros}

\newcommand{\LEX}{\mathit{lex}} \newcommand{\FILE}{\mathit{file}}
\newcommand{\MSG}{\mathit{msg}} \newcommand{\PDM}{\mathit{pdm}}
\newcommand{\REN}{\mathit{ren}} \newcommand{\NAME}{\mathit{name}}
\newcommand{\DISPLAY}{\mathit{display}}
\newcommand{\COLOR}{\mathit{color}} \newcommand{\FONT}{\mathit{font}}
\newcommand{\ATTR}{\mathit{attr}}

\begin{document}
\begin{center}\Large\bf \textsf{Crypto}: A Cryptogram Encoder/Decoder\\
User's Guide
\end{center}

\section{Introduction}

\textsf{Crypto} is a Linux/Unix/Mac OS X program for encoding and
decoding cryptograms.  There are two main versions of the program, in
which the decoding process is structured as a game: one with a
terminal-based user-interface, and one with an X window
system graphical user-interface.  But there is also a version of the
program with an automatic (batch) user-interface.

\section{Usage of Terminal and Graphical Versions}

This section describes how the two main versions of the program can be
used.  A later section describes the usage of the version with the
automatic user-interface.

\textsf{Crypto} makes use of a \emph{lexicon}, $\LEX$, consisting of a
set of \emph{words}, which are nonempty sequences of lowercase
letters.  Initially, \textsf{crypto}'s lexicon is empty.

\textsf{Crypto} has primary and secondary command loops.  In the
terminal-based version of crypto, commands may be abbreviated to
unambiguous prefixes of themselves, and a command's arguments are
listed after the command, separated from themselves and the command by
whitespace characters.  In the graphical version of the program,
commands are selected by clicking on buttons, after which the user is
prompted to enter or select any command arguments.

Upon invocation, \textsf{crypto} enters its \emph{primary command
  loop}.  The primary commands are listed below.  In the
terminal-based version, there is also a \textsf{help} command.
\begin{itemize}
\item The \textsf{quit} command causes \textsf{crypto} to exit with
  status success ($0$).  In the terminal-based version of
  \textsf{crypto}, signaling end-of-file also has this effect.  In the
  graphical version, asking the window manager to request that the
  program exit will also have this effect.

\item The \textsf{lexicon} command takes an argument, $\FILE$, and
  replaces the lexicon, $\LEX$, with the words of $\FILE$.  Words are
  separated by nonempty sequences of whitespace characters.  If the
  file cannot be opened for input, then \textsf{crypto} issues an
  error message and leaves $\LEX$ unchanged.  In the graphical
  version, the user is given the option of editing the filename and
  trying again.  If non-words appear in $\FILE$, then warning messages
  are issued, but those non-words are otherwise ignored.

\item To understand what the \textsf{encode} command does, we need
  some definitions.

  A \emph{message} is a list of \emph{lines}, each of which is a list
  of words.  A \emph{renaming} $\REN$ is a function from lowercase
  letters to lowercase letters with the property that, for all
  lowercase letters $y$, there is a unique lowercase letter $x$ such
  that $\REN(x)=y$.  We \emph{apply} a renaming $\REN$ to a message by
  applying $\REN$ to each letter of each word of each line of the
  message.  A \emph{decoding} of a message $\MSG$ is a message $\MSG'$
  such that
  \begin{itemize}
  \item each word of $\MSG'$ is in the lexicon, $\LEX$;

  \item $\MSG'$ can be formed by applying some renaming to $\MSG$.
  \end{itemize}

  The \textsf{encode} command begins by asking the user to enter a
  message.  The words of the message may be spread over multiple
  lines, and words are separated by whitespace characters.  In the
  terminal-based version, the message is terminated by typing a line
  consisting of the character ``\textsf{.}''  (followed by a newline);
  input of the message may be aborted by typing a line consisting of
  the character ``\textsf{!}''.  In the graphical version, after
  typing the message in a text window, the user has the option of
  confirming hir\footnote{``Sie'' (pronounced ``see'', replacing
  he/she) and ``hir'' (pronouced ``hear'', replacing him/her) are
  gender neutral pronouns.}
  choice of message by clicking the \textsf{OK} button,
  or aborting the \textsf{encode} command by clicking the
  \textsf{Cancel} button.  If any non-words were entered by the user,
  then \textsf{encode} displays an error message.
  In the graphical version, the user is given the option of editing
  the message and trying again, but the terminal version simply
  aborts.

  Let the message $\MSG$ be the list of words that the user entered.
  Next, \textsf{encode} checks whether $\MSG$ is the only decoding of
  itself.  The user is allowed to abort this computation, by typing
  hir interrupt character (usually \emph{CTRL}-\texttt{c}) in the
  terminal-based version, and clicking the \textsf{Cancel} button in
  the graphical version.  During the computation, the user is
  periodically informed of its progress.

  If $\MSG$ is not the only decoding of itself, then an error message
  is issued.  In the graphical version, the user is given the option
  of editing the message and trying again; the terminal version simply
  aborts.  Otherwise, a random renaming is generated and then applied
  to $\MSG$, and the resulting encoded message is displayed ($\MSG$
  will be the only decoding of this message).

\item The \textsf{decode} command begins by reading a message $\MSG$
  from the standard input, as with the \textsf{encode} command.  Next,
  \textsf{decode} checks whether $\MSG$ has a unique decoding (and
  saves this decoding for future use, without telling the user what it
  is, if the answer is ``yes'').  As with the \textsf{encode} command,
  the user is allowed to abort this process.

  If $\MSG$ doesn't have a unique decoding, then an error message is
  issued.  In the graphical version, the user is given the option of
  editing the message and trying again; the terminal version simply
  aborts.  Otherwise, \textsf{crypto} enters its \emph{secondary
    command loop}.  At each iteration of the secondary command loop,
  \textsf{crypto} first displays the current \emph{partially decoded
    message}, $\PDM$, consisting of a sequence of \emph{partially
    decoded lines}, each of which consists of a sequence of
  \emph{partially decoded words}, i.e., nonempty sequences of upper-
  and lowercase letters.  Initially, this partially decoded message is
  $\MSG$.  The uppercase letters represent the renamings already
  performed by the user and program.

  It will always be the case that the current partially decoded
  message, $\PDM$, is \emph{consistent} with the message, $\MSG$,
  being decoded, i.e.,
  \begin{itemize}
  \item $\MSG$ and $\PDM$ have the same shape, and

  \item for all lowercase letters $a$, either
    \begin{itemize}
    \item $a$ appears in $\MSG$ at exactly the same positions as it
      appears in $\PDM$, or

    \item there is an uppercase letter $b$ such that $a$ appears in
      $\MSG$ at exactly the same positions that $b$ appears in $\PDM$.
    \end{itemize}
  \end{itemize}

  Suppose $\PDM$ is a partially decoded message that is consistent
  with the message, $\MSG$, being decoded, and that $\MSG'$ is the
  decoding of $\MSG$.  We say that $\PDM$ is \emph{decodable} iff each
  occurrence of an uppercase letter in $\PDM$ appears in the same
  position in $\MSG'$, but in its lowercase form.  We say that $\PDM$
  is \emph{decoded} iff $\PDM$ is decodable and has no lowercase
  letters.  Given a lowercase letter $a$ that appears in $\PDM$, we
  say that the \emph{decoding} of $a$ is the lowercase letter $b$ that
  appears in $\MSG'$ at the positions corresponding to the positions
  at which $a$ appears in $\PDM$ (i.e., the positions at which $a$
  appears in $\MSG$).

  The secondary commands are listed below.  In the terminal-based
  version, there is also a \textsf{help} command.
  \begin{itemize}
  \item The \textsf{quit} command causes \textsf{crypto} to exit with
    status success ($0$).  Signaling end-of-file (normally
    \emph{CTRL}-\texttt{d}) in the terminal-based version also has
    this effect.  In the graphical version, asking the window manager
    to request that the program exit will also have this effect.

  \item The \textsf{abort} command causes \textsf{crypto} to return to
    its primary command loop.

  \item The \textsf{check} command works as follows.  If the current
    partially decoded message, $\PDM$, is not decodable, then the user
    is informed of this fact.  Otherwise, if $\PDM$ is decoded, then
    the user is informed of this fact, and \textsf{crypto} returns to
    the primary command loop.  Otherwise, the user is told that $\PDM$
    is decodable, but isn't yet decoded.

  \item The \textsf{hint} command works as follows.  If the current
    partially decoded message, $\PDM$, is not decodable, then the user
    is informed of this fact, and no other action is taken.

    Otherwise, if $\PDM$ is decoded, then the user is informed of this
    fact, and \textsf{crypto} returns to the primary command loop.

    Otherwise, \textsf{crypto} selects the lowercase letter $a$ of
    $\PDM$ that appears at least as many times in $\PDM$ as any other
    lowercase letter, and that appears earlier in the alphabet than
    any other lowercase letter with an equal number of occurrences in
    $\PDM$.  \textsf{Crypto} then produces a new partially decoded
    message $\PDM'$, by replacing all occurrences of $a$ in $\PDM$ by
    the uppercase version of the decoding of $a$.  The current
    partially decoded message is then set to $\PDM'$.

  \item The \textsf{replace} command has two arguments $a$ and $b$,
    where $a$ is a lowercase letter of $\PDM$, and $b$ is a lowercase
    letter than doesn't appear in uppercase form in $\PDM$.  It then
    produces a new partially decoded message $\PDM'$, by replacing all
    occurrences of $a$ in $\PDM$ by the uppercase form of $b$.  The
    current partially decoded message is then set to $\PDM'$.

  \item The \textsf{undo} command causes \textsf{crypto} to undo the
    most recent replacement made, or to return to the primary command
    loop, if there is no such replacement.  A given replacement might
    have been carried out by the user using a \textsf{replace}
    command, or might have been carried out by the program using a
    \textsf{hint} command.
  \end{itemize}
\end{itemize}

\section{Options and Customization}

The terminal-based version of \textsf{crypto} takes no command-line
arguments.  If it is given any arguments, it prints a usage message
and exits with status failure ($1$).

The graphical version of \textsf{crypto} can be controlled and
customized using command-line arguments and X resources.

The $\NAME$ (a string of letters, digits, \texttt{-}'s and
\texttt{\_}'s) and $\DISPLAY$ of the program can be customized using
command line arguments:
\begin{center}
  \begin{tabular}{l} \texttt{-name} $\NAME$ \\ \texttt{-display}
    $\DISPLAY$
  \end{tabular}
\end{center} If these aren't used, then $\DISPLAY$ is taken from the
value of the \texttt{DISPLAY} variable in the user environment
(\texttt{:0.0} if it isn't set), and $\NAME$ is the last part
(everything past the last \texttt{/}, if any) of the name by which the
program was invoked (i.e., \texttt{crypto}, unless the shell script is
renamed).

Some program attributes may be customized using the X resource
database:
\begin{center}
  \begin{tabular}{lll} Resource Name & Default & Comment \\ \hline
    \texttt{background} & \texttt{white} & background color of windows \\
    \texttt{foreground} & \texttt{black} & foreground color of windows \\
    \texttt{font} & \texttt{10x20} & font of windows
  \end{tabular}
\end{center} When looking for the value of a resource attribute
$\ATTR$, \textsf{crypto} looks for the value of the resource name
\begin{center} $\NAME$.$\ATTR$
\end{center} For instance, a user could load any of the following
resource specifications into the X server's resource database to set
\textsf{crypto}'s background color to \texttt{grey}:
\begin{center}
  \begin{tabular}{l} \texttt{*background:~grey} \\
    $\NAME$\texttt{*background:~grey} \\
    $\NAME$\texttt{.background:~grey}
  \end{tabular}
\end{center} (Later forms take precedence over earlier ones.)

These attributes may also be specified using command line arguments,
which take precedence over the settings in the X resource database:
\begin{center}
  \begin{tabular}{ll} Option & Attribute \\ \hline
    \texttt{-background} $\COLOR$ & background color \\ \texttt{-bg}
    $\COLOR$ & background
    color \\ \texttt{-foreground} $\COLOR$ & foreground color \\
    \texttt{-fg} $\COLOR$ & foreground color \\ \texttt{-font} $\FONT$
    & font \\ \texttt{-fn} $\FONT$ & font
  \end{tabular}
\end{center} Later command line arguments take precedence over earlier
ones, and command line arguments may be abbreviated to unambiguous
prefixes.

If invalid command line arguments are supplied to \textsf{crypto}, or
if \textsf{crypto} is unable to open the display, then it issues an
error message on the standard error output and exits with status
failure ($1$).

\section{Automatic User-Interface}

The automatic user-interface version of \textsf{crypto} is invoked
with two arguments: a lexicon filename, followed by a mode, which may
be \textsf{encode} or \textsf{decode}.  Modes may be abbreviated to
unambiguous prefixes.  If the arguments are invalid, or if any other
kind of error occurs, this version of crypto exits with status failure
($1$), after printing an appropriate error message on the standard
error output.  Warning and status messages are also printed on the
standard error output.  At any point, the user may terminate
\textsf{crypto} by typing hir interrupt character (usually
\emph{CTRL}-\texttt{c}).

\textsf{Crypto} begins by loading its lexicon from the lexicon file,
issuing warning messages about any non-words appearing in this file.

If the mode is \textsf{encode}, then \textsf{crypto} reads a message
from the standard input, where the message is terminated by
end-of-file.  If the message contains any non-words, then an
appropriate error message is issued, and \textsf{crypto} exits.
Otherwise, \textsf{crypto} checks whether the inputted message is the
only decoding of itself.  The user is periodically informed of the
status of this checking process.  If the inputted message is not the
only decoding of itself, then an error message is issued, and
\textsf{crypto} exits.  Otherwise, a random renaming is generated and
then applied to the message, the resulting encoded message is printed
on the standard output, and \textsf{crypto} exits with status success
($0$).

If the mode is \textsf{decode}, then \textsf{crypto} reads a message
from the standard input, where the message is terminated by
end-of-file.  If the message contains any non-words, then an
appropriate error message is issues, and \textsf{crypto} exits.
Otherwise, \textsf{crypto} checks whether the inputted message has a
unique decoding, saving this unique decoding if the answer is ``yes''.
The user is periodically informed of the status of this checking
process.  If the inputted message doesn't have a unique decoding, then
an error message is issued, and \textsf{crypto} exits.  Otherwise, the
unique decoding is printed on the standard output, and \textsf{crypto}
exits with status success.
\end{document}