(This documentation file is only relevant in curses-like runmode.)

Introduction

You use retawq by entering keyboard commands. Most commands consist of a single key. The keys usually have been chosen so that you can remember them easily, e.g. "n" for "new window", "h" for "home URL" and "l" for "scroll down one line".

Some commands require additional input like a URL you want to visit or an explicit confirmation for a possibly "dangerous" command. This is explained in the section "Line Input" below.

The Escape key can be used to cancel several operations, e.g. all commands which require additional input and all menus.

Certain special keys like "Home" or "Page Up" don't work on all kinds of terminals. If you encounter this problem, please read about the run-time configuration option "keymap" which makes it possible to use different keys.

Some rather special commands have not been bound to keys by default because retawq is slowly "running out of keys" already due to the high number of commands. If you miss a command here, take a look at the full list of available actions, especially those which are marked "no default key".

Commands

Window Handling:

• n - create a new browser window; the old window in which you were working is not removed (and activities running there aren't stopped), you can get back to it with the commands "w", "W" and "ctrl-w".
• N - open the current browser document in a new browser window
• C - close the current window
• 1 - un-split the screen
• 2 - split the screen
• Tab (tabulator) - switch between visible windows when the screen is split
• w/W - go to the next/previous virtual window in the list of all virtual windows; for higher comfort, you probably want to use the command "ctrl-w" instead.
• ctrl-w - show a list of all currently existing windows in a menu

Document Handling:

• Page-down/Space - scroll down one screenfull of lines in the current document
• Page-up - scroll up one screenfull of lines in the current document
• l/L (and Delete/Insert) - scroll down/up one line in the current document
• Home - scroll up to the top of the current document
• End - scroll down to the bottom of the current document
• / (slash) - search for a string in the current document in a case-insensitive way; you're asked for the string; the search starts in the line right below the topmost line which is currently shown; if the string is found, the document is scrolled so that the respective line becomes topmost. This command currently finds a string only if it is completely contained in one rendered line; so, if a string isn't found although "it should be there", try to search for a single word to avoid line break boundaries.
• ? - like the command "/", but searches backward
• s - save the current document (its original, unmodified, unlayouted contents) in a file; you're asked for a filename. Saving automatically proceeds "in the background" until the whole document has been received or until reception is stopped.
• d - dump the current document (layouted) into a file; you're asked for a filename. The document is only dumped as far as it has already been received. To dump the source code of an HTML document in a browser window, view the source code with the keyboard command "\" and dump from there.

Web Browsing:

• Cursor-left - go back to the previous view in the series of views in the current browser window
• Cursor-right - go to the next view in the series of views in the current browser window; note: to follow a link, use the Return/Enter/o key instead (described below) - here retawq differs from other browsers.
• Cursor-down - go to the next link (or HTML form element) in the current web page
• Cursor-up - go to the previous link (or HTML form element) in the current web page
• Return/Enter/o - open the current link in the current browser window, or activate the current HTML form element; note that you can't activate form elements which are marked disabled or read-only in the HTML source code (but check the keyboard command "E"). Before you submit a form, make sure that it has been received completely and that you've scrolled down to its end at least once; otherwise the form data might be sent incompletely.
• O - open the current link in a new window
• ctrl-o - like "O", but the screen is split and the new window is shown in the other part of the screen; this way, you can read the contents of the current and the new window simultaneously. This command is especially useful for getting an index of news articles in one window and opening the articles in a new window without losing sight of the index.
• r - reload the current browser window document without looking into retawq's internal cache
• R - like "r", but additionally tries to bypass external caches ("enforced reload"); it also tries again to lookup the hostname if that failed previously
• g - go to a new URL; you can enter the new URL at the bottom of the screen; read URL Schemes for information about currently supported URLs.
• G - like "g", but the new URL is preset to the URL of the current document so you can edit it
• . (period) - stop any ongoing network/disk activity for the current document, e.g. stop receiving a web page
• \ (backslash) - show the HTML source code of the current browser window web page; to get back to the web page, use Cursor-left
• i - show information about the current link (or HTML form element) in the message line at the bottom of the screen
• I - show information about the current browser window view, e.g. about the links, images and forms which exist in a web page; the information is shown in a newly created window of window kind "information window".
• h - go to the "home" URL; by default, this is the retawq project home page; you can change this or turn it off completely with the run-time configuration option "home".
• e - go to your favorite search engine URL; you can set this with the run-time configuration option "search-engine".
• b - go to the bookmarks document URL; you can set this with the run-time configuration option "bookmarks".
• j - "jump" to a URL; you just enter a shortcut, and retawq goes to the associated URL as configured with the run-time configuration option "jumps". This is useful if you visit several URLs regularly and don't want to re-type the whole URLs each time, or if you want to "insert arguments" into often-used URL patterns, e.g. when using search engines.
• J - like "j", but the new jump shortcut is preset to the previously entered shortcut so you can edit it
• E - enable a disabled HTML form element; some wannabe-clever web page authors e.g. mark a submit button as disabled and let the browser enable it with a Javascript statement when the user fills in a certain text field; these authors ignore all the browsers which can't deal with Javascript - that's why you might need this command some time...

Other Commands:

• m - show the contextual menu
• u - show the URL history (a list of the most recently used URLs) in a menu
• D - download something from the URL which is given by the current link and save it in a file; you're asked for a filename; cf. "ctrl-d" for more information
• ctrl-d - download something from a URL and save it in a file; you're asked for the URL from which something shall be downloaded and for a filename; you can download from arbitrary URLs with the exception of local regular files - "downloading" them would be pointless anyway... The downloaded content isn't stored in retawq's internal caches, it is just saved in the file and "forgotten"; this way, you can receive very large contents without filling the RAM of your computer. Downloading happens "in the background", so it doesn't display any messages. It can't yet be paused/resumed and doesn't yet have a nice user interface - you can get some raw information about the progress by visiting (and reloading) the URL "about:activity" or by using the shell command "ls" for the file.
• ! (exclamation mark) - execute a shell command; for security reasons, this only works if the respective feature has been enabled with the compile-time configuration option OPTION_EXECEXT; you should additionally specify an explicit shell program with the run-time configuration option "execext-shell".
  With this keyboard command, you can execute any normal shell command from inside retawq like e.g. from inside textual console FTP clients. But retawq enables you to do more - you can prepend the command with a list of options; options are introduced with a colon (":") and end with a space character, after which the actual command is given, so the general format is ":options command"; the options are a sequence of letters with the following meaning:
  • o: read the output of the command (technobabble: from the "standard output" stream)
  • e: read any error messages of the command (technobabble: from the "standard error" stream)
  • H: interpret all received output as HTML source code
  • h: write a little header as input for the shell command; each header line is terminated by a line feed character ("\n"), and the header is terminated by an empty line; currently, the header only contains information about the retawq version number; later versions will contain more; the header might be useful if you execute special commands
  • c: write the content of the current document as input for the shell command; for example, this is useful if you want to convert the current document from a strange format to something which can be nicely displayed by retawq
  • i: interpret special "percent markers" in the shell command before executing it; for now, this only replaces the first occurrence of "%U" with the URL of the current document
  Please note that special shell characters aren't automatically escaped; this way you get more flexibility, but you should be aware of possible security implications.
  If you don't use any of the "read" options, the shell command is executed "in the background" and its output is discarded. This is useful for shell commands like "mkdir foo"; but for shell commands like "ls", you should at least use the option "o" to get the resulting directory listing, like so: ":oe ls".
  If you use any of the "read" options, the resulting output is shown in a window of window kind "information window".
• & - switch the shell command configuration which is used with the keyboard command "!"; this flips between a customized configuration which was given with the run-time configuration option "execext-shell" and the built-in standard configuration "/bin/sh -c".
• S - save the current session in a file
• M - resume a session from a file
• H - interpret the current document as HTML code; use this command if retawq can't determine the document kind automatically, e.g. when the name of a local HTML file doesn't end with ".htm" or ".html". - Please be careful to use this command only if the document really consists of HTML code; otherwise you'll get some mess on the screen because e.g. line breaks are shown as space characters and anything after a "<" is interpreted as an (invalid) HTML tag and probably not be displayed.
• Y - When you've enabled the mouse support (cf. the compile-time configuration option OPTION_TEXTMODEMOUSE), you can use this command to switch the terminal between the following two modes: "register mouse clicks on links and HTML form elements" and "allow copy-paste".
• Q - quit retawq

Line Input

Sometimes you are asked for additional information for a command: a message is displayed at the bottom line of the screen, and you have to input something there (or cancel). This is called "line input mode". There are basically two cases:

• You have to enter a single key, e.g. in order to confirm a question like: "Really close this window?" If the message is so long that it isn't completely visible, you can scroll it with the cursor keys, page up/down and home/end keys.
• You have to enter/edit some text, e.g. a URL (keyboard command "g") or a text field of an HTML form. You can edit it with the usual cursor, backspace, delete and return keys. If the message is so long that it isn't completely visible, you can use the key "ctrl-a" to switch into the message area, use keys to scroll it as explained above and then use "ctrl-a" again to get back into the edit area.

There's one special case: when you are asked for a login password and suddenly realize that the username was wrong, you can use the key "ctrl-u" ("u" as in "username") to go one step back and enter a new username first.