[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Advanced Features

11.1 Disk Caching  Improving performance by using a local disk cache
11.2 Printing  Emacs/W3 can print HTML by various methods.
11.3 Interfacing to Mail/News  How to make VM understand hypertext links
11.4 Debugging HTML  How to make Emacs/W3 display warnings about invalid
HTML/HTML+ constructs.
11.5 Hooks  Various hooks to use throughout Emacs/W3
11.6 Miscellaneous variables  Miscellaneous variables that control the real guts of Emacs/W3.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

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.

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

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.
The document style to use when printing or mailing converted HTML files in LaTeX.
List of LaTeX packages to include. Currently this is only used if w3-latex-use-latex2e is non-nil.
If non-nil, the LaTeX engine will use real LaTeX title pages for document titles.
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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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
	   (lambda ()
	     (define-key rmail-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
	     (define-key rmail-mode-map "\r"      'w3-maybe-follow-link))))

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4 Debugging HTML

For those people that are adventurous, or are just as anal as I am about people writing valid HTML, set the variable w3-debug-html to t and see what happens. Alternatively, you can set it to style to warn about stylistic issues as well. The debugging information will be written to the buffer named by w3-debug-buffer, `*HTML Debug*' by default. To control font-lock highlighting in the HTML error buffer, use w3-html-errors-font-lock-keywords. After Emacs/W3 has displayed HTML errors for a page, it runs w3-display-errors-hook.

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?

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

These hooks are run the first time a URL is fetched. All the Emacs/W3 variables are initialized before this hook is run.
These hooks are run after a buffer has been parsed and displayed, but before any inlined images are downloaded and converted.
These hooks are run after displaying a document's source.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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

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

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.

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

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.
A list of file related commands
Various standard editing commands (copy/paste)
Controlling various things about the document view
Navigation control
Bookmark / hotlist control
Various options
The standard buffers menu
A toggle button to switch back to normal emacs menus
Control style information and who gets to set what
Various search engines
The help menu
This may appear once in the list. All menus after this will be displayed flush right.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on October, 2 2007 using texi2html