Run-Time Configuration Options
When retawq starts, it tries to read a configuration file which is normally
located at /home/your_home/.retawq/config. (You can make retawq look in
a different directory with the command-line option
"--retawqdir=path".) This file consists of sections and
- The beginning of a section is marked by a line which starts with a
non-whitespace character. (Space and tabulator characters are
- A subsection ("rule") within a section simply is a single line which starts
with a whitespace character. Rules are tested in the given order until a
matching rule (e.g. a rule containing a matching host name pattern) is found;
if no rules are given or none of the given rules matches, retawq's internal
default rule applies. - Some sections can't have subsections, simply because
they don't need any...
- Lines which begin with a "#" are comment lines and ignored by retawq.
Please note that case matters - don't use upper-case letters where
lower-case letters are required! :-)
There's a configuration file example
Options Part I: User Interface
- colors - By default, retawq displays colored text on any text
terminal which supports colors, and it mostly uses white color on a black
background. If you don't like colors at all, use "colors off". If you want to
get black-on-white text, use "colors reverse".
- home - a document which shall be displayed when you use the keyboard command "h", e.g. your private home page
- search-engine - a search engine form which shall be displayed when
you use the keyboard command "e"
- bookmarks - a bookmarks document which shall be displayed when you
use the keyboard command "b"
- jumps - URL shortcut associations that are used with the keyboard command "j"; each rule contains a shortcut and the
associated URL. The shortcut may currently be a combination of "almost any"
characters, but you should only use letters and digits; it must not contain
space characters (obviously), and it may be arbitrarily long. The URL may be
either a "constant" URL or a URL pattern. If it is a constant URL and you enter
the shortcut with the keyboard command, retawq will simply open this URL.
If you need something more flexible instead, you can use a URL
pattern. Such a pattern can contain several "markers" of your choice;
after the pattern, you tell retawq which character sequences in the pattern
actually are the markers (separated by single space characters). If you use the
keyboard command then, you don't only enter the shortcut, but also the
arguments which should replace the markers. For example, if you use the
visit http://www.!1.org/!2.html !1 !2
...and then enter "visit server document" with the keyboard command, retawq
will open the URL "http://www.server.org/document.html", because the configured
markers "!1" and "!2" are replaced with the entered arguments "server" and
You can use almost any sequence of characters as a marker, with a few
exceptions: you can't use space characters because they are interpreted as
argument separators, and the characters "=", ":", ";", ",", "$" and all kinds
of braces and quotation marks are reserved for feature extensions in future
versions. Also you can't use character sequences which might appear in the URL
during the replacement of markers with arguments; so, e.g. you should not use
single letters as markers because they likely appear in the URL. It is
recommended that you only use combinations of exclamation marks and digits as
markers, like in the above example, if possible.
- local-dir-sort - By default, retawq sorts the contents of local
directories only by name (ascending). If you want to use a different sorting
occasionally, you can use a "?sort=..." query directly with the URL (see
URL Schemes for an example).
If you want certain directories to be sorted in a special way
regularly, you can simply configure this. Each rule consists of a path
pattern and the desired sorting. The path pattern may be either an exact path
or end with a "*" character (which has the usual meaning). The sorting is given
as a sequence of letters; lower-case letters result in ascending order, the
corresponding upper-case letters in descending order:
As a special case, you can use "_" to disable all sorting for the path
pattern. And the configured sorting can always be overridden by using a
"?sort=..." query directly with the URL.
- g - sort by group ID
- m - sort by modification time
- n - sort by name
- s - sort by size
- t - sort by type (file/directory/...)
- u - sort by user ID
- dont-confirm - Normally retawq asks you for confirmation if you try
to perform a command which may have "dangerous" or unwanted effects, e.g.
quitting the program or overwriting a file. If you know the program so good
that you don't handle it the wrong way, you can disable the enervating :-)
questions individually with the following keywords:
- quit - don't ask when quitting retawq (keyboard command "Q")
- close - don't ask when closing a window (keyboard command "C")
- overwrite - don't ask before overwriting a local file
- form-submit - don't ask before submitting an HTML form to an HTTP
- form-reset - don't ask before resetting an HTML form, i.e. setting
all elements of a form back to their default values
- form-repost - don't ask before re-submitting an HTML form to an HTTP
server using the "post" method; this method is often used for tasks like adding
a record to a database, and adding it twice normally isn't a good idea; a
re-submit can e.g. happen if you reload a document which resulted from a "post"
- enforce-html - don't ask before enforcing the interpretation of a
document as HTML source code (keyboard command "H")
- enable - don't ask before enabling a disabled HTML form element
(keyboard command "E")
Options Part II: Technical
- http-proxies - By default, retawq doesn't use any proxies when
sending HTTP requests to servers. But in some local networks, the connection to
the Internet is only possible via proxies - e.g. because your local network is
protected by a firewall.
To define HTTP proxies, you start a "http-proxies" section in the config
file and define one rule per subsection line; each rule consists of a proxy and
a host pattern, optionally followed by a username and a password for proxy
authentication. (The password is entered in clear text, which might be a
security problem, so you should make sure that nobody but you can read the
config file; for example, use the shell command "chmod go-rwx config" in
You can also provide portnumbers in the usual "name:portnumber" notation;
if you don't provide a portnumber for the proxy, port 8080 is used; if you
don't provide a portnumber for the host pattern, the given rule applies to
all host ports. A host pattern can either be an exact name or begin with
a "*" character (which has the usual meaning).
For the example of a local network behind a firewall, your configuration
might look like this:
This means that all servers of your own domain (that is "inside the local
network" for this example) are accessed without proxies (use "none" as the
proxy name), and all other servers are contacted via the proxy
- ftp-login - Specify standard username and password for FTP server
login; if you don't provide username and password in an URL (like in
"ftp://user:firstname.lastname@example.org/"), retawq uses the word "anonymous" for them by
default. But some public FTP servers require that the password is (or at least
looks like) an e-mail address. If you get a "login failed" error message when
trying to access a public FTP service, you should add something like the
following to the configuration file:
anonymous email@example.com *
Now retawq will send the username "anonymous" and password "firstname.lastname@example.org"
when trying to access any ("*") FTP server unless a username and password are
explicitly given in the URL. Of course you can define a more detailed
configuration with several rule lines.
In theory, you could use this configuration for non-public FTP server
access as well. But writing down passwords in clear text is a bad idea, so
don't do it in practice - this configuration option is only intended for
non-standard, public FTP access!
- http-cookies - If the compile-time
configuration option OPTION_COOKIES has been enabled, you can specify for
which HTTP servers cookies may actually be stored and sent (default: none are
stored/sent); cookies will only be stored in RAM, not written to disk, so they
are automatically discarded when you quit retawq. The first argument in each
rule must be either "allow" or "deny". The second argument is a host name
pattern which can be either an exact name or begin with a "*" character (which
has the usual meaning).
- languages - a comma-separated, whitespace-free list of language
codes for your preferred natural languages in which you would like to download
documents from HTTP servers; example: "fr,en" if you prefer French documents
but also accept :-) English documents. If the server can't satisfy your
preference, it will send the document in "any" language, most likely English. -
The default value for this option is "en" (i.e., English documents are
preferred, nothing else is said). - This option corresponds to the HTTP header
- local-cgi - If the compile-time
configuration option OPTION_LOCAL_CGI has been enabled, you can specify
which CGI scripts on the local computer may be executed with the protocol
scheme "local-cgi" (default: nothing allowed). The first argument in each rule
must be either "allow" or "deny". The second argument is a script path pattern
which must begin with a "/" character and may be either an exact script name or
end with a "*" character (which has the usual meaning).
- user-agent - retawq, like most other browsers, identifies itself to
HTTP servers by including a "User-Agent" line into the HTTP header. The
"user-agent" option allows you to specify how much information about your
computer retawq may reveal to the server. The amount of information is defined
by a number ranging from 0 to 3, which had the following effect on my
The resulting HTTP header line contains the program name ("retawq"), the
version number (here "0.0.1"), the language code for the default user interface
language (here "[en]" for the English language) and some additional information
in parentheses, e.g. the word "text" which is there to distinguish the
currently used text mode from the not-yet-implemented graphics mode.
Distinguishing text and graphics mode might help dynamic content creation
programs (CGI scripts) on servers to decide whether they should generate a
fully-blown graphics version of some document or a lightweight text-only
- "user-agent 0" - "User-Agent: retawq/0.0.1 [en] (text)"
- "user-agent 1" - "User-Agent: retawq/0.0.1 [en] (text; Linux)"
- "user-agent 2" - "User-Agent: retawq/0.0.1 [en] (text; Linux 2.2.19)"
- "user-agent 3" - "User-Agent: retawq/0.0.1 [en] (text; Linux 2.2.19;
Higher numbers for the option "user-agent" result in more information. If
you want to advertise your operating system (like me:-), you should set the
number to at least 1. The default value is 0, of course, so that you don't
reveal private information accidentally.
The information is obtained via the operating system function "uname()". If
you're curious, you can easily find out this information for your computer with
the command-line program "uname", e.g. "uname -srm" or "uname -a".
- redirections - maximum number of automatic URL redirections with the
HTTP and FTP protocols; the default is 10 (which should be enough for any
"real-life" case), allowed values are in the range 3..20.
This documentation file is part of version 0.1.4 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-2002 Arne Thomaßen.