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.
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:
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.
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:
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".
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".
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:
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.)
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.
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:
Depending on the actual configuration and activities, retawq might use the following environment variables:
Additionally, retawq might set environment variables for "local-cgi" URLs as defined in the CGI specification.