

ELinks Manual ($Revision: 1.3.2.2 $)                              J. Fonseca
                                                               P. Baudis
                                                                L. Monin
                                                              M. Masters
                                                             J. González
                                                             May 2, 2005


                     ELinks Manual for version 0.10


Abstract

   Welcome! This is the entry point for the current humble ELinks
   manual.  It is by no way complete, it is not even very homogeneous
   and it should be eventually superseded by a complete ELinks Book,
   which you can find in the book/ subdirectory in a very prenatal
   stage.

   There was a complete (or from a large part complete) manual for the
   Links 0.82 once, you can still find it at:
   <http://links.sourceforge.net/docs/manual-0.82-en/index.html> While
   large parts of it do not apply anymore, you may still find some
   relevant information there.

   You may also refer to the manual page for a very quick reference,
   however little effort is done to keep it always up-to-date.  On the
   other hand, the built-in documentation is _always_ up-to-date.  Check
   the --long-help and --config-help ELinks command-line arguments.

   Hold harmless the author, and any lawful use is allowed.





















Fonseca, et al.                                                 [Page 1]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


Table of Contents

   1.    Introduction to the World of ELinks  . . . . . . . . . . . .  4
   1.1   Overview of the User Interface . . . . . . . . . . . . . . .  4
   1.2   The Title, Tab and Status bar  . . . . . . . . . . . . . . .  5
   1.3   The Main, Link and Tab Menus . . . . . . . . . . . . . . . .  5
   1.4   The Managers . . . . . . . . . . . . . . . . . . . . . . . .  5
   1.5   Navigation . . . . . . . . . . . . . . . . . . . . . . . . .  7
   1.5.1 Page-Oriented Navigation . . . . . . . . . . . . . . . . . .  7
   1.5.2 Link-Oriented Navigation . . . . . . . . . . . . . . . . . .  8
   1.5.3 Position-Oriented Navigation . . . . . . . . . . . . . . . .  8
   1.5.4 Forms  . . . . . . . . . . . . . . . . . . . . . . . . . . .  9
   1.6   Searching  . . . . . . . . . . . . . . . . . . . . . . . . .  9
   1.7   Hints and Odd Features . . . . . . . . . . . . . . . . . . . 10
   2.    The Ultimate Bookmarks Guide . . . . . . . . . . . . . . . . 11
   2.1   The Bookmark Manager . . . . . . . . . . . . . . . . . . . . 11
   2.2   The Ancient Forests  . . . . . . . . . . . . . . . . . . . . 12
   2.3   Searching needle in the haycock  . . . . . . . . . . . . . . 12
   2.4   File formats . . . . . . . . . . . . . . . . . . . . . . . . 12
   2.4.1 Native file format . . . . . . . . . . . . . . . . . . . . . 13
   2.4.2 XBEL file format . . . . . . . . . . . . . . . . . . . . . . 14
   2.4.3 Usage hints  . . . . . . . . . . . . . . . . . . . . . . . . 14
   3.    The Wonders of Tabbed Browsing . . . . . . . . . . . . . . . 15
   3.1   Introduction to the basic actions involving tabs . . . . . . 16
   3.1.1 The tab bar and the tab menu . . . . . . . . . . . . . . . . 16
   3.1.2 Creating new tabs  . . . . . . . . . . . . . . . . . . . . . 16
   3.1.3 Switching between tabs . . . . . . . . . . . . . . . . . . . 16
   3.1.4 Closing tabs . . . . . . . . . . . . . . . . . . . . . . . . 17
   3.2   Advanced topics involving tabs . . . . . . . . . . . . . . . 17
   3.2.1 Moving tabs  . . . . . . . . . . . . . . . . . . . . . . . . 17
   3.2.2 Saving and restoring tabs  . . . . . . . . . . . . . . . . . 17
   4.    Marks (the lite edition) . . . . . . . . . . . . . . . . . . 17
   4.1   What it is?  . . . . . . . . . . . . . . . . . . . . . . . . 18
   4.2   Restrictions . . . . . . . . . . . . . . . . . . . . . . . . 18
   4.3   Marks lifespan . . . . . . . . . . . . . . . . . . . . . . . 18
   5.    URL Shortcuts in ELinks  . . . . . . . . . . . . . . . . . . 19
   5.1   What it does . . . . . . . . . . . . . . . . . . . . . . . . 19
   5.2   How it works . . . . . . . . . . . . . . . . . . . . . . . . 20
   5.3   Alternative URI rewriting mechanisms . . . . . . . . . . . . 21
   6.    The Terminal Setup . . . . . . . . . . . . . . . . . . . . . 21
   6.1   Options  . . . . . . . . . . . . . . . . . . . . . . . . . . 22
   6.1.1 Terminal type  . . . . . . . . . . . . . . . . . . . . . . . 22
   6.1.2 Color mode . . . . . . . . . . . . . . . . . . . . . . . . . 22
   6.1.3 Switch fonts for line drawing (aka 11m hack) . . . . . . . . 23
   6.1.4 Restrict frames in cp850/852 . . . . . . . . . . . . . . . . 23
   6.1.5 Block cursor . . . . . . . . . . . . . . . . . . . . . . . . 23
   6.1.6 Transparency . . . . . . . . . . . . . . . . . . . . . . . . 23
   6.1.7 Text underlining capability  . . . . . . . . . . . . . . . . 23



Fonseca, et al.                                                 [Page 2]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   6.1.8 UTF-8 I/O  . . . . . . . . . . . . . . . . . . . . . . . . . 24
   6.1.9 Character Set  . . . . . . . . . . . . . . . . . . . . . . . 24
   6.2   Terminal Configurations  . . . . . . . . . . . . . . . . . . 24
   7.    Introduction to MIME handling  . . . . . . . . . . . . . . . 24
   7.1   Handling MIME types, the ELinks way  . . . . . . . . . . . . 25
   7.1.1 What are MIME types and why may you want to use them?  . . . 25
   7.1.2 Associating files to MIME types  . . . . . . . . . . . . . . 25
   7.1.3 Managing a given MIME type . . . . . . . . . . . . . . . . . 25
   7.1.4 Specifying the details for a handler . . . . . . . . . . . . 26
   7.2   Setting up elinks.conf . . . . . . . . . . . . . . . . . . . 26
   7.2.1 Associating a file extension to a MIME type  . . . . . . . . 27
   7.2.2 Defining a handler . . . . . . . . . . . . . . . . . . . . . 27
   7.2.3 Associating a MIME type to a handler . . . . . . . . . . . . 28
   8.    Managing External Viewers with Mailcap . . . . . . . . . . . 28
   8.1   A Short Intro to Mailcap . . . . . . . . . . . . . . . . . . 28
   8.2   Parameters to Mailcap Entries  . . . . . . . . . . . . . . . 28
   8.3   Reading of Mailcap Files . . . . . . . . . . . . . . . . . . 29
   8.4   Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
   8.5   Mailcap Configuration  . . . . . . . . . . . . . . . . . . . 30
   8.6   Some Sample Mailcap Entries  . . . . . . . . . . . . . . . . 30
   9.    The tale of ex-mode  . . . . . . . . . . . . . . . . . . . . 30
   9.1   What it is . . . . . . . . . . . . . . . . . . . . . . . . . 31
   9.2   Configuration directives in exmode . . . . . . . . . . . . . 31
   9.3   Actions in exmode - or exmode in action? . . . . . . . . . . 32
   9.4   How to use it  . . . . . . . . . . . . . . . . . . . . . . . 32
   9.5   The "but"s . . . . . . . . . . . . . . . . . . . . . . . . . 32
   10.   Managing remote ELinks instances with -remote  . . . . . . . 32
   10.1  Limitations and outstanding issues . . . . . . . . . . . . . 33
   10.2  Remote Actions . . . . . . . . . . . . . . . . . . . . . . . 33
   11.   Acknowledgement  . . . . . . . . . . . . . . . . . . . . . . 34
   12.   References . . . . . . . . . . . . . . . . . . . . . . . . . 34
         Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 34



















Fonseca, et al.                                                 [Page 3]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


1.  Introduction to the World of ELinks

   The goal of this introduction is to explain the basic concepts in
   ELinks, give an overview of how to get started and serve as an entry
   point to many of the (undocumented) features of ELinks.  It won't
   tell you all the details, but should hopefully give you an idea of
   how things work and make it possible for you to even figure out how
   to go further.

   Allthough ELinks is text-based, the user interface has many of
   interaction methods normally found in graphical environments.  There
   are menus, dialogs with buttons and hierarchic list boxes with
   folders.  Care has been taken to make the interaction between various
   dialogs consistent, so the controls will quickly become familiar to
   new users.

   The user interface can be controlled using both mouse and keyboard,
   but currently it is only possible to configure keybindings.  Looking
   back, the key-controls have been more advanced than the mouse
   support, but during the 0.10 prereleases the mouse support has been
   much improved.  You will now find find stuff like contextual menus
   when right-clicking in different document zones.

1.1  Overview of the User Interface

   The main user interface of ELinks consists of the document view and
   dialog bars displaying the information such as the title of the
   currently viewed document, all opened tabs and the browsing status.
   The 3 bars are elaborated further below.

   The most important dialogs that you will meet include the Main, Link
   and Tab menus and the different managers.  The menus serve as entry
   points to the actions available from different contexts, while the
   managers let you check the state and control the various subsystems,
   such as loaded cookies and the global history.  The utility menus and
   the manager tools are investigated further below.

   The document viewer in ELinks provides a feature-rich set of ways to
   browse documents.  That is, multiple options exist for navigating,
   searching and displaying documents and you will hopefully figure in
   time what works best for you.  The basic browsing possibilities are
   presented below.

   ELinks is highly configurable, so if there is something that you
   would like to change, it is most likely possible.  The best overview
   of the many options are given in the elinks.conf(5) man page.
   Keybindings are discussed in the elinkskeys(5) man page.  It is not
   always up-to-date, so you should also check the keybinding manager



Fonseca, et al.                                                 [Page 4]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   and the overview of all the configured keybindings given in the Help
   -> Keys dialog.  The Keys dialogs serves as a good introduction to
   the most common keybindings.

1.2  The Title, Tab and Status bar

   The title bars main purpose is to display the title of the current
   document.  Documents bigger than can be displayed with the current
   screen size are divided into subpages.  In this case the current
   document position is indicated in the far right of the title bar as a
   suffix to the actual document title.  The syntax is: (
   current-subpage / total-subpages ), an example is "(4/9)" that
   indicates the 4th subpage of 9 subpages.

   The tab bar by default is only visible when 2 or more tabs are open.
   It is divided into slots containing the trimmed title of the tabs'
   loaded document.  Between each tab is a separator.  The current tab
   is highlighted and all tabs that has not been viewed after being
   loaded are highlighted as fresh.  Tabs are explained in details in
   the tabs.txt file.

   The status bar has multiple purposes.  Most of the time it will
   contain the URI (and title) of the currently selected link.  If a
   link is followed, connection information is shown in the status bar.
   When using cursor routing, the status bar will show the coordinates
   of the cursor when a link is not followed.

1.3  The Main, Link and Tab Menus

   The Main Menu gives you access to many of the features of ELinks via
   submenus and serves as a good entry point for performing actions on
   the different objects of interest, such as links, documents and tabs.
   The Link menu and Tab menus are more specialized and targeted to a
   specific context, such as link handling or managing the tab bar.
   Actually, the Link Menu is accessible from the Main Menu as a
   submenu.

   Once you have familiarized yourself with the menus, you will have a
   good chance at gradually learning the most common keybinding, since
   all the configured keybindings are shown as right aligned text.  Menu
   entries can also be quickly accessed using hotkeys.  Hotkeys appear
   highlighted in the menu entry text.  For example the key-combo "Alt-v
   i" will open the document info dialog accessible from the View sub
   menu in the Main menu.

1.4  The Managers

   The managers let you control the state of subsystems, such as cookies



Fonseca, et al.                                                 [Page 5]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   and the global history.  They are accessible from the Tools or Setup
   submenu in the Main Menu.  The managers consists of an area showing a
   hierarchic listbox and buttons at the bottom.  Below, a view of the
   cookie manager is shown.


   +------------------------- Cookie manager -------------------------+
   |                                                                  |
   |   [-]- bugzilla.elinks.or.cz                                     |
   |    |    |-- BUGLIST                                              |
   |    |    `-- LASTORDER                                            |
   |   [+]- kerneltrap.org                                            |
   |   [+]-*dictionary.reference.com                                  |
   |   [+]-*bjork.com                                                 |
   |   [-]- www.google.com                                            |
   |         `-- PREF                                                 |
   |                                                                  |
   |                                                                  |
   |                                                                  |
   |                                                                  |
   |   [ Info ]  [ Add ]  [ Edit ]  [ Delete ]  [ Save ]  [ Close ]   |
   +------------------------------------------------------------------+

   Each item is either a folder or a leaf.  A folder is displayed with a
   "[-]" or "[+]" before the name telling whether the folder is
   currently open or closed.  Nested items are displayed indented
   compared to the folder they are nested in.  In the cookie manager
   example above "bjork.com" is a folder and "PREF" is a leaf.

   Items can be "marked", which makes it possible to select a group of
   items and perform an action on them, such as deleting all marked
   items.  If any item has been marked the currently selected item is
   ignored when performing the action.  Marked items are displayed with
   an asterics ('*') prefixing the name.

   The buttons make it possible to perform actions either on selected or
   marked items or on all items in the manager.  Buttons named "Clear"
   and "Save" are performed on all items; "Clear" will delete all items
   and "Save" will update the runtime state file associated with the
   manager in the ~/.elinks/ directory.  Most buttons presses will query
   you before completing the action.

   At any time, both the currently selected item and button are
   highlighted.  The same goes for marked items.  Most manager dialogs
   also maintains the state, so that when you reopen the manager later
   it will have the same items selected and the same folders opened or
   closed.




Fonseca, et al.                                                 [Page 6]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   The basic default controls for managers are the following:

   +---------------------+---------------------------------------------+
   | Keys                | Action                                      |
   +---------------------+---------------------------------------------+
   | Up/Down             | Select the item above/below.                |
   | '*'                 | Toggle marking of a item.                   |
   | Space               | Open and close folders.                     |
   | Left/Right          | Select the button to the left/right.        |
   | Home/End            | Select the first/last item.                 |
   | Enter               | Press the currently selected button.        |
   | Esc                 | Close the manager dialog.                   |
   +---------------------+---------------------------------------------+

   Some managers also supports searching, either by pressing the "[
   Search ]" button or by pressing '/'.  By searching the empty string,
   all hidden items from the previous search will be shown again.

1.5  Navigation

   ELinks provides various ways to navigate documents.  Depending on how
   documents are structured, it can be a great help to change navigation
   style.  The navigation styles can roughly be divided into
   page-oriented, link-oriented and screen-oriented.  They overlap in
   many ways, so this separation is mostly used as a mean to present
   them.

1.5.1  Page-Oriented Navigation

   This involves scrolling documents horizontally and vertically.
   Documents can be scrolled page-wise, where the next or previous
   subpage will be displayed.  It is also possible to scroll documents
   in steps, either line-wise (vertically) or column-wise
   (horizontally).  The step size can be configured and by default is 2
   lines and 8 columns.  Alternatively, whole documents can be scrolled
   to the start or the end.

   The basic default controls:

   +---------------------+---------------------------------------------+
   | Keys                | Action                                      |
   +---------------------+---------------------------------------------+
   | Insert/Delete       | Scroll up/down line-wise. (vertically)      |
   | PageUp/PageDown     | Scroll up/down page-wise.                   |
   | '['/']'             | Scroll left/right column-wise.              |
   |                     | (horizontally)                              |
   | Home/End            | Scroll to the start/end of the document.    |
   +---------------------+---------------------------------------------+



Fonseca, et al.                                                 [Page 7]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


1.5.2  Link-Oriented Navigation

   For hypertext documents, access to the links makes it more practical
   to navigate by jumping between links in the document.  There are two
   ways to do this; either you can move between links relationally or by
   number.  Using relational link navigation it is possible to focus the
   next/previous link or move in a directional manner to the link in a
   certain direction such as left/right/up/down.

   In order to navigate using link numbers, you have to first toggle
   link numbering on; this will prefix all links with a number using the
   notation [number].  "[23]" indicates link number 23.  When link
   numbering is enabled, pressing any number key will pop up a "Go to
   link"-dialog where the complete link number can be entered.  By
   pressing Enter the entered link number will be focused, but only if
   it is a valid link number.

   Note: it is also possible to jump to links by searching the link
   text; check the documentation on searching.

   The basic default controls:

   +---------------------+---------------------------------------------+
   | Keys                | Action                                      |
   +---------------------+---------------------------------------------+
   | Up/Down             | Move to the previous/next link.             |
   | '.'                 | Toggle link numbering.                      |
   | Enter/Right         | Follow the current focused link.            |
   +---------------------+---------------------------------------------+

   No keys are by default configured for directional link navigation.

1.5.3  Position-Oriented Navigation

   Positional navigation (sorry, bad word) uses the either the position
   of the cursor or the mouse click to navigate the document.  If you
   are familiar with the w3m text-browser you will be familiar with
   cursor routing.  Basicly, you move the cursor around -- kind of like
   a mouse -- in the document area of the user interface.  When the
   cursor is over a link, the link is highlighted, and when the cursor
   moves outside the current document view, it will cause the document
   view to scroll.

   The possibilities when using the mouse to navigate the document
   depend on what terminal you are using.  In some terminals, it is
   possible to scroll by using the mouse wheel.  Scrolling is however
   also possible by clicking in the edge areas of the document view.
   Highlighting links can be done by clicking on a link but waiting to



Fonseca, et al.                                                 [Page 8]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   release the mouse button until the link is no longer under the mouse
   pointer.

   No keys are by default configured for cursor routing.

1.5.4  Forms

   The status bar will indicate the type and name of the field.

   Input text/Password fields: These will be displayed as "________".
      Note that passwords will be obscured using "*" characters.  Status
      bar will display something like "Text field, name q", or "Password
      field, name password" for password fields.

   Textarea boxes: These will be displayed as multiple lines consisting
      of "_".  Status bar will display something like "Text area, name
      comment"

   Buttons: These will be displayed as "[ Go ]".  Status bar will
      display something like "Submit form to ...", "Post form to ..."
      for submit buttons.

   Checkboxes: These will be displayed as "[ ]" or "[X]".  Status bar
      will display something like "Checkbox, name c, value 1".  To set
      one just press ENTER on it.

   Radio buttons: These will be displayed as "( )" or "(X)".  Status bar
      will display something like "Radio button, name radio1".  To set
      one, you may use ENTER.

   Select lists: These will be displayed as "[first item____]".  Note
      that if multiple attribute is used, these are displayed as a group
      of checkboxes instead.  Status bar will display something like
      "Select field, name list" To select one entry, press ENTER, then
      navigate using UP/DOWN, then press ENTER again.


1.6  Searching

   Searching is by default available by pressing '/'.  This will open a
   search dialog with a input text field for entering the search terms
   and checkboxes to control how searching is performed.  You can
   indicate whether matching should be case sensitive and whether
   regular expressions or normal searching should be used.

   It is also possible to make an incremental search, also called
   type-ahead searching.  You can search either the whole document text
   or only link text.  The latter can be useful if you see a link deep



Fonseca, et al.                                                 [Page 9]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   inside a page and want to get to it quickly.

   Matches of the search term will be high-lighted.  After having
   performed document text search all matches will be high-lighted.  To
   get rid of this high-lighting you have to ``search for the empty
   string'', that is open a search dialog and just press Enter in the
   input field.

   Previous search words are saved in the search history, so they can
   easily b found and used later.  Browsing the history will replace the
   current entered search terms.

   The basic default controls for searching are the following:

   +---------------------+---------------------------------------------+
   | keys                | action                                      |
   +---------------------+---------------------------------------------+
   | '/'                 | Open search dialog                          |
   | '?'                 | Open search dialog for backwards searching  |
   | '#'                 | Start incremental link text search          |
   | '#/'                | Start incremental document search           |
   | 'n'/'N'             | Show next/previous match                    |
   | Tab                 | Show next match (only for incremental       |
   |                     | searching)                                  |
   | Up/Down             | Insert previous/next search word from       |
   |                     | history (only when the input field is       |
   |                     | selected)                                   |
   +---------------------+---------------------------------------------+


1.7  Hints and Odd Features

   Note: This is still a work in progress and from here on an below
   everything is marked TODO!

   o  Numerical action prefixes.  Example: 3<Down> jumps down three
      links.

   o  How to move forward in the document history ('u').

   o  Toggling color modes, plain/html and image link rendering.

   o  Link numbering.

   o  Insert mode in text-input form-fields.

   o  Menu searching.




Fonseca, et al.                                                [Page 10]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


2.  The Ultimate Bookmarks Guide

   Glad to see you again, mortal.  Now, we are going to learn about
   bookmarks - how to use them, how to maintain them, and also something
   more about the file formats and maybe even about the code structure
   later.  But don't fear, we won't burden you with it, just stop
   reading when you already know enough.

   In order to read this, you need some common sense, the ability to
   start ELinks and some idea about what's a Web document, a URL address
   and knowledge like that.

   If we ever mention some keys here, please note that you can rebind
   almost any action to another key which you like more - then you must
   obviously imagine your own key in place of that.  Below, we will list
   all actions, options and so on related to bookmarks.  We won't tell
   you how to rebind the keys, though; another document will take on
   that.

   Somewhat out-of-order, a very frequent FAQ: In order to move
   bookmarks around, you need to mark them first - press Insert or '*'
   (if you use the default keymap) to do that.

2.1  The Bookmark Manager

   Basically, almost everything is going on in the so-called bookmark
   manager.  That's a special dialog window, which contains a listing of
   all the bookmarks you ever told ELinks to remember and it lets you to
   do with them anything you would ever want to do with them.

   You launch the bookmark manager by pressing the 's' key in standby
   (standard) mode.  You should see a big empty space (bookmarks will
   slowly appear there as you will add them) and couple of buttons
   shriveling at the bottom.  So, as a start, move with the right (or
   left; both will do) arrow to the button "Add bookmark" and fill in
   the input fields it offers to you.  I mean, you can type something
   like "ELinks homepage" to the first field, then move down by e.g.
   the down arrow and fill "http://elinks.or.cz/" to the second field.
   Then, bravely press enter and watch the bookmark popping up at the
   top of the vast area reserved for bookmarks.

   Repeat this step few times.  Now, you can move between bookmarks by
   the up and down arrow, jump to the location any of them points to by
   the Goto button, change it by the Edit button, delete it with the
   Delete button and so on.  When you'll become bored, press the escape
   button and you're free again!

2.2  The Ancient Forests



Fonseca, et al.                                                [Page 11]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   It's not very convenient to have all the bookmarks mixed up - soon,
   you will get lost in them.  Thus, in ELinks you can categorize them
   to various folders, subfolders, subsubfolders and so on, then you can
   expand and back enfold them and so on.

   In order to create your first folder, use the button "Add folder" and
   fill the first input field.  You can safely ignore the URL field,
   ELinks will do the same.  *POOF* and you see it - it has that strange
   [+] or [-] thing there.  If it has [+] near, it's enfolded, while
   when it has [-] near, it is expanded, while you can change that by
   pressing the spacebar.

   In order to add a bookmark into a folder, move on the item of the
   folder (it must be expanded) or onto any bookmark inside of the
   folder and simply do the usual "Add bookmark" job.  You can also move
   the bookmarks around, obviously.  You need to first mark all the
   bookmarks (or even folders) you want to move using the Insert or '*'
   key--asterisk will appear near of all marked bookmarks--and then move
   to where you want to have the stuff moved to, and press the "Move"
   button.

   Separators can be inserted as well, using "Add separator" button, or
   by entering a special bookmark with "-" as title and no url.

2.3  Searching needle in the haycock

   Of course, you can search in the bookmarks.  Just use the "Find"
   button - for convenience, you have the current document's URL and
   title pre-filled there, and for convenience only
   up-up-enter-down-down sequence is enough to have the playground
   clean.  Then, just fill a substring of what you are looking for, and
   the bookmarks will be filtered so that only the matching ones are
   shown.  (Actually, currently it will not be filtered but the cursor
   will only jump to the first matching bookmark below the current
   cursor position - and it will NOT wrap around.  The exact behaviour
   changes time by time and hasn't been stabilized yet.)

2.4  File formats

   ELinks supports two bookmark formats: the native format and a generic
   bookmark exchange format called XBEL.  Each of those formats has its
   pros and cons, which we shall discuss below.  You can switch between
   then by changing the option bookmarks.file_format.

   However, first please note that ELinks CANNOT read Links bookmarks
   directly.  Importing Links-0.9x (or Links-1.x) bookmarks is easy - it
   is just matter of changing all the '|' (pipe) characters to tabs.
   There is a script for that in the contrib/conv/ directory.  Importing



Fonseca, et al.                                                [Page 12]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   Links-2.xx bookmarks is not so easy; in fact, the scribe knows of no
   way of doing that at the time of writing this, so this is up to you
   to figure out (if you do, please tell us so that we can add it here).
   Perhaps you might find a way to convert Links2 bookmarks to the XBEL
   format, which can then be loaded in ELinks.

2.4.1  Native file format

   This is the preferred bookmarks format, which is also used by
   default.  The bookmarks file is ~/.elinks/bookmarks, in a simple
   format:

   	<name> '\t' <url> [ '\t' <depth> ['\t' <flags>]] '\n'

   '\t' represents a tab character, '\n' represents a newline character.
   [Square brackets] denote optional parts.  The <name> and <url> fields
   should be obvious.  <depth> contains the depth level of the entry -
   by that, ELinks can unambiguously figure out the bookmarks hierarchy:


   	Bookmarks structure:                                Depth:
   	 ,-- The Pasky's C Bestiary                         0
   	[-]- Wonderful things                               0
   	 |    |-- Christmas Carol in l33tsp34k by L.M.      1
   	 |   [-]- Beautiful Potato Camera Shots             1
   	 |   [-]- Gallery of Scary Images of Jonas Fonseca  1
   	 |         |-- Jonas torturing gdb                  2
   	 |        [-]- Urgh                                 2
   	 |         |    `-- Jonas consuming Tofu            3
   	 |         `-- Jonas with crashed ELinks            2
   	 |-- Slides from Witek's hack-patch show            0
   	 `-- Miciah's English Grammar Spellbook             0

   <flags> is a string of characters.  Currently, two flags are
   supported:

   E: This folder is currently expanded.  (No effect for non-folders.)

   F: This entry is a folder.  The <url> part is usually empty.

   Separators: these are special bookmarks with "-" as title and no url.

   Pros: Naturally, ELinks handles the native format the best, easiest
   and most reliably.

   Cons: It is unlikely that you could use the native format anywhere
   else than in ELinks.




Fonseca, et al.                                                [Page 13]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   To use the native format, set bookmarks.file_format = 0.

2.4.2  XBEL file format

   The XBEL file format support was added at some point during the 0.4
   development by Fabio Boneli.  It has never been complete and has
   plenty of troubles, but generally, it works at the basic level.  The
   bookmarks file is ~/.elinks/bookmarks.xbel (thanks to a different
   filename, you can have both XBEL and native bookmarks saved in your
   ~/.elinks directory).

   We shall not describe the XBEL file format here,
   <http://pyxml.sourceforge.net/topics/xbel/> is the authoritative
   resource on that.  It also contains list of some of the applications
   supporting the format.  Basically, you will be probably able to
   convert from/to the XBEL format to/from most of the other widely used
   formats, so this way you can import your bookmarks to ELinks from
   basically anything.

   Pros: XBEL is the gateway to the rest of the bookmarks world.

   Cons: The support for XBEL is incomplete and there are known bugs.
   Especially, national character sets are basically not supported, so
   ELinks will most likely get it wrong if you have any non-ASCII
   characters in your bookmarks.  Generally, the XBEL support should be
   considered experimental and you shouldn't rely on it.  It *could*
   trash your XBEL bookmarks file so make regular backups.

   To use the XBEL format, set bookmarks.file_format = 1.

2.4.3  Usage hints

   As already noted above, probably the best usage pattern is to use
   XBEL for importing/exporting your bookmarks to/from ELinks and the
   native format for regular operation.  Of course, if you want to
   synchronize your bookmarks in ELinks and some other XBEL-supporting
   gadget and you are brave, you can use XBEL as your exclusive bookmark
   format - the choice is upon you.

   Regarding the bookmarks synchronization, there is one important note.
   ELinks saves your bookmarks each time you added one through the 'a'
   shortcut (add-bookmark action) or when closing the bookmarks manager
   if you made any changes or when quitting ELinks.  However, ELinks
   reads your bookmarks only _ONCE_, during the startup.  This behaviour
   may change in the future (tell us if you need a way for ELinks to
   re-read the bookmarks file), but this is how it is done now.

   Actually, you may now ask "So how do I convert bookmarks between the



Fonseca, et al.                                                [Page 14]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   two formats?".  It is quite easy.  ELinks simply follows the current
   value of bookmarks.file_format whenever loading/saving the bookmarks.

   So, e.g.  if you normally use the native format but you want the
   bookmarks to be saved in the XBEL format once, change
   bookmarks.file_format to 1, then cause the bookmarks to be resaved
   (e.g.  by doing some simple change, like adding a trailing space to
   some bookmark's title or so), then change the bookmarks.file_format
   value back to 0.

   It is a little more complicated if you normally use the native format
   but you want to import bookmarks from the XBEL format once.  You
   again change bookmarks.file_format to 1, then cause the bookmarks to
   be reloaded.  That involves saving the configuration, quitting ELinks
   _completely_ (that means closing/killing all instances of it you have
   running), then restarting it and changing bookmarks.file_format to 0.
   Then save the configuration again and cause ELinks to resave the
   bookmarks.

   Agreed, this all strange dances are quite clumsy, likely some simple
   wizard-like interface for switching the bookmarks formats will be
   introduced in the future.  So far, we have had no reports from our
   users that anyone wants to switch their bookmarks format frequently,
   so this is not too high on our TODO list.  So be sure to tell us if
   you would like this process to be simplified rather sooner than
   later.

3.  The Wonders of Tabbed Browsing

   In this information age with our stream of consciousness constantly
   being dispersed by links to different resources on the Net, it is a
   challenge to keep track of where you are going.  The need for being
   able access several pages in parallel arises.  Tabbed browsing gives
   you an easy way to browse multiple sites in parallel.

   If you are not already familiar with the concept of tabbed browsing
   you can think of a tab as a separate browsing context with its own
   history and the various other browsing state information, like search
   word and document loading.  Whenever you stumble upon a link to a
   document that you want to follow without leaving the current
   document, you can open it in a new tab.  This makes it possible to
   more easily jump between pages on the Net and removes the need for
   running more than one ELinks to do that.

   Options related to tabs are located under ``User Interface -> Window
   Tabs'' in the option manager.  In the configuration file the naming
   prefix is ``ui.tabs''.




Fonseca, et al.                                                [Page 15]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   Tabbed browsing has been supported since version 0.9.0 and is fairly
   complete.  The documentation on tabs is therefore divided into two
   chapters: a general introduction and an introduction to advanced
   topics.

3.1  Introduction to the basic actions involving tabs

3.1.1  The tab bar and the tab menu

   The current state of all opened tabs are displayed in the tab bar.
   The tab bar will by default become visible when more than one tab is
   open, but this is configurable.  For each open tab, the document
   title will be shown, possibly truncated.  The current tab is
   highlighted.  The tab bar will also display a load meter for tabs
   that are loading documents.  Finally, any tab that has not been
   selected since its document was loaded will be marked as ``fresh'' by
   using a different coloring scheme.

   The tab menu gives access to tab specific actions along with some
   other useful document specific actions.  So even if you haven't
   configured keybindings for all actions, chances are you will find it
   in the tab menu.  It is by default opened by pressing 'e'.

3.1.2  Creating new tabs

   When creating new tabs, it is possible to specify whether to create
   the tab and make it the current active tab or if the tab is to be
   created ``in the background''--that is, without it taking over the
   focus.

   Tabs can be created either with or without specifying a desired first
   document to load.  That is, you can open links or submitted forms in
   a new tab or just open a new tab.  Depending on your configuration,
   the latter will load the configured homepage in the newly created tab
   or simply leave the tab blank with no loaded document.

   By default, 't' will open a new tab and 'T' will open the current
   link in a new backgrounded tab.  You can configure keybindings for
   opening a new tab in the background and opening the current link as
   the active tab.

3.1.3  Switching between tabs

   By default, it is possible to switch between tabs by using '<' and
   '>' to select the previous and next tab.  When currently positioned
   at the leftmost tab and switching to the previous tab the switching
   between tabs will perform a wrap-around so that the rightmost tab
   will be selected.  The wrap-around behaviour is configurable.



Fonseca, et al.                                                [Page 16]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


3.1.4  Closing tabs

   Tabs can by default be closed by pressing 'c'.  It is possible to
   optionally have a confirmation dialog pop up when closing a tab to
   avoid accidental closing.  To complement closing of the current tab,
   it is also possible to close all tabs but the current one.  No key is
   by default configured for this; the tab menu, however, provides this
   ability.

   Note: downloads initiated from a tab are in no way tied to that tab,
   so tabs can be closed while the download will be unaffected.

3.2  Advanced topics involving tabs

3.2.1  Moving tabs

   Newly created tabs are always positioned as the rightmost tab, but it
   is possible to move the current tab either to the left or the right.
   The default keybindings have them bound to Alt-< and Alt->.  Note,
   however, that there are problems recognizing those kaybindings when
   using XTerm, so you might want to rebind them.

3.2.2  Saving and restoring tabs

   Several features use bookmarks to save tabs; they will create a
   folder and bookmark therein the currently displayed document of each
   tab:

   o  You can explicitly command all tabs to be bookmarked.  This will
      ask you for a folder name in which the tabs will be bookmarked.

   o  At startup and shutdown tabs can automatically be bookmarked in
      order to save and restore the browsing state.  Note that when
      restoring, all history information will be gone.  It is possible
      to configure both tab saving and restoring via options in ``UI ->
      Sessions''.

   o  As a mean of crash protection, tabs can periodically be saved so
      that it is later possible to reconstruct opened tabs.  In case of
      a clean shutdown periodically saved tabs will be removed.


4.  Marks (the lite edition)

   So, were you ever reading this huge 300-pages specification heavily
   cross-referencing itself, jumping around and getting a headache when
   looking for the place where you stopped reading the last time?




Fonseca, et al.                                                [Page 17]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   Were you doing something similar in C code, but praising *vi* for
   document marks?

   ELinks can do them, too! For vim non-users:

4.1  What it is?

   When you place a "document mark" (just "mark" from now on), you place
   an _invisible_ anchor at the current position in the document.  You
   can place several such marks --- each mark is identified by a single
   character (any reasonable character will do).  Then, you can just
   happily browse around aimlessly (but see below) and when in the same
   document again, you can return to any of the marks in the file again.
   That will restore your position in the file at the time of placing
   the mark.

   You can place a mark by the "m" key followed by the mark character.
   You can go to a mark by the "'" (apostrophe) key followed by the mark
   character.  E.g., you can place a mark named "a" in the file by
   pressing "ma", then return to it anytime later by typing "'a".  You
   can of course change those shortcuts at any time to anything you wish
   in the keybindings manager.

   Short summary: you can place a mark (e.g.  'z') in a document by
   pressing "mz" and then go back to it anytime later by pressing "'z".

4.2  Restrictions

   To make a good start, one non-restriction comes first.  The document
   marks are local to the document.  That means you can have a mark "x"
   in one document and another mark "x" in another document and ELinks
   won't mind and it will get it right each time.

   Now for the restrictions.  ALL the document marks are always local to
   the document.  I.e.  the vim text editor has an extension that makes
   the capital-letter marks to be global to the whole program and going
   to such a mark will make it to open the right document.  This is not
   implemented in ELinks _yet_.

   Contrary to vim, ELinks doesn't support numbered marks (jumping to
   the last n documents in history) nor the special "'" mark (jumping to
   the last mark).  Yet.

   There is no way to get a listing of all marks set in a document.
   Yet.

4.3  Marks lifespan




Fonseca, et al.                                                [Page 18]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   I already hinted something about another restriction regarding
   aimless browsing.  The lifespan of document marks depends on rather
   ill-defined and (for an average mortal) mostly non-deterministic
   technical conditions.

   Generally, marks _always_ survive when not moving away from the
   document or when moving only in the session history (and unhistory).
   That means, if you go back and the "unback" to the document, you will
   find your marks safely in place.  If you follow a link from the
   document (or typed an address to the Goto URL dialog) and then go
   back (by pressing the right arrow or through the File menu), your
   marks are safe too.  These are in fact by far the most common usage
   cases for the marks, so most of the time it will just work as you
   expect.  That's a good news.

   The bad news is that in all other cases, nothing is guaranteed.  It
   might work if you get back to the document by any other means (by
   following some link or typing its address to the Goto URL dialog), or
   it might not.  It might be possible to achieve two instances of the
   document inside a single ELinks, each with its own set of marks.
   However, again, generally it will work as expected - this paragraph
   serves only as a disclaimer in cases it doesn't.  Don't rely on it.

   Marks never survive over ELinks restarts.  If you quit your ELinks
   completely and run it again, the marks you placed will be no more.
   No exceptions.  Well.  In some cases, it *might* appear that they
   survived, but that just means you did not quit your ELinks
   _completely_ --- if you run multiple ELinks instances under a single
   user on a single system, they "join" together and you must quit (or
   kill) them all to get rid of the damn thing.  But that's a different
   story.

5.  URL Shortcuts in ELinks

   One extremely useful and convenient feature on ELinks which is
   presumably not very well known is so-called URL rewriting.  If you
   give ELinks a URL (by passing it on the command line, through the
   -remote magic device or most frequently by typing it to the Goto URL
   dialog), it can mangle it in certain ways before processing it.  This
   mangling is called URI rewriting.

5.1  What it does

   The URI rewriting can expand certain URL shortcuts to complete URLs.
   For example, if you type 'sd' to the Goto URL dialog, it will get
   rewritten to

   		http://www.slashdot.org/



Fonseca, et al.                                                [Page 19]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   first, then loaded --- /.'s front page will be displayed.

   More so, if you type 'g elinks' to the Goto URL dialog, it will be
   rewritten to

   		http://www.google.com/search?q=elinks&btnG=Google+Search

   and then loaded --- therefore, a Google search for the 'elinks'
   keyword will ensue.  Note that you can separate the 'g' by either a
   space or a colon, so 'g:elinks' will do the exact same thing.

   A large number of those shortcuts is already predefined.  You can
   browse the Protocols :: URI Rewriting :: Dumb/Smart prefixes in the
   Options Manager for complete listing of already defined shortcuts
   (press the [Info] button on a shortcut to see what it gets rewritten
   to).  See below for details on how to enable/disable this rewriting
   and how to define own shortcuts.

5.2  How it works

   All the URI rewriting can be controlled by options in the
   'protocol.rewrite' options tree.

   In the 'sd' case, URI rewriting mechanism called 'dumb prefix' is
   used.  If protocol.rewrite.enable-dumb is true, ELinks looks at the
   contents of protocol.rewrite.dumb tree, and if it finds option
   protocol.rewrite.dumb.sd, it will use its value as the target URI.

   Therefore, in the general way, if ELinks looks at
   protocol.rewrite.dumb.<typed_string> and if it exists, it replaces
   the URI with it.  These dumb prefixes can be used as kind of
   alternative bookmarks - if you want to have a fast access to a
   certain site and you don't want to spend lengthy seconds navigating
   in the bookmarks manager, you can just fire up the Goto URL dialog,
   type the shortcut and there you go.

   A dumb prefix can contain '%c', which will be replaced by the URI of
   the current document.  This is used, for example, in the 'arc'
   dumb-prefix, which provides a shortcut to the Wayback machine at
   archive.org.

   In the 'g' case, a slightly different URI rewriting mechanism called
   'smart prefixes' is used.  If protocol.rewrite.enable-smart is true,
   ELinks looks at the contents of protocol.rewrite.smart tree and if it
   finds option protocol.rewrite.smart.g, it will use its value as the
   target URI.

   The difference is that the smart prefixes can take arguments and



Fonseca, et al.                                                [Page 20]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   reference them in the target URI.  As with dumb prefixes, '%c' in the
   URI means the current address.  Additionally, '%s' will be
   substituted by the whole string following the prefix ('elinks' in the
   'g' example above; '%s' is by far the most frequently used
   expansion), while you can reference individual space-separated
   arguments with the codes '%0' thru '%9'.  Finally, if you want a
   plain % to the resulting URI, use '%%'.

   Note that the prefix searched in the protocol.rewrite.smart tree is
   everything in the typed address up to the first space or colon (so
   'bug:123' and 'bug 123' make no difference).  These prefixes are
   generally useful for searching anything very fast - be it Google
   ('g:foo', 'gi:foo', 'gr:foo', ...), ELinks Bugzilla bugs
   ('bug:1234'), RFC database ('cr:foo'), or Czech-English dictionary
   ('czen:foo').  But only your imagination is the limit.

5.3  Alternative URI rewriting mechanisms

   In the past before this was implemented, Lua scripting did the job.
   And you still have complete control over the URI in the internal
   scripting goto-url hook.  The advantages are clear - you get complete
   control over the URI and you can do much more interesting things with
   it (e.g., there is some very advanced CVSweb and Debian packages
   database URIs prefixes support in the sample Lua hooks file).  One
   disadvantage is clear too - you must have Lua scripting enabled in
   order to make use of this, and many users don't have Lua installed.
   Another hidden disadvantage is that the goto-url hook is not
   triggered all the times when the built-in URI rewriting has its say
   on the URL.  Specifically, the goto-url hook isn't triggered when the
   URL is passed on the command line.

6.  The Terminal Setup

   ELinks uses neither (n)curses nor termcap/terminfo, so unless you are
   using a terminal that is known by ELinks and have a built-in
   configuration (see below for a list), it might be required that you
   do a little configuring of how your terminal should be handled.  The
   easiest way to do this is using the Terminal Options dialog located
   in the Setup submenu of the Main menu.

   It is possible to have configurations for multiple terminals as long
   as the TERM environment variable -- used to distinguish terminals
   from one another -- is set to something different for each terminal.
   So be sure to set TERM to different values for two terminals that
   cannot share the same configuration.  For example, always setting
   TERM to xterm-color can lead to problems if you run ELinks under the
   Linux console.  This is because the Linux console does not support
   underlining and ELinks will not know that underlined characters will



Fonseca, et al.                                                [Page 21]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   have to be color highlighted so they stand out.

   In short, ELinks does not use termcap or terminfo.  ELinks uses
   $TERM, but only to distinguish between terminals in its own
   configuration.  That is, you need only configure your terminal within
   ELinks: Go to the Setup menu and select Terminal Options.  If $TERM
   is set to 'screen' when you configure ELinks' terminal settings,
   ELinks will remember to use those settings when $TERM is 'screen'.

6.1  Options

   Apart from the last charset option configurable through the Setup ->
   Character Set submenu in the Main menu, the rest can be configured
   using the Terminal Options dialog.

6.1.1  Terminal type

   It maps roughly to the terminal type, such as Linux console, XTerm,
   VT100 etc.  It matters mostly when drawing frames and borders around
   dialog windows.  As already mentioned, it also turns on certain
   features which try to compensate for ``missing'' terminal
   capabilities when drawing.  Special highlighting of underlined text
   if underlining is not supported is one such thing.

   +---------------------+---------------------------------------------+
   | Type                | Notes                                       |
   +---------------------+---------------------------------------------+
   | No frames           | Dumb terminal type / ASCII art              |
   | VT 100 frames       | Works in most terminals                     |
   | Linux or OS/2       | Linux console / you get double frames and   |
   | frames              | other goodies                               |
   | KOI-8               |                                             |
   | FreeBSD             | FreeBSD console                             |
   +---------------------+---------------------------------------------+

   The default is to assume dumb terminal/ASCII art.

6.1.2  Color mode

   The color mode controls what colors are used and how they are output
   to the terminal.  The available color modes are:

   +---------------------+---------------------------------------------+
   | Mode                | Color codes                                 |
   +---------------------+---------------------------------------------+
   | Mono mode           | Only 2 colors are used                      |
   | 16 color mode       | Uses the common ANSI colors                 |
   | 256 color mode      | Uses XTerm RGB codes (if compiled in)       |



Fonseca, et al.                                                [Page 22]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   +---------------------+---------------------------------------------+

   The default is to use mono mode.

6.1.3  Switch fonts for line drawing (aka 11m hack)

   This is related to the drawing of frames and window borders
   controlled by the option above.  It controls whether to switch fonts
   when drawing lines, enabling both local characters and lines working
   at the same time.

   This boolean option only makes sense with the Linux terminal.  Off
   off by default.

6.1.4  Restrict frames in cp850/852

   This is related to the drawing of frames and window borders
   controlled by the option above.  If enabled, it restricts the
   characters used when drawing lines.

   This boolean option only makes sense with the Linux terminals using
   the cp850/852 character sets.  Off by default.

6.1.5  Block cursor

   Move cursor to bottom right corner when done drawing if possible.
   This is particularly useful when we have a block cursor, so that text
   colors are displayed correctly.  If you are using a screen reader you
   do not want to enable it since the cursor is strategically positioned
   near relevant text of selected dialog elements.

   This boolean option is off by default.

6.1.6  Transparency

   Whether to set the background to black.  This is particularly useful
   when using a terminal (typically in some windowing environment) with
   a background image or a transparent background.  If this option is
   enabled the background will be visible in ELinks as well.

   Note that this boolean option makes sense only when colors are
   enabled.  On by default.

6.1.7  Text underlining capability

   This boolean option controls whether to underline text or enhance the
   color instead.




Fonseca, et al.                                                [Page 23]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   Note: not all terminals support text underlining, so it is off by
   default.

6.1.8  UTF-8 I/O

   This boolean option controls outputting of I/O in UTF-8 for Unicode
   terminals.

   Note that currently, only the subset of UTF-8 according to the
   terminal codepage is used.  Offff by default.

6.1.9  Character Set

   Codepage of the charset used for displaying content on terminal.

   The value 'System' (which is the default) will set the charset
   according to the current locale.  The default is to use the charset
   of the current locale.

6.2  Terminal Configurations

   Built-in configurations exists for the following terminals:

   		linux, vt100, vt110, xterm, xterm-color and xterm-256color

   The last configuration requires that support for 256 is compiled in.

   GNU Screen is VT100-compatible, so select 'VT 100 frames'.  GNU
   Screen also supports colors just fine, so select '16 colors'; or if
   you are running Screen within a terminal emulator that supports 256
   colors and you have compiled both Screen and ELinks to support it,
   choose '256 colors'.

7.  Introduction to MIME handling

   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 UI (so usually there is no
   need to deal with elinks.conf), 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.

   The comments provided within elinks.conf 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



Fonseca, et al.                                                [Page 24]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   launch a program to view some kind of file (like images), then read
   on.  Some basic knowledge of MIME is recommended.

7.1  Handling MIME types, the ELinks way

7.1.1  What are MIME types and why may you want to use them?

   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.

   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.

7.1.2  Associating files to MIME types

   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 FTP or from your local
   filesystem, so sometimes ELinks needs to guess it.

   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.

7.1.3  Managing a given MIME type

   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 zgv (a popular svgalib image viewer) when you are
   using the text console, but xli (a image viewer for X) when running
   the X window system.

7.1.3.1  Binding it to a handler

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




Fonseca, et al.                                                [Page 25]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   For instance, you may create an image_viewer handler and assign it to
   MIME types image/jpeg, image/png and image/gif.  Then you would
   associate to image_viewer 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.

7.1.4  Specifying the details for a handler

   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.

   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 the X window sytem.  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 foo) 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).

7.1.4.1  Attaching a program to it

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

7.1.4.2  Choosing whether you want confirmation before applying it

   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 C 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 indent to display it with less.

7.1.4.3  Choosing whether to block the terminal

   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.

7.2  Setting up elinks.conf

   If you have old configuration files from old ELinks versions or from
   Links, then you may use the conf-links2elinks.pl script (which is



Fonseca, et al.                                                [Page 26]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   placed at contrib/conv/ 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.

7.2.1  Associating a file extension to a MIME type

   You can still do this with the UI, from the the Setup->File
   Extensions submenu.

   If you want to do so from the configuration file, enter set
   mime.extension.ext = "type", replacing ext with the appropiate file
   extension, and type with its MIME type.  E.g.  you may want to have
   set mime.extension.jpg = "image/jpeg".

7.2.2  Defining a handler

   For each handler you must define three items, specifying in what
   context the value of the item should be applied.  You must enter set
   mime.handler.handler-name.item.context = value, replacing
   handler-name with the name for the handler you are defining, item
   with the item you are defining for this handler, context with the
   context this item value is to be applied, and value with the value
   you want to assign to the item.  You must do so for each of the
   available items: program, ask and block.

   The value for program is a string with the exact command you want to
   be issued to view the file, placing % were you would put the file
   name.  The values for ask and block are either 0 (no) or 1 (yes).
   Available contexts include unix and unix-xwin, 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 DISPLAY variable is set so that ELinks may run an X program.

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

   	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 %"

   In this example the image_viewer handler uses the svgalib image
   viewer zgv when X is not available, and the X image viewer xli when



Fonseca, et al.                                                [Page 27]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   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.

7.2.3  Associating a MIME type to a handler

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

8.  Managing External Viewers with Mailcap

   This document describes the support for Mailcap (RFC 1524) in ELinks.
   It does not describe the mailcap format.  There are plenty of
   documents on the Web that does this.  Google and thou wilt find.  ;)

8.1  A Short Intro to Mailcap

   Mailcap is a file format defined in RFC 1524.  Its purpose is to
   inform multiple mail reading user agent (MUA) programs about the
   locally-installed facilities for handling mail in various formats.
   It is designed to work with the Multipurpose Internet Mail
   Extensions, known as MIME.

   ELinks allows MIME handlers to be defined using its own configuration
   system, so why support mailcap? It can be seen as an alternative or
   simply as a supplement for setting up MIME handlers in ELinks.
   Mailcap files are present on most UNIX systems--usually in /etc/
   mailcap--so this makes it possible for ELinks to know how to handle a
   great variety of file formats with little configuration.  To be able
   to use mailcap, it has to be compiled into ELinks.  This is the
   default.  If you don't need mailcap support, just configure ELinks
   with the flag: --disable-mailcap.

8.2  Parameters to Mailcap Entries

   The code has been ported from Mutt and thereby inherits some of its
   various features and limitation.

   The following parameters are supported:

   +--------------+----------------------------------------------------+
   | Parameter    | Description                                        |
   +--------------+----------------------------------------------------+
   | %s           | The filename that contains the data.               |
   | %f           | The content type, like 'text/plain'.               |



Fonseca, et al.                                                [Page 28]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   +--------------+----------------------------------------------------+

   The following parameters are not supported, since they do not really
   make much sense for a non-MUA program:

   +--------------+----------------------------------------------------+
   | Parameter    | Description                                        |
   +--------------+----------------------------------------------------+
   | %n           | The integer number of sub-parts in the multipart   |
   | %F           | The "content-type filename" repeated for each      |
   |              | sub-part                                           |
   | %{parameter} | The "parameter" value from the content-type field  |
   +--------------+----------------------------------------------------+


8.3  Reading of Mailcap Files

   Mailcap files will be read when starting ELinks.  The mailcap files
   to use will be found from the mailcap path, a colon separated list of
   files similar to the $PATH environment variable.  The mailcap path
   will be determined in the following way:

   1.  From the value of the mime.mailcap.path option in elinks.conf;
       for example:

   	set mime.mailcap.path = "~/.mailcap:/usr/local/etc/mailcap"

   2.  From MAILCAP environment variable.

   3.  If non of the above is defined, the mailcap path defaults to "~/
       .mailcap:/etc/mailcap".


8.4  Fields

   Since mailcap handling is primarily for displaying of resources, all
   fields like edit, print, compose etc.  are ignored.

   Note: Test commands are supported, but unfortunately, it's not
   possible to provide the file when running the test.  So any test that
   requires a file will be considered failed and the handler will not be
   used.

   Unfortunately, there are no 'native' support for the copiousoutput
   field.  The field basicly mean 'needs pager'.  So it is handled by
   appending a pipe and a pager program to the command.  The pager
   program will be read from the PAGER environment variable.  If this
   fails, test are made for common pager programs (/usr/bin/pager, /usr/



Fonseca, et al.                                                [Page 29]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   bin/less and /usr/bin/more in that order).  So if you define
   png2ascii as your handler for image/png and specify copiousoutput
   then the executed command will be "png2ascii |/usr/bin/less" if less
   is your pager or present on your system.

8.5  Mailcap Configuration

   Apart from the mime.mailcap.path option, you can configure if mailca
   support should be disabled.  The default being that it is enabled.
   To disable it just put:

   	set mime.mailcap.enable = 0

   in elinks.conf.

   It is also possible to control wether ELinks should ask you before
   opening a file.  The option is a boolian and can be set like this:

   	set mime.mailcap.ask = 1

   if you would like to be asked before opening a file.

8.6  Some Sample Mailcap Entries

   Below are examples of how to specify external viewers:

   	# Use xv if X is running
   	image/*;                xv %s ; test=test -n "$DISPLAY";

   	# Convert images to text using the netpbm tools
   	image/*;                (anytopnm %s | pnmscale -xysize 200 150 | \
   				 pnminvert | ppmtopgm | pgmtopbm | \
   				 pbmtoascii -1x2 ) 2>&1 ; copiousoutput

   	# Various multimedia files
   	audio/mpeg;             xmms '%s'; test=test -n "$DISPLAY";
   	application/pdf;        xpdf '%s'; test=test -n "$DISPLAY";
   	application/postscript; ps2ascii %s ; copiousoutput


9.  The tale of ex-mode

   Are you a vim-controls nerd who wants to see them everywhere?
   Welcome.

   Actually ELinks doesn't shine in this area yet very much.  Heck, the
   famous hjkl foursome is still occupied by some feeble managers in the
   default keymap (we have that in our monumental TODO lists).  Still,



Fonseca, et al.                                                [Page 30]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   if you know what to touch during the compilation (--enable-exmode),
   you can get at least some familiar reply to the mighty ':' (colon)
   grip.

9.1  What it is

   Ex-mode gives you some (still very rough and only marginally
   complete) access to advanced ELinks commands, to be invoked anywhere
   anytime, straight and fast.

   When you activate the ex-mode (named after the equivalent gadget in
   the vi text editor flavours), a command line appears at the bottom of
   the screen for you to type the commands.

   Only two kinds of commands are supported so far.  First, (almost?)
   anything that can appear in the configuration file can be used in
   ex-mode.  Second, you can invoke (almost) any action from the
   ex-mode.

9.2  Configuration directives in exmode

   There aren't many of these, so we can skim through them fast.

   If you want to flip an option you know by name and refuse to engage
   with the option manager visuals, you can just drop in to the ex-mode
   and type 'set the.option = 1234'.  See man elinks.conf (5) or the
   options manager for the list of options; you can also get a complete
   options tree saved to elinks.conf if you set config.saving_style = 2
   (but do NOT keep that setting unless you know what are you doing; if
   we change a default value of some option in future releases, we
   (generally) know what are we doing - this change won't propagate to
   you during an upgrade if you already have the original default value
   saved in your configuration file, though).

   It's the same story with keybindings.  You can use 'bind "main" "h" =
   "move-cursor-left"'.  It's not the same story with keybindings
   documentation.  There is the elinkskeys (5) manual page but it's
   horribly obsolete, so don't rely on it.  You can refer to the
   keybindings manager for names of actions and even their short
   descriptions.  Also, all the 'bind' commands are saved to the
   configuration file if you set config.saving_style = 2 (but see
   above).

   You can also use 'include my.conf', which will read my.conf as an
   ELinks configuration file.

   Actually, ELinks would eat '#blahblah blah' too, if you see a point
   in feeding it that kind of stuff.



Fonseca, et al.                                                [Page 31]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


9.3  Actions in exmode - or exmode in action?

   There is too many of these, so we should better skim through them
   fast.

   Actually, we already talked about them.  It's the last argument to
   the 'bind' command.  So, they are those listed in the keybinding
   manager.  So if you enter 'move-cursor-left' command, it will move
   your cursor left - by a single character, making this a little
   awkward, but it's useful if you sometimes want to easily invoke an
   action and you don't want to waste a key for it.

   Actually, actions could theoretically take arguments too.  This is
   currently implemented only for the 'goto-url' action, which can take
   the location it should go at as a parameter (otherwise it opens the
   standard well-known dialog as if you pressed 'g' in the default
   keymap).

   Regarding the mysterious "(almost)" hinted above, you can never
   invoke the "quit" action from the exmode - if you type it there,
   "really-quit" is invoked instead.

9.4  How to use it

   It's simple.  You press ':' (without the apostrophes, of course) and
   type in the command, then you press enter.  E.g., ':set
   config.saving_style = 3' (this is a good thing), ':quit' (and the
   game is over).  The standard line-editing facility is present (cursor
   keys and so), and the ex-mode input line has own history.

9.5  The "but"s

   The biggest usability hurdle so far is that there is no
   tab-completion.  This is why the ex-mode support is not enabled by
   default and part of the reason why its practical usage is somewhat
   limited yet - if you don't remember exactly what do you want to
   invoke, tough beans.  Someone shall address this issue in the future.

   Also, perhaps wider scale of commands should be implemented in
   ex-mode.  The code is extremely flexible and it is very trivial to
   make another ex-mode command handler, it's just that no one has done
   it yet ;-).  Also, more actions should be able to take arguments.

10.  Managing remote ELinks instances with -remote

   Some programs provide the ability to pass URIs to external programs.
   When stumbling upon a reference to a page you want to see, it is
   sometimes a kludge to copy and paste it into ELinks.  This is where



Fonseca, et al.                                                [Page 32]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   -remote can be a nifty solution.

   When invoking ELinks with the -remote argument, it does not start a
   new instance, but instead connects to an already running ELinks,
   making it possible to control that ELinks instance.  The -remote
   command line switch takes a command consisting of the action to
   invoke and any parameters to the action.  Here is an example for
   opening freshmeat.net in a new tab:

   	$ elinks -remote "openURL(http://freshmeat.net/, new-tab)"

   When running this command in a terminal, you will see a small delay
   before ELinks returns.  If no running instance was found, it will
   return with the error message:

   	ELinks: No remote session to connect to.

   All URLs passed to the openURL() commands can be URL prefixes, so the
   command above could have simply used ``openURL(fm, new-tab)''.

10.1  Limitations and outstanding issues

   Remote control is implemented using the intercommunication socket
   created in ~/.elinks/, so the command has to be run on the same
   machine as the instance you want to control; or put differently: the
   two ELinkses need to share a file system that supports socket files,
   which rules out usage of -remote over NFS.  This also implies that
   the ELinks instance you want to control should be started without
   passing -no-home nor -no-connect.

   The built-in -remote support is to some degree compatible with the
   one Mozilla provides (http://www.mozilla.org/unix/remote.html), but
   with some homebrew extensions added and few unsupported features.
   All the supported actions are documented below.

   Under some circumstances, use of the -remote control can cause ELinks
   to become unresponsive.  This is cause by the current key press and
   mouse focus being redirected to new tabs or dialogs opened by the
   -remote action.

10.2  Remote Actions

   The command syntax is case-insensitive.  For readability, we use the
   casing in the listing of supported commands.

   Mozilla -remote compatible commands:

   ping(): Checks for existence of a remote instance.  Makes it possible



Fonseca, et al.                                                [Page 33]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


      for scripts to query if remote controlling is possible.

   openURL(): Prompts for a URL in current tab by opening the Goto
      dialog.

   openURL(URL): Open the passed URL in current tab.

   openURL(URL, new-tab): Opens the passed URL in new tab.

   openURL(URL, new-window): Opens the passed URL in new window.

   xfeDoCommand(openBrowser): Opens an ELinks instance in a new window.
      This ELinks instance will connect to the already running one.

   ELinks extensions:

   addBookmark(URL): Bookmarks the passed URL.

   -remote can also take a list of URLs without an explicit action, in
   which case the URL arguments will be opened in new tabs in the remote
   instance.  For example, by running:

   $ elinks -remote slashdot.org fm g:elinks

   new tabs containing slashdot.org, freshmeat.net and a Google search
   of elinks will be opened.

11.  Acknowledgement

12  References


Authors' Addresses

   Jonas Fonseca

   EMail: fonseca@diku.dk


   Petr Baudis

   EMail: pasky@ucw.cz


   Laurent Monin

   EMail: zas@norz.org




Fonseca, et al.                                                [Page 34]

ELinks/0.10          ELinks Manual for version 0.10             May 2005


   Miciah Dashiel Butler Masters

   EMail: miciah@myrealbox.com


   José Luis González González

   EMail: jlg80@mi.madritel.es











































Fonseca, et al.                                                [Page 35]

