\input texinfo
@setfilename ../info/w3.info
@settitle Emacs-W3 User's Manual
@iftex
@finalout
@end iftex
@c @setchapternewpage odd
@c @smallbook
@tex
\overfullrule=0pt
%\global\baselineskip 30pt      % for printing in double space
@end tex
@synindex cp fn
@synindex vr fn
@ifinfo
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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo
@c
@titlepage
@sp 6
@center @titlefont{Emacs-W3}
@center @titlefont{User's Manual}
@sp 4
@center Third Edition, Emacs-W3 Version 3.0
@sp 1
@center August 1996
@sp 5
@center William M. Perry
@center @i{wmperry@@cs.indiana.edu}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993, 1994, 1995 William M. Perry@*
Copyright @copyright{} 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.

@end titlepage
@page
@ifinfo
@node Top, Introduction,, (DIR)
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.

@menu
* Introduction::                Overview of Emacs-W3.
* Starting Up::                 What happens when you start Emacs-W3
* Basic Usage::                 Basic movement and usage of Emacs-W3.
* Compatibility::               Explanation of compatibility with
                                other web browsers.
* Controlling Formatting::	How to control HTML formatting
* MIME Support::                Support for MIME
* Security::                    Various forms of security
* Non-Unix Operating Systems::	Special considerations necessary to get
                                up and running correctly under non-unix
                                OS's.
* Advanced Features::           Some of the more arcane features.
* More Help::                   How to get more help---mailing lists,
                                newsgroups, etc.
* Future Directions::           Plans for future revisions

Appendices:
* Reporting Bugs::              How to report a bug in Emacs-W3
* Installing SSL::              Turning on SSL support
* Using PGP/PEM::               Turning on PGP/PEM encryption support
* Mailcap Files::               An explanation of Mailcap files

Indices:
* General Index::               General Index
* Key Index::                   Menus of command keys and their references
@end menu
@end ifinfo

@node Introduction, Starting Up, Top, Top
@chapter Introduction
@cindex World Wide Web
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
(@i{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 @dfn{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 @b{hypertext} and @b{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.
@iftex
@section Client Side View of WWW
@end iftex
@ifinfo
@center ----------------
@center CLIENT SIDE VIEW
@center ----------------
@end ifinfo
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 @i{virtual} document containing links to the documents
found.  A simple protocol, Hypertext Transfer Protocol or @i{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.
@iftex
@section Information Provider View of WWW
@end iftex
@ifinfo
@center -------------------------
@center INFORMATION PROVIDER VIEW
@center -------------------------
@end ifinfo
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 @b{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.


@ifinfo
Here is some more specific information about what Emacs-W3 does and does
not understand:
@menu
* Markup Languages Supported::	The different markup languages that
				Emacs-W3 understands natively.
* Supported Protocols::		The different network protocols that
				Emacs-W3 speaks to.
@end menu
@end ifinfo
@node Markup Languages Supported, Supported Protocols, Introduction, Introduction
@chapter Supported Markup Languages
Several different markup languages, and various extensions to those
languages, are supported by Emacs-W3.
@ifinfo
@center ----------
@center HTML 2.0
@center ----------
@end ifinfo
@iftex
@section HTML 2.0
@end iftex
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: @samp{<title>My Useful Document</title>}, and @samp{<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@footnote{ftp://ds.internic.net/}.  It is RFC 1866.


@ifinfo
@center ----------
@center HTML 3.0
@center ----------
@end ifinfo
@iftex
@section HTML 3.2
@end iftex
@cindex HTML 3.2
The HTML 3.2 language is an extension of HTML, with a large degree of
backward compatibility with HTML 2.0.  This basically documents current
practice as of January, 1996.

@ifinfo
@center ----------
@center Netscape-HTML
@center ----------
@end ifinfo
@iftex
@section Netscape-HTML
@end iftex
I hate to say it, but I broke down and actually included some of the
Netscape extensions into Emacs-W3.  The thing I hate to say even more,
is that most of the uglier things in Netscape-HTML are now in the HTML
3.2 specification.  All hail the W3Cs lack of backbone.

@table @b
@item <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 @b{not} to do things.
@item <isindex>
The isindex tag can now take a prompt attribute, to get rid of the
default 'This is a searchable index' label.
@end table
@ifinfo
@center ----------
@center SGML Features
@center ----------
@end ifinfo
@iftex
@section SGML Features
@end iftex
@cindex SGML Features
@cindex Entity Definitions
@cindex Marked Sections
:: WORK :: Document marked sections, SGML features
@ifinfo
@center ----------
@center Extras
@center ----------
@end ifinfo
@iftex
@section Extra Markup
@end iftex
@cindex Easter Eggs
@cindex Fluff
@cindex Pomp & Circumstance
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.
@itemize @bullet
@item
More <HR> improvements.  Text can be added into a horizontal rule by
using the LABEL and TEXTALIGN attributes.

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

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

<hr label="testing" textalign="left">
yields
-Testing----------------------------------------------------------
@end example
@item
FLAME support.  For truly interesting dynamic documents.  This is
replaced with a random quote from Mr. Angry (see @kbd{M-x flame} for a
sample).
@item
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
(@i{lemay@@netcom.com}).  Much thanks to her for the humor.
@table @b
@item <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.
@item <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.)
@item <pinhead>
Inserts "zippyisms" into the enclosed text.  Perfect for those professional
documents.  This is sure to be a favorite of mine!
@item <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.
@item <hype>
Causes Marc Andreesen to magically appear and grant an interview (wanted
or not).  Please use this tag sparingly.
@item <peek>....</peek>
@item <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.
@item <yogsothoth>
@cindex Gates Bill
@cindex 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.

@item <blink>...</blink>
Causes the enclosed text to .... ooops that one made it in.
@end table
@end itemize
@node Supported Protocols, , Markup Languages Supported, Introduction
@chapter Supported Protocols
@cindex Network Protocols
@cindex Protocols Supported
@cindex Supported Protocols
Emacs-W3 supports the following protocols
@table @b
@item 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.

@item HTTP
Supports the HTTP/0.9, HTTP/1.0, and HTTP/1.1 protocols.  Fully
MIME-compliant with regards to HTTP/1.0.
@item Gopher
Support for all gopher types, including CSO queries.
@item Gopher+
Support for Gopher+ retrievals. Support for converting ASK blocks into
HTML 3.0 FORMS and submitting them back to the server.
@item FTP
FTP is handled by either ange-ftp or efs.
@item Local files
Local files are handled, and MIME content-types are derived from the
file extensions.
@item Telnet
Telnet is handled by running the Emacs Lisp function @code{telnet}, or
spawning an xterm running telnet.
@item TN3270
TN3270 is handled by running a tn3270 program in an Emacs buffer, or
spawning an xterm running tn3270.
@item Mailto
Causes a mail message to be started to a specific address.
@item 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.
@item 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.
@item 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 @file{tcp.el}
package that comes with GNUS.  @xref{Installing SSL}
@item 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.
@end table

@node Starting Up, Basic Setup, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Starting Up
@cindex Starting Up Emacs-W3
This section of the manual deals with getting, compiling, and
configuring @i{Emacs-W3}.
@ifinfo
@menu
* Basic Setup::                 Basic setup that everyone needs to do
* Firewalls::                   How to set Emacs-W3 up to use a particular
                                firewall setup.
* Proxy Gateways::              Using a proxy server
@end menu
@end ifinfo

@node Basic Setup, Firewalls, Starting Up, Starting Up
@comment  node-name,  next,  previous,  up
@section Basic Setup
There are a few variables that almost all people need to change.

@table @code
@item w3-default-homepage
@vindex 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 @file{.emacs} file. If
WWW_HOME is undefined, then it defaults to the hypertext documentation
for Emacs-W3.

@item w3-delay-image-loads
@vindex w3-delay-image-loads
Controls the loading of inlined images.  If non-@code{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 @code{t}.
Defaults to @code{nil}.
@item url-global-history-file
@vindex 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.
@item w3-hotlist-file
@vindex 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.
@item w3-personal-annotation-directory
@vindex 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.
@item url-pgp/pem-entity
@findex user-real-login-name
@findex system-name
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
@code{user-mail-address} if it is set, otherwise @code{(user-real-login-name)}@@@code{(system-name)}.
@item url-personal-mail-address
@vindex url-personal-mail-address
@vindex url-pgp/pem-entity
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 @code{url-pgp/pem-entity}.

@item w3-right-border
@vindex w3-right-border
@findex window-width
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 @code{fill-column}.

@item w3-track-mouse
@vindex w3-track-mouse
Controls whether to track the mouse and message the url under the mouse.
If this is non-@code{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.
@item w3-echo-link
@vindex w3-echo-link
Controls how a URL is shown when a link is reached with @key{f},
@key{b}, or the mouse moves over it.  Possible values are:
@table @b
@item url
Displays the URL (ie: @samp{http://www.cs.indiana.edu/}).
@item text
Displays the text of the link (ie: @samp{A link to Indiana University}).
@item nil
Show nothing.
@end table
@item w3-use-forms-index
@vindex w3-use-forms-index
@cindex ISINDEX handling
@cindex Forms based searching
@cindex Searching with forms
Non-@code{nil} means translate <ISINDEX> tags into a hypertext form.  A
single text entry box is shown where the ISINDEX tag appears.
@item url-use-hypertext-gopher
@vindex url-use-hypertext-gopher
@cindex Gopher+
Controls how gopher documents are retrieved.  If non-@code{nil}, the
gopher pages are converted into HTML and parsed just like any other
page.  If @code{nil}, the requests are passed off to the
@file{gopher.el} package by Scott Snyder.  Using the @file{gopher.el}
package loses the gopher+ support, and inlined searching.
@item url-xterm-command
@vindex url-xterm-command
Command used to start a windowed shell, similar to an xterm.  This
string is passed through @code{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.
@end table
@node Firewalls, Proxy Gateways, Basic Setup, Starting Up
@comment  node-name,  next,  previous,  up
@section Firewalls
@cindex Gateways
There are several different reasons why the gateway support might be
required.
@enumerate
@cindex Firewalls
@item
Stuck behind a firewall.  This is usually the case at large corporations
with paranoid system-administrators.

@cindex TERM
@item
Using TERM @footnote{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: XEmacs and Emacs 19.22 or later have 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 @file{termnet} library that comes with the latest versions of TERM.
 
@item
@cindex Faulty hostname resolvers
@cindex Broken SUN libc
@cindex Can't resolve hostnames
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
@file{-lresolv} library or dynamic linking, it is just like being behind
a firewall.  Another alternative is to set the variable
@code{url-broken-resolution} - this will use the support in ange-ftp or
EFS to use @file{nslookup} in a subprocess to do all hostname resolving.
See the variables @code{efs-nslookup-program},
@code{efs-nslookup-on-connect}, and @code{efs-nslookup-threshold} if are
using EFS, or @code{ange-ftp-nslookup-program} if using Ange-FTP.

@end enumerate

@vindex url-gateway-local-host-regexp
Emacs-W3 has support for using the gateway mechanism for certain
domains, and directly connecting to others.  To use this, change the
value of @code{url-gateway-local-host-regexp}.  This should be a regular
expression @footnote{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 @code{nil}, then all connections are
made through the gateway.


@vindex url-gateway-method
Emacs-W3 supports several methods of getting around gateways.  The variable
@code{url-gateway-method} controls which of these methods is used.  This
variable can have several values (use these as symbol names, not
strings):
@table @dfn
@item program
Run a program in a subprocess to connect to remote hosts (examples are
@i{itelnet}@footnote{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
@i{expect}@footnote{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.).

@item host
Log into another local computer that has access to the internet, and run
a telnet-like program from there.
@item tcp
Masanobu UMEDA (@i{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 @code{program} does, but is slightly
more transparent to the user.
@item 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.
@end table
Two of these need a bit more explanation than that:
@vindex url-gateway-telnet-ready-regexp
@vindex url-gateway-telnet-program
When running a program in a subprocess to emulate a network connection,
a few extra variables need to be set.  The variable
@code{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
@code{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 @code{url-gateway-telnet-program}.
The default should work fine for telnet.

@cindex Host-based gateways
@cindex Hair-pulling gateway-headaches
@vindex url-gateway-host
When using the @code{host}-based gatway method, things get a bit more
complicated.  This is basically my attempt to do some of the basic stuff
of @i{expect} within elisp.  First off, set the variable
@code{url-gateway-host} to be the name of the gateway machine.


@vindex url-gateway-connect-program
The variable @code{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
@dfn{rsh} command.

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

@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:")
@end example

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

@vindex url-gateway-host-program-ready-regexp
@vindex url-gateway-host-program
The variable @code{url-gateway-host-program-ready-regexp} should contain
a regular expression that matches the end of the setup of
@code{url-gateway-host-program} when it tries to make a connection to an
off-firewall machine.  (Basically the same as
@code{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.

@node Proxy Gateways, Basic Usage, Firewalls, Starting Up
@comment  node-name,  next,  previous,  up
@section Proxy Gateways
@vindex url-proxy-services
@cindex Proxy Servers
@cindex Proxies
@cindex Proxies, environment variables
@cindex HTTP Proxy
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
@var{PROTOCOL}_proxy, where @var{PROTOCOL} is one of the supported
network protocols (gopher, file, HTTP, FTP, etc.)

@cindex No Proxy
@cindex Proxies, exclusion lists
@vindex NO_PROXY
For companies with internal intranets, it will usually be helpful to
define a list of hosts that should be contacted directly, @b{not} sent
through the proxy.  The @var{NO_PROXY} environment variable controls
what hosts are able to be contacted directly.  This should be a comma
separated list of hostnames, domain names, or a mixture of both.
Asterisks can be used as a wildcard.  For example:

@example
NO_PROXY=*.aventail.com,home.com,*.seanet.com
@end example

tells Emacs-W3 to contact all machines in the @b{aventail.com} and
@b{seanet.com} domains directly, as well as the machine named
@b{home.com}.

@vindex url-proxy-services
@cindex Proxies, setting from lisp
For those adventurous souls who enjoy writing regular expressions, all
the proxy settings can be manipulated from Emacs-Lisp.  The variable
@code{url-proxy-services} controls this.  This is an assoc list, keyed
on the protocol type (http, gopher, etc) in all lowercase.  The
@code{cdr} of each entry should be the fully-specified URL of the proxy
server to contact, or, in the case of the special "no_proxy" entry, a
regular expression that matches any hostnames that should be contacted
directly.

@example
(setq url-proxy-services '(("http"     . "http://proxy.aventail.com/")
                           ("no_proxy" . "^.*\\(aventail\\|seanet\\)\.com")))
@end example

@node Basic Usage, , Proxy Gateways, Top
@comment  node-name,  next,  previous,  up
@chapter Basic Usage
Emacs-W3 is similar to the Info package all Emacs users hold near and dear to
their hearts (@xref{Top,,Info,info, The Info Manual}, for a description
of Info).  Basically, @kbd{space} and @kbd{backspace} control scrolling,
and @kbd{return} or @kbd{mouse2} follows a hypertext link.  The @kbd{f}
and @kbd{b} keys maneuver around the various links on the page.

@b{NOTE:} To enter data into a form entry area, select it using
@kbd{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.  @xref{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 @b{current document}, and an
uppercase key takes an action on the document pointed to by the
hypertext link @b{under the cursor}.

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

@ifinfo
@menu
* Movement::		Moving around in a Emacs-W3 buffer
* Information::		Getting information about the Emacs-W3 document being
			viewed, and/or links within that document.
* Action::		Taking actions in a Emacs-W3 buffer (following links,
			printing, etc.)
* Miscellaneous::	Miscellaneous keybindings
@end menu
@end ifinfo
@node Movement, Information, Basic Usage, Basic Usage
@section Movement
:: WORK :: Document the 'h' and 'a' keymaps
@table @kbd
@findex scroll-up
@kindex SPC
@item SPC
Scroll downward in the buffer.  With prefix arg, scroll down that many
screenfuls. 
@kindex DEL
@findex scroll-down
@item DEL
Scroll upward in the buffer.  With prefix arg, scroll up that many
screenfuls. 
@kindex <
@findex w3-start-of-document
@item <
Goes to the start of document
@kindex >
@findex w3-end-of-document
@item >
Goes to the end of document
@kindex b
@kindex Shift-TAB
@findex w3-back-link
@item Shift-TAB, b
Attempts to move backward one link area in the current document.
Signals an error if no previous links are found.
@kindex hl
@findex w3-show-hotlist
@item hl
Displays a complete listing of the items in the hotlist.
@kindex hu
@findex w3-use-hotlist
@item hu
Go to a link in the hotlist.
@kindex m
@findex w3-complete-link
@item m
Choose a link from the current buffer and follow it.  A completing-read
is done on all the links, so @kbd{space} and @kbd{TAB} can be used for
completion.
@kindex f
@kindex TAB
@kindex n
@findex w3-forward-link
@item TAB, f, n
Attempts to move forward one link area in the current document.  Signals
an error if no more links are found.
@end table
@node Information, Action, Movement, Basic Usage
@section Information
These functions relate information about one or more links on the
current document.
@table @kbd
@kindex v
@findex url-view-url
@item v
This shows the URL of the current document in the minibuffer.
@kindex V
@findex w3-view-this-url
@item 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.
@kindex i
@findex w3-document-information
@item 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.
@kindex I
@findex w3-document-information-this-url
@item I
Shows information about the URL at point.
@kindex s
@findex w3-source-document
@item 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.
@kindex S
@findex w3-source-document-at-point
@item 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.
@kindex k
@findex w3-save-url
@item k
This stores the current document's URL in the kill ring, and also in the
current window-system's clipboard, if possible.
@kindex K
@findex w3-save-this-url
@item K
Stores the URL of the document under point in the kill ring, and also in
the current window-system's clipboard, if possible.
@end table
@node Action, Miscellaneous, Information, Basic Usage
@section Action
First, here are the keys and functions that bring up a new hypertext
page, usually creating a new buffer.
@table @kbd
@kindex return
@findex w3-follow-link
@item return 
Pressing return when over a hyperlink attempts to follow the link
under the cursor.  With a prefix argument (@kbd{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).

@kindex Middle Mouse Button
@findex w3-follow-mouse
@item 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).

@kindex Control Middle Mouse Button
@kindex Meta return
@findex w3-follow-inlined-image
@item 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.

@kindex p
@findex w3-print-this-url
@item p
Prints out the current buffer in a variety of formats, including
PostScript, HTML source, or formatted text.
@kindex P
@findex w3-print-url-under-point
@item P
Prints out the URL under point in a variety of formats, including
PostScript, HTML source, or formatted text.
@kindex m
@findex w3-complete-link
@item m
Selects a destination from a list of all the hyperlinks in the current
buffer.  Use @kbd{space} and @kbd{tab} to complete on the links.

@kindex r
@kindex g
@findex w3-reload-document
@item 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.
@kindex C-o
@findex w3-fetch
@item 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.
@kindex o
@findex w3-open-local
@vindex url-use-hypertext-dired
@item 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 @code{url-use-hypertext-dired} is @code{nil},
then a dired-mode buffer is displayed.  If non@code{nil}, 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.

@kindex M-s
@findex w3-search
@item 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.
@kindex Hv
@findex w3-show-history-list
@vindex w3-keep-history
@item Hv
If @code{url-keep-history} is non-@code{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.
@end table

@cindex Buffer movement
And here are the commands to move around between Emacs-W3 buffers:

@table @kbd
@kindex l
@findex w3-goto-last-buffer
@item l
Goes to the last WWW buffer seen.
@kindex q
@findex w3-quit
@item q
Quits WWW mode.  This kills the current buffer and goes to the most
recently visited buffer.
@kindex Q
@findex w3-leave-buffer
@item 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
@code{w3-goto-last-buffer} in that it does not return to the last WWW
page visited - it is the same as using @code{switch-to-buffer} - the
buffer left in the window is fairly random. 
@kindex HB
@kindex B
@findex w3-backward-in-history
@item HB, B
Takes one step back along the path in the current history.  Has no
effect if at the beginning of the session history.
@kindex HF
@kindex F
@findex w3-forward-in-history
@item HF, F
Takes one step forward along the path in the current history.  Has no
effect if at the end of the session history.
@end table

@node Miscellaneous, , Action, Basic Usage
@section Miscellaneous
@table @kbd
@kindex M-m
@findex w3-mail-current-document
@item 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.
@kindex M-M
@findex w3-mail-document-under-point
@item 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.
@kindex p
@findex w3-print-this-url
@item 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).

@findex lpr-buffer
@vindex lpr-command
@vindex lpr-switches
When the formatted text is printed, the normal @code{lpr-buffer} function
is called, and the variables @code{lpr-command} and @code{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.
@vindex w3-use-html2latex
@vindex w3-html2latex-prog
@vindex w3-html2latex-args
@vindex w3-print-commnad
@vindex w3-latex-docstyle
When postscript is printed, then the HTML source of the document is
converted into LaTeX source.  If the variable @code{w3-use-html2latex}
is non-@code{nil}, then the program specified by
@code{w3-html2latex-prog} is run in a subprocess with the arguments in
@code{w3-html2latex-args}.  The @code{w3-html2latex-prog} must accept
HTML source on its standard input and send the LaTeX output to standard
output.  If @code{w3-use-html2latex} is @code{nil}, then an Emacs Lisp
function uses regular expressions to replace the HTML code with LaTeX
markup.  The variable @code{w3-latex-docstyle} controls how the document
is laid out in this case, and postscript figures are printed as
well.
@kindex P
@findex w3-print-url-under-point
@item P
Prints the document pointed to by the hypertext link under point.
Please see the previous item for more information.
@kindex M-x w3-insert-formatted-url
@findex w3-insert-formatted-url
@item 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.
@kindex M-tab
@findex w3-insert-this-url
@item 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.
@kindex U
@findex w3-use-links
@item 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 @code{completing-read} on only the links that have that type of
relationship.
@end table

@node Compatibility, , , Top
@comment  node-name,  next,  previous,  up
@chapter 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.

@ifinfo
@menu
* Emulation::			Emacs-W3 can emulate the keybindings and
				other behaviours of other browsers.
* Hotlist Handling::            A hotlist is an easy way to keep track of
				interesting Web pages without having to
				remember the exact path to get there.
* Session History::             Keeping a history of documents visited
				in one Emacs sessions allows the use of
				'forward' and 'back' buttons easily.
* Global History::		Keeping a history of all the places ever
				visited on the web.
* Annotations::                 Annotations allow comments on other
				people's Web documents without needing
				to change the document.
@end menu
@end ifinfo
@node Emulation, Hotlist Handling, Compatibility, Compatibility
@section Emulation
:: WORK :: Document lynx emulation
:: WORK :: Document netscape emulation
@cindex Browser emulation
@cindex Emulation of other browsers
@cindex Netscape emulation
@cindex Lynx emulation
@findex turn-on-netscape-emulation
@findex turn-on-lynx-emulation
@findex w3-netscape-emulation-minor-mode
@findex w3-lynx-emulation-minor-mode
@vindex w3-mode-hook

@node Hotlist Handling, Session History, Emulation, Compatibility
@section 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 @code{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 @file{~/.mosaic-hotlist-default}.

Hotlist commands are:
@table @kbd
@kindex hi
@findex w3-hotlist-add-document
@vindex w3-hotlist-file
@item a
Adds the current document to the hotlist, with the buffer name as its
identifier.  Modifies the file specified by @code{w3-hotlist-file}.  If
this is given a @var{prefix-argument} (via @kbd{C-u}), the title is
prompted for instead of automatically defaulting to the
document title.

@findex w3-hotlist-refresh
@vindex w3-hotlist-file
@kindex hR
@item hR
This rereads the default hostlist file specified by
@code{w3-hotlist-file}.
@findex w3-hotlist-delete
@vindex w3-hotlist-file
@kindex hd
@item 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 @code{w3-hotlist-file} are
updated. 
@item hr
@kindex hr
@findex w3-hotlist-rename-entry
@vindex w3-hotlist-file
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
@code{w3-hotlist-file}.

@item hu
@kindex hu
@findex w3-use-hotlist
Prompts for the alias to jump to.  Pressing the @key{spacebar} or
@key{tab} key shows partial completions.

@item hv
@kindex hv
@findex w3-show-hotlist
Converts the hotlist into HTML and displays it.
@item ha
@kindex ha
@findex w3-hotlist-apropos
Shows the hotlist entries matching a regular expression.
@item hA
@kindex hA
@findex w3-hotlist-append
Appends another hotlist file to the one currently in memory.
@end table
@node Session History, Global History, Hotlist Handling, Compatibility
@section History
@cindex History Lists
Almost all web browsers keep track of the URLs followed from a page, so
that it can provide @b{forward} and @b{back} buttons to keep a @i{path}
of URLs that can be traversed easily.
@vindex url-keep-history
If the variable @code{url-keep-history} is @code{t}, then Emacs-W3
keeps a list of all the URLs visited in a session.
@findex w3-show-history
To view a listing of the history for this session of Emacs-W3, use
@code{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.

@findex w3-forward-in-history
@findex w3-backward-in-history
@findex w3-fetch
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 @b{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 @code{w3-forward-in-history},
to go backward, use the function @code{w3-backward-in-history}.

@node Global History, Annotations, Session History, Compatibility
@section 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.

@vindex url-keep-history
@vindex url-global-history-file
If the variable @code{url-keep-history} is @code{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 @code{url-global-history-file},
which defaults to @file{~/.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.

@cindex Completion of URLs
@cindex Usefulness of global history
One of the nice things about keeping a global history files is that Emacs-W3
can use it as a completion table.  When doing @kbd{M-x w3-fetch}, pressing
the @kbd{tab} or @kbd{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.

@node Annotations, Group Annotations, Global History, Compatibility
@section Annotations
@cindex Annotations
Mosaic can @i{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.
 
@ifinfo
@menu
* Group Annotations::             Annotations accessible by everyone
* Personal Annotations::          Private annotations only accessible
				  to the user who created them
@end menu
@end ifinfo
@node Group Annotations, Personal Annotations, Annotations, Annotations
@subsection Group Annotations
@cindex Group Annotations
@b{@i{NOTE}}: The group annotation experiment has been terminated.  It
will be replaced with support on the server side for adding <LINK> tags
to documents.

@node Personal Annotations, , Group Annotations, Annotations
@subsection Personal Annotations
@cindex Personal Annotations
@vindex w3-personal-annotation-directory
Emacs-W3 looks in the directory specified by
@code{w3-personal-annotation-directory} (defaults to
@file{~/.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

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

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

@findex w3-delete-personal-annotation
To delete a personal annotation, it must be the current page.  Once
reading the annotation, @kbd{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.

@node Controlling Formatting, General Formatting, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Controlling Formatting
@cindex Customizing formatting
@cindex Specifying Fonts
@cindex Fonts
@cindex Colors
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.

@ifinfo
@menu
* General Formatting::                 Changing general things about a
                                       document.
* Character based terminals::          Changing how a document is
                                       displayed on a non-graphics
                                       terminal (vt100, etc.@:) or if
                                       @code{w3-delimit-emphasis} is @code{t}.
* Graphics workstations::              Changing how a document is
                                       displayed on a graphics terminal
                                       (Xwindows, Windows, NeXTstep,
                                       OS/2, etc.)
* Inlined images::                     How to specify how Emacs-W3
                                       handles inlined images/mpegs.
@end menu
@end ifinfo
@node General Formatting, Character based terminals, Controlling Formatting, Controlling Formatting
@section General formatting conventions
@iftex
@heading Setting the fill column
@end iftex
@ifinfo
@center --------------------
@center Setting the fill column
@center --------------------
@end ifinfo
@vindex fill-column
@vindex w3-right-border
Each time a document is parsed, the @code{fill-column} is recalculated
using @code{window-width} and @code{w3-right-border}.
@code{w3-right-border} is an integer specifying how much room at the
right edge of the screen to leave blank.  The @code{fill-column} is set
to @code{(- (window-width) @code{w3-right-border})}.
@iftex
@heading Formatting of hypertext links
@end iftex
@ifinfo
@center --------------------
@center Formatting of hypertext links
@center --------------------
@end ifinfo
@vindex w3-delimit-links
@vindex w3-link-start-delimiter
@vindex w3-link-end-delimiter
If the variable @code{w3-delimit-links} is non-@code{nil} (the default
for text-terminals), then hypertext links are surrounded by text
specified by the user.  The variables @code{w3-link-start-delimiter} and
@code{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 @i{global
history}), then the @code{car} of these variables is inserted at the
start and end of the link.  If the link has been visited before, then
the @code{cdr} is inserted.  So, links look like:

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

@iftex
@heading Formatting of lists
@end iftex
@ifinfo
@center --------------------
@center Formatting of lists
@center --------------------
@end ifinfo
@cindex Indentation
@vindex w3-indent-level
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 @code{w3-indent-level}.  This is the number of spaces to
indent lists and other items requiring special margins.

@vindex w3-list-chars-assoc
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
@code{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 @code{car} of this list should be a symbol
(@b{not} a string) representing the type of list (e.g., @samp{ul}).
The rest of the list should consist of strings to insert at certain
levels of lists.  The @code{n}th element of this list is used when the
list is nested @code{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 '.'.
@iftex
@heading Formatting of directory listings
@end iftex
@ifinfo
@center --------------------
@center Formatting of directory listings
@center --------------------
@end ifinfo
@vindex url-use-hypertext-dired
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
@code{dired-mode} to peruse the listing.  The variable
@code{url-use-hypertext-dired} controls this behavior.

If the value is @code{t}, Emacs-W3 uses @code{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 @code{nil}, just pass the directory off to dired using
@code{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.

@ignore
@cindex Downloading multiple files
@cindex FTP'ing multiple files
@vindex url-forms-based-ftp
A new option in the 2.2 series is @code{url-forms-based-ftp} - this is
still in the experimental stages, but can be useful.  If
@code{url-forms-based-ftp} is @code{t}, then all automatically generated
directory listings will have a form mixed in with the file listing.
Each file will have a checkbox next to it, and a row of buttons at the
bottom of the screen.  Selecting one of the buttons at the bottom of the
screen will take the designated action on all the marked files.
Currently, only deleting and copying marked files is supported.
@end ignore
@iftex
@heading Formatting of gopher directories
@end iftex
@ifinfo
@center --------------------
@center Formatting of gopher directories
@center --------------------
@end ifinfo
@vindex w3-use-hypertext-gopher
@cindex Gopher+
@cindex ASK blocks
There are two different ways of viewing gopher links.  The built-in
support that converts gopher directories into HTML, or the
@file{gopher.el} package by Scott Snyder (@i{snyder@@fnald0.fnal.gov}).
The variable that controls this is @code{w3-use-hypertext-gopher}.  If
set to @code{nil}, then @file{gopher.el} is used.  Any other value
causes Emacs-W3 to use its internal gopher support.  If using
@file{gopher.el}, all the hypertext capabilities of Emacs-W3 are lost.
All the functionality of @file{gopher.el} is now available in the
hypertext version, and the hypertext version supports Gopher+ and ASK
blocks. 

@vindex w3-gopher-labels
The main way to control the display of gopher directories is by the
variable @code{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: @samp{("0" . "(TXT)")}.  I have tried to keep all the tags
to three characters plus two parentheses. 
@iftex
@heading Creating a horizontal rule
@end iftex
@ifinfo
@center --------------------
@center Creating a horizontal rule
@center --------------------
@end ifinfo
@vindex w3-horizontal-rule-char
Horizontal rules (@b{<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
@code{w3-horizontal-rule-char} controls which character is used to draw a
horizontal bar.  This variable must be the ASCII value of the character,
@b{not a string}.  The variable is passed through make-string whenever a
horizontal rule of a certain width is necessary.

@node Character based terminals, Graphics workstations, General Formatting, Controlling Formatting
@section On character based terminals
@vindex w3-delimit-emphasis
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
@code{w3-delimit-emphasis} is non-@code{nil}, then Emacs-W3 can insert
characters before and after character formatting commands in HTML
documents.  The defaul value of @code{w3-delimit-emphasis} is
automatically set based on the type of window system and version of
Emacs being used. 

@vindex w3-header-chars-assoc
:: WORK ::

@findex w3-upcase-region
@code{w3-header-chars-assoc} is an assoc list of header tags and a list
of formatting instructions.  The @code{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 @code{w3-upcase-region} instead of
@code{upcase-region}, so that entities are converted properly.

@node Graphics workstations, Inlined images, Character based terminals, Controlling Formatting
@section 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

@node Inlined images, , Graphics workstations, Controlling Formatting
@cindex Inlined images
@cindex Images
@cindex Movies
@cindex Inlined MPEGs
@cindex MPEGs
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.

@cindex Netpbm
@cindex Pbmplus
@vindex w3-graphic-converter-alist
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 @b{netpbm utilities}@footnote{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 @code{w3-graphic-converter-alist}
controls how each image type is converted.  This is an assoc list, keyed
on the MIME content-type.  The @code{car} is the content-type, and the
@code{cdr} is a string suitable to pass to @code{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:

@enumerate
@item
image/x-xbitmap
@item
image/xbitmap
@item
image/xbm
@item
image/gif
@item
image/jpeg
@item
image/x-fax
@item
image/x-raster
@item
image/windowdump
@item
image/x-icon
@item
image/portable-graymap
@item
image/portable-pixmap
@item
image/x-pixmap
@item
image/x-xpixmap
@item
image/pict
@item
image/x-macpaint
@item
image/x-targa
@item
image/tiff
@end enumerate

@vindex w3-color-max-blue
@vindex w3-color-max-green
@vindex w3-color-max-red
@vindex w3-color-use-reducing
@vindex w3-color-filter
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 @code{w3-color-use-reducing} is non-@code{nil}, then the
images will use reduced colors.  If @code{w3-color-filter} is @code{eq} to
@code{'ppmquant}, then the ppmquant program will be used.  If @code{eq} to
@code{'ppmdither}, then the ppmdither program will be used.  The ppmdither
program tends to give better results.  The values of
@code{w3-color-max-red}, @code{w3-color-max-blue}, and
@code{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.  @code{w3-color-filter} may also be a string, specifying
exactly what external filter to use.  An example is: @samp{ppmquant -fs
-map ~/pixmaps/colormap.ppm}.

@cindex MPEGs
@cindex Inlined animations
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:
@example
<embed href="somevideo.mpg" type="video/mpeg">
@end example

@vindex w3-mpeg-args
@vindex w3-mpeg-program
This requires a special version of the standard @file{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
@code{w3-mpeg-program} should point to this executable, and
@code{w3-mpeg-args} should be a list of any additional arguments to be
passed to the player.  By default, this includes @var{-loop}, so the
mpeg plays continuously.

@cindex Delaying inlined images
@cindex Delaying inlined animations
@vindex w3-delay-image-loads
@vindex w3-delay-mpeg-loads
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
@code{w3-delay-image-loads} and @code{w3-delay-mpeg-loads} control this.
If set to non-@code{nil}, then the images or movies are not
loaded until explicitly requested by the user.

@cindex Loading delayed images
@cindex Loading delayed movies
@findex w3-load-delayed-images
@findex w3-load-delayed-mpegs
To load any delayed images, use the function
@code{w3-load-delayed-images}.  Its counterpart for delayed movies is
@code{w3-load-delayed-mpegs}

@node MIME Support, Adding MIME types based on file extensions, , Top
@chapter 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
@samp{text/html} specifies an HTML document, whereas
@samp{image/x-xwindowdump} specifies an image of an Xwindow taken with
the @file{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 @file{something.gif} (not a great idea, but
possible).

@ifinfo
@menu
* Adding MIME types based on file extensions::  How to map file
                                                extensions onto MIME
                                                types (e.g., @samp{.gif ->
                                                image/gif)}.
* Specifying Viewers::  How to specify external and internal viewers
                        for files that Emacs-W3 cannot handle natively.
@end menu
@end ifinfo

@node Adding MIME types based on file extensions, Specifying Viewers, MIME Support, MIME Support
@section Adding MIME types based on file extensions
@vindex mm-mime-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 @code{mm-mime-extensions}.

This variable is an assoc list of file extensions and the corresponding
MIME content-type.  A sample entry looks like: @samp{(".movie"
. "video/x-sgi-movie")} This makes all files that end in @file{.movie}
(@file{foo.movie} and @file{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 @b{NOT} be used.

@cindex mime-types file
@findex mm-parse-mimetypes
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
@code{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 @code{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 @code{MIMETYPES} environment
variable is empty, then Emacs-W3 looks for these files:

@enumerate
@item
@file{~/.mime-types}
@item
@file{/etc/mime-types}
@item
@file{/usr/etc/mime-types}
@item
@file{/usr/local/etc/mime-types}
@item
@file{/usr/local/www/conf/mime-types}
@end enumerate

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 ...  ext@var{n}

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.

@node Specifying Viewers, ,Adding MIME types based on file extensions, MIME Support
@section 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.  @xref{Mailcap Files}

@findex mm-add-mailcap-entry
As an alternative, the function @code{mm-add-mailcap-entry} can also be
used from an appropriate hook.@xref{Hooks}  This functions takes three
arguments, the major type ("@i{image}"), the minor type ("@i{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.

@node Security, Non-Unix Operating Systems, , Top
@chapter Security
@cindex Security
@cindex Paranoia
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:

@table @b
@item Basic Authentication
@cindex Security, Basic
@cindex HTTP/1.0 Authentication
@cindex Authentication, Basic
The weakest authentication available, not recommended if serious
security is necessary.  This is simply a string that looks like
@samp{user:password} that has been Base64 encoded, as defined in RFC
1421.
@item Digest Authentication
@cindex Security, Digest
@cindex HTTP/1.0 Authentication
@cindex Authentication, Digest
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@footnote{One is ftp://ds.internic.net/internet-drafts}.
@item SSL Encryption
@cindex HTTP/1.0 Authentication
@cindex Secure Sockets Layer
@cindex SSL
@cindex Gag Puke Retch
@cindex Exportability
@cindex Export Restrictions
SSL is the @code{Secure Sockets Layer} interface developed by Netscape
Communications @footnote{http://www.netscape.com/}.  Emacs-W3 supports
HTTP transfers over an SSL encrypted channel, if the appropriate files
have been installed.@xref{Installing SSL}
@item PGP/PEM
@cindex HTTP/1.0 Authentication
@cindex Public Key Cryptography
@cindex Authentication, PGP
@cindex Authentication, PEM
@cindex RIPEM
@cindex Public Key Cryptography
@cindex PGP
@cindex Pretty Good Privacy
@cindex Encryption
@cindex Security
@cindex ITAR must die
@cindex Stupid export restrictions
@cindex Support your local crypto-anarchist
@cindex NSA freaks
A few servers still support this method of authentication, but it has
been superseded by SSL and Secure-HTTP.@xref{Using PGP/PEM}
@end table

@node Non-Unix Operating Systems, VMS, Security, Top
@chapter Non-Unix Operating Systems
@cindex Non-Unix Operating Systems
@ifinfo
@menu
* VMS::                 The wonderful world of VAX|AXP-VMS!
* OS/2::                The next-best thing to Unix.
* MS-DOS::              The wonderful world of MS-DOG!
* 32-Bit Windows::      Windows NT, Chicago/Windows 95.
* Amiga::               The Amiga, for those who still love them.
@end menu
@end ifinfo

@node VMS, OS/2, Non-Unix Operating Systems, Non-Unix Operating Systems
@section VMS
@cindex VAX-VMS
@cindex AXP-VMS
@cindex Digital VMS
@cindex VMS
:: WORK :: VMS Specific instriuctions

@node OS/2, MS-DOS, VMS, Non-Unix Operating Systems
@section OS/2
@cindex OS/2
@cindex Warp
:: WORK :: OS/2 Specific instructions

@node MS-DOS, 32-Bit Windows, OS/2, Non-Unix Operating Systems
@section MS-DOS
@cindex MS-DOS
@cindex Microsloth
@cindex DOS
@cindex MS-DOG
:: WORK :: DOS Specific instructions

@node 32-Bit Windows, Amiga, MS-DOS, Non-Unix Operating Systems
@section 32-Bit Windows
@cindex Windows (32-Bit)
@cindex 32-Bit Windows
@cindex Microsloth
@cindex Windows '95
:: WORK :: 32bit Windows Specific instructions

@node Amiga, Advanced Features, 32-Bit Windows, Non-Unix Operating Systems
@section Amiga
@cindex Amiga
@cindex Commodore
:: WORK :: Amiga specific instructions

@node Advanced Features, Style Sheets, Amiga, Top
@comment  node-name,  next,  previous,  up
@chapter Advanced Features

@ifinfo
@menu
* Style Sheets::        Formatting control, the right way
* Disk Caching::        Improving performance by using a local disk cache
* Interfacing to Mail/News::	How to make VM understand hypertext links
* Debugging HTML::      How to make Emacs-W3 display warnings about invalid
                        HTML/HTML+ constructs.
* Native WAIS Support:: How to make Emacs-W3 understand WAIS links without
                        using a gateway.
* Rating Links::        How to make Emacs-W3 put an 'interestingness' value
                        next to each link.
* Gopher Plus Support:: How Emacs-W3 makes use of the Gopher+ protocol.
* Hooks::               Various hooks to use throughout Emacs-W3
* Other Variables::     Miscellaneous variables that control the real
                        guts of Emacs-W3.
@end menu
@end ifinfo

@node Style Sheets, Disk Caching, Advanced Features, Advanced Features
@section Style Sheets
@cindex Formatting control
@cindex Style sheets
@cindex Look and Feel
@cindex Layout control
@cindex Experimental style sheet mechanism
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.

@example
<style notation="css">
/* This is a comment
** These will be ignored, up to the terminating */

h1 @{ align: center,
     color: yellow,
     background: red,
     font-size: 24pt
   @}
h2 @{ align: right,
     font-family: palatino,
     font-size: 18pt
   @}
</style>
@end example

:: WORK :: Much more information on stylesheets

@cindex <style>
To include a stylesheet into a document, simply use the <style> tag.
Use the @b{notation} attribute to specify what language the stylesheet
is specified in.  The default is @b{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.
@example
<link rel="stylesheet" href="/bill.style">
@end example
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.

@cindex DSSSL
@cindex DSSSL-lite
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

@node Disk Caching, Interfacing to Mail/News, Style Sheets, Advanced Features
@section Disk Caching
@cindex Caching
@cindex Persistent Cache
@cindex Disk Cache
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.

@vindex url-automatic-caching
@cindex Turning on caching
@cindex Cleaning the cache
@cindex Clearing the cache
@cindex Cache cleaning
@cindex Limiting the size of the cache
To turn on disk caching, set the variable @code{url-automatic-caching}
to non-@code{nil}, or choose the 'Caching' menu item (under `Options').
That is all there is to it.  Running the @code{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 @i{at} or @i{cron} (see the manual pages for
crontab(5) or at(1) for more information)


@cindex Relying on cache
@cindex Cache only mode
@cindex Standalone mode
@cindex Browsing with no network connection
@cindex Netless browsing
@vindex url-standalone-mode
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 @code{url-standalone-mode} to
non-@code{nil}, or choose the `Use Cache Only' menu item (under
`Options')

@cindex Caching options
@cindex Alternate caching method
Emacs-W3 caches files under the temporary directory specified by
@code{url-temporary-directory}, in a user-specific subdirectory
(determined by the @code{user-real-login-name} function).  The cache
files are stored under their original names, so a URL like:
http://www.aventail.com/foo/bar/baz.html would be stored in a cache file
named: /tmp/wmperry/com/aventail/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
@file{.emacs} file:


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

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

@node Interfacing to Mail/News, Debugging HTML, Disk Caching, Advanced Features
@section Interfacing to Mail/News
@cindex Interfacing to Mail/News
@cindex VM
@cindex Using Emacs-W3 with VM
@cindex GNUS
@cindex Using Emacs-W3 with Gnus
@cindex RMAIL
@cindex Using Emacs-W3 with RMAIL
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. 

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

To access URLs from within RMAIL, the following hook should do the
trick.
@example
(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))))
@end example

@node Debugging HTML, Native WAIS Support, Interfacing to Mail/News, Advanced Features
@section Debugging HTML
@cindex Debugging
@cindex Invalid HTML
@cindex Bad HTML
@vindex w3-debug-buffer
@vindex w3-debug-html
For those people that are adventurous, or are just as anal as I am about
people writing valid HTML, set the variable @code{w3-debug-html} to
@code{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 ::

@node Native WAIS Support, Rating Links, Debugging HTML, Advanced Features
@section 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 @dfn{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.

@vindex url-waisq-prog
@vindex url-wais-gateway-server
@vindex url-wais-gateway-port
The variable @code{url-waisq-prog} must point to this executable, and
one of @code{url-wais-gateway-server} or @code{url-wais-gateway-port}
should be @code{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 @code{url-waisq-prog} in a subprocess.  The
results will be converted into HTML and displayed.

@node Rating Links, Gopher Plus Support, Native WAIS Support, Advanced Features
@section Rating Links
The @code{w3-link-info-display-function} variable can be used to 'rate' a URL
when it shows up in an HTML page.  If non-@code{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:

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

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

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

@node Gopher Plus Support, Hooks, Rating Links, Advanced Features
@section Gopher+ Support
@cindex Gopher+
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.

@node Hooks, Other Variables, Gopher Plus Support, Advanced Features
@section Hooks
@cindex 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.

@table @code
@vindex w3-load-hooks
@item w3-load-hooks
These hooks are run by @code{w3-do-setup} the first time a URL is
fetched.  All the w3 variables are initialized before this hook is
run.
@item w3-file-done-hooks
These hooks are run by @code{w3-prepare-buffer} after all parsing on a
document has been done.  All @code{url-current-}@var{*} and
@code{w3-current-}@var{*} 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.
@item w3-file-prepare-hooks
These hooks are run by @code{w3-prepare-buffer} before any parsing is
done on the HTML file.  The HTTP/1.0 headers specified by
@code{w3-show-headers} have been inserted, the syntax table has been set
to @code{w3-parse-args-syntax-table}, and any personal annotations have
been inserted by the time this hook is run.
@item w3-mode-hooks
These hooks are run after a buffer has been parsed and displayed, but
before any inlined images are downloaded and converted.
@item w3-source-file-hooks
These hooks are run after displaying a document's source
@end table

@node Other Variables, , Hooks, Advanced Features
@section 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.

@table @code
@item url-bad-port-list
@vindex 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.
@item url-confirmation-func
@vindex url-confirmation-func
What function to use for asking yes or no functions.  Possible values
are @code{'yes-or-no-p} or @code{'y-or-n-p}, or any function that takes
a single argument (the prompt), and returns @code{t} only if a positive
answer is gotten.  Defaults to @code{'yes-or-no-p}.
@item w3-default-action
@vindex w3-default-action
A lisp symbol specifying what action to take for files with extensions
that are not in the @code{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 @code{'w3-prepare-buffer} or @code{'indented-text-mode}.
@ignore
@item w3-icon-directory-list
@vindex w3-icon-directory-list
A list of directorys to look in for the w3 standard icons...  must end
in a /!  If the directory @code{data-directory}/w3 exists, then this is
automatically added to the default value of
http://cs.indiana.edu/elisp/w3/icons/.
@end ignore
@item w3-keep-old-buffers
@vindex 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 @code{nil}.  I
recommend setting it to @code{t}, so that backtracking from one link to
another is faster.

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

@item w3-reuse-buffers
@vindex w3-reuse-buffers
Determines what happens when @code{w3-fetch} is called on a document
that has already been loaded into another buffer.  Possible values are:
@code{nil}, @code{yes}, and @code{no}.  @code{nil} will ask the user if
Emacs-W3 should reuse the buffer (this is the default value).  A value of
@code{yes} means assume the user wants to always reuse the buffer.  A
value of @code{no} means assume the user always wants to re-fetch the
document.
@item w3-show-headers
@vindex 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 @code{t}, then
all the HTTP/1.0 headers are shown.  The default value is
@code{nil}.
@item w3-show-status, url-show-status
@vindex url-show-status
@vindex w3-show-status
Whether to show progress messages in the minibuffer.
@code{w3-show-status} controls if messages about the parsing are
displayed, and @code{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.
@item mm-content-transfer-encodings
@vindex mm-content-transfer-encodings
An assoc list of @var{Content-Transfer-Encodings} or
@var{Content-Encodings} and the appropriate decoding algorithms for each.
If the @code{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 @code{stdin}
and send its output to @code{stdout}.

If the @code{cdr} of a node is a symbol whose function definition is
non-@code{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.
@item url-uncompressor-alist
@vindex 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.
@item url-waisq-prog
@vindex url-waisq-prog
Name of the waisq executable on this system.  This should be the
@file{waisq} program from think.com's wais8-b5.1 distribution.
@end table

@node More Help, Future Directions, , Top
@chapter More Help
@cindex Relevant Newsgroups
@cindex Newsgroups
@cindex Support
For more help on Emacs-W3, please send me mail
(@i{wmperry@@cs.indiana.edu}).  Several discussion lists have also been
created for Emacs-W3.  To subscribe, send mail to
@i{majordomo@@indiana.edu}, with the body of the message 'subscribe
@var{listname} @var{<email addres>}'.  All other mail should go to
@i{<listname>@@indiana.edu}.


@itemize @bullet
@item
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.
(@i{www-announce@@w3.org} is included on this list).
@item
w3-beta -- this list is for beta testers of Emacs-W3.  These brave souls test
out not-quite stable code.
@item
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.
@end itemize

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 @i{<listname>-request@@w3.org}
with a subject line of 'subscribe <listname>'.  All mail should go to
@i{<listname>@@w3.org}.  Administrative mail should go to
@i{www-admin@@w3.org}.  The lists are:


@itemize @bullet
@item
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.
@item
www-announce -- for announcements concerning the World Wide Web.  Server
changes, new servers, new software, etc.
@end itemize

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

@node Future Directions, Reporting Bugs, More Help, Top
@chapter 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

@node Reporting Bugs, Installing SSL, Future Directions, Top
@appendix Reporting Bugs
@cindex Reporting Bugs
@cindex Bugs
@cindex Contacting the author

:: WORK :: Reporting bugs needs work.

@node Installing SSL, Using PGP/PEM, Reporting Bugs, Top 
@appendix Installing SSL
@cindex HTTP/1.0 Authentication
@cindex Secure Sockets Layer
@cindex SSL
@cindex Gag Puke Retch
@cindex Exportability
@cindex Export Restrictions
In order to use SSL in Emacs-W3, an implementation of SSL is necessary.
These are the implementations that I am aware of:

@table @code
@item SSLRef 2.0
Available from Netscape Communications @footnote{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/
@item 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/
@end table

@vindex ssl-program-name
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 @code{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.

@node Using PGP/PEM, Mailcap Files, Installing SSL, Top
@appendix Using PGP/PEM
@cindex HTTP/1.0 Authentication
@cindex Public Key Cryptography
@cindex Authentication, PGP
@cindex Authentication, PEM
@cindex RIPEM
@cindex Public Key Cryptography
@cindex PGP
@cindex Pretty Good Privacy
@cindex Encryption
@cindex Security
@cindex ITAR must die
@cindex Stupid export restrictions
@cindex Support your local crypto-anarchist
@cindex NSA freaks
Most of this chapter has been reproduced from the original documentation
written by Rob McCool (@i{robm@@netscape.com})@footnote{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.

@example
*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.  
@end example

@cindex Mailcrypt
Emacs-W3 uses the excellent @i{mailcrypt}@footnote{Available from
http://www.cs.indiana.edu/LCD/cover.html?mailcrypt} package written by
Jin S Choi (@i{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.

@node Mailcap Files, General Index, Using PGP/PEM, Top
@appendix 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 @code{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 @code{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 @code{MAILCAPS}
environment variable is empty, then Emacs-W3 looks for these
files:

@enumerate
@item
@file{~/.mailcap}
@item
@file{/etc/mailcap}
@item
@file{/usr/etc/mailcap}
@item
@file{/usr/local/etc/mailcap}
@end enumerate

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:
@itemize @bullet
@item
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.
@item
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.
@item
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.
@item
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.
@item
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.
@item
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.
@item
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.
@item
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.
@item
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.
@item
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.
@end itemize

@node General Index, Key Index, Mailcap Files, Top
@appendix General Index
@printindex fn
@node Key Index, , General Index, Top
@appendix Key Index
@printindex ky
@contents
@bye