<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter>
<chapterinfo>
<authorgroup>
<author>
	<firstname>José Luis</firstname>
	<surname>González González</surname>
</author>
<othercredit>
	<firstname>Laurent</firstname>
	<surname>Monin</surname>
	<contrib>
	
	For pointing out the syntax for the mime.type and mime.handler options.

	</contrib>
</othercredit>
<othercredit>
	<firstname>Petr</firstname>
	<surname>Baudis</surname>
	<contrib>

	Suggestion to use the Links to ELinks configuration conversion script
	from the contrib/ directory and in general for keeping up improving
	ELinks.

	</contrib>
</othercredit>
</authorgroup>
<releaseinfo>

	This document was written out of despair due to the lack of
	documentation regarding the new way to configure MIME in recent ELinks
	prereleases. Suggestions, fixes and contributions are welcomed.

</releaseinfo>
</chapterinfo>
<title>Basic instructions for MIME configuration</title>

<sect1><title>Introduction</title>

<sect2><title>What's all this about?</title>
<para>

	At some time along the 0.4 prereleases, ELinks replaced the old Links
	file configuration system with its own one.  Now, the configuration is
	stored in &elinks.conf;, much more complete and featuring a new syntax.
	You can set most options from the <acronym><link linkend="acronym-UI">
	UI</link></acronym> (so usually there is no need to deal with
	<filename>elinks.conf</filename>), and that used to be true for setting
	MIME handlers and extensions as well; but now the associations menu is
	gone temporarily, forcing you to set the handlers from the
	configuration file.

</para>
<para>

	The comments provided within <filename>elinks.conf</filename> for the MIME
	options are not much helpful, and those options may seem a bit obscure
	or confusing at first. This document is a basic introduction to
	setting of MIME associations for ELinks. If you want to know how to
	automatically launch a program to view some kind of file (like images),
	then read on. Some basic knowledge of MIME is recommended.

</para>
</sect2>
</sect1>

<sect1><title>Handling MIME types, the ELinks way</title>

<sect2><title>What are MIME types and why may you want to use them?</title>
<para>

	If, while browsing with ELinks, you need to display files that it can't
	show (like images or PDF documents), then you will likely want to pass
	them to other programs that are suitable for this task.  While you may
	do it manually (saving the file to disk, running the auxiliar program
	to show it and then removing the file when finished), ELinks provides a
	method to do this automatically using MIME types.

</para>
<para>

	ELinks usually knows what the MIME type is for any file (which is a
	kind of description of its format), thus you only need to specify how
	to manage the MIME types for the files you want to open.  If you don't
	tell ELinks how to manage a given MIME type then it will show you on
	screen the contents of the file (as if it was ASCII text) instead of
	calling an external program to show them.

</para>
</sect2>

<sect2><title>Associating files to MIME types</title>

<para>

	If the file is fetched from a web server then this web server should
	tell ELinks what its MIME type is, so you should have generally no need
	to care about it. However, the web server might send an incorrect type,
	or you may be retrieving it by <acronym><link
	linkend="acronym-FTP">FTP</link></acronym> or from your local
	filesystem, so sometimes ELinks needs to guess it.

</para>
<para>

	The easiest method to guess a MIME type for a file is to just look at
	its name trusting it was given the right extension.  ELinks supports
	this, letting you to specify a type for any given extension.

</para>
</sect2>

<sect2><title>Managing a given MIME type</title>
<para>

	This usually means specifying programs to open files of this type and
	the conditions in which those programs may be used.  For instance, you
	may want to use <command>zgv</command> (a popular svgalib image viewer) when
	you are using the text console, but <command>xli</command> (a image viewer
	for X) when running the X window system.

</para>

<sect3><title>Binding it to a handler</title>
<para>

	Instead of directly attaching a program to a MIME type, ELinks lets you
	associate an abstract <property>handler</property> to each type.  Then you can
	specify which programs implement the handler and how are they used.

</para>
<para>

	For instance, you may create an <varname>image_viewer</varname> handler
	and assign it to MIME types <type>image/jpeg</type>,
	<type>image/png</type> and <type>image/gif</type>. Then you would
	associate to <varname> image_viewer</varname> the programs you would
	like to use for viewing images and the details on how to use them.
	This is less cumbersome than repeating all these details for each MIME
	type.

</para>
</sect3>
</sect2>

<sect2><title>Specifying the details for a handler</title>
<para>

	There are three issues to specify for a handler: the program associated
	to it, whether you want confirmation before using it and whether you
	want the terminal to be blocked while it is being used.

</para>
<para>

	When specifying any of these issues, you must tell ELinks the situation
	in which it gets applied, which is typically either the text console or
	<link linkend="explain-X">the X window system</link>. So you can
	specify that you don't want confirmation before running the program
	when running X, and that you want it otherwise. Similarly, when you are
	attaching a program (name it <command>foo</command>) to this handler
	you must tell if it's for X or not (you can attach a second program for
	the other choice if you want).

</para>

<sect3><title>Attaching a program to it</title>
<para>

	You must tell ELinks the exact command for running it (with any options
	you wish). In place of the filename you must enter <option>%</option>.

</para>
</sect3>

<sect3><title>Choosing whether you want confirmation before applying it</title>
<para>

	This is rather simple.  If you choose not to do so, then the handler
	will be automatically called upon when you demand ELinks to show
	something attached to this handler.  Otherwise, if you ask for
	confirmation, you will be prompted to open it with a external program,
	with additional choices that include cancelling the operation and
	viewing it with ELinks.  E.g: you may use this option for programs
	written in <acronym><link linkend="acronym-C">C</link></acronym> so
	that you may always choose if you want to read the source with ELinks,
	or if you want to save it, or if you want to use <command><link
	linkend="explain-indent">indent</link></command> to display it with less.

</para>
</sect3>

<sect3><title>Choosing whether to block the terminal</title>
<para>

	If you don't want to allow going back to ELinks (or any other program
	from the same terminal) before the external program ends, then you
	should ask to block the terminal.

</para>
</sect3>
</sect2>
</sect1>

<sect1><title>Setting up <filename>elinks.conf</filename></title>
<para>

	If you have old configuration files from old ELinks versions or from
	Links, then you may use the <filename>conf-links2elinks.pl</filename> script
	(which is placed at <filename>contrib/conv/</filename> on the source
	distribution) to convert them to the new format.  If you don't use it
	you will need to edit the configuration file, and here you will find
	how.

</para>

<sect2><title>Associating a file extension to a MIME type</title>
<para>

	You can still do this with the <acronym><link
	linkend="acronym-UI">UI</link></acronym>, from the
	<guisubmenu>File Extensions</guisubmenu> submenu found in the
	<guimenu>Setup</guimenu> menu.

</para>
<para>

	If you want to do so from the configuration file, enter

</para>
<screen>
set mime.extension.<userinput>ext</userinput> = "<userinput>type</userinput>"
</screen>
<para>

	replacing <varname>ext</varname> with the appropiate file extension, and
	<varname>type</varname> with its MIME type.  E.g. you may want to have

</para>
<screen>
set mime.extension.jpg = "image/jpeg"
</screen>
</sect2>

<sect2><title>Defining a handler</title>
<para>

	For each handler you must define three items, specifying in what
	context the value of the item should be applied. You must enter

</para>
<screen>
set mime.handler.<userinput>handler-name</userinput>.<userinput>item</userinput>.<userinput>context</userinput> = <userinput>value</userinput>
</screen>
<para>

	replacing <varname>handler-name</varname> with the name for the handler
	you are defining, <varname>item</varname> with the item you are
	defining for this handler, <varname>context</varname> with the context
	this item value is to be applied, and <varname>value</varname> with the
	value you want to assign to the item. You must do so for each of the
	available items: <property>program</property>, <property>ask</property>
	and <property>block</property>.

</para>
<para>

	The value for <property>program</property> is a string with the exact
	command you want to be issued to view the file, placing
	<option>%</option> were you would put the file name. The values for
	<property>ask</property> and <property>block</property> are either 0
	(no) or 1 (yes). Available contexts include <property>unix</property>
	and <property>unix-xwin</property>, which mean UNIX text terminal and X
	respectively (others can be os2, win32, beos, riscos, ...).  The latter
	does not mean you are running ELinks from X, just that the
	<envar>DISPLAY</envar> variable is set so that ELinks may run an X
	program.

</para>
<para>

	To illustrate it, here is an example. Suppose you want to define the
	<varname>image_viewer</varname> handler which should be used to view
	images. The configuration file may look like this:

</para>
<screen>
set mime.handler.image_viewer.unix.ask = 1
set mime.handler.image_viewer.unix-xwin.ask = 0

set mime.handler.image_viewer.unix.block = 1
set mime.handler.image_viewer.unix-xwin.block = 0

set mime.handler.image_viewer.unix.program = "zgv %"
set mime.handler.image_viewer.unix-xwin.program = "xli %"
</screen>
<para>

	In this example the <varname>image_viewer</varname> handler uses the
	<varname>svgalib</varname> image viewer <command>zgv</command> when X
	is not available, and the X image viewer <command>xli</command> when it
	is. The terminal would be blocked when X is not available and it would
	not be when it's available. Finally, ELinks would ask for confirmation
	before using the handler only with X not available.

</para>
</sect2>

<sect2><title>Associating a MIME type to a handler</title>
<para>

	Just enter <userinput>set
	mime.type.<varname>class</varname>.<varname>name</varname> =
	"<varname>handler</varname>" </userinput>, replacing
	<varname>class</varname> with the class for the mime type,
	<varname>name</varname> with the specific name within that class, and
	<varname>handler</varname> with the name for the handler you want to
	assign to the MIME type.  E.g. you may want to have <userinput>set
	mime.type.image.jpeg = "image_viewer"</userinput>.

</para>
</sect2>
</sect1>
</chapter>
