Introduction

When retawq starts, it tries to get its run-time configuration from up to two places, in this order:

• A "built-in" configuration; cf. the compile-time configuration option OPTION_BIRTCFG. This is a rather special possibility, intended for users with rare needs.
• An "external" configuration file which is normally located at "/home/your_home/.retawq/config", depending on the environment variable "HOME". (You can make retawq use a different directory with the command-line option "--userdir=path".)

Each run-time configuration (built-in or file) consists of text lines which represent 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. When applied, 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.

There's a configuration example available. The below information shows which sections can be specified and how subsections are interpreted; if something is not explicitly configured, an implicit default behavior is applied. Please note that case matters for all option names: don't use uppercase letters where lowercase letters are required.

Options Part I: User Interface

• bookmarks - the URL of a bookmarks document which shall be displayed when you use the keyboard command "b"
• 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".
• 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")
• execext-shell - specify which shell program to run (and how) with the keyboard command "!"; if you want to use this, the respective feature must have been enabled with the compile-time configuration option OPTION_EXECEXT.
  The first parameter must be the absolute path of the shell program you'd like to use (e.g. /bin/sh or /bin/bash), any further parameters are passed as command-line options to the shell program without modification.
  The "shell" can, in fact, be any program of your choice. If you want to use a normal shell program, you'll probably want to call it with the parameter "-c" (because that's what such a shell program needs), so your config file should contain a line like this: "execext-shell /bin/sh -c".
• home - the URL of a document which shall be displayed when you use the keyboard command "h", e.g. your private home page
• 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 simply opens 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 opens 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.
• keymap - Let certain keys cause certain program actions. Currently, it is possible to map keys to commands or to line input actions, so you can use "keymap command" or "keymap line-input" here. Each rule line consists of one key identifier and one associated action identifier as described in the keymaps documentation, e.g. the command map "ctrl-w menu-windowlist". Your mappings can override retawq's default mappings; for example, if you configure "ctrl-w document-top", the default command action for "ctrl-w" ("menu-windowlist") is forgotten.
• 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 (cf. 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; lowercase letters result in ascending order, the corresponding uppercase letters in descending order:
  • g - sort by group ID
  • i - sort by name, case-insensitive
  • 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.
• scroll-bars - whether scroll bars shall be shown ("on") or not ("off"); currently this is only relevant if the compile-time configuration option OPTION_TG has been set to xcurses
• search-engine - the URL of a search engine form document which shall be displayed when you use the keyboard command "e"
• termwintitle - whether the terminal window title shall be set (1) or not (0; default) to a text of the form "retawq version number" in xterm-like and in GNU screen terminals; this might not work with some terminal emulators; retawq won't try to reset the title when quitting because finding the original title is "expensive" and often still fails anyway

Options Part II: Technical

• ftp-login - Specify the standard username and password for FTP server login. If you don't provide username and password in a URL (like in "ftp://user:pass@foo.org/"), retawq uses the words "anonymous" and "guest" 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 sends 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!
• ftps-method - (apologies for all this unavoidable technobabble:-) Several methods exist for protecting FTP transfers with TLS/SSL; some of these methods are rather historical and shouldn't be used nowadays, but retawq supports them anyway in order to be as useful as possible.
  For the URL scheme "ftps", retawq normally tries to autodetect the appropriate method as follows: if the portnumber is 990 (the "classical" ftps portnumber), a TLS handshake on a connection is started as soon as the connection has been established; otherwise retawq tries the FTP command "AUTH TLS" (plus "PROT P") and fall back to "AUTH SSL" if necessary. If autodetection finds that a server supports "AUTH TLS" but not "PROT P", it might ask you something like this: "Server ... can't protect data - allow cleartext?" If you say yes, "PROT C" is used and the data connection won't be protected.
  However, autodetection might not work with all servers or you might get tired of answering questions again and again. For example, some servers simply can't protect the data connection; if this happens to you and you don't mind transferring the data in the clear (e.g. if you use ftps mainly to avoid sending the password command in clear text over the control connection), you can use this option with the method specifier "authtls-dataclear".
  Each rule line consists of a host pattern and a method specifier. The host pattern can either be an exact name or begin with a "*" character (which has the usual meaning); you can also append a specific portnumber in the usual "hostname:portnumber" notation; if you don't, the rule applies to all ports on the host(s). The following method specifiers are available:
  • autodetect: perform autodetection of the appropriate method, as described above
  • tls: immediately perform a TLS handshake when the connection has been established, don't send any "AUTH" command
  • authtls: start TLS with the FTP command "AUTH TLS", later followed by "PROT P"
  • authtls-dataclear: start TLS with the FTP command "AUTH TLS", later followed by "PROT C", so the data connection won't be protected with this method
  • authssl: start TLS with the FTP command "AUTH SSL"
• 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 are only stored in RAM, not written to a file, 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).
• 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.) Technobabble: proxy authentication can only apply basic authentication, not yet digest authentication.
  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 contain something 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".
• http-version - Too many HTTP server implementations don't handle the HTTP/1.1 protocol correctly, so retawq uses HTTP/1.0 by default nowadays. If you'd like to try HTTP/1.1 anyway, this option allows you to set an explicit HTTP protocol version. Each rule consists of a host pattern and a version number. The host pattern can either be an exact name or begin with a "*" character (which has the usual meaning); you can also append a specific portnumber in the usual "hostname:portnumber" notation; if you don't, the rule applies to all ports on the host(s). The protocol version number can currently be either "1.0" or "1.1". In general, this option applies to both HTTP and https; you can easily restrict it to only one of these by providing a portnumber (usually 80 for HTTP and 443 for https) with the host pattern.
• https-cookies - This is used for the URL scheme "https" like "http-cookies" is used for "http".
• https-proxies - This is used for the URL scheme "https" like "http-proxies" is used for "http".
• languages - a comma-separated, whitespace-free list of language codes for your preferred natural languages in which you would like to receive 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 sends 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). - Technobabble: 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 URL 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).
• news-server-default - the default server for "news:" and "nntp:" URLs which don't contain an explicit server name
• redirections - maximum number of automatic URL redirections with the HTTP and https protocols; the default is 10 (which should be enough for any "real-life" case), allowed values are in the range 3..20.
• user-agent - most browsers identify themselves to HTTP servers by including a "User-Agent" line in the HTTP header. The "user-agent" option allows you to specify how much information about your computer retawq may reveal to servers. 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.
  Technobabble: 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".