doc/introduction.txt

   1 Introduction to the World of ELinks
   2 -----------------------------------
   3
   4 The goal of this introduction is to explain the basic concepts in ELinks,
   5 give an overview of how to get started and serve as an entry point to many
   6 of the (undocumented) features of ELinks. It won't tell you all the
   7 details, but should hopefully give you an idea of how things work and make
   8 it possible for you to even figure out how to go further.
   9
  10 Although ELinks is text-based, the user interface has many of interaction
  11 methods normally found in graphical environments. There are menus, dialogs
  12 with buttons and hierarchic list boxes with folders. Care has been taken to
  13 make the interaction between various dialogs consistent, so the controls
  14 will quickly become familiar to new users.
  15
  16 The user interface can be controlled using both mouse and keyboard, but
  17 currently it is only possible to configure keybindings. Looking back, the
  18 key-controls have been more advanced than the mouse support, but during the
  19 0.10 prereleases the mouse support has been much improved. You will now find
  20 find stuff like contextual menus when right-clicking in different document
  21 zones.
  22
  23 Overview of the User Interface
  24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  25
  26 The main user interface of ELinks consists of the document view and dialog
  27 bars displaying the information such as the title of the currently viewed
  28 document, all opened tabs and the browsing status. The 3 bars are elaborated
  29 further below.
  30
  31 The most important dialogs that you will meet include the Main, Link and Tab
  32 menus and the different managers. The menus serve as entry points to the
  33 actions available from different contexts, while the managers let you check
  34 the state and control the various subsystems, such as loaded cookies and the
  35 global history. The utility menus and the manager tools are investigated
  36 further below.
  37
  38 The document viewer in ELinks provides a feature-rich set of ways to browse
  39 documents. That is, multiple options exist for navigating, searching and
  40 displaying documents and you will hopefully figure in time what works best
  41 for you. The basic browsing possibilities are presented below.
  42
  43 ELinks is highly configurable, so if there is something that you would like
  44 to change, it is most likely possible. The best overview of the many options
  45 are given in the `elinks.conf(5)` man page.  Keybindings are discussed in the
  46 `elinkskeys(5)` man page.  It is not always up-to-date, so you should also
  47 check the keybinding manager and the overview of all the configured
  48 keybindings given in the Help -> Keys dialog. The Keys dialogs serves as a
  49 good introduction to the most common keybindings.
  50
  51 The Title, Tab and Status bar
  52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 The title bars main purpose is to display the title of the current document.
  55 Documents bigger than can be displayed with the current screen size are
  56 divided into subpages. In this case the current document position is
  57 indicated in the far right of the title bar as a suffix to the actual
  58 document title.  The syntax is: ( current-subpage / total-subpages ), an
  59 example is `(4/9)` that indicates the 4th subpage of 9 subpages.
  60
  61 The tab bar by default is only visible when 2 or more tabs are open. It is
  62 divided into slots containing the trimmed title of the tabs' loaded
  63 document. Between each tab is a separator. The current tab is highlighted
  64 and all tabs that has not been viewed after being loaded are highlighted as
  65 fresh. Tabs are explained in details in the tabs.txt file.
  66
  67 The status bar has multiple purposes. Most of the time it will contain the
  68 URI (and title) of the currently selected link. If a link is followed,
  69 connection information is shown in the status bar. When using cursor
  70 routing, the status bar will show the coordinates of the cursor when a link
  71 is not followed.
  72
  73 The Main, Link and Tab Menus
  74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  75
  76 The Main Menu gives you access to many of the features of ELinks via
  77 submenus and serves as a good entry point for performing actions on the
  78 different objects of interest, such as links, documents and tabs. The Link
  79 menu and Tab menus are more specialized and targeted to a specific context,
  80 such as link handling or managing the tab bar. Actually, the Link Menu is
  81 accessible from the Main Menu as a submenu.
  82
  83 Once you have familiarized yourself with the menus, you will have a good
  84 chance at gradually learning the most common keybinding, since all the
  85 configured keybindings are shown as right aligned text. Menu entries can
  86 also be quickly accessed using hotkeys. Hotkeys appear highlighted in the
  87 menu entry text. For example the key-combo "Alt-v i" will open the document
  88 info dialog accessible from the View sub menu in the Main menu.
  89
  90 The Managers
  91 ~~~~~~~~~~~~
  92
  93 The managers let you control the state of subsystems, such as cookies and
  94 the global history. They are accessible from the Tools or Setup submenu in
  95 the Main Menu. The managers consists of an area showing a hierarchic listbox
  96 and buttons at the bottom. Below, a view of the cookie manager is shown.
  97
  98         +------------------------- Cookie manager -------------------------+
  99         |                                                                  |
 100         |   [-]- bugzilla.elinks.cz                                        |
 101         |    |    |-- BUGLIST                                              |
 102         |    |    `-- LASTORDER                                            |
 103         |   [+]- kerneltrap.org                                            |
 104         |   [+]-*dictionary.reference.com                                  |
 105         |   [+]-*bjork.com                                                 |
 106         |   [-]- www.google.com                                            |
 107         |         `-- PREF                                                 |
 108         |                                                                  |
 109         |                                                                  |
 110         |                                                                  |
 111         |                                                                  |
 112         |   [ Info ]  [ Add ]  [ Edit ]  [ Delete ]  [ Save ]  [ Close ]   |
 113         +------------------------------------------------------------------+
 114
 115 Each item is either a folder or a leaf. A folder is displayed with a `[-]`
 116 or `[+]` before the name telling whether the folder is currently open or
 117 closed. Nested items are displayed indented compared to the folder they are
 118 nested in. In the cookie manager example above "bjork.com" is a folder and
 119 "PREF" is a leaf.
 120
 121 Items can be "marked", which makes it possible to select a group of items
 122 and perform an action on them, such as deleting all marked items. If any
 123 item has been marked the currently selected item is ignored when performing
 124 the action.  Marked items are displayed with an asterisk ('*') prefixing the
 125 name.
 126
 127 The buttons make it possible to perform actions either on selected or marked
 128 items or on all items in the manager. Buttons named 'Clear' and 'Save' are
 129 performed on all items; 'Clear' will delete all items and 'Save' will update
 130 the runtime state file associated with the manager in the `~/.elinks/`
 131 directory.  Most buttons presses will query you before completing the
 132 action.
 133
 134 At any time, both the currently selected item and button are highlighted.
 135 The same goes for marked items. Most manager dialogs also maintains the
 136 state, so that when you reopen the manager later it will have the same items
 137 selected and the same folders opened or closed.
 138
 139 The basic default controls for managers are the following:
 140
 141 `--------------`--------------------------------------------------------------
 142 Keys            Action
 143 ------------------------------------------------------------------------------
 144 Up/Down         Select the item above/below.
 145 '*'             Toggle marking of a item.
 146 Space           Open and close folders.
 147 Left/Right      Select the button to the left/right.
 148 Home/End        Select the first/last item.
 149 Enter           Press the currently selected button.
 150 Esc             Close the manager dialog.
 151 ------------------------------------------------------------------------------
 152
 153 Some managers also supports searching, either by pressing the 'Search'
 154 button or by pressing '/'. By searching the empty string, all hidden items
 155 from the previous search will be shown again.
 156
 157 LED status indicators
 158 ~~~~~~~~~~~~~~~~~~~~~
 159
 160 As an optional feature it is possible to have tiny LED-like status
 161 indicators shown at the bottom-right of the screen. They are used for
 162 displaying an overview of the current browsing state, ie.  whether you are
 163 currently talking through a SSL-secured connection, what is the current
 164 input mode (normal or insert), JavaScript errors etc.
 165
 166 An example display may look like: `[SIJP--]`. Each position in the LED
 167 display is associated with the following state:
 168
 169 `--------------`--------------------------------------------------------------
 170 Symbol          Description
 171 ------------------------------------------------------------------------------
 172 'S'             Whether an SSL connection was used.
 173 'i'/'I'         The state of insert mode for text-input form-fields: 'i'     \
 174                 means modeless, 'I' means insert mode is on.
 175 'J'             A JavaScript error has occurred.
 176 'P'             A JavaScript pop-up window was blocked.
 177 -               Unused.
 178 -               Unused.
 179 ------------------------------------------------------------------------------
 180
 181 `-` generally indicates that the LED is off.
 182
 183 The above information is also available in the LED dialog available by
 184 either clicking on the LED display or via the Help menu.
 185
 186 Navigation
 187 ~~~~~~~~~~
 188
 189 ELinks provides various ways to navigate documents. Depending on how
 190 documents are structured, it can be a great help to change navigation style.
 191 The navigation styles can roughly be divided into page-oriented,
 192 link-oriented and screen-oriented. They overlap in many ways, so this
 193 separation is mostly used as a mean to present them.
 194
 195 Page-Oriented Navigation
 196 ^^^^^^^^^^^^^^^^^^^^^^^^
 197
 198 This involves scrolling documents horizontally and vertically.  Documents
 199 can be scrolled page-wise, where the next or previous subpage will be
 200 displayed. It is also possible to scroll documents in steps, either
 201 line-wise (vertically) or column-wise (horizontally). The step size can be
 202 configured and by default is 2 lines and 8 columns. Alternatively, whole
 203 documents can be scrolled to the start or the end.
 204
 205 The basic default controls:
 206
 207 `--------------`--------------------------------------------------------------
 208 Keys            Action
 209 ------------------------------------------------------------------------------
 210 Insert/Delete   Scroll up/down line-wise. (vertically)
 211 PageUp/PageDown Scroll up/down page-wise.
 212 '['/']'         Scroll left/right column-wise. (horizontally)
 213 Home/End        Scroll to the start/end of the document.
 214 ------------------------------------------------------------------------------
 215
 216 Link-Oriented Navigation
 217 ^^^^^^^^^^^^^^^^^^^^^^^^
 218
 219 For hypertext documents, access to the links makes it more practical to
 220 navigate by jumping between links in the document. There are two ways to do
 221 this; either you can move between links relationally or by number. Using
 222 relational link navigation it is possible to focus the next/previous link or
 223 move in a directional manner to the link in a certain direction such as
 224 left/right/up/down.
 225
 226 In order to navigate using link numbers, you have to first toggle link
 227 numbering on; this will prefix all links with a number using the notation
 228 [number]. `[23]` indicates link number 23. When link numbering is enabled,
 229 pressing any number key will pop up a "Go to link"-dialog where the complete
 230 link number can be entered. By pressing Enter the entered link number will
 231 be focused, but only if it is a valid link number.
 232
 233 Note: it is also possible to jump to links by searching the link text; check
 234 the documentation on searching.
 235
 236 The basic default controls:
 237
 238 `--------------`--------------------------------------------------------------
 239 Keys            Action
 240 ------------------------------------------------------------------------------
 241 Up/Down         Move to the previous/next link.
 242 '.'             Toggle link numbering.
 243 Enter/Right     Follow the current focused link.
 244 ------------------------------------------------------------------------------
 245
 246 No keys are by default configured for directional link navigation.
 247
 248 Position-Oriented Navigation
 249 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 250
 251 Positional navigation (sorry, bad word) uses the either the position of the
 252 cursor or the mouse click to navigate the document. If you are familiar with
 253 the w3m text-browser you will be familiar with cursor routing. Basically,
 254 you move the cursor around -- kind of like a mouse -- in the document area
 255 of the user interface. When the cursor is over a link, the link is
 256 highlighted, and when the cursor moves outside the current document view, it
 257 will cause the document view to scroll.
 258
 259 The possibilities when using the mouse to navigate the document depend on
 260 what terminal you are using. In some terminals, it is possible to scroll by
 261 using the mouse wheel. Scrolling is however also possible by clicking in the
 262 edge areas of the document view. Highlighting links can be done by clicking
 263 on a link but waiting to release the mouse button until the link is no
 264 longer under the mouse pointer.
 265
 266 No keys are by default configured for cursor routing.
 267
 268 Forms
 269 ^^^^^
 270
 271 The status bar will indicate the type and name of the field.
 272
 273 Input text/Password fields::
 274         These will be displayed as `________`.
 275         Note that passwords will be obscured using `*` characters.
 276         Status bar will display something like "Text field, name q",
 277         or "Password field, name password" for password fields.
 278
 279 Textarea boxes::
 280         These will be displayed as multiple lines consisting of `_`.
 281         Status bar will display something like "Text area, name comment"
 282
 283 Buttons::
 284         These will be displayed as `[ Go ]`.
 285         Status bar will display something like "Submit form to ...",
 286         "Post form to ..." for submit buttons.
 287
 288 Checkboxes::
 289         These will be displayed as `[ ]` or `[X]`.
 290         Status bar will display something like "Checkbox, name c, value 1".
 291         To set one just press ENTER on it.
 292
 293 Radio buttons::
 294         These will be displayed as `( )` or `(X)`.
 295         Status bar will display something like "Radio button, name radio1".
 296         To set one, you may use ENTER.
 297
 298 Select lists::
 299         These will be displayed as `[first item____]`.
 300         Note that if multiple attribute is used, these are displayed as a
 301         group of checkboxes instead.
 302         Status bar will display something like "Select field, name list"
 303         To select one entry, press ENTER, then navigate using UP/DOWN, then
 304         press ENTER again.
 305
 306
 307 Searching
 308 ~~~~~~~~~
 309
 310 Searching is by default available by pressing '/'. This will open a search
 311 dialog with a input text field for entering the search terms and checkboxes
 312 to control how searching is performed. You can indicate whether matching
 313 should be case sensitive and whether regular expressions or normal searching
 314 should be used.
 315
 316 It is also possible to make an incremental search, also called type-ahead
 317 searching. You can search either the whole document text or only link text.
 318 The latter can be useful if you see a link deep inside a page and want to
 319 get to it quickly.
 320
 321 Matches of the search term will be high-lighted. After having performed
 322 document text search all matches will be high-lighted.  To get rid of this
 323 high-lighting you have to ``search for the empty string'', that is open a
 324 search dialog and just press Enter in the input field.
 325
 326 Previous search words are saved in the search history, so they can easily be
 327 found and used later. Browsing the history will replace the current entered
 328 search terms.
 329
 330 The basic default controls for searching are the following:
 331
 332 `--------------`--------------------------------------------------------------
 333 Keys            Action
 334 ------------------------------------------------------------------------------
 335 '/'             Open search dialog
 336 '?'             Open search dialog for backwards searching
 337 '#'             Start incremental link text search
 338 '#/'            Start incremental document search
 339 'n'/'N'         Show next/previous match
 340 Tab             Show next match (only for incremental searching)
 341 Up/Down         Insert previous/next search word from history (only when the \
 342                 input field is selected)
 343 ------------------------------------------------------------------------------
 344
 345 Hints and Odd Features
 346 ~~~~~~~~~~~~~~~~~~~~~~
 347
 348 Note: This is still a work in progress and from here on an below
 349 everything is marked TODO!
 350
 351 - Numerical action prefixes. Example: 3<Down> jumps down three links.
 352
 353 - How to move forward in the document history ('u').
 354
 355 - Toggling color modes, plain/html and image link rendering.
 356
 357 - Link numbering.
 358
 359 - Insert mode in text-input form-fields.
 360
 361 - Menu searching.