Added all of the MH sources, including RCS files, in

[mmh] / docs / historical / mh-6.8.5 / conf / doc / RCS / mhn.rf,v

head    1.14;
access;
symbols;
locks; strict;
comment @# @;


1.14
date    93.10.26.20.12.56;      author jromine; state Exp;
branches;
next    1.13;

1.13
date    93.10.26.16.23.27;      author jromine; state Exp;
branches;
next    1.12;

1.12
date    93.10.26.16.02.50;      author jromine; state Exp;
branches;
next    1.11;

1.11
date    93.09.09.22.32.07;      author jromine; state Exp;
branches;
next    1.10;

1.10
date    93.09.01.20.49.46;      author jromine; state Exp;
branches;
next    1.9;

1.9
date    93.08.20.15.42.08;      author jromine; state Exp;
branches;
next    1.8;

1.8
date    92.12.10.23.59.10;      author jromine; state Exp;
branches;
next    1.7;

1.7
date    92.11.16.22.31.42;      author jromine; state Exp;
branches;
next    1.6;

1.6
date    92.11.02.16.58.55;      author jromine; state Exp;
branches;
next    1.5;

1.5
date    92.10.26.16.55.42;      author jromine; state Exp;
branches;
next    1.4;

1.4
date    92.10.20.20.30.08;      author jromine; state Exp;
branches;
next    1.3;

1.3
date    92.10.16.17.12.29;      author jromine; state Exp;
branches;
next    1.2;

1.2
date    92.03.03.17.13.54;      author jromine; state Exp;
branches;
next    1.1;

1.1
date    92.01.31.16.26.38;      author jromine; state Exp;
branches;
next    ;


desc
@multimedia MH
@


1.14
log
@fixup re: content-id
@
text
@.\"    @@(MHWARNING)
.\" @@(#)$Id: mhn.rf,v 1.13 1993/10/26 16:23:27 jromine Exp jromine $
.SC MHN 1
.NA
mhn \- multi-media MH
.SY
mhn
\%[\%[+folder] \%[msgs] | \%[\-file\0file]]
.br
\%[\-part\0number]... \%[\-type\0content]...
.br
\%[\-list\0\%[\-headers]\0\%[\-noheaders]
.br
       \%[\-realsize]\0\%[\-norealsize]] \%[-nolist]
.br
\%[\-show\0\%[\-serialonly]\0\%[\-noserialonly]
.br
       \%[\-form\0formfile]\0\%[\-pause]\0\%[\-nopause]] \%[\-noshow]
.br
\%[\-store\0\%[\-auto]\0\%[\-noauto]] \%[\-nostore]
.br
\%[\-cache] \%[\-nocache] \%[\-rcache\0policy] \%[\-wcache\0policy]
.br
\%[\-check]\0\%[\-nocheck]
.br
\%[\-ebcdicsafe]\0\%[\-noebcdicsafe]
.br
\%[\-rfc934mode]\0\%[\-norfc934mode]
.br
\%[\-verbose]\0\%[\-noverbose]
.br
\%[\-help]
.DE
The \fImhn\fR command manipulates multi-media messages as specified in
RFC 1521.

Four action switches direct the operation of \fImhn\fR,
namely `\-list', `\-show', `\-store', and `-cache'.
Any of these switches may be used concurrently.
Normally these action switches will operate on the content of each of the
named messages.
However,
by using the `\-part' and `\-type' switches,
the scope of the operation can be focused on particular
subparts (of a multipart content) and/or particular content types.

A part specification consists of a series of numbers separated by dots.
For example,
in a multipart content containing three parts,
these would be named as 1, 2, and 3, respectively.
If part 2 was also a multipart content containing two parts,
these would be named as 2.1 and 2.2, respectively.
Note that the `\-part' switch is effective for only messages
containing a multipart content.
If a message has some other kind of content,
or if the part is itself another multipart content,
the `\-part' switch will not prevent the content from being acted upon.

A content specification consists of a content type and a subtype.
The initial list of \*(lqstandard\*(rq content types and subtypes can be found
in RFC 1521.
.ne 18
A list of commonly used contents is briefly reproduced here:
.sp
.nf
.in +.5i
.ta \w'application  'u
Type    Subtypes
----    --------
text    plain
multipart       mixed, alternative, digest, parallel
message rfc822, partial, external-body
application     octet-stream, postscript
image   jpeg, gif, x-pbm, x-pgm, x-ppm, x-xwd
audio   basic
video   mpeg
.re
.in -.5i
.fi
.sp
Subtypes are mandatory.
.PP
To specify a content,
regardless of its subtype,
just use the name of the content,
e.g.,
\*(lqaudio\*(rq.
To specify a specific subtype,
separate the two with a slash,
e.g.,
\*(lqaudio/basic\*(rq.
Note that regardless of the values given to the `\-type' switch,
a multipart content (of any subtype listed above) is always acted upon.
Further note that if the `\-type' switch is used,
and it is desirable to act on a message/external-body content,
then the `\-type' switch must be used twice:
once for message/external-body and once for the content externally referenced.

Each content may optionally have an integrity check associated with it.
If present and the `-check' switch is given,
then \fImhn\fR will attempt to verify the integrity of the content.

The option `\-file\ file' directs \fImhn\fR to use the specified
file as the source message, rather than a message from
a folder.
Note that the file should be a validly formatted message,
just like any other \fIMH\fR message.
It should \fBNOT\fR be in mail drop format
(to convert a file in mail drop format to a folder of \fIMH\fR messages,
see \fIinc\fR\0(1)).

.Uh "Listing the Contents"
The `\-list' switch tells \fImhn\fR to list the table of contents
associated with the named messages.
The `\-headers' switch indicates that a one-line banner should be
displayed above the listing.
The `\-realsize' switch tells \fImhn\fR to evaluate the \*(lqnative\*(rq
(decoded) format of each content prior to listing.
This provides an accurate count at the expense of a small delay.

.Uh "Showing the Contents"
The `\-show' switch tells \fImhn\fR to display the contents of the named
messages.
The headers of the message are displayed with the \fImhlproc\fR,
using format file \fImhl.headers\fR.
(The choice of format file can be overridden by the `\-form\0formfile' switch.)

\fImhn\fR will look for information in the user's profile to determine
how the different contents should be displayed.
This is accomplished by consulting a display string,
and executing it under \fB/bin/sh\fR,
with the standard input set to the content.
.ne 16
The display string may contain these escapes:
.sp
.nf
.in +.5i
.ta \w'%F  'u
%a      additional arguments
%e      exclusive execution
%f      filename containing content
%F      %e, %f, and stdin is terminal not content
%l      display listing prior to displaying content
%p      %l, and ask for confirmation
%s      subtype
%d      content description
.re
.in -.5i
.fi
.sp
For those display strings containing the e- or F-escape,
\fImhn\fR will execute at most one of these at any given time.
Although the F-escape expands to be the filename containing the content,
the e-escape has no expansion as far as the shell is concerned.

When the p-escape prompts for confirmation,
typing INTR (usually control-C) will tell \fImhn\fR not to display
that content.
(The p-escape can be disabled by specifying `\-nopause'.)
Further,
when \fImhn\fR is display a content,
typing QUIT (usually control-\\) will tell \fImhn\fR to wrap things up
immediately.

Note that if the content being displayed is multipart,
but not one of the subtypes listed above,
then the f- and F-escapes expand to multiple filenames,
one for each subordinate content.
Further,
stdin is not redirected from the terminal to the content.

First,
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-show-<type>/<subtype>
.in -.5i
.sp
to determine the command to use to display the content.
If this isn't found,
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-show-<type>
.in -.5i
.sp
to determine the display command.
.ne 10
If this isn't found,
\fImhn\fR has two default values:
.sp
.nf
.in +.5i
mhn-show-text/plain: %pmoreproc '%F'
mhn-show-message/rfc822: %pshow -file '%F'
.in -.5i
.fi
.sp
If neither apply,
\fImhn\fR will check to see if the message has a application/octet-stream
content with parameter \*(lqtype=tar\*(rq.
If so,
\fImhn\fR will use an appropriate command.
If not,
\fImhn\fR will complain.

.ne 10
Example entries might be:
.sp
.nf
.in +.5i
mhn-show-audio/basic: raw2audio 2>/dev/null | play
mhn-show-image: xv '%f'
mhn-show-application/PostScript: lpr -Pps
.in -.5i
.fi
.sp
Note that when using the f- or F-escape,
it's a good idea to use single-quotes around the escape.
This prevents misinterpretation by the shell of any funny characters
that might be present in the filename.

Because the text content might be in a non-ASCII character set,
when \fImhn\fR encounters a \*(lqcharset\*(rq parameter for this content,
it checks to see whether the environment variable $MM_CHARSET is set
and whether the value of this environment variable is equal to the value of
the charset parameter.
If not,
then
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-charset-<charset>
.in -.5i
.sp
which should contain a command creating an environment to render the
character set.
This command string should containing a single \*(lq%s\*(rq,
which will be filled-in with the command to display the content.

An example entry might be:
.sp
.in +.5i
mhn-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
.in -.5i
.sp
Note that many pagination programs strip off the high-order bit.
However,
newer releases of the \fIless\fR program have modest support for
single-octet character sets.
The source to \fIless\fR version 177,
which has such support,
is found in the MH source tree under \fBmiscellany/less-177\fR.
In order to view messages sent in the ISO 8859/1 character set using
\fIless\fR,
.ne 9
put these lines in your \&.login file:
.sp
.nf
.in +.5i
setenv LESSCHARSET latin1
setenv LESS "-f"
.in -.5i
.fi
.sp
The first line tells \fIless\fR to use 8859/1 definition for determing
whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq, or
\*(lqbinary\*(rq.
The second line tells \fIless\fR not to warn you if it encounters a
file that has non-ASCII characters.
Then,
simply set the \fBmoreproc\fR profile entry to \fIless\fR,
and it will get called automatically.
(To handle other single-octet character sets,
look at the \fIless\fR\0(1) manual entry for information about the
\fBLESSCHARDEF\fR environment variable.)

Finally,
\fImhn\fR will process each message serially\0--\0it won't start showing
the next message until all the commands executed to display the
current message have terminated.
In the case of a multipart content (of any subtype listed above),
the content contains advice indicating if the parts should be
displayed serially or in parallel.
Because this may cause confusion,
particularly on uni-window displays,
the `\-serialonly' switch can be given to tell \fImhn\fR to never
display parts in parallel.

.Uh "Storing the Contents"
The `\-store' switch tells \fImhn\fR to store the contents of the
named messages in \*(lqnative\*(rq (decoded) format.
Two things must be determined:
the directory to store the content,
and the filenames.
Files are written in the directory given by the \fBmhn-storage\fR
profile entry,
.ne 6
e.g.,
.sp
.in +.5i
mhn-storage: /tmp
.in -.5i
.sp
If this entry isn't present,
the current working directory is used.

\fImhn\fR will look for information in the user's profile to determine
how the different contents should be stored.
This is achieved through the use of a formatting string,
.ne 13
which may contain these escapes:
.sp
.nf
.in +.5i
.ta \w'%P  'u
%m      message number
%P      .part
%p      part
%s      subtype
.re
.in -.5i
.fi
.sp
If the content isn't part of a multipart (of any subtype listed above) content,
the p-escapes are ignored.
Note that if the formatting string starts with a \*(lq+\*(rq character,
then these escapes are ignored,
and the content is stored in the named folder.
(A formatting string consisting solely of a \*(lq+\*(rq character
indicates the current folder.)
Further,
a formatting string consisting solely of a \*(lq-\*(rq character
indicates the standard-output.

First,
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-store-<type>/<subtype>
.in -.5i
.sp
to determine the formatting string.
If this isn't found,
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-store-<type>
.in -.5i
.sp
to determine the formatting string.
If this isn't found,
\fImhn\fR will check to see if the content is application/octet-stream
with parameter \*(lqtype=tar\*(rq.
If so,
\fImhn\fR will choose an appropriate filename.
If the content is not application/octet-stream,
then \fImhn\fR will check to see if the content is a message.
If so,
\fImhn\fR will use the value \*(lq+\*(rq.
If not,
\fImhn\fR will use the value \*(lq%m%P.%s\*(rq.

Note that if the formatting string starts with a '/',
then content will be stored in the full path given
(rather than using the value of \fBmhn-storage\fR or the current working
directory.)
Similarly,
if the formatting string starts with a '|',
then \fImhn\fR will execute a command which should ultimately store
the content.
Note that before executing the command,
\fImhn\fR will change to the appropriate directory.
Also note that if the formatting string starts with a '|',
then \fImhn\fR will also honor the a-escape when processing the
formatting string.

.ne 10
Example entries might be:
.sp
.nf
.in +.5i
mhn-store-text: %m%P.txt
mhn-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
mhn-store-application/PostScript: %m%P.ps
.in -.5i
.fi
.sp
Further,
note that when asked to store a content containing a partial message,
\fImhn\fR will try to locate all of the portions and combine them accordingly.
Thus,
if someone's sent you a message in several parts,
you might put them all in their own folder and do:
.sp
.in +.5i
mhn all -store
.in -.5i
.sp
This will store exactly one message,
containing the sum of the parts.
Note that if \fImhn\fR can not locate each part,
it will not store anything.

Finally,
if the `\-auto' switch is given and the content contains information
indicating the filename the content should be stored as
(and if the filename doesn't begin with a '/'),
then the filename from the content will be used instead.

.Uh "External Access"
For contents of type message/external-body,
.ne 12
\fImhn\fR supports these access-types:
.sp
.nf
.in +.5i
afs
anon-ftp
ftp
local-file
mail-server
.in -.5i
.fi
.sp
For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
if your system supports a SOCKETs interface to TCP/IP,
then \fImhn\fR will use a built-in FTP client.
Otherwise,
\fImhn\fR will look for the \fBmhn-access-ftp\fR profile entry,
.ne 6
e.g.,
.sp
.in +.5i
mhn-access-ftp: myftp.sh
.in -.5i
.sp
to determine the pathname of a program to perform the FTP retrieval.
.ne 14
This program is invoked with these arguments:
.sp
.nf
.in +.5i
domain name of FTP-site
username
password
remote directory
remote filename
local filename
\*(lqascii\*(rq or \*(lqbinary\*(rq
.in -.5i
.fi
.sp
The program should terminate with a zero-valued exit-status if the
retrieval is successful.

.Uh "The Content Cache"
When \fImhn\fR encounters an external content containing a
\*(lqContent-ID:\*(rq field,
and if the content allows caching,
then depending on the caching behavior of \fImhn\fR,
the content might be read from or written to a cache.

The caching behavior of \fImhn\fR is controlled with
the `\-rcache' and `\-wcache' switches,
which define the policy for reading from,
and writing to,
the cache, respectively.
One of four policies may be specified:
\*(lqpublic\*(rq,
indicating that \fImhn\fR should make use of a
publically-accessible content cache;
\*(lqprivate\*(rq,
indicating that \fImhn\fR should make use of the user's
private content cache;
\*(lqnever\*(rq,
indicating that \fImhn\fR should never make use of caching;
and,
\*(lqask\*(rq,
indicating that \fImhn\fR should ask the user.

There are two directories where contents may be cached:
the profile entry \fBmhn-cache\fR names a directory containing
world-readable contents,
and,
the profile entry \fBmhn-private-cache\fR names a directory containing
private contents.
The former should be an absolute (rooted) directory name.
.ne 6
For example,
.sp
.in +.5i
mhn-cache: /tmp
.in -.5i
.sp
might be used if you didn't care that the cache got wiped after each reboot
of the system.
The latter is interpreted relative to the user's MH directory,
if not rooted,
.ne 6
e.g.,
.sp
.in +.5i
mhn-private-cache: .cache
.in -.5i
.sp
(which is the default value).

.Uh "Caching the Contents"
When you encounter a content of type message/external-body with access type
\*(lqmail-server\*(rq,
\fImhn\fR will ask you if may send a message to a mail-server
requesting the content,
.ne 14
e.g.,
.sp
.nf
.in +.5i
% show 1
Retrieve content by asking mail-server@@...

SEND file

? yes
mhn: request sent
.in -.5i
.fi
.sp
Regardless of your decision,
\fImhn\fR can't perform any other processing on the content.

However,
if \fImhn\fR is allowed to request the content,
then when it arrives,
there should be a top-level \*(lqContent-ID:\*(rq field which
corresponds to the value in the original message/external-body content.
You should now use the `-cache' switch to tell \fImhn\fR to enter the
arriving content into the content cache,
.ne 8
e.g.,
.sp
.nf
.in +.5i
% mhn -cache 2
caching message 2 as file ...
.in -.5i
.fi
.sp
You can then re-process the original message/external-body content,
and \*(lqthe right thing should happen\*(rq,
.ne 8
e.g.,
.sp
.nf
.in +.5i
% show 1
\0...
.in -.5i
.fi

.Uh "Composing the Contents"
The \fImhn\fR program can also be used as a simple editor to aid in
composing multi-media messages.
When invoked by a \fIwhatnow\fR program,
\fImhn\fR will expect the body of the draft to be formatted as an
\*(lq\fImhn\fR composition file.\*(rq

.ne 59
The syntax of this is straight-forward:
.sp
.nf
.in +.5i
   body         ::=     1*(content | EOL)

   content      ::=     directive | plaintext

   directive    ::=     "#" type "/" subtype
                            0*(";" attribute "=" value)
                            [ "(" comment ")" ]
                            [ "<" id ">" ]
                            [ "[" description "]" ]
                            [ filename ]
                            EOL

                      | "#@@" type "/" subtype
                            0*(";" attribute "=" value)
                            [ "(" comment ")" ]
                            [ "<" id ">" ]
                            [ "[" description "]" ]
                            external-parameters
                            EOL

                      | "#forw"
                            [ "<" id ">" ]
                            [ "[" description "]" ]
                            [ "+"folder ] [ 0*msg ]
                            EOL

                      | "#begin"
                              [ "<" id ">" ]
                              [ "[" description "]" ]
                              [   "alternative"
                                | "parallel"
                                | something-else    ]
                              EOL
                            1*body
                        "#end" EOL

   plaintext    ::=     [ "Content-Description:"
                              description EOL EOL ]
                            1*line
                        [ "#" EOL ]

                      | "#<" type "/" subtype
                            0*(";" attribute "=" value)
                            [ "(" comment ")" ]
                            [ "[" description "]" ]
                            EOL
                            1*line
                        [ "#" EOL ]

   line         ::=     "##" text EOL
                        -- interpreted as "#"text EOL
                      | text EOL
.in -.5i
.fi
.sp
Basically,
the body contains one or more contents.
A content consists of either a directive,
indicated with a \*(lq#\*(rq as the first character of a line;
or,
plaintext (one or more lines of text).
The continuation character, \*(lq\\\*(lq, may be used to enter a single
.ne 11
directive on more than one line,
e.g.,
.sp
.nf
.in +.5i
#@@application/octet-stream; \\
    type=tar; \\
    x-conversions=compress
.in -.5i
.fi
.sp
There are four kinds of directives:
\*(lqtype\*(rq directives,
which name the type and subtype of the content;
\*(lqexternal-type\*(rq directives,
which also name the type and subtype of the content;
the \*(lqforw\*(rq directive,
which is used to forward a digest of messages;
and,
the \*(lqbegin\*(rq directive,
which is used to create a multipart content.

For the type directives,
the user may optionally specify the name of a file containing the
contents in \*(lqnative\*(rq (decoded) format.
(If the filename starts with the \*(lq|\*(rq character,
then this gives a command whose output is captured accordingly.)
If a filename is not given,
\fImhn\fR will look for information in the user's profile to determine
how the different contents should be composed.
This is accomplished by consulting a composition string,
and executing it under \fB/bin/sh\fR,
with the standard output set to the content.
.ne 13
The composition string may contain these escapes:
.sp
.nf
.in +.5i
.ta \w'%P  'u
%a      additional arguments
%f      filename containing content
%F      %f, and stdout is not re-directed
%s      subtype
.re
.in -.5i
.fi
.sp
First,
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-compose-<type>/<subtype>
.in -.5i
.sp
to determine the command to use to compose the content.
If this isn't found,
\fImhn\fR will look for an entry of the form:
.sp
.in +.5i
mhn-compose-<type>
.in -.5i
.sp
to determine the composition command.
If this isn't found,
\fImhn\fR will complain.

An example entry might be:
.sp
.in +.5i
mhn-compose-audio/basic: record | raw2audio -F
.in -.5i
.sp
Because commands like these will vary,
depending on the display environment used for login,
composition strings for different contents should probably be put in
the file specified by the \fB$MHN\fR environment variable,
instead of directly in your user profile.

The external-type directives are used to provide a reference to a content,
rather than enclosing the contents itself.
Hence,
instead of providing a filename as with the type directives,
external-parameters are supplied.
These look like regular parameters,
.ne 15
so they must be separated accordingly,
e.g.,
.sp
.nf
.in +.5i
#@@application/octet-stream; \\
    type=tar; \\
    x-conversions=compress [] \\
    access-type=anon-ftp; \\
    name="mh-mime.tar.Z"; \\
    directory="mrose/mh-mime"; \\
    site="ftp.ics.uci.edu"
.in -.5i
.fi
.sp
By specifying \*(lq[]\*(rq,
an empty description string is given,
and the start of the external-parameters is identified.
.ne 19
These parameters are of the form:
.sp
.nf
.in +.5i
.ta \w'access-type=  'u
access-type=    usually \fIanon-ftp\fR or \fImail-server\fR
name=   filename
permission=     read-only or read-write
site=   hostname
directory=      directoryname (optional)
mode=   usually \fIascii\fR or \fIimage\fR (optional)
size=   number of octets
server= mailbox
subject=        subject to send
body=   command to send for retrieval
.re
.in -.5i
.fi
.sp

For the forw directive,
the user may optionally specify the name of the folder and which
messages are to be forwarded.
if a folder is not given,
it defaults to the current folder.
Similarly,
if a message is not given,
it defaults to the current message.
Hence,
the forw directive is similar to the \fIforw\fR\0(1) command,
except that the former uses the MIME rules for encapsulation
rather than those specified in RFC 934.
Usage of the `\-rfc934mode' switch indicates whether \fImhn\fR should
attempt to utilize the encapsulation rules in such a way as to appear
that RFC 934 is being used.
If given,
then RFC 934-compliant user-agents should be able to burst the message on
reception\0--\0providing that the messages being encapsulated do not
contain encapsulated messages themselves.
The drawback of this approach is that the encapsulations are generated
by placing an extra newline at the end of the body of each message.

For the begin directive,
the user must specify at least one content between
the begin and end pairs.

For all of these directives,
the user may include a brief description of the content between
the \*(lq[\*(rq character and the \*(lq]\*(rq character.
By default,
\fImhn\fR will generate a unique \*(lqContent-ID:\*(rq for each directive;
however,
the user may override this by defining the ID using the
\*(lq<\*(rq and \*(lq>\*(rq characters.
Putting this all together,
.ne 15
here is a brief example of what a user's components file might look like:
.sp
.nf
.in +.5i
To:
cc:
Subject:
--------
#audio/basic [Flint phone]  \\
    |raw2audio -F < /home/mrose/lib/multi-media/flint.au
#image/gif   [MTR's photo] \\
                    /home/mrose/lib/multi-media/mrose.gif
.in -.5i
.fi
.sp
For a later example,
we'll call this components file \fImhncomps\fR.

As noted earlier,
in addition to directives,
plaintext can be present.
Plaintext is gathered,
until a directive is found or the draft is exhausted,
and this is made to form a text content.
If the plaintext must contain a \*(lq#\*(rq at the beginning of a line,
simply double it,
.ne 6
e.g.,
.sp
.in +.5i
##when sent, this line will start with only one #
.in -.5i
.sp
If you want to end the plaintext prior to a directive,
e.g.,
to have two plaintext contents adjacent,
simply insert a line containing a single \*(lq#\*(rq character,
.ne 10
e.g.,
.sp
.nf
.in +.5i
this is the first content
#
and this is the second
.in -.5i
.fi
.sp
Finally,
if the plaintext starts with a line of the form:
.sp
.in +.5i
Content-Description: text
.in -.5i
.sp
then this will be used to describe the plaintext content.
\fBNOTE WELL:\fR you must follow this line with a blank line before
starting your text.

By default,
plaintext is captured as a text/plain content.
You can override this by starting the plaintext with \*(lq#<\*(rq
followed by a content-type specification,
.ne 11
e.g.,
.sp
.nf
.in +.5i
#<text/richtext
this content will be tagged as text/richtext
#
and this content will be tagged as text/plain
.in -.5i
.fi
.sp
Note that if you use the \*(lq#<\*(rq plaintext-form,
then the content-description must be on the same line which identifies
the content type of the plaintext.

If \fImhn\fR is successful,
it renames the original draft to start with the \*(lq,\*(rq character
and end with the string \*(lq.orig\*(rq,
e.g.,
if you are editing the file \*(lqdraft\*(rq,
it will be renamed to \*(lq,draft.orig\*(rq.
This allows you to easily recover the \fImhn\fR composition file.

If the `-check' switch is given,
\fImhn\fR will associate an integrity check with each content.

.Uh "Automatic Composition"
Note that MH will not invoke \fImhn\fR automatically,
unless you add this line to your \&.mh\(ruprofile file:
.sp
.in +.5i
automhnproc: mhn
.in -.5i
.sp
Otherwise,
you must specifically give the command
.sp
.in +.5i
What now? edit mhn
.in -.5i
.sp
prior to sending the draft.

You can easily tailor MH to help you remember to do this.
.ne 10
Suppose you have these lines in your profile:
.sp
.nf
.in +.5i
mcomp:          -editor mprompter -form mhncomps
mprompter:      -noprepend -norapid
mprompter-next: mhn
.in -.5i
.fi
.sp
where \fImcomp\fR is a link to \fIcomp\fR\0(1),
and \fImprompter\fR is a link to \fIprompter\fR\0(1).
Then to send a message using the \fImhncomps\fR components file above,
.ne 26
the sequence is:
.sp
.nf
.in +.5i
% \fBmcomp\fR
To: \fBuser@@host\fR
cc:
Subject: \fBmulti-media message\fR
--------
#audio/basic [Flint phone]  \\
    |raw2audio -F < /home/mrose/lib/multi-media/flint.au
#image/gif   [MTR's photo] \\
                    /home/mrose/lib/multi-media/mrose.gif

--------Enter additional text

\fBThis message contains three contents.\fR
\fB<CTRL-D>\fR
--------

What now? \fBedit\fR (this invokes \fImhn\fR)

What now? \fBsend\fR
.in -.5i
.fi
.sp
You have to remember to type the additional edit command,
but it should be fairly obvious from the interaction.

Finally,
you should consider adding this line to your profile:
.sp
.in +.5i
lproc: show
.in -.5i
.sp
This way,
if you decide to \fBlist\fR after invoking \fImhn\fR as your editor,
the command
.sp
.in +.5i
What now? list
.in -.5i
.sp
will work as you expect.

.Uh "Sending Files via Mail"
When you want to send a bunch of files to someone,
you can run the \fIviamail\fR shell script,
which is similar the tarmail command:
.sp
.in +.5i
@@(MHETCPATH)/viamail mailpath \*(lqsubject\*(rq files\0...
.in -.5i
.sp
\fIviamail\fR will archive the directories/files you name with \fItar\fR\0(1),
and then mail the compressed archive to the `mailpath' with the given
`subject'.
The archive will be automatically split up into as many messages as
necessary in order to get past most mailers.

Sometimes you want \fIviamail\fR to pause after posting a partial message.
This is usually the case when you are running \fIsendmail\fR and
expect to generate a lot of partial messages.
If the first argument given to \fIviamail\fR starts with a dash,
then it is interpreted as the number of seconds to pause in between postings,
.ne 6
e.g.,
.sp
.in +.5i
@@(MHETCPATH)/viamail -300 mailpath \*(lqsubject\*(rq files\0...
.in -.5i
.sp
will pause 5 minutes in between each posting.

When these messages are received,
invoke \fImhn\fR once,
with the list of messages,
and the `\-store' command.
The \fImhn\fR program will then store exactly one message containing the
archive.
You can then use `\-show' to find out what's inside;
possibly  followed by `\-store' to write the archive to a file where you
.ne 26
can subsequently uncompress and untar it, e.g.,
.sp
.nf
.in +.5i
% mhn -list all
 msg part  type/subtype             size description
   1       message/partial           47K part 1 of 4
   2       message/partial           47K part 2 of 4
   3       message/partial           47K part 3 of 4
   4       message/partial           18K part 4 of 4
% mhn -store all
% mhn -list -verbose last
 msg part  type/subtype             size description
   5       application/octet-stream 118K
             (extract with uncompress | tar xvpf -)
             type=tar
             x-conversions=compress
% mhn -show last
 msg part  type/subtype             size description
   5       application/octet-stream 118K
-- headers of message, followed by \fItar\fR listing appears here
% mhn -store last
% uncompress < 5.tar.Z | tar xvpf -
.in -.5i
.fi
.sp
Alternately,
by using the `\-auto' switch,
\fImhn\fR will automatically do the extraction for you,
.ne 26
e.g.,
.sp
.nf
.in +.5i
% mhn -list all
 msg part  type/subtype             size description
   1       message/partial           47K part 1 of 4
   2       message/partial           47K part 2 of 4
   3       message/partial           47K part 3 of 4
   4       message/partial           18K part 4 of 4
% mhn -store all
% mhn -list -verbose last
 msg part  type/subtype             size description
   5       application/octet-stream 118K
             (extract with uncompress | tar xvpf -)
             type=tar
             x-conversions=compress
% mhn -show last
 msg part  type/subtype             size description
   5       application/octet-stream 118K
-- headers of message, followed by \fItar\fR listing appears here
% mhn -store -auto last
-- \fItar\fR listing appears here as files are extracted
.in -.5i
.fi
.sp
As the second \fItar\fR listing is generated,
the files are extracted.
A prudent user will never put `\-auto' in the \&.mh\(ruprofile file.
The correct procedure is to first use `\-show',
to find out what will be extracted.
Then \fImhn\fR can be invoked with  `\-store' and `\-auto' to perform
the extraction.

.Uh "User Environment"
Because the display environment in which \fImhn\fR operates may vary
for a user,
\fImhn\fR will look for the environment variable \fB$MHN\fR.
If present,
this specifies the name of an additional user profile which should be read.
Hence,
when a user logs in on a particular display device,
this environment variable should be set to refer to a file containing
definitions useful for the display device.
Normally,
only entries of the form
.sp
.in +.5i
mhn-show-<type>/<subtype>
.br
mhn-show-<type>
.in -.5i
.sp
need be present.
Finally,
\fImhn\fR will attempt to consult one other additional user profile,
.ne 6
e.g.,
.sp
.in +.5i
@@(MHETCPATH)/mhn_defaults
.in -.5i
.sp
which is created automatically during MH installation.
.Fi
^$HOME/\&.mh\(ruprofile~^The user profile
^$MHN~^Additional profile entries
^@@(MHETCPATH)/mhn_defaults~^System-default profile entries
^@@(MHETCPATH)/mhl.headers~^The headers template
.Pr
^Path:~^To determine the user's MH directory
.Ps
^Current\-Folder:~^To find the default current folder
.Ps
^mhlproc:~^Default program to display message headers
.Ps
^mhn-access-ftp:~^Program to retrieve contents via FTP
.Ps
^mhn-cache~^Public directory to store cached external contents
.Ps
^mhn-charset-<charset>~^Template for environment to render character sets
.Ps
^mhn-compose-<type>*~^Template for composing contents
.Ps
^mhn-private-cache~^Personal directory to store cached external contents
.Ps
^mhn-show-<type>*~^Template for displaying contents
.Ps
^mhn-storage~^Directory to store contents
.Ps
^mhn-store-<type>*~^Template for storing contents
.Ps
^moreproc:~^Default program to display text/plain content
.Sa
mhl(1)
.br
\fIMIME: Mechanisms for Specifying and Describing the Format of
Internet Message Bodies\fR
(RFC 1521),
.br
\fIProposed Standard for Message Encapsulation\fR
(RFC 934).
.De
`+folder' defaults to the current folder
.Ds
`msgs' defaults to cur
.Ds
`\-noauto'
.Ds
`\-nocache'
.Ds
`\-nocheck'
.Ds
`\-noebcdicsafe'
.Ds
`\-form\0mhl.headers'
.Ds
`\-headers'
.Ds
`\-pause'
.Ds
`\-rcache\0ask'
.Ds
`\-realsize'
.Ds
`\-rfc934mode'
.Ds
`\-noserialonly'
.Ds
`\-show'
.Ds
`\-noverbose'
.Ds
`\-wcache\0ask'
.Co
If a folder is given,
it will become the current folder.
The last message selected will become the current message.
.Bu
Partial messages contained within a multipart content are not reassembled
with the `\-store' switch.
.En
@


1.13
log
@change RFC 1341 -> 1521 (new RFC)
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.12 1993/10/26 16:02:50 jromine Exp jromine $
d8 2
a9 2
\%[+folder] \%[msgs]
\%[\-file\0file]
d568 1
a568 1
.ne 55
d580 1
d588 1
d594 1
d600 1
d789 5
@


1.12
log
@update -cache, -rcache, -wcache
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.9 1993/08/20 15:42:08 jromine Exp $
d35 1
a35 1
RFC 1341.
d61 1
a61 1
in RFC 1341.
d70 1
a70 1
text    plain, richtext
d1122 1
a1122 1
(RFC 1341),
@


1.11
log
@fixes from mtr
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.9 1993/08/20 15:42:08 jromine Exp jromine $
d8 2
a9 2
\%[+folder] \%[msgs] 
\%[\-file\0file] 
d22 1
a22 1
\%[\-cache\0policy]
d37 2
a38 2
Three action switches direct the operation of \fImhn\fR,
namely `\-list', `\-show', and `\-store'.
d298 1
d426 2
a427 1
If your system supports a SOCKETs interface to TCP/IP,
d431 1
d455 1
a455 1
retrieval is success.
d461 30
a490 9
then \fImhn\fR looks for the profile entry \fBmhn-cache\fR to
determine if the content should be read from/written to a cache.
Any content written to the cache will,
by default,
be world-readable.
(To prevent this,
use a directory name with the desired read and execute permissions.)
The \fBmhn-cache\fR profile entry names the directory used for caching,
e.g.,
d498 10
d509 12
a520 6
The caching behavior of \fImhn\fR is controlled with the `\-cache' switch.
One of three arguments may be specified:
always, indicating that \fImhn\fR should make use of caching whenever possible;
ask, indicating that \fImhn\fR should ask the user;
and,
never, indicating that \fImhn\fR should never make use of caching.
d522 39
d568 1
a568 1
.ne 54
d639 1
a639 1
    conversions=x-compress
d724 1
a724 1
    conversions=x-compress [] \\
d735 1
a735 1
.ne 16
d813 1
d976 1
d1010 1
a1010 1
             conversions=x-compress
d1040 1
a1040 1
             conversions=x-compress
d1080 1
d1102 1
a1102 1
^mhn-cache~^Directory to store cached external contents
d1108 2
d1133 1
a1133 1
`\-cache\0ask'
d1145 2
d1156 2
@


1.10
log
@document mhn -file
@
text
@d93 1
a93 1
a multipart content is always acted upon.
d146 1
d165 7
d282 1
a282 1
In the case of a multipart content,
d324 1
a324 1
If the content isn't part of a multipart content,
d520 2
a521 1
                                | "parallel"    ]
d1044 2
@


1.9
log
@fixes from mtr
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.8 1992/12/10 23:59:10 jromine Exp jromine $
d8 3
a10 1
\%[+folder] \%[msgs] \%[\-part\0number]... \%[\-type\0content]...
d102 9
@


1.8
log
@typo
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.7 1992/11/16 22:31:42 jromine Exp jromine $
d14 1
a14 1
\%[\-show\0\%[\-serialonly]\0\%[\-noserialonly]]
d16 1
a16 1
       \%[\-form\0formfile]] \%[\-noshow]
d20 1
a20 3
\%[\-verbose] \%[\-noverbose]
\%[\-rfc934mode] \%[\-norfc934mode]
\%[\-ebcdicsafe] \%[\-noebcdicsafe]
d22 8
d71 1
a71 1
application     octet-stream, oda, postscript
d97 4
d147 1
d456 7
d644 2
a646 1
site=   hostname
d648 1
d650 1
d774 3
d1027 4
d1036 2
@


1.7
log
@specify only character cell fonts with mhn.
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.6 1992/11/02 16:58:55 jromine Exp jromine $
d195 2
a196 2
it checks to see if the environment variable $MM_CHARSET is set,
and that that the value of this environment variable is equal to the value of
@


1.6
log
@fixes from mtr
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.5 1992/10/26 16:55:42 jromine Exp jromine $
d214 1
a214 1
mhn-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-*-*-iso8859-*' -e %s
@


1.5
log
@add quotes around %f
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.4 1992/10/20 20:30:08 jromine Exp jromine $
d358 3
a360 4

Further note that when asked to store a content containing a partial
message, \fImhn\fR will try to locate all of the portions and combine
them accordingly.
d380 44
d974 2
a1024 8

For contents of type message/external-body,
those with a parameter of \*(lqaccess-type=tftp\*(rq will not be
automatically retrieved.
Further,
those with a parameter \*(lqaccess-type=ftp\*(rq or
\*(lqaccess-type=anon-ftp\*(rq will be automatically retrieved
only if your system supports a SOCKETs interface to TCP/IP.
@


1.4
log
@MIME upgrade 10
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.3 1992/10/16 17:12:29 jromine Exp jromine $
d164 2
a165 2
mhn-show-text/plain: %pmoreproc %F
mhn-show-message/rfc822: %pshow -file %F
d183 1
a183 1
mhn-show-image: xv %f
d188 4
@


1.3
log
@revisions from mtr -- mime/update9
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.1 1992/01/31 16:26:38 jromine Exp $
d54 1
d91 1
d100 1
d112 1
d158 1
d177 1
a208 1
.nf
a211 1
.fi
d222 1
d256 1
d276 1
d343 1
d377 1
d398 1
a398 30
Because the display environment in which \fImhn\fR operates may vary
for a user,
\fImhn\fR will look for the environment variable \fB$MHN\fR.
If present,
this specifies the name of an additional user profile which should be read.
Hence,
when a user logs in on a particular display device,
this environment variable should be set to refer to a file containing
definitions useful for the display device.
Normally,
only entries of the form
.sp
.in +.5i
mhn-show-<type>/<subtype>
.br
mhn-show-<type>
.in -.5i
.sp
need be present.
Finally,
\fImhn\fR will attempt to consult one other additional user profile,
e.g.,
.sp
.in +.5i
@@(MHETCPATH)/mhn_defaults
.in -.5i
.sp
which is created automatically during MH installation.

.bp
d404 2
d467 1
d501 1
d552 1
d571 1
d619 1
d656 1
d682 1
d706 1
d708 1
a708 1
unless you  add this line to your \&.mh\(ruprofile file:
d724 1
d738 1
d785 1
a806 1
.nf
a809 1
.fi
d821 1
d851 1
d885 30
@


1.2
log
@fixes from mtr
@
text
@d2 1
a2 1
.\" @@(#)$Id: mhn.rf,v 1.1 1992/01/31 16:26:38 jromine Exp jromine $
d10 1
a10 1
\%[\-list\0\%[\-header]\0\%[\-noheader]
d22 1
a22 1
\%[\-ebcdic] \%[\-noebcdicsafe]
d27 1
a27 1
the MIME draft.
d52 2
a53 2
The list of \*(lqstandard\*(rq content types and subtypes can be found
in the MIME draft.
d65 1
a65 1
image   g3fax, jpeg, gif, x-pbm, x-pgm, x-ppm
d86 1
a86 1
and it is desirable to act on a message/external content,
d88 1
a88 1
once for message/external and once for the content externally referenced.
d92 1
a92 1
The `\-header' switch indicates that a one-line banner should be
d119 1
d125 1
a125 1
For those display string containing the e- or F-escape,
d128 1
a128 1
the e-escape has no expansion as far as the shell is concerned..
d130 8
d159 2
a160 2
mhn-show-text/plain: moreproc %F
mhn-show-message/rfc822: show -file %F
d178 1
a178 1
mhn-show-application/PostScript: pageview -
d183 56
d248 2
a249 2
the `\-serialonly' switch can be given to tell \fImhn\fR to always
display parts in serial.
d290 3
d369 20
d416 1
a416 3
which should be created by the system-administrator.
It only makes sense to do this if there is sufficiently homogeneity
among the displays attached to the system.
d439 1
a439 1
                        "#@@" type "/" subtype
d453 2
a454 1
                              [ "alternative" | "parallel" ]
d464 8
d484 12
d518 1
a518 1
The display string may contain these escapes:
d573 7
a579 1
#@@application/octet-stream; type=tar [] access-type=ftp; ...
d591 1
d594 1
a594 1
access-type=    usually \fIftp\fR or \fIanon-ftp\fR
d596 2
a597 2
site=   hostname
expiration=     822-style date
d641 4
a644 2
#audio/basic  [Flint phone]  | raw2audio -F < /home/mrose/flint.au
#image/x-pbm  [MTR's photo]  /home/mrose/mrose.pbm
d690 19
d717 2
a718 2
Note that MH will not invoke \fImhn\fR automatically.
You must specifically give the command
d721 7
d731 2
a732 1
after you have constructed the \fImhn\fR composition file.
d756 4
a759 2
#audio/basic  [Flint phone]  | raw2audio -F < /home/mrose/flint.au
#image/x-pbm  [MTR's photo]  /home/mrose/mrose.pbm
d846 1
a846 1
             conversions=compress
d875 1
a875 1
             conversions=compress
d895 1
a895 1
^@@(MHETCPATH)/mhn_profile~^System-default profile entries
d904 4
d921 2
a922 1
Internet Message Bodies\fR,
d935 1
a935 1
`\-header'
d954 5
a958 2
For contents of type message/external,
only those with parameter \*(lqaccess-type=ftp\*(rq or
d960 1
a960 1
(and only if your system supports a SOCKETs interface to TCP/IP).
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" @@(#)$Id$
d65 1
a65 2
image   g3fax, jpeg, gif, pbm, pgm, ppm,
        tiff-b-netfax
d528 1
a528 1
#image/pbm    [MTR's photo]  /home/mrose/mrose.pbm
d614 1
a614 1
#image/pbm    [MTR's photo]  /home/mrose/mrose.pbm
@