# w3m MANUAL

Akinori Ito
aito@fw.ipsj.or.jp

## Index

- Introduction
- Options
- Document colors
- Key bindings
- Lynx-like key bindings
- Mouse operation
- Key customization
- Local CGI

## 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 [options] [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:

+number

  Move to the specified line-number.

-t width

  Specify tab width. Default is 8.

-r

  When displaying text/plain documents, prohibit emphasis using backspace. If you don't specify this option, A^H_ is interpreted as an underlined A and A^HA as a bold A.

-l number

  Specify the number of lines that should be cached while reading a text/plain document from standard input. Default is 10,000.

-O charset

  Specify display/output charset.

-I charset

  Specify document charset.

-T type

  Specify document 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

-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.

-v

  Show w3m's startup page.

-B

  Show w3m's bookmarks page.

-bookmark file

  Specify a custom bookmarks file.

-M

  Monochrome display mode.

-F

  Automatically render HTML frames.

-s

  Squeeze blank lines.

-X

  Upon exit, do not reinitialize the terminal.

-W

  Toggle wrapping mode in searches.

-o option=value

  Specify option. The available option names and values are the same as in ~/.w3m/config.

-cookie

  Process cookies.

-no-cookie

  Don't process cookies.

-num

  Show line-numbers.

-dump

  Read document specified by URL and dump page rendered as text into standard output. A width of 80 columns is used unless option -cols sets another value.

-cols width

  Specify document width. Used with -dump option.

-ppc count

  Specify the number of pixels per character (default 8.0). Larger values will make tables narrower.

-dump_source

  Read document specified by URL and dump the source.

-dump_head

  Read document specified by URL and dump headers.

-dump_both

  Read document specified by URL and dump headers and the source.

-dump_extra

  Read document specified by URL and dump extra informations, headers, and the source.

-post file

  Use POST method with file content.

-header string

  Insert string as a header.

-no-proxy

  Don't use proxy server.

-no-graph

  Use ASCII characters to draw frames rather than graphical ones.

-no-mouse

  Deactivate mouse support.

-config file

  Specify config file.

## Document colors

Links and images are displayed as follows.

| Color mode | Monochrome mode
--- | --- | ---
links | blue | underline
inline images | green | reverse
form input | red | reverse

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

## Key bindings

After invoking w3m, you can control it with keyboard commands.

Here's the original key-binding table. If you are using Lynx-like key bindings, see the Lynx-like key bindings. Throughout, the C- and M- notations indicate the modifiers control and meta (which can be replaced with alt or ESC); on the other hand 2 M simply means 2 followed by M.

### In-page navigation

SPC, C-v, +, PGDN | Forward page
b, M-v, -, PGUP | Backward page
l, C-f, RIGHT | Cursor right
h, C-b, LEFT | Cursor left
j, C-n, DOWN | Cursor down
k, C-p, UP | Cursor up
J | Scroll screen up one line
K | Scroll screen down one line
^, C-a | Go to the beginning of line
$, C-e | Go to the end of line
w | Go to the next word
W | Go to the previous word
> | Shift screen right
< | Shift screen left
. | Shift screen one column right
, | Shift screen one column left
g, M-<, HOME | Go to the first line
G, M->, END | Go to the last line
M-g | Go to the specified line
Z | Center on cursor column
z | Center on cursor line
TAB | Move to the next hyperlink
C-u, M-TAB | Move to the previous hyperlink
[ | Move to the first hyperlink
] | Move to the last hyperlink

### Hyperlink operation

C-j, C-m, RET | Follow hyperlink
a, M-RET | Save link to file
u | Show link URL
i | Show image URL
I | View inline image
M-I | Save inline image to file
: | Mark URL-like strings as hyperlinks
M-: | Mark Message-ID-like strings as links
c | Show current URL
= | Show information about current document
C-g | Show current position in page
C-h | Show browsing history
M | Browse current document using external browser (prefix 2, 3, ..., or 9 to invoke alternate configured browsers, e.g. 3 M)
M-M | Browse link using external browser (prefixed as above, e.g. 3 M-M)

### Bookmark management

M-b | Go to the bookmarks page
M-a | Bookmark current page

### File/stream operation

U | Open new URL
V | Open new file
@ | Execute shell command and view output
# | Execute shell command and browse output

### Content operations

v | Toggle viewing as text or rendered HTML
F | Toggle rendering HTML frames
C-l | Redraw screen
R | Reload
E | Edit local source
M-e | Edit rendered copy of page
M-s | Save source
S | Save rendered copy of page

### Buffer/tab navigation

B | Go back, popping the buffer stack
s | Show buffer-stack menu
M-t | Show tab menu
T | Open current page as new tab
C-t | Open link as new tab
} | Switch to next tab
{ | Switch to previous tab
C-q | Close current tab

### Search

/ | Search forward
? | Search backward
C-s | Incremental search forward
C-r | Incremental search backward
n | Next match
N | Previous match
C-w | Toggle wrapping mode in searches

### Mark management

C-SPC | Set/unset mark
M-p | Go to the previous mark
M-n | Go to the next mark
" | Mark all occurrences of a regular expression

### Miscellany

! | Execute shell command
M-c | Invoke w3m function
H | Show help panel
o | Show options panel
C-k | Show cookie jar
C-c | Interrupt
C-z | Suspend w3m
q | Quit (with confirmation dialog)
Q | Quit without confirmation

Two special operational modes exist which have built-in (not redefinable) keymappings:

### Menu selection mode

k, C-p, UP | Select previous item
j, C-n, DOWN | Select next item
D | Delete current item
SPC, RET | Go to the selected item

### Line-editing mode

C-f, RIGHT | Move cursor forward
C-b, LEFT | Move cursor backward
C-h, BKSPC | Delete previous character
C-d | Delete current character
C-k | Kill everything after cursor
C-u | Kill everything before cursor
C-a | Move to the beginning of line
C-e | Move to the end of line
C-p, UP | Fetch the previous string from the history list
C-n, DOWN | Fetch the next string from the history list
TAB, SPC | Try to complete filename
RET | Accept

## Lynx-like key bindings

If w3m was compiled with Lynx-like key bindings, you can use the following key bindings.

### In-page navigation

SPC, C-v, + | Forward page
b, M-v, - | Backward page
l | Cursor right
h | Cursor left
j | Cursor down
k | Cursor up
J | Scroll screen up one line
K | Scroll screen down one line
^ | Go to the beginning of line
$ | Go to the end of line
> | Shift screen right
< | Shift screen left
. | Shift screen one column right
, | Shift screen one column left
C-a, M-< | Go to the first line
C-e, M-> | Go to the last line
G | Go to the specified line
w | Go to the next word
W | Go to the previous word
Z | Center on cursor line
z | Center on cursor column
TAB, C-n, DOWN | Move to the next hyperlink
M-TAB, C-p, C-u, UP | Move to the previous link
C-g | Show current position in page
[ | Move to the first hyperlink
] | Move to the last hyperlink

### Hyperlink operation

C-f, C-j, C-m, RET, RIGHT | Follow hyperlink
d, M-RET | Save link to file
u | Show link URL
i | Show image URL
I | View inline image
M-I | Save inline image to file
: | Mark URL-like strings as hyperlinks
M-: | Mark Message-ID-like strings as news anchors
c | Show current URL
= | Show information about current document
C-h | Show browsing history
M | Browse current document using external browser (prefix 2, 3, ..., or 9 to invoke alternate configured browsers, e.g. 3 M)
M-M | Browse link using external browser (prefixed as above, e.g. 3 M-M)

### Bookmark management

v, M-b | Go to the bookmarks page
a, M-a | Bookmark current page

### File/stream operation

g, U | Open new URL
V | Open new file
@ | Execute shell command and view output
# | Execute shell command and browse output

### Content operations

\ | Toggle viewing as text or rendered HTML
F | Toggle rendering HTML frames
C-l, C-w | Redraw screen
R, C-r | Reload
E | Edit local source
M-e | Edit rendered copy of page
M-s | Save source
S, p | Save rendered copy of page

### Buffer/tab navigation

B, C-b, LEFT | Go back, popping the buffer stack
s, C-h | Show buffer-stack menu
M-t | Show tab menu
T | Open current page as new tab
C-t | Open link as new tab
} | Switch to next tab
{ | Switch to previous tab
C-q | Close current tab

### Search

/, C-s | Search forward
n | Next match
w | Toggle wrapping mode in searches

### Mark management

C-SPC | Set/unset mark
P | Go to the previous mark
N | Go to the next mark
" | Mark all occurrences of a regular expression

### Miscellany

! | Execute shell command
M-c | Invoke w3m function
H, ? | Show help panel
o | Show options panel
C-k | Show cookie jar
C-c | Interrupt
C-z | Suspend w3m
q | Quit (with confirmation dialog)
Q | Quit without confirmation

The Lynx-like configuration leaves keymappings unchanged in the menu-selection and line-editing modes.

## 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).

left click | Move the cursor to the place indicated by the mouse cursor. If you click the cursor and it is on a hyperlink, follow the link.
middle click | Back to the previous buffer.
right click | Open pop-up menu. You can choose an item by clicking it.
left drag | Scroll document. The default behavior is to grab the document and drag it. You can reverse the behavior (grab the window and drag it) with the option setting panel.

## Key customization

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

       keymap C-o NEXT_PAGE

binds the NEXT_PAGE function (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 (keymap.default and keymap.lynx) as examples.

## Local CGI

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 option 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. 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

  It is not recommended to include the current directory to this path.

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 w3m-control: header 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.