doc/mime.txt

   1 [[mime]]
   2 Introduction to MIME handling
   3 -----------------------------
   4
   5 At some time along the 0.4 prereleases, ELinks replaced the old Links file
   6 configuration system with its own one. Now, the configuration is stored in
   7 elinks.conf, much more complete and featuring a new syntax. You can set most
   8 options from the UI (so usually there is no need to deal with elinks.conf),
   9 and that used to be true for setting MIME handlers and extensions as well; but
  10 now the associations menu is gone temporarily, forcing you to set the handlers
  11 from the configuration file.
  12
  13 The comments provided within elinks.conf for the MIME options are not much
  14 helpful, and those options may seem a bit obscure or confusing at first.  This
  15 document is a basic introduction to setting of MIME associations for ELinks.
  16 If you want to know how to automatically launch a program to view some kind of
  17 file (like images), then read on. Some basic knowledge of MIME is recommended.
  18
  19
  20 Handling MIME types, the ELinks way
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22
  23 What are MIME types and why may you want to use them?
  24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  25
  26 If, while browsing with ELinks, you need to display files that it can't show
  27 (like images or PDF documents), then you will likely want to pass them to
  28 other programs that are suitable for this task. While you may do it manually
  29 (saving the file to disk, running the auxiliary program to show it and then
  30 removing the file when finished), ELinks provides a method to do this
  31 automatically using MIME types.
  32
  33 ELinks usually knows what the MIME type is for any file (which is a kind of
  34 description of its format), thus you only need to specify how to manage the
  35 MIME types for the files you want to open. If you don't tell ELinks how to
  36 manage a given MIME type then it will show you on screen the contents of the
  37 file (as if it was ASCII text) instead of calling an external program to show
  38 them.
  39
  40 Associating files to MIME types
  41 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  42
  43 If the file is fetched from a web server then this web server should tell
  44 ELinks what its MIME type is, so you should have generally no need to care
  45 about it. However, the web server might send an incorrect type, or you may be
  46 retrieving it by FTP or from your local filesystem, so sometimes ELinks needs
  47 to guess it.
  48
  49 The easiest method to guess a MIME type for a file is to just look at its name
  50 trusting it was given the right extension.  ELinks supports this, letting you
  51 to specify a type for any given extension.
  52
  53 Managing a given MIME type
  54 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  55
  56 This usually means specifying programs to open files of this type and the
  57 conditions in which those programs may be used. For instance, you may want to
  58 use zgv (a popular svgalib image viewer) when you are using the text console,
  59 but xli (a image viewer for X) when running the X window system.
  60
  61
  62 Binding it to a handler
  63 +++++++++++++++++++++++
  64
  65 Instead of directly attaching a program to a MIME type, ELinks lets you
  66 associate an abstract handler to each type. Then you can specify which
  67 programs implement the handler and how are they used.
  68
  69 For instance, you may create an image_viewer handler and assign it to MIME
  70 types image/jpeg, image/png and image/gif. Then you would associate to
  71 image_viewer the programs you would like to use for viewing images and the
  72 details on how to use them. This is less cumbersome than repeating all these
  73 details for each MIME type.
  74
  75
  76 Specifying the details for a handler
  77 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78
  79 There are three issues to specify for a handler: the program associated to it,
  80 whether you want confirmation before using it and whether you want the
  81 terminal to be blocked while it is being used.
  82
  83 When specifying any of these issues, you must tell ELinks the situation in
  84 which it gets applied, which is typically either the text console or the X
  85 window system. So you can specify that you don't want confirmation before
  86 running the program when running X, and that you want it otherwise.
  87 Similarly, when you are attaching a program (name it foo) to this handler you
  88 must tell if it's for X or not (you can attach a second program for the other
  89 choice if you want).
  90
  91 Attaching a program to it::
  92
  93         You must tell ELinks the exact command for running it (with any
  94         options you wish). In place of the filename you must enter %.
  95
  96 Choosing whether you want confirmation before applying it::
  97
  98         This is rather simple. If you choose not to do so, then the handler
  99         will be automatically called upon when you demand ELinks to show
 100         something attached to this handler. Otherwise, if you ask for
 101         confirmation, you will be prompted to open it with a external program,
 102         with additional choices that include cancelling the operation and
 103         viewing it with ELinks. E.g: you may use this option for programs
 104         written in C so that you may always choose if you want to read the
 105         source with ELinks, or if you want to save it, or if you want to use
 106         indent to display it with less.
 107
 108 Choosing whether to block the terminal::
 109
 110         If you don't want to allow going back to ELinks (or any other program
 111         from the same terminal) before the external program ends, then you
 112         should ask to block the terminal.
 113
 114
 115 Setting up elinks.conf
 116 ~~~~~~~~~~~~~~~~~~~~~~
 117
 118 If you have old configuration files from old ELinks versions or from Links,
 119 then you may use the conf-links2elinks.pl script (which is placed at
 120 contrib/conv/ on the source distribution) to convert them to the new format.
 121 If you don't use it you will need to edit the configuration file, and here you
 122 will find how.
 123
 124 Associating a file extension to a MIME type
 125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 126
 127 You can still do this with the UI, from the the Setup-&gt;File Extensions
 128 submenu.
 129
 130 If you want to do so from the configuration file, enter set mime.extension.ext
 131 = "type", replacing ext with the appropriate file extension, and type with its
 132 MIME type. E.g. you may want to have set mime.extension.jpg = "image/jpeg".
 133
 134
 135 Defining a handler
 136 ^^^^^^^^^^^^^^^^^^
 137
 138 For each handler you must define three items, specifying in what context the
 139 value of the item should be applied. You must enter set
 140 mime.handler.handler-name.item.context = value, replacing handler-name with
 141 the name for the handler you are defining, item with the item you are defining
 142 for this handler, context with the context this item value is to be applied,
 143 and value with the value you want to assign to the item. You must do so for
 144 each of the available items: program, ask and block.
 145
 146 The value for program is a string with the exact command you want to be issued
 147 to view the file, placing % were you would put the file name. The values for
 148 ask and block are either 0 (no) or 1 (yes). Available contexts include unix
 149 and unix-xwin, which mean UNIX text terminal and X respectively (others can be
 150 os2, win32, beos, riscos, ...). The latter does not mean you are running
 151 ELinks from X, just that the DISPLAY variable is set so that ELinks may run an
 152 X program.
 153
 154 To illustrate it, here is an example. Suppose you want to define the
 155 image_viewer handler which should be used to view images.  The configuration
 156 file may look like this:
 157
 158 --------------------------------------------------------------------------------
 159 set mime.handler.image_viewer.unix.ask = 1
 160 set mime.handler.image_viewer.unix-xwin.ask = 0
 161
 162 set mime.handler.image_viewer.unix.block = 1
 163 set mime.handler.image_viewer.unix-xwin.block = 0
 164
 165 set mime.handler.image_viewer.unix.program = "zgv %"
 166 set mime.handler.image_viewer.unix-xwin.program = "xli %"
 167 --------------------------------------------------------------------------------
 168
 169 In this example the image_viewer handler uses the svgalib image viewer zgv
 170 when X is not available, and the X image viewer xli when it is. The terminal
 171 would be blocked when X is not available and it would not be when it's
 172 available. Finally, ELinks would ask for confirmation before using the handler
 173 only with X not available.
 174
 175 Associating a MIME type to a handler
 176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 177
 178 Just enter set mime.type.class.name = "handler", replacing class with the
 179 class for the mime type, name with the specific name within that class, and
 180 handler with the name for the handler you want to assign to the MIME type.
 181 E.g. you may want to have set mime.type.image.jpeg = "image_viewer".