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

   Copyright (C) 1993, 1994, 1995 William M. Perry

   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.

Action
======

   First, here are the keys and functions that bring up a new hypertext
page, usually creating a new buffer.
`return'
     Pressing return when over a hyperlink attempts to follow the link
     under the cursor.  With a prefix argument (`C-u'), this forces the
     file to be saved to disk instead of being passed off to other
     viewers or being parsed as HTML.

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

`button2, M-x w3-follow-mouse'
     This function expects to be bound to a mouse button.  It moves to
     the point under mouse and tries to fetch the link that was clicked
     on.  If no link is found, a message is displayed in the minibuffer.

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

`C-button2, M-return, M-x w3-follow-inlined-image'
     This function 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, M-x w3-print-this-url'
     Prints out the current buffer in a variety of formats, including
     Postscript, HTML source, or formatted text.

`P, M-x w3-print-url-under-point'
     Prints out the URL under point in a variety of formats, including
     Postscript, HTML source, or formatted text.

`m, M-x w3-complete-link'
     Choose from a list of all the hyperlinks in the current buffer.
     Use `space' and `tab' to complete on the links.

`r, g, M-x w3-reload-document'
     Reload the current document--the current buffer is killed, and the
     URL it was visiting is fetched and redisplayed.  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).

`C-o, M-x w3-fetch'
     This function 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, M-x w3-open-local'
     Find 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 non`nil', then
     Emacs-w3 automatically generates a hypertext listing of the
     directory.  The hypertext mode is the default, so that all the
     keys and functions remain the same.

`M-s, M-x w3-search'
     Perform a search, if this is a searchable index.  This sends a
     string of the type `'URL?search-terms'' to the server this
     document was retrieved from.  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.

`C-c C-b, M-x w3-show-history-list'
     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, M-x w3-goto-last-buffer'
     Go to last WWW buffer visited

`q, M-x w3-quit'
     Quits WWW mode.  This kills the current buffer and goes to the most
     recently visited buffer.

`u, M-x w3-leave-buffer'
     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.

`B, M-x w3-backward-in-history'
     Take one step back along the path in the current history.  Has no
     effect if at the beginning of the history list.

`F, M-x w3-forward-in-history'
     Take one step forward along the path in the current history.  Has
     no effect if at the end of the history list.

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

`M-m, M-x w3-mail-current-document'
     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, M-x w3-mail-document-under-point'
     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, M-x w3-print-this-url'
     Prints the current document.  Choose from several different
     formats to print: formatted text, HTML source, PostScript (with
     ps-print), or by using LaTeX and dvips).

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

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

`P, M-x w3-print-url-under-point'
     Prints the document pointed to by the hypertext link under point.
     Please see the documentation for `w3-print-this-url' directly above
     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, M-x w3-insert-this-url'
     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, M-x w3-use-links'
     Select 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 Mosaic & Netscape
************************************

   Since NCSA Mosaic for Xwindows or Netscape is the de-facto hypertext
browser at most sites, Emacs-w3 is compatible with them in several ways.

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

   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:
`M-x w3-import-netscape-bookmarks'
     Converts a Netscape bookmark file into Emacs-w3's internal hotlist
     format.

`a, M-x w3-hotlist-add-document'
     This 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 `buffer-name'.

`M-x w3-hotlist-refresh'
     This rereads the default hostlist file specified by
     `w3-hotlist-file'.

`d, M-x w3-hotlist-delete'
     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.

`M-x w3-hotlist-rename-entry'
     Some hotlist item names can be very unwieldy (`Mosaic for X level
     2 fill out form support'), or uninformative (`Index of /').  If
     you are not satisfied with how a specific item is labeled, you may
     change it by typing `M-x w3-rename-hotlist-entry'.  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'.

`H, M-x w3-use-hotlist'
     Prompts for the alias to jump to.  Pressing the spacebar or tab key
     shows partial completions.

`M-x w3-show-hotlist'
     This converts the hotlist into HTML and displays it.

History
=======

   NCSA Mosaic keeps 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 you
were at before jumping to this document, and also keeps track of where
you jump to from that buffer.  This means that you can go forwards and
backwards very easily along the path you took 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'.  These are
fairly stable functions, but may not work as expected all the time.
First, the buffer-list is used to look at the URL of every buffer, and
if it matches the item in the history list you are looking for, then it
is brought forward.  If no buffer containing the desired URL is found,
then the URL is fetched.  Then the desired position in the buffer is
searched for.

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

   Mosaic and Netscape supports 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 you are using (Netscape 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' keys 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
server before choosing which to retrieve.

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

   Mosaic can annotate documents.  Annotations are comments about the
current document, and these annotations appear as a link to the
comments at the end of the document when you browse it in Mosaic.  The
original file is not changed.  There are two types of annotations
supported in Mosaic, and both are supported by Emacs-w3 as well.

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

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

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

   If you do not want to share your musings about a particular document
with the entire network, you can add a personal annotation that only you
can see.  Personal annotations are stored in a subdirectory in the users
account on the local disk, with a log file that contains information
about what URLs have been annotated and which files contain the
annotations.

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

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

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

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

   Editing personal annotations is not yet supported.

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

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

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

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

                          -------------------

                        Setting the fill column

                          -------------------

   Each time a document is parsed, the `fill-column' is recalculated
using `window-width' and `w3-right-border'.  `w3-right-border' is an
integer specifying how much room at the right edge of the screen to
leave blank.  The `fill-column' is set to `(- (window-width)
`w3-right-border')'.

                          -------------------

                     Formatting of hypertext links

                          -------------------

   If the variable `w3-delimit-links' is non-`nil' (the default for
text-terminals), then hypertext links are surrounded by text specified
by the user.  The variables `w3-link-start-delimiter' and
`w3-link-end-delimiter' control what text is at the start and end of a
hypertext link.  These variables are cons-pairs of two strings.

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

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

                          -------------------

                          Formatting of lists

                          -------------------

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

   Another thing that is easy to change about lists is the bullet
character put at the front of each list item.  This is controlled by
the variable `w3-list-chars-assoc', which is an assoc list.  This is a
list of lists, each sublist describing what to put at the start of each
particular list type.  The `car' of this list should be a symbol (not a
string) representing the type of list (e.g., `ul').  The rest of the
list should consist of strings to insert at certain levels of lists.
The `n'th element of this list is used when the list is nested `n + 1'
levels.  If the list is not long enough to define a string for a
certain nesting level, then it defaults to either a '*' or a '.'.

                          -------------------

                   Formatting of directory listings

                          -------------------

   When Emacs-w3 encounters a link to a directory (whether by local
file access or via ftp), it can either create an HTML document on the
fly, or use `dired-mode' to peruse the listing.  The variable
`url-use-hypertext-dired' controls this behavior.

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

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

   A new option in the 2.2 series is `url-forms-based-ftp' - this is
still in the experimental stages, but can be useful.  If
`url-forms-based-ftp' is `t', then all automatically generated
directory listings will have a form mixed in with the file listing.
Each file will have a checkbox next to it, and a row of buttons at the
bottom of the screen.  Selecting one of the buttons at the bottom of the
screen will take the designated action on all the marked files.
Currently, only deleting and copying marked files is supported.

                          -------------------

                   Formatting of gopher directories

                          -------------------

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

   The main way to control the display of gopher directories is by the
variable `w3-gopher-labels'.  This variable controls the text that is
inserted at the front of each item.  This is an assoc list of gopher
types (as one character strings), and a string to insert just after the
list item.  All the normal gopher types are defined.  Entries should be
similar to: `("0" . "(TXT)")'.  I have tried to keep all the tags to
three characters plus two parentheses.

                          -------------------

                      Creating a horizontal rule

                          -------------------

   Horizontal rules (<HR> tags in HTML[+]) are used to separate chunks
of a document, and is meant to be rendered as a solid line across the
page.  Some terminals display characters differently, so the variable
`w3-horizontal-rule-char' controls which character is used to draw a
horizontal bar.  This variable must be the ASCII value of the character,
not a string.  The variable is passed through make-string whenever a
horizontal rule of a certain width is necessary.

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

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

   Two variables control what text is inserted around different markup
tags.  `w3-header-chars-assoc' controls what characters are inserted
around header items, and `w3-style-chars-assoc' controls what
characters are inserted around most other markup (italics, addresses,
etc.).

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

   `w3-style-chars-assoc' is an assoc list of style tags and a list of
strings.  The `car' of the list is the type of style tag it specifies
(DFN, B, I, etc.).  The rest of the list should contain two items.  The
`car' is text to insert before the stylized text.  The `cdr' is text to
insert after the stylized text.  Both should have reserved characters
converted to their HTML[+] entity definitions.

   If using Emacs 19.2x on a VT100 compatible terminal, Emacs-w3 can
show links, headers, and various other types of emphasis in bold or
underlined text.

   To do this, set the variable `w3-emacs19-hack-faces-p' to non-`nil'
in your `~/.emacs' file.  Also make sure that the environment variable
`TERM' is set to the correct terminal type.

   If there is a function called `w3-emacs19-hack-TERMINAL', then this
is used to setup the special characters that turn on bold and
underlined text.  If this function does not exist, it is fairly easy to
write one from scratch, using the terminal's entry in the
`/etc/termcap' file.

   Each function should use the `standard-display-table' to replace ^A,
^B, ^C, and ^D with escape sequences that turn on highlighting.  When
reading the `/etc/termcap' file, be on the lookout for these codes:

`us'
     Code to turn on underlining

`ue'
     Code to turn off underlining

`mb'
     Code to turn on boldface type

`se'
     Code to turn off all attributes

   Here is an example for creating the VT100 control sequences:

     (defun w3-emacs19-hack-vt100 ()
       "Hack 'faces' for ttys (vt100)"
       (or standard-display-table
           (setq standard-display-table (make-vector 261 nil)))
       (aset standard-display-table 1 (vector (create-glyph "\e[4m")))
       (aset standard-display-table 2 (vector (create-glyph "\e[m")))
       (aset standard-display-table 3 (vector (create-glyph "\e[5m")))
       (aset standard-display-table 4 (vector (create-glyph "\e[m")))
       )

   To turn off the highlighting features, set the variable
`w3-emacs19-hack-faces-p' to `nil' and execute the function
`w3-emacs19-unhack-faces'

   NOTE: This highlighting is not perfect and could cause some odd
display glitches, especially when Emacs does a smart redisplay and
doesn't redraw the whole screen.  `C-l' usually fixes these problems.

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

   When running in a graphic environemnt (Xwindows or NeXTstep for
example), the fonts and colors used by Emacs-w3 to display text can be
controlled by setting a few resources.  To specify these resources:
   * Xwindows: Place them into the `~/.Xresources' file or the
     `/usr/lib/X11/app-defaults/Emacs' file.

   * NeXTstep: When using the NeXTstep port of Emacs 19, use the
     `dwrite' command to install these resources.  The command should
     look something like: (`dwrite Emacs <Style>.Attribute<item>
     value', where style and attribute are one of the choices below.

   * OS/2 or Windows: When using the Lucid Emacs or FSF Emacs that has
     been ported to the Presentation Manager or Windows 3.x, the
     documentation states where to store a file that Emacs looks at for
     Xresources.  The resources for each version of Emacs are the same.
For each style of text that Emacs-w3 uses, you can specify any of the
following resources by replacing <style> with the actual style name.
   * Emacs*<Style>.AttributeFont: Font name

   * Emacs*<Style>.AttributeForeground: Foreground color

   * Emacs*<Style>.AttributeBackground: Background color

   * Emacs*<Style>.AttributeUnderline: Underline text?

   Emacs-w3 uses these special style names:
`w3-node-style'
     For links to other documents

`w3-visited-node-style'
     For displaying hypertext links that have been viewed before

   All other styles can be specified by using the tag name as the
<Style> section of the resource.  For example:
`Emacs*h1.attributeForeground', or `Emacs*address.attributeForeground'.

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

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

  1. image/x-xbitmap

  2. image/xbitmap

  3. image/xbm

  4. image/gif

  5. image/jpeg

  6. image/x-fax

  7. image/x-raster

  8. image/windowdump

  9. image/x-icon

 10. image/portable-graymap

 11. image/portable-pixmap

 12. image/x-pixmap

 13. image/x-xpixmap

 14. image/pict

 15. image/x-macpaint

 16. image/x-targa

 17. image/tiff

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

   When running in XEmacs 19.11 or XEmacs 19.12, Emacs-w3 can insert an
MPEG movie in the middle of a buffer.  This utilizes a now deprecated
feature of HTML 3.0, so its use should be limited to pages you do not
mind modifying once the standard way to do this is nailed down.

   The basic syntax is:
     <embed href="somevideo.mpg" type="video/mpeg">

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

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

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

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

   (1)  Available via anonymous ftp from
ftp.x.org:/R5contrib/netpbm-1mar1994.tar.gz, and most large ftp sites.

HTTP/1.0 Support
****************

   The new revision of the HTTP specification adds much more
functionality to the server side of a transaction.  Access
authorization has been added, and several types of redirection can
occur.  All of this negotiation and redirection should take place
before the user ever sees the first requested page--this avoids the
overhead of parsing any error messages or old documents the server may
have returned with the redirection or authorization message.  The new
protocol is also MIME (Multipurpose Internet Mail Extensions, see RFC
1341) compliant.

Redirection
===========

   One of the most useful aspects of HTTP/1.0 is the ability to
transparently move files between different servers (perhaps even
different protocols).  Most of the WWW browsers support redirection in
some form or another.  The Emacs browser supports all three types of
redirection in the HTTP/1.0 specification (error codes 301, 302, and
303).

   Whenever a redirection response is detected, the URL specified by the
Location: header is retrieved.  All relative references are resolved
before requesting the new URL.

   An HTML editor that is tightly integrated with Emacs-w3 is planned,
and will include the ability to edit documents to change their links if
a permanent relocation is seen.

Authentication
==============

   Lots of information is useful to a group of people within an
organization, or a group working on a project, but it is not always wise
to distribute this information to the world at large.

   The HTTP/1.0 protocol adds the capability to have authentication
based on usernames and passwords.  If the improper username/password
pair is sent to the server, an error code of 401, Unauthorized is
returned by the server.

   The browser has a very extensible interface to its authentication
handling.  When a 401 error code is received, the WWW-Authenticate
header is checked--this header field should be a space-separated list
of suitable authorization schemes for the requested URL.  The value of
this header is read into a lisp symbol by way of Emacs's read-string
function.  This lisp symbol looks like `url-authtype-auth', where
authtype is replaced by the correct authorization type.  The
authorization types defined in the latest HTTP/1.0 specification
include user, basic, public key, and kerberos (versions 4 and 5).  If a
function of this name is currently defined, then the function is called
via `funcall' with several parameters:
  1. The URL being authenticated.

  2. whether to prompt for a username/password if no cached data is
     found.

  3. whether to overwrite an old username/password if the information is
     found in the cache.
        This interface was chosen for its flexibility and
extensibility.  The main routine that does the MIME parsing and the
building of the Authorization header does not need to know how to
handle each type of authentication, and the addition of a new method
for authentication is simply a matter of defining one function that
conforms to a simple interface.

Payment
=======

   The Chargeto: header will be used to pay for services offered over
the World Wide Web.  Such things as electronic magazines and commercial
databases all need a way to restrict access to only authorized
subscribers.  The format of the header has yet to be specified, but the
interface and storage techniques will be similar to the Authorization
section.

MIME Support
============

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

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

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.

Mapping gopher types to MIME types
----------------------------------

   In order to avoid having to specify viewers for gopher in a different
way, Emacs-w3 converts gopher types to MIME media types and uses the
standard mailcap viewers.  The variable `url-gopher-to-mime' determines
how this mapping of gopher types to MIME is done.  This is an assoc
list, the `car' of each element should be a character (not a string)
specifying the gopher type.  The `cdr' of each element should be a
string, specifying what MIME media type the gopher object should be
treated as.

   The default value for this should be sufficient for most uses, but if
any gopher types have been left out, or mislabeled, please let
wmperry@spry.com know.

Specifying Viewers
------------------

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

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