w3m MANUAL

Index

• Introduction
• Options
• Document Colors
• Functions and Key bindings
• Mouse Operation
• Local CGI scripts

Introduction

w3m is a pager/text-based WWW browser. You can browse local documents and/or documents on the WWW using a terminal emulator.

Options

Command line usage is

  w3m [option]... [file|URL]...

If you specify filenames/URLs on the command line, these documents are displayed. If you specify nothing, w3m will read a document from standard input and display it. If it doesn't find a document there either then normally w3m will terminate.

Options include:

General options

-B

with no other target defined, use the bookmark page for startup

-M

monochrome display

-no-mouse

deactivate mouse support.

-num

display each line's number

-v

with no other target defined, welcome users with a built-in page

-W

toggle wrapping mode in searches

-X

upon exit, do not reinitialize the terminal.

+num

go to line num; only effective for numbers larger than the number of lines in the terminal

Browser options

-cols num

with stdout as destination; HTML is rendered to lines of num characters

-cookie

use stored cookies and accept new ones

-no-cookie

neither use stored cookies nor accept new ones

-F

render frames

-no-graph

do not use graphic characters for drawing HTML table and frame borders

-header string

append string to the HTTP(S) request. Expected to match the header syntax "Variable: Value"

-m

display document using Internet message mode. With this option, w3m determines document type from header information. This is useful when reading e-mail or Usenet news posts.

-no-proxy

do not use proxy

-post file

use POST method to upload data defined in file. The syntax to be used is "var1=value1[&var2=value2]…"

Text pager options

-l num

number of lines preserved internally when receiving plain text from stdin (default 10,000)

-r

use caret notation to display special escape characters (such as ANSI escapes or nroff-style backspaces for bold and underlined characters) instead of processing them

-s

squeeze multiple blank lines into one

-t num

set tab width to num columns. No effect on stdout

Data type/encoding options

-I charset

user defined character encoding of input data

-O charset

user defined character encoding of output data

-T type

explicit characterization of input data by MIME type. Without this option, document type is determined from the extension of a file. If the determination fails, the document is regarded as text/plain. For example:

Read HTML document from standard input and display it

   cat example.html | w3m -T text/html

Display HTML source

   w3m -T text/plain example.html

Options for data output, followed by immediate exit

-dump

read document specified by URL and dump page rendered as text into standard output. Is set implicitly when output is directed to a file or pipe. A width of 80 columns is used unless option -cols sets another value.

-dump_source

dump the page's source code into stdout

-dump_head

dump response of a HEAD request for a URL into stdout

-dump_both

dump HEAD, and source code for a URL into stdout

-dump_extra

dump HEAD, source code, and extra information for a URL into stdout

Options for overriding default settings and resources

-bookmark file

use file instead of the default bookmark.html file

-config file

use file instead of the default configuration file

-o option=value

modify one configuration item with an explicitly given value; without option=value, equivalent to -show-option

Document Colors

Hyperlinks and images are displayed as follows.

These colors can be customized using the options setting command o.

Functions and Key bindings

After invocation, you can control w3m by typing in functions by name or with keystroke combinations bound to a function. There are default key bindings.

You can customize the key bindings (except those for menu operations and line-editing) in a ~/.w3m/keymap file. For example,

   keymap C-o NEXT_PAGE

binds the command NEXT_PAGE (normally bound to SPC and C-v) to control-o. See README.func for a list of available functions. Original and Lynx-like keymap definitions are provided as examples: keymap.default and keymap.lynx.

Throughout, the C- and M- notations indicate the modifiers control and meta. The ALT-key replaces the latter whereas pressing the ESC-key toggles between meta-modified and simple keystrokes. The minus indicates pressing the keys simultaneously wheras a space represents that one key is pressed after the other, i.e. 2 M simply means 2 followed by M.

There are the following operational modes with built-in key bindings for relevant functions. These bindings are not subject to the DEFINE_KEY function or entries in the file keymap.

Mouse Operation

If w3m is compiled with mouse support and you are invoking w3m either from a console with GPM or from an X terminal emulator, you can use the mouse for navigation (in the case of rxvt, you need to set the TERM environment variable to xterm or kterm).

An introduction to configure mouse actions is provided with README.mouse.

Local CGI scripts

You can run CGI scripts using w3m, without any HTTP server. This means that w3m behaves like an HTTP server and runs the CGI script, then reads the output of the script and displays it. For example, the bookmark registration system and default directory browser are realized as local CGI scripts. Moreover, such scripts allow w3m to be used as a form interface to acquire all kinds of data.

For security reason, CGI scripts invoked by w3m must be in one of the following directories:

• The directory where w3m-related files are stored (typically /usr/local/lib/w3m). This directory can be referenced as $LIB.
• The /cgi-bin/ directory. You can map /cgi-bin/ to any directory you like in the options setting panel (the Directory corresponds to /cgi-bin field). You can specify multiple paths separated by :, like /usr/local/cgi-bin:/home/aito/cgi-bin. It is not recommended to include the current directory to this path. To use a /cgi-bin/ directory, you must use a file:/cgi-bin URL as follows:

 w3m -o cgi_bin=/path/to/cgi-bin file:/cgi-bin/script.cgi

The CGI script can use the special header w3m-control: to control w3m. This field can take any function (see README.func), and the specified function is invoked after the document is displayed. For example, the CGI output

Content-Type: text/plain
W3m-control: BACK

will display a blank page and delete that buffer immediately. This is useful when you don't want to display any page after the script is invoked. The next example

Content-Type: text/plain
W3m-control: DELETE_PREVBUF
contents.....

will override the current buffer.

Each header w3m-control: can contain only one function, but you can include more than one w3m-control: line in the HTTP header. In addition, you can specify an argument to the GOTO function:

Content-Type: text/plain
W3m-control: GOTO http://www.example.org/

This example works exactly the same way as the Location header:

Content-Type: text/plain
Location: http://www.example.org/

Note that this header has no effect when the CGI script is invoked through an HTTP server.