xemacs-beta: man/w3.texi comparison

comparison man/w3.texi @ 70:131b0175ea99 r20-0b30

Import from CVS: tag r20-0b30

author	cvs
date	Mon, 13 Aug 2007 09:02:59 +0200
parents	6a22abad6937
children	1ce6082ce73f

comparison

equal deleted inserted replaced

-:804d1389bcd6
+:131b0175ea99
 \input texinfo
-@c
+@setfilename ../info/w3.info
-@c Please note that this file uses some constructs not supported by earlier
+@settitle Emacs-W3 User's Manual
-@c versions of TeX-info.  You must be running one of the newer TeX-info
-@c releases (I currently use version 3.9 from ftp://prep.ai.mit.edu/pub/gnu/)
-@c
-@c Please do not send in bug reports about not being able to format the
-@c document with 'makeinfo' or 'tex', just upgrade your installation.
-@c
-@c Info formatted files are provided in the distribution, and you can
-@c retrieve dvi, postscript, and PDF versions from the web site or FTP
-@c site: http://www.cs.indiana.edu/elisp/w3/docs.html
-@c
-@setfilename w3.info
-@settitle Emacs/W3 User's Manual
 @iftex
 @finalout
 @end iftex
 @c @setchapternewpage odd
 @c @smallbook
 \overfullrule=0pt
 %\global\baselineskip 30pt      % for printing in double space
 @end tex
 @synindex cp fn
 @synindex vr fn
-@dircategory World Wide Web
-@dircategory GNU Emacs Lisp
-@direntry
-* W3: (w3).                       Emacs/W3 World Wide Web browser.
-@end direntry
 @ifinfo
-This file documents the Emacs/W3 World Wide Web browser.
+This file documents the Emacs-W3 World Wide Web browser.
-Copyright (C) 1993, 1994, 1995, 1996 William M. Perry
+Copyright (C) 1993, 1994, 1995 William M. Perry
-Copyright (C) 1996, 1997 Free Software Foundation
+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.
 @end ignore
 @end ifinfo
 @c
 @titlepage
 @sp 6
-@center @titlefont{Emacs/W3}
+@center @titlefont{Emacs-W3}
 @center @titlefont{User's Manual}
 @sp 4
-@center Third Edition, Emacs/W3 Version 3.0
+@center Third Edition, Emacs-W3 Version 3.0
 @sp 1
-@center February 1997
+@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, 1997 Free Software Foundation
+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, Getting Started, (dir), (dir)
+@node Top, Introduction,, (DIR)
-@top W3
+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
-Users can browse the World Wide Web from within Emacs by using Emacs/W3.
+following chapters.
-All of the widely used (and even some not very widely used) @sc{url}
-schemes are supported, and it is very easy to add new methods as the
-need arises.
-Emacs/W3 provides some core functionality that can be readily re-used
-from any program in Emacs.  Users and other package writers are
-encouraged to @i{Web-enable} their applications and daily work routines
-with the library.
-Emacs/W3 is completely customizable, both from Emacs-Lisp and from
-stylesheets @xref{Stylesheets}  If there is any aspect of Emacs/W3 that
-cannot be modified to your satisfaction, please send mail to the
-@t{w3-beta@@indiana.edu} mailing list with any suggestions.
-@xref{Reporting Bugs}
 @menu
-* Getting Started::             Getting up and running with Emacs/W3
+* Introduction::                Overview of Emacs-W3.
-* Basic Usage::                 Basic movement and usage 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 browsers.
+other web browsers.
-* Stylesheets::                 How to control the look of web pages
+* Controlling Formatting::	How to control HTML formatting
-* Supported URLs::              What @sc{URL} schemes are supported.
+* MIME Support::                Support for MIME
-* MIME Support::                Support for @sc{mime}
+* Security::                    Various forms of security
-* Security::                    Various security methods supported
+* Non-Unix Operating Systems::	Special considerations necessary to get
-* Non-Unix Operating Systems::  Special considerations necessary to get
 up and running correctly under non-unix
 OS's.
-* Speech Integration::          Outputting to a speech synthesizer.
 * 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.
+* Reporting Bugs::              How to report a bug in Emacs-W3
-* Dealing with Firewalls::      How to get around your firewall.
+* Installing SSL::              Turning on SSL support
-* Proxy Gateways::              Using a proxy gateway with Emacs/W3.
+* Using PGP/PEM::               Turning on PGP/PEM encryption support
-* Installing SSL::              Turning on @sc{ssl} support.
+* Mailcap Files::               An explanation of Mailcap files
-* Mailcap Files::               An explanation of Mailcap files.
-* Down with DoubleClick::       Annoyed by advertisements?  Read this!
 Indices:
-* General Index::               General Index.
+* General Index::               General Index
-* Key Index::                   Menus of command keys and their references.
+* Key Index::                   Menus of command keys and their references
 @end menu
 @end ifinfo
-@node Getting Started, Basic Usage, Top, Top
+@node Introduction, Starting Up, Top, Top
-@chapter Getting Started
+@chapter Introduction
-@cindex Clueless in Seattle
+@cindex World Wide Web
-@cindex Getting Started
+Emacs-W3 is an Emacs subsystem that allows the user to browse the wonderful
-@kindex M-x w3
+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
-@findex w3
+The url to open at startup.  This defaults to the environment variable
-If installed correctly, starting Emacs/W3 is quite painless.  Just type
+WWW_HOME if it is not set it in the users @file{.emacs} file. If
-@kbd{M-x w3} in a running Emacs session.  This will retrieve the default
+WWW_HOME is undefined, then it defaults to the hypertext documentation
-page that has been configured (@pxref{Preferences Panel}) - by default the
+for Emacs-W3.
-documentation for Emacs/W3 at Indiana University.
+@item w3-delay-image-loads
-If the default page is not retrieved correctly at startup, you will have
+@vindex w3-delay-image-loads
-to do some customization (@pxref{Preferences Panel}).
+Controls the loading of inlined images.  If non-@code{nil}, images are
+not loaded.  If the correct image converters are not installed or the
-Once started, you can use the mouse and the menu or use the following
+network connection is very slow, it is best to set this to @code{t}.
-key commands (for more commands and more detail, @pxref{Basic Usage, ,
+Defaults to @code{nil}.
-Basic Usage}).
+@item url-global-history-file
+@vindex url-global-history-file
-@table @asis
+The global history file used by both Mosaic/X and Emacs-W3.  This file
-@item move forward
+contains a list of all the URLs that have been visited.  This file is parsed
-press the space bar,
+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
-@item move backwards
+internal format (faster).  The file type is determined automatically, or
-press the backspace key,
+prompted for if the file does not exist.
+@item w3-hotlist-file
-@item move to the next HTML reference on the page
+@vindex w3-hotlist-file
-press the @kbd{TAB} key,
+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
-@item move to the previous HTML reference on the page
+commonly accessed URLs.
-press the @kbd{SHIFT} and @kbd{TAB} keys at the same time.  If this does
+@item w3-personal-annotation-directory
-not work (some text terminals cannot distinguish between @kbd{TAB} and
+@vindex w3-personal-annotation-directory
-@kbd{SHIFT-TAB}, pressing the @kbd{ALT} and @kbd{TAB} keys should also
+The directory where Emacs-W3 looks for personal annotations.  This is a
-work.
+directory that should hold the personal annotations stored in a
+Mosaic/X-compatible format.
-@item follow a link
+@item url-pgp/pem-entity
-put the cursor over it
+@findex user-real-login-name
-and press the @kbd{RETURN} key, or @*
+@findex system-name
-click the left mouse button on it,
+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
-@item fetch a @sc{url}
+@code{user-mail-address} if it is set, otherwise @code{(user-real-login-name)}@@@code{(system-name)}.
-press the @kbd{Control} and @kbd{o} keys at the same time,@*
+@item url-personal-mail-address
-type the @sc{url}, and then press the @kbd{RETURN} key,
+@vindex url-personal-mail-address
+@vindex url-pgp/pem-entity
-@item return to the last URL you were at
+User's full email address.  This is what is sent to HTTP/1.0 servers as
-press the @kbd{l} key,
+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 quit W3 mode
-press the @kbd{q} key.
+@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
-@menu
+@vindex w3-use-forms-index
-* Downloading::                 Where to download Emacs/W3.
+@cindex ISINDEX handling
-* Building and Installing::     Compiling and installing from source.
+@cindex Forms based searching
-* Startup Files::               What is where, and why.
+@cindex Searching with forms
-* Preferences Panel::           Quick configuration of common options.
+Non-@code{nil} means translate <ISINDEX> tags into a hypertext form.  A
-@end menu
+single text entry box is shown where the ISINDEX tag appears.
+@item url-use-hypertext-gopher
-@node Downloading, Building and Installing, Getting Started, Getting Started
+@vindex url-use-hypertext-gopher
-@section Downloading
+@cindex Gopher+
+Controls how gopher documents are retrieved.  If non-@code{nil}, the
-:: WORK :: What you need, and why
+gopher pages are converted into HTML and parsed just like any other
-:: WORK :: Where to download Emacs, XEmacs, various platforms
+page.  If @code{nil}, the requests are passed off to the
-:: WORK :: Where to download Emacs/W3
+@file{gopher.el} package by Scott Snyder.  Using the @file{gopher.el}
-:: WORK :: Where to download related utilities (netpbm, xv, gimp, etc.)
+package loses the gopher+ support, and inlined searching.
+@item url-xterm-command
-@node Building and Installing, Startup Files, Downloading, Getting Started
+@vindex url-xterm-command
-@section Building and Installing
+Command used to start a windowed shell, similar to an xterm.  This
+string is passed through @code{format}, and should expect four strings:
-:: WORK :: Document makefile variables
+the title of the window, the program name to execute, and the server and
-:: WORK :: Document what gets installed where, why
+port number.  The default is for xterm, which is very UNIX and
+XWindows-centric.
-@node Startup Files, Preferences Panel, Building and Installing, Getting Started
+@end table
-@section Startup Files
+@node Firewalls, Proxy Gateways, Basic Setup, Starting Up
-@cindex Startup files
+@comment  node-name,  next,  previous,  up
-@cindex Default stylesheet
+@section Firewalls
+@cindex Gateways
-:: WORK :: startup files
+There are several different reasons why the gateway support might be
-This section should document where Emacs/W3 looks for its startup files,
+required.
-and what each one does.  'profile' 'stylesheet' 'hotlist' 'history' etc.
+@enumerate
+@cindex Firewalls
-@node Preferences Panel,  , Startup Files, Getting Started
+@item
-@section Preferences Panel
+Stuck behind a firewall.  This is usually the case at large corporations
-@cindex Preferences
+with paranoid system-administrators.
-@kindex M-x w3-preferences-edit
+@cindex TERM
-:: WORK :: pref panel
+@item
-This should document the quick preferences panel.  M-x w3-preferences-edit
+Using TERM @footnote{TERM is a user-level protocol for emulating IP over
+a serial line.  More information is available at
-@node Basic Usage, Compatibility, Getting Started, Top
+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
-@cindex Basic Usage
+Emacs-W3 is similar to the Info package all Emacs users hold near and dear to
-@kindex space
+their hearts (@xref{Top,,Info,info, The Info Manual}, for a description
-@kindex backspace
+of Info).  Basically, @kbd{space} and @kbd{backspace} control scrolling,
-@kindex return
+and @kbd{return} or @kbd{mouse2} follows a hypertext link.  The @kbd{f}
-@kindex tab
+and @kbd{b} keys maneuver around the various links on the page.
-@kindex M-tab
-Emacs/W3 is similar to the Info package all Emacs users hold near and
+@b{NOTE:} To enter data into a form entry area, select it using
-dear to their hearts (@xref{Top,,Info,info, The Info Manual}, for a
+@kbd{return} or the middle mouse button, just like a hypertext link.
-description of Info).  Basically, @kbd{space} and @kbd{backspace}
-control scrolling, and @kbd{return} or the middle mouse button follows a
-hypertext link.  The @kbd{tab} and @kbd{Meta-tab} keys maneuver around the
+On non-graphic terminals (VT100, DOS, etc.), hypertext links are
-various links on the page.
+surrounded by '[[' and ']]' by default.  On a graphics terminal, the
+links are in bold print.  @xref{Controlling Formatting} for information
-@b{NOTE:} Starting with Emacs/W3 3.0, form entry areas in a page can be
+on how to change this, or for help on getting the highlighting to work
-typed directly into.  This is one of the main differences in navigation
+on graphics terminals.
-from version 2.0.  If you are used to using the @kbd{f} and @kbd{b} keys
-to navigate around a buffer, I suggest training yourself to always use
+There are approximately 50 keys bound to special Emacs-W3 functions.
-@kbd{tab} and @kbd{M-tab} - it will save time and frustration on pages
+The basic rule of thumb regarding keybindings in Emacs-W3 is that a
-with lots of form fields.
-By default, hypertext links are surrounded by '[[' and ']]' on
-non-graphic terminals (VT100, DOS window, etc.).  On a graphics
-terminal, the links are in shown in different colors.
-@xref{Stylesheets} for information on how to change this.
-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 the buffer.
+* Movement::		Moving around in a Emacs-W3 buffer
-* Information::                 Getting information about a document.
+* Information::		Getting information about the Emacs-W3 document being
-* Action::                      Following links, printing, etc.
+			viewed, and/or links within that document.
-* Miscellaneous::               Everything else.
+* 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
-All the standard Emacs bindings for movement are still in effect, with a
-few additions for convenience.
 @table @kbd
-@findex w3-scroll-up
+@findex scroll-up
-@kindex space
+@kindex SPC
-@item space
+@item SPC
 Scroll downward in the buffer.  With prefix arg, scroll down that many
 screenfuls.
-@kindex backspace
+@kindex DEL
 @findex scroll-down
-@item backspace
+@item DEL
 Scroll upward in the buffer.  With prefix arg, scroll up that many
 screenfuls.
 @kindex <
 @findex w3-start-of-document
 @item <
 @kindex >
 @findex w3-end-of-document
 @item >
 Goes to the end of document
 @kindex b
-@kindex Meta-tab
+@kindex Shift-TAB
-@findex w3-widget-backward
+@findex w3-back-link
-@item Meta-tab, Shift-tab, b
+@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 f
+@kindex hl
-@kindex tab
+@findex w3-show-hotlist
-@kindex n
+@item hl
-@findex w3-widget-forward
+Displays a complete listing of the items in the hotlist.
-@item tab, f, n
+@kindex hu
-Attempts to move forward one link area in the current document.  Signals
+@findex w3-use-hotlist
-an error if no more links are found.
+@item hu
-@kindex B
+Go to a link in the hotlist.
-@findex w3-backward-in-history
-@item B
-Move backwards in the history stack.
-@kindex F
-@findex w3-forward-in-history
-@item F
-Move forwards in the history stack.
-@kindex l
-@findex w3-goto-last-buffer
-@item l
-Return to the last buffer shown before this buffer.
-@kindex q
-@findex w3-quit
-@item q
-Kill this buffer.
-@kindex Q, u
-@findex w3-leave-buffer
-@item Q, u
-Bury this buffer, but don't kill it
-@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 @sc{url} of the current document in the minibuffer.
-@kindex V
-@findex w3-view-this-url
-@item V
-This shows the @sc{url} of the hypertext link under point in the
-minibuffer.
-@kindex i
-@findex w3-document-information
-@item i
-Shows miscellaneous information about the currently displayed document.
-This includes the @sc{url}, the last modified date, @sc{mime} headers,
-the @sc{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 @sc{url} at point.
-@kindex s
-@findex w3-source-document
-@item s
-This shows the @sc{html} source of the current document in a separate buffer.
-The buffer's name is based on the document's @sc{url}.
-@kindex S
-@findex w3-source-document-at-point
-@item S
-Shows the @sc{html} source of the hypertext link under point in a separate
-buffer.  The buffer's name is based on the document's @sc{url}.
-@kindex k
-@findex w3-save-url
-@item k
-This stores the current document's @sc{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 @sc{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 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 @sc{html}.
+or being parsed as HTML.
-Pressing return when over a form input field can cause auto-submission
+Pressing return when over a form input field will prompt in the
-of the form.  This is for Mosaic and Netscape compatibility.  If there
-is only one item in the form other than submit or reset buttons, then
 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
 @kindex p
 @findex w3-print-this-url
 @item p
 Prints out the current buffer in a variety of formats, including
-PostScript, @sc{html} source, or formatted text.
+PostScript, HTML source, or formatted text.
 @kindex P
 @findex w3-print-url-under-point
 @item P
-Prints out the @sc{url} under point in a variety of formats, including
+Prints out the URL under point in a variety of formats, including
-PostScript, @sc{html} source, or formatted text.
+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.
 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 @sc{url} in the minibuffer, and attempts to fetch
+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
+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
+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-save-as
+@findex w3-search
 @item M-s
-Save a document to the local disk as HTML Source, Formatted Text, LaTeX
+Perform a search, if this is a searchable index.  Searching requires a
-Source, or Binary.
+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
+If @code{url-keep-history} is non-@code{nil}, then Emacs-W3 keeps track
-of all the @sc{url}s visited in an Emacs session.  This function takes all
+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:
+And here are the commands to move around between Emacs-W3 buffers:
 @table @kbd
 @kindex l
 @findex w3-goto-last-buffer
 @item l
 @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
+@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, @sc{html} source, PostScript, or LaTeX source.
+formats to mail: formatted text, HTML source, PostScript, or LaTeX source.
-When the @sc{html} source is mailed, then an appropriate <base> tag is inserted
+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, @sc{html} source,
+Choose from several different formats to mail: formatted text, HTML source,
-PostScript, or LaTeX source.  When the @sc{html} source is mailed, then an
+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, @sc{html} source, PostScript (with ps-print), or by using
+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 @sc{html} source is printed, then an appropriate <base> tag is
+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 @sc{html} source of the document is
+When postscript is printed, then the HTML source of the document is
-converted into LaTeX source.  There are several variables controlling
+converted into LaTeX source.  If the variable @code{w3-use-html2latex}
-what the final LaTeX document looks like.
+is non-@code{nil}, then the program specified by
+@code{w3-html2latex-prog} is run in a subprocess with the arguments in
-:: WORK :: Document the new LaTeX backend
+@code{w3-html2latex-args}.  The @code{w3-html2latex-prog} must accept
+HTML source on its standard input and send the LaTeX output to standard
-@table @code
+output.  If @code{w3-use-html2latex} is @code{nil}, then an Emacs Lisp
-@item w3-latex-use-latex2e
+function uses regular expressions to replace the HTML code with LaTeX
-@vindex w3-latex-use-latex2e
+markup.  The variable @code{w3-latex-docstyle} controls how the document
-If non-@code{nil}, configures the LaTeX engine to use the LaTeX2e
+is laid out in this case, and postscript figures are printed as
-syntax.  A @code{nil} value indicates that LaTeX 2.0.9 compabibility
+well.
-will be used instead.
-@item w3-latex-docstyle
-@vindex w3-latex-docstyle
-The document style to use when printing or mailing converted @sc{html} files
-in LaTeX.  Good defaults are: @{article@}, [psfig,twocolumn]@{article@},
-etc.
-@item w3-latex-packages
-@vindex w3-latex-packages
-List of LaTeX packages to include.  Currently this is only used if
-@code{w3-latex-use-latex2e} is non-@code{nil}.
-@item w3-latex-use-maketitle
-@vindex w3-latex-use-maketitle
-If non-@code{nil}, the LaTeX engine will use real LaTeX title pages for
-document titles.
-@item w3-latex-print-links
-@vindex w3-latex-print-links
-If non-@code{nil}, prints the @sc{url}s of hypertext links as endnotes at the
-end of the document.  If set to @code{footnote}, prints the @sc{url}'s as
-footnotes on each page.
-@end table
 @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 @sc{html} link into another buffer.  This gets the
+Insert a fully formatted HTML link into another buffer.  This gets the
-name and @sc{url} of either the current buffer, or, with a prefix arg, of 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 @sc{url} of the current document into another buffer.  Buffer is
+Inserts the URL of the current document into another buffer.  Buffer is
-prompted for in the minibuffer.  With prefix arg, uses the @sc{url} of the
+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
 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, Stylesheets, Basic Usage, Top
+@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
+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
+* 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
+* 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
-:: WORK :: Document lynx emulation
-@table @kbd
-@item Down arrow
-Highlight next topic
-@item Up arrow
-Highlight previous topic
-@item Right arrow, Return, Enter
-Jump to highlighted topic
-@item Left arrow
-Return to previous topic
-@item +
-Scroll down to next page (Page-Down)
-@item -
-Scroll up to previous page (Page-Up)
-@item SPACE
-Scroll down to next page (Page-Down)
-@item b
-Scroll up to previous page (Page-Up)
-@item C-A
-Go to first page of the current document (Home)
-@item C-E
-Go to last page of the current document (End)
-@item C-B
-Scroll up to previous page (Page-Up)
-@item C-F
-Scroll down to next page (Page-Down)
-@item C-N
-Go forward two lines in the current document
-@item C-P
-Go back two lines in the current document
-@item )
-Go forward half a page in the current document
-@item (
-Go back half a page in the current document
-@item #
-Go to Toolbar or Banner in the current document
-@item ?, h
-Help (this screen)
-@item a
-Add the current link to a bookmark file
-@item c
-Send a comment to the document owner
-@item d
-Download the current link
-@item e
-Edit the current file
-@item g
-Goto a user specified @sc{url} or file
-@item i
-Show an index of documents
-@item j
-Execute a jump operation
-@item k
-Show a list of key mappings
-@item l
-List references (links) in current document
-@item m
-Return to main screen
-@item o
-Set your options
-@item p
-Print the current document
-@item q
-Quit
-@item /
-Search for a string within the current document
-@item s
-Enter a search string for an external search
-@item n
-Go to the next search string
-@item v
-View a bookmark file
-@item V
-Go to the Visited Links Page
-@item x
-Force submission of form or link with no-cache
-@item z
-Cancel transfer in progress
-@item [backspace]
-Go to the history Page
-@item =
-Show file and link info
-@item \
-Toggle document source/rendered view
-@item !
-Spawn your default shell
-@item *
-Toggle image_links mode on and off
-@item [
-Toggle pseudo_inlines mode on and off
-@item ]
-Send an @sc{http} @sc{head} request for the current doc or link
-@item C-R
-Reload current file and refresh the screen
-@item C-W
-Refresh the screen
-@item C-U
-Erase input line
-@item C-G
-Cancel input or transfer
-@item C-T
-Toggle trace mode on and off
-@item C-K
-Invoke the Cookie Jar Page
-@end table
-:: WORK :: Document netscape emulation
-Uh, turn this into pretty tables about what keys are emulated.
-@example
-(define-key w3-netscape-emulation-minor-mode-map "\M-s" 'w3-save-as)
-(define-key w3-netscape-emulation-minor-mode-map "\M-m" 'w3-mailto)
-(define-key w3-netscape-emulation-minor-mode-map "\M-n" 'make-frame)
-(define-key w3-netscape-emulation-minor-mode-map "\M-l" 'w3-fetch)
-(define-key w3-netscape-emulation-minor-mode-map "\M-o" 'w3-open-local)
-(define-key w3-netscape-emulation-minor-mode-map "\M-p" 'w3-print-this-url)
-(define-key w3-netscape-emulation-minor-mode-map "\M-q" 'w3-quit)
-(define-key w3-netscape-emulation-minor-mode-map "\M-f" 'w3-search-forward)
-(define-key w3-netscape-emulation-minor-mode-map "\M-g" 'w3-search-again)
-(define-key w3-netscape-emulation-minor-mode-map "\M-r" 'w3-reload-document)
-(define-key w3-netscape-emulation-minor-mode-map "\M-i" 'w3-load-delayed-images)
-(define-key w3-netscape-emulation-minor-mode-map "\M-a" 'w3-hotlist-add-document)
-(define-key w3-netscape-emulation-minor-mode-map "\M-b" 'w3-show-hotlist)
-(define-key w3-netscape-emulation-minor-mode-map "\M-h" 'w3-show-history-list)
-@end example
 @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
+document over and over, Emacs-W3 supports a ``hotlist'' like Mosaic.  This is
-a file that contains @sc{url}s and aliases.  Hotlists allow quick access to any
+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}.
 @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 prefix-argument (via @kbd{C-u}), the title is prompted
+this is given a @var{prefix-argument} (via @kbd{C-u}), the title is
-for instead of automatically defaulting to the document title.
+prompted for instead of automatically defaulting to the
+document title.
 @findex w3-hotlist-refresh
 @vindex w3-hotlist-file
 @kindex hR
 @item hR
 @key{tab} key shows partial completions.
 @item hv
 @kindex hv
 @findex w3-show-hotlist
-Converts the hotlist into @sc{html} and displays it.
+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
 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
-Almost all web browsers keep track of the @sc{url}s followed from a page, so
 that it can provide @b{forward} and @b{back} buttons to keep a @i{path}
-of @sc{url}s that can be traversed easily.
+of URLs that can be traversed easily.
 @vindex url-keep-history
-If the variable @code{url-keep-history} is @code{t}, then Emacs/W3
+If the variable @code{url-keep-history} is @code{t}, then Emacs-W3
-keeps a list of all the @sc{url}s visited in a session.
+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
+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
+@code{M-x w3-show-history} from any buffer, and Emacs-W3 generates an
-@sc{html} document showing every @sc{url} visited since Emacs started (or
+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 @sc{url}, buffer, and buffer position of the
+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,  , Session History, Compatibility
+@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 @sc{url}s the
+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
-@sc{url}s.
+URLs.
 @vindex url-keep-history
 @vindex url-global-history-file
-If the variable @code{url-keep-history} is @code{t}, then Emacs/W3
+If the variable @code{url-keep-history} is @code{t}, then Emacs-W3
-keeps a list of all the @sc{url}s visited in a session.  The file is
+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 @sc{url} in the list is found in the file, it is not saved, but new
+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
+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
+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 @sc{url}.  This is very useful, especially for very long @sc{url}s that
+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 Stylesheets, Supported URLs, Compatibility, Top
+@node Annotations, Group Annotations, Global History, Compatibility
-@chapter Stylesheets
+@section Annotations
-The way in which Emacs/W3 formats a document is very customizable.  All
+@cindex Annotations
-formatting is now controlled by a default stylesheet set by the user
+Mosaic can @i{annotate} documents.  Annotations are comments about the
-with the @code{w3-default-stylesheet} variable.  Emacs/W3 currently
+current document, and these annotations appear as a link to the comments
-supports the @sc{W3C} recommendation for Cascading Style Sheets, Level 1
+at the end of the document.  The original file is not changed.
-(commonly known as @sc{CSS1}) with a few experimental items from other
-W3C proposals.  Wherever Emacs/W3 diverges from the specification, it
+@ifinfo
-will be clearly documented, and will be changed once a full standard is
-available.
-Support for @sc{DSSSL} is progressing, but spare time is at an all-time
-low.  If anyone would like to help, please contact the author.
-The following sections closely parallel the @sc{CSS1} specification so
-it should be very easy to look up what Emacs/W3 supports when browsing
-through the @sc{CSS1} specification.  Please note that a lot of the text
-in the following sections comes directly from the specification as
-well.
 @menu
-* Terminology::                 Terms used in the rest of this chapter.
+* Group Annotations::             Annotations accessible by everyone
-* Basic Concepts::              Why are stylesheets useful?  Getting started.
+* Personal Annotations::          Private annotations only accessible
-* Pseudo-Classes/Elements::     Special classes for elements.
+				  to the user who created them
-* The Cascade::                 How stylesheets are combined.
-* Properties::                  What properties you can set on elements.
-* Units::                       What you can set them to.
 @end menu
+@end ifinfo
-@node Terminology, Basic Concepts, Stylesheets, Stylesheets
+@node Group Annotations, Personal Annotations, Annotations, Annotations
-@section Terminology
+@subsection Group Annotations
+@cindex Group Annotations
-@table @dfn
+@b{@i{NOTE}}: The group annotation experiment has been terminated.  It
-@item attribute
+will be replaced with support on the server side for adding <LINK> tags
-HTML attribute, ie: @samp{align=center} - align is the attribute.
+to documents.
-@item author
-The author of an HTML document.
+@node Personal Annotations, , Group Annotations, Annotations
-@item block-level element
+@subsection Personal Annotations
-An element which has a line break before and after (e.g. 'H1' in @sc{HTML}).
+@cindex Personal Annotations
-@item canvas
+@vindex w3-personal-annotation-directory
-The part of the UA's drawing surface onto which documents are rendered.
+Emacs-W3 looks in the directory specified by
-@item child element
+@code{w3-personal-annotation-directory} (defaults to
-A subelement in @sc{sgml} terminology.
+@file{~/.mosaic-personal-annotations}).  Any personal annotations for a
-@item contextual selector
+document are automatically appended when it is retrieved.
-A selector that matches elements based on their position in the document
-structure. A contextual selector consists of several simple
+:: WORK :: Document the new 'a' prefix keymap
-selectors. E.g., the contextual selector 'H1.initial B' consists of two
+:: WORK :: Tell where the annotations are stored
-simple selectors, 'H1.initial' and 'B'.
-@item @sc{css}
+@findex w3-add-personal-annotation
-Cascading Style Sheets.
+@vindex w3-annotation-mode
-@item declaration
+To add a new personal annotation, type @kbd{M-x
-A property (e.g. 'font-size') and a corresponding value (e.g. '12pt').
+w3-add-personal-annotation}.  This creates a new buffer, in the mode
-@item designer
+specified by @code{w3-annotation-mode}.  This defaults to
-The designer of a style sheet.
+@code{html-mode}.  If this variable is @code{nil}, or it points to an
-@item document
+undefined function, then @code{default-major-mode} is consulted.
-@sc{html} document.
-@item element
+A minor mode redefines @kbd{C-c C-c} to complete the annotation and
-@sc{html} element.
+store it on the local disk.
-@item element type
-A generic identifier in @sc{sgml} terminology.
+@findex w3-delete-personal-annotation
-@item fictional tag sequence
+To delete a personal annotation, it must be the current page.  Once
-A tool for describing the behavior of pseudo-classes and pseudo-elements.
+reading the annotation, @kbd{M-x w3-delete-personal-annotation} will
-@item font size
+remove it.  This deletes the file containing the annotation, and any
-The size for which a font is designed. Typically, the size of a font is
+references to it in the annotation log file.
-approximately equal to the distance from the bottom of the lowest letter
-with a descender to the top of the tallest letter with an ascender and
+Editing personal annotations is not yet supported.
-(optionally) with a diacritical mark.
-@item @sc{html} extension
+@node Controlling Formatting, General Formatting, Top, Top
-Markup introduced by UA vendors, most often to support certain visual
+@comment  node-name,  next,  previous,  up
-effects. The @sc{font}, @sc{center} and @sc{blink} elements are examples
+@chapter Controlling Formatting
-of HTML extensions, as is the @sc{bgcolor} attribute. One of the goals
+@cindex Customizing formatting
-of @sc{css} is to provide an alternative to @sc{html} extensions.
+@cindex Specifying Fonts
-@item inline element
+@cindex Fonts
-An element which does not have a line break before and after
+@cindex Colors
-(e.g. '@sc{strong}' in @sc{html})
+How Emacs-W3 formats a document is very customizable.  How a document is
-@item intrinsic dimensions
+displayed depends on whether the user is on a terminal
-The width and height as defined by the element itself, not imposed by
+capable of graphics and a few variables.
-the surroundings. In this specification it is assumed that all replaced
-elements -- and only replaced elements -- come with intrinsic
+The following sections describe in more detail how to change the
-dimensions.
+formatting of a document.
-@item parent element
-The containing element in @sc{sgml} terminology.
+@ifinfo
-@item pseudo-element
+@menu
-Pseudo-elements are used in @sc{css} selectors to address typographical
+* General Formatting::                 Changing general things about a
-items (e.g. the first line of an element) rather than structural
+document.
-elements.
+* Character based terminals::          Changing how a document is
-@item pseudo-class
+displayed on a non-graphics
-Pseudo-classes are used in @sc{css} selectors to allow information
+terminal (vt100, etc.@:) or if
-external to the @sc{html} source (e.g. the fact that an anchor has been
+@code{w3-delimit-emphasis} is @code{t}.
-visited or not) to classify elements.
+* Graphics workstations::              Changing how a document is
-@item property
+displayed on a graphics terminal
-A stylistic parameter that can be influenced through @sc{css}.
+(Xwindows, Windows, NeXTstep,
-@item reader
+OS/2, etc.)
-The person for whom the document is rendered.
+* Inlined images::                     How to specify how Emacs-W3
-@item replaced element
+handles inlined images/mpegs.
-An element that the @sc{css} formatter only knows the intrinsic
+@end menu
-dimensions of. In @sc{html}, @sc{img}, @sc{input}, @sc{textarea},
+@end ifinfo
-@sc{select} and @sc{object} elements can be examples of replaced
+@node General Formatting, Character based terminals, Controlling Formatting, Controlling Formatting
-elements. E.g., the content of the @sc{img} element is often replaced by
+@section General formatting conventions
-the image that the @sc{src} attribute points to.  @sc{css1} does not
+@iftex
-define how the intrinsic dimensions are found.
+@heading Setting the fill column
-@item rule
+@end iftex
-A declaration (e.g. 'font-family: helvetica') and its selector
+@ifinfo
-(e.g. @sc{'H1'}).
+@center --------------------
-@item selector
+@center Setting the fill column
-A string that identifies what elements the corresponding rule applies
+@center --------------------
-to. A selector can either be a simple selector (e.g. 'H1') or a
+@end ifinfo
-contextual selector (e.g. @sc{'h1 b'}) which consists of several simple
+@vindex fill-column
-selectors.
+@vindex w3-right-border
-@item @sc{sgml}
+Each time a document is parsed, the @code{fill-column} is recalculated
-Standard Generalized Markup Language, of which @sc{html} is an
+using @code{window-width} and @code{w3-right-border}.
-application.
+@code{w3-right-border} is an integer specifying how much room at the
-@item simple selector
+right edge of the screen to leave blank.  The @code{fill-column} is set
-A selector that matches elements based on the element type and/or
+to @code{(- (window-width) @code{w3-right-border})}.
-attributes, and not the element's position in the document
+@iftex
-structure. E.g., 'H1.initial' is a simple selector.
+@heading Formatting of hypertext links
-@item style sheet
+@end iftex
-A collection of rules.
+@ifinfo
-@item @sc{ua}
+@center --------------------
-User Agent, often a web browser or web client.
+@center Formatting of hypertext links
-@item user
+@center --------------------
-Synonymous with reader.
+@end ifinfo
-@item weight
+@vindex w3-delimit-links
-The priority of a rule.
+@vindex w3-link-start-delimiter
-@end table
+@vindex w3-link-end-delimiter
+If the variable @code{w3-delimit-links} is non-@code{nil} (the default
-@node Basic Concepts, Pseudo-Classes/Elements, Terminology, Stylesheets
+for text-terminals), then hypertext links are surrounded by text
-@section Basic Concepts
+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
-Designing simple style sheets is easy. One needs only to know a little
+of a hypertext link.  These variables are cons-pairs of two
-HTML and some basic desktop publishing terminology. E.g., to set the
+strings.
-text color of 'H1' elements to blue, one can say:
+If a link has never been visited before (it is not in the @i{global
-@example
+history}), then the @code{car} of these variables is inserted at the
-H1 @{ color: blue @}
+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
-The example above is a simple CSS rule. A rule consists of two main
+@iftex
-parts: selector ('H1') and declaration ('color: blue'). The declaration
+@heading Formatting of lists
-has two parts: property ('color') and value ('blue'). While the example
+@end iftex
-above tries to influence only one of the properties needed for rendering
+@ifinfo
-an HTML document, it qualifies as a style sheet on its own. Combined
+@center --------------------
-with other style sheets (one fundamental feature of CSS is that style
+@center Formatting of lists
-sheets are combined) it will determine the final presentation of the
+@center --------------------
-document.
+@end ifinfo
+@cindex Indentation
-The selector is the link between the HTML document and the style sheet, and
+@vindex w3-indent-level
-all HTML element types are possible selectors.
+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
-@node Pseudo-Classes/Elements, The Cascade, Basic Concepts, Stylesheets
+the paragraphs in the document.  To control this, set the
-@section Pseudo-Classes/Elements
+variable @code{w3-indent-level}.  This is the number of spaces to
+indent lists and other items requiring special margins.
-In @sc{css1}, style is normally attached to an element based on its
-position in the document structure. This simple model is sufficient for
+@vindex w3-list-chars-assoc
-a wide variety of styles, but doesn't cover some common effects. The
+Another thing that is easy to change about lists is the bullet character
-concept of pseudo-classes and pseudo-elements extend addressing in
+put at the front of each list item.  This is controlled by the variable
-@sc{css1} to allow external information to influence the formatting
+@code{w3-list-chars-assoc}, which is an assoc list.  This is a list of
-process.
+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
-Pseudo-classes and pseudo-elements can be used in @sc{css} selectors,
+(@b{not} a string) representing the type of list (e.g., @samp{ul}).
-but do not exist in the @sc{html} source. Rather, they are "inserted" by
+The rest of the list should consist of strings to insert at certain
-the @sc{ua} under certain conditions to be used for addressing in style
+levels of lists.  The @code{n}th element of this list is used when the
-sheets. They are referred to as "classes" and "elements" since this is a
+list is nested @code{n + 1} levels.  If the list is not long enough to
-convenient way of describing their behavior. More specifically, their
+define a string for a certain nesting level, then it defaults to either
-behavior is defined by a fictional tag sequence.
+a '*' or a '.'.
+@iftex
-Pseudo-elements are used to address sub-parts of elements, while
+@heading Formatting of directory listings
-pseudo-classes allow style sheets to differentiate between different
+@end iftex
-element types.
+@ifinfo
+@center --------------------
-The only support pseudo-classes in Emacs/W3 are on the anchor tag
+@center Formatting of directory listings
-(<a>...</a>).
+@center --------------------
+@end ifinfo
-User agents commonly display newly visited anchors differently from
+@vindex url-use-hypertext-dired
-older ones. In @sc{css1}, this is handled through pseudo-classes on the
+When Emacs-W3 encounters a link to a directory (whether by local file access
-'A' element:
+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
-A:link @{ color: red @}       /* unvisited link */
+<embed href="somevideo.mpg" type="video/mpeg">
-A:visited @{ color: blue @}   /* visited links */
-A:active @{ color: lime @}    /* active links */
 @end example
-All 'A' elements with an 'HREF' attribute will be put into one and only
+@vindex w3-mpeg-args
-one of these groups (i.e. target anchors are not affected). UAs may
+@vindex w3-mpeg-program
-choose to move an element from 'visited' to 'link' after a certain
+This requires a special version of the standard @file{mpeg_play} mpeg
-time. An 'active' link is one that is currently being selected (e.g. by
+player.  Patches against the 2.0 version are available at
-a mouse button press) by the reader.
+ftp://ftp.cs.indiana.edu/pub/elisp/w3/mpeg_patch.  The variable
+@code{w3-mpeg-program} should point to this executable, and
-The formatting of an anchor pseudo-class is as if the class had been
+@code{w3-mpeg-args} should be a list of any additional arguments to be
-inserted manually. A @sc{ua} is not required to reformat a currently
+passed to the player.  By default, this includes @var{-loop}, so the
-displayed document due to anchor pseudo-class transitions. E.g., a style
+mpeg plays continuously.
-sheet can legally specify that the 'font-size' of an 'active' link
-should be larger that a 'visited' link, but the UA is not required to
+@cindex Delaying inlined images
-dynamically reformat the document when the reader selects the 'visited'
+@cindex Delaying inlined animations
-link.
+@vindex w3-delay-image-loads
+@vindex w3-delay-mpeg-loads
-Pseudo-class selectors do not match normal classes, and vice versa. The
+Because images and movies can take up an incredible amount of bandwidth,
-style rule in the example below will therefore not have any influence:
+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
-@example
+@code{w3-delay-image-loads} and @code{w3-delay-mpeg-loads} control this.
-A:link @{ color: red @}
+If set to non-@code{nil}, then the images or movies are not
+loaded until explicitly requested by the user.
-<A CLASS=link NAME=target5> ... </A>
-@end example
+@cindex Loading delayed images
+@cindex Loading delayed movies
-In @sc{css1}, anchor pseudo-classes have no effect on elements other
+@findex w3-load-delayed-images
-than 'A'. Therefore, the element type can be omitted from the selector:
+@findex w3-load-delayed-mpegs
+To load any delayed images, use the function
-@example
+@code{w3-load-delayed-images}.  Its counterpart for delayed movies is
-A:link @{ color: red @}
+@code{w3-load-delayed-mpegs}
-:link @{ color: red @}
-@end example
+@node MIME Support, Adding MIME types based on file extensions, , Top
-The two selectors above will select the same elements in CSS1.
-Pseudo-class names are case-insensitive.
-Pseudo-classes can be used in contextual selectors:
-@example
-A:link IMG @{ border: solid blue @}
-@end example
-Also, pseudo-classes can be combined with normal classes:
-@example
-A.external:visited @{ color: blue @}
-<A CLASS=external HREF="http://out.side/">external link</A>
-@end example
-If the link in the above example has been visited, it will be rendered
-in blue. Note that normal class names precede pseudo-classes in the
-selector.
-@node The Cascade, Properties, Pseudo-Classes/Elements, Stylesheets
-@section The Cascade
-In @sc{css}, more than one style sheet can influence the presentation
-simultaneously. There are two main reasons for this feature: modularity
-and author/reader balance.
-@table @i
-@item modularity
-A style sheet designer can combine several (partial) style sheets to
-reduce redundancy:
-@example
-@@import url(http://www.style.org/pastoral);
-@@import url(http://www.style.org/marine);
-H1 @{ color: red @}     /* override imported sheets */
-@end example
-@item author/reader balance
-Both readers and authors can influence the presentation through style
-sheets. To do so, they use the same style sheet language thus reflecting
-a fundamental feature of the web: everyone can become a publisher. The
-@sc{ua} is free to choose the mechanism for referencing personal style
-sheets.
-@end table
-Sometimes conflicts will arise between the style sheets that influence
-the presentation. Conflict resolution is based on each style rule having
-a weight. By default, the weights of the reader's rules are less than
-the weights of rules in the author's documents. I.e., if there are
-conflicts between the style sheets of an incoming document and the
-reader's personal sheets, the author's rules will be used. Both reader
-and author rules override the @sc{ua}'s default values.
-The imported style sheets also cascade with each other, in the order
-they are imported, according to the cascading rules defined below. Any
-rules specified in the style sheet itself override rules in imported
-style sheets. That is, imported style sheets are lower in the cascading
-order than rules in the style sheet itself. Imported style sheets can
-themselves import and override other style sheets, recursively.
-In @sc{css1}, all '@@import' statements must occur at the start of a
-style sheet, before any declarations. This makes it easy to see that
-rules in the style sheet itself override rules in the imported style
-sheets.
-NOTE: The use of !important in @sc{css} stylesheets is unsupported at
-this time.
-Conflicting rules are intrinsic to the CSS mechanism. To find the value
-for an element/property combination, the following algorithm must be
-followed:
-@enumerate
-@item
-Find all declarations that apply to the element/property in
-question. Declarations apply if the selector matches the element in
-question. If no declarations apply, the inherited value is used. If
-there is no inherited value (this is the case for the 'HTML' element and
-for properties that do not inherit), the initial value is used.
-@item
-Sort the declarations by explicit weight: declarations marked
-'!important' carry more weight than unmarked (normal) declarations.
-@item
-Sort by origin: the author's style sheets override the reader's style
-sheet which override the UA's default values. An imported style sheet
-has the same origin as the style sheet from which it is imported.
-@item
-Sort by specificity of selector: more specific selectors will override
-more general ones. To find the specificity, count the number of ID
-attributes in the selector (a), the number of CLASS attributes in the
-selector (b), and the number of tag names in the selector
-(c). Concatenating the three numbers (in a number system with a large
-base) gives the specificity. Some examples:
-@example
-LI            @{...@}  /* a=0 b=0 c=1 -> specificity =   1 */
-UL LI         @{...@}  /* a=0 b=0 c=2 -> specificity =   2 */
-UL OL LI      @{...@}  /* a=0 b=0 c=3 -> specificity =   3 */
-LI.red        @{...@}  /* a=0 b=1 c=1 -> specificity =  11 */
-UL OL LI.red  @{...@}  /* a=0 b=1 c=3 -> specificity =  13 */
-#x34y         @{...@}  /* a=1 b=0 c=0 -> specificity = 100 */
-@end example
-Pseudo-elements and pseudo-classes are counted as normal elements and
-classes, respectively.
-@item
-Sort by order specified: if two rules have the same weight, the latter
-specified wins. Rules in imported style sheets are considered to be
-before any rules in the style sheet itself.
-@end enumerate
-The search for the property value can be terminated whenever one rule
-has a higher weight than the other rules that apply to the same
-element/property combination.
-This strategy gives author's style sheets considerably higher weight
-than those of the reader. It is therefore important that the reader has
-the ability to turn off the influence of a certain style sheet,
-e.g. through a pull-down menu.
-A declaration in the 'STYLE' attribute of an element has the same weight
-as a declaration with an ID-based selector that is specified at the end
-of the style sheet:
-@example
-<STYLE TYPE="text/css">
-#x97z @{ color: blue @}
-</STYLE>
-<P ID=x97z STYLE="color: red">
-@end example
-In the above example, the color of the 'P' element would be
-red. Although the specificity is the same for both declarations, the
-declaration in the 'STYLE' attribute will override the one in the
-'STYLE' element because of cascading rule number 5.
-The @sc{ua} may choose to honor other stylistic @sc{html} attributes,
-for example 'ALIGN'. If so, these attributes are translated to the
-corresponding @sc{css} rules with specificity equal to 1. The rules are
-assumed to be at the start of the author style sheet and may be
-overridden by subsequent style sheet rules. In a transition phase, this
-policy will make it easier for stylistic attributes to coexist with
-style sheets.
-@node Properties, Units, The Cascade, Stylesheets
-@section Properties
-In the text below, the allowed values for each property are listed
-with a syntax like the following:
-@example
-Value: N | NW | NE
-Value: [ <length> | thick | thin ]@{1,4@}
-Value: <uri>? <color> [ / <color> ]?
-Value: <uri> || <color>
-@end example
-The words between < and > give a type of value. The most common types
-are <length>, <percentage>, <url>, <number>and <color> these are
-described in the section on [[units]]. The more specialized types
-(e.g. <font-family>and <border-style>) are described under the property
-where they appear.
-Other words are keywords that must appear literally, without quotes. The
-slash (/) and the comma (,) must also appear literally.
-Several things juxtaposed mean that all of them must occur, in the given
-order. A bar (|) separates alternatives: one of them must occur. A
-double bar (A || B) means that either A or B or both must occur, in any
-order. Brackets ([]) are for grouping. Juxtaposition is stronger than
-the double bar, and the double bar is stronger than the bar. Thus "a b |
-c || d e" is equivalent to "[ a b ] | [ c || [ d e ]]".
-Every type, keyword, or bracketed group may be followed by one of the
-following modifiers:
-@itemize @bullet
-@item
-An asterisk (*) indicates that the preceding type, word or group is
-repeated zero or more times.
-@item
-A plus (+) indicates that the preceding type, word or group is repeated
-one or more times.
-@item
-A question mark (?) indicates that the preceding type, word or group is
-optional.
-@item
-A pair of numbers in curly braces (@{A,B@}) indicates that the preceding
-type, word or group is repeated at least A and at most B times.
-@end itemize
-Other than the value the following information is also shown.
-@multitable @columnfractions .20 .8
-@item Supported Values: @tab If this is present, it lists the parts of
-the specification that Emacs/W3 currently supports.
-@item Unsupported Values: @tab If this is present, it represents the
-parts of the specifcation that Emacs/W3 does not support.
-@item Initial: @tab The default value for the property, unless
-explicitly set in a stylesheet.
-@item Applies to: @tab What type of elements this property can be attached to.
-@item Inherited: @tab Yes or no
-@item Percentage values: @tab What a percentage value applies to when given.
-@end multitable
-@menu
-* Font Properties::             Selecting fonts, styles, and sizes.
-* Colors and Backgrounds::      Controlling colors, front and back.
-* Text Properties::             Alignment, decoration, and more!
-* Box Properties::              Borders, padding, and margins, oh my!
-* Classification::              Changing whitespace and display policies.
-* Media Selection::             Conditionalize stylesheets on media-type.
-* Speech Properties::           Speech output controlled by stylesheets.
-@end menu
-@node Font Properties, Colors and Backgrounds, Properties, Properties
-@subsection Font Properties
-Setting font properties will be among the most common uses of style
-sheets.  Unfortunately, there exists no well-defined and universally
-accepted taxonomy for classifying fonts, and terms that apply to one
-font family may not be appropriate for others. E.g. 'italic' is commonly
-used to label slanted text, but slanted text may also be labeled as
-being @b{Oblique}, @b{Slanted}, @b{Incline}, @b{Cursive} or
-@b{Kursiv}. Therefore it is not a simple problem to map typical font
-selection properties to a specific font.
-The properties defined by CSS1 are described in the following sections.
-@menu
-* font-family::                 Groups of fonts.
-* font-style::                  Normal, italic, or oblique?
-* font-variant::                Small-caps, etc.
-* font-weight::                 How bold can you go?
-* font-size::                   How big is yours?
-* font::                        Shorthand for all of the above.
-@end menu
-@node font-family, font-style, Font Properties, Font Properties
-@subsubsection font-family
-@multitable @columnfractions .20 .8
-@item Supported Values: @tab [[<family-name> | <generic-family>],]* [<family-name> | <generic-family>]
-@item Initial: @tab User specific
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The value is a prioritized list of font family names and/or generic
-family names. Unlike most other CSS1 properties, values are separated
-by a comma to indicate that they are alternatives:
-@example
-BODY @{ font-family: gill, helvetica, sans-serif @}
-@end example
-There are two types of list values:
-@table @b
-@item <family-name>
-The name of a font family of choice. In the last example, "gill" and
-"helvetica" are font families.
-@item <generic-family>
-In the example above, the last value is a generic family name. The
-following generic families are defined:
-@itemize @bullet
-@item
-'serif' (e.g. Times)
-@item
-'sans-serif' (e.g. Helvetica)
-@item
-'cursive' (e.g. Zapf-Chancery)
-@item
-'fantasy' (e.g. Western)
-@item
-'monospace' (e.g. Courier)
-@end itemize
-@end table
-Style sheet designers are encouraged to offer a generic font family as a
-last alternative.
-Font names containing whitespace should be quoted:
-@example
-BODY @{ font-family: "new century schoolbook", serif @}
-<BODY STYLE="font-family: 'My own font', fantasy">
-@end example
-If quoting is omitted, any whitespace characters before and after the
-font name are ignored and any sequence of whitespace characters inside
-the font name is converted to a single space.
-@node font-style, font-variant, font-family, Font Properties
-@subsubsection font-style
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab normal | italic | oblique
-@item Initial: @tab normal
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The 'font-style' property selects between normal (sometimes referred to
-as "roman" or "upright"), italic and oblique faces within a font family.
-A value of 'normal' selects a font that is classified as 'normal' in the
-UA's font database, while 'oblique' selects a font that is labeled
-'oblique'. A value of 'italic' selects a font that is labeled 'italic',
-or, if that is not available, one labeled 'oblique'.
-The font that is labeled 'oblique' in the UA's font database may
-actually have been generated by electronically slanting a normal font.
-Fonts with Oblique, Slanted or Incline in their names will typically be
-labeled 'oblique' in the UA's font database. Fonts with Italic, Cursive
-or Kursiv in their names will typically be labeled 'italic'.
-@example
-H1, H2, H3 @{ font-style: italic @}
-H1 EM @{ font-style: normal @}
-@end example
-In the example above, emphasized text within 'H1' will appear in a
-normal face.
-@node font-variant, font-weight, font-style, Font Properties
-@subsubsection font-variant
-@multitable @columnfractions .2 .8
-@item Value:             @tab normal | small-caps
-@item Initial:           @tab normal
-@item Applies to:        @tab all elements
-@item Inherited:         @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-Another type of variation within a font family is the small-caps. In a
-small-caps font the lower case letters look similar to the uppercase
-ones, but in a smaller size and with slightly different proportions. The
-'font-variant' property selects that font.
-A value of 'normal' selects a font that is not a small-caps font,
-'small-caps' selects a small-caps font. It is acceptable (but not
-required) in CSS1 if the small-caps font is a created by taking a normal
-font and replacing the lower case letters by scaled uppercase
-characters. As a last resort, uppercase letters will be used as
-replacement for a small-caps font.
-The following example results in an 'H3' element in small-caps, with
-emphasized words in oblique small-caps:
-@example
-H3 @{ font-variant: small-caps @}
-EM @{ font-style: oblique @}
-@end example
-There may be other variants in the font family as well, such as fonts
-with old-style numerals, small-caps numerals, condensed or expanded
-letters, etc. CSS1 has no properties that select those.
-@node font-weight, font-size, font-variant, Font Properties
-@subsubsection font-weight
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
-@item Unsupported Values: @tab bolder | lighter
-@item Initial: @tab normal
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The 'font-weight' property selects the weight of the font. The values
-'100' to '900' form an ordered sequence, where each number indicates a
-weight that is at least as dark as its predecessor. The keyword 'normal'
-is synonymous with '400', and 'bold' is synonymous with '700'. Keywords
-other than 'normal' and 'bold' have been shown to be often confused with
-font names and a numerical scale was therefore chosen for the 9-value
-list.
-@example
-P @{ font-weight: normal @}   /* 400 */
-H1 @{ font-weight: 700 @}     /* bold */
-@end example
-The 'bolder' and 'lighter' values select font weights that are relative
-to the weight inherited from the parent:
-@example
-STRONG @{ font-weight: bolder @}
-@end example
-There is no guarantee that there will be a darker face for each of the
-'font-weight' values; for example, some fonts may have only a normal and
-a bold face, others may have eight different face weights. There is no
-guarantee on how a UA will map font faces within a family to weight
-values. The only guarantee is that a face of a given value will be no
-less dark than the faces of lighter values.
-@node font-size, font, font-weight, Font Properties
-@subsubsection font-size
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab <absolute-size> | <length>
-@item Unsupported Values: @tab <percentage> | <relative-size>
-@item Initial: @tab medium
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab relative to parent element's font size
-@end multitable
-@table @b
-@item <absolute-size>
-An <absolute-size> keyword is an index to a table of font sizes computed
-and kept by the UA. Possible values are:
-@itemize @bullet
-@item
-xx-small
-@item
-x-small
-@item
-small
-@item
-medium
-@item
-large
-@item
-x-large
-@item
-xx-large
-@end itemize
-On a computer screen a scaling factor of 1.5 is suggested between
-adjacent indexes; if the 'medium' font is 10pt, the 'large' font could
-be 15pt. Different media may need different scaling factors. Also, the
-UA should take the quality and availability of fonts into account when
-computing the table. The table may be different from one font family to
-another.
-@item <relative-size>
-A <relative-size> keyword is interpreted relative to the table of font
-sizes and the font size of the parent element. Possible values are
-@b{larger} or @b{smaller}. For example, if the parent element has a font
-size of 'medium', a value of 'larger' will make the font size of the
-current element be 'large'. If the parent element's size is not close to
-a table entry, the UA is free to interpolate between table entries or
-round off to the closest one. The UA may have to extrapolate table
-values if the numerical value goes beyond the keywords.
-@end table
-Length and percentage values should not take the font size table into
-account when calculating the font size of the element.
-Negative values are not allowed.
-On all other properties, 'em' and 'ex' length values refer to the font
-size of the current element. On the 'font-size' property, these length
-units refer to the font size of the parent element.
-Note that an application may reinterpret an explicit size, depending on
-the context. E.g., inside a VR scene a font may get a different size
-because of perspective distortion.
-Examples:
-@example
-P @{ font-size: 12pt; @}
-BLOCKQUOTE @{ font-size: larger @}
-EM @{ font-size: 150% @}
-EM @{ font-size: 1.5em @}
-@end example
-If the suggested scaling factor of 1.5 is used, the last three
-declarations are identical.
-@node font,  , font-size, Font Properties
-@subsubsection font
-@multitable @columnfractions .2 .8
-@item Value: @tab [ <font-style> || <font-variant> || <font-weight> ]? <font-size> [ / <line-height> ]? <font-family>
-@item Initial: @tab not defined for shorthand properties
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab allowed on <font-size> and <line-height>
-@end multitable
-The 'font' property is a shorthand property for setting 'font-style'
-'font-variant' 'font-weight' 'font-size', 'line-height' and
-'font-family' at the same place in the style sheet. The syntax of this
-property is based on a traditional typographical shorthand notation to
-set multiple properties related to fonts.
-For a definition of allowed and initial values, see the previously
-defined properties. Properties for which no values are given are set to
-their initial value.
-@example
-P @{ font: 12pt/14pt sans-serif @}
-P @{ font: 80% sans-serif @}
-P @{ font: x-large/110% "new century schoolbook", serif @}
-P @{ font: bold italic large Palatino, serif @}
-P @{ font: normal small-caps 120%/120% fantasy @}
-@end example
-In the second rule, the font size percentage value ('80%') refers to the
-font size of the parent element. In the third rule, the line height
-percentage refers to the font size of the element itself.
-In the first three rules above, the 'font-style', 'font-variant' and
-'font-weight' are not explicitly mentioned, which means they are all
-three set to their initial value ('normal'). The fourth rule sets the
-'font-weight' to 'bold', the 'font-style' to 'italic' and implicitly
-sets 'font-variant' to 'normal'.
-The fifth rule sets the 'font-variant' ('small-caps'), the 'font-size'
-(120% of the parent's font), the 'line-height' (120% times the font
-size) and the 'font-family' ('fantasy'). It follows that the keyword
-'normal' applies to the two remaining properties: 'font-style' and
-'font-weight'.
-@node Colors and Backgrounds, Text Properties, Font Properties, Properties
-@subsection Colors and Backgrounds
-These properties describe the color (often called foreground color) and
-background of an element (i.e. the surface onto which the content is
-rendered). One can set a background color and/or a background image. The
-position of the image, if/how it is repeated, and whether it is fixed or
-scrolled relative to the canvas can also be set.
-The 'color' property inherits normally. The background properties do not
-inherit, but the parent element's background will shine through by
-default because of the initial 'transparent' value on
-'background-color'.
-NOTE: Currently, Emacs/W3 can only show background images under XEmacs.
-Emacs 19 doesn't have the support in its display code yet.
-@menu
-* color::                       Foreground colors.
-* background-color::            Background colors.
-* background-image::            Background images.
-* background-repeat::           Controlling repeating of background images.
-* background-attachment::       Where background images are drawn.
-* background-position::         Where background images are drawn.
-* background::                  Shorthand for all background properties.
-@end menu
-@node color, background-color, Colors and Backgrounds, Colors and Backgrounds
-@subsubsection color
-@multitable @columnfractions .2 .8
-@item Value: @tab <color>
-@item Initial: @tab User specific
-@item Applies to: @tab  all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-This property describes the text color of  an element (often referred to
-as the foreground color). There are different ways to specify red:
-@example
-EM @{ color: red @}              /* natural language */
-EM @{ color: rgb(255,0,0) @}     /* RGB range 0-255   */
-@end example
-See @ref{Color Units} for a description of possible color values.
-@node background-color, background-image, color, Colors and Backgrounds
-@subsubsection background-color
-@multitable @columnfractions .2 .8
-@item Value: @tab <color> | transparent
-@item Initial: @tab transparent
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab N/A
-@end multitable
-This property sets the background color of an element.
-@example
-H1 @{ background-color: #F00 @}
-@end example
-@node background-image, background-repeat, background-color, Colors and Backgrounds
-@subsubsection background-image
-@multitable @columnfractions .2 .8
-@item Value: @tab <url> | none
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab N/A
-@end multitable
-This property sets the background image of an element. When setting a
-background image, one should also set a background color that will be
-used when the image is unavailable. When the image is available, it is
-overlaid on top of the background color.
-@example
-BODY @{ background-image: url(marble.png) @}
-P @{ background-image: none @}
-@end example
-@node background-repeat, background-attachment, background-image, Colors and Backgrounds
-@subsubsection background-repeat
-This property is not supported at all under Emacs/W3.
-@node background-attachment, background-position, background-repeat, Colors and Backgrounds
-@subsubsection background-attachment
-This property is not supported at all under Emacs/W3.
-@node background-position, background, background-attachment, Colors and Backgrounds
-@subsubsection background-position
-This property is not supported at all under Emacs/W3.
-@node background,  , background-position, Colors and Backgrounds
-@subsubsection background
-@multitable @columnfractions .2 .8
-@item Value: @tab <background-color> || <background-image> || <background-repeat> || <background-attachment> || <background-position>
-@item Initial: @tab not defined for shorthand properties
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab allowed on <background-position>
-@end multitable
-The 'background' property is a shorthand property for setting the
-individual background properties (i.e., 'background-color',
-'background-image', 'background-repeat', 'background-attachment' and
-'background-position') at the same place in the style sheet.
-Possible values on the 'background' properties are the set of all
-possible values on the individual properties.
-@example
-BODY @{ background: red @}
-P @{ background: url(chess.png) gray 50% repeat fixed @}
-@end example
-The 'background' property always sets all the individual background
-properties. In the first rule of the above example, only a value for
-'background-color' has been given and the other individual properties
-are set to their initial value. In the second rule, all individual
-properties have been specified.
-@node Text Properties, Box Properties, Colors and Backgrounds, Properties
-@subsection Text Properties
-@menu
-* word-spacing::
-* letter-spacing::
-* text-decoration::
-* vertical-align::
-* text-transform::
-* text-align::
-* text-indent::
-* line-height::
-@end menu
-@node word-spacing, letter-spacing, Text Properties, Text Properties
-@subsubsection word-spacing
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab normal
-@item Unsupported Values: @tab <length>
-@item Initial: @tab normal
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The length unit indicates an addition to the default space between
-words. Values can be negative, but there may be implementation-specific
-limits. The UA is free to select the exact spacing algorithm. The word
-spacing may also be influenced by justification (which is a value of the
-'align' property).
-@example
-H1 @{ word-spacing: 0.4em @}
-@end example
-Here, the word-spacing between each word in 'H1' elements would be
-increased by '1em'.
-NOTE: Emacs/W3 cannot currently support this, due to limitations in
-Emacs.  It may  be implemented in the future.
-@node letter-spacing, text-decoration, word-spacing, Text Properties
-@subsubsection letter-spacing
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab normal
-@item Unsupported Values: @tab <length>
-@item Initial: @tab normal
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The length unit indicates an addition to the default space between
-characters. Values can be negative, but there may be
-implementation-specific limits. The UA is free to select the exact
-spacing algorithm. The letter spacing may also be influenced by
-justification (which is a value of the 'align' property).
-@example
-BLOCKQUOTE @{ letter-spacing: 0.1em @}
-@end example
-Here, the letter-spacing between each character in 'BLOCKQUOTE' elements
-would be increased by '0.1em'.
-NOTE: Emacs/W3 cannot currently support this, due to limitations in
-Emacs.  It may be implemented in the future.
-@node text-decoration, vertical-align, letter-spacing, Text Properties
-@subsubsection text-decoration
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab none | underline | line-through | blink
-@item Unsupported Values: @tab overline
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab no, but see clarification below
-@item Percentage values: @tab N/A
-@end multitable
-This property describes decorations that are added to the text of an
-element. If the element has no text (e.g. the 'IMG' element in HTML) or
-is an empty element (e.g. '<EM></EM>'), this property has no effect. A
-value of 'blink' causes the text to blink.
-The color(s) required for the text decoration should be derived from the
-'color' property value.
-This property is not inherited, but elements should match their
-parent. E.g., if an element is underlined, the line should span the
-child elements. The color of the underlining will remain the same even
-if descendant elements have different 'color' values.
-@example
-A:link, A:visited, A:active @{ text-decoration: underline @}
-@end example
-The example above would underline the text of all links (i.e., all 'A'
-elements with a 'HREF' attribute).
-NOTE: The 'line-through' property is only supported under XEmacs
-currently.  A patch has been sent to the Emacs maintainers to add
-support for this, but it has not made it into the main distribution
-yet.
-@node vertical-align, text-transform, text-decoration, Text Properties
-@subsubsection vertical-align
-This is currently unsupported in Emacs/W3.
-@node text-transform, text-align, vertical-align, Text Properties
-@subsubsection text-transform
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab none
-@item Unsupported Values: @tab capitalize | uppercase | lowercase
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-@table @b
-@item 'capitalize'
-Uppercases the first character of each word.
-@item 'uppercase'
-Uppercases all letters of the element.
-@item 'lowercase'
-Lowercases all letters of the element.
-@item 'none'
-Neutralizes inherited value.
-@end table
-The actual transformation in each case is human language dependent.
-@example
-H1 @{ text-transform: uppercase @}
-@end example
-The example above would put 'H1' elements in uppercase text.
-NOTE: This capability was in the previous version of Emacs/W3, but has
-not been reimplemented in the new display code yet.  Please feel free to
-send me patches.
-@node text-align, text-indent, text-transform, Text Properties
-@subsubsection text-align
-@multitable @columnfractions .2 .8
-@item Value: @tab left | right | center | justify
-@item Initial: @tab User specific
-@item Applies to: @tab block-level elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-This property describes how text is aligned within the element. The
-actual justification algorithm used is UA and human language dependent.
-Example:
-@example
-DIV.center @{ text-align: center @}
-@end example
-Since 'text-align' inherits, all block-level elements inside the 'DIV'
-element with 'CLASS=center' will be centered. Note that alignments are
-relative to the width of the element, not the canvas.
-@node text-indent, line-height, text-align, Text Properties
-@subsubsection text-indent
-Not currently implemented in Emacs/W3.
-@node line-height,  , text-indent, Text Properties
-@subsubsection line-height
-Not currently implemented in Emacs/W3.
-@node Box Properties, Classification, Text Properties, Properties
-@subsection Box Properties
-@multitable @columnfractions .2 .8
-@end multitable
-@node Classification, Media Selection, Box Properties, Properties
-@subsection Classification
-These properties classify elements into categories more than they set
-specific visual parameters.
-The list-style properties describe how list items (i.e. elements with a
-'display' value of 'list-item') are formatted. The list-style properties
-can be set on any element, and it will inherit normally down the
-tree. However, they will only be have effect on elements with a
-'display' value of 'list-item'. In HTML this is typically the case for
-the 'LI' element.
-@menu
-* display::
-* white-space::
-* list-style-type::
-* list-style-image::
-* list-style-position::
-* list-style::
-@end menu
-@node display, white-space, Classification, Classification
-@subsubsection display
-@multitable @columnfractions .2 .8
-@item Value: @tab block | inline | list-item | none
-@item Extensions: @tab line
-@item Initial: @tab inline
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab N/A
-@end multitable
-This property describes how/if an element is displayed on the canvas
-(which may be on a printed page, a computer display etc.).
-An element with a 'display' value of 'block' opens whitespace suitable
-for a paragraph break.  Typically, elements like 'H1' and 'P' are of
-type 'block'. A value of 'list-item' is similar to 'block' except that a
-list-item marker is added. In HTML, 'LI' will typically have this value.
-An element with a 'display' value of 'inline' results in a new inline
-box on the same line as the previous content.
-A value of 'none' turns off the display of the element, including
-children elements and the surrounding box.
-@example
-P @{ display: block @}
-EM @{ display: inline @}
-LI @{ display: list-item @}
-IMG @{ display: none @}
-@end example
-The last rule turns off the display of images.
-A value of 'line' results in a single line break.  Emacs/W3 needs this
-extension to be able to fully specify the behaviour of @sc{br} and
-@sc{hr} elements within a stylesheet.
-NOTE: Emacs/W3 defaults to using 'inline' for this property, which is a
-slight deviation from the specification.
-@node white-space, list-style-type, display, Classification
-@subsubsection white-space
-@multitable @columnfractions .2 .8
-@item Value: @tab normal | pre | nowrap
-@item Initial: @tab normal
-@item Applies to: @tab block-level elements
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-This property declares how whitespace inside the element is handled: the
-'normal' way (where whitespace is collapsed), as 'pre' (which behaves
-like the 'PRE' element in HTML) or as 'nowrap' (where wrapping is done
-only through BR elements):
-@example
-PRE @{ white-space: pre @}
-P   @{ white-space: normal @}
-@end example
-@node list-style-type, list-style-image, white-space, Classification
-@subsubsection list-style-type
-@multitable @columnfractions .2 .8
-@item Value: @tab disc | circle | square | decimal | lower-roman | upper-roman | lower-alpha | upper-alpha | none
-@item Initial: @tab disc
-@item Applies to: @tab elements with 'display' value 'list-item'
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-This property is used to determine the appearance of the list-item
-marker if 'list-style-image' is 'none' or if the image pointed to by the
-URL cannot be displayed.
-Fo example:
-@example
-OL @{ list-style-type: decimal @}       /* 1 2 3 4 5 etc. */
-OL @{ list-style-type: lower-alpha @}   /* a b c d e etc. */
-OL @{ list-style-type: lower-roman @}   /* i ii iii iv v etc. */
-@end example
-@node list-style-image, list-style-position, list-style-type, Classification
-@subsubsection list-style-image
-@multitable @columnfractions .2 .8
-@item Value: @tab <url> | none
-@item Initial: @tab none
-@item Applies to: @tab elements with 'display' value 'list-item'
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-This property sets the image that will be used as the list-item
-marker. When the image is available it will replace the marker set with
-the 'list-style-type' marker.
-NOTE: This is currently unimplemented in Emacs/W3.
-@example
-UL @{ list-style-image: url(http://png.com/ellipse.png) @}
-@end example
-@node list-style-position, list-style, list-style-image, Classification
-@subsubsection list-style-position
-@multitable @columnfractions .2 .8
-@item Supported Values: @tab outside
-@item Unsupported Values: @tab inside
-@item Initial: @tab outside
-@item Applies to: @tab elements with 'display' value 'list-item'
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The value of 'list-style-position' determines how the list-item marker
-is drawn with regard to the content. For a formatting example see
-section 4.1.3.
-@node list-style,  , list-style-position, Classification
-@subsubsection list-style
-@multitable @columnfractions .2 .8
-@item Value: @tab <keyword> || <position> || <url>
-@item Initial: @tab not defined for shorthand properties
-@item Applies to: @tab elements with 'display' value 'list-item'
-@item Inherited: @tab yes
-@item Percentage values: @tab N/A
-@end multitable
-The 'list-style' property is a shorthand notation for setting the three
-properties 'list-style-type', 'list-style-image' and
-'list-style-position' at the same place in the style sheet.
-@example
-UL @{ list-style: upper-roman inside @}
-UL UL @{ list-style: circle outside @}
-LI.square @{ list-style: square @}
-@end example
-Setting 'list-style' directly on 'LI' elements can have unexpected
-results. Consider:
-@example
-<STYLE TYPE="text/css">
-OL.alpha LI  @{ list-style: lower-alpha @}
-UL LI        @{ list-style: disc @}
-</STYLE>
-<BODY>
-<OL CLASS=alpha>
-<LI>level 1
-<UL>
-<LI>level 2
-</UL>
-</OL>
-</BODY>
-@end example
-Since the specificity (as defined in the cascading order) is higher for
-the first rule in the style sheet in the example above, it will override
-the second rule on all 'LI' elements and only 'lower-alpha' list styles
-will be used. It is therefore recommended to set 'list-style' only on
-the list type elements:
-@example
-OL.alpha  @{ list-style: lower-alpha @}
-UL        @{ list-style: disc @}
-@end example
-In the above example, inheritance will transfer the 'list-style' values
-from 'OL' and 'UL' elements to 'LI' elements.
-A URL value can be combined with any other value:
-@example
-UL @{ list-style: url(http://png.com/ellipse.png) disc @}
-@end example
-In the example above, the 'disc' will be used when the image is
-unavailable.
-@node Media Selection, Speech Properties, Classification, Properties
-@subsection Media Selection
-To specify that a stylesheet declaration should only apply when using a
-certain media type (ie: different font families preferred when printing
-versus on-screen presentation), the declarations should be wrapped in
-the proposed @b{@@media} directive.
-The @@media directive takes two arguments, the media type, and a block
-of style declarations.
-@example
-@@media print @{
-BODY @{ font-size: 10pt @}
-H1 @{ font-size: 14pt @}
-@}
-@end example
-The '@@media' construct also allows to put include style sheet rules
-for various media in the same style sheet:
-@example
-@@media print @{
-BODY @{ font-size: 10pt @}
-@}
-@@media screen @{
-BODY @{ font-size: 12pt @}
-@}
-@end example
-Currently, the following media types are defined.
-@table @b
-@item Print
-Output for paged opaque material, and for documents viewed on screen in
-print preview mode.
-@item Screen
-A continuous presentation for computer screens.
-@item Projector
-Paged presentation for projected presentations.
-@item Braille
-For braille tactile feedback devices.
-@item Speech
-Aural presentation.
-@item Emacs
-The stylesheet will only be applied if the user is running in Emacs 19.
-@item XEmacs
-The stylesheet will only be applied if the user is running in XEmacs 19.
-@item All
-The default value, the style sheet applies to all output devices
-@end table
-@node Speech Properties,  , Media Selection, Properties
-@subsection Speech Properties
-Those of us who are sighted are accustomed to visual presentation of
-@sc{html} documents, frequently on a bitmapped display. This is not the
-only possible presentation method, however. Aural presentation, using a
-combination of speech synthesis and 'audio icons', provides an
-alternative presentation. This form of presentation is in current use by
-the blind and print-impaired communities.
-Often such aural presentation occurs by converting the document to plain
-text and feeding this to a 'screen reader' -- software or hardware that
-simply reads all the characters on the screen. This results in less
-effective presentation than would be the case if the document structure
-were retained.
-There are other large markets for aural presentation, including in-car
-and home entertainment use; aurual or mixed aural/visual presentation is
-thus likely to increase in importance over the next few years. Realizing
-that that the aural rendering is essentially independent of the visual
-rendering:
-@itemize @bullet
-@item
-Allows orthogonal aural and visual views.
-@item
-Allows browsers to optionally implement both aural and visual views to
-produce truly multimodal documents.
-@end itemize
-@menu
-* volume::
-* pause-before::
-* pause-after::
-* pause::
-* cue-before::
-* cue-after::
-* cue::
-* play-during::
-* speed::
-* voice-family::
-* pitch::
-* pitch-range::
-* stress::
-* richness::
-* speak-punctuation::
-* speak-date::
-* speak-numeral::
-* speak-time::
-@end menu
-@node volume, pause-before, Speech Properties, Speech Properties
-@subsubsection volume
-@multitable @columnfractions .2 .8
-@item Value: @tab <percentage> | mute | x-soft | soft | medium | loud | x-loud
-@item Initial: @tab medium
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@item Percentage values: @tab relative to user-specified mapping
-@end multitable
-The legal range of percentage values is 0% to 100%. There is a fixed
-mapping between keyword values and percentages:
-@itemize @bullet
-@item
-'x-soft' = '0%'
-@item
-'soft' = '25%'
-@item
-'medium' = '50%'
-@item
-'loud' = '75%'
-@item
-'x-loud' = '100%'
-@end itemize
-Volume refers to the median volume of the waveform. In other words, a
-highly inflected voice at a volume of 50 might peak well above
-that. Note that '0%' does not mean the same as "mute". 0% represents the
-minimum audible volume level and 100% corresponds to the maximum
-comfortable level. The UA should allow the values corresponding to 0%
-and 100% to be set by the user. Suitable values depend on the equipment
-in use (speakers, headphones), the environment (in car, home theater,
-library) and personal preferences. Some examples:
-@itemize @bullet
-@item
-A browser for in-car use has a setting for when there is lots of
-background noise . 0% would map to a fairly high level and 100% to a
-quite high level. The overall values are likely to be human adjustable
-for comfort, for example with a physical volume control: what this
-proposal does is adjust the dynamic range.
-@item
-Another speech browser is being used in the home, late at night, (don't
-annoy the neighbors) or in a shared study room. 0% is set to very quiet
-and 100% to a fairly quiet level, too. As with the first example, there
-is a low slope; the dynamic range is reduced. The actual volumes are low
-here, wheras they were high in the first example.
-@item
-In a quiet and isolated house, an expensive hifi home theatre setup. 0%
-is set fairly low and 100% to quite high; there is wide dynamic range.
-@end itemize
-The same authors stylesheet could be used in all cases, simply by
-mapping the 0 and 100 points suitably at the client side.
-@node pause-before, pause-after, volume, Speech Properties
-@subsubsection pause-before
-@multitable @columnfractions .2 .8
-@item Value: @tab <time> | <percentage>
-@item Initial: @tab UA specific
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab speed
-@end multitable
-This property specifies the pause before elements. It may be given in an
-absolute units (seconds, milliseconds) or as a relative value in which
-case it is relative to the reciprocal of the 'speed' property: if speed
-is 120 words per minute (ie a word takes half a second -- 500
-milliseconds) then a pause-before of 100% means a pause of 500 ms and a
-pause-before of 20% means 100ms.
-Using relative units gives more robust stylesheets in the face of large
-changes in speed.
-@node pause-after, pause, pause-before, Speech Properties
-@subsubsection pause-after
-@multitable @columnfractions .2 .8
-@item Value: @tab <time> | <percentage>
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab speed
-@end multitable
-This property specifies the pause after elements. Values are specified
-the same way as 'pause-before'.
-@node pause, cue-before, pause-after, Speech Properties
-@subsubsection pause
-@multitable @columnfractions .2 .8
-@item Value: @tab [<time> | <percentage> ]@{1,2@};
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@item Percentage values: @tab speed
-@end multitable
-The 'pause' property is a shorthand for setting 'pause-before' and
-'pause-after'. The first value is pause-before and the second is
-pause-after. If only one value is given, it applies to both properties.
-Examples:
-@example
-H1 @{ pause: 20ms @}       /* pause-before: 20ms; pause-after: 20ms */
-H2 @{ pause: 30ms 40ms @}  /* pause-before: 30ms; pause-after: 40ms */
-H3 @{ pause-after: 10ms @} /* pause-before: ?;    pause-after: 10ms */
-@end example
-@node cue-before, cue-after, pause, Speech Properties
-@subsubsection cue-before
-@multitable @columnfractions .2 .8
-@item Value: @tab <url> | none
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@end multitable
-Auditory icons are another way to distinguish semantic elements. Sounds
-may be played before, and/or after the element to delimit it. The same
-sound can be used both before and after, using the cue property.
-Examples:
-@example
-A  @{ cue-before: url(bell.aiff); cue-after: url(dong.wav) @}
-H1 @{ cue-before: url(pop.au); cue-after: url(pop.au) @}
-H1 @{ cue: url(pop.au) @}  /* same as previous */
-@end example
-@node cue-after, cue, cue-before, Speech Properties
-@subsubsection cue-after
-@xref{cue-before}
-@node cue, play-during, cue-after, Speech Properties
-@subsubsection cue
-@xref{cue-before}
-@node play-during, speed, cue, Speech Properties
-@subsubsection cue-during
-@multitable @columnfractions .2 .8
-@item Value: @tab <url> | mix | none
-@item Initial: @tab mix
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@end multitable
-Similar to the cue-before and cue-after properties, this indicates sound
-to be played during an element as a background (ie the sound is mixed in
-with the speech).
-Examples:
-@example
-BLOCKQUOTE.sad @{ cue-during: url(violins.aiff) @}
-@end example
-@node speed, voice-family, play-during, Speech Properties
-@subsubsection speed
-@multitable @columnfractions .2 .8
-@item Value: @tab <words-per-minute> | x-slow | slow | medium | fast | x-fast | faster | slower
-@item Initial: @tab medium
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-Specifies the speaking rate. Note that both absolute and relative
-keyword values are allowed (compare with @ref{font-weight}).
-@node voice-family, pitch, speed, Speech Properties
-@subsubsection voice-family
-@multitable @columnfractions .2 .8
-@item Value: @tab [[<specific-voice> | <generic-voice>],]* [<specific-voice> | <generic-voice>]
-@item Initial: @tab device-specific
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-The value is a prioritized list of voice family names. Generic families
-are male, female, and child.
-Examples of specific voice families are: comedian, paul, lisa
-Examples
-@example
-H1 @{ voice-family: announcer, male @}
-P.part.romeo @{ voice-family: romeo, male @}
-P.part.juliet @{ voice-family: juliet, female @}
-@end example
-@node pitch, pitch-range, voice-family, Speech Properties
-@subsubsection pitch
-@multitable @columnfractions .2 .8
-@end multitable
-@node pitch-range, stress, pitch, Speech Properties
-@subsubsection pitch-range
-@multitable @columnfractions .2 .8
-@end multitable
-@node stress, richness, pitch-range, Speech Properties
-@subsubsection stress
-@multitable @columnfractions .2 .8
-@item Value: @tab <percentage>
-@item Initial: @tab medium
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-Specifies the level of stress (assertiveness or emphasis) of the
-speaking voice. English is a stressed language, and different parts of a
-sentence are assigned primary, secondary or tertiary stress. The value
-of property 'stress' controls the amount of inflection that results from
-these stress markers.
-Increasing the value of this property results in the speech being more
-strongly inflected. It is in a sense dual to property 'pitch-range' and
-is provided to allow developers to exploit higher-end auditory displays.
-@node richness, speak-punctuation, stress, Speech Properties
-@subsubsection richness
-@multitable @columnfractions .2 .8
-@item Value: @tab <percentage>
-@item Initial: @tab medium (50%)
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-Specifies the richness (brightness) of the speaking voice. Different
-speech devices may require the setting of one or more device-specific
-parameters to achieve this effect.
-The effect of increasing richness is to produce a voice that carries --
-reducing richness produces a soft, mellifluous voice.
-@node speak-punctuation, speak-date, richness, Speech Properties
-@subsubsection speak-punctuation
-@multitable @columnfractions .2 .8
-@item Value: @tab code | none
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-'code' indicates that punctuation such as semicolons, braces, and so on
-are to be spoken literally. The default value of 'none' means that
-punctuation is not spoken but instead is rendered naturally as various
-pauses.
-@node speak-date, speak-numeral, speak-punctuation, Speech Properties
-@subsubsection speak-date
-@multitable @columnfractions .2 .8
-@item Value: @tab myd | dmy | ymd | none
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab no
-@end multitable
-This is a hint that the element contains a date and also how that date
-should be spoken. month-day-year is common in the USA, while
-day-month-year is common in Europe and year-month-day is also used.
-This should really be an HTML tag not a stylesheet property, since it
-gives semantic information about the content.
-@node speak-numeral, speak-time, speak-date, Speech Properties
-@subsubsection speak-numeral
-@multitable @columnfractions .2 .8
-@item Value: @tab digits | continous
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-@node speak-time,  , speak-numeral, Speech Properties
-@subsubsection speak-time
-@multitable @columnfractions .2 .8
-@item Value: @tab 24 | 12 | none
-@item Initial: @tab none
-@item Applies to: @tab all elements
-@item Inherited: @tab yes
-@end multitable
-@node Units,  , Properties, Stylesheets
-@section Units
-@menu
-* Length Units::
-* Percentage Units::
-* Color Units::
-* URLs::
-* Angle Units::
-* Time Units::
-@end menu
-@node Length Units, Percentage Units, Units, Units
-@subsection Length Units
-@node Percentage Units, Color Units, Length Units, Units
-@subsection Percentage Units
-@node Color Units, URLs, Percentage Units, Units
-@subsection color Units
-@node URLs, Angle Units, Color Units, Units
-@subsection URLs
-@node Angle Units, Time Units, URLs, Units
-@subsection Angle Units
-These are the legal angle units:
-@itemize @bullet
-@item
-deg: degrees
-@item
-grad
-@item
-rad: radians
-@end itemize
-@node Time Units,  , Angle Units, Units
-@subsection Time Units
-These are the legal time units:
-@itemize @bullet
-@item
-ms: milliseconds
-@item
-s: seconds
-@end itemize
-@node Supported URLs, MIME Support, Stylesheets, Top
-@chapter Supported URLs
-::WORK:: List supported URL types, specific RFCs, etc.
-@menu
-* file::                        Local file access.
-* ftp::                         Remote file access via ftp.
-* nfs::                         Remote file access via NFS.
-* info::                        Access to the Emacs Info system.
-* http/https::                  @sc{http/1.0} support.
-* mailto::                      Sending simple electronic mail.
-* news/nntp/snews::             Reading and sending Usenet news.
-* rlogin/telnet/tn3270::        Legacy host connections.
-* irc::                         Internet Relay Chat.
-* data::                        Embedding the data within the URL itself.
-* mailserver::                  Slightly more complicated electronic mail.
-* gopher::                      Gopher and Gopher+.
-* finger::                      The old favorite.
-@end menu
-@node file, ftp, Supported URLs, Supported URLs
-@section file
-@node ftp, nfs, file, Supported URLs
-@section ftp
-@node nfs, info, ftp, Supported URLs
-@section nfs
-@node info, http/https, nfs, Supported URLs
-@section info
-@node http/https, mailto, info, Supported URLs
-@section http/https
-@node mailto, news/nntp/snews, http/https, Supported URLs
-@section mailto
-@node news/nntp/snews, rlogin/telnet/tn3270, mailto, Supported URLs
-@section news/nntp/snews
-@node rlogin/telnet/tn3270, irc, news/nntp/snews, Supported URLs
-@section rlogin/telnet/tn3270
-@node irc, data, rlogin/telnet/tn3270, Supported URLs
-@section irc
-@node data, mailserver, irc, Supported URLs
-@section data
-@node mailserver, gopher, data, Supported URLs
-@section mailserver
-@node gopher, finger, mailserver, Supported URLs
-@section gopher
-@node finger,  , gopher, Supported URLs
-@section finger
-@node MIME Support, Security, Supported URLs, Top
 @chapter MIME Support
-@sc{mime} is an emerging standard for multimedia mail.  It offers a very
+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, png, jpeg, etc.).  So
+is the specific type of data (postscript, gif, jpeg, etc.).  So
-@samp{text/html} specifies an @sc{html} document, whereas
+@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.  @sc{http}/1.0
+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.  @sc{html}
+and not have the client second-guess it based on file extensions.  HTML
-files can now be named @file{something.png} (not a great idea, but
+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{.png ->
+types (e.g., @samp{.gif ->
-image/png)}.
+image/gif)}.
-* Specifying Viewers::          How to specify external and internal viewers
+* Specifying Viewers::  How to specify external and internal viewers
-for files that Emacs/W3 cannot handle natively.
+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 @sc{ftp}, local file access, or old
+only be needed when accessing files via FTP, local file access, or old
-@sc{http}/0.9 servers.
+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}.
 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 @sc{http} daemon rely on a separate file for mapping
+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
+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:
+variable is empty, then Emacs-W3 looks for these files:
 @enumerate
 @item
 @file{~/.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 @sc{http} type.  These types resemble
+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
+@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
-Not all files look as they should when parsed as an @sc{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 (PNG
+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{png}"), and
+arguments, the major type ("@i{image}"), the minor type ("@i{gif}"), and
-an assoc list of information about the viewer.  Please see the @sc{url}
+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, MIME Support, Top
+@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
+service.  Emacs-W3 tries to support as many as possible.  Emacs-W3
 currently supports:
 @table @b
 @item Basic Authentication
 @cindex Security, Basic
 @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
+Communications @footnote{http://www.netscape.com/}.  Emacs-W3 supports
-@sc{http} transfers over an SSL encrypted channel, if the appropriate files
+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, Speech Integration, Security, Top
+@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!
+* VMS::                 The wonderful world of VAX|AXP-VMS!
-* OS/2::                        The next-best thing to Unix.
+* OS/2::                The next-best thing to Unix.
-* MS-DOS::                      The wonderful world of MS-DOG!
+* MS-DOS::              The wonderful world of MS-DOG!
-* Windows::                     Windows NT, Chicago/Windows 95.
+* 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, Windows, OS/2, Non-Unix Operating Systems
+@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 Windows,  , MS-DOS, Non-Unix Operating Systems
+@node 32-Bit Windows, Amiga, MS-DOS, Non-Unix Operating Systems
-@section Windows
+@section 32-Bit Windows
 @cindex Windows (32-Bit)
 @cindex 32-Bit Windows
 @cindex Microsloth
 @cindex Windows '95
 :: WORK :: 32bit Windows Specific instructions
-@node Speech Integration, Advanced Features, Non-Unix Operating Systems, Top
+@node Amiga, Advanced Features, 32-Bit Windows, Non-Unix Operating Systems
-@chapter Speech Integration
+@section Amiga
+@cindex Amiga
-:: WORK :: Emacspeak integration
+@cindex Commodore
+:: WORK :: Amiga specific instructions
-@node Advanced Features, More Help, Speech Integration, Top
+@node Advanced Features, Style Sheets, Amiga, Top
+@comment  node-name,  next,  previous,  up
 @chapter Advanced Features
+@ifinfo
 @menu
-* Disk Caching::                Improving performance by using a local disk cache
+* Style Sheets::        Formatting control, the right way
-* Interfacing to Mail/News::    How to make VM understand hypertext links
+* Disk Caching::        Improving performance by using a local disk cache
-* Debugging HTML::              How to make Emacs/W3 display warnings about invalid
+* Interfacing to Mail/News::	How to make VM understand hypertext links
-@sc{html}/@sc{html}+ constructs.
+* Debugging HTML::      How to make Emacs-W3 display warnings about invalid
-* Hooks::                       Various hooks to use throughout Emacs/W3
+HTML/HTML+ constructs.
-* Other Variables::             Miscellaneous variables that control the real
+* Native WAIS Support:: How to make Emacs-W3 understand WAIS links without
-guts of Emacs/W3.
+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 Disk Caching, Interfacing to Mail/News, Advanced Features, Advanced Features
+@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
+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
+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
+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 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
+(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 Using Emacs-W3 with VM
 @cindex GNUS
-@cindex Using Emacs/W3 with Gnus
+@cindex Using Emacs-W3 with Gnus
 @cindex RMAIL
-@cindex Using Emacs/W3 with RMAIL
+@cindex Using Emacs-W3 with RMAIL
+More and more people are including URLs in their signatures, and within
-More and more people are including @sc{url}s 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), @sc{url}s are automatically highlighted, and can be followed with the
+(5.x), URLs are automatically highlighted, and can be followed with the
-mouse or the return key.  How the @sc{url}s are viewed is determined by 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 @sc{url}s from within RMAIL, the following hook should do the
+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, Hooks, Interfacing to Mail/News, Advanced Features
+@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 @sc{html}, set the variable @code{w3-debug-html} to
+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 @sc{html}, then a debugging
+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 Hooks, Other Variables, Debugging HTML, Advanced Features
+@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
+Emacs-W3's behavior.  They are arranged in the order in which they would
-happen when retrieving a document.  These are all 'normal hooks' in
+happen when retrieving a document.  All of these are functions (or lists
-standard Emacs-terminology, meaning they are functions (or lists of
+of functions) that are called consecutively.
-functions) that are called consecutively.
 @table @code
-@vindex w3-load-hook
+@vindex w3-load-hooks
-@item w3-load-hook
+@item w3-load-hooks
-These hooks are run the first time a @sc{url} is fetched.  All the
+These hooks are run by @code{w3-do-setup} the first time a URL is
-Emacs/W3 variables are initialized before this hook is run.
+fetched.  All the w3 variables are initialized before this hook is
-@item w3-mode-hook
+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-hook
+@item w3-source-file-hooks
-These hooks are run after displaying a document's source.
+These hooks are run after displaying a document's source
 @end table
-@node Other Variables,  , Hooks, Advanced Features
+@node Other Variables, , Hooks, Advanced Features
 @section Miscellaneous variables
+There are lots of variables that control the real nitty-gritty of Emacs-W3
-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 @sc{nntp} ports so a malicious @sc{html} author cannot spoof mail or
+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
 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
+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
 @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
+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 @sc{http}/1.0 headers to show at the end of a buffer.  All
+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 @sc{http}/1.0 headers are shown.  The default value is
+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.
 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
-@sc{http}/1.0 requests.
+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, Advanced Features, Top
+@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
+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
+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
+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.
+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
+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.
+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
 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, Dealing with Firewalls, Future Directions, Top
+@node Reporting Bugs, Installing SSL, Future Directions, Top
 @appendix Reporting Bugs
 @cindex Reporting Bugs
 @cindex Bugs
 @cindex Contacting the author
-If any bugs are discovered in Emacs/W3, please report them to the
+:: WORK :: Reporting bugs needs work.
-mailing list @t{w3-beta@@indiana.edu} - this is where the brave souls
-who beta test the latest versions of Emacs/W3 reside, and are generally
+@node Installing SSL, Using PGP/PEM, Reporting Bugs, Top
-very responsive to bug reports.
-@kindex w
-Please make sure to use the bug submission feature of Emacs/W3, so that
-all relevant information will be sent along with your bug report.  By
-default this is bound to the `@key{w}' key when in an Emacs/W3 buffer,
-or you can use @key{M-x w3-submit-bug} from anywhere within Emacs.
-For problems that are causing emacs to signal and error, please send a
-backtrace.  You can get a backtrace by @kbd{M-x setvariable RET
-debug-on-error RET t RET}, and then reproduce the error.
-If the problem is visual, please capture a copy of the output and mail
-it along with the bug report (preferably as a MIME attachment, but
-anything will do).  You can use the @code{xwd} program under X-windows
-for this, or @key{Alt-PrintScreen} under Windows 95/NT.  Sorry, but I
-don't remember what the magic incarnation is for doing a screen dump
-under NeXTstep or OS/2.
-If the problem is actually causing Emacs to crash, then you will need to
-also mail the maintainers of the various Emacs distributions with the
-bug.  Please use the @t{gnu.emacs.bug} newgroup for reporting bugs with
-GNU Emacs 19, and @t{comp.emacs.xemacs} for reporting bugs with XEmacs
-19 or XEmacs 20.  I am actively involved with the beta testing of the
-latest versions of both branches of Emacs, and if I can reproduce the
-problem, I will do my best to see it gets fixed in the next release.
-It is also important to always maintain as much context as possible in
-your responses.  I get so much email from my various Emacs-activities
-and work, that I cannot remember everything.  If you send a bug report,
-and I send you a reply, and you reply with 'no that didn't work', then
-odds are I will have no clue what didn't work, much less what that was
-trying to fix in the first place.  It will be much quicker and less
-painful if I don't have to waste a round-trip email exchange saying
-'what are you talking about'.
-@node Dealing with Firewalls, Proxy Gateways, Reporting Bugs, Top
-@appendix Dealing with Firewalls
-By default, Emacs can support standard @sc{tcp}/@sc{ip} network
-connections on almost all the platforms it runs on (Unix, @sc{vms},
-Windows, etc).  However, there are several situations where it is not
-sufficient.
-@table @b
-@cindex Firewalls
-@item Firewalls
-It is becoming more and more common to be behind a firewall or some
-other system that restricts your outbound network activity, especially
-if you are like me and away from the wonderful world of academia.
-Emacs/W3 has several different methods to get around firewalls (not to
-worry though - none of them should get you in trouble with the local
-@sc{mis} department.)
-@item Emacs cannot resolve hostnames.
-@cindex Faulty hostname resolvers
-@cindex Broken SunOS libc
-@cindex Hostname resolution
-This happens quite often on SunOS workstations and some ULTRIX machines.
-Some C libraries do not include the hostname resolver routines in their
-static libraries.  If Emacs was linked statically, and was not linked
-with the resolver libraries, it wil not 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
-(@url{http://129.79.254.191/} works, but
-@url{http://www.cs.indiana.edu/} doesn't).
-The best solution for this problem is to recompile Emacs, making sure to
-either link dynamically (if available on your operating system), or
-include the @file{-lresolv}.
-@cindex url-gateway-broken-resolution
-If you do not have the disk space or the appropriate permissions to
-recompile Emacs, another alternative is using the @file{nslookup}
-program to do hostname resolution.  To turn this on, set the variable
-@code{url-gateway-broken-resolution} in your @file{~/.emacs} file.  This
-runs the program specified by @code{url-gateway-nslookup-program} (by
-default "@code{nslookup}" to do hostname resolution.  This program should
-expect a single argument on the command line - the hostname to resolve,
-and should produce output similar to the standard Unix @file{nslookup}
-program:
-@example
-Name: www.cs.indiana.ed
-Address: 129.79.254.191
-@end example
-@cindex @sc{term}
-@item Using @sc{term} (or @sc{term}-like) Networking Software
-@sc{term} @footnote{@sc{term} is a user-level protocol for emulating
-@sc{ip} over a serial line.  More information is available at
-@url{ftp://sunsite.unc.edu/pub/Linux/apps/comm/term}} for slip-like
-access to the internet.
-@sc{note}: XEmacs and Emacs 19.22 or later have patches to enable native
-@sc{term} networking.  To enable it, @code{#define TERM} in the
-appropriate s/*.h file for the operating system, then change the
-@code{SYSTEM_LIBS} definition to include the @file{termnet} library that
-comes with the latest versions of @sc{term}.
-If you run into any problems with the native @sc{term} networking
-support in Emacs or XEmacs, please let @t{wmperry@@cs.indiana.edu} know,
-as he is responsible for the original support.
-@end table
-@vindex url-gateway-local-host-regexp
-Emacs/W3 has support for using the gateway mechanism for certain
-domains, and directly connecting to others.  The variable
-@code{url-gateway-local-host-regexp} controls this behaviour.  This is 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), ie: @samp{(setq url-gateway-method 'telnet)}.  Possible
-values are:
-@table @dfn
-@item telnet
-Use this method if you must first telnet and log into a gateway host,
-and then run telnet from that host to connect to outside machines.
-:: WORK :: document telnet gw variables
-This section needs more information, specifically documenting the
-following variables.  For now, please do @key{C-h v} on the variable for
-more information.
-@table @code
-@item url-gateway-telnet-host
-@item url-gateway-telnet-parameters
-@item url-gateway-telnet-password-prompt
-@item url-gateway-telnet-puser-name
-@item url-gateway-prompt-pattern
-@end table
-@item rlogin
-This method is identical to the @code{telnet} method, but uses
-@file{rlogin} to log into the remote machine without having to send the
-username and password over the wire every time.
-:: WORK :: document rlogin gw variables
-This section needs more information, specifically documenting the
-following variables.  For now, please do @key{C-h v} on the variable for
-more information.
-@table @code
-@item url-gateway-rlogin-host
-@item url-gateway-rlogin-parameters
-@item url-gateway-rlogin-user-name
-@item url-gateway-prompt-pattern
-@end table
-@item tcp
-Masanobu UMEDA (@i{umerin@@mse.kyutech.ac.jp}) has written a very small
-application that you can run in a subprocess to do the network
-connections.
-@item @sc{socks}
-Use if the firewall has a @sc{socks} gateway running on it.
-:: WORK :: document socks variables
-This section needs more information, specifically documenting the
-following variables.  For now, please do @key{C-h v} on the variable for
-more information.
-@table @code
-@item socks-host
-@item socks-password
-@item socks-username
-@item socks-port
-@item socks-timeout
-@end table
-@c @item ssl
-@c This probably shouldn't be documented
-@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
-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, Installing SSL, Dealing with Firewalls, Top
-@appendix 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 (@sc{http}, @sc{wais}, gopher,
-@sc{ftp}, etc.) can have a different gateway server.  The environment
-variables are @code{PROTOCOL}_proxy, where @code{PROTOCOL} is one of the
-supported network protocols (gopher, file, @sc{http}, @sc{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 @code{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 (@sc{http}, gopher, etc) in all lowercase.  The
-@code{cdr} of each entry should be the fully-specified @sc{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 Installing SSL, Mailcap Files, Proxy Gateways, 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.
+In order to use SSL in Emacs-W3, an implementation of SSL is necessary.
-Emacs/W3 is configued to work out of the box with SSLeay 0.6.6 or later.
+These are the implementations that I am aware of:
-For best results, you should apply a patch that makes the SSLeay client
-much quieter about what it reports.
-You can download SSLeay from
-@url{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/}
-The following variables control how the external program is invoked.
 @table @code
-@item ssl-program-name
+@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
-The name of the program to run, as a string.
+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
-(setq ssl-program-name "s_client")
+*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
-@item ssl-program-arguments
+@cindex Mailcrypt
-@vindex ssl-program-arguments
+Emacs-W3 uses the excellent @i{mailcrypt}@footnote{Available from
-This should be used if your SSL program needs command line switches to
+http://www.cs.indiana.edu/LCD/cover.html?mailcrypt} package written by
-specify any behaviour (certificate file locations, etc).  This is a list
+Jin S Choi (@i{jsc@@mit.edu}).  This package takes care of calling ripem
-of strings and symbols.
+and/or pgp with the correct arguments.  Please see the documentation at
+the top of mailcrypt.el for instructions on using mailcrypt.  All bug
-The special symbols 'host and 'port may be used in the list of arguments
+reports about mailcrypt should go to Jin S Choi, but bugs about how I
-and will be replaced with the hostname and service/port that will be
+use it in Emacs-W3 should of course be directed to me.
-connected to.
+@node Mailcap Files, General Index, Using PGP/PEM, Top
-@example
-(setq ssl-program-arguments '("-host" host "-port" service "-verify" "4"
-"-CApath /usr/local/ssl/certs"))
-@end example
-@end table
-@node Mailcap Files, Down with DoubleClick, Installing SSL, 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
+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
+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
+environment variable is empty, then Emacs-W3 looks for these
 files:
 @enumerate
 @item
 @file{~/.mailcap}
 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 Down with DoubleClick, General Index, Mailcap Files, Top
+@node General Index, Key Index, Mailcap Files, Top
-@appendix Down with DoubleClick
-:: WORK :: Document why doubleclick is evil
-:: WORK :: Document how you can never see another ad from them again
-@node General Index, Key Index, Down with DoubleClick, Top
 @appendix General Index
 @printindex fn
-@node Key Index,  , General Index, Top
+@node Key Index, , General Index, Top
 @appendix Key Index
 @printindex ky
 @contents
 @bye

Mercurial > hg > xemacs-beta

comparison man/w3.texi @ 70:131b0175ea99 r20-0b30