Copyright (C) 1993, 1994, 1995, 1996, 1997, 1999, 2000 Free Software
Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being "A GNU Manual".  A copy of the license is included in the
     section entitled "GNU Free Documentation License" in the Emacs
     manual.

W3
**

Users can browse the World Wide Web from within Emacs by using Emacs/W3.
All of the widely used (and even some not very widely used) 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 Web-enable their applications and daily work routines with
the library.

   Emacs/W3 is completely customizable, both from Emacs-Lisp and from
stylesheets Stylesheets.  If there is any aspect of Emacs/W3
that cannot be modified to your satisfaction, please send mail to the
w3-beta@xemacs.org mailing list with any suggestions.  See Reporting Bugs.

   This manual corresponds to Emacs/W3 $State: Exp $

Appendices:

Indices:

1 Getting Started
*****************

If installed correctly, starting Emacs/W3 is quite painless.  Just type
'M-x w3' in a running Emacs session.  This will retrieve the default
page that has been configured -- by default the documentation for
Emacs/W3 at Indiana University.  The default homepage is specified by
the 'w3-default-homepage' variable.

   If the default page is not retrieved correctly at startup, you will
have to do some customization.

   Once started, you can use the mouse and the menu or use the following
key commands (for more commands and more detail, see Basic Usage).

move forward
     press the space bar,

move backwards
     press the backspace key,

move to the next HTML reference on the page
     press the 'TAB' key,

move to the previous HTML reference on the page
     press the 'SHIFT' and 'TAB' keys at the same time.  If this does
     not work (some text terminals cannot distinguish between 'TAB' and
     'SHIFT-TAB', pressing the 'ALT' and 'TAB' keys should also work.

follow a link
     put the cursor over it and press the 'RETURN' key, or
     click the left mouse button on it,

fetch a URL
     press the 'Control' and 'o' keys at the same time,
     type the URL, and then press the 'RETURN' key,

return to the last URL you were at
     press the 'l' key,

quit W3 mode
     press the 'q' key.

1.1 Downloading
===============

Emacs/W3 will work with Emacs 19.29 and later and XEmacs 19.14 and
later, but if you're using a 19.x Emacs then you will need to get the
latest custom and widget libraries.

Emacs
     Available from the GNU archive <ftp://prep.ai.mit.edu/pub/gnu> or
     one of it's many mirrors.

XEmacs
     Available from the XEmacs archive <http://www.xemacs.org/> or one
     of it's many mirrors.

Emacs/W3
     <http://www.cs.indiana.edu/elisp/w3/docs.html> is the main
     distribution point for Emacs/W3.

Emacspeak
     A speech synthesizer package for Emacs and XEmacs.  More
     information is available at
     <http://www.cs.cornell.edu/Info/People/raman/emacspeak/>

1.2 Building and Installing
===========================

Emacs/W3 uses GNU 'configure' (see configure) to control
installation.  configure will attempt to find what version of Emacs you
have and where it is installed.  If it finds both Emacs and XEmacs, then
XEmacs is used (but see below for how to change this).  Apart from the
usual options, the following options are accepted:

'--with-xemacs'
     Use XEmacs.
'--with-emacs'
     Use Emacs.
'--with-lispdir=DIR'
     Put lisp files (*.el and *.elc) in DIR.  If this is not specified,
     and neither is '--with-package-dir', then the lisp files go into
     'EMACS/site-lisp'.
'--with-package-dir=DIR'
     If using XEmacs, install Emacs/W3 as a package in DIR.  Please note
     that this and the '--prefix' argument are mutually exclusive.
'--with-makeinfo=MAKEINFO'
     Use MAKEINFO to build info files from Texinfo files.  'configure'
     will normally find makeinfo if it's available, you should only need
     to specify this if it's not called makeinfo or if it isn't in a
     directory in your 'PATH'.
'--with-custom=DIR'
     Use the custom package in DIR.  'configure' will attempt to find a
     suitable custom package, you should not need to specify this
     yourself if the custom package is in Emacs's 'load-path'.
'--enable-site-install'
     Install Emacs/W3 for the site, rather than just yourself.  This
     only affects whether 'make dotemacs' affects '~/.emacs' or
     'site-lisp/default.el'.

   These are the most useful of the normal 'configure' options.

'--prefix=DIR'
     This is the top level directory and by default everything is
     installed somewhere below this.  This is '/usr/local' by default.
'--infodir=DIR'
     Where to put the info files.  This is 'PREFIX/info' by default.
'--data-dir=DIR'
     Where to put date files (default stylesheets).  This is
     'PREFIX/share' by default unless '--with-package-dir=PACK-DIR' was
     given in which case they go into 'PACK-DIR/etc/w3'.

   The directory that the byte-compiled lisp files will be installed
into is controlled by the '--prefix', '--with-package-dir' and
'--with-lispdir' options.  The directory for the info and data files is
likewise controlled by the '--prefix', '--with-package-dir' and
'--infodir' or '--data-dir' options.

   Normally these are the only things that need to be installed, they
can by compiled by 'make all', or 'make w3' and 'make info'.  'make
install' will install the lisp, info and data files.  'make all' in the
'texi' directory will create the info files and also dvi files.  HTML
and postscript can be generated by 'make html' and 'make ps'
respectively.

1.3 Startup Files
=================

Emacs/W3 needs a directory for each user to store options, history and
the cache.  'w3-configuration-directory' controls this directory, which
is '~/.w3' by default.

1.3.1 Emacs/W3 profile
----------------------

Emacs/W3 keeps a file called 'profile' in your configuration directory
that sets many variables.  *Warning*: this file will overide any options
that you set in your '.emacs'.  You _must_ either edit 'profile'
directly or use 'w3-menu-save-options' to save your settings.

   If you prefer, you can set 'w3-default-configuration-file' to specify
a different configuration file.  This file does not need to be dedicated
to Emacs/W3 because Emacs/W3 will delimit its part of the file so you
can set this to '.emacs' if you want.  However, while Emacs/W3 will save
it's options to the correct part of the file, it will read (and execute)
the entire file when starting.

1.3.2 Default stylesheets
-------------------------

Emacs/W3 will look for style-sheets in 'w3-configuration-directory' as
well as the site-wide directories.  In particular it will look for
'dark.css' or 'stylesheet-dark' if you're using a dark background and
'light.css' or 'stylesheet-light' if you're using a light background as
well as 'stylesheet' and 'default.css'.  If 'w3-default-stylesheet' is
not 'nil' then the file that it names will be used as well.  For more
information, see Stylesheets.

1.3.3 History
-------------

Emacs/W3 keeps a file called 'history' in the configuration directory.
This is a list of all the links you have visited.  You can change the
file where the history is stored by setting 'url-global-history-file' to
the name of the file you'd prefer.  See Global History.

1.3.4 Hotlists
--------------

"Hotlists" (sometimes called bookmarks, but not to be confused with
Emacs's bookmarks) are a list of URLs.  Emacs/W3 supports mosaic's
hotlist format which associates an alias with each URL -- see Hotlist Handling.
The 'w3-hotlist-file' variable specifies the hotlist file.
It defaults to '.mosaic-hotlist-default'.

2 Basic Usage
*************

Emacs/W3 is similar to the Info package all Emacs users hold near and
dear to their hearts (see Info (info), for a description of Info).
Basically, 'space' and 'backspace' control scrolling, and 'return' or
the middle mouse button follows a hypertext link.  The 'tab' and
'Meta-tab' keys maneuver around the various links on the page.

   NOTE: Starting with Emacs/W3 4.0, form entry areas in a page can be
typed directly into.  This is one of the main differences in navigation
from version 2.0.  If you are used to using the 'f' and 'b' keys to
navigate around a buffer, I suggest training yourself to always use
'tab' and 'M-tab' -- it will save time and frustration on pages 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.  For information
on how to change this, see Stylesheets.

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

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

2.1 Movement
============

All the standard Emacs bindings for movement are still in effect, with a
few additions for convenience.

'space'
     Scroll downward in the buffer.  With prefix arg, scroll down that
     many screenfuls ('w3-scroll-up').
'M-space'
     Goes to next document.

'M-del'
     Goes to previous document.

'backspace, C-?'
     Scroll upward in the buffer.  With prefix arg, scroll up that many
     screenfuls ('scroll-down').
'<'
     Goes to the start of document ('w3-start-of-document').
'>'
     Goes to the end of document ('w3-end-of-document').
'Meta-tab, Shift-tab, b'
     Attempts to move backward one link area in the current document
     ('w3-widget-backward').  Signals an error if no previous links are
     found.
'tab, f, n'
     Attempts to move forward one link area in the current document
     ('w3-widget-forward').  Signals an error if no more links are
     found.
'B, HB'
     Takes one step back along the path in the current history
     ('w3-history-backward').  Has no effect if at the beginning of the
     session history.
'F, HF'
     Takes one step forward along the path in the current history
     ('w3-history-forward').  Has no effect if at the end of the session
     history.
'l'
     Return to the last buffer shown before this buffer
     ('w3-goto-last-buffer').
'q'
     Kill this buffer ('w3-quit').
'Q, u'
     Bury this buffer, but don't kill it ('w3-leave-buffer').

2.2 Information
===============

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

'v'
     This shows the URL of the current document in the minibuffer
     ('url-view-url').
'V'
     This shows the URL of the hypertext link under point in the
     minibuffer ('w3-view-this-url').
'i'
     Shows miscellaneous information about the currently displayed
     document ('w3-document-information').  This includes the URL, the
     last modified date, MIME headers, the HTTP response code, and any
     relationships to other documents.  Any security information is also
     displayed.
'I'
     Shows information about the URL at point ('w3-popup-info').
's'
     This shows the HTML source of the current document in a separate
     buffer ('w3-source-document').  The buffer's name is based on the
     document's URL.
'S'
     Shows the HTML source of the hypertext link under point in a
     separate buffer ('w3-source-document-at-point').  The buffer's name
     is based on the document's URL.
'k'
     This stores the current document's URL in the kill ring, and also
     in the current window-system's clipboard, if possible
     ('w3-save-url').
'K'
     Stores the URL of the document under point in the kill ring, and
     also in the current window-system's clipboard, if possible
     ('w3-save-this-url').

2.3 Action
==========

First, here are the keys and functions that bring up a new hypertext
page, usually creating a new buffer.
'm'
     Choose a link from the current buffer and follow it
     ('w3-complete-link').  A completing-read is done on all the links,
     so 'space' and 'TAB' can be used for completion.
'return'
     Pressing return when over a hyperlink attempts to follow the link
     under the cursor ('w3-follow-link').

     Pressing return when over a form input field can cause
     auto-submission 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 the form will be submitted.

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

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

'D'
     Download the URL at point ('w3-download-url-at-point').
'd'
     Download the current URL ('w3-download-this-url').
'm'
     Selects a destination from a list of all the hyperlinks in the
     current buffer ('w3-complete-link').  Use 'space' and 'tab' to
     complete on the links.

'r, g'
     Reloads the current document ('w3-reload-document').  The position
     within the buffer remains the same (unless the document has changed
     since it was last retrieved, in which case it should be relatively
     close).  This causes an unconditional reload from the remote server
     -- the locally cached copy is not consulted.
'R'
     Redraws the buffer without reloading document
     ('w3-refresh-buffer').
'C-o'
     Prompts for a URL in the minibuffer, and attempts to fetch it
     ('w3-fetch').  If there are any errors, or Emacs/W3 cannot
     understand the type of link requested, the errors are displayed in
     a hypertext buffer.
'o'
     Opens a local file, interactively ('w3-open-local').  This prompts
     for a local file name to open.  The file must exist, and may be a
     directory.  If the requested file is a directory and
     'url-use-hypertext-dired' is 'nil', then a dired-mode buffer is
     displayed.  If non'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.

'M-s'
     Save a document to the local disk as HTML Source, Formatted Text,
     LaTeX Source, or Binary ('w3-save-as').

'Hv, C-c C-b'
     Show the current session's history list ('w3-show-history-list').
     This takes all the links that are in that internal list, and
     formats them as hypertext links in a list, see Global History

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

'l'
     Goes to the last WWW buffer seen ('w3-goto-last-buffer').
'p'
     Prints the current document ('w3-print-this-url').  Choose from
     several different formats to print: formatted text, HTML source,
     PostScript (with ps-print), or by using LaTeX and dvips).  See
     Printing.
'P'
     Prints out the URL under point in a variety of formats
     ('w3-print-url-under-point').  See Printing.
'q'
     Quits WWW mode ('w3-quit').  This kills the current buffer and goes
     to the most recently visited buffer.
'u, Q'
     This ('w3-leave-buffer') is similar to 'w3-quit', but the buffer is
     not killed, it is moved to the bottom of the buffer list (so it is
     the least likely to show up as the default with switch-to-buffer).
     This is different from 'w3-goto-last-buffer' in that it does not
     return to the last WWW page visited -- it is the same as using
     'switch-to-buffer' -- the buffer left in the window is fairly
     random.

2.4 Miscellaneous
=================

'?'
     Shows help for Emacs/W3 ('w3-help').
'C-c C-v'
     Show what version of Emacs/W3 you're running ('w3-version').
'M-m'
     Mails the current document to someone ('w3-mail-current-document').
     Choose from several different formats to mail: formatted text, HTML
     source, PostScript, or LaTeX source.  When the HTML source is
     mailed, then an appropriate <base> tag is inserted at the beginning
     of the document so that relative links may be followed correctly by
     whoever receives the mail.
'M-M'
     Mails the document pointed to by the hypertext link under point to
     someone ('w3-mail-document-under-point').  Choose from several
     different formats to mail: formatted text, HTML source, PostScript,
     or LaTeX source.  When the HTML source is mailed, then an
     appropriate <base> tag is inserted at the beginning of the document
     so that relative links may be followed correctly by whoever
     receives the mail.
'M-t, A-t'
     gdj1: bound to url-list-processes.  What does this do?
'c'
     Send a mail to the author of the current document
     ('w3-mail-document-author').

'M-x w3-insert-formatted-url'
     Insert a fully formatted HTML link into another buffer
     ('w3-insert-formatted-url').  This gets the name and URL of either
     the current buffer, or, with a prefix arg, of the link under point,
     and construct the appropriate <a...>...</a> markup and insert it
     into the desired buffer.
'M-tab'
     Inserts the URL of the current document into another buffer
     ('w3-insert-this-url'').  Buffer is prompted for in the minibuffer.
     With prefix arg, uses the URL of the link under point.
'U'
     Selects one of the <LINK> tags from this document and fetch it
     ('w3-use-links').  Links are attributes of a specific document, and
     can tell such things as who made the document, where a table of
     contents is located, etc.

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

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

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

3.1 Emulation
=============

Emacs/W3 can emulate the keybindings of lynx and netscape, but only one
at a time.  If you want emulation permanantly turned on, then you should
add 'turn-on-lynx-emulation' or 'turn-on-netscape-emulation' to
'w3-mode-hook'.

3.2 Lynx emulation
==================

'turn-on-lynx-emulation' turns on lynx emulation and turns off netscape
emulation.  lynx emulation is handled by the
'w3-lynx-emulation-minor-mode' minor mode.  For more information about
lynx style hotlists, see Hotlist Handling.

   :: work :: Document lynx emulation
'Down arrow'
     Highlight next topic
'Up arrow'
     Highlight previous topic
'Right arrow, Return, Enter'
     Jump to highlighted topic
'Left arrow'
     Return to previous topic.  gdj1: actually, this doesn't seem to
     work quite right.
'+'
     Scroll down to next page (Page-Down)
'-'
     Scroll up to previous page (Page-Up)
'SPACE'
     Scroll down to next page (Page-Down)
'b'
     Scroll up to previous page (Page-Up)
'C-a'
     Go to first page of the current document (Home)
'C-e'
     Go to last page of the current document (End)
'C-b'
     Scroll up to previous page (Page-Up)
'C-f'
     Scroll down to next page (Page-Down)
'C-n'
     Go forward two lines in the current document
'C-p'
     Go back two lines in the current document
')'
     Go forward half a page in the current document (ignored)
'('
     Go back half a page in the current document (ignored)
'#'
     Go to Toolbar or Banner in the current document, only works in
     XEmacs.  gdj1: is this what is meant by toolbar?
'?, h'
     Help (this screen)
'a'
     Add the current link to a bookmark file
'c'
     Send a comment to the document owner
'd'
     Download the current link
'e'
     Edit the current file (ignored)
'g'
     Goto a user specified URL or file
'i'
     Show an index of documents (ignored)
'j'
     Execute a jump operation (using hotlist)
'k'
     Show a list of key mappings
'l'
     List references (links) in current document
'm'
     Return to main screen
'n'
     Go to the next search string
'o'
     Set your options
'p'
     Print the current document
'q'
     Quit
'r'
     Delete hotlist entry
's'
     Enter a search string for an external search gdj1: really?
'u'
     Go backwards in history
'/'
     Search for a string within the current document
'v'
     View a bookmark file
'V'
     Go to the Visited Links Page
'x'
     Force submission of form or link with no-cache
'z'
     Cancel transfer in progress
'[backspace]'
     Go to the history Page gdj1: really?
'='
     Show file and link info
'\'
     Toggle document source/rendered view
'!'
     Spawn your default shell
'*'
     Toggle image_links mode on and off (ignored)
'['
     Toggle pseudo_inlines mode on and off (ignorged)
']'
     Send an HTTP HEAD request for the current doc or link (ignored)
'C-r'
     Reload current file and refresh the screen
'C-w'
     Refresh the screen
'C-u'
     Erase input line (ignored)
'C-g'
     Cancel input or transfer
'C-t'
     Toggle trace mode on and off (ignored)
'C-k'
     Invoke the Cookie Jar Page (ignored)

3.3 Netscape emulation
======================

'turn-on-netscape-emulation' turns on netscape emulation and turns off
lynx emulation.  netscape emulation is handled by the
'w3-netscape-emulation-minor-mode' minor mode.  For more information
about netscape style hotlists, see Hotlist Handling.

'M-a'
     Add the current link to a bookmark file

'M-b'
     Show hotlist file.

'M-f'
     Search forward in document

'M-g'
     Reapeat last search

'M-h'
     Show history window

'M-i'
     Load images

'M-l'
     Goto a user specified URL or file

'M-m'
     Send mail

'M-n'
     Open new frame

'M-o'
     Open a local file

'M-p'
     Print current document

'M-q'
     Quit current document

'M-r'
     Reload document and redraw

'M-s'
     Save current document

'M-[left]'
     Go back in history list

'M-[right]'
     Go forward in history list

'[left]'
     Scroll left

'[right]'
     Scroll right

'[up]'
     Scroll up

'[down]'
     Scroll down

3.4 Masquerading
================

HTTP allows servers to ask browsers what browser they are, and what
version they are.  Emacs/W3 allows you to choose the reply.  There are
functions to masquerade as lynx, netscape, IE or arena.  For each
BROWSER there are three functions, 'turn-on-BROWSER-masquerade-mode',
'turn-off-BROWSER-masquerade-mode' and 'w3-BROWSER-masquerade-mode'.
The purpose of the first two is clear, 'w3-BROWSER-masquerade-mode'
takes an optional argument which toggles the mode if it's 'nil', turns
off the mode if it's 0 and turns the mode on otherwise.

   If you'd prefer to masquerade as another browser, then you should
call 'w3-masquerade-stub' with three arguments: ARG, APP and VERSION.
ARG has the same function as for 'w3-BROWSER-masquerade-mode', APP is
the name of the browser to masquerade as and VERSION is the version.

   Why would you want to masquerade as another browser when you could be
advertising Emacs/W3?  Well, some servers will only let certain browsers
connect with them.  This is cleary evil.  Also some servers may alter
what they present depending on the browser, this is probably a Good
Thing but they might not know about Emacs/W3.  Also one could argue that
demanding the USER_AGENT field is a breach of privacy, Emacs/W3 doesn't
have to send it (see Security), but the server doesn't have to let
you connect either.

3.5 Hotlist Handling
====================

Emacs/W3 supports two types of hotlist, mosaic hotlists and HTML as used
by lynx and netscape (which both call hotlists bookmarks).
Unfortunately, not all hotlist operations are supported for HTML files
at the moment.

   In order to avoid having to traverse many documents to get to the
same document over and over, Emacs/W3 supports a "hotlist" like Mosaic.
This is a file that contains URLs and aliases.  Hotlists allow quick
access to any document in the Web, providing it has been visited and
added to the hotlist.  The variable 'w3-hotlist-file' determines where
this information is saved.  The structure of the file is compatible with
Mosaic's hotlist file, so this defaults to '~/.mosaic-hotlist-default'.

   Hotlist commands are:
'ha'
     Shows the hotlist entries matching a regular expression.

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

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

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

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

'hv'
     Converts the hotlist into HTML and displays it.

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

'hI'
     Add the document pointed to by the hyperlink under point to the
     hotlist.

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

3.6 History
===========

Almost all web browsers keep track of the URLs followed from a page, so
that it can provide forward and back buttons to keep a path of URLs that
can be traversed easily.

   If 'url-keep-history' is non-'nil', then Emacs/W3 keeps track of all
the URLs visited in an Emacs session.  If 't' then Emacs/W3 will save
the history list at the end of each session to the
'url-global-history-file' file.  The history list is simply a list of
all the URLs visited in the session.

   To view a listing of the history for this session of Emacs/W3, use
'M-x w3-show-history-list' ('Hv') from any buffer, and Emacs/W3
generates an HTML document showing every URL visited since Emacs started
(or cleared the history list), and then format it.  Any of the links can
be chosen and followed to the original document.  To clear the history
list, choose 'Clear History' from the 'Options' menu.

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

3.7 Global History
==================

Most web browsers also support the idea of a "history" of URLs the user
has visited, and it displays them in a different style than normal URLs.
Emacs/W3 will read and write history files generated by Emacs/W3, Mosaic
v1 and v2 or netscape.  Emacs/W3 looks at the file contents to determine
the type of history.

   If the variable 'url-keep-history' is 't', then Emacs/W3 keeps a list
of all the URLs visited in a session.  The file is automatically written
to disk every 'url-global-history-save-interval' seconds and when
exiting emacs.  The list is added to those already in the file specified
by 'url-global-history-file', which defaults to '~/mosaic.hst' for MS
operating systems, '~/mosaic.global-history' for VMS and '~/.w3/history'
for everything else.

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

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

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

3.8 Display Variables
=====================

Emacs/W3 has many variable for you to fiddle with to get the display
just right.

'w3-display-frames'
     You can control what Emacs/W3 does with frame by setting
     'w3-display-frames'.  It can be
     'nil'
          Emacs/W3 will pretend not to understand frames at all.
     'as-nil'
          Emacs/W3 will show hyperlinks to frames but will not fetch
          them (the same behaviour as lynx).
     'ask'
          This is similar to 'as-nil', but Emacs/W3 will ask if you want
          to retrieve the frames.
     't'
          Emacs/W3 will dispaly the hyperlinks and fetch the frames.

'w3-bullets'
     Emacs/W3 lets _you_ decide what characters to use for bullets in
     unordered lists by setting 'w3-bullets'.  It is a association list,
     mapping list types to characters.  By default it is '((disc . ?*)
     (circle . ?o) (square . ?#) (none . ? ))'.

'w3-echo-link'
     You can decide what should be displayed when tabbing through links
     by setting the 'w3-echo-link' variable.  It is a list and may
     contain the following symbols,
     'url'
          Display the URL of the target.
     'text'
          Display the text of the link.
     'title'
          Display the title attribute of the link.
     'name'
          Display the name or id attribute of the link.

     The default is '(title url text name)'.

'w3-horizontal-rule-char'
     Many HTML pages use horizontal lines (rules) to seperate sections
     of the page.  You can control what character Emacs/W3 will use to
     draw these by setting 'w3-horizontal-rule-char'.  If it is a
     character (_not_ a string) then Emacs/W3 will replicate that
     character across the screen, if it is 'nil' then Emacs/W3 will use
     a terminal graphics character if possible.  It is 'nil by default'.

'w3-use-terminal-characters'
     When Emacs/W3 draws table and rules, it needs to approximate line
     somehow.  If 'w3-use-terminal-characters' it 'non-nil' (the
     default) then Emacs/W3 will use terminal graphics characters if
     they are available.

'w3-use-terminal-characters-on-tty'
     Using terminal graphics characters on ttys will trigger display
     bugs in both XEmacs and FSF Emacs, but the display is usually
     readable with FSF Emacs.  'w3-use-terminal-characters-on-tty'
     controls whether to use terminal graphics characters on ttys, it is
     'nil' by default.

'w3-use-terminal-glyphs'
     Emacs/W3 can use glyphs rather than text properties for terminal
     graphics characters.  Glyphs do not work with the most recent
     versions of XEmacs.  This is 't' by default.

'w3-defined-link-types'
     'w3-defined-link-types' is a list of names that have special
     significance as the values of 'REL' or 'REV' attributes of <link>
     elements.  All members should be in lowercase.

'w3-auto-image-alt'
     Some people do not feel it's worth their time to add 'alt' tags to
     their images, but Emacs/W3 can create 'alt' tags on the fly for
     images that do not have them.  To control this you can set
     'w3-auto-image-alt' to one of the following:
     'nil'
          Do not create 'alt' tags
     string
          The string will be run through format with the filename of the
          image and so may have a single '%s', for example
          '"[IMAGE(%s)]"'
     function
          The function will be called with the filename of the images as
          the argument.  This is the default, with
          'w3-default-image-alt-func' being the function.

'w3-min-img-size, w3-default-image-alt-func, w3-dummy-img-alt-repl'
     'w3-default-image-alt-func' returns 'w3-dummy-img-alt-repl' ('*' by
     default) if the image's height and width are both less than
     'w3-min-img-size' pixels (15 by default) and if the filename
     matches the 'w3-dummy-img-re' regular expression.  Otherwise,
     'w3-default-image-alt-func' returns the filename enclosed in a '[]'
     pair.

'w3-icon-format'
     Emacs/W3 will expect the standard icons to be in the format
     specified by 'w3-icon-format'.  This is 'gif' by default, but could
     be 'xpm', 'xbm' or any other format for that matter.  It is added
     as a file extension to the icon name, but the variable's value must
     be a symbol.  If 'nil', then the server decides.

'w3-delay-image-loads'
     You can choose whether Emacs/W3 retrieves images with the document,
     or delays loading them by setting 'w3-delay-image-loads'.  By
     default this is 't' if you compiled XEmacs with support for gifs,
     jpegs, pngs or imagick and 'nil' otherwise.

'w3-image-mappings'
     'w3-image-mappings' controls the mapping of MIME types to image
     types for the 'image' package.  Each entry is a cons cell of a MIME
     type string and an image-type symbol.

'w3-max-menu-length'
     Emacs/W3 will split menus into smaller submenus if they are longer
     than 'w3-max-menu-length'.

'w3-max-menu-width'
     The maximum width of a pulldown menu choice.

'w3-right-margin'
     Emacs/W3's right margin is controlled by 'w3-right-margin'.  This
     is subtracted from '(window-width)' for each Emacs/W3 buffer and
     used as the fill-column.  It is 2 by default.

'w3-maximum-line-length'
     The maximum length of a line.  If 'nil' (the default) then lines
     can extend to the window margin.

'w3-modeline-format'
     You can specify the modeline to use in 'w3-mode' by setting this.

'w3-honor-stylesheets'
     If this is non-'nil' (the default) then Emacs/W3 will let a
     document specify a CSS stylesheet.

'w3-user-colors-take-precedence'
     Emacs/W3 will ignore a document's attempts to define certain
     colours if 'w3-user-colors-take-precedence' it non-'nil'.  The
     default is 'nil'.

'w3-user-fonts-take-precedence'
     Emacs/W3 will ignore attempts by stylesheets or font tags to change
     certain fonts if this is non-'nil'.

3.8.1 Asynchronous behaviour
----------------------------

'url-be-asynchronous'
     If this is non-'nil' then document retrievals over HTTP will be
     down in the background.

'url-default-retrieval-proc'
     This controls what happens when an asynchronous retrievel
     completes.  It is 'url-default-callback' by default but can be any
     function taking one argument.  The argument specifies the file that
     has been retrieved.  If there is no buffer associated with the
     file, then 'url-default-callback' just puts a message in the
     minibuffer saying that the retrieval is complete, otherwise the
     action depends on the buffer.

'w3-do-incremental-display'
     Emacs/W3 can de incremental display of pages if
     'w3-do-incremental-display' is 't'.  It is 'nil' by default.

'w3-notify'
     You might want Emacs/W3 to notify you discreetly when it has
     finished preparing a page for your reading pleasure.  You can
     control Emacs/W3's behaviour in this situation by way of the
     'w3-notify' variable.  It may take the following values:
     'newframe'
          Puts the Emacs/W3 page in its own frame.
     'bully'
          Make the Emacs/W3 page the current buffer and only window.
     'semibully'
          Make the Emacs/W3 page the current buffer in the same window.
          This is the default.
     'aggressive'
          Make the Emacs/W3 page the current buffer in the other window.
     'friendly'
          Display the Emacs/W3 page in the other window, but don't make
          it the current buffer.
     'polite'
          Don't display Emacs/W3 page, but print a message when ready
          and beep.
     'quiet'
          The same as 'polite', but don't beep.
     'meek'
          Make no indication that the page is ready, in fact any other
          value is equivalent to meek.

4 Stylesheets
*************

The way in which Emacs/W3 formats a document is very customizable.  All
formatting is now controlled by a default stylesheet set by the user
with the 'w3-default-stylesheet' variable.  Emacs/W3 currently supports
the W3C recommendation for Cascading Style Sheets, Level 1 (commonly
known as CSS1) with a few experimental items from other W3C proposals.
Wherever Emacs/W3 diverges from the specification, it will be clearly
documented, and will be changed once a full standard is available.

   Support for 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 CSS1 specification so it
should be very easy to look up what Emacs/W3 supports when browsing
through the CSS1 specification.  Please note that a lot of the text in
the following sections comes directly from the specification as well.

4.1 Terminology
===============

"attribute"
     HTML attribute, ie: 'align=center' -- align is the attribute.
"author"
     The author of an HTML document.
"block-level element"
     An element which has a line break before and after (e.g. 'H1' in
     HTML).
"canvas"
     The part of the UA's drawing surface onto which documents are
     rendered.
"child element"
     A subelement in SGML terminology.
"contextual selector"
     A selector that matches elements based on their position in the
     document structure.  A contextual selector consists of several
     simple selectors.  E.g., the contextual selector 'H1.initial B'
     consists of two simple selectors, 'H1.initial' and 'B'.
"CSS"
     Cascading Style Sheets.
"declaration"
     A property (e.g.  'font-size') and a corresponding value (e.g.
     '12pt').
"designer"
     The designer of a style sheet.
"document"
     HTML document.
"element"
     HTML element.
"element type"
     A generic identifier in SGML terminology.
"fictional tag sequence"
     A tool for describing the behavior of pseudo-classes and
     pseudo-elements.
"font size"
     The size for which a font is designed.  Typically, the size of a
     font is 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 (optionally) with a diacritical mark.
"HTML extension"
     Markup introduced by UA vendors, most often to support certain
     visual effects.  The FONT, CENTER and BLINK elements are examples
     of HTML extensions, as is the BGCOLOR attribute.  One of the goals
     of CSS is to provide an alternative to HTML extensions.
"inline element"
     An element which does not have a line break before and after (e.g.
     'STRONG' in HTML)
"intrinsic dimensions"
     The width and height as defined by the element itself, not imposed
     by the surroundings.  In this specification it is assumed that all
     replaced elements - and only replaced elements - come with
     intrinsic dimensions.
"parent element"
     The containing element in SGML terminology.
"pseudo-element"
     Pseudo-elements are used in CSS selectors to address typographical
     items (e.g.  the first line of an element) rather than structural
     elements.
"pseudo-class"
     Pseudo-classes are used in CSS selectors to allow information
     external to the HTML source (e.g.  the fact that an anchor has been
     visited or not) to classify elements.
"property"
     A stylistic parameter that can be influenced through CSS.
"reader"
     The person for whom the document is rendered.
"replaced element"
     An element that the CSS formatter only knows the intrinsic
     dimensions of.  In HTML, IMG, INPUT, TEXTAREA, SELECT and OBJECT
     elements can be examples of replaced elements.  E.g., the content
     of the IMG element is often replaced by the image that the SRC
     attribute points to.  CSS1 does not define how the intrinsic
     dimensions are found.
"rule"
     A declaration (e.g.  'font-family: helvetica') and its selector
     (e.g.  'H1').
"selector"
     A string that identifies what elements the corresponding rule
     applies to.  A selector can either be a simple selector (e.g.
     'H1') or a contextual selector (e.g.  'H1 B') which consists of
     several simple selectors.
"SGML"
     Standard Generalized Markup Language, of which HTML is an
     application.
"simple selector"
     A selector that matches elements based on the element type and/or
     attributes, and not the element's position in the document
     structure.  E.g., 'H1.initial' is a simple selector.
"style sheet"
     A collection of rules.
"UA"
     User Agent, often a web browser or web client.
"user"
     Synonymous with reader.
"weight"
     The priority of a rule.

4.2 Basic Concepts
==================

Designing simple style sheets is easy.  One needs only to know a little
HTML and some basic desktop publishing terminology.  E.g., to set the
text color of 'H1' elements to blue, one can say:

       H1 { color: blue }

   The example above is a simple CSS rule.  A rule consists of two main
parts: selector ('H1') and declaration ('color: blue').  The declaration
has two parts: property ('color') and value ('blue').  While the example
above tries to influence only one of the properties needed for rendering
an HTML document, it qualifies as a style sheet on its own.  Combined
with other style sheets (one fundamental feature of CSS is that style
sheets are combined) it will determine the final presentation of the
document.

   The selector is the link between the HTML document and the style
sheet, and all HTML element types are possible selectors.

4.3 Pseudo-Classes/Elements
===========================

In CSS1, style is normally attached to an element based on its position
in the document structure.  This simple model is sufficient for a wide
variety of styles, but doesn't cover some common effects.  The concept
of pseudo-classes and pseudo-elements extend addressing in CSS1 to allow
external information to influence the formatting process.

   Pseudo-classes and pseudo-elements can be used in CSS selectors, but
do not exist in the HTML source.  Rather, they are "inserted" by the UA
under certain conditions to be used for addressing in style sheets.
They are referred to as "classes" and "elements" since this is a
convenient way of describing their behavior.  More specifically, their
behavior is defined by a fictional tag sequence.

   Pseudo-elements are used to address sub-parts of elements, while
pseudo-classes allow style sheets to differentiate between different
element types.

   The only support pseudo-classes in Emacs/W3 are on the anchor tag
(<a>...</a>).

   User agents commonly display newly visited anchors differently from
older ones.  In CSS1, this is handled through pseudo-classes on the 'A'
element:

       A:link { color: red }       /* unvisited link */
       A:visited { color: blue }   /* visited links */
       A:active { color: lime }    /* active links */

   All 'A' elements with an 'HREF' attribute will be put into one and
only one of these groups (i.e.  target anchors are not affected).  UAs
may choose to move an element from 'visited' to 'link' after a certain
time.  An 'active' link is one that is currently being selected (e.g.
by a mouse button press) by the reader.

   The formatting of an anchor pseudo-class is as if the class had been
inserted manually.  A UA is not required to reformat a currently
displayed document due to anchor pseudo-class transitions.  E.g., a
style 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
dynamically reformat the document when the reader selects the 'visited'
link.

   Pseudo-class selectors do not match normal classes, and vice versa.
The style rule in the example below will therefore not have any
influence:

       A:link { color: red }

       <A CLASS=link NAME=target5> ... </A>

   In CSS1, anchor pseudo-classes have no effect on elements other than
'A'. Therefore, the element type can be omitted from the selector:

       A:link { color: red }
       :link { color: red }

   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:

       A:link IMG { border: solid blue }

   Also, pseudo-classes can be combined with normal classes:

       A.external:visited { color: blue }

       <A CLASS=external HREF="http://out.side/">external link</A>

   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.

4.4 The Cascade
===============

In CSS, more than one style sheet can influence the presentation
simultaneously.  There are two main reasons for this feature: modularity
and author/reader balance.

modularity
     A style sheet designer can combine several (partial) style sheets
     to reduce redundancy:

            @import url(http://www.style.org/pastoral);
            @import url(http://www.style.org/marine);

            H1 { color: red }     /* override imported sheets */
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 UA is free to choose the mechanism for
     referencing personal style sheets.

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

  1. 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.
  2. Sort the declarations by explicit weight: declarations marked
     '!important' carry more weight than unmarked (normal) declarations.
  3. 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.
  4. 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:
            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 */
     Pseudo-elements and pseudo-classes are counted as normal elements
     and classes, respectively.
  5. 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.

   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:

     <STYLE TYPE="text/css">
       #x97z { color: blue }
     </STYLE>

     <P ID=x97z STYLE="color: red">

   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 UA may choose to honor other stylistic HTML attributes, for
example 'ALIGN'. If so, these attributes are translated to the
corresponding 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.

4.5 Properties
==============

In the text below, the allowed values for each property are listed with
a syntax like the following:

           Value: N | NW | NE
           Value: [ <length> | thick | thin ]{1,4}
           Value: <uri>? <color> [ / <color> ]?
           Value: <uri> || <color>

   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:

   * An asterisk (*) indicates that the preceding type, word or group is
     repeated zero or more times.
   * A plus (+) indicates that the preceding type, word or group is
     repeated one or more times.
   * A question mark (?)  indicates that the preceding type, word or
     group is optional.
   * 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.

   Other than the value the following information is also shown.

Supported Values:      If this is present, it lists the parts of the
                       specification that Emacs/W3 currently supports.
Unsupported Values:    If this is present, it represents the parts of
                       the specifcation that Emacs/W3 does not support.
Initial:               The default value for the property, unless
                       explicitly set in a stylesheet.
Applies to:            What type of elements this property can be
                       attached to.
Inherited:             Yes or no
Percentage values:     What a percentage value applies to when given.

4.5.1 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 Oblique, Slanted, Incline, Cursive or 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.

4.5.1.1 font-family
...................

Supported      [[<family-name> | <generic-family>],]* [<family-name> |
Values:        <generic-family>]
Initial:       User specific
Applies to:    all elements
Inherited:     yes
Percentage     N/A
values:
   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:

       BODY { font-family: gill, helvetica, sans-serif }

   There are two types of list values:

<family-name>
     The name of a font family of choice.  In the last example, "gill"
     and "helvetica" are font families.
<generic-family>
     In the example above, the last value is a generic family name.  The
     following generic families are defined:
        * 'serif' (e.g.  Times)
        * 'sans-serif' (e.g.  Helvetica)
        * 'cursive' (e.g.  Zapf-Chancery)
        * 'fantasy' (e.g.  Western)
        * 'monospace' (e.g.  Courier)

   Style sheet designers are encouraged to offer a generic font family
as a last alternative.

   Font names containing whitespace should be quoted:

       BODY { font-family: "new century schoolbook", serif }

       <BODY STYLE="font-family: 'My own font', fantasy">

   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.

4.5.1.2 font-style
..................

Supported      normal | italic | oblique
Values:
Initial:       normal
Applies to:    all elements
Inherited:     yes
Percentage     N/A
values:

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

       H1, H2, H3 { font-style: italic }
       H1 EM { font-style: normal }

   In the example above, emphasized text within 'H1' will appear in a
normal face.

4.5.1.3 font-variant
....................

Value:         normal | small-caps
Initial:       normal
Applies to:    all elements
Inherited:     yes
Percentage     N/A
values:

   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:

       H3 { font-variant: small-caps }
       EM { font-style: oblique }

   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.

4.5.1.4 font-weight
...................

Supported Values:      normal | bold | 100 | 200 | 300 | 400 | 500 |
                       600 | 700 | 800 | 900
Unsupported Values:    bolder | lighter
Initial:               normal
Applies to:            all elements
Inherited:             yes
Percentage values:     N/A

   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.

       P { font-weight: normal }   /* 400 */
       H1 { font-weight: 700 }     /* bold */

   The 'bolder' and 'lighter' values select font weights that are
relative to the weight inherited from the parent:

       STRONG { font-weight: bolder }

   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.

4.5.1.5 font-size
.................

Supported Values:      <absolute-size> | <length>
Unsupported Values:    <percentage> | <relative-size>
Initial:               medium
Applies to:            all elements
Inherited:             yes
Percentage values:     relative to parent element's font size

<absolute-size>
     An <absolute-size> keyword is an index to a table of font sizes
     computed and kept by the UA. Possible values are:
        * xx-small
        * x-small
        * small
        * medium
        * large
        * x-large
        * xx-large

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

   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:

       P { font-size: 12pt; }
       BLOCKQUOTE { font-size: larger }
       EM { font-size: 150% }
       EM { font-size: 1.5em }

   If the suggested scaling factor of 1.5 is used, the last three
declarations are identical.

4.5.1.6 font
............

Value:         [ <font-style> || <font-variant> || <font-weight> ]?
               <font-size> [ / <line-height> ]?  <font-family>
Initial:       not defined for shorthand properties
Applies to:    all elements
Inherited:     yes
Percentage     allowed on <font-size> and <line-height>
values:
   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.

       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 }

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

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

4.5.2.1 color
.............

Value:         <color>
Initial:       User specific
Applies to:    all elements
Inherited:     yes
Percentage     N/A
values:

   This property describes the text color of an element (often referred
to as the foreground color).  There are different ways to specify red:

       EM { color: red }              /* natural language */
       EM { color: rgb(255,0,0) }     /* RGB range 0-255   */

   See Color Units for a description of possible color values.

4.5.2.2 background-color
........................

Value:         <color> | transparent
Initial:       transparent
Applies to:    all elements
Inherited:     no
Percentage     N/A
values:

   This property sets the background color of an element.

       H1 { background-color: #F00 }

4.5.2.3 background-image
........................

Value:         <url> | none
Initial:       none
Applies to:    all elements
Inherited:     no
Percentage     N/A
values:

   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.

       BODY { background-image: url(marble.png) }
       P { background-image: none }

4.5.2.4 background-repeat
.........................

This property is not supported at all under Emacs/W3.

4.5.2.5 background-attachment
.............................

This property is not supported at all under Emacs/W3.

4.5.2.6 background-position
...........................

This property is not supported at all under Emacs/W3.

4.5.2.7 background
..................

Value:         <background-color> || <background-image> ||
               <background-repeat> || <background-attachment> ||
               <background-position>
Initial:       not defined for shorthand properties
Applies to:    all elements
Inherited:     no
Percentage     allowed on <background-position>
values:

   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.

       BODY { background: red }
       P { background: url(chess.png) gray 50% repeat fixed }

   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.

4.5.3 Text Properties
---------------------

4.5.3.1 word-spacing
....................

Supported Values:      normal
Unsupported Values:    <length>
Initial:               normal
Applies to:            all elements
Inherited:             yes
Percentage values:     N/A

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

       H1 { word-spacing: 0.4em }

   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.

4.5.3.2 letter-spacing
......................

Supported Values:      normal
Unsupported Values:    <length>
Initial:               normal
Applies to:            all elements
Inherited:             yes
Percentage values:     N/A

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

       BLOCKQUOTE { letter-spacing: 0.1em }

   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.

4.5.3.3 text-decoration
.......................

Supported Values:      none | underline | line-through | blink
Unsupported Values:    overline
Initial:               none
Applies to:            all elements
Inherited:             no, but see clarification below
Percentage values:     N/A

   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.

       A:link, A:visited, A:active { text-decoration: underline }

   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.

4.5.3.4 vertical-align
......................

This is currently unsupported in Emacs/W3.

4.5.3.5 text-transform
......................

Supported Values:      none
Unsupported Values:    capitalize | uppercase | lowercase
Initial:               none
Applies to:            all elements
Inherited:             yes
Percentage values:     N/A

'capitalize'
     Uppercases the first character of each word.
'uppercase'
     Uppercases all letters of the element.
'lowercase'
     Lowercases all letters of the element.
'none'
     Neutralizes inherited value.

   The actual transformation in each case is human language dependent.

       H1 { text-transform: uppercase }

   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.

4.5.3.6 text-align
..................

Value:         left | right | center | justify
Initial:       User specific
Applies to:    block-level elements
Inherited:     yes
Percentage     N/A
values:

   This property describes how text is aligned within the element.  The
actual justification algorithm used is UA and human language dependent.

   Example:
       DIV.center { text-align: center }

   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.

4.5.3.7 text-indent
...................

Not currently implemented in Emacs/W3.

4.5.3.8 line-height
...................

Not currently implemented in Emacs/W3.

4.5.4 Box Properties
--------------------

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

4.5.5.1 display
...............

Value:         block | inline | list-item | none
Extensions:    line
Initial:       inline
Applies to:    all elements
Inherited:     no
Percentage     N/A
values:

   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.

       P { display: block }
       EM { display: inline }
       LI { display: list-item }
       IMG { display: none }

   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 BR and HR
elements within a stylesheet.

   NOTE: Emacs/W3 defaults to using 'inline' for this property, which is
a slight deviation from the specification.

4.5.5.2 white-space
...................

Value:         normal | pre | nowrap
Initial:       normal
Applies to:    block-level elements
Inherited:     yes
Percentage     N/A
values:

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

       PRE { white-space: pre }
       P   { white-space: normal }

4.5.5.3 list-style-type
.......................

Value:         disc | circle | square | decimal | lower-roman |
               upper-roman | lower-alpha | upper-alpha | none
Initial:       disc
Applies to:    elements with 'display' value 'list-item'
Inherited:     yes
Percentage     N/A
values:

   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:
       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. */

4.5.5.4 list-style-image
........................

Value:         <url> | none
Initial:       none
Applies to:    elements with 'display' value 'list-item'
Inherited:     yes
Percentage     N/A
values:

   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.

       UL { list-style-image: url(http://png.com/ellipse.png) }

4.5.5.5 list-style-position
...........................

Supported Values:      outside
Unsupported Values:    inside
Initial:               outside
Applies to:            elements with 'display' value 'list-item'
Inherited:             yes
Percentage values:     N/A

   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.

4.5.5.6 list-style
..................

Value:         <keyword> || <position> || <url>
Initial:       not defined for shorthand properties
Applies to:    elements with 'display' value 'list-item'
Inherited:     yes
Percentage     N/A
values:

   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.

       UL { list-style: upper-roman inside }
       UL UL { list-style: circle outside }
       LI.square { list-style: square }

   Setting 'list-style' directly on 'LI' elements can have unexpected
results.  Consider:

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

   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:

       OL.alpha  { list-style: lower-alpha }
       UL        { list-style: disc }

   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:

       UL { list-style: url(http://png.com/ellipse.png) disc }

   In the example above, the 'disc' will be used when the image is
unavailable.

4.5.6 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 @media directive.

   The @media directive takes two arguments, the media type, and a block
of style declarations.

       @media print {
         BODY { font-size: 10pt }
         H1 { font-size: 14pt }
       }
   The '@media' construct also allows to put include style sheet rules
for various media in the same style sheet:

       @media print {
         BODY { font-size: 10pt }
       }
       @media screen {
         BODY { font-size: 12pt }
       }

   Currently, the following media types are defined.
Print
     Output for paged opaque material, and for documents viewed on
     screen in print preview mode.
Screen
     A continuous presentation for computer screens.
Projector
     Paged presentation for projected presentations.
Braille
     For braille tactile feedback devices.
Speech
     Aural presentation.
Light
     The stylesheet will only be applied if the user is using a light
     background.
Dark
     The stylesheet will only be applied if the user is using a dark
     background.
Emacs
     The stylesheet will only be applied if the user is running in Emacs
     19.
XEmacs
     The stylesheet will only be applied if the user is running in
     XEmacs 19.
All
     The default value, the style sheet applies to all output devices.

4.5.7 Speech Properties
-----------------------

Those of us who are sighted are accustomed to visual presentation of
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:

   * Allows orthogonal aural and visual views.
   * Allows browsers to optionally implement both aural and visual views
     to produce truly multimodal documents.

4.5.7.1 volume
..............

Value:         <percentage> | mute | x-soft | soft | medium | loud |
               x-loud
Initial:       medium
Applies to:    all elements
Inherited:     yes
Percentage     relative to user-specified mapping
values:

   The legal range of percentage values is 0% to 100%.  There is a fixed
mapping between keyword values and percentages:

   * 'x-soft' = '0%'
   * 'soft' = '25%'
   * 'medium' = '50%'
   * 'loud' = '75%'
   * 'x-loud' = '100%'

   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:

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

   The same authors stylesheet could be used in all cases, simply by
mapping the 0 and 100 points suitably at the client side.

4.5.7.2 pause-before
....................

Value:         <time> | <percentage>
Initial:       UA specific
Applies to:    all elements
Inherited:     no
Percentage     speed
values:

   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.

4.5.7.3 pause-after
...................

Value:         <time> | <percentage>
Applies to:    all elements
Inherited:     no
Percentage     speed
values:

   This property specifies the pause after elements.  Values are
specified the same way as 'pause-before'.

4.5.7.4 pause
.............

Value:         [<time> | <percentage> ]{1,2};
Applies to:    all elements
Inherited:     no
Percentage     speed
values:

   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:

       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 */

4.5.7.5 cue-before
..................

Value:         <url> | none
Initial:       none
Applies to:    all elements
Inherited:     no
   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:

       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 */

4.5.7.6 cue-after
.................

See cue-before.

4.5.7.7 cue
...........

See cue-before.

4.5.7.8 cue-during
..................

Value:         <url> | mix | none
Initial:       mix
Applies to:    all elements
Inherited:     no
   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:

       BLOCKQUOTE.sad { cue-during: url(violins.aiff) }

4.5.7.9 speed
.............

Value:         <words-per-minute> | x-slow | slow | medium | fast |
               x-fast | faster | slower
Initial:       medium
Applies to:    all elements
Inherited:     yes

   Specifies the speaking rate.  Note that both absolute and relative
keyword values are allowed (compare with font-weight).

4.5.7.10 voice-family
.....................

Value:         [[<specific-voice> | <generic-voice>],]*
               [<specific-voice> | <generic-voice>]
Initial:       device-specific
Applies to:    all elements
Inherited:     yes

   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

       H1 { voice-family: announcer, male }
       P.part.romeo { voice-family: romeo, male }
       P.part.juliet { voice-family: juliet, female }

4.5.7.11 pitch
..............

4.5.7.12 pitch-range
....................

4.5.7.13 stress
...............

Value:         <percentage>
Initial:       medium
Applies to:    all elements
Inherited:     yes

   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.

4.5.7.14 richness
.................

Value:         <percentage>
Initial:       medium (50%)
Applies to:    all elements
Inherited:     yes

   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.

4.5.7.15 speak-punctuation
..........................

Value:         code | none
Initial:       none
Applies to:    all elements
Inherited:     yes

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

4.5.7.16 speak-date
...................

Value:         myd | dmy | ymd | none
Initial:       none
Applies to:    all elements
Inherited:     no

   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.

4.5.7.17 speak-numeral
......................

Value:         digits | continous
Initial:       none
Applies to:    all elements
Inherited:     yes

4.5.7.18 speak-time
...................

Value:         24 | 12 | none
Initial:       none
Applies to:    all elements
Inherited:     yes

4.6 Units
=========

4.6.1 Length Units
------------------

4.6.2 Percentage Units
----------------------

4.6.3 color Units
-----------------

4.6.4 URLs
----------

4.6.5 Angle Units
-----------------

These are the legal angle units:
   * deg: degrees
   * grad
   * rad: radians

4.6.6 Time Units
----------------

These are the legal time units:

   * ms: milliseconds
   * s: seconds

5 Supported URLs
****************

::WORK:: List supported URL types, specific RFCs, etc.

   "Uniform Resource Locators" (URLs) are a specific form of "Uniform
Resource Identifiers" (URI) described in RFC2396 which updates RFC1738
and RFC1808.

   RFC2016 defines uniform resource agents.

   URI have the form SCHEME:SCHEME-SPECIFIC-PART, where SCHEME appears
in the menu below for URLs supported by Emacs/W3.

   FTP, NFS, HTTP, HTTPS, 'rlogin', 'telnet', tn3270, IRC and gopher
URLs all have the form SCHEME://[USERINFO@]HOSTNAME[:PORT][/PATH] where
'[' and ']' delimit optional parts.  USERINFO sometimes takes the form
USERINFO:PASSWORD but you should beware of the security risks of sending
cleartext passwords.  HOSTNAME may be a domain name or a dotted decimal
address.  If the ':PORT' is omitted then Emacs/W3 will use the well
known port for that service.  With the possible exception of 'telnet',
it is very rare for ports to be specified, and it is possible using a
non-standard port may have undesired consequences if a different service
is listening on that port (eg.  a gopher URL specifying the SMTP port
can cause mail to be sent), but url-bad-port-list.
The meaning of the PATH component depends on the service.

5.1 File URLs
=============

This allows Emacs/W3 to read arbitary files from hosts.  Compressed
files are handled, but support is hard-coded so that
'jka-compr-compression-info-list' and so on have no affect.  Suffixes
recognized are '.z', '.gz' and '.Z'.  If the URL points to a directory,
then it will try to retrieve a file named by 'url-directory-index-file'
('index.html' by default) and parse it, otherwise you get a directory
listing in 'dired' mode.  If the URL refers to a file on a remote host,
then Emacs/W3 uses 'ange-ftp' (see ange-ftp) or 'efs' (see
efs) to retrive the file.  ftp:// and file:// are synonymous for
Emacs/W3.

5.2 FTP URLs
============

For details of usage see file.  In Emacs/W3 file and FTP URLs
are synonymous and files on the localhost are retrieved directly rather
than by FTP.  Emacs/W3 relies on 'ange-ftp' (see ange-ftp) or
'efs' (see efs) to do the actual transfers.

5.3 NFS URLs
============

gdj1: have I misunderstood the point of this?  Since NFS is fairly
transparent to the user (at least when it's working), there isn't very
much to say here.  An nfs URL is similar to a file URL except that it
points to a file on a remote host that is handled by the automounter on
the local host.  The variable 'url-nfs-automounter-directory-spec' may
need to be tweaked depending on local configuration.  The NFS URL is
defined in RFC2224.

5.4 info
========

Info URLs are not an officially recognised URL (gdj1: is this right?),
but Emacs/W3 will parse them to produce a reference to a TeXinfo node,
or 'Top' if one is not specified.  'Info-mode' will be used to browse
the document.

5.5 http/https
==============

The HyperText Transfer Protocol is the protocol used to get documents
from the World Wide Web.  Emacs/W3 supports HTTP version 1.0 as defined
in RFC1945 -- now superseded by version 1.1 defined in RFC2068.

   If 'url-honor-refresh-requests' is 'nil' then 'Refresh' headers will
not be honoured, if 't' then they will always be honoured, otherwise the
user will be asked for each request.  The default is 't'.
'url-be-anal-about-file-attributes' controls whether HTTP is used to
discover file attributes, or whether they're just guessed.  The default
is 'nil' which means that Emacs/W3 will make educated guesses.

   HTTPS is a secure version of HTTP defined in RFC2069 (gdj1: ?).
Emacs/W3 requires SSL to handle this, see Installing SSL.

5.6 mailto
==========

A mailto URL will send an email message to the address in the URL, for
example 'mailto:foo@bar.com' would compose a message to foo@bar.com.
Emacs/W3 uses the command specified by the 'url-mail-command' variable
to compose the email, this is 'url-mail' by default which uses Gnu's
'message' mode (see Message (message)) if available, otherwise
the standard 'mail' command.  An X-Url-From header field containing the
URL of the document that contained the mailto URL is added, as is an
X-Mailer header field containing the version of Emacs/W3 being used.

   RFC2368 extends the definition of mailto URLs in RFC1738.  The form
of a mailto URL is 'mailto:MAILBOX[?HEADER=CONTENTS[&HEADER=CONTENTS]]'
where an arbitary number of HEADERs can be added.  If the HEADER is
'body', then CONTENTS is put in the body otherwise a HEADER header field
is created with CONTENTS as its contents.  Note that Emacs/W3 does not
consider any headers as 'dangerous' so you should check them before
sending the message.

   Email messages are defined in RFC822.

5.7 mailserver
==============

A mailserver URL allows you to send an email to a person, but this URL
optionally specifies a subject and a body.  The basic format is
'mailserver:[MAILBOX/SUBJECT[/BODY]'.  Thus,
'mailserver:foo@bar.com/wibble/flibble' will compose a message to
foo@bar.com with SUBJECT as the subject and BODY already in the body of
the email.  Note that both the subject and the body are "hex"ed, but the
subject cannot contain newlines.

5.8 news/nntp/snews
===================

If the URL doesn't specify a host, then the host in 'url-news-server'
will be used, and unless the URL has a port the news port as defined in
'url-default-ports' (119) will be used.  The username and password
specified in the URL will be used if present.  The URL may contain a
message-id, in which case that article is displayed; it may contain a
newsgroup in which case Gnus is used to display the newsgroup; or it may
by empty in which case Gnus is called with no arguments.  Emacs/W3
requires Gnus v5.x or Red, Quassia or Pterodactyl Gnus, see
gnus.  The variable 'url-news-use-article-mode' controls the
displaying of news articles; if non-'nil' then articles are displayed in
Gnus article mode, otherwise they are turned into HTML and rendered by
Emacs/W3.

   An NNTP URL is the same as a news URL, except that the URL may
specify an article by its number.

5.9 rlogin/telnet/tn3270
========================

To handle rlogin, telnet and tn3270 URLs, Emacs/W3 runs an 'rlogin',
'telnet' or 'tn3270' session (the program names and arguments are
hardcoded) in a 'terminal-emulator' buffer.  Well-known ports are used
if the URL does not specify a port.

5.10 irc
========

"Internet Relay Chat" (IRC) is handled by handing off the IRC session to
a function named in 'url-irc-function'.  This function must take five
argumenst, HOST, PORT, CHANNEL, USER and PASSWORD.  The CHANNEL argument
specifies the channel to join immediately, this can be 'nil'.  By
default this is 'url-irc-zenirc' which processes the arguments and lets
'zenirc' handle the session.

5.11 data
=========

Data URLs contain MIME data in the URL itself, by default the data is
8bit encoded 'text/plain', but the URL can specify either or both the
content-type and the encoding.  Emacs/W3 will parse the URL's data as
MIME and display it appropriately.  See MIME Support.

5.12 gopher
===========

"Gopher" (Go for) was in someways the precurser to the world wide web
and is becoming rarer as the web becomes more powerful.  Nevertheless,
there are still many gopher sites around and Emacs/W3 supports this
protocol (of course).  The variable 'url-gopher-labels' maps gopher
types to something else (gdj: ?)  for displaying the gopher menus.
'url-gopher-icons' maps gopher types to pictures.  'url-gopher-to-mime'
maps gopher types to MIME types.  If 'url-use-hypertext-gopher' is
non-'nil', then gopher pages will be turned into HTML for Emacs/W3 to
parse and display normally, otherwise Emacs/W3 will let 'gopher.el'
handle all gopher requests which will lose gopher+ support and inlined
searching.  This is 't' by default.

5.13 finger
===========

Finger URLs will finger a given user at a given host, or 'localhost' if
no host is specified, processing the results to create an HTML page for
Emacs/W3 to display.

5.14 netrek
===========

This is unsupported at present.

6 MIME Support
**************

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

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

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

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

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

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

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

  1. '~/.mime-types'
  2. '/etc/mime-types'
  3. '/usr/etc/mime-types'
  4. '/usr/local/etc/mime-types'
  5. '/usr/local/www/conf/mime-types'

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

   type/subtype ext1 ext2 ...  extN

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

6.2 Specifying Viewers
======================

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

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

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

7 Security
**********

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

Basic Authentication
     The weakest authentication available, not recommended if serious
     security is necessary.  This is simply a string that looks like
     'user:password' that has been Base64 encoded, as defined in RFC
     1421.
Digest Authentication
     Jeffery L. Hostetler, John Franks, Philip Hallam-Baker, Ari
     Luotonen, Eric W. Sink, and Lawrence C. Stewart have an internet
     draft for a new authentication mechanism.  For the complete
     specification, please see draft-ietf-http-digest-aa-01.txt in the
     nearest internet drafts archive(1).
SSL Encryption
     SSL is the 'Secure Sockets Layer' interface.  Emacs/W3 supports
     HTTP transfers over an SSL encrypted channel, if the appropriate
     files have been installed.  See Installing SSL.

7.1 Privacy
===========

Sometimes you don't want people to know who you are, or where you've
been.  HTTP is quite happy to tell everyone it meets who you are and
where you've come from.  'url-privacy-level' can be used to set how much
information is given, it can be a list of the following symbols

'email'
     Do not send email address.  This just sets
     'url-personal-mail-address' to 'nil'.
'os'
     Do not send operating system
'lastloc'
     Do not send the last location
'agent'
     Do not send the User-Agent string (for an alternative approach,
     see Masquerading).
'cookie'
     Never accept cookies (see Cookies)

   Alternatively 'url-privacy-level' can be a single symbol,
'none'
     Send all information.
'low'
     Don't send the last location.  Equivalent to '(lastloc)'
'high'
     Don't send the email address or last location.  Equivalent to
     '(email lastloc)'
'paranoid'
     Don't send anything.  Equivalent to '(email os lastloc agent
     cookie)'

   If you change 'url-privacy-level' then you should also call
'url-setup-privacy-info' to make sure that the changes propogate.

   ---------- Footnotes ----------

   (1) One is ftp://ds.internic.net/internet-drafts

8 Cookies
*********

HTTP is a stateless protocol which means that the server sees every
request for pages independently with no idea of how it relates to any
other request.  Therefore the server has no idea whether or not you've
seen a page before, or whether you've registered (if that's an option).
Cookies(1) are used to add state to HTTP sessions.  Cookies are defined
in RFC2109.

   Cookies are saved in the file specified in 'url-cookie-file', which
is 'W3-CONFIGURATION-DIRECTORY/cookies' by default.  Note that this file
should probably not be world writable, and possibly not even world
readable.

   Some people see cookies as an invasion of privacy while others see
them as a product of badly designed websites and buggy servers.
Emacs/W3 lets you unconditionally reject all cookies by adding 'cookie'
to 'url-privacy-level' or setting it to 'paranoid' (see Security)
but for those who want finer control over what to accept and reject,
Emacs/W3 offers 'url-cookie-trusted-urls' and
'url-cookie-untrusted-urls' which are lists of regular expressions that
match URLs from which cookies should be accepted and rejected
respectively.  If a URL matches patterns in both of these, then Emacs/W3
decides whether to accept or not based on the most specific match (the
most specific match being the shortest match).  Note that Emacs/W3 only
considers the first match for each variable, so the regular expressions
should be in increasing order of generality.

   For even more control over which cookies are accepted, you can set
'url-cookie-confirmation' to non-'nil', in which case every time a
cookie is offered Emacs/W3 will ask if you want to accept it.  This only
applies to cookies that would otherwise be accepted, Emacs/W3 will still
reject cookies from URLs matched in 'url-cookie-untrusted-urls'.

   ---------- Footnotes ----------

   (1) In computer terms a "cookie" is data that a program holds but
which has no meaning in itself.  Cookies are not processed by the
program (indeed the program may not even know what data they hold or
what format it's in) but is passed to libraries or servers which do
understand it.

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

9.1 VMS
=======

:: WORK :: VMS Specific instriuctions

9.2 OS/2
========

:: WORK :: OS/2 Specific instructions

9.3 MS-DOS
==========

:: WORK :: DOS Specific instructions

9.4 Windows
===========

:: WORK :: 32bit Windows Specific instructions

10 Speech Integration
*********************

:: WORK :: Emacspeak integration

11 Advanced Features
********************

11.1 Disk Caching
=================

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

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

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

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

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

11.2 Printing
=============

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

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

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

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

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

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

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

     :: WORK :: Document the new LaTeX backend

     'w3-latex-use-latex2e'
          If non-'nil', configures the LaTeX engine to use the LaTeX2e
          syntax.  A 'nil' value indicates that LaTeX 2.0.9
          compabibility will be used instead.
     'w3-latex-docstyle'
          The document style to use when printing or mailing converted
          HTML files in LaTeX.
     'w3-latex-packages'
          List of LaTeX packages to include.  Currently this is only
          used if 'w3-latex-use-latex2e' is non-'nil'.
     'w3-latex-use-maketitle'
          If non-'nil', the LaTeX engine will use real LaTeX title pages
          for document titles.
     'w3-latex-print-links'
          If non-'nil', prints the URLs of hypertext links as endnotes
          at the end of the document.  If set to 'footnote', prints the
          URL's as footnotes on each page.

11.3 Interfacing to Mail/News
=============================

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

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

   To access URLs from within RMAIL, the following hook should do the
trick.
     (add-hook 'rmail-mode-hook
     	  (function
     	   (lambda ()
     	     (define-key rmail-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
     	     (define-key rmail-mode-map "\r"      'w3-maybe-follow-link))))

11.4 Debugging HTML
===================

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

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

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

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

11.5 Hooks
==========

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

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

11.6 Miscellaneous variables
============================

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

'url-bad-port-list'
     List of ports to warn the user about connecting to.  Defaults to
     just the mail, NNTP and chargen ports so a malicious HTML author
     cannot spoof mail or news to other people.
'url-confirmation-func'
     What function to use for asking yes or no functions.  Possible
     values are ''yes-or-no-p' or ''y-or-n-p', or any function that
     takes a single argument (the prompt), and returns 't' only if a
     positive answer is gotten.  Defaults to ''yes-or-no-p'.

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

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

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

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

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

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

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

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

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

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

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

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

'url-inhibit-mime-parsing'
     This controls whether to parse MIME headers in a message.  If it is
     'nil' then the headers are parsed and deleted.

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

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

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

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

'w3-documentation-root'
     This specifies the location of the Emacs/W3 documentation, it
     _must_ end in a slash.

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

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

'w3-use-menus'
     If 'w3-use-menus' is 'nil' then Emacs/W3 will not provide a menu
     interface.  If it is '1', then Emacs/W3 will add a 'W3' item to the
     Emacs menubar.  If it is a list then Emacs/W3 will add its own
     menubar.  The following symbols may appear in the list to control
     what Emacs/W3 puts in its menubar.
     'file'
          A list of file related commands
     'edit'
          Various standard editing commands (copy/paste)
     'view'
          Controlling various things about the document view
     'go'
          Navigation control
     'bookmark'
          Bookmark / hotlist control
     'options'
          Various options
     'buffers'
          The standard buffers menu
     'emacs'
          A toggle button to switch back to normal emacs menus
     'style'
          Control style information and who gets to set what
     'search'
          Various search engines
     'help'
          The help menu
     'nil'
          This may appear once in the list.  All menus after this will
          be displayed flush right.

12 More Help
************

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

   * w3-announce - this list is for anyone interested in Emacs/W3, and
     should in general only be used by me.  The gnu.emacs.sources
     newsgroup and a few other mailing lists are included on this.
     Please only use this list for major package releases related to
     Emacs/W3.  (www-announce@w3.org is included on this list).
   * w3-beta - this list is for beta testers of Emacs/W3.  These brave
     souls test out not-quite stable code.
   * w3-dev - a list consisting of myself and a few other people who are
     interested in the internals of Emacs/W3, and doing active
     development work.  Pretty dead right now, but I hope it will grow.

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

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

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

13 Future Directions
********************

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

   BUGS (4.0):
   - need to support HTTP/0.9 (http://c2.com:8080) responses
   - /etc/mailcap cannot overide builtin mm-mime-data stuff?
   - try to protect people from using '~' in file URLs
   - keystrokes entered while in w3-pause self-insert under XEmacs --
     the loop around dispatch-event needs to be smarter about what it
     swallows.
   - border-color can have multiple color specifications, but we
     currently choke with 'args out of range' when we see this.
   - widget appears to be stealing button3 to mean 'activate' -- this is
     bogus!  We lose all context-sensitive menus because of this.
   - We still seem to be growing the line size under Emacs 19.x/20.x
   - It would be really nice if w3 buffers were put into w3-mode as soon
     as they were created.  Then if the rendering craps out somehow then
     the buffer could be browsed such as it was.  Ideally, links and
     widgets would be functional.
   - document how to translate Netscape foo.pac files to emacs lisp
   - Should we stop using reporter.el?

   BUGS (4.1):
   - background colors are not heeded on table rows (<tr>).  Same
     properties on individual cells or the table as a whole work fine.
   - <br> in <dd> hosed -- margins in general tend to be too big
     sometimes.
   - client side imagemaps have to be in the same buffer (actually in
     the smae buffer, _BEFORE_ the usemap directive on an image) -- fix
     to be able to use imagemaps in different files, any position, etc,
     etc.

   FEATURES (4.1)
   - cache a formatted version of documents, with enough info to
     recreate the widgets in them.
   - w3-preview-region command
   - LDAP support (XEmacs)
   - New proxy type for sending requests via mail to a mail->web->mail
     gateway.
   - Emacspeak Interaction

        * some way of specifying in a stylesheet whether certain text is
          inaudible.  use the 'inaudible text property for this.
        * Full Aural-CSS support

   - more sophisticated filling algorithm.  I'm not sure exactly what
     would be sufficient but breaking lines after punctuation seems like
     it would solve most of the problem.
   - When fetching images for viewing (not inlining), W3 should at least
     have an option of displaying it inline, ala Netscape.
   - Widget library merging

        * Write a font selection widget
        * Write a voice selection widget
        * Write a mailcap entry widget

   - Custom library merging
        * Add custom support for MM
   - Hotlist handling

        * Abstract out current support
        * Do something similar to GNUS 'backends' to provide easy way to
          add new bookmark formats, etc.

   - Write a new major mode for handling CSS style sheets

   FEATURES (5.0)

   - Emacspeak Integration

        * Need option to turn off table rendering and print it out as a
          table that is viewable with emacspeak-table-ui.el

   - Write a text/xml parser
   - Completely rewrite display code again

        * Abstract everything out to follow parse->flow objects->render
          model
        * Base all stylesheet stuff off of DSSSL
        * CSS2
        * New rendering backends

             - Native postscript output
             - LaTeX upgrade
             - TeXinfo

   - Display code

        * implement <spacer> from netscape 3.0b5
        * reimplement w3-show-headers
        * Handle math environment using the calc library
        * Better integration with the parser

Appendix A Reporting Bugs
*************************

If any bugs are discovered in Emacs/W3, please report them to the
mailing list w3-beta@xemacs.org -- this is where the brave souls who
beta test the latest versions of Emacs/W3 reside, and are generally very
responsive to bug reports.  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 '<w>' key when in
an Emacs/W3 buffer, or you can use <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 '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 'xwd' program under X-windows for
this, or <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 gnu.emacs.bug newgroup for reporting bugs with GNU
Emacs 19, and 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'.

Appendix B Dealing with Firewalls
*********************************

By default, Emacs can support standard TCP/IP network connections on
almost all the platforms it runs on (Unix, VMS, Windows, etc).  However,
there are several situations where it is not sufficient.

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 MIS department.)

Emacs cannot resolve hostnames.
     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 (<http://129.79.254.191/> works, but
     <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 '-lresolv'.

     If you do not have the disk space or the appropriate permissions to
     recompile Emacs, another alternative is using the 'nslookup'
     program to do hostname resolution.  To turn this on, set the
     variable 'url-gateway-broken-resolution' in your '~/.emacs' file.
     This runs the program specified by 'url-gateway-nslookup-program'
     (by default "'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
     'nslookup' program:

          Name: www.cs.indiana.ed
          Address: 129.79.254.191

Using TERM (or TERM-like) Networking Software
     TERM (1) 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'
     definition to include the 'termnet' library that comes with the
     latest versions of TERM.

     If you run into any problems with the native TERM networking
     support in Emacs or XEmacs, please let wmperry+w3@cs.indiana.edu
     know, as he is responsible for the original support.

   Emacs/W3 has support for using the gateway mechanism for certain
domains, and directly connecting to others.  The variable
'url-gateway-local-host-regexp' controls this behaviour.  This is a
regular expression (2) that matches local hosts that do not require the
use of a gateway.  If 'nil', then all connections are made through the
gateway.

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

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

     'url-gateway-telnet-host'
          The gateway host to telnet to.  Once logged in there, you then
          telnet out to the hosts you want to connect to.
     'url-gateway-telnet-parameters'
          This should be a list of parameters to pass to the 'telnet'
          program.
     'url-gateway-telnet-password-prompt'
          This is a regular expression that matches the password prompt
          when logging in.
     'url-gateway-telnet-login-prompt'
          This is a regular expression that matches the username prompt
          when logging in.
     'url-gateway-telnet-user-name'
          The username to log in with.
     'url-gateway-telnet-password'
          This is the password to send when logging in.
     'url-gateway-prompt-pattern'
          This is a regular expression that matches the shell prompt.

"rlogin"
     This method is identical to the 'telnet' method, but uses 'rlogin'
     to log into the remote machine without having to send the username
     and password over the wire every time.

     'url-gateway-rlogin-host'
          Host to 'rlogin' to before telnetting out.
     'url-gateway-rlogin-parameters'
          Parametres to pass to 'rsh'.
     'url-gateway-rlogin-user-name'
          User name to use when logging in to the gateway.
     'url-gateway-prompt-pattern'
          This is a regular expression that matches the shell prompt.

"tcp"
     Masanobu UMEDA (umerin@mse.kyutech.ac.jp) has written a very small
     application that you can run in a subprocess to do the network
     connections.

"SOCKS"
     Use if the firewall has a SOCKS gateway running on it.  SOCKS v5
     protocol is defined in RFC1928.

     'socks-password'
          If this is 'nil' then you will be asked for the passward,
          otherwise it will be used as the password for authenticating
          you to the SOCKS server.

     'socks-username'
          This is the username to use when authenticating yourself to
          the SOCKS server.  By default this is your login name

     'socks-timeout'
          This controls how long, in seconds, Emacs/W3 will wait for
          responses from the SOCKS server; it is 5 by default.

     'socks-server'
          Thiss the default server, it take the form ('"Default server"'
          SERVER PORT VERSION) where VERSION can be either 4 or 5.

     'socks-server-aliases'
          This a list of server aliases.  It is a list of aliases of the
          form '(alias hostname port version)'.

     'socks-network-aliases'
          This a list of network aliases.  Each entry in the list takes
          the form '(alias (network))' where ALIAS is a string that
          names the NETWORK.  The networks can contain a pair (not a
          dotted pair) of IP addresses which specify a range of IP
          addresses, an IP address and a netmask, a domain name or a
          unique hostname or IP address.

     'socks-redirection-rules'
          This a list of redirection rules.  Each rule take the form
          '(Destination network Connection type)' where DESTINATION
          NETWORK is a network alias from 'socks-network-aliases' and
          CONNECTION TYPE can be 'nil' in which case a direct connection
          is used, or it can be an alias from 'socks-server-aliases' in
          which case that server is used as a proxy.

     'socks-nslookup-program'
          This the 'nslookup' program.  It is 'nslookup' by default.

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

   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.

   ---------- Footnotes ----------

   (1) TERM is a user-level protocol for emulating IP over a serial
line.  More information is available at
<ftp://sunsite.unc.edu/pub/Linux/apps/comm/term>

   (2) Please see the full Emacs distribution for a description of
regular expressions

Appendix C Proxy Gateways
*************************

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

   For companies with internal intranets, it will usually be helpful to
define a list of hosts that should be contacted directly, not sent
through the proxy.  The '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:

     NO_PROXY=*.aventail.com,home.com,*.seanet.com

   tells Emacs/W3 to contact all machines in the aventail.com and
seanet.com domains directly, as well as the machine named home.com.

   For those adventurous souls who enjoy writing regular expressions,
all the proxy settings can be manipulated from Emacs-Lisp.  The variable
'url-proxy-services' controls this.  This is an assoc list, keyed on the
protocol type (HTTP, gopher, etc) in all lowercase.  The 'cdr' of each
entry should be the ADDRESS of the proxy server to contact, followed by
":" and the port number to use.  In the case of the special "no_proxy"
entry, it should be a regular expression that matches any hostnames that
should be contacted directly.

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

Appendix D Installing SSL
*************************

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.
For best results, you should apply a patch that makes the SSLeay client
much quieter about what it reports.

   You can download SSLeay from <ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/>

   The following variables control how the external program is invoked.

'ssl-program-name'
     The name of the program to run, as a string.

          (setq ssl-program-name "s_client")

'ssl-program-arguments'
     This should be used if your SSL program needs command line switches
     to specify any behaviour (certificate file locations, etc).  This
     is a list of strings and symbols.

     The special symbols 'host and 'port may be used in the list of
     arguments and will be replaced with the hostname and service/port
     that will be connected to.

          (setq ssl-program-arguments '("-host" host
                                        "-port" service
                                        "-verify" "4"
                                        "-CApath /usr/local/ssl/certs"))
   The default is ("-host" host "-port" service "-verify"
SSL-CERTIFICATE-VERIFICATION-POLICY -CApath SSL-CERTIFICATE-DIRECTORY).

   'ssl-certificate-directory' is the directory in which CA certificates
are stored.  It is 'W3-CONFIGURATION-DIRECTORY/cert' by default.

   'ssl-rehash-program-name' is the program that is run after adding a
certificate to the 'ssl-certificate-directory' directory.  It is run
with the directory name as an argument and defaults to 'c_rehash'.

   'ssl-view-certificate-program-name' names the program that can
produce a human-readable view of a certificate.  It is 'x509' by default
and is called with the arguments listed in
'ssl-view-certificate-program-arguments' which is '("text" "-inform"
"DER")' by default.

   'ssl-certificate-directory-style' specifies the type of certificate
database to use.  It's default (and at the moment, only possible value)
is 'ssleay' which specifies a directory or pem encoded certificates with
hash symlinks.

   You can decide how high up the chain of certificates should be
verified by setting 'ssl-certificate-verification-policy'.  Possible
values are
0
     No verification
1
     Verification required
3
     Reject connection if verification fails
5
     SSL_VERIFY_CLIENT_ONCE
   The default is 0

Appendix E Mailcap Files
************************

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

  1. '~/.mailcap'
  2. '/etc/mailcap'
  3. '/usr/etc/mailcap'
  4. '/usr/local/etc/mailcap'

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

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

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

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

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

   The optional fields, which may be given in any order, are as follows:
   * The "compose" field may be used to specify a program that can be
     used to compose a new body or body part in the given format.  Its
     intended use is to support mail composing agents that support the
     composition of multiple types of mail using external composing
     agents.  As with the view- command, the semantics of program
     execution are operating system dependent.  The result of the
     composing program may be data that is not yet suitable for mail
     transport--that is, a Content-Transfer-Encoding may need to be
     applied to the data.
   * The "composetyped" field is similar to the "compose" field, but is
     to be used when the composing program needs to specify the
     Content-type header field to be applied to the composed data.  The
     "compose" field is simpler, and is preferred for use with existing
     (non-mail-oriented) programs for composing data in a given format.
     The "composetyped" field is necessary when the Content-type
     information must include auxilliary parameters, and the composition
     program must then know enough about mail formats to produce output
     that includes the mail type information.
   * The "edit" field may be used to specify a program that can be used
     to edit a body or body part in the given format.  In many cases, it
     may be identical in content to the "compose" field, and shares the
     operating-system dependent semantics for program execution.
   * The "print" field may be used to specify a program that can be used
     to print a message or body part in the given format.  As with the
     view-command, the semantics of program execution are operating
     system dependent.
   * The "test" field may be used to test some external condition (e.g.
     the machine architecture, or the window system in use) to determine
     whether or not the mailcap line applies.  It specifies a program to
     be run to test some condition.  The semantics of execution and of
     the value returned by the test program are operating system
     dependent.  If the test fails, a subsequent mailcap entry should be
     sought.  Multiple test fields are not permitted--since a test can
     call a program, it can already be arbitrarily complex.
   * The "needsterminal" field indicates that the view-command must be
     run on an interactive terminal.  This is needed to inform
     window-oriented user agents that an interactive terminal is needed.
     (The decision is not left exclusively to the view-command because
     in some circumstances it may not be possible for such programs to
     tell whether or not they are on interactive terminals.)  The
     needsterminal command should be assumed to apply to the compose and
     edit commands, too, if they exist.  Note that this is NOT a
     test--it is a requirement for the environment in which the program
     will be executed, and should typically cause the creation of a
     terminal window when not executed on either a real terminal or a
     terminal window.
   * The "copiousoutput" field indicates that the output from the
     view-command will be an extended stream of output, and is to be
     interpreted as advice to the UA (User Agent mail- reading program)
     that the output should be either paged or made scrollable.  Note
     that it is probably a mistake if needsterminal and copiousoutput
     are both specified.
   * The "description" field simply provides a textual description,
     optionally quoted, that describes the type of data, to be used
     optionally by mail readers that wish to describe the data before
     offering to display it.
   * The "x11-bitmap" field names a file, in X11 bitmap (xbm) format,
     which points to an appropriate icon to be used to visually denote
     the presence of this kind of data.
   * Any other fields beginning with "x-" may be included for local or
     mailer-specific extensions of this format.  Implementations should
     simply ignore all such unrecognized fields to permit such
     extensions, some of which might be standardized in a future version
     of this document.