[retawq] User Guide

retawq Documentation
User Guide

Introduction

This user guide describes general concepts of the program and provides an overview of the other documentation files. retawq has become a quite extensive program which offers many options and features like different window kinds and runmodes which are unusual for text-mode web browsers. At the beginning, you can ignore most of the special properties. You can use retawq like most other text-mode browsers and rarely have to care about anything special if you don't want to.

Guided Tour

First, build the executable program as described in INSTALL without caring about all those possible compile-time configuration options. Start the program without any command-line options. It presents a web page which mentions the current version number of the program and possibly information about some libraries which are used and other things. Technically, this web page is a document which is contained in one "view" in a window of window kind "browser window", but we don't yet care.

Surf around a little bit to become familiar with the program; the most important keyboard commands for this are:

- the cursor up/down and page up/down keys to navigate inside a document
- the Return key to follow the currently highlighted link
- the keys "g" and "G" to enter URLs manually
- the cursor left/right keys to go back and forth in the series of views

All these keys let you stay in one single window, which is what you probably are used to from other text-mode browsers.

When you follow a link with the Return key or visit a URL with the "g"/"G" keys, a new "view" is created in the current browser window. Such a series of views seems to be unusual in text-mode browsers, but you probably know a similar concept from graphical browsers where you have the "Back" and "Forward" buttons.

Now create some other browser windows by splitting the screen (key "2"), by opening the current document in a new browser window (key "N") or by simply creating a new, empty browser window (key "n"). To change between two simultaneously visible windows when the screen is split, press the tabulator key. To reach a window which is currently not on screen, use the keys "w", "W" and "ctrl-w".

Once you are familiar with these basic operations, read some of the other documentation files: quite a few URL schemes are supported, not just HTTP; you might want to provide a run-time configuration; or maybe you want to use some command-line options, e.g. to start the program in a different runmode; if you often visit the same web pages, maybe you're interested in the sessions feature; if some of the default keys don't work on your terminal, you can associate different keys to actions by configuring the keymaps; if you want to transfer data over encrypted network connections, read about TLS/SSL support.

This little tour should have given you a first impression of the "look and feel" of the program. The further sections explain some general concepts in detail.

Terminal Screen Utilization

As mentioned above, you can create an arbitrary number of windows and manage them with keyboard commands like "w", "W" and "ctrl-w" in curses-like runmode. At any time, one or two windows are visible on the screen.

Each visible window has its own title line at its bottom which is displayed in reverse coloring. The title line always begins with a letter like "B" or "I" which indicates the window kind. The remainder of the line contains some kind-specific information like the URL of the currently displayed document in a browser window.

The bottom line of the screen is used for any of three purposes:

- to show information about the current window; for example, to show the progress when you are receiving a web page from an HTTP server in a browser window
- to show a message which informs you about the result of a keyboard command; for example, a text like "saving" when you started saving a document with the keyboard command "s", or a text like "found" when you searched for a string with the keyboard command "/"
- to enter something like a new URL or an HTML form text; cf. the section "Line Input" in the documentation file Keyboard Handling

If colors are enabled, error messages appear in red color.

If the compile-time configuration option OPTION_TG has been set to xcurses, scroll bars are available. (This feature will be available in other curses variants later too.) They appear at the right border of the terminal window (if the current document isn't completely visible) and can be turned on/off with the run-time configuration option "scroll-bars" and with the command action "scroll-bars-flip".

Documents

The user interface is built around a generic "document" concept. Whenever the program presents some content or other long text on the screen, this is done in a document. The most common documents are the layouted HTML web pages in browser windows.

One advantage of this concept is that you can treat documents mostly in the same way, no matter where they occur and in which window kind. For example, you can always use the same keyboard commands to scroll documents or to save them in a file.

If a document is interpreted as a web page, it might contain so-called "active elements": links and HTML form elements. Active elements are displayed as underlined text and, unless colors are disabled, in blue color. One of the currently visible active elements is displayed in reverse coloring; this is the "current" active element which can be treated with keyboard commands like the "Return" key or "i".

HTML Forms

Some web pages contain HTML forms. In retawq, all (non-hidden) HTML form fields are presented as "active elements", which are explained in the previous section. Since text terminals don't offer many layout possibilities, some kinds of form fields look similiar; to get information about the actual kind of a field, use the keyboard command "i". Some fields have a distinctive look:

- "[_]" - an unchecked checkbox
- "[X]" - a checked checkbox
- "(_)" - an unselected radio button
- "(*)" - a selected radio button

To change the value of a form field or to "push" a submit/reset button, use the keyboard command "Return". Simple fields like checkboxes change their value directly this way. For textual input fields, you are prompted at the bottom of the screen; cf. the section "Line Input" in the documentation file Keyboard Handling. If you want to change the value of a disabled field for some reason, you might have to use the keyboard command "E" first. The textual values of password fields are always symbolized by disguising "*" characters.

When you try to change the value of a selection list, a menu pops up; to change the value, select an option from the menu. The currently selected option is always marked with a "+" character in the menu. Disabled options are marked with a "-" character; this mark is only a "warning": retawq allows you to select disabled options, but the web page author presumably thought that nobody should actually do it. Most selection lists only allow a single selected option at any time; if you select an option in such a list, the previously selected option is automatically un-selected. In special multi-option lists, on the other hand, you have to choose a selected option explicitly to un-select it; only the "first" ("topmost") selected option from the menu is shown in the web page.

You can't yet upload local files with HTML forms. (Technobabble: the form field control type "file select" isn't yet handled on form submission. The default values for such fields aren't (and won't be) taken from the HTML source code because this could lead to the accidental upload of local files when users aren't aware that a form contained such fields - that could cause bad security and privacy problems.)

User Directory

The path to the retawq user directory is something like "/home/your_home/.retawq/" by default, depending on the environment variable "HOME"; you can choose a different path explicitly with the command-line option "--userdir".

This directory can contain several important files and sub-directories as described below; the most important file is probably the run-time configuration file "config". You can manually edit, move or remove anything in this directory as you like, but please do this only when retawq isn't running - otherwise problems might occur.

A note which is related to security and privacy: this directory might contain information which only you should be able to read, e.g. if you received a document via encrypted TLS connections and it's stored in the (not yet implemented) disk cache; the directory, especially the run-time configuration file, might contain security-relevant settings which only you should be able to modify, e.g. the paths of local CGI scripts which may be executed. For such reasons, you should make sure that only you can access the contents of this directory; for example, you should execute a shell command like "chmod go-rwx /home/your_home/.retawq/".

In future versions, this directory will contain many more things, e.g. a disk cache; if you want to put your own files or directories into it, their names should not begin with a lowercase letter, to avoid later conflicts.

- config - the run-time configuration file
- session - the standard session file; this is used when you apply the command-line option "--resume-session" without an explicit argument

Caching

retawq caches some of the information which it gets while it runs. Currently, everything is only cached in RAM, none of the information is stored in files; this means that all such information is "forgotten" when you quit the program. The following might be cached:

- documents - as long as you keep a reference to a document, e.g. in a window, the document is kept in a cache; to refresh a document in a browser window, you can use the keyboard commands "r" and "R" to reload the document
- URL history - the most recently visited URLs; to inspect this cache or visit one of the URLs, use the keyboard command "u"
- DNS lookup results - the association of hostnames with IP addresses (DNS: Domain Name System); you can inspect this cache by visiting the URL "about:hostinfo"; you can't yet modify/refresh this cache manually
- HTTP state mechanism ("cookies") - cookies are only cached as explicitly allowed by the run-time configuration options "http-cookies" and "https-cookies"; you can inspect this cache by visiting the URL "about:hostinfo", where the cached cookies appear near their respective hosts; this cache is automatically refreshed when a server sends new cookies

Environment Variables

Depending on the actual configuration and activities, retawq might use the following environment variables:

- COLUMNS - the number of columns of the terminal; relevant if the compile-time configuration option OPTION_TG has been set to bicurses (built-in curses) or xcurses mode
- DISPLAY - this is used to detect whether retawq is run in a terminal emulator in a graphical environment; relevant if the run-time configuration option "termwintitle" says so
- HOME - your home directory, e.g. "/home/your_home/"; for example, this is used as the base of the default user directory, cf. the respective section above
- LANG - the locale for internationalization of user interface texts; relevant if the compile-time configuration option OPTION_I18N has been enabled
- LINES - the number of lines of the terminal; relevant if the compile-time configuration option OPTION_TG has been set to bicurses (built-in curses) or xcurses mode
- STY - this is used to detect whether retawq is run inside GNU screen; relevant if the run-time configuration option "termwintitle" says so
- TERM - the terminal type; relevant if the compile-time configuration option OPTION_TG has been set to bicurses (built-in curses) mode and "probably" in most other curses variants too
- TERMINFO - the path of a non-default directory which contains the terminfo files; relevant if the compile-time configuration option OPTION_TG has been set to bicurses (built-in curses) mode

Additionally, retawq might set environment variables for "local-cgi" URLs as defined in the CGI specification.

This documentation file is part of version 0.2.6c of retawq, a network client created by Arne Thomaßen. retawq is basically released under certain versions of the GNU General Public License and WITHOUT ANY WARRANTY. Copyright (C) 2001-2006 Arne Thomaßen.