retawq supports several types ("schemes") of URLs. The scheme specifies how a resource is accessed, e.g. which network protocol is used. This page lists a few examples of currently supported URLs and general notes to show what's possible and how retawq interprets URLs, including some "magic assumptions" (built-in defaults) for URLs which don't contain an explicit scheme.
retawq can currently handle the following schemes: "http", "https" (if enabled), "ftp", "ftps" (if enabled), "news"/"nntp" (if enabled), "finger", "file"/"local", "local-cgi" (if enabled), "about". The scheme "local-cgi" is retawq-specific; a similar feature is available in Lynx with the scheme "lynxcgi". The scheme "about" is available in several other web browsers, but with different URLs.
Since the "U" in "URL" means "uniform", retawq tries to apply the general URL format "scheme://username:password@hostname:portnumber/path?query#fragment" to all URLs as far as possible. One little disadvantage is that local file/directory/script names can't contain the special characters "?" and "#", because these characters are interpreted as the beginning of query and fragment parts, respectively (and the query part is actually used, e.g. for local directory sorting options).
The "#fragment" part of a URL is recognized and removed, but not yet handled.
"http://foo.org/" - receive the document "/" (usually this means "/index.html" or "/index.htm") from the server "foo.org" via HTTP; the default HTTP port (80) is used.
"foo.org" - the same unless you have a file or directory with that name in the current directory on your local computer
"www.foo.org" - if no explicit scheme is given and the domain name begins with "www.", the HTTP scheme is assumed, no matter whether a file or directory with that name exists on your local computer
"http://foo.org:42/bar.html" - receive the document "/bar.html" from the server "foo.org" via HTTP; the non-standard port 42 is used.
"http://foo.org/cgi-bin/bar.cgi?whatever" - send the query "whatever" to the CGI script "/cgi-bin/bar.cgi" on the HTTP server "foo.org" and receive the resulting document
The scheme "https" works very much like "http", except that TLS/SSL (which must have been enabled) is used for secure network communications.
"ftp://ftp.foo.org/" - receive the top-level FTP directory ("/") from the FTP server ftp.foo.org; the default FTP port (21) is used.
"ftp.foo.org" - the same; if no explicit scheme is given and the domain name begins with "ftp.", the FTP scheme is assumed.
"ftp://ftp.foo.org:42/bar/" - receive the directory "/bar" from the server ftp.foo.org via FTP; the non-standard port 42 is used.
"ftp://username:password@ftp.foo.org/home/user/" - receive the directory "/home/user" from the server ftp.foo.org via FTP, logging in as user "username" with password "password"; if you need to log in frequently, consider using the run-time configuration option "ftp-login".
The scheme "ftps" works very much like "ftp", except that TLS/SSL (which must have been enabled) is used for secure network communications.
Some server programs can only protect the control connection, not the data connection; please read about the run-time configuration option "ftps-method", especially the method specifier "authtls-dataclear".
These schemes only work if the compile-time configuration option OPTION_NEWS has been enabled. The scheme "nntp" is handled in exactly the same way as the scheme "news"; the different scheme names only exist due to historical differences in protocol specifications.
If the URL doesn't contain an explicit domain name, retawq uses the default name as configured with the run-time configuration option "news-server-default". (If no explicit name is given and no default name is configured, you get a "Hostname missing" error.) Some of the following examples assume that a default name has been configured, just to improve readability.
"news://news.foo.org/" - show a list of all news groups which are available on the server "news.foo.org"; the default NNTP port (119) is used.
"news.foo.org" - the same; if no explicit scheme is given and the domain name begins with "news.", the news scheme is assumed.
"news:alt.fan.douglas-adams" - show an index of all articles in the news group "alt.fan.douglas-adams" on the default news server, latest first
"news:alt.fan.douglas-adams/100-200" - similar, but the index only shows the articles with the numbers 100 to 200 (as far as they exist)
"news:alt.fan.douglas-adams/100" - show the article (header and body) with the number 100 in the news group "alt.fan.douglas-adams" on the default news server
"news:foo@bar.com" - show the article (header and body) with the so-called message identifier "foo@bar.com"; the message identifier of an article "should" be world-wide unique across all servers and groups, so this is the preferred form of referencing (e.g. when putting a link on a web page) a news article; in contrast to message identifiers, the above combinations of group names and plain article numbers aren't unique because different servers might use different numbers for the same article and vice versa. - Message identifiers can be recognized by the presence of an "@" character.
"finger://username@foo.org" - show information about the user "username" on the server "foo.org"; the default finger port (79) is used.
"finger://username@foo.org:42" - show information about the user "username" on the server "foo.org"; the non-standard port 42 is used.
"finger://finger.kernel.org" - show information about current Linux kernel versions
"local:/home/" - list the contents of the local directory "/home"
"/home" - the same; if no explicit scheme is given and the URL begins with "/", "~/" or "./", a local file/directory is assumed
"local:/home/foo/bar.html" - show the local file "/home/foo/bar.html"
"local:~/foo/bar.html" - show the local file "foo/bar.html" in the user's local home directory (depending on the environment variable "HOME"); normally this results in an absolute path like "/home/your_home/foo/bar.html".
"local:/home/my_home?sort=tS" - show the contents of the local directory "/home/my_home", sorted by file type (lowercase "t", ascending) and size (uppercase "S", descending); cf. the run-time configuration option "local-dir-sort" for more information.
"local:foo/bar.html" - show the local file "foo/bar.html" in the "current" directory; this is normally the directory in which you were when you launched retawq.
Most other browsers use the scheme "file" instead of "local"; with retawq, you can use both of them, and they have the same meaning; "local" is just preferred because "file" might seem as if you could only access files and no directories...
retawq only reads regular files and directories; for example, it doesn't try to read from device nodes like "/dev/zero". It shows "Document empty" messages if the operating system erroneously reports a file size 0, which might e.g. be the case for system-generated files inside the directory "/proc".
"local-cgi:/usr/cgi-bin/script.cgi" - launch the script "/usr/cgi-bin/script.cgi" on the local computer and show its output
For security reasons, this scheme only works if the compile-time configuration option OPTION_LOCAL_CGI has been enabled, and scripts are only launched as the run-time configuration option "local-cgi" explicitly allows it.
retawq currently uses version 1.1 of the Common Gateway Interface (CGI) specification to launch scripts. There's a script example available.
"about:retawq" - show information about retawq and possibly about used libraries; this is normally shown when you start retawq in curses-like runmode without providing URLs on the command-line.
"about:" - the same
"about:help" - a quick pointer to locations where documentation is available; the link for the local URL only works if you installed the package properly, e.g. with "make install".
"about:activity" - show some raw information about retawq's current activity, e.g. about the open connections to servers; this doesn't yet look nice and you have to reload it manually to get updated information, but it might be useful sometimes, especially when downloads are running
"about:hostinfo" - show some raw information about hosts which have been visited or whose names have been looked up in the DNS (Domain Name System); this information was mostly intended for debugging, but it might sometimes be generally useful to find out the IP addresses of certain hosts
"about:ctconfig" - show information about the actual values of compile-time configuration options which were used when retawq was built
"about:birtcfg" - show the text of a built-in run-time configuration; cf. the compile-time configuration option OPTION_BIRTCFG.