This file documents the Emacs-W3 World Wide Web browser.

Copyright (C) 1993, 1994, 1995 William M. Perry Copyright (C) 1996 Free Software Foundation

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

This manual documents the Emacs-W3 World Wide Web browser, a Lisp program which runs as a subsystem under Emacs.  The manual is divided into the following chapters.

Introduction
************

Emacs-W3 is an Emacs subsystem that allows the user to browse the wonderful World Wide Web (WWW).

The World Wide Web was begun at the CERN physics institute in Switzerland in 1991.  The project was initiated by Tim Berners-Lee (timbl@w3.org) for distributing data between different research groups effectively.

The Web has since grown into the most advanced information system currently on the internet.  It is now a global hypertext system with servers and browsers (programs written to interpret the hypertext language and display it correctly, and allow the user to follow links) exist for all major platforms (VMS, Windows, DOS, Unix, VM, NeXTstep, Amiga, and Macintosh).

The basic concepts used in the Web are hypertext and hypermedia. Hypertext is the same as regular text, with one exception---it can contain links (cross-references) to other textual documents.  Hypermedia is slightly different---it can contain links to other forms of media (movies, sounds, interactive programs, etc.).

WWW also allows searches of indices that are located anywhere on the network; in this respect, it mirrors certain capabilities found in both WAIS and Gopher.
----------------
CLIENT SIDE VIEW
----------------
The WWW consists of documents and links.  Indexes are special documents which, rather than being read, may be searched.  The result of such a search is another virtual document containing links to the documents found.  A simple protocol, Hypertext Transfer Protocol or HTTP, is used to allow a browser program to request a keyword search by a remote information server.

The web contains documents in many formats.  Those documents which are hypertext, (real or virtual) contain links to other documents, or places within documents.  All documents, whether real, virtual or indexes, look similar to the reader and are contained within the same addressing scheme.
-------------------------
INFORMATION PROVIDER VIEW
-------------------------
WWW browsers can access many existing data systems via existing protocols (FTP, NNTP) or via HTTP and a gateway.  In this way, the critical mass of data is quickly exceeded, and the increasing use of the system by readers and information suppliers encourage each other.

Providing information is as simple as running a WWW server and pointing it at an existing directory structure.  The server automatically generates a hypertext view of the files to guide the user around.

To personalize it, a few SGML hypertext files can be written to give an even more friendly view.  Also, any file available by anonymous FTP, or any internet newsgroup can be immediately linked into the web.  The small start-up effort is designed to allow open contributions.  At the other end of the scale, large information providers may provide an HTTP server with full text or keyword indexing.  This may allow access to a large existing database without changing the way that database is managed.  Such gateways have already been made into Oracle(tm), WAIS, and Digital's VMS/Help systems, to name but a few.

The WWW model gets over the frustrating incompatibilities of data format between suppliers and reader by allowing negotiation of format between a smart browser and a smart server.  This provides a basis for extension into multimedia, and allow those who share application standards to make full use of them across the web.

Here is some more specific information about what Emacs-W3 does and does not understand:

Supported Markup Languages
**************************

Several different markup languages, and various extensions to those languages, are supported by Emacs-W3.
----------
HTML 2.0
----------
The Hypertext Markup Language, or HTML, is composed of a set of elements that define a document and guide its display.  An HTML element may include a name, some attributes and some text or hypertext, and appears in an HTML document as <tag_name>text</tag_name>, <tag_name attribute_name=argument>text</tag_name>, or just <tag_name>.

For example: <title>My Useful Document</title>, and <pre width=60> A lot of text here.  </pre>.

An HTML document is composed of a single element: <html>...</html>, that is, in turn, composed of head and body elements: <head>...</head>, and <body>...</body>.  To allow older HTML documents to remain readable, <html>, <head>, and <body> are actually optional within HTML documents.

All the tags and attributes of HTML are fully supported in Emacs-W3.

The full HTML 2.0 specification is available at any RFC archive (ftp://ds.internic.net/).  It is RFC 1866.

----------
HTML 3.0
----------
The HTML 3.0 language is an extension of HTML, with a large degree of backward compatibility with HTML 2.0.  The idea of having one huge HTML 3.0 document has been dropped in favor of several smaller supplementatry RFCs.  This will allow the standard to be upgraded much more quickly than trying to agree on all the features at once.

As each new chunk of HTML 3.0 is proposed and agreed upon, Emacs-W3 will support it.

:: WORK :: List currently supported chunks (embed, etc) ::

  * Embed Embedding of arbitrary objects into an HTML document.  With the <embed> tag, any type of document can be inserted.  The most entertaining use of this is with embedding MPEG movies into an emacs buffer.  This requires Lucid Emacs 19.10, or XEmacs 19.11, as well as a slightly patched version of mpeg_play 2.0 (The patch is available from ftp://ftp.cs.indiana.edu/pub/elisp/w3/mpeg_patch).

----------
Netscape-HTML
----------
I hate to say it, but I broke down and actually included some of the Netscape extensions into Emacs-W3.

<font>...</font>
     Changes the font size.  Valid values range from 0-7. The default font size is 3. The value given can optionally have a '+' or '-' character in front of it to specify that it is relative to the document basefont.  Stylesheets are recommended instead, as they allow much greater control.See Style Sheets

<center>...</center>
     This ugly, ill-thought-out alternative to the HTML 3.0 align attribute on headers and paragraphs was included for compatibility, and as an example of how not to do things.

<isindex>
     The isindex tag can now take a prompt attribute, to get rid of the default 'This is a searchable index' label.

<hr width=xx align=xx>
     The width and alignment of a horizontal rule can now be controlled.  The WIDTH attribute specifies how wide the rule should be, as a percentage of the window width.

     The ALIGN attribute specifies where the horizontal rule is placed. Valid values are left, right, center, and indent.

<body background=URL bgcolor=RGB TEXT=RGB LINK=RGB ALINK=RGB VLINK=RGB>
     Various colors can now be set on a document wide basis.  This is done with various attributes on the BODY tag.  Stylesheets are really a better way to do this, and are recommended.  This is just for compatibility.  See Style Sheets NOTE: Netscape requires that all colors be specified in RGB values - this is not very intuitive for the avergage author, so Emacs-W3 allows you to use logical system colors (ie: "PaleGoldenrod" instead of "#eee8aa").

     BACKGROUND=URL
          Specifies a graphic to tile in the background of the document.  This only works in XEmacs 19.12 or later.

     BGCOLOR=COLOR
          Specifies the background of the document, as a color instead of a graphic.

     TEXT=COLOR
          Specifies the color of text on the page.

     LINK=COLOR
          Specifies the color of hypertext links on the page.

     VLINK=COLOR
          Specifies the color of hypertext links that have been visited already.

     ALINK=COLOR
          Specifies the color of active hypertext links (links that have been clicked on, but not yet fully retrieved).

----------
SGML Features
----------
:: WORK :: Document marked sections, SGML features
----------
Extras
----------
There are several different markup elements that are not officially part of HTML or HTML 3.0 that Emacs-W3 supports.  These are either items that were dropped from HTML 3.0 after I had implemented them, or experimental parts of HTML that should not be counted as "official" or long lived.

  * More <HR> improvements.  Text can be added into a horizontal rule by using the LABEL and TEXTALIGN attributes.

          <hr label="testing" textalign="right">
          yields
          ----------------------------------------------------------testing-

          <hr label="testing" textalign="center">
          yields
          -----------------------------testing------------------------------

          <hr label="testing" textalign="left">
          yields
          -Testing----------------------------------------------------------

  * FLAME support.  For truly interesting dynamic documents.  This is replaced with a random quote from Mr. Angry (see M-x flame for a sample).

  * The top ten tags that did not make it into netscape.  These tags were posted to the newsgroup comp.infosystems.www.misc by Laura Lemay (lemay@netcom.com).  Much thanks to her for the humor.

     <wired>...</wired>
          Renders the enclosed text in a suitably ugly font/color combination.  If no default has been set up by the user, this is the default font, with red text on a yellow background.

     <roach>...</roach>
          When selected, the enclosed text runs and hides under the nearest window.  OR, giggles a lot and demands nachos, depending on the definition of "roach." (the formal definition, of course, to be determined by the Official Honorary Internet Standards Committee For Moving Really Slowly.)

     <pinhead>
          Inserts "zippyisms" into the enclosed text.  Perfect for those professional documents.  This is sure to be a favorite of mine!

     <secret>...</secret>
          Must use secret spy decoder glasses (available direct from Netscape for a reasonable fee) in order to read the enclosed text.  Can also be read by holding the computer in front of a full moon during the autumn solstice.

          In Emacs-W3, this displays the text using rot13 encoding.

     <hype>
          Causes Marc Andreesen to magically appear and grant an interview (wanted or not).  Please use this tag sparingly.

     <peek>....</peek>

     <poke>...</poke>
          Need more control over screen layout in HTML?  Well, here ya go.

          Actually, <peek> could almost be considered useful.  The VARIABLE attribute can be used to insert the value of an emacs variable into the current document.  Things like 'Welcome to my page, <peek variable=user-mail-address>' can be useful in freaking people out.

     <yogsothoth>
          Summons the elder gods to suck away your immortal soul.  Or Bill Gates, if the elder gods are busy.  Unpredictable (but amusing) results occur when the <YOGSOTHOTH> and <HYPE> tags are used in close proximity.

     <blink>...</blink>
          Causes the enclosed text to .... ooops that one made it in.

Supported Protocols
*******************

Emacs-W3 supports the following protocols

Usenet News
     Can either display an entire newsgroup or specific articles by Message-ID: header.  This supports a unix-style .newsrc file, so the user does not see articles they have read using another newsreader, but due to how news URLs work, the .newsrc file cannot be updated reliably.

     To be more in line with the other URL schemes, the hostname and port of an NNTP server can be specified.  URLs of the form news://hostname:port/messageID work, but will not work in most other browsers.

HTTP
     Supports both the HTTP/0.9 and HTTP/1.0 protocols.  Fully MIME-compliant with regards to HTTP/1.0.

Gopher
     Support for all gopher types, including CSO queries.

Gopher+
     Support for Gopher+ retrievals. Support for converting ASK blocks into HTML 3.0 FORMS and submitting them back to the server.

FTP
     FTP is handled by either ange-ftp or efs.

Local files
     Local files are handled, and MIME content-types are derived from the file extensions.

Telnet
     Telnet is handled by running the Emacs Lisp function telnet, or spawning an xterm running telnet.

TN3270
     TN3270 is handled by running a tn3270 program in an Emacs buffer, or spawning an xterm running tn3270.

Mailto
     Causes a mail message to be started to a specific address.

mailserver
     A more powerful version of mailto, which allows the author to specify the subject and body text of the mail message.  This type of link is never fully executed without user confirmation, because it is possible to insert insulting or threatening (and possibly illegal) data into the message.  The mail message is displayed, and the user must type 'yes' to send it.

X-exec
     A URL can cause a local executable to be run, and its output interpreted as if it had come from an HTTP server.  This is very useful, but is still an experimental protocol, hence the X- prefix.

SSL
     SSL requires a set of patches to the Emacs C code and SSLRef 2.0, or an external program to run in a subprocess (similar to the tcp.el package that comes with GNUS.  See Installing SSL

Secure HTTP
     Work is in progress to add support for the Secure HTTP specification from Enterprise Information Technologies.  The specification for SHTTP can be found on EIT's web server at http://www.commerce.net/information/standards/drafts/shttp.txt.

Setting Up
**********

This section of the manual deals with getting, compiling, and configuring Emacs-W3.

Retrieving Emacs-W3
===================

:: WORK :: Document that Emacs-W3 now requires the URL package as well

Compiling Emacs-W3
==================

To install Emacs-W3, go into the w3 subdirectory and edit the Makefile.  These variables might need to be changed:

EMACS
     This variable controls what version of Emacs is used to compile the programs.  It should be the full path to the Emacs executable on the system.  The default is to use GNU Emacs (emacs).

LISPDIR
     This variable controls where the lisp code is copied to when it is installed (with make install).  This is usually the users personal lisp code directory.  The value is run through expand-file-name and then added to the load-path.  Default is ~/lisp.

DOTEMACS
     This variable points to the Emacs customization file, default is ~/.emacs.

INFODIR
     This variable points to the local info directory.  This can be any valid directory, as long as it is in Info-default-directory-list so that info-mode can find it.  Default is /usr/local/info/.

MAKEINFO
     This variables controls how the info files are built.  Possible values are makeinfo or emacs -batch -q -f batch-texinfo-format.  Default is makeinfo.

Once the Makefile has been modified, several different targets can be built.

make w3
     This compiles all the .el files into the much faster .elc files.

make install
     Compiles all the .el files and copies .el and .elc files into the directory specified by LISPDIR.

make emacs
     Modifies the file specified by DOTEMACS.  A statement modifying the load-path variable and several autoload statements are added to the end of the file.

make all
     Compiles and installs the .el files, and also modify/create the DOTEMACS file.

make w3.info
     Creates the Emacs-readable info files.  The info files are created in the directory specified by INFODIR.  The makefile variable MAKEINFO determines how the info file is built.

make w3.dvi
     Creates the printable documentation, using tex and texindex to properly generate the indices.  A w3.dvi file is left in the current directory.

Basic Setup
===========

There are a few variables that almost all people need to change.

w3-default-homepage
     The url to open at startup.  This defaults to the environment variable WWW_HOME if it is not set it in the users .emacs file. If WWW_HOME is undefined, then it defaults to the hypertext documentation for Emacs-W3.

w3-delay-image-loads
     Controls the loading of inlined images.  If non-nil, images are not loaded.  If the correct image converters are not installed or the network connection is very slow, it is best to set this to t. Defaults to nil.

url-global-history-file
     The global history file used by both Mosaic/X and Emacs-W3.  This file contains a list of all the URLs that have been visited.  This file is parsed at startup and used to provide URL completion.  Emacs-W3 can read and write Mosaic/X or Netscape 1.x style history files, or use its own internal format (faster).  The file type is determined automatically, or prompted for if the file does not exist.

w3-hotlist-file
     Hotlist filename.  This should be the name of a file that is stored in NCSA's Mosaic/X or Netscape's format.  It is used to keep a listing of commonly accessed URLs.

w3-personal-annotation-directory
     The directory where Emacs-W3 looks for personal annotations.  This is a directory that should hold the personal annotations stored in a Mosaic/X-compatible format.

url-pgp/pem-entity
     The name by which the user is known to PGP and/or PEM entities.  If this is not set when Emacs-W3 is loaded, it defaults to user-mail-address if it is set, otherwise (user-real-login-name)@(system-name).

url-personal-mail-address
     User's full email address.  This is what is sent to HTTP/1.0 servers as the FROM header.  If this is not set when Emacs-W3 is loaded, then it defaults to the value of url-pgp/pem-entity.

w3-right-border
     Amount of space to leave on right margin of WWW buffers.  This amount is subtracted from the width of the window for each new WWW buffer and used as the new fill-column.

w3-track-mouse
     Controls whether to track the mouse and message the url under the mouse. If this is non-nil, then a description of the hypertext area under the mouse is shown in the minibuffer.  This shows what type of link (inlined image, form entry area, delayed image, delayed MPEG, or hypertext reference) is under the cursor, and the destination.

w3-echo-link
     Controls how a URL is shown when a link is reached with f, b, or the mouse moves over it.  Possible values are:

     url
          Displays the URL (ie: http://www.cs.indiana.edu/).

     text
          Displays the text of the link (ie: A link to Indiana University).

     nil
          Show nothing.

w3-use-forms-index
     Non-nil means translate <ISINDEX> tags into a hypertext form.  A single text entry box is shown where the ISINDEX tag appears.

url-use-hypertext-gopher
     Controls how gopher documents are retrieved.  If non-nil, the gopher pages are converted into HTML and parsed just like any other page.  If nil, the requests are passed off to the gopher.el package by Scott Snyder.  Using the gopher.el package loses the gopher+ support, and inlined searching.

url-xterm-command
     Command used to start a windowed shell, similar to an xterm.  This string is passed through format, and should expect four strings: the title of the window, the program name to execute, and the server and port number.  The default is for xterm, which is very UNIX and XWindows-centric.

Firewalls
=========

There are several different reasons why the gateway support might be required.

 1. Stuck behind a firewall.  This is usually the case at large corporations with paranoid system-administrators.

 2. Using TERM  (TERM is a user-level protocol for emulating IP over a serial line.  More information is available at ftp://sunsite.unc.edu/pub/Linux/apps/comm/term) for slip-like access to the internet.

     NOTE: Emacs 19.22 has patches to enable native TERM networking.  To enable it, #define TERM in the appropriate s/*.h file for the operating system, then change the SYSTEM_LIBS define to include the termnet library that comes with the latest versions of TERM.

 3. Emacs cannot resolve hostnames.  This happens quite often on Sun workstations and some ULTRIX machines.  Some C libraries do not include the hostname resolver routines in their static libraries.  If Emacs was linked statically, this means it won't be able to get to any machines off the local network.  This is characterized by being able to reach someplace with a raw ip number, but not its hostname (http://129.79.254.191/ works, but http://www.cs.indiana.edu/ doesn't).

     If for some reason it is not feasible to recompile Emacs with the -lresolv library or dynamic linking, it is just like being behind a firewall.  Another alternative is to set the variable url-broken-resolution - this will use the support in ange-ftp or EFS to use nslookup in a subprocess to do all hostname resolving. See the variables efs-nslookup-program, efs-nslookup-on-connect, and efs-nslookup-threshold if are using EFS, or ange-ftp-nslookup-program if using Ange-FTP.

 4. Running XEmacs 19.x and Solaris 2.x (SunOS 5.x).  For some reason, network processes under Solaris and XEmacs never get a status of exit or closed.  This causes retrieval of HTTP and gopher pages to hang indefinitely, with Emacs chewing up large amounts of CPU time.

Emacs-W3 has support for using the gateway mechanism for certain domains, and directly connecting to others.  To use this, change the value of url-gateway-local-host-regexp.  This should be a regular expression  (Please see the full Emacs distribution for a description of regular expressions) that matches local hosts that do not require the use of a gateway.  If nil, then all connections are made through the gateway.

Emacs-W3 supports several methods of getting around gateways.  The variable url-gateway-method controls which of these methods is used.  This variable can have several values (use these as symbol names, not strings):

program
     Run a program in a subprocess to connect to remote hosts (examples are itelnet (Itelnet is a standard name for a telnet executable that is capable of escaping the firewall.  Check with system administrators to see if anything similar is available), an expect (Expect is a scripting language that allows control of interactive programs (like telnet) very easily.  It is available from gatekeeper.dec.com:/pub/GNU/expect-3.24.0.tar.gz) script, etc.).

host
     Log into another local computer that has access to the internet, and run a telnet-like program from there.

tcp
     Masanobu UMEDA (umerin@mse.kyutech.ac.jp) has written a very nice replacement for the standard networking in Emacs.  This does basically the same thing that a method of program does, but is slightly more transparent to the user.

native
     This means that Emacs-W3 should use the builtin networking code of Emacs. This should be used only if there is no firewall, or the Emacs source has already been hacked to get around the firewall.

Two of these need a bit more explanation than that: When running a program in a subprocess to emulate a network connection, a few extra variables need to be set.  The variable url-gateway-telnet-program should point to an executable that accepts a hostname and port # as its arguments, and passes standard input to the remote host.  This can be either the full path to the executable or just the basename.  The variable url-gateway-telnet-ready-regexp controls how long Emacs-W3 should wait after spawning the subprocess to start sending to its standard input.  This gets around a bug where telnet would miss the beginning of requests becausse it did not buffer its input before opening a connection.  This should be a regular expression to watch for that signifies the end of the setup of url-gateway-telnet-program. The default should work fine for telnet.

When using the host-based gatway method, things get a bit more complicated.  This is basically my attempt to do some of the basic stuff of expect within elisp.  First off, set the variable url-gateway-host to be the name of the gateway machine.

The variable url-gateway-connect-program controls how the host is reached.  The easiest way is to have a program that does not require a username and password to login.  The most common of these is the rsh command.

If rsh is not available, then things get very ugly.  First, set the variable url-gateway-program-interactive to non-nil.  Then set the variables url-gateway-host-username and url-gateway-host-password to be the username and password necessary to log into the gateway machine.  The regular expressions in the variables url-gateway-handholding-login-regexp and url-gateway-handholding-password-regexp should match the login and password prompts on the gateway system respectively.  For example:

     (setq url-gateway-connect-program "telnet"
           url-gateway-host-program "telnet"
           url-gateway-program-interactive t
           url-gateway-host-username "wmperry"
           url-gateway-host-password "yeahrightkeepdreaming"
           url-gateway-host "moose.cs.indiana.edu"
           url-gateway-host-program-ready-regexp "Escape character is .*"
           url-gateway-handholding-login-regexp "ogin:"
           url-gateway-handholding-password-regexp "ord:")

This should take care of logging in to the remote system.  The variable url-gateway-host-prompt-pattern should contain a regular expression that matches the shell prompt on the remote machine.  This should appear no where in the login banner/setup, or things could get very confused.

The variable url-gateway-host-program-ready-regexp should contain a regular expression that matches the end of the setup of url-gateway-host-program when it tries to make a connection to an off-firewall machine.  (Basically the same as url-gateway-telnet-ready-regexp.

Emacs-W3 should now be able to get outside the local network.  If none of this makes sense, its probably my fault.  Please check with the network administrators to see if they have a program that does most of this already, since somebody somewhere at the company has probably been through something similar to this before, and would be much more helpful/knowledgeable about the local setup than I would be.  But feel free to mail me as a last resort.

Proxy Gateways
==============

In late January 1993, Kevin Altis and Lou Montulli proposed and implemented a new proxy service.  This service requires the use of environment variables to specify a gateway server/port # to send protocol requests to.  Each protocol (HTTP, WAIS, gopher, FTP, etc.) can have a different gateway server.  The environment variables are PROTOCOL_proxy, where PROTOCOL is one of gopher, file, HTTP, FTP, or WAIS.

:: WORK ::

Basic Usage
***********

Emacs-W3 is similar to the Info package all Emacs users hold near and dear to their hearts (see Info (The Info Manual), for a description of Info).  Basically, space and backspace control scrolling, and return or mouse2 follows a hypertext link.  The f and b keys maneuver around the various links on the page.

NOTE: To enter data into a form entry area, select it using return or the middle mouse button, just like a hypertext link.

On non-graphic terminals (VT100, DOS, etc.), hypertext links are surrounded by '[[' and ']]' by default.  On a graphics terminal, the links are in bold print.  See Controlling Formatting for information on how to change this, or for help on getting the highlighting to work on graphics terminals.

There are approximately 50 keys bound to special Emacs-W3 functions. The basic rule of thumb regarding keybindings in Emacs-W3 is that a lowercase key takes an action on the current document, and an uppercase key takes an action on the document pointed to by the hypertext link under the cursor.

There are several areas that the keybindings fall into: movement, information, action, and miscellaneous.

Movement
========

:: WORK :: Document the 'h' and 'a' keymaps

SPC
     Scroll downward in the buffer.  With prefix arg, scroll down that many screenfuls.

DEL
     Scroll upward in the buffer.  With prefix arg, scroll up that many screenfuls.

<
     Goes to the start of document

>
     Goes to the end of document

Shift-TAB, b
     Attempts to move backward one link area in the current document. Signals an error if no previous links are found.

hl
     Displays a complete listing of the items in the hotlist.

hu
     Go to a link in the hotlist.

m
     Choose a link from the current buffer and follow it.  A completing-read is done on all the links, so space and TAB can be used for completion.

TAB, f, n
     Attempts to move forward one link area in the current document.  Signals an error if no more links are found.

Information
===========

These functions relate information about one or more links on the current document.

v
     This shows the URL of the current document in the minibuffer.

V
     This shows the URL of the hypertext link under point in the minibuffer. If there is not a hypertext link under point, then it shows the type of form entry area under point.  If there is no form entry area under point, then it shows the inlined image's URL that is under point, if any.

i
     Shows miscellaneous information about the currently displayed document. This includes the URL, the last modified date, MIME headers, the HTTP response code, and any relationships to other documents.  Any security information is also displayed.

I
     Shows information about the URL at point.

s
     This shows the HTML source of the current document in a separate buffer. The buffer's name is based on the document's URL.

S
     Shows the HTML source of the hypertext link under point in a separate buffer.  The buffer's name is based on the document's URL.

k
     This stores the current document's URL in the kill ring, and also in the current window-system's clipboard, if possible.

K
     Stores the URL of the document under point in the kill ring, and also in the current window-system's clipboard, if possible.

Action
======

First, here are the keys and functions that bring up a new hypertext page, usually creating a new buffer.

return
     Pressing return when over a hyperlink attempts to follow the link under the cursor.  With a prefix argument (C-u), this forces the file to be saved to disk instead of being passed off to other viewers or being parsed as HTML.

     Pressing return when over a form input field will prompt in the minibuffer for the data to insert into the input field.  Type checking is done, and the data is only entered into the form when data of the correct type is entered (ie: cannot enter 44 for 'date' field, etc).

Middle Mouse Button
     Attempt to follow a hypertext link under the mouse cursor.  Clicking on a form input field will prompt in the minibuffer for the data to insert into the input field.  Type checking is done, and the data is only entered into the form when data of the correct type is entered (ie: cannot enter 44 for 'date' field, etc).

Control Middle Mouse Button, Meta return
     Tries to retrieve the inlined image that is under point.  It ignores any form entry areas or hyperlinks, and blindly follows any inlined image. Useful for seeing images that are meant to be used as hyperlinks when not on a terminal capable of displaying graphics.

p
     Prints out the current buffer in a variety of formats, including PostScript, HTML source, or formatted text.

P
     Prints out the URL under point in a variety of formats, including PostScript, HTML source, or formatted text.

m
     Selects a destination from a list of all the hyperlinks in the current buffer.  Use space and tab to complete on the links.

r, g
     Reloads the current document.  The position within the buffer remains the same (unless the document has changed since it was last retrieved, in which case it should be relatively close).  This causes an unconditional reload from the remote server - the locally cached copy is not consulted.

C-o
     Prompts for a URL in the minibuffer, and attempts to fetch it.  If there are any errors, or Emacs-W3 cannot understand the type of link requested, the errors are displayed in a hypertext buffer.

o
     Opens a local file, interactively.  This prompts for a local file name to open.  The file must exist, and may be a directory.  If the requested file is a directory and url-use-hypertext-dired is nil, then a dired-mode buffer is displayed.  If nonnil, then Emacs-W3 automatically generates a hypertext listing of the directory.  The hypertext mode is the default, so that all the keys and functions remain the same.

M-s
     Perform a search, if this is a searchable index.  Searching requires a server - Emacs-W3 can not do local file searching, as there are too many possible types of searches people could want to do.  Generally, the only URL types that allow searching are HTTP, gopher, and X-EXEC.

Hv
     If url-keep-history is non-nil, then Emacs-W3 keeps track of all the URLs visited in an Emacs session.  This function takes all the links that are in that internal list, and formats them as hypertext links in a list.

And here are the commands to move around between Emacs-W3 buffers:

l
     Goes to the last WWW buffer seen.

q
     Quits WWW mode.  This kills the current buffer and goes to the most recently visited buffer.

u
     This is similar to w3-quit, but the buffer is not killed, it is moved to the bottom of the buffer list (so it is the least likely to show up as the default with switch-to-buffer).  This is different from w3-goto-last-buffer in that it does not return to the last WWW page visited - it is the same as using switch-to-buffer - the buffer left in the window is fairly random.

HB, B
     Takes one step back along the path in the current history.  Has no effect if at the beginning of the session history.

HF, F
     Takes one step forward along the path in the current history.  Has no effect if at the end of the session history.

Miscellaneous
=============

M-m
     Mails the current document to someone.  Choose from several different formats to mail: formatted text, HTML source, PostScript, or LaTeX source. When the HTML source is mailed, then an appropriate <base> tag is inserted at the beginning of the document so that relative links may be followed correctly by whoever receives the mail.

M-M
     Mails the document pointed to by the hypertext link under point to someone. Choose from several different formats to mail: formatted text, HTML source, PostScript, or LaTeX source.  When the HTML source is mailed, then an appropriate <base> tag is inserted at the beginning of the document so that relative links may be followed correctly by whoever receives the mail.

p
     Prints the current document.  Choose from several different formats to print: formatted text, HTML source, PostScript (with ps-print), or by using LaTeX and dvips).

     When the formatted text is printed, the normal lpr-buffer function is called, and the variables lpr-command and lpr-switches control how the document is printed.

     When the HTML source is printed, then an appropriate <base> tag is inserted at the beginning of the document. When postscript is printed, then the HTML source of the document is converted into LaTeX source.  If the variable w3-use-html2latex is non-nil, then the program specified by w3-html2latex-prog is run in a subprocess with the arguments in w3-html2latex-args.  The w3-html2latex-prog must accept HTML source on its standard input and send the LaTeX output to standard output.  If w3-use-html2latex is nil, then an Emacs Lisp function uses regular expressions to replace the HTML code with LaTeX markup.  The variable w3-latex-docstyle controls how the document is laid out in this case, and postscript figures are printed as well.

P
     Prints the document pointed to by the hypertext link under point. Please see the previous item for more information.

M-x w3-insert-formatted-url
     Insert a fully formatted HTML link into another buffer.  This gets the name and URL of either the current buffer, or, with a prefix arg, of the link under point, and construct the appropriate <a...>...</a> markup and insert it into the desired buffer.

M-tab
     Inserts the URL of the current document into another buffer.  Buffer is prompted for in the minibuffer.  With prefix arg, uses the URL of the link under point.

U
     Selects one of the <LINK> tags from this document and fetch it.  Links are attributes of a specific document, and can tell such things as who made the document, where a table of contents is located, etc.

     Link tags specify relationships between documents in two ways.  Normal (forward) relationships (where the link has a REL="xxx" attribute), and reverse relationships (where the link has a REV="xxx" attribute).  This first asks what type of link to follow (Normal or Reverse), then does a completing-read on only the links that have that type of relationship.

Compatibility with other Browsers
*********************************

Due to the popularity of several other browsers, Emacs-W3 offers an easy transition to its much better way of life.  This ranges from being able to share the same preferences files and disk cache to actually emulating the keybindings used in other browsers.

Emulation
=========

:: WORK :: Document lynx emulation :: WORK :: Document netscape emulation

Hotlist Handling
================

:: WORK :: Document that it supports different types of hotlist formats :: WORK :: Make sure everything hotlist related can be accessed via 'h' In order to avoid having to traverse many documents to get to the same document over and over, Emacs-W3 supports a ``hotlist'' like Mosaic.  This is a file that contains URLs and aliases.  Hotlists allow quick access to any document in the Web, providing it has been visited and added to the hotlist. The variable w3-hotlist-file determines where this information is saved.  The structure of the file is compatible with Mosaic's hotlist file, so this defaults to ~/.mosaic-hotlist-default.

Hotlist commands are:

a
     Adds the current document to the hotlist, with the buffer name as its identifier.  Modifies the file specified by w3-hotlist-file.  If this is given a PREFIX-ARGUMENT (via C-u), the title is prompted for instead of automatically defaulting to the document title.

hR
     This rereads the default hostlist file specified by w3-hotlist-file.

d
     Prompts for the alias of the entry to kill.  Pressing the spacebar or tab will list out partial completions.  The internal representation of the hotlist and the file specified by w3-hotlist-file are updated.

hr
     Some hotlist item names can be very unwieldy (`Mosaic for X level 2 fill out form support'), or uninformative (`Index of /').  Prompts for the item to rename in the minibuffer---use the spacebar or tab key for completion.  After having chosen an item to rename, prompts for a new title until a unique title is entered.  Modifies the file specified by w3-hotlist-file.

hu
     Prompts for the alias to jump to.  Pressing the spacebar or tab key shows partial completions.

hv
     Converts the hotlist into HTML and displays it.

ha
     Shows the hotlist entries matching a regular expression.

hA
     Appends another hotlist file to the one currently in memory.

History
=======

Almost all web browsers keep track of the URLs followed from a page, so that it can provide forward and back buttons to keep a path of URLs that can be traversed easily. If the variable url-keep-history is t, then Emacs-W3 keeps a list of all the URLs visited in a session. To view a listing of the history for this session of Emacs-W3, use M-x w3-show-history from any buffer, and Emacs-W3 generates an HTML document showing every URL visited since Emacs started (or cleared the history list), and then format it.  Any of the links can be chosen and followed to the original document.  To clear the history list, choose 'Clear History' from the 'Options' menu.

Another twist on the history list mechanism is the fact that all Emacs-W3 buffers remember what URL, buffer, and buffer position of the last document, and also keeps track of the next location jumped to from that buffer.  This means that the user can go forwards and backwards very easily along the path taken to reach a particular document.  To go forward, use the function w3-forward-in-history, to go backward, use the function w3-backward-in-history.

Global History
==============

:: WORK :: Document that the global history can have diff. formats Most web browsers also support the idea of a ``history'' of URLs the user has visited, and it displays them in a different style than normal URLs.

If the variable url-keep-history is t, then Emacs-W3 keeps a list of all the URLs visited in a session.  The file is automatically written to disk when exiting emacs.  The list is added to those already in the file specified by url-global-history-file, which defaults to ~/.mosaic-global-history.

If any URL in the list is found in the file, it is not saved, but new ones are added at the end of the file.

The function that saves the global history list is smart enough to notice what style of history list is being used (Netscape, Emacs-W3, or XMosaic), and writes out the new additions appropriately.

One of the nice things about keeping a global history files is that Emacs-W3 can use it as a completion table.  When doing M-x w3-fetch, pressing the tab or space key will show all completions for a partial URL.  This is very useful, especially for very long URLs that are not in a hotlist, or for seeing all the pages from a particular web site before choosing which to retrieve.

Annotations
===========

Mosaic can annotate documents.  Annotations are comments about the current document, and these annotations appear as a link to the comments at the end of the document.  The original file is not changed.

Group Annotations
-----------------

NOTE: The group annotation experiment has been terminated.  It will be replaced with support on the server side for adding <LINK> tags to documents.

Personal Annotations
--------------------

Emacs-W3 looks in the directory specified by w3-personal-annotation-directory (defaults to ~/.mosaic-personal-annotations).  Any personal annotations for a document are automatically appended when it is retrieved.

:: WORK :: Document the new 'a' prefix keymap :: WORK :: Tell where the annotations are stored

To add a new personal annotation, type M-x w3-add-personal-annotation.  This creates a new buffer, in the mode specified by w3-annotation-mode.  This defaults to html-mode.  If this variable is nil, or it points to an undefined function, then default-major-mode is consulted.

A minor mode redefines C-c C-c to complete the annotation and store it on the local disk.

To delete a personal annotation, it must be the current page.  Once reading the annotation, M-x w3-delete-personal-annotation will remove it.  This deletes the file containing the annotation, and any references to it in the annotation log file.

Editing personal annotations is not yet supported.

Controlling Formatting
**********************

How Emacs-W3 formats a document is very customizable.  How a document is displayed depends on whether the user is on a terminal capable of graphics and a few variables.

The following sections describe in more detail how to change the formatting of a document.

General formatting conventions
==============================

--------------------
Setting the fill column
--------------------
Each time a document is parsed, the fill-column is recalculated using window-width and w3-right-border. w3-right-border is an integer specifying how much room at the right edge of the screen to leave blank.  The fill-column is set to (- (window-width) w3-right-border).
--------------------
Formatting of hypertext links
--------------------
If the variable w3-delimit-links is non-nil (the default for text-terminals), then hypertext links are surrounded by text specified by the user.  The variables w3-link-start-delimiter and w3-link-end-delimiter control what text is at the start and end of a hypertext link.  These variables are cons-pairs of two strings.

If a link has never been visited before (it is not in the global history), then the car of these variables is inserted at the start and end of the link.  If the link has been visited before, then the cdr is inserted.  So, links look like:

     [[This is a hypertext link]] that has never been visited.
     {{This one, however}} has been seen before at some point in time.

--------------------
Formatting of lists
--------------------
There are several different ways to control the formatting of lists. The most obvious is how deeply they are indented relative to the rest of the paragraphs in the document.  To control this, set the variable w3-indent-level.  This is the number of spaces to indent lists and other items requiring special margins.

Another thing that is easy to change about lists is the bullet character put at the front of each list item.  This is controlled by the variable w3-list-chars-assoc, which is an assoc list.  This is a list of lists, each sublist describing what to put at the start of each particular list type.  The car of this list should be a symbol (not a string) representing the type of list (e.g., ul). The rest of the list should consist of strings to insert at certain levels of lists.  The nth element of this list is used when the list is nested n + 1 levels.  If the list is not long enough to define a string for a certain nesting level, then it defaults to either a '*' or a '.'.
--------------------
Formatting of directory listings
--------------------
When Emacs-W3 encounters a link to a directory (whether by local file access or via FTP), it can either create an HTML document on the fly, or use dired-mode to peruse the listing.  The variable url-use-hypertext-dired controls this behavior.

If the value is t, Emacs-W3 uses directory-files to list them out and transform the directory into a hypertext document, then pass it through the parser like any other document.

If the value is nil, just pass the directory off to dired using find-file.  Using this option loses all the hypertext abilities of Emacs-W3, and the users is unable to load documents in the directory directly into Emacs-W3 by clicking with the mouse, etc.

--------------------
Formatting of gopher directories
--------------------
There are two different ways of viewing gopher links.  The built-in support that converts gopher directories into HTML, or the gopher.el package by Scott Snyder (snyder@fnald0.fnal.gov). The variable that controls this is w3-use-hypertext-gopher.  If set to nil, then gopher.el is used.  Any other value causes Emacs-W3 to use its internal gopher support.  If using gopher.el, all the hypertext capabilities of Emacs-W3 are lost. All the functionality of gopher.el is now available in the hypertext version, and the hypertext version supports Gopher+ and ASK blocks.

The main way to control the display of gopher directories is by the variable w3-gopher-labels.  This variable controls the text that is inserted at the front of each item.  This is an assoc list of gopher types (as one character strings), and a string to insert just after the list item.  All the normal gopher types are defined.  Entries should be similar to: ("0" . "(TXT)").  I have tried to keep all the tags to three characters plus two parentheses.
--------------------
Creating a horizontal rule
--------------------
Horizontal rules (<HR> tags in HTML[+]) are used to separate chunks of a document, and is meant to be rendered as a solid line across the page.  Some terminals display characters differently, so the variable w3-horizontal-rule-char controls which character is used to draw a horizontal bar.  This variable must be the ASCII value of the character, not a string.  The variable is passed through make-string whenever a horizontal rule of a certain width is necessary.

On character based terminals
============================

On character based terminals, there is no easy way to show that a certain range of text is in bold or italics.  If the variable w3-delimit-emphasis is non-nil, then Emacs-W3 can insert characters before and after character formatting commands in HTML documents.  The defaul value of w3-delimit-emphasis is automatically set based on the type of window system and version of Emacs being used.

:: WORK ::

w3-header-chars-assoc is an assoc list of header tags and a list of formatting instructions.  The car of the list is the level of the header (1--6).  The rest of the list should contain three items. The first item is text to insert before the header.  The second item is text to insert after the header.  Both should have reserved characters converted to their HTML[+] entity definitions.  The third item is a function to call on the area the header is in.  This function is called with arguments specifying the start and ending character positions of the header.  The starting point is always first.  To convert a region to upper case, please use w3-upcase-region instead of upcase-region, so that entities are converted properly.

With graphics workstations
==========================

Starting with the first public release of version 2.3.0, all formatting is controlled by the use of stylesheets.

:: WORK :: Graphic workstation stuff - redo for stylesheets

When running in Lucid Emacs 19.10 or XEmacs 19.11 and higher, Emacs-W3 can display inlined images and MPEG movies.  There are several variables that control how and when the images are displayed.

Since Lucid/XEmacs only natively understands XPixmaps and XBitmaps, GIFs and other image types must first be converted to one of these formats. To do this, the netpbm utilities (Available via anonymous ftp from ftp.x.org:/R5contrib/netpbm-1mar1994.tar.gz, and most large ftp sites.) programs are normally used.  This is a suite of freeware image conversion tools.  The variable w3-graphic-converter-alist controls how each image type is converted.  This is an assoc list, keyed on the MIME content-type.  The car is the content-type, and the cdr is a string suitable to pass to format.  A %s in this string will be replaced with a converter from the ppm image format to an XPixmap (or XBitmap, if being run on a monochrome display).  By default, the Emacs-W3 browser has converters for:

 1. image/x-xbitmap

 2. image/xbitmap

 3. image/xbm

 4. image/gif

 5. image/jpeg

 6. image/x-fax

 7. image/x-raster

 8. image/windowdump

 9. image/x-icon

 10. image/portable-graymap

 11. image/portable-pixmap

 12. image/x-pixmap

 13. image/x-xpixmap

 14. image/pict

 15. image/x-macpaint

 16. image/x-targa

 17. image/tiff

Since most displays are (sadly) not 24-bit, Emacs-W3 can automatically dither an image, so that it does not fill up the application' colormap too quickly.  If w3-color-use-reducing is non-nil, then the images will use reduced colors.  If w3-color-filter is eq to 'ppmquant, then the ppmquant program will be used.  If eq to 'ppmdither, then the ppmdither program will be used.  The ppmdither program tends to give better results.  The values of w3-color-max-red, w3-color-max-blue, and w3-color-max-green control how many colors the inlined images can use.  If using ppmquant, then the product of these three variables is used as the maximum number of colors per image.  If using ppmdither, then only the set number of color cells can be allocated per image.  See the man pages for ppmdither and ppmquant for more information on how the dithering is actually done.  w3-color-filter may also be a string, specifying exactly what external filter to use.  An example is: ppmquant -fs -map ~/pixmaps/colormap.ppm.

When running in XEmacs 19.11 or XEmacs 19.12, Emacs-W3 can insert an MPEG movie in the middle of a buffer.

:: WORK :: Need a pointer to the new EMBED Internet Draft ::

The basic syntax is:

     <embed href="somevideo.mpg" type="video/mpeg">

This requires a special version of the standard mpeg_play mpeg player.  Patches against the 2.0 version are available at ftp://ftp.cs.indiana.edu/pub/elisp/w3/mpeg_patch.  The variable w3-mpeg-program should point to this executable, and w3-mpeg-args should be a list of any additional arguments to be passed to the player.  By default, this includes -LOOP, so the mpeg plays continuously.

Because images and movies can take up an incredible amount of bandwidth, it is useful to be able to control whether they are loaded or not.  By default, images and movies are loaded automatically, but the variables w3-delay-image-loads and w3-delay-mpeg-loads control this. If set to non-nil, then the images or movies are not loaded until explicitly requested by the user.

To load any delayed images, use the function w3-load-delayed-images.  Its counterpart for delayed movies is w3-load-delayed-mpegs

MIME Support
************

MIME is an emerging standard for multimedia mail.  It offers a very flexible typing mechanism.  The type of a file or message is specified in two parts, separated by a '/'.  The first part is the general category of the data (text, application, image, etc.).  The second part is the specific type of data (postscript, gif, jpeg, etc.).  So text/html specifies an HTML document, whereas image/x-xwindowdump specifies an image of an Xwindow taken with the xwd program.

This typing allows much more flexibility in naming files.  HTTP/1.0 servers can now send back content-type headers in response to a request, and not have the client second-guess it based on file extensions.  HTML files can now be named something.gif (not a great idea, but possible).

Adding MIME types based on file extensions
==========================================

For some protocols however, it is still necessary to guess the content of a file based on the file extension.  This type of guess-work should only be needed when accessing files via FTP, local file access, or old HTTP/0.9 servers.

Instead of specifying how to view things twice, once based on content-type and once based on the file extension, it is easier to map file extensions to MIME content-types.  The variable that controls this is mm-mime-extensions.

This variable is an assoc list of file extensions and the corresponding MIME content-type.  A sample entry looks like: (".movie" . "video/x-sgi-movie") This makes all files that end in .movie (foo.movie and bar.movie) be interpreted as SGI animation files.  If a content-type is defined for the document, then this is over-ridden.  Regular expressions can NOT be used.

Both Mosaic and the NCSA HTTP daemon rely on a separate file for mapping file extensions to MIME types.  Instead of having the users of Emacs-W3 duplicate this in lisp, this file can be parsed using the url-parse-mimetypes function.  This function is called each time w3 is loaded.  It tries to locate mimetype files in several places. If the environment variable MIMETYPES is nonempty, then this is assumed to specify a UNIX-like path of mimetype files (this is a colon separated string of pathnames).  If the MIMETYPES environment variable is empty, then Emacs-W3 looks for these files:

 1. ~/.mime-types

 2. /etc/mime-types

 3. /usr/etc/mime-types

 4. /usr/local/etc/mime-types

 5. /usr/local/www/conf/mime-types

Each line contains information for one http type.  These types resemble MIME types.  To add new ones, use subtypes beginning with x-, such as application/x-myprogram.  Lines beginning with # are comment lines, and suitably ignored.  Each line consists of:

type/subtype ext1 ext2 ...  extN

type/subtype is the MIME-like type of the document. ext* is any number of space-separated filename extensions which correspond to the MIME type.

Specifying Viewers
==================

Not all files look as they should when parsed as an HTML document (whitespace is stripped, paragraphs are reformatted, and lots of little changes that make the document look unrecognizable).  Files may be passed to external programs or Emacs Lisp functions to be viewed.

Not all files can be viewed accurately from within an Emacs session (GIF files for example, or audio files).  For this reason, the user can specify file "viewers" based on MIME content-types.  This is done with a standard mailcap file.  See Mailcap Files

As an alternative, the function mm-add-mailcap-entry can also be used from an appropriate hook.See Hooks  This functions takes three arguments, the major type ("image"), the minor type ("gif"), and an assoc list of information about the viewer.  Please see the URL documentation for more specific information on what this assoc list should look like.

Security
********

There are an increasing number of ways to authenticate a user to a web service.  Emacs-W3 tries to support as many as possible.  Emacs-W3 currently supports:

Basic Authentication
     The weakest authentication available, not recommended if serious security is necessary.  This is simply a string that looks like user:password that has been Base64 encoded, as defined in RFC 1421.

Digest Authentication
     Jeffery L. Hostetler, John Franks, Philip Hallam-Baker, Ari Luotonen, Eric W. Sink, and Lawrence C. Stewart have an internet draft for a new authentication mechanism.  For the complete specification, please see draft-ietf-http-digest-aa-01.txt in the nearest internet drafts archive (One is ftp://ds.internic.net/internet-drafts).

SSL Encryption
     SSL is the Secure Sockets Layer interface developed by Netscape Communications  (http://www.netscape.com/).  Emacs-W3 supports HTTP transfers over an SSL encrypted channel, if the appropriate files have been installed.See Installing SSL

PGP/PEM
     A few servers still support this method of authentication, but it has been superseded by SSL and Secure-HTTP.See Using PGP/PEM

Non-Unix Operating Systems
**************************

VMS
===

:: WORK :: VMS Specific instriuctions

OS/2
====

:: WORK :: OS/2 Specific instructions

MS-DOS
======

:: WORK :: DOS Specific instructions

16-Bit Windows
==============

:: WORK :: 16bit Windows Specific instructions

32-Bit Windows
==============

:: WORK :: 32bit Windows Specific instructions

Amiga
=====

:: WORK :: Amiga specific instructions

Advanced Features
*****************

Style Sheets
============

Emacs-W3 currently supports the experimental style sheet mechanism proposed by H&kon W. Lie of the W3 Consortium.  This allows for the author to specify what a document should look like, and yet allow the end user to override any of the stylistic changes.  This allows for people with special needs (most notably the visually impaired) to override style bindings that could make a document totally unreadable.

     <style notation="css">
     /* This is a comment
     ** These will be ignored, up to the terminating end-of-line
     #
     h1 { align: center,
          color: yellow,
          background: red,
          font-size: 24pt
        }
     h2 { align: right,
          font-family: palatino,
          font-size: 18pt
        }
     </style>

:: WORK :: Much more information on stylesheets

To include a stylesheet into a document, simply use the <style> tag. Use the notation attribute to specify what language the stylesheet is specified in.  The default is css.  The data between the <style> and </style> tags is the stylsheet proper - no HTML parsing is done to this data - it is treated similar to an <XMP> section of text.  To reference an external stylesheet, use the <link> tag.

     <link rel="stylesheet" href="/bill.style">

If these two mechanisms are mixed, then the URL is resolved first, and the contents of the <style> tag take precedence if there are any conflicting directives.

In the future, DSSSL and DSSSL-lite will be supported as valid stylesheet languages, but not in this release.  For more information on DSSSL-lite see http://www.falch.no/~pepper/DSSSL-Lite/ - for more information on full DSSSL, see ftp://ftp.jclark.com/pub/dsssl/dsssl.ps.gz

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

Emacs-W3 caches files under the temporary directory specified by url-temporary-directory, in a user-specific subdirectory (determined by the user-real-login-name function).  The cache files are stored under their original names, so a URL like: http://www.spry.com/foo/bar/baz.html would be stored in a cache file named: /tmp/wmperry/com/spry/www/foo/bar/baz.html.  Sometimes, espcially with gopher links, there will be name conflicts, and an error will be signalled.  This cannot be avoided, and still have reasonable performance at startup time (reading in an index file of all the cached pages can take a long time on slow machines, or even fast machines with large caches).  When running XEmacs 19.12 or later, a different naming scheme can be used.  This avoids name conflicts, but loses the human readability of the cache file names.  The cache files will look like: /tmp/wmperry/acbd18db4cc2f85cedef654fccc4a4d8, which is certainly unique, but not very user-friendly.  To turn this on, add this to the .emacs file:

     (add-hook 'w3-load-hooks '(lambda ()
                                  (fset 'url-create-cached-filename
                                        'url-create-cached-filename-using-md5)))

If other versions of emacs will not be sharing the cache, I highly recommend this method of creating the cache filename.

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), URLs are highlighted, and can be followed with the mouse or the return key.

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

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

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

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.

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

Native WAIS Support
===================

This version of Emacs-W3 supports native WAIS querying (earlier versions required the use of a gateway program).  In order to use the native WAIS support, a working waisq binary is required.  I recommend the distribution from think.com - ftp://think.com/wais/wais-8-b6.1.tar.Z is a good place to start.

The variable url-waisq-prog must point to this executable, and one of url-wais-gateway-server or url-wais-gateway-port should be nil.

When a WAIS URL is encountered, a form will be automatically generated and displayed.  After typing in the search term, the query will be sent to the server by running the url-waisq-prog in a subprocess.  The results will be converted into HTML and displayed.

Rating Links
============

The w3-link-info-display-function variable can be used to 'rate' a URL when it shows up in an HTML page.  If non-nil, then this should be a list specifying (or a symbol specifying the name) of a function. This function should expect one argument, a fully specified URL, and should return a string.  This string is inserted after the link text.

If a user has decided that all links served from blort.com are too laden with images, and wants to be warned that a link points at this host, they could do something like this:

     (defun check-url (url)
       (if (string-match "://[^/]blort.com" url)
          "[SLOW!]" ""))

     (setq w3-link-info-display-function 'check-url)

So that all links pointing to any site at blort.com shows up as "Some link[SLOW!]" instead of just "Some link".

Gopher+ Support
===============

The gopher+ support in Emacs-W3 is limited to the conversion of ASK blocks into HTML 3.0 forms, and the usage of the content-length given by the gopher+ server to give a nice status bar on the bottom of the screen.

This will hopefully be extended to include the Gopher+ method of content-type negotiation, but this may be a while.

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.  All of these are functions (or lists of functions) that are called consecutively.

w3-load-hooks
     These hooks are run by w3-do-setup the first time a URL is fetched.  All the w3 variables are initialized before this hook is run.

w3-file-done-hooks
     These hooks are run by w3-prepare-buffer after all parsing on a document has been done.  All url-current-* and w3-current-* variables are initialized when this hook is run. This is run before the buffer is shown, and before any inlined images are downloaded and converted.

w3-file-prepare-hooks
     These hooks are run by w3-prepare-buffer before any parsing is done on the HTML file.  The HTTP/1.0 headers specified by w3-show-headers have been inserted, the syntax table has been set to w3-parse-args-syntax-table, and any personal annotations have been inserted by the time this hook is run.

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

w3-source-file-hooks
     These hooks are run after displaying a document's source

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

w3-delimit-links
     :: WORK :: This is going away, and should be specified with stylesheets instead

w3-delimit-emphasis
     :: WORK :: This is going away, and should be specified with stylesheets instead

w3-default-action
     A lisp symbol specifying what action to take for files with extensions that are not in the mm-mime-extensions assoc list.  This is useful in case Emacs-W3 ever run across files with weird extensions (.foo, .README, .READMEFIRST, etc.).  In most circumstances, this should not be required anymore.

     Possible values: any lisp symbol.  Should be a function that takes no arguments.  The return value does not matter, it is ignored.  Some examples are 'w3-prepare-buffer or 'indented-text-mode.

w3-keep-old-buffers
     Whether to keep old buffers around when following links.  To avoid lots of buffers in one Emacs session, set this variable to nil.  I recommend setting it to t, so that backtracking from one link to another is faster.

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.

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.

w3-show-headers
     This is a list of HTTP/1.0 headers to show at the end of a buffer.  All the headers should be in lowercase.  They are inserted at the end of the buffer in a <UL> list.  Alternatively, if this is simply t, then all the HTTP/1.0 headers are shown.  The default value is nil.

w3-show-status, url-show-status
     Whether to show progress messages in the minibuffer. w3-show-status controls if messages about the parsing are displayed, and url-show-status controls if a running total of the number of bytes transferred is displayed.  These 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.

url-waisq-prog
     Name of the waisq executable on this system.  This should be the waisq program from think.com's wais8-b5.1 distribution.

More Help
*********

For more help on Emacs-W3, please send me mail (wmperry@cs.indiana.edu).  Several discussion lists have also been created for Emacs-W3.  To subscribe, send mail to majordomo@indiana.edu, with the body of the message 'subscribe LISTNAME <EMAIL ADDRES>'.  All other mail should go to <listname>@indiana.edu.

  * w3-announce -- this list is for anyone interested in Emacs-W3, and should in general only be used by me.  The gnu.emacs.sources newsgroup and a few other mailing lists are included on this.  Please only use this list for major package releases related to Emacs-W3. (www-announce@w3.org is included on this list).

  * w3-beta -- this list is for beta testers of Emacs-W3.  These brave souls test out not-quite stable code.

  * w3-dev -- a list consisting of myself and a few other people who are interested in the internals of Emacs-W3, and doing active development work. Pretty dead right now, but I hope it will grow.

For more help on the World Wide Web in general, please refer to the comp.infosystems.www.* newsgroups.  There are also several discussion lists concerning the Web.  Send mail to <listname>-request@w3.org with a subject line of 'subscribe <listname>'.  All mail should go to <listname>@w3.org.  Administrative mail should go to www-admin@w3.org.  The lists are:

  * www-talk -- for general discussion of the World Wide Web, where its going, new features, etc.  All the major developers are subscribed to this list.

  * www-announce -- for announcements concerning the World Wide Web.  Server changes, new servers, new software, etc.

As a last resort, mail me.  I'll try to answer as quickly as I can.

Future Directions
*****************

Changes are constantly being made to the Emacs browser (hopefully all for the better).  This is a list of the things that are being worked on right now.

:: WORK :: Revamp the todo list

Internals of Emacs-W3
*********************

This chapter attempts to explain some of the internal workings of Emacs-W3 and various data structures that are used.  It also details some functions that are useful for using some of the Emacs-W3 functionality from within other programs, or extending the current capabilities of Emacs-W3.

Generalized ZONES
=================

Due to the many different flavors of Emacs in existence, the addition of data and font information to arbitrary regions of text has been generalized.  The following functions are defined for using/manipulating these zones of data.

w3-add-zone (start end style data &optional highlight)
     Creates a zone between buffer positions start and end, with font information specified by style, and a data segment of data.  If the optional argument highlight is non-nil, then the region highlights when the mouse moves over it.

w3-zone-at (point)
     Returns the zone at POINT.  Preference is given to hypertext links, then to form entry areas, then to inlined images.  So if an inlined image was part of a hypertext link, this would always return the hypertext link.

w3-zone-data (zone)
     Returns the zone's data segment. The data structures used in Emacs-W3 are relatively simple.  They are just list structures that follow a certain format.  The two main data types are form objects, link objects,and inlined images.  All the information for these types of links are stored as lists.

w3-zone-hidden-p (zone)
     Returns t if and only if a zone is currently invisible.

w3-hide-zone (start end)
     Makes a region of text from start to end invisible.

w3-unhide-zone (start end)
     Makes a region of text from start to end visible again.

w3-zone-start (zone)
     Returns an integer that is the start of zone, as a buffer position.  In Emacs 18.xx, this returns a marker instead of an integer, but it can be used just like an integer.

w3-zone-end (zone)
     Returns an integer that is the end of zone, as a buffer position.  In Emacs 18.xx, this returns a marker instead of an integer, but it can be used just like an integer.

w3-zone-eq (zone1 zone2)
     Returns t if and only if zone1 and zone2 represent the same region of text in the same buffer, with the same properties and data.

w3-delete-zone (zone)
     Removes zone from its buffer (or current buffer).  The return value is irrelevant, and varies for each version of Emacs.

w3-all-zones ()
     Returns a list of all the zones contained in the current buffer.  Useful for extracting information about hypertext links or form entry areas.  Programs should not rely on this list being sorted, as the order varies with each version of Emacs.

w3-zone-at (pt)
     Returns the zone at character position PT in the current buffer that is either a link or a forms entry area.  Returns nil if no link at point.

These data structures are what is generally returned by w3-zone-data.

Global variables
================

There are also some variables that may be useful when writing a program or function that interacts with Emacs-W3.  All of the w3-current-* variables are local to each buffer.

url-current-mime-headers
     An assoc list of all the MIME headers for the current document.  Keyed on the lowercase MIME header (e.g., content-type or content-encoding.

url-current-server
     Server that the current document was retrieved from.

url-current-file
     Filename of the current document

url-current-type
     A string representing what network protocol was used to retrieve the current buffer's document.  Can be one of http, gopher, file, ftp, news, or mailto.

url-current-port
     Port # of the current document.

w3-current-last-buffer
     The last buffer seen before this one.

w3-running-FSF19
     This is t if and only if we are running in FSF Emacs 19.

w3-running-xemacs
     This is t if and only if we are running in Lucid Emacs, WinEmacs, or XEmacs.

Data Structures
===============

Form objects are used to store information about a FORM data entry area.

 1. 'w3form

 2. A cons pair of (METHOD . URL), where METHOD specifies what method to use to retrieve the form when it is submitted (e.g., GET) and URL is a fully specified URL pointing at where to submit the FORM data to.

 3. The type of input area this is.  (e.g., CHECKBOX or RADIO)

 4. The name of the input tag.  This is used when sending the form to the server, so that the server can tell what data is what.

 5. The default value of the input area.  Gotten from the INPUT tag at creation time.

 6. The current value of the input area.

 7. Whether the item is checked or not.  Only used for RADIO or CHECKBOX items.

 8. The size (in characters) of the input area.  Not used for CHECKBOX, RADIO, or TEXTAREA input areas.

 9. The maximum length of the input.  Only used for TEXT or PASSWORD input areas.

 10. The form that this input area belongs to.  Each form in the same buffer has a unique identifier assigned when the document is parsed.  It is used when the form is submitted to get only the data for the correct form.

 11. A list of strings that represent the choices for this input area.  Only used for SELECT tags.

 12. A string or nil, specifying the ID attribute on this input tag.

A new development in the World Wide Web is the concept of collapsible areas of text.  If a zone controls one of these regions, it is marked with the w3expandlist property.  The format of this structure is:

 1. 'w3expandlist

 2. A marker representing the start of the hidden text as a buffer position.

 3. A marker representing the end of the hidden text as a buffer position.

A zone with the w3graphic property is a link to an inlined image's source file.

 1. 'w3graphic

 2. The full URL of the inlined image.  This is only ever returned if the inlined image is the only extent under point, or w3-follow-inlined-image is invoked.

A zone with the w3 property is a full-fledged hypertext link to another document.

 1. 'w3

 2. The ID attribute of this link.  Used for resolving references to specific points within a document (e.g., file.html#sectionA.

 3. The HREF attribute of this link.  This is a fully specified URL pointing at a network resource.  All relative directory references should have been removed before being stored in this structure.

 4. The text between the <A> and </A> tags.  This is used to build menus or to get the text of a link without doing a buffer-substring.

 5. The URN attribute of this link.  Currently not used for anything, waiting for the URN specification to be hammered out.

 6. The REL attribute of this link.  Specifies the links relevance to the current document.

 7. The REV attribute of this link.  Specifies the current documents relevance to the link.

 8. The METHODS attribute, which tells what methods can be used on this link.  (e.g., GET, HEAD, PUT.

Miscellaneous Functions
=======================

I have done quite a bit of work trying to make a clean interface to the internals of Emacs-W3.

url-clear-tmp-buffer
     Sets the current buffer to be url-working-buffer, creating it if necessary, and erase it.  This should usually be called before retrieving URLs.

w3-convert-html-to-latex
     Takes a buffer of HTML markup (which should be in w3-working-buffer), and convert it into LaTeX.  This is an adaptation of the simple sed scripts from Cern.  Does as good a job as the html2latex program, and I usually prefer its formatting over html2latex's.

w3-fetch
     Takes a URL as its only argument. It then attempts to retrieve the URL. For example: (w3-fetch "http://cs.indiana.edu/") would retrieve the Indiana University CS home page and parse it as HTML.

url-generate-new-buffer-name
     Takes a string, and returns the first unique buffer name using that string as a base.  For example (url-generate-new-buffer-name "new-buff") would return "new-buff<1>" if buffer new-buff already existed.

url-generate-unique-filename
     Returns a string that represents a unique filename in the /tmp directory.  For example, (url-generate-unique-filename) would return "/tmp/url-tmp129440".  The filename is arrived at by using a unique prefix (url-tmp), the uid of the current user (12944 in my case), and a number that is incremented if a file already exists.

url-buffer-visiting (url)
     Returns the name of a buffer (if any) that is visiting URL.

url-create-mime-request (fname ref-url)
     Creates a MIME request for the file fname.  The Referer: field of the HTTP/1.0 request is set to the value of ref-url if necessary.  Returns a string that can be sent to an HTTP server.  The request uses several variables that control how the request looks.

     If the value of url-request-extra-headers is non-nil, then it is used as extra MIME headers when an HTTP/1.0 request is created.

url-get-url-at-point
     Returns the url at a point specified by an optional argument.  If no argument is given to the function, the current buffer position is used. Tries to find the URL closest to that point, but does not change the users position in the buffer.  Has a preference for looking backward when not directly on a URL.

url-hexify-string
     Takes a string and replaces any characters that are not acceptable in a URL with the "escaped" encoding that is standard for URLs (replaces the character with a % followed by the hexadecimal representation of the ASCII value of the character).  For example, (url-hexify-string "this is a test") would return "this%20is%20a%20test".

url-open-stream
     Takes the same parameters as open-network-stream, and functions similarly.  It takes a process name, a buffer name, a host name, and a port number or server name.  It attempts to open a network connection to the remote host on the specified port/service name, with output going to the buffer.  It returns the process object that is the network connection.

url-retrieve
     :: WORK :: Need to describe the url-request-* variables and the no-cache and expected-md5 arguments to url-retrieve ::

url-unhex-string
     This is the opposite of url-hexify-string.  It removes any %XXX encoded characters in a string.  For example (url-unhex-string "this%20is%20a%20test") would return "this is a test".

w3-view-this-url
     Returns the URL of the hyperlink under point (if no hyperlink is under point, then it returns nil).  If the optional argument is nil, then the URL is also displayed in the minibuffer.

url-view-url
     Returns the URL of current document.  If the optional argument is nil, then the URL is also displayed in the minibuffer.

MIME Functions
==============

mm-compose-type(TYPE)
     Composes a body section of MIME-type TYPE.  This uses the compose field of a mailcap entry to generate the data, and returns a string that contains the data, with a correct content-type header.

mm-extension-to-mime(EXTN)
     Returns the MIME content-type of the file extension EXTN.

mm-mime-info(ST ND REQUEST)
     Returns the mime viewer command for a specific MIME type.  If ST is a number, then the MIME type is the buffer-substring between ST and ND, otherwise ST should be a string specifying the MIME type and associated data.  Returns nil if the specified type is not found.

     Expects a complete content-type header line as its argument.  This can be simple like text/html, or complex like text/plain; charset=blah; foo=bar

     Third argument REQUEST specifies what information to return.  If it is nil or the empty string, the viewer (second field of the mailcap entry) is returned.  If it is a string, then the mailcap field corresponding to that string is returned (print, description, whatever). If a number, then all the information for this specific viewer is returned.

mm-parse-mailcap(FILE)
     Parses the mailcap file specified by FILE.

mm-parse-mailcaps(PATH)
     Parses the default mailcap files.  Optional argument PATH specifies a UNIX-style path of where to find the mailcap files.  This function must be run before the rest of the mm-* functions.

mm-parse-mimetype-file(FILE)
     Parses out a mime-types file specified by FILE.

mm-parse-mimetypes(PATH)
     Parses the default mimetypes files.  Optional argument PATH specifies a UNIX-style path of where to find the mimetypes files.

Reporting Bugs
**************

:: WORK :: Reporting bugs needs work.

Installing SSL
**************

In order to use SSL in Emacs-W3, an implementation of SSL is necessary. These are the implementations that I am aware of:

SSLRef 2.0
     Available from Netscape Communications  (http://www.netscape.com/newsref/std/sslref.html).  This requires the RSARef library, which is not exportable.  The RSARef library is available from ftp://ftp.rsa.com/rsaref/

SSLeay 0.4
     An implementation by Eric Young (eay@mincom.oz.au) that is free for commerial or noncommercial use, and was developed completely outside the US by a non-US citizen.  More information can be found at ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/

Whichever reference implementation is used (I recommend the SSLeay distribution, just to thumb a nose at the NSA :), there is a program that can be run in a subprocess that takes a hostname and port number on the command line, and reads/writes to standard input/output (the Netscape implementation comes with one of these by default).  Set the variable ssl-program-name to point to this program.

This should be all the configuration necessary.  In the future, I will be distributing a set of patches to Emacs 19.xx and XEmacs 19.xx to SSL-enable them, for the sake of speed.

Using PGP/PEM
*************

Most of this chapter has been reproduced from the original documentation written by Rob McCool (robm@netscape.com) (See http://hoohoo.ncsa.uiuc.edu/docs/PEMPGP.html for the original).

RIPEM is 'Riordan's Internet Privacy Enhanced Mail', and is currently on version 1.2b3.  US citizens can ftp it from ftp://ripem.msu.edu/pub/crypt/ripem.

PGP is 'Pretty Good Privacy', and is currently on version 2.6.  The legal controversies that plagued earlier versions have been resolved, so this is a competely legal program now.  There is also a legal version for european users, called 2.6ui (the Unofficial International version).

PGP and PEM are programs that allow two parties to communicate in a way which does not allow third parties to read them, and which certify that the person who sent the message is really who they claim they are.

PGP and PEM both use RSA encryption.  The U.S.  government has strict export controls over foreign use of this technology, so people outside the U.S.  may have a difficult time finding programs which perform the encryption.

A working copy of either Pretty Good Privacy or RIPEM is required.  You should be familiar with the program and have generated a public/private key pair.

Currently, the protocol has been implemented with PEM and PGP using local key files on the server side, and on the client side with PEM using finger to retrieve the server's public key.

Parties who wish to use Emacs-W3 with PEM or PGP encryption will need to communicate beforehand and find a tamper-proof way to exchange their public keys.

Pioneers get shot full of arrows.  This work is currently in the experimental stages and thus may have some problems that I have overlooked.  The only known problem that I know about is that the messages are currently not timestamped.  This means that a malicious user could record the encrypted message with a packet sniffer and repeat it back to the server ad nauseum.  Although they would not be able to read the reply, if the request was for something being charged for, this could be very inconvenient.

This protocol is almost word-for-word a copy of Tony Sander's RIPEM based scheme, generalized a little.  Below, wherever PEM is used, replace it with PGP, and the behaviour should remain the same.

     *Client:*

     GET /docs/protected.html HTTP/1.0
     UserAgent: Emacs-W3/2.1.x

     *Server:*

     HTTP/1.0 401 Unauthorized
     WWW-Authenticate: PEM entity="webmaster@hoohoo.ncsa.uiuc.edu"
     Server: NCSA/1.1

     *Client:*

     GET / HTTP/1.0
     Authorization: PEM entity="robm@ncsa.uiuc.edu"
     Content-type: application/x-www-pem-request

     --- BEGIN PRIVACY-ENHANCED MESSAGE ---
     this is the real request, encrypted
     --- END PRIVACY-ENHANCED MESSAGE ---

     *Server:*

     HTTP/1.0 200 OK
     Content-type: application/x-www-pem-reply

     --- BEGIN PRIVACY-ENHANCED MESSAGE ---
     this is the real reply, encrypted
     --- END PRIVACY-ENHANCED MESSAGE ---
     That's it.

Emacs-W3 uses the excellent mailcrypt (Available from http://www.cs.indiana.edu/LCD/cover.html?mailcrypt) package written by Jin S Choi (jsc@mit.edu).  This package takes care of calling ripem and/or pgp with the correct arguments.  Please see the documentation at the top of mailcrypt.el for instructions on using mailcrypt.  All bug reports about mailcrypt should go to Jin S Choi, but bugs about how I use it in Emacs-W3 should of course be directed to me.

Mailcap Files
*************

NCSA Mosaic and almost all other WWW browsers rely on a separate file for mapping MIME types to external viewing programs.  This takes some of the burden off of browser developers, so each browser does not have to support all image formats, or postscript, etc.  Instead of having the users of Emacs-W3 duplicate this in lisp, this file can be parsed using the mm-parse-mailcaps function.  This function is called each time Emacs-W3 is loaded.  It tries to locate mimetype files in several places. If the environment variable MAILCAPS is nonempty, then this is assumed to specify a UNIX-like path of mimetype files (this is a colon separated string of pathnames).  If the MAILCAPS environment variable is empty, then Emacs-W3 looks for these files:

 1. ~/.mailcap

 2. /etc/mailcap

 3. /usr/etc/mailcap

 4. /usr/local/etc/mailcap

This format of this file is specified in RFC 1343, but a brief synopsis follows (this is taken verbatim from sections of RFC 1343).

Each mailcap file consists of a set of entries that describe the proper handling of one media type at the local site.  For example, one line might tell how to display a message in Group III fax format.  A mailcap file consists of a sequence of such individual entries, separated by newlines (according to the operating system's newline conventions). Blank lines and lines that start with the "#" character (ASCII 35) are considered comments, and are ignored.  Long entries may be continued on multiple lines if each non-terminal line ends with a backslash character ('\', ASCII 92), in which case the multiple lines are to be treated as a single mailcap entry.  Note that for such "continued" lines, the backslash must be the last character on the line to be continued.

Each mailcap entry consists of a number of fields, separated by semi-colons.  The first two fields are required, and must occur in the specified order.  The remaining fields are optional, and may appear in any order.

The first field is the content-type, which indicates the type of data this mailcap entry describes how to handle.  It is to be matched against the type/subtype specification in the "Content-Type" header field of an Internet mail message.  If the subtype is specified as "*", it is intended to match all subtypes of the named content-type.

The second field, view-command, is a specification of how the message or body part can be viewed at the local site.  Although the syntax of this field is fully specified, the semantics of program execution are necessarily somewhat operating system dependent.

The optional fields, which may be given in any order, are as follows:

  * The "compose" field may be used to specify a program that can be used to compose a new body or body part in the given format.  Its intended use is to support mail composing agents that support the composition of multiple types of mail using external composing agents.  As with the view- command, the semantics of program execution are operating system dependent.  The result of the composing program may be data that is not yet suitable for mail transport---that is, a Content-Transfer-Encoding may need to be applied to the data.

  * The "composetyped" field is similar to the "compose" field, but is to be used when the composing program needs to specify the Content-type header field to be applied to the composed data.  The "compose" field is simpler, and is preferred for use with existing (non-mail-oriented) programs for composing data in a given format.  The "composetyped" field is necessary when the Content-type information must include auxilliary parameters, and the composition program must then know enough about mail formats to produce output that includes the mail type information.

  * The "edit" field may be used to specify a program that can be used to edit a body or body part in the given format.  In many cases, it may be identical in content to the "compose" field, and shares the operating-system dependent semantics for program execution.

  * The "print" field may be used to specify a program that can be used to print a message or body part in the given format.  As with the view-command, the semantics of program execution are operating system dependent.

  * The "test" field may be used to test some external condition (e.g.  the machine architecture, or the window system in use) to determine whether or not the mailcap line applies.  It specifies a program to be run to test some condition.  The semantics of execution and of the value returned by the test program are operating system dependent.  If the test fails, a subsequent mailcap entry should be sought.  Multiple test fields are not permitted---since a test can call a program, it can already be arbitrarily complex.

  * The "needsterminal" field indicates that the view-command must be run on an interactive terminal.  This is needed to inform window-oriented user agents that an interactive terminal is needed.  (The decision is not left exclusively to the view-command because in some circumstances it may not be possible for such programs to tell whether or not they are on interactive terminals.)  The needsterminal command should be assumed to apply to the compose and edit commands, too, if they exist.  Note that this is NOT a test---it is a requirement for the environment in which the program will be executed, and should typically cause the creation of a terminal window when not executed on either a real terminal or a terminal window.

  * The "copiousoutput" field indicates that the output from the view-command will be an extended stream of output, and is to be interpreted as advice to the UA (User Agent mail- reading program) that the output should be either paged or made scrollable. Note that it is probably a mistake if needsterminal and copiousoutput are both specified.

  * The "description" field simply provides a textual description, optionally quoted, that describes the type of data, to be used optionally by mail readers that wish to describe the data before offering to display it.

  * The "x11-bitmap" field names a file, in X11 bitmap (xbm) format, which points to an appropriate icon to be used to visually denote the presence of this kind of data.

  * Any other fields beginning with "x-" may be included for local or mailer-specific extensions of this format.  Implementations should simply ignore all such unrecognized fields to permit such extensions, some of which might be standardized in a future version of this document.