\documentstyle{article}  
\title{The PLM (Program Logic Manual) for n2m.}
\author{David Collier-Brown}
\date{Started 22 August 1992, printed \today}
\begin{document}
\maketitle

\section{Introduction.}
    n2m is one half of a set of minimum-functionality mail gateway tools for
using NeXTs in a MIME universe.  The other is tnextmil (or optionally m2n, yet
to be written). n2m converts NeXT-format multimedia mail into syntactically
correct MIME-format mail.
  It is a converter, not a translator: the conversion is not fully
correctness-preserving. It uses knowledge of the semantics of NeXT mail
to do a decent job without undue effort. This is normally sufficient
for a MIME-compliant mail agent and an improvement even for simple
RFC822-only mail agents.

\subsection{History.}
   I was faced with the appearance of a cloud of NeXTs in a universe
of RFC822 mail agents, just when I was trying to get ready for MIME.
Rather than wandering off into the wilds of proprieteryness, I decided
to try writing a filter.  This was made easy, since Chris Paris,
cap+@cmu.edu, had already written tnextmail, an ascii-to-NeXT mail
filter, and was kind enough to make it available to me to examine.

  Several people, notably Derek Beatty and XYZZY, helped me with
some obvious blunders.  Nataniel Borenstein doesn't know it, but
he helped too (the base64 encoding code was taken from metamail).

  If NeXT don't switch to MIME, I'll upgrade this to a true translator,
by adding a full-fledged intermediate pass between decompose and recompose,
and use somewhat better transformations.

\subsection{NeXT Mail Format}
  NeXT mail is either ordinary, or a message which the NeXT mailer fears
will not make it through the 7-bit mail system.  These messages have 
a special header, ``Next-Attachment:'', giving the name of a tar file.

  The tar file follows as the body of the message, compressed and uuencoded.
Alas, the permissions are usually wrong, the compressed file doesn't have
the standard .Z extension and uuencode uses blanks as a significant
character, which means some mail gateways will shred them.  So the 

  Inside (!) the tar file is a file called index.rtf, which contains the
readable part of the message and attachment declarations in microsoft-rtf
format.  This is then followed by the attachments.

  All in all, the NeXT scheme is a good first attempt, but rather flawed.

\newpage
\subsection{Organization.}
  The paper has the same structure as the program, starting with main()
and working its way down.
  A structure chart looks like this: 
\begin{verbatim}

                              +------+
                              | main |
                              +------+
                                  |
                                  +------------+
                                  |            |
                              +-------+   +-----------+
                              | n2m   |   | doOptions |
                              +-------+   +-----------+
                                  |
                        +---------+---+--------------+
                        |             |              |
                  +-----------+ +-----------+  +-----------+  
                  | decompose | | translate |  | recompose |
                  +-----------+ +-----------+  +-----------+

\end{verbatim}
  The simplicity of the structure is deliberate: MIME is simple, but
not simple-minded.  

\section{File n2m.c}
\subsection{unnamed}
  There are a few interesting things amongst the declarations.  The
questionable one is a timeout jmp\_buf, and a timeout value.  I've been
trapped by infinitely-running uudecodes in the past, and stole this
code from a network mail transfer utility.  I'm not totally sure the
time value is large enough for an arbitrarily-large sound file (:-)).

  The other is a declaration that uses the correct base64 code from
metamail.  Mine was bogus.

\subsection{function main()}
	This function does little save set signals, parse args
and pass non-options to n2m.

\subsection{function doOptions()}

	The options are -v (verbose) and -d (save the temp files).
The latter is for people who don't have base64 decoders and want to use
the files directly.  It implies -v so that the user finds out the
directory and filenames to look for.

\subsection{function n2m()}

  This is the filter management routine.

  All the policy lives here.  This makes arguing about the fidelity of the
implementation much easier, just like a recursive descent compiler.
  This is important: this program has to interwork with some software which
is not well-understood, plus a large group of quite new multimedia
user agents.

  There are two error conditions which the program can not deal with:
impossibilities and fatal errors.  Both cause the program to exit with
a message and a non-zero return code and without affecting the
input file.
  The impossible conditions are things like an ill-formed NeXT file,
which cannot be turned into a tar container or cannot be untarred.
Merely fatal errors are an inability to get temp space for the 
transformed message or an I/O error.

\subsection{function decompose()}
  This function takes a NeXT uuencoded, compressed tar file out
of the message and turns it into plain files in a directory, plus an
ordered list of what was in the message.

  The headers go into a file called ``.0'', the directory of the NeXT tar
file goes into .-1 and the text of the ``index.rtf'' file into ``.1''.  None
of these is necessarily a good name, as someone could easily use these names
in the NeXT tar file.  This will require some small amount of thought.

  For non-obvious reasons, I translate the NeXT header here.  I think
I'd be better doing in translate\ldots

The progress is optionally reported after each transformation.

\subsection{function translate()}
  This function translates exactly and only the subset-rtf in the
index.rtf file.  It's where any other translations should go, including
any header munging and translation of NeXT sound into a real sound file.

  The translation of the index.rtf file is minimal: fomatting commands and a
few declarations are stripped, and the attachments names are placed in 
comments. This translation is packed up into a multipart/alternative
with the original rtf for mailers which can understand (or translate)
microsoft-speak.

  This is stuffed into file ``.1'' for recompose.

\subsection{function recompose()}
  This function puts everything back together, in the order it was
in the tar file, plus encoding individual enclosures.

  First, it adds a few headers to describe the file format, a note to
the users of non-MIME mail readers, then starts with the file ``.1''.
 It follows this with each of the enclosures in order.

  Each save the numbered files is characterized, to decide on the content-type
and transfer-encoding.  If the file is known to be text, it's left alone.
Otherwise it gets encoded as base64.

  As in decompose, status is reported regularly and a timer is kept running
against the leap to infinite-duration recomposition.

\section{Supporting libraries.}
	There are a small set of supporting libraries. 
The interesting one is the characterizer, which uses the file extension
to decide of the file should be encoded in base64.  If not, it is left as
readable text.  The basic logic is to leave known ascii files alone and
to encode all others.
  A file pointer is passed to characterize, so that it can read
the magic number of the file or the whole file if it elects, in order to
do the characterization.  That's a hook for a real translator.

   This is followed by the base64 code stolen from Bellcore.

  Finally there are a few tempdir-management functions.
 
\section{File Strings.c}
  This file is some string utilities, including ones known
to be absent on machines I've tested. This is provided mainly
for completeness, but I do expect a port to something stupid 
is inevitable.

\section{Caveats}
 The sound converter converts the whole file, header and all, into a
base64 sound file.  This is a deliberate over-simplification, and
causes the sound to start with a distinct click if played directly. A
smarter sound program can take the file and interpret it with more
fidelity.

  The conversion of the initial ``index.rtf'' file to text is done using
a NeXT-specific trivial reformatter.  Don't try to use it for general
rft!  Use rtf2text or rtf2troff instead.

\end{document}
%
% $Header: /team/davecb/Tools/n2m/src/RCS/n2m_plm.tex,v 1.6 1992/09/01 12:24:38 davecb Exp $
%
%
% $Log: n2m_plm.tex,v $
% Revision 1.6  1992/09/01  12:24:38  davecb
% adding a tarnslation
%
% Revision 1.5  1992/09/01  02:23:20  davecb
% adding caveats
%
% Revision 1.4  1992/08/29  22:38:08  davecb
% *** empty log message ***
%
% Revision 1.3  1992/08/29  22:26:21  davecb
% add words
%
% Revision 1.2  1992/08/26  11:51:35  davecb
% *** empty log message ***
%
% Revision 1.1  1992/08/22  22:06:37  davecb
% Initial revision
%
%

