retawq Documentation
Keyboard Handling
(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 browse to 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.
It is a known problem that certain special keys like "Home" or "Page Up"
don't work on all kinds of terminals. If you encounter this problem, please
have a look at the run-time configuration option
"keymap", which makes it possible to use different keys.
Commands
Window Handling:
- n - create a new "virtual window"; the old window in which you were
working will not be removed (and activities running there won't be stopped),
you can get back to it with the commands "w", "W" and "ctrl-w".
- N - open the current document in a new 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
View Handling:
- Cursor-left - go back to the previous document in the series of
documents in the current window
- Cursor-right - go to the next document in the series of documents in
the current window; note: to follow a link, use the Return/Enter/o key instead
(see below) - here retawq differs from other browsers.
- 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
Web Browsing:
- 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 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 see 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 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; see 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 web page;
use Cursor-left to get back to the web page
- i - show information about the current link (or HTML form element)
in the message line at the bottom of the screen
- 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)
- / (slash) - search for a string in the current document in a
case-insensitive way; you'll be 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 will be 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'll be asked for a filename. Saving will automatically
proceed until the whole document has been received or until reception is
stopped.
- d - dump the current document (layouted) into a file; you'll be
asked for a filename. The document will only be dumped as far as it has already
been received. To dump the source code of an HTML document, view the
source code with the keyboard command "\" and dump from there.
- D - download something from the URL which is given by the current
link and save it in a file; you'll be asked for a filename; see "ctrl-d" for
more information
- ctrl-d - download something from a URL and save it in a file; you'll
be asked for the URL from which something shall be downloaded and for a
filename; you can download from arbitrary URLs (cf. URL
Schemes) with the exception of local regular files - "downloading" them
would be pointless anyway... The downloaded content won't be stored in retawq's
internal caches, it will just be saved in the file and "forgotten"; this way,
you can receive very large contents without filling the RAM of your computer.
Downloading can't yet be paused/resumed and doesn't yet have a nice user
interface - you can get some raw information by visiting (and reloading) the URL "about:activity" or by using the shell command "ls"
for the file.
- ! - execute a shell command; for security reasons, this will only
work 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 will only replace the first occurrence of "%U" with
the URL of the current document
If you don't specify any of the "read" options, the shell command will be
executed in the background, and its output will be 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 see the resulting directory listing, like
so: ":oe ls".
If you use any of the "read" options, the resulting document can't (yet) be
handled in all regards as the usual documents which result from a URL access;
you might have to save the resulting document in a file and open that file to
perform certain keyboard commands on it.
- & - switch the shell command configuration; this will flip
between the 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 see some mess on the screen because e.g. line breaks are shown as space
characters and anything after a "<" will be interpreted as an (invalid) HTML
tag and probably not be displayed.
- Y - When you've enabled the mouse support (see 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're 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 an FTP 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.
This documentation file is part of version 0.2.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-2004 Arne Thomaßen.