Introduction

A session is information about the current state of retawq. More precisely, it is information about all "virtual windows" which are currently open and about the documents which are shown in the views of each window.

You can save this information at any time into an arbitrary local file with the keyboard command "S". Once you have saved the session, you can resume it at any later time, even after the program was quit and restarted. This allows you to get quickly back to where you were.

To resume a session when you start the program, you can use the command-line option "--resume-session". To resume a session while the program is running, use the keyboard command "M"; in this case, the current state is not "lost", it is only supplemented by the resumed session. Resuming from a session file does not remove or modify the file, so you can resume from the same file again and again.

Problems

When you save a session, not all state information is saved, because that would result in very big, complicated files. (Simpler files have the advantage that you can create or edit them by hand, if you want to; cf. the file format description below.) The following problems can occur; they mostly concern very rare conditions, so they shouldn't cause much trouble in practice.

• When a document was the result of an HTTP "post" operation, you won't get it when resuming, mostly for the following reasons: 1. the post-data (which might be very large) isn't stored in a session file; 2. the "post" method is often used for tasks like adding a record to a database, and adding a record twice normally isn't a good idea.
• All of your changes in resumed HTML forms are lost, so you might e.g. have to re-enter texts.
• When you resume a session which contained many non-local documents (e.g. from HTTP URLs), a "download storm" will break loose. This is because retawq doesn't yet have a disk cache and must receive all the non-local documents again.

File Format

A session file consists of a series of text lines:

• A line beginning with a "#" character is a comment line and ignored.
• A line beginning with "W:" marks the creation of a new virtual window; any subsequent "U:" lines open documents in new views within that window until the next "W:" occurs. If this line contains a "v" part with a number 0 or 1, this means it's the currently visible window with that number.
• A line beginning with "U:" opens a URL in a new view in the current window. The line consists of several descriptive parts; all parts besides the URL are optional. Each part begins with the character sequence "|#|", followed by a lowercase letter and a ":"; the letters have the following meaning:
  • u: the URL of the document
  • f: special flags; in this part, an "h" means "enforce HTML" (cf. the keyboard command "H"); an "s" shows the document as source code, even if it would normally be interpreted as HTML; a "c" means that this URL is the "current" one in the window, that is, the one which is shown when the window is visible
  • l: a line number, indicating how far you had scrolled down in the document; not yet used
  • w: the width of the view; not yet used
  • h: a title for a document which is not interpreted as HTML (if a document is interpreted as HTML, the title is taken from the HTML <title> tag)

If this format seems too complicated, just save a session and read the resulting file - it's really simple. :-)