doc/mailcap.txt

   1 Managing External Viewers with Mailcap
   2 --------------------------------------
   3
   4 This document describes the support for Mailcap (RFC 1524) in ELinks. It does
   5 not describe the mailcap format. There are plenty of documents on the Web that
   6 does this. Google and thou wilt find. ;)
   7
   8
   9 A Short Intro to Mailcap
  10 ~~~~~~~~~~~~~~~~~~~~~~~~~
  11
  12 Mailcap is a file format defined in RFC 1524. Its purpose is to inform
  13 multiple mail reading user agent (MUA) programs about the locally-installed
  14 facilities for handling mail in various formats. It is designed to work with
  15 the Multipurpose Internet Mail Extensions, known as MIME.
  16
  17 ELinks allows MIME handlers to be defined using its own configuration system,
  18 so why support mailcap? It can be seen as an alternative or simply as a
  19 supplement for setting up MIME handlers in ELinks.  Mailcap files are present
  20 on most UNIX systems--usually in /etc/mailcap--so this makes it possible for
  21 ELinks to know how to handle a great variety of file formats with little
  22 configuration. To be able to use mailcap, it has to be compiled into ELinks.
  23 This is the default. If you don't need mailcap support, just configure ELinks
  24 with the flag: \--disable-mailcap.
  25
  26
  27 Parameters to Mailcap Entries
  28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29
  30 The code has been ported from Mutt and thereby inherits some of its various
  31 features and limitation.
  32
  33 The following parameters are supported:
  34
  35 `---------------`-------------------------------------------------------------
  36 Parameter       Description
  37 ------------------------------------------------------------------------------
  38 %s              The filename that contains the data.
  39 %f              The content type, like 'text/plain'.
  40 ------------------------------------------------------------------------------
  41
  42 The following parameters are not supported, since they do not really make much
  43 sense for a non-MUA program:
  44
  45 `---------------`-------------------------------------------------------------
  46 Parameter       Description
  47 ------------------------------------------------------------------------------
  48 %n              The integer number of sub-parts in the multipart
  49 %F              The "content-type filename" repeated for each sub-part
  50 %{ parameter}   The "parameter" value from the content-type field
  51 ------------------------------------------------------------------------------
  52
  53
  54 Reading of Mailcap Files
  55 ~~~~~~~~~~~~~~~~~~~~~~~~
  56
  57 Mailcap files will be read when starting ELinks. The mailcap files to use will
  58 be found from the mailcap path, a colon separated list of files similar to the
  59 $PATH environment variable. The mailcap path will be determined in the
  60 following way:
  61
  62  - From the value of the mime.mailcap.path option in elinks.conf; for example:
  63
  64         set mime.mailcap.path = "~/.mailcap:/usr/local/etc/mailcap"
  65
  66  - From MAILCAP environment variable.
  67
  68  - If non of the above is defined, the mailcap path defaults to
  69    `~/.mailcap:/etc/mailcap`.
  70
  71
  72 Fields
  73 ~~~~~~
  74
  75 Since mailcap handling is primarily for displaying of resources, all fields
  76 like edit, print, compose etc. are ignored.
  77
  78 Note: Test commands are supported, but unfortunately, it's not possible to
  79 provide the file when running the test. So any test that requires a file will
  80 be considered failed and the handler will not be used.
  81
  82 Unfortunately, there are no 'native' support for the copiousoutput field.  The
  83 field basically mean 'needs pager'. So it is handled by appending a pipe and a
  84 pager program to the command. The pager program will be read from the `PAGER`
  85 environment variable. If this fails, test are made for common pager programs
  86 (`/usr/bin/pager`, `/usr/bin/less` and `/usr/bin/more` in that order). So if you
  87 define png2ascii as your handler for image/png and specify copiousoutput then
  88 the executed command will be "`png2ascii |/usr/bin/less`" if less is your pager
  89 or present on your system.
  90
  91
  92 Mailcap Configuration
  93 ~~~~~~~~~~~~~~~~~~~~~
  94
  95 Apart from the mime.mailcap.path option, you can configure if mailcap support
  96 should be disabled. The default being that it is enabled. To disable it just
  97 put:
  98
  99         set mime.mailcap.enable = 0
 100
 101 in elinks.conf.
 102
 103 It is also possible to control whether ELinks should ask you before opening a
 104 file. The option is a boolean and can be set like this:
 105
 106         set mime.mailcap.ask = 1
 107
 108 if you would like to be asked before opening a file.
 109
 110
 111 Some Sample Mailcap Entries
 112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 113
 114 Below are examples of how to specify external viewers:
 115
 116 -------------------------------------------------------------------------------
 117 # Use xv if X is running
 118 image/*;                xv %s ; test=test -n "$DISPLAY";
 119
 120 text/x-csrc;            view %s; needsterminal
 121
 122 # Various multimedia files
 123 audio/mpeg;             xmms '%s'; test=test -n "$DISPLAY";
 124 application/pdf;        xpdf '%s'; test=test -n "$DISPLAY";
 125 application/postscript; ps2ascii %s ; copiousoutput
 126 -------------------------------------------------------------------------------