+\subsection{Java API for Ship Descriptions}
+
+The FleetTwo toolchain includes a utility for parsing a {\tt .ship}
+file into a {\tt ShipDescription}. There is one {\tt ShipDescription}
+for each {\it kind} of ship. This distinction will become important
+later, when we introduce classes to represent {\it instances} of ship
+types.
+
+\begin{verbatim}
+/** a description of a ship */
+public class ShipDescription implements Iterable<DockDescription> {
+ public String getName();
+ public Iterable<ConstantDescription> getConstantDescriptions();
+ public Iterable<DockDescription> getDockDescriptions();
+}
+
+/** a description of a valve */
+public class DockDescription {
+ public String getName();
+ public boolean isInbox();
+ public boolean isOutbox();
+ public DockDescription getShortcut();
+}
+
+/** a constant declared by a ship */
+public class ConstantDescription {
+ public final long setbits;
+ public final long clearbits;
+ public final boolean signExtend;
+ public final int numberOffset;
+ public final int numberWidth;
+}
+\end{verbatim}
+
+
+\pagebreak
+\section{Instructions}
+\subsection{Fleet Assembly Language}
+
+The Fleet Assembly language is designed to be a human-readable
+depiction of the bits which comprise a Fleet program.
+
+\subsubsection{Formal Grammar}
+
+The formal syntax is given below. The metagrammar used is that of the
+Scannerless Boolean Parser \cite{sbp}.
+
+\verbatiminput{fleet.g}
+
+\subsubsection{Translation To Machine Code}
+
+Please refer to \cite{ArchMan} for the details of the Fleet
+instruction encoding.
+
+As shown in the grammar above, the start symbol for the grammar ({\tt
+ s}) yields a {\tt Program} surrounded by optional whitespace. A
+program is a sequence of {\tt Directive}s followed by a {\tt
+ CodeBagBody}. A {\tt CodeBagBody} consists of zero or more
+elements, each of which is either a {\tt Fiber} or a (nested) {\tt
+ CodeBagDef}.
+
+A {\tt Fiber} is a set of {\tt Instruction}s which all share a common
+execution point ({\tt Pump}). Each instruction can be {\tt unclog},
+{\tt clog}, {\tt kill}, {\tt literal}, or a set of {\tt Command}s. It
+should be fairly clear how to translate all but the last sort of
+instruction into machine code, based on the encodings in
+\cite{ArchMan}. Take particular note of the fact that {\tt literal}s
+may have a {\tt RequeueCount} but not a {\tt RepeatCount}.
+
+The repetition count for an instruction is placed in square brackets
+and prefixes the instruction. The requeueing count for an instruction
+is placed at the end of the instruction because, {\it conceptually},
+requeueing takes place after the instruction executes.
+
+A {\tt Command} is either {\tt wait}, {\tt nop}, {\tt discard}, {\tt
+ recieve}, {\tt take}, {\tt deliver}, {\tt send}, {\tt sendto}, {\tt
+ notify}, or {\tt notifyLast}. These are compiled as shown below:
+
+\begin{itemize}
+\item[\tt nop] is not valid in combination with any other command; it sets all control bits to {\tt 0}
+\item[\tt wait] is valid only on an output port, and sets {\tt Ti=1}
+\item[\tt discard] sets {\tt Di=1,Dc=0}
+\item[\tt recieve] is valid only on an input port, and sets {\tt Di=1,Dc=1}
+\item[\tt take] is valid only on an output port, and sets {\tt Di=1,Dc=1}
+\item[\tt deliver] is valid only on an input port, and sets {\tt Do=1}
+\item[\tt sendto] is valid only on an output port, and sets {\tt Do=1}
+\item[\tt send] is valid only on an output port, and sets {\tt Do=1,To=1}\footnote{see \cite{ArchMan} for the special meaning this bit combination has}
+\item[\tt notify] sets {\tt To=1} and is not valid in combination with {\tt send} or {\tt sendto}
+\item[\tt notifyLast] sets {\tt To=1,Ig=1} and is not valid in combination with {\tt send} or {\tt sendto}
+\end{itemize}
+
+It is an error to specify two commands within a single instruction if
+both of the commands attempt to set the same bit, even if they attempt
+to set it to the same value.
+
+Note that un-named ``anonymous'' codebags may appear as literals.
+This means that it is possible to write interesting programs such as
+the one below:
+
+\begin{verbatim}
+#ship debug : Debug
+#ship memory : Memory
+
+memory.inCBD: literal {
+ memory.inCBD: literal {
+ memory.inCBD: literal {
+ debug.in:
+ literal 3;
+ deliver;
+ }; deliver;
+ }; deliver;
+ }; deliver;
+\end{verbatim}
+
+
+