This is Info file ../info/w3.info, produced by Makeinfo-1.63 from the
input file w3.texi.

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

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

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


File: w3.info,  Node: General Formatting,  Next: Character based terminals,  Prev: Controlling Formatting,  Up: Controlling Formatting

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.

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

                   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.


File: w3.info,  Node: Character based terminals,  Next: Graphics workstations,  Prev: General Formatting,  Up: Controlling Formatting

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.

   :: WORK ::

   `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 entities are converted properly.


File: w3.info,  Node: Graphics workstations,  Next: Inlined images,  Prev: Character based terminals,  Up: Controlling Formatting

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

   Starting with the first public release of version 2.3.0, all
formatting is controlled by the use of stylesheets.

   :: WORK :: Graphic workstation stuff - redo for stylesheets


File: w3.info,  Node: Inlined images,  Prev: Graphics workstations,  Up: Controlling Formatting

   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.

   :: WORK :: Need a pointer to the new EMBED Internet Draft ::

   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.


File: w3.info,  Node: MIME Support,  Next: Adding MIME types based on file extensions,  Up: Top

MIME Support
************

   MIME is an emerging standard for multimedia mail.  It offers a very
flexible typing mechanism.  The type of a file or message is specified
in two parts, separated by a '/'.  The first part is the general
category of the data (text, application, image, etc.).  The second part
is the specific type of data (postscript, gif, jpeg, etc.).  So
`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 possible).

* Menu:

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


File: w3.info,  Node: Adding MIME types based on file extensions,  Next: Specifying Viewers,  Prev: MIME Support,  Up: MIME Support

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.


File: w3.info,  Node: Specifying Viewers,  Prev: Adding MIME types based on file extensions,  Up: MIME Support

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

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

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

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


File: w3.info,  Node: Security,  Next: Non-Unix Operating Systems,  Up: Top

Security
********

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

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

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

SSL Encryption
     SSL is the `Secure Sockets Layer' interface developed by Netscape
     Communications (2).  Emacs-W3 supports HTTP transfers over an SSL
     encrypted channel, if the appropriate files have been
     installed.*Note Installing SSL::

PGP/PEM
     A few servers still support this method of authentication, but it
     has been superseded by SSL and Secure-HTTP.*Note Using PGP/PEM::

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

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

   (2)  http://www.netscape.com/


File: w3.info,  Node: Non-Unix Operating Systems,  Next: VMS,  Prev: Security,  Up: Top

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

* Menu:

* VMS::                 The wonderful world of VAX|AXP-VMS!
* OS/2::                The next-best thing to Unix.
* MS-DOS::              The wonderful world of MS-DOG!
* 32-Bit Windows::      Windows NT, Chicago/Windows 95.
* Amiga::               The Amiga, for those who still love them.


File: w3.info,  Node: VMS,  Next: OS/2,  Prev: Non-Unix Operating Systems,  Up: Non-Unix Operating Systems

VMS
===

   :: WORK :: VMS Specific instriuctions


File: w3.info,  Node: OS/2,  Next: MS-DOS,  Prev: VMS,  Up: Non-Unix Operating Systems

OS/2
====

   :: WORK :: OS/2 Specific instructions


File: w3.info,  Node: MS-DOS,  Next: 32-Bit Windows,  Prev: OS/2,  Up: Non-Unix Operating Systems

MS-DOS
======

   :: WORK :: DOS Specific instructions


File: w3.info,  Node: 32-Bit Windows,  Next: Amiga,  Prev: MS-DOS,  Up: Non-Unix Operating Systems

32-Bit Windows
==============

   :: WORK :: 32bit Windows Specific instructions


File: w3.info,  Node: Amiga,  Next: Advanced Features,  Prev: 32-Bit Windows,  Up: Non-Unix Operating Systems

Amiga
=====

   :: WORK :: Amiga specific instructions


File: w3.info,  Node: Advanced Features,  Next: Style Sheets,  Prev: Amiga,  Up: Top

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

* Menu:

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


File: w3.info,  Node: Style Sheets,  Next: Disk Caching,  Prev: Advanced Features,  Up: Advanced Features

Style Sheets
============

   Emacs-W3 currently supports the experimental style sheet mechanism
proposed by H&kon W. Lie of the W3 Consortium.  This allows for the
author to specify what a document should look like, and yet allow the
end user to override any of the stylistic changes.  This allows for
people with special needs (most notably the visually impaired) to
override style bindings that could make a document totally unreadable.

     <style notation="css">
     /* This is a comment
     ** These will be ignored, up to the terminating */
     
     h1 { align: center,
          color: yellow,
          background: red,
          font-size: 24pt
        }
     h2 { align: right,
          font-family: palatino,
          font-size: 18pt
        }
     </style>

   :: WORK :: Much more information on stylesheets

   To include a stylesheet into a document, simply use the <style> tag.
Use the notation attribute to specify what language the stylesheet is
specified in.  The default is css.  The data between the <style> and
</style> tags is the stylsheet proper - no HTML parsing is done to this
data - it is treated similar to an <XMP> section of text.  To reference
an external stylesheet, use the <link> tag.
     <link rel="stylesheet" href="/bill.style">
   If these two mechanisms are mixed, then the URL is resolved first,
and the contents of the <style> tag take precedence if there are any
conflicting directives.

   In the future, DSSSL and DSSSL-lite will be supported as valid
stylesheet languages, but not in this release.  For more information on
DSSSL-lite see http://www.falch.no/~pepper/DSSSL-Lite/ - for more
information on full DSSSL, see
ftp://ftp.jclark.com/pub/dsssl/dsssl.ps.gz


File: w3.info,  Node: Disk Caching,  Next: Interfacing to Mail/News,  Prev: Style Sheets,  Up: 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.


File: w3.info,  Node: Interfacing to Mail/News,  Next: Debugging HTML,  Prev: Disk Caching,  Up: Advanced Features

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


File: w3.info,  Node: Debugging HTML,  Next: Native WAIS Support,  Prev: Interfacing to Mail/News,  Up: Advanced Features

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


File: w3.info,  Node: Native WAIS Support,  Next: Rating Links,  Prev: Debugging HTML,  Up: Advanced Features

Native WAIS Support
===================

   This version of Emacs-W3 supports native WAIS querying (earlier
versions required the use of a gateway program).  In order to use the
native WAIS support, a working "waisq" binary is required.  I recommend
the distribution from think.com -
ftp://think.com/wais/wais-8-b6.1.tar.Z is a good place to start.

   The variable `url-waisq-prog' must point to this executable, and one
of `url-wais-gateway-server' or `url-wais-gateway-port' should be `nil'.

   When a WAIS URL is encountered, a form will be automatically
generated and displayed.  After typing in the search term, the query
will be sent to the server by running the `url-waisq-prog' in a
subprocess.  The results will be converted into HTML and displayed.


File: w3.info,  Node: Rating Links,  Next: Gopher Plus Support,  Prev: Native WAIS Support,  Up: Advanced Features

Rating Links
============

   The `w3-link-info-display-function' variable can be used to 'rate' a
URL when it shows up in an HTML page.  If non-`nil', then this should
be a list specifying (or a symbol specifying the name) of a function.
This function should expect one argument, a fully specified URL, and
should return a string.  This string is inserted after the link text.

   If a user has decided that all links served from blort.com are too
laden with images, and wants to be warned that a link points at this
host, they could do something like this:

     (defun check-url (url)
       (if (string-match "://[^/]blort.com" url)
          "[SLOW!]" ""))
     
     (setq w3-link-info-display-function 'check-url)

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


File: w3.info,  Node: Gopher Plus Support,  Next: Hooks,  Prev: Rating Links,  Up: Advanced Features

Gopher+ Support
===============

   The gopher+ support in Emacs-W3 is limited to the conversion of ASK
blocks into HTML 3.0 forms, and the usage of the content-length given by
the gopher+ server to give a nice status bar on the bottom of the
screen.

   This will hopefully be extended to include the Gopher+ method of
content-type negotiation, but this may be a while.


File: w3.info,  Node: Hooks,  Next: Other Variables,  Prev: Gopher Plus Support,  Up: Advanced Features

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, the syntax table has been set
     to `w3-parse-args-syntax-table', and any personal annotations have
     been inserted 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


File: w3.info,  Node: Other Variables,  Prev: Hooks,  Up: Advanced Features

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.

`url-waisq-prog'
     Name of the waisq executable on this system.  This should be the
     `waisq' program from think.com's wais8-b5.1 distribution.


File: w3.info,  Node: More Help,  Next: Future Directions,  Up: Top

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.


File: w3.info,  Node: Future Directions,  Next: Reporting Bugs,  Prev: More Help,  Up: Top

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


File: w3.info,  Node: Reporting Bugs,  Next: Installing SSL,  Prev: Future Directions,  Up: Top

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

   :: WORK :: Reporting bugs needs work.


File: w3.info,  Node: Installing SSL,  Next: Using PGP/PEM,  Prev: Reporting Bugs,  Up: Top

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

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

   (1)  http://www.netscape.com/newsref/std/sslref.html


File: w3.info,  Node: Using PGP/PEM,  Next: Mailcap Files,  Prev: Installing SSL,  Up: Top

Using PGP/PEM
*************

   Most of this chapter has been reproduced from the original
documentation written by Rob McCool (robm@netscape.com)(1).

   RIPEM is 'Riordan's Internet Privacy Enhanced Mail', and is
currently on version 1.2b3.  US citizens can ftp it from
ftp://ripem.msu.edu/pub/crypt/ripem.

   PGP is 'Pretty Good Privacy', and is currently on version 2.6.  The
legal controversies that plagued earlier versions have been resolved, so
this is a competely legal program now.  There is also a legal version
for european users, called 2.6ui (the Unofficial International version).

   PGP and PEM are programs that allow two parties to communicate in a
way which does not allow third parties to read them, and which certify
that the person who sent the message is really who they claim they are.

   PGP and PEM both use RSA encryption.  The U.S.  government has strict
export controls over foreign use of this technology, so people outside
the U.S.  may have a difficult time finding programs which perform the
encryption.

   A working copy of either Pretty Good Privacy or RIPEM is required.
You should be familiar with the program and have generated a
public/private key pair.

   Currently, the protocol has been implemented with PEM and PGP using
local key files on the server side, and on the client side with PEM
using finger to retrieve the server's public key.

   Parties who wish to use Emacs-W3 with PEM or PGP encryption will
need to communicate beforehand and find a tamper-proof way to exchange
their public keys.

   Pioneers get shot full of arrows.  This work is currently in the
experimental stages and thus may have some problems that I have
overlooked.  The only known problem that I know about is that the
messages are currently not timestamped.  This means that a malicious
user could record the encrypted message with a packet sniffer and repeat
it back to the server ad nauseum.  Although they would not be able to
read the reply, if the request was for something being charged for, this
could be very inconvenient.

   This protocol is almost word-for-word a copy of Tony Sander's RIPEM
based scheme, generalized a little.  Below, wherever PEM is used,
replace it with PGP, and the behaviour should remain the same.

     *Client:*
     
     GET /docs/protected.html HTTP/1.0
     UserAgent: Emacs-W3/2.1.x
     
     *Server:*
     
     HTTP/1.0 401 Unauthorized
     WWW-Authenticate: PEM entity="webmaster@hoohoo.ncsa.uiuc.edu"
     Server: NCSA/1.1
     
     *Client:*
     
     GET / HTTP/1.0
     Authorization: PEM entity="robm@ncsa.uiuc.edu"
     Content-type: application/x-www-pem-request
     
     --- BEGIN PRIVACY-ENHANCED MESSAGE ---
     this is the real request, encrypted
     --- END PRIVACY-ENHANCED MESSAGE ---
     
     *Server:*
     
     HTTP/1.0 200 OK
     Content-type: application/x-www-pem-reply
     
     --- BEGIN PRIVACY-ENHANCED MESSAGE ---
     this is the real reply, encrypted
     --- END PRIVACY-ENHANCED MESSAGE ---
     That's it.

   Emacs-W3 uses the excellent mailcrypt(2) package written by Jin S
Choi (jsc@mit.edu).  This package takes care of calling ripem and/or
pgp with the correct arguments.  Please see the documentation at the
top of mailcrypt.el for instructions on using mailcrypt.  All bug
reports about mailcrypt should go to Jin S Choi, but bugs about how I
use it in Emacs-W3 should of course be directed to me.

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

   (1)  See http://hoohoo.ncsa.uiuc.edu/docs/PEMPGP.html for the
original

   (2)  Available from
http://www.cs.indiana.edu/LCD/cover.html?mailcrypt


File: w3.info,  Node: Mailcap Files,  Next: General Index,  Prev: Using PGP/PEM,  Up: Top

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.

