5.1 General variables

w3m-accept-languages

List of acceptable languages in descending order of priority. The default value is set according to the `accept_language' entry of the `w3m' configuration file (normally `~/.w3m/config').

w3m-add-referer

Rule of sending referers. There are five choices as the valid values of this option.

1. nil: this means that emacs-w3m never send referers.

2. t: this means that emacs-w3m always send referers.

3. lambda: this means that emacs-w3m send referers only when both the current page and the target page are provided by the same server.

4. a cons cell keeping two regular expressions: this means that emacs-w3m send referers when the url of the current page matches the first regular expression and does not match the second regular expression. Nil for the regexp matches any url.

5. a function: emacs-w3m send referers when this function which has two arguments, URL and REFERER, returns non-nil.

If you're nervous about leaking private WEB browsing history information, set this option to `nil' or `lambda'. If your computer belongs to a secret network, you may set a pair of regular expressions to inhibit sending referers which will disclose your private information, as follows:

(setq w3m-add-referer '("\\`http:\" . "\\`http://\\([^./]+\\.\\)*example\\.net/"))

w3m-add-user-agent

Non-nil means add the User-Agent field to the request header. The value of w3m-user-agent is used for the field body.

w3m-arrived-file

Name of the file to keep the arrived URLs database.

w3m-auto-show

Non-nil means provide the ability to horizontally scroll the window. Automatic horizontal scrolling happens when the point gets away from both ends of the window, but nothing occurs if truncate-lines is set to nil.

This feature works with specific emacs-w3m code; usual auto-hscroll-mode, automatic-hscrolling, auto-show-mode or hscroll-mode will all be invalidated in emacs-w3m buffers.

w3m-charset-coding-system-alist

Alist of MIME charsets and coding systems. Both charsets and coding systems must be symbols.

w3m-coding-system

Default coding system used to communicate with the `w3m' command.

w3m-coding-system-priority-list

Coding systems in order of priority used for emacs-w3m sessions.

w3m-command

Name of the executable file of the `w3m' command. You normally don't have to specify the value, since emacs-w3m looks for the existing commands `w3m', `w3mmee' and `w3m-m17n' (in this order) in the exec-path directories in order if it is nil in the beginning.

If you want to use the other `w3m' command, specify the value of this variable explicitly in the .emacs file or customize the value and save it. In this case, you need to restart Emacs and emacs-w3m: there is currently no way to apply the changing of the `w3m' command to all the emacs-w3m programs safely after loading the `w3m.elc' module.

w3m-command-arguments

List of the default arguments passed to the `w3m' command. See also w3m-command-arguments-alist.

w3m-command-arguments-alist

Alist of regexps matching urls and additional arguments passed to `w3m'. A typical usage of this variable is to specify whether to use a proxy server for particular hosts. The first match made will be used. Here is an example of how to set this variable:

(setq w3m-command-arguments-alist '(;; Don't use the proxy server to visit local web pages. ("^http://\\([^/]*\\.\\)*your-company\\.com\\(/\\|$\\)" "-no-proxy") ;; Use the proxy server to visit any foreign urls. ("" "-o" "http_proxy=http://proxy.your-company.com:8080/")))

Here the first element matches any url where the scheme is `http' and the hostname is either `your-company.com' or a name ending with `.your-company.com'; the proxy server is not used for those hosts. If you are a regexp novice, you can use the w3m-no-proxy-domains variable instead.

w3m-command-environment

Alist of environment variables for subprocesses to inherit.

w3m-content-type-alist

Alist of file suffixes and content types.

w3m-correct-charset-alist

Alist of MIME charsets; strange ones and standard ones.

w3m-db-history-display-size

Maximum number of arrived URLs which are displayed per page.

w3m-decoder-alist

Alist of encoding types, decoder commands, and arguments.

w3m-default-coding-system

Default coding system used to encode url strings and post-data.

w3m-default-content-type

Default value assumed as the content type of local files.

w3m-default-save-directory

Default directory where downloaded files will be saved to.

w3m-delete-duplicated-empty-lines

Non-nil means display two or more continuous empty lines into single.

w3m-dirlist-cgi-program

Name of the CGI program to list a local directory. If it is nil, the dirlist.cgi module of the `w3m' command will be used.

w3m-edit-function

Function used for editing local files. It is used when the w3m-edit-current-url command or the w3m-edit-this-url command is invoked.

w3m-edit-function-alist

Alist of functions used for editing pages. This option is refered to decide which function shouled be used to edit a specified page, when either w3m-edit-current-url or w3m-edit-this-url is invoked. When no suitable function is found from this alist, w3m-edit-function is used.

w3m-encoding-type-alist

Alist of file suffixes and content encoding types.

w3m-file-coding-system

Coding system used when writing configuration files. This value will be referred to by the w3m-save-list function.

w3m-file-name-coding-system

Coding system used to convert pathnames when emacs-w3m accesses files.

w3m-fill-column

Integer used as the value for fill-column in emacs-w3m buffers. If it is positive, pages will be displayed within the columns of that number. If it is zero or negative, the number of columns which subtracted that number from the window width is applied to the maximum width of pages. Note that XEmacs does not always obey this setting.

w3m-follow-redirection

Maximum number of redirections which emacs-w3m honors and follows. If nil, redirections are followed by the `w3m' command. Don't set it to nil if you allow to use cookies (i.e., you have set w3m-use-cookies to non-nil) since cookies may be shared among many redirected pages.

w3m-home-page

This variable specifies the url string to open when emacs-w3m starts. Don't say HP, it's the abbreviated name of a certain company. ;-)

w3m-horizontal-scroll-columns

Number of steps in columns used when scrolling a window horizontally.

w3m-horizontal-scroll-division

Integer used by the program making the point certainly visible. The cursor definitely does not go missing even when it has been driven out of the window while wandering around anchors and forms in an emacs-w3m buffer.

Suppose that the value of this variable is N. When the point is outside the left of the window, emacs-w3m scrolls the window so that the point may be displayed on the position within 1/N of the width of the window from the left. Similarly, when the point is outside the right of the window, emacs-w3m scrolls the window so that the point may be displayed on the position of 1/N of the width of the window from the right.

This feature doesn't work if w3m-auto-show is nil. The value must be a larger integer than 1.

w3m-horizontal-shift-columns

Number of steps in columns used when shifting a window horizontally. The term `shifting' means a fine level scrolling.

w3m-imitate-widget-button

If non-nil, imitate the widget buttons on link (anchor) buttons. It is useful for moving about in a Gnus article buffer using TAB key. It can also be any Lisp form that should return a boolean value.

w3m-init-file

Your emacs-w3m startup file name. If a file with the `.el' or `.elc' suffixes exists, it will be read instead.

Note: This file is used as the startup configuration NOT for the `w3m' command but for emacs-w3m. In order to modify configurations for the `w3m' command, edit the file named `~/.w3m/config' normally.

w3m-input-coding-system

Coding system used when writing to `w3m' processes. It overrides coding-system-for-write if it is not binary. Otherwise, the value of the w3m-current-coding-system variable is used instead.

w3m-keep-arrived-urls

Maximum number of URLs which the arrived URLs database keeps.

w3m-keep-cache-size

Maximum number of pages to be cached in emacs-w3m.

w3m-key-binding

Type of key binding set used in emacs-w3m sessions. The valid values include info which provides Info-like keys, and nil which provides Lynx-like keys.

w3m-language

Your preferred language used in emacs-w3m sessions.

w3m-local-directory-view-method

Symbol of the method to view a local directory tree. The valid values include w3m-cgi using the CGI program specified by the w3m-dirlist-cgi-program variable (which see), and w3m-dtree using the w3m-dtree Lisp module.

w3m-local-find-file-function

Function used to open local files. If a url of the file: scheme in which you entered agrees with the rule of the w3m-local-find-file-regexps variable (which see), it is used to open the file.

Function should take one argument, the string naming the local file. It can also be any Lisp form returning a function. Set this to nil if you want to always use emacs-w3m to see local files.

w3m-local-find-file-regexps

Cons of two regexps matching and not matching with local file names. If a url of the file: scheme in which you entered matches the first form and does not match the latter form, it will be opened by the function specified by the w3m-local-find-file-function variable. Nil for the regexp matches any file names.

For instance, the value (nil . "\\.html?\\'") allows `file:///some/where/w3m.el', not `file:///any/where/index.html', to open by the function specified by w3m-local-find-file-function. The latter will be opened as a normal web page.

It is effective only when the w3m-local-find-file-function variable is set properly.

w3m-mailto-url-function

Function used to handle the mailto urls. Function is called with one argument, just a url. If it is nil, a function specified by the mail-user-agent variable will be used for composing mail messages.

w3m-mailto-url-popup-function-alist

Alist of (MAJOR-MODE . FUNCTION) pairs used to pop a mail buffer up. If a user clicks on a mailto url and a mail buffer is composed by mail-user-agent with the MAJOR-MODE, FUNCTION will be called with a mail buffer as an argument. Note that the variables special-display-buffer-names, special-display-regexps, same-window-buffer-names and same-window-regexps will be bound to nil while popping to a buffer up.

w3m-make-new-session

Non-nil means making new emacs-w3m buffers when visiting new pages. If it is non-nil and there are already emacs-w3m buffers, the w3m command makes a new emacs-w3m buffer if a user specifies a url string in the minibuffer, and the w3m-safe-view-this-url command also makes a new buffer if a user invokes it in a buffer not being running the w3m-mode. The default value is nil.

w3m-mbconv-command

Name of the `mbconv' command provided by the `libmoe' package. The `libmoe' package is used when you use the `w3mmee' command instead of the `w3m' command. See also w3m-command.

w3m-no-proxy-domains

List of domain names for which emacs-w3m will not use a proxy server. Each element should be exactly a domain name which means the latter common part of the host names, not a regexp.

w3m-output-coding-system

Coding system used when reading from `w3m' processes.

w3m-pop-up-frames

Non-nil means pop to a new frame up for an emacs-w3m session. This variable is similar to pop-up-frames and does override w3m-pop-up-windows. If w3m-use-tab is non-nil or there is the buffers selection window (for the w3m-select-buffer feature), this variable is ignored when creating the second or more emacs-w3m session.

w3m-pop-up-windows

Non-nil means split the windows when a new emacs-w3m session is created. This variable is similar to pop-up-windows and quite overridden by w3m-pop-up-frames as if pop-up-frames influences. Furthermore, if w3m-use-tab is non-nil or there is the buffers selection window (for the w3m-select-buffer feature), this variable is ignored when creating the second or more emacs-w3m session.

w3m-popup-frame-parameters

Alist of frame parameters used when creating a new emacs-w3m frame. It allows not only the alist form but also XEmacs' plist form.

w3m-prefer-cache

Non-nil means that cached contents are used without checking headers.

w3m-profile-directory

Directory where emacs-w3m config files are loaded from or saved to.

w3m-quick-start

Non-nil means let emacs-w3m start quickly w/o requiring confirmation. When you invoke the w3m command, it attempts to visit the page of a string like url around the cursor or the value of w3m-home-page. You won't be asked for the confirmation then if this value is non-nil. Otherwise, you will be prompted for that url with the editing form.

w3m-redirect-with-get

If non-nil, use the GET method after redirection. It controls how emacs-w3m works when a server responds the code 301 or 302. Here is an extract from RFC2616:

Note: RFC 1945 and RFC 2068 specify that the client is not allowed to change the method on the redirected request. However, most existing user agent implementations treat 302 as if it were a 303 response, performing a GET on the Location field-value regardless of the original request method.

w3m-relationship-estimate-rules

Rules to estimate relationships between a retrieved page and others.

w3m-select-buffer-horizontal-window

Non-nil means split windows horizontally to open the selection window.

w3m-select-buffer-window-ratio

The percentage of the selection window to the whole frame. The car is used when splitting windows horizontally and the cdr is for splitting windows vertically.

w3m-show-decoded-url

Non-nil means show decoded URIs in the echo area, the balloon, etc. This variable can take one of the following five kinds of forms:

1. t

   Decode URIs using the encoding assumed by the default presumption rule based on the priority list including the encoding used to decode the current page and the value of w3m-coding-system-priority-list.

2. Coding system

   Decode URIs using this value.

3. List of coding systems

   Decode URIs using the encoding assumed based on this list.

4. Alist of predicates and forms described below:

   Each element looks like the (PREDICATE . ENCODING) form. PREDICATE should be a regexp, a function or a Lisp form, and ENCODING should be one of the forms described here excluding this form. If PREDICATE is a regexp, it will be tested whether it matches to the current url. If it is a function, it will be called with no argument. If it is a Lisp form, it will be simply evaluated. Elements are tested in turn until the result of the test of the predicate is true and the encoding which is associated to the predicate is used for decoding URIs.

5. nil

   Don't decode URIs.

w3m-show-error-information

Non-nil means show an error information as a web page. Page is made when the foreign server doesn't respond to a request to retrieve data.

w3m-space-before-favicon

String of space char(s) to be put in front of favicon in the mode-line. It may be better to use two or more spaces if you are using oblique or italic font in the modeline.

w3m-space-before-modeline-icon

String of space character(s) to be put in front of the modeline icon. It may be better to use one or more spaces if you are using oblique or italic font in the modeline.

w3m-terminal-coding-system

Default coding system used when writing to `w3m' processes. It is just a default value to set process' coding system initially. (This variable name is analogically derived from the behavior of the `w3m' command which accepts data from Emacs just like reads from the terminal.)

w3m-touch-command

Name of the executable file of the touch command. Note that the command is required to be able to modify file's timestamp with the `-t' option.

w3m-track-mouse

Whether to track the mouse and message the url under the mouse. This feature does not work under Emacs or XEmacs versions prior to 21. See also show-help-function if you are using Emacs 21 or later.

A tip for XEmacs users:

You can also use the balloon-help feature by the M-x balloon-help-mode command with arg 1. If the window manager decorates the balloon-help frame, and that is not to your taste, you may strip it off with the following directives:

For ol[v]wm use this in .Xdefaults: olvwm.NoDecor: balloon-help or olwm.MinimalDecor: balloon-help For fvwm version 1 use this in your .fvwmrc: NoTitle balloon-help or Style "balloon-help" NoTitle, NoHandles, BorderWidth 0 For twm use this in your .twmrc: NoTitle { "balloon-help" }

See the `balloon-help.el' file for more information.

w3m-uri-replace-alist

Alist of regexps matching URIs, and some types of replacements. It can be used universally to replace URI strings in the local rule to the valid forms in the Internet.

Each element looks like the (REGEXP FUNCTION OPTIONS...) form. FUNCTION takes one or more arguments, a uri and OPTIONS. You can use the grouping constructs `\\(...\\)' in REGEXP, and they can be referred by the `\N' forms in a replacement (which is one of OPTIONS).

Here are some predefined functions which can be used for those ways:

w3m-pattern-uri-replace

Replace a URI using PATTERN (which is just an OPTION). It is allowed that PATTERN contains the `\N' forms in the same manner of replace-match.

w3m-search-uri-replace

Generate valid URLs to query words on some specified search engines. For example, the element

("\\`gg:" w3m-search-uri-replace "google")

makes it possible to replace the URI `gg:emacs' to a query for the word `emacs' on the Google search engine.

w3m-url-local-directory-alist

Alist of URLs and local directories. If directory names of a given URL and the car of an element are the same, emacs-w3m assumes that the file exists in the local directory where the cdr of an element points to. The default value will be set to a value of the yahtml-path-url-alist variable which exchanged the car and the cdr in each element if it is available.

w3m-use-ange-ftp

Non-nil means that ange-ftp or efs is used to access FTP servers.

w3m-use-cygdrive

If non-nil, use the `/cygdrive/' rule when performing expand-file-name.

w3m-use-filter

Non-nil means use filter programs to convert web contents. See also w3m-filter-rules.

w3m-use-form

Non-nil means make it possible to use form extensions. (EXPERIMENTAL)

w3m-use-header-line

Non-nil means display the header line.

w3m-use-mule-ucs

Non-nil means use the multi-script support with Mule-UCS.

w3m-use-refresh

Non-nil means honor the REFRESH attribute in META tags. Emacs-w3m arbitrarily takes you to a url specified by that attribute. Note that they may be malicious traps.

w3m-use-symbol

Non-nil means replace symbols that the `<_SYMBOL>' tags lead into. It is meaningful only when the `w3m-m17n' command is used and (X)Emacs handles unicode charsets.

w3m-use-tab

Non-nil means make emacs-w3m a tab browser. It makes it possible to show all emacs-w3m buffers in a single window with the tabs line, and you can choose one by clicking a mouse on it. Unfortunately, users of Emacs 20 and less cannot enjoy this feature. See also w3m-use-tab-menubar.

w3m-use-tab-menubar

Non-nil means use the TAB pull-down menu in the menubar. It makes it possible to show all emacs-w3m buffers in a single window, and you can choose one by clicking a mouse on it. This feature requires that Emacs has been built to be able to display multilingual text in the menubar if you often visit web sites written in non-ascii text. See also w3m-use-tab.

w3m-use-toolbar

Non-nil activates toolbar of `w3m'.

w3m-user-agent

String used for the User-Agent field. See also w3m-add-user-agent.

w3m-view-this-url-new-session-in-background

Run w3m-view-this-url without switching to the newly created buffer. It is useful if you enabled the tabs line or the buffers selection window for the w3m-select-buffer feature. Note that it is meaningful only when specifying a prefix argument to the w3m-view-this-url command or using the w3m-view-this-url-new-session command in order to create a new emacs-w3m session.