Introduction

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 subsections:

• The beginning of a section is marked by a line which starts with a non-whitespace character. (Space and tabulator characters are "whitespace".)
• 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 available.

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 following configuration...
  jumps
   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 "document", respectively.
  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:
  • 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
  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.
• 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 server
  • 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" operation.
  • 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 advance.)
  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:
  http-proxies:
   none *my-domain.org
   firewall.my-domain.org *
  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 "firewall.my-domain.org".
• 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:pass@foo.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:
  ftp-login
   anonymous mail@foo.org *
  Now retawq will send the username "anonymous" and password "mail@foo.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 "Accept-Language".
• 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 computer:
  
  • "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; i686)"
  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 version.
  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.