11. Advanced Features

11.1 Disk Caching

A cache stores the information on a page on the local machine. When requesting a page that is in the cache, Emacs/W3 can retrieve the page from the cache more quickly than retrieving the page again from its location out on the network. With a well-populated cache, browsing the web is dramatically faster.

The first time a page is requested, Emacs/W3 retrieves the page from the network. When requesting a page that is in the cache, Emacs/W3 checks to see if the page has changed since it was last retrieved from the remote machine. If it has not changed, the local copy is used, saving the transmission of the file over the network.

To turn on disk caching, set the variable url-automatic-caching to non-nil, or choose the 'Caching' menu item (under `Options'). That is all there is to it. Running the clean-cache shell script fist is recommended, to allow for future cleaning of the cache. This shell script will remove all files that have not been accessed since it was last run. To keep the cache pared down, it is recommended that this script be run from at or cron (see the manual pages for crontab(5) or at(1) for more information)

With a large cache of documents on the local disk, it can be very handy when traveling, or any other time the network connection is not active (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely solely on its cache, and avoid checking to see if the page has changed on the remote server. In the case of a dial-on-demand PPP connection, this will keep the phone line free as long as possible, only bringing up the PPP connection when asking for a page that is not located in the cache. This is very useful for demonstrations as well. To turn this feature on, set the variable url-standalone-mode to non-nil, or choose the `Use Cache Only' menu item (under `Options')

url-cache-expired decides whether or not a cache entry has expired. It is a function that take two times as it parameters and returns non-nil if the second time is "too old" when compared with the first time. url-cache-ignored-protocols is a list of protocols that will never be cached, this is '("www" "about" "https" "mailto") by default. url-cache-directory sets the directory to store the cache files, `"w3-configuration-directorycache/"' by default. url-cache-creation-function sets the type of cache to use, it is a function that takes a URL as an argument and returns the absolute pathname of the cache-file corresponding to that URL. You may write your own function or use one of the two ready built functions, url-cache-create-filename-using-md5 and url-cache-create-filename-human-readable. The advantage of url-cache-create-filename-using-md5 is that there are very few cache collisions but is only "suitably fast" if you're not using XEmacs. url-cache-create-filename-human-readable will give a filename more obviously connected to the URL, but it is more likely to conflict with other files.

11.2 Printing

If you want to print an HTML document, then Emacs/W3 needs to convert it into something that can be printed. You can choose from

HTML source

This will simply print the raw HTML source code using lpr-buffer. An appropriate <base> tag is inserted at the beginning of the document.

Formatted text

This will print the rendered document using lpr-buffer; so the conversion is handled by Emacs. This will print plain ASCII.

Postscript

This will call the function in w3-postscript-print-function, which is ps-print-buffer-with-faces by default. This just tells Emacs to generate postscript as best it can.

LaTeX

Emacs/W3 can generate a LaTeX equivalent of the HTML document.

w3-print-command contains a command string to print `dvi' files. It is `lpr -h -d' by default.

There are several variables controlling what the final LaTeX document looks like.

:: WORK :: Document the new LaTeX backend

w3-latex-use-latex2e

If non-nil, configures the LaTeX engine to use the LaTeX2e syntax. A nil value indicates that LaTeX 2.0.9 compabibility will be used instead.

w3-latex-docstyle

The document style to use when printing or mailing converted HTML files in LaTeX.

w3-latex-packages

List of LaTeX packages to include. Currently this is only used if w3-latex-use-latex2e is non-nil.

w3-latex-use-maketitle

If non-nil, the LaTeX engine will use real LaTeX title pages for document titles.

w3-latex-print-links

If non-nil, prints the URLs of hypertext links as endnotes at the end of the document. If set to footnote, prints the URL's as footnotes on each page.

11.3 Interfacing to Mail/News

More and more people are including URLs in their signatures, and within the body of mail messages. It can get quite tedious to type these into the minibuffer to follow one.

With the latest versions of VM (the 5.9x series of betas) and Gnus (5.x), URLs are automatically highlighted, and can be followed with the mouse or the return key. How the URLs are viewed is determined by the variable browse-url-browser-function, and it should be set to the symbol browse-url-w3.

To access URLs from within RMAIL, the following hook should do the trick.

(add-hook 'rmail-mode-hook
	  (function
	   (lambda ()
	     (define-key rmail-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
	     (define-key rmail-mode-map "\r"      'w3-maybe-follow-link))))

11.4 Debugging HTML

If a Emacs/W3 thinks it has encountered invalid HTML, then a debugging message is displayed.

:: WORK :: Need to list the different values w3-debug-html can have, and
:: WORK :: what they do ::

gdj1: Does this refer to the macro? And if so, why?

11.5 Hooks

These are the various hooks that can be used to customize some of Emacs/W3's behavior. They are arranged in the order in which they would happen when retrieving a document. These are all 'normal hooks' in standard Emacs-terminology, meaning they are functions (or lists of functions) that are called consecutively.

w3-load-hook

These hooks are run the first time a URL is fetched. All the Emacs/W3 variables are initialized before this hook is run.

w3-mode-hook

These hooks are run after a buffer has been parsed and displayed, but before any inlined images are downloaded and converted.

w3-source-file-hook

These hooks are run after displaying a document's source.

11.6 Miscellaneous variables

There are lots of variables that control the real nitty-gritty of Emacs/W3 that the beginning user probably shouldn't mess with. Here they are.

url-bad-port-list

List of ports to warn the user about connecting to. Defaults to just the mail, NNTP and chargen ports so a malicious HTML author cannot spoof mail or news to other people.

url-confirmation-func

What function to use for asking yes or no functions. Possible values are 'yes-or-no-p or 'y-or-n-p, or any function that takes a single argument (the prompt), and returns t only if a positive answer is gotten. Defaults to 'yes-or-no-p.

url-passwd-entry-func

This is a symbol indicating which function to call to read in a password. If this variable is nil at startup, it is initialized depending on whether EFS or ange-ftp is being used. This function should accept the prompt string as its first argument, and the default value as its second argument.

url-max-password-attempts

When a protected document is requested, Emacs/W3 will prompt for a password. url-max-password-attempts controls how many attempts should be allowed, it is 5 by default.

w3-reuse-buffers

Determines what happens when w3-fetch is called on a document that has already been loaded into another buffer. Possible values are: nil, yes, and no. nil will ask the user if Emacs/W3 should reuse the buffer (this is the default value). A value of yes means assume the user wants to always reuse the buffer. A value of no means assume the user always wants to re-fetch the document.

url-show-status

Whether to show progress messages in the minibuffer. url-show-status controls if a running total of the number of bytes transferred is displayed. This Can cause a large performance hit if using a remote X display over a slow link, or a terminal with a slow modem.

mm-content-transfer-encodings

An assoc list of Content-Transfer-Encodings or Content-Encodings and the appropriate decoding algorithms for each. If the cdr of a node is a list, then this specifies the decoder is an external program, with the program as the first item in the list, and the rest of the list specifying arguments to be passed on the command line. If using an external decoder, it must accept its input from stdin and send its output to stdout.

If the cdr of a node is a symbol whose function definition is non-nil, then that encoding can be handled internally. The function is called with 2 arguments, buffer positions bounding the region to be decoded. The function should completely replace that region with the unencoded information.

Currently supported transfer encodings are: base64, x-gzip, 7bit, 8bit, binary, x-compress, x-hqx, and quoted-printable.

url-uncompressor-alist

An assoc list of file extensions and the appropriate uncompression programs for each. This is used to build the Accept-encoding header for HTTP/1.0 requests.

w3-do-scripting

If this is non-nil then Emacs/W3 will do clien-side scripting. This is nil by default.

url-external-retrieval-program, url-external-retrieval-args

url-external-retrieval-program names the external program that is run to retrieve URLs. It is `www' by default. url-external-retrieval-args specifies the arguments that will be passed to it, `("-source")' by default.

w3-netscape-compatible-comments

Not everyone uses proper HTML comments. To allow for the presence of lesser browsers, Emacs/W3 will honour the incorrect netscape-style comments (`<! >') if w3-netscape-compatible-comments is non-nil. This is t by default, but it shouldn't need to be.

font-blink-interval

This controls how often blinks occur for text inside `<blink>' tags. It is 0.5 seconds by default.

url-inhibit-mime-parsing

This controls whether to parse MIME headers in a message. If it is nil then the headers are parsed and deleted.

url-mime-language-string

This is used to set the contents of the `Accept-language:' field in HTTP/1.0 requests. If it is nil then the field isn't added and the server's default language version is retrieved, if it is * then the first available langauge version is retrieved. If it is a string, then it should be the desired language.

url-multiple-p

If this is non-nil then multiple queries are possible through ` *URL-<i>*' buffers.

url-personal-mail-address

url-personal-mail-address contains your full email address. This is sent in the FROM field in an HTTP/1.0 request, but 7. Security for how to prevent this. If nil (the default), then it will be set to user-mail-address if non-nil, else it will be (user-real-login-name) at (system-name).

url-temporary-directory, w3-temporary-directory

url-temporary-directory and w3-temporary-directory control where temporary files are placed. If `TMPDIR' is set then they default to that, otherwise `/tmp'.

w3-documentation-root

This specifies the location of the Emacs/W3 documentation, it must end in a slash.

w3-popup-menu-on-mouse-3

If you like context-sensitive menus then you're bound to like w3-popup-menu-on-mouse-3. If non-nil (the default) then Emacs/W3 will bind mouse-3 to provide context-sensitive menus. This might not work at the moment. If w3-popup-menu-on-mouse-3 is nil, then Emacs/W3 will not change the binding of mouse-3.

w3-track-mouse

If w3-track-mouse is non-nil (the default) then Emacs/W3 will display the URL under the mouse in the echo-area.

w3-use-menus

If w3-use-menus is nil then Emacs/W3 will not provide a menu interface. If it is `1', then Emacs/W3 will add a `W3' item to the Emacs menubar. If it is a list then Emacs/W3 will add its own menubar. The following symbols may appear in the list to control what Emacs/W3 puts in its menubar.

file

A list of file related commands

edit

Various standard editing commands (copy/paste)

view

Controlling various things about the document view

go

Navigation control

bookmark

Bookmark / hotlist control

options

Various options

buffers

The standard buffers menu

emacs

A toggle button to switch back to normal emacs menus

style

Control style information and who gets to set what

search

Various search engines

help

The help menu

nil

This may appear once in the list. All menus after this will be displayed flush right.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.