Mailcap Files
*************

   NCSA Mosaic and almost all other WWW browsers rely on a separate file
for mapping MIME types to external viewing programs.  This takes some of
the burden off of browser developers, so each browser does not have to
support all image formats, or postscript, etc.  Instead of having the
users of Emacs/W3 duplicate this in lisp, this file can be parsed using
the `mm-parse-mailcaps' function.  This function is called each time
Emacs/W3 is loaded.  It tries to locate mimetype files in several
places. If the environment variable `MAILCAPS' is nonempty, then this
is assumed to specify a UNIX-like path of mimetype files (this is a
colon separated string of pathnames).  If the `MAILCAPS' environment
variable is empty, then Emacs/W3 looks for these files:

  1. `~/.mailcap'

  2. `/etc/mailcap'

  3. `/usr/etc/mailcap'

  4. `/usr/local/etc/mailcap'

   This format of this file is specified in RFC 1343, but a brief
synopsis follows (this is taken verbatim from sections of RFC 1343).

   Each mailcap file consists of a set of entries that describe the
proper handling of one media type at the local site.  For example, one
line might tell how to display a message in Group III fax format.  A
mailcap file consists of a sequence of such individual entries,
separated by newlines (according to the operating system's newline
conventions). Blank lines and lines that start with the "#" character
(ASCII 35) are considered comments, and are ignored.  Long entries may
be continued on multiple lines if each non-terminal line ends with a
backslash character ('\', ASCII 92), in which case the multiple lines
are to be treated as a single mailcap entry.  Note that for such
"continued" lines, the backslash must be the last character on the line
to be continued.

   Each mailcap entry consists of a number of fields, separated by
semi-colons.  The first two fields are required, and must occur in the
specified order.  The remaining fields are optional, and may appear in
any order.

   The first field is the content-type, which indicates the type of data
this mailcap entry describes how to handle.  It is to be matched against
the type/subtype specification in the "Content-Type" header field of an
Internet mail message.  If the subtype is specified as "*", it is
intended to match all subtypes of the named content-type.

   The second field, view-command, is a specification of how the
message or body part can be viewed at the local site.  Although the
syntax of this field is fully specified, the semantics of program
execution are necessarily somewhat operating system dependent.

   The optional fields, which may be given in any order, are as follows:
   * The "compose" field may be used to specify a program that can be
     used to compose a new body or body part in the given format.  Its
     intended use is to support mail composing agents that support the
     composition of multiple types of mail using external composing
     agents.  As with the view- command, the semantics of program
     execution are operating system dependent.  The result of the
     composing program may be data that is not yet suitable for mail
     transport--that is, a Content-Transfer-Encoding may need to be
     applied to the data.

   * The "composetyped" field is similar to the "compose" field, but is
     to be used when the composing program needs to specify the
     Content-type header field to be applied to the composed data.  The
     "compose" field is simpler, and is preferred for use with existing
     (non-mail-oriented) programs for composing data in a given format.
     The "composetyped" field is necessary when the Content-type
     information must include auxilliary parameters, and the
     composition program must then know enough about mail formats to
     produce output that includes the mail type information.

   * The "edit" field may be used to specify a program that can be used
     to edit a body or body part in the given format.  In many cases,
     it may be identical in content to the "compose" field, and shares
     the operating-system dependent semantics for program execution.

   * The "print" field may be used to specify a program that can be
     used to print a message or body part in the given format.  As with
     the view-command, the semantics of program execution are operating
     system dependent.

   * The "test" field may be used to test some external condition (e.g.
     the machine architecture, or the window system in use) to
     determine whether or not the mailcap line applies.  It specifies a
     program to be run to test some condition.  The semantics of
     execution and of the value returned by the test program are
     operating system dependent.  If the test fails, a subsequent
     mailcap entry should be sought.  Multiple test fields are not
     permitted--since a test can call a program, it can already be
     arbitrarily complex.

   * The "needsterminal" field indicates that the view-command must be
     run on an interactive terminal.  This is needed to inform
     window-oriented user agents that an interactive terminal is
     needed.  (The decision is not left exclusively to the view-command
     because in some circumstances it may not be possible for such
     programs to tell whether or not they are on interactive
     terminals.)  The needsterminal command should be assumed to apply
     to the compose and edit commands, too, if they exist.  Note that
     this is NOT a test--it is a requirement for the environment in
     which the program will be executed, and should typically cause the
     creation of a terminal window when not executed on either a real
     terminal or a terminal window.

   * The "copiousoutput" field indicates that the output from the
     view-command will be an extended stream of output, and is to be
     interpreted as advice to the UA (User Agent mail- reading program)
     that the output should be either paged or made scrollable. Note
     that it is probably a mistake if needsterminal and copiousoutput
     are both specified.

   * The "description" field simply provides a textual description,
     optionally quoted, that describes the type of data, to be used
     optionally by mail readers that wish to describe the data before
     offering to display it.

   * The "x11-bitmap" field names a file, in X11 bitmap (xbm) format,
     which points to an appropriate icon to be used to visually denote
     the presence of this kind of data.

   * Any other fields beginning with "x-" may be included for local or
     mailer-specific extensions of this format.  Implementations should
     simply ignore all such unrecognized fields to permit such
     extensions, some of which might be standardized in a future
     version of this document.