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

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

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

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 see Stylesheets  If there is any aspect of Emacs-W3 that cannot be modified to your satisfaction, please send mail to the w3-beta@indiana.edu mailing list with any suggestions. See Reporting Bugs

Getting Started
***************

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

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

Downloading
===========

:: WORK :: What you need, and why :: WORK :: Where to download Emacs, XEmacs, various platforms :: WORK :: Where to download Emacs-W3 :: WORK :: Where to download related utilities (netpbm, xv, gimp, etc.)

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

:: WORK :: Document makefile variables :: WORK :: Document what gets installed where, why

Startup Files
=============

:: WORK :: startup files This section should document where emacs-w3 looks for its startup files, and what each one does.  'profile' 'stylesheet' 'hotlist' 'history' etc.

Preferences Panel
=================

:: WORK :: pref panel This should document the quick preferences panel.  M-x w3-preferences-edit

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

Emacs-W3 is similar to the Info package all Emacs users hold near and dear to their hearts (see Info (The Info Manual), for a description of Info).  Basically, space and backspace control scrolling, and return or 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 3.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. See Stylesheets for information on how to change this.

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

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

Movement
========

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.

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

<
     Goes to the start of document

>
     Goes to the end of document

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

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

B
     Move backwards in the history stack.

F
     Move forwards in the history stack.

l
     Return to the last buffer shown before this buffer.

q
     Kill this buffer. Bury this buffer, but don't kill it

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

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

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

V
     This shows the URL of the hypertext link under point in the minibuffer.

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

I
     Shows information about the URL at point.

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

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

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

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

Action
======

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

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

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

     Pressing return when over a form input field 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

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

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

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

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

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

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

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

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

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

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

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

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

l
     Goes to the last WWW buffer seen.

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

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

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

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

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

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

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

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

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

     When the HTML source is printed, then an appropriate <base> tag is inserted at the beginning of the document. When postscript is printed, then the HTML source of the document is converted into LaTeX source.  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.  Good defaults are: {article}, [psfig,twocolumn]{article}, etc.

     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.

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

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

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

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

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

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

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

Emulation
=========

:: WORK :: Document lynx emulation

Down arrow
     Highlight next topic

Up arrow
     Highlight previous topic

Right arrow, Return, Enter
     Jump to highlighted topic

Left arrow
     Return to previous topic

+
     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

(
     Go back half a page in the current document

#
     Go to Toolbar or Banner in the current document

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

g
     Goto a user specified URL or file

i
     Show an index of documents

j
     Execute a jump operation

k
     Show a list of key mappings

l
     List references (links) in current document

m
     Return to main screen

o
     Set your options

p
     Print the current document

q
     Quit

/
     Search for a string within the current document

s
     Enter a search string for an external search

n
     Go to the next search string

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

=
     Show file and link info

\
     Toggle document source/rendered view

!
     Spawn your default shell

*
     Toggle image_links mode on and off

[
     Toggle pseudo_inlines mode on and off

]
     Send an HTTP HEAD request for the current doc or link

C-R
     Reload current file and refresh the screen

C-W
     Refresh the screen

C-U
     Erase input line

C-G
     Cancel input or transfer

C-T
     Toggle trace mode on and off

C-K
     Invoke the Cookie Jar Page

:: WORK :: Document netscape emulation Uh, turn this into pretty tables about what keys are emulated.

     (define-key w3-netscape-emulation-minor-mode-map "\M-s" 'w3-save-as)
     (define-key w3-netscape-emulation-minor-mode-map "\M-m" 'w3-mailto)
     (define-key w3-netscape-emulation-minor-mode-map "\M-n" 'make-frame)
     (define-key w3-netscape-emulation-minor-mode-map "\M-l" 'w3-fetch)
     (define-key w3-netscape-emulation-minor-mode-map "\M-o" 'w3-open-local)
     (define-key w3-netscape-emulation-minor-mode-map "\M-p" 'w3-print-this-url)
     (define-key w3-netscape-emulation-minor-mode-map "\M-q" 'w3-quit)
     (define-key w3-netscape-emulation-minor-mode-map "\M-f" 'w3-search-forward)
     (define-key w3-netscape-emulation-minor-mode-map "\M-g" 'w3-search-again)
     (define-key w3-netscape-emulation-minor-mode-map "\M-r" 'w3-reload-document)
     (define-key w3-netscape-emulation-minor-mode-map "\M-i" 'w3-load-delayed-images)
     (define-key w3-netscape-emulation-minor-mode-map "\M-a" 'w3-hotlist-add-document)
     (define-key w3-netscape-emulation-minor-mode-map "\M-b" 'w3-show-hotlist)
     (define-key w3-netscape-emulation-minor-mode-map "\M-h" 'w3-show-history-list)

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

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

Hotlist commands are:

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

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

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

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

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

hv
     Converts the hotlist into HTML and displays it.

ha
     Shows the hotlist entries matching a regular expression.

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

History
=======

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

If the variable url-keep-history is t, then Emacs-W3 keeps a list of all the URLs visited in a session.

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

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

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

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

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

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

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

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

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.

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

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.

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.

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.

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.

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.

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

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

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.

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

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

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.

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

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

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.

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.

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.

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 values:   allowed on <font-size> and <line-height>

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

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.

color
.....

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

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.

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

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

This property sets the background color of an element.

       H1 { background-color: #F00 }

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

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

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 }

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

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

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

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

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

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

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 values:   allowed on <background-position>

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.

Text Properties
---------------

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.

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.

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.

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

This is currently unsupported in Emacs-W3.

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.

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

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

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.

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

Not currently implemented in Emacs-W3.

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

Not currently implemented in Emacs-W3.

Box Properties
--------------

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.

display
.......

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

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.

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

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

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 }

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 values:   N/A

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

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

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

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

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.

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

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

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.

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.

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

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.

volume
......

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

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.

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

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

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.

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

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

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

pause
.....

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

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

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

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

See cue-before

cue
...

See cue-before

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

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

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 }

pitch
.....

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

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.

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.

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.

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.

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

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

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

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

Units
=====

Length Units
------------

Percentage Units
----------------

color Units
-----------

URLs
----

Angle Units
-----------

These are the legal angle units:

  * deg: degrees

  * grad

  * rad: radians

Time Units
----------

These are the legal time units:

  * ms: milliseconds

  * s: seconds

Supported URLs
**************

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

file
====

ftp
===

nfs
===

info
====

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

mailto
======

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

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

irc
===

data
====

mailserver
==========

gopher
======

finger
======

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

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

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

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

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

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

 1. ~/.mime-types

 2. /etc/mime-types

 3. /usr/etc/mime-types

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

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

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

type/subtype ext1 ext2 ...  extN

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

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

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

Not all files can be viewed accurately from within an Emacs session (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.

Security
********

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

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

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

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

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

VMS
===

:: WORK :: VMS Specific instriuctions

OS/2
====

:: WORK :: OS/2 Specific instructions

MS-DOS
======

:: WORK :: DOS Specific instructions

Windows
=======

:: WORK :: 32bit Windows Specific instructions

Speech Integration
******************

:: WORK :: Emacspeak integration

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

Disk Caching
============

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

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

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

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

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

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

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

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

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

With the latest versions of VM (the 5.9x series of betas) 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))))

Debugging HTML
==============

For those people that are adventurous, or are just as anal as I am about people writing valid HTML, set the variable w3-debug-html to t and see what happens.

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

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

Hooks
=====

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

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

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

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

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

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

Miscellaneous variables
=======================

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

url-bad-port-list
     List of ports to warn the user about connecting to.  Defaults to just the mail and NNTP ports so a malicious HTML author cannot spoof mail or news to other people.

url-confirmation-func
     What function to use for asking yes or no functions.  Possible values are 'yes-or-no-p or 'y-or-n-p, or any function that takes a single argument (the prompt), and returns t only if a positive answer is gotten.  Defaults to 'yes-or-no-p.

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

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

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

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

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

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

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

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

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

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

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

More Help
*********

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

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

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

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

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

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

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

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

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

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

:: WORK :: Revamp the todo list

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

If any bugs are discovered in Emacs-W3, please report them to the mailing list w3-beta@indiana.edu - 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'.

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

     NOTE: XEmacs and Emacs 19.22 or later have patches to enable native TERM networking.  To enable it, #define TERM in the appropriate s/*.h file for the operating system, then change the SYSTEM_LIBS 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@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  (Please see the full Emacs distribution for a description of regular expressions) that matches local hosts that do not require the use of a gateway.  If nil, then all connections are made through the gateway.

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

     :: WORK :: document telnet gw variables This section needs more information, specifically documenting the following variables.  For now, please do C-h v on the variable for more information.

     url-gateway-telnet-host

     url-gateway-telnet-parameters

     url-gateway-telnet-password-prompt

     url-gateway-telnet-puser-name

     url-gateway-prompt-pattern

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.

     :: WORK :: document rlogin gw variables This section needs more information, specifically documenting the following variables.  For now, please do C-h v on the variable for more information.

     url-gateway-rlogin-host

     url-gateway-rlogin-parameters

     url-gateway-rlogin-user-name

     url-gateway-prompt-pattern

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.

     :: WORK :: document socks variables This section needs more information, specifically documenting the following variables.  For now, please do C-h v on the variable for more information.

     socks-host

     socks-password

     socks-username

     socks-port

     socks-timeout

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.

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 fully-specified URL of the proxy server to contact, or, in the case of the special "no_proxy" entry, a regular expression that matches any hostnames that should be contacted directly.

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

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

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

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

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

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

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

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.

Down with DoubleClick
*********************

:: WORK :: Document why doubleclick is evil :: WORK :: Document how you can never see another ad from them again