\input texinfo
@c
@c Things to add:
@c 1. Comparisons against other browsers (Mosaic, Lynx, tkWWW, violaWWW)
@c 2. Using under Dos/Windows/OS/2
@c 3. HTML+ Compatibility
@c 4. Enhancements above and beyond HTML+
@c 5. Data structures used
@c
@setfilename ../info/w3.info
@settitle W3 User's Manual
@iftex
@finalout
@end iftex
@c @setchapternewpage odd
@c @smallbook
@tex
\overfullrule=0pt
%\global\baselineskip 30pt      % for printing in double space
@end tex
@ifinfo
This file documents the W3 World Wide Web browser.

Copyright (C) 1993, 1994 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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo
@c
@titlepage
@sp 6
@center @titlefont{W3 User's Manual}
@sp 4
@center First Edition, W3 Version 2
@sp 1
@center January 1994
@sp 5
@center William M. Perry
@center @t{wmperry@@indiana.edu}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993, 1994 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.

@end titlepage
@page
@ifinfo
@node Top, Introduction,, (DIR)

This manual documents the W3 World Wide Web browser, a Lisp program
which runs as a subsystem under Emacs.  The manual is divided into the
following chapters.

@menu
* License::                     License
* Introduction::                Overview of the W3 interface
* Mosaic Compatibility::        Support for NCSA Mosaic features
* Hyperbole Compatibility::     How to use W3 with Hyperbole
* Internals of W3::             How to use W3 from your own programs
* Customizing Formatting::      How to change document display
* Printing::                    How to print WWW documents
* Saving Files::                How to save WWW documents
* Using W3 behind a firewall::  How to use W3 behind a firewall.
* Hook Variables::              Different hooks to use in W3
* Miscellaneous::               Other configuration variables
* More Help::                   How to get more help - mailing lists,
                                newsgroups, etc
* HTML::                        Hypertext Markup Language Introduction
* WWW::                         Introduction to the World Wide Web

Indices:

* Concept Index::               Concept Index
* Key Index::                   Menus of command keys and their references
* Command Index::               Menus of commands and their references
* Variable Index::              Menus of variables and their references
@end menu
@end ifinfo

@node License, Introduction, Variable Index, Top
@unnumbered License

@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 1, February 1989
@cindex license to copy Emacs
@cindex General Public License

@display
Copyright @copyright{} 1989 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The license agreements of most software companies try to keep users
at the mercy of those companies.  By contrast, our General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  The
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of a such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS
@end iftex
@ifinfo
@center TERMS AND CONDITIONS
@end ifinfo

@enumerate
@item
This License Agreement applies to any program or other work which
contains a notice placed by the copyright holder saying it may be
distributed under the terms of this General Public License.  The
``Program'', below, refers to any such program or work, and a ``work based
on the Program'' means either the Program or any work containing the
Program or a portion of it, either verbatim or with modifications.  Each
licensee is addressed as ``you''.

@item
@cindex Distribution
You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
General Public License and to the absence of any warranty; and give any
other recipients of the Program a copy of this General Public License
along with the Program.  You may charge a fee for the physical act of
transferring a copy.

@item
You may modify your copy or copies of the Program or any portion of
it, and copy and distribute such modifications under the terms of Paragraph
1 above, provided that you also do the following:

@itemize @bullet
@item
cause the modified files to carry prominent notices stating that
you changed the files and the date of any change; and

@item
cause the whole of any work that you distribute or publish, that
in whole or in part contains the Program or any part thereof, either
with or without modifications, to be licensed at no charge to all
third parties under the terms of this General Public License (except
that you may choose to grant warranty protection to some or all
third parties, at your option).

@item
If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive use
in the simplest and most usual way, to print or display an
announcement including an appropriate copyright notice and a notice
that there is no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this General
Public License.

@item
You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.
@end itemize

Mere aggregation of another independent work with the Program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other work under the scope of these terms.

@item
You may copy and distribute the Program (or a portion or derivative of
it, under Paragraph 2) in object code or executable form under the terms of
Paragraphs 1 and 2 above provided that you also do one of the following:

@itemize @bullet
@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal charge
for the cost of distribution) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with the information you received as to where the
corresponding source code may be obtained.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
@end itemize

Source code for a work means the preferred form of the work for making
modifications to it.  For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.

@item
You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
the Program is void, and will automatically terminate your rights to use
the Program under this License.  However, parties who have received
copies, or rights to use copies, from you under this General Public
License will not have their licenses terminated so long as such parties
remain in full compliance.

@item
By copying, distributing or modifying the Program (or any work based
on the Program) you indicate your acceptance of this license to do so,
and all its terms and conditions.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the original
licensor to copy, distribute or modify the Program subject to these
terms and conditions.  You may not impose any further restrictions on the
recipients' exercise of the rights granted herein.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of the license which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
the license, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
@end smallexample

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items---whatever suits your
program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here a sample; alter the names:

@example
Yoyodyne, Inc., hereby disclaims all copyright interest in the
program `Gnomovision' (a program to direct compilers to make passes
at assemblers) written by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end example

That's all there is to it!

@ifinfo
@node Introduction, Setting Up, License, Top
@end ifinfo
@iftex
@unnumbered Introduction
@end iftex
@cindex World Wide Web

W3 is an Emacs subsystem that allows the user to browse the wonderful
World Wide Web.  The World Wide Web was started at the CERN physics
institute in Switzerland in 1991.  The project was initially started by
Tim Berners-Lee (@i{timbl@@info.cern.ch}) for distributing data between
different research groups effectively.

The Web has since grown into the most advanced information system
currently on the internet.  It is now a global hypertext system with
servers and browsers (programs written to interpret the hypertext
language and display it correctly, and allow the user to follow links)
exist for all major platforms (VMS, Windows, DOS, Unix, VM, NeXTstep,
and Macintosh).@refill

The basic concepts used in the Web are @b{hypertext}, which is text
which is not constrained to be linear, and @b{hypermedia}, which is
information that is not constrained to be text.  With hypertext,
documents can contain @b{links} to other documents, or another reference
within the same document.  With hypermedia, documents can contain links
to objects that are not necessarily text - sounds, movies, and
interactive sessions are all possible.@refill

WWW also allows searches of indices that are located anywhere on the
network; in this respect, it mirrors certain capabilities found in both
WAIS and Gopher.@refill

Here are a few references to other documents.

@itemize @bullet
@item
<A HREF="http://info.cern.ch/">CERN's Web site, birthplace of WWW.</A>
@item
<A HREF="http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/StartingPoints/NetworkStartingPoints.html">NCSA's Network Starting Points Page.</A>
@item
<A HREF="http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/whats-new.html">NCSA's What's New Page</A>
@item
<A HREF="/usr/local/www/home-page.html">Indiana University Home Page</A>
@item
<A HREF="forms.html">Demo of the forms support.</A>
@item
<A HREF="file://cs.indiana.edu/pub/elisp/w3">Latest version of W3</A>
@end itemize

@ifinfo
@menu
* Setting Up::                  Getting and installing W3
* Starting Up::                 How to get into the Web
* Basic Movement::              Basics of navigating the Web with W3
@end menu
@end ifinfo


@ifinfo
@node Setting Up, Starting Up, Introduction, Introduction
@end ifinfo
@iftex
@unnumberedsec Setting Up
@end iftex

If you are using Lucid Emacs 19.9, you should be able to safely skip to
the section on starting W3.  W3 comes standard with all versions of
Lucid Emacs from 19.9 onwards.@refill

First off, you will need the file w3.tar.gz, which is available from
cs.indiana.edu:/pub/elisp/w3 via anonymous ftp.  If you do not have
ange-ftp, html-mode, or the nntp package by Masanobu Umeda, then you
will also need the extras.tar.gz.@refill

After you have retrieved the files unpack them with the following
commands: @kbd{zcat w3.tar.gz | tar xvvf -} and @kbd{zcat extras.tar.gz
| tar xvvf -}.  This will unpack distribution into two subdirectories
@file{w3} and @file{extras}.  To compile and install all the packages in
the extras directory, please see the comments at the top of each lisp
file.@refill

To install W3, go into the @file{w3} subdirectory and edit the
@file{Makefile}.  You need to change three variables:@refill

@iftex
@table @asis
@end iftex
@ifinfo
@table @var
@end ifinfo
@item EMACS
This variable controls what version of emacs is used to compile the
programs.  It should be the full path to the emacs executable on your
system.  Te default is to use Lucid Emacs (@file{lemacs}).@refill
@item LISPDIR
This variable controls where the lisp code will be copied to when it is
installed (with @code{make install}).  This will usually be your
personal lisp code directory (I prefer @file{~/lisp}).  The value will
be run through @dfn{expand-file-name} and then added to your
load-path.@refill
@item DOTEMACS
This variable points to your emacs customization file, usually
@file{~/.emacs}.  If you keep yours in a different place, you must
change this variable.  Otherwise @code{make emacs} will not work.@refill
@end table

Once you have modified the @file{Makefile}, you should be able to build
several different targets.@refill

@iftex
@table @asis
@end iftex
@ifinfo
@table @code
@end ifinfo
@item make w3
This will compile all the .el files into the much faster .elc files.  If
you are using Jamie Zawinski's optimizing byte compiler (standard in
Emacs 19 and Lucid Emacs), then you may see a few compilation warnings
(not many hopefully).  These can be safely ignored as long as everything
finishes compiling.  This is the default target for @code{make} with no
arguments.@refill
@item make install
This will compile all the .el files and then copy .el and .elc files
into the directory specified by @var{LISPDIR}.@refill
@item make emacs
This will modify the file specified by @var{DOTEMACS}.  A statement
modifying the load-path variable and size autoload statements will be
added to the end of the file.@refill
@item make all
This will compile and install the .el files, and also modify/create the
@var{DOTEMACS} file.@refill
@end table

Once you have done a @code{make intall} and a @code{make emacs} you
should be ready to start up W3.  @xref{Starting Up}.@refill

@ifinfo
@node Starting Up, Basic Movement, Setting Up, Introduction
@end ifinfo
@iftex
@unnumberedsec Starting Up
@end iftex

There are several ways to start W3: @kbd{M-x w3}, @kbd{M-x
w3-open-local}, @kbd{M-x w3-fetch}, @kbd{M-x w3-use-hotlist}, @kbd{M-x
w3-follow-url-at-point} and @kbd{M-x w3-preview-this-buffer}.@refill

@iftex
@table @asis
@end iftex
@ifinfo
@table @kbd
@end ifinfo
@findex w3
@vindex w3-default-homepage
@cindex URL
@cindex Uniform Resource Locator
@item M-x w3
Causes W3 to try and retrieve the file specified by
@var{w3-default-homepage}.  @var{w3-default-homepage} defaults to the
beginning of a hypertext documentation tree for W3 here at IU.  This
variable can be any valid @dfn{URL}.@refill

@findex w3-open-local
@item M-x w3-open-local
Will prompt for a filename on the local system.  W3 will open this file
and attempt to parse it as an HTML document.  Filename completion is
used.@refill

@findex w3-fetch
@item M-x w3-fetch
Will prompt for a valid URL.  W3 will attempt to parse this url and
retrieve the document specified.@refill

@findex w3-use-hotlist
@item M-x w3-use-hotlist
Will do a completing-read on w3-hotlist.  If a valid hotlist entry is
chosen, that URL is retrieved and parsed.@refill

@findex w3-follow-url-at-point
@item M-x w3-follow-url-at-point
Will attempt to find a url under the cursor and follow it.  Essentially
a w3-fetch on a buffer-substring.@refill

@findex w3-preview-this-buffer
@item M-x w3-preview-this-buffer
Will try to parse out the current buffers contents as an HTML document
and display them.@refill
@end table

@ifinfo
@node Basic Movement, Mosaic Compatibility, Starting Up, Introduction
@end ifinfo
@iftex
@unnumberedsec Basic Movement
@end iftex

Once you have started W3, there are a few basic keystrokes that should
get you started.  First, some terminology used within this
documentation.@refill

@iftex
@heading Basic W3 Terminology
@end iftex
@ifinfo
@center --------------------
@center Basic W3 Terminology
@center --------------------
@end ifinfo

@iftex
@table @asis
@end iftex
@ifinfo
@table @dfn
@end ifinfo

@item link
Is a hypertext link, either within this document, to another document,
or a forms-based entry area.@refill

@item hotlist
A hotlist is a list of items that you have marked for future quick
reference. @xref{Hotlist Handling}.@refill

@end table

@iftex
@heading Movement within the buffer
@end iftex
@ifinfo
@center --------------------
@center Movement, within the buffer, to other documents
@center --------------------
@end ifinfo

@iftex
@table @asis
@end iftex
@ifinfo
@table @kbd
@end ifinfo

@kindex SPC
@item SPC
Scroll downward in the buffer.  With prefix arg, scroll down that many
screenfuls. @refill

@kindex DEL
@item DEL
Scroll upward in the buffer.  With prefix arg, scroll up that many
screenfuls. @refill

@kindex <
@findex w3-start-of-document
@item <, M-x w3-start-of-document
Go to start of document

@kindex >
@findex w3-end-of-document
@item >, M-x w3-end-of-document
Go to end of document

@kindex b
@findex w3-back-link
@item b, M-x w3-back-link
Will attempt to move backward one link area in the current document.
Signals an error if no previous links are found.@refill

@kindex m
@findex w3-complete-link
@item m, M-x w3-complete-link
Choose a link from the current buffer and follow it.  A completing-read
is done on all the links, so @kbd{space} and @kbd{TAB} can be used for
completion.@refill

@kindex f
@findex w3-forward-link
@item f, M-x w3-forward-link
Will attempt to move forward one link area in the current document.
Signals an error if no more links are found.@refill

@kindex l
@findex w3-goto-last-buffer
@item l, M-x w3-goto-last-buffer
Go to last WWW buffer visited

@kindex RET
@findex w3-follow-link
@item RET 
Pressing return will attempt to follow the link under the cursor.@refill

@kindex H
@findex w3-use-hotlist
@vindex w3-keep-old-buffers
@item H, M-x w3-use-hotlist
Possibly go to a link in the hotlist.  A new buffer will be created for
the new document.  If the variable @var{w3-keep-old-buffers} is
non-@code{nil}, the current buffer will be kept.  If @code{nil}, then
the current buffer will be killed.@refill

@kindex U
@findex w3-use-links
@item 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.@refill

@kindex r
@findex w3-reload-document
@item r, M-x w3-reload-document
This will reload the current document - the current buffer is killed,
and the URL it was visiting is fetched and redisplayed.  Your position
within the buffer will remain the same (unless the document has changed
since you last retrieved it, in which case it should be relatively
close). @refill

@kindex o
@findex w3-open-local
@vindex w3-directory-format
@item o, M-x w3-open-local
Find a local file, interactively.  This will prompt you for a local file
name to open.  The file must exist, and may be a directory.  If the
requested file is a directory and @var{w3-directory-format} is
@code{'dired}, then a dired-mode buffer is displayed.  If
@code{'hypertext}, then W3 automatically generates a hypertext listing
of the directory.  @code{'hypertext} is the default, so that all the
keys and functions remain the same.@refill

@kindex s
@findex w3-search
@item s, M-x w3-search
Perform a search, if this is a searchable index.  This will send a
string of the type @samp{'URL?search-terms'} to the server this document
was retrieved from.  Searching requires a server, W3 can not do local
file searching, as there are too many possible types of searches people
could want to do.@refill

@kindex C-c C-b
@findex w3-show-history-list
@vindex w3-keep-history
@item C-c C-b, M-x w3-show-history-list
If @var{w3-keep-history} is non-@code{nil}, then W3 will keep track of
all the URLs you visit in an emacs session.  This function will take all
the links that are in that internal list, and format them as hypertext
links in a list.@refill

@kindex u
@kindex q
@findex w3-quit
@item u, q, M-x w3-quit
Quit WWW mode.  This kills the current buffer and goes to the most
recently visited buffer.@refill

@kindex button2
@findex w3-follow-mouse
@item button2, M-x w3-follow-mouse
This function expects to be bound to a mouse button.  It will move to
the point under mouse and try to fetch the link that was clicked on.  If
no link is found, a message is displayed in the minibuffer.@refill

@kindex C-o
@findex w3-fetch
@item 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 W3 cannot understand the type of link
you requested, the errors are displayed in a hypertext buffer.@refill

@end table

@iftex
@heading Information on links
@end iftex
@ifinfo
@center --------------------
@center Information
@center --------------------
@end ifinfo

@iftex
@table @asis
@end iftex
@ifinfo
@table @kbd
@end ifinfo

@kindex v
@findex w3-view-url
@item v, M-x w3-view-url
View the current document's URL in the minibuffer.@refill

@kindex V
@findex w3-view-this-url
@item V, M-x w3-view-this-url
This will display the URL of the link under point in the minibuffer.  If
no link is found, an error message is displayed in the
minibuffer.@refill

@kindex C-k
@findex w3-save-url
@item C-k, M-x w3-save-url
Save current url in the kill ring, and copy it to the Xwindows clipboard
if necessary.  With prefix-arg, this function operates on the URL under
point instead.@refill

@kindex M-TAB
@findex w3-insert-this-url
@item M-TAB, M-x w3-insert-this-url
Insert the current url in another buffer, with prefix ARG, insert URL
under point.  Prompts for a buffer to insert into.  Point and
current-buffer are not affected.@refill

@kindex C-q
@findex w3-write-global-history
@vindex w3-global-history-file
@vindex w3-keep-history
@item C-q, M-x w3-write-global-history
Write the global history file into @var{w3-global-history-file}.  This
will only work if @var{w3-keep-history} is non-@code{nil} so that W3 has
been keeping track of the URLs that have been visited.

@kindex C-c C-v
@findex w3-version
@item C-c C-v, M-x w3-version
Show the version number of W3 in the minibuffer.

@end table

@iftex
@heading Miscellaneous Keys
@end iftex
@ifinfo
@center --------------------
@center Miscellaneous Keys
@center --------------------
@end ifinfo

@iftex
@table @asis
@end iftex
@ifinfo
@table @code
@end ifinfo

@kindex M
@findex w3-mail-current-document
@item M, M-x w3-mail-current-document
Mail the current-document to someone.  You can mail several different
formats, including LaTeX, HTML source, or formatted text.@refill

@kindex P
@findex w3-print-this-url
@item P, M-x w3-print-this-url
Print out the current document.  You can print out several different
formats, including Postscript (via conversion to LaTeX), HTML source, or
formatted text.  @xref{Printing}.@refill

@kindex h
@findex w3-help
@item h, M-x w3-help
Display documentation on W3 mode - this is a hypertext document
generated automatically by W3 from a list of functions and
variables.@refill

@kindex w
@findex w3-submit-bug
@item w, M-x w3-submit-bug
Function to submit a bug to the programs maintainer.  Will include the
version of W3 and emacs that you are using automatically. @refill

@kindex button3
@findex w3-popup-menu
@item button3, M-x w3-popup-menu
Pop up a menu of common W3 commands.  Expects to be bound to a mouse
key.@refill

@kindex M-s
@findex w3-document-source
@item M-s, M-x w3-document-source
View this documents source.

@end table

@ifinfo
@node Mosaic Compatibility, Hyperbole Compatibility, Basic Movement, Top
@end ifinfo
@iftex
@unnumbered Mosaic Compatibility
@end iftex

Since NCSA Mosaic is the de-facto hypertext browser at most sites, W3 is
compatible with it in several ways.@refill

@ifinfo
@menu
* Hotlist Handling::            Hotlist Handling
* History::                     History
* Annotations::                 Annotations
@end menu
@end ifinfo

@ifinfo
@node Hotlist Handling, History, Mosaic Compatibility, Mosaic Compatibility
Compatibility
@end ifinfo
@iftex
@unnumberedsec Hotlist Handling
@end iftex

In order to avoid having to traverse many documents to get to the same
document over and over, W3 supports a ``hotlist'' like Mosaic.  This is
a file that contains URLS and aliases.  You can quickly go to any
document in the Web, providing you've been there before and added it to
your hotlist.  The variable @var{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.@refill

Hotlist commands are:

@itemize @bullet
@item
@kindex a
@findex w3-add-document-to-hotlist
@vindex w3-hotlist-file
To add a document to your hotlist, just hit @kbd{a} or @kbd{M-x
w3-add-document-to-hotlist} in any W3 buffer.  This will add the current
document to your hotlist, with the buffer name as its identifier.  This
function will modify the file specified by @var{w3-hotlist-file}.@refill

@item
@findex w3-remove-from-hotlist
@vindex w3-hotlist-file
@kindex d
To kill a hotlist entry, hit @kbd{d} in a W3 buffer, or @kbd{M-x
w3-remove-from-hotlist} in any buffer.  You will be prompted for the
alias of the entry to kill.  You may press the spacebar or tab key for
partial completions.  Once you select the item to delete, the internal
representation of the hotlist is updated, and the file specified by
@var{w3-hotlist-file}.@refill

@item
@kindex H
@findex w3-use-hotlist
To jump to a hotlist entry, type @kbd{H} in any W3 buffer, or @kbd{M-x
w3-use-hotlist} from anywhere will prompt you for the alias to jump to.
You may press the spacebar or tab key for partial completions.@refill

@item
@findex w3-show-hotlist
To see a list of all your hotlist entries in a W3 buffer, type
@kbd{M-x w3-show-hotlist} from any buffer.  This will convert your
hotlist into an ordered list and parse it as HTML.@refill

@item
@findex w3-rename-hotlist-entry
@vindex w3-hotlist-file
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 @kbd{M-x w3-rename-hotlist-entry}.  You will be prompted for the
item to rename in the minibuffer - you may use the spacebar or tab key
for completion.  After you have chosen an item to rename, you will be
prompted for a new title until you enter one that does not already
exists in the hotlist.  This function modifies the  file specified by
@var{w3-hotlist-file}.@refill

@end itemize

@ifinfo
@node History, Annotations, Hotlist Handling, Mosaic Compatibility
@end ifinfo
@iftex
@unnumberedsec History
@end iftex
@cindex History Lists

Mosaic supports the idea of a ``history'' of URLs you have visited, and
it displays them in a different style than normal URLs so you will not
visit someplace again on accident.@refill

@vindex w3-keep-history
@kindex C-q
@vindex w3-global-history-file
@findex w3-write-global-history
If you set the variable @var{w3-keep-history} to @code{t}, then W3 will
keeep a list of all the URLS you visit in a session.  To write the file
out, you will have to hit @kbd{C-q} in a W3 buffer, or @kbd{M-x
w3-write-global-history} then the list will be added to those already in
the file specified by @var{w3-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.@refill

@findex w3-show-history
To see a listing of your history for this session of W3, you can type
@var{M-x w3-show-history} from any buffer, and W3 will generate an HTML
document showing every URL you have visited since you started emacs (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, you can choose 'Clear History' from the 'Options' menu.@refill

@findex w3-forward-in-history
@findex w3-backward-in-history
@findex w3-fetch
Another twist on the history list mechanism is the fact that all 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
@b{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 @code{w3-forward-in-history},
to go backward, use the function @code{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. @refill

@ifinfo
@node Annotations, Group Annotations, History, Mosaic Compatibility
@end ifinfo
@iftex
@unnumberedsec Annotations
@end iftex
@cindex Annotations
Mosaic allows you to @i{annotate} documents.  You can type in comments
about the current document, and these annotations will appear as a link
to your comments at the end of the document when you browse it in
Mosaic.  The original file is not changed.@refill

There are two types of annotations supported in Mosaic, and both are
supported by W3 as well.@refill

@ifinfo
@menu
Group Annotations::             Annotations accessible by everyone
Personal Annotations::          Private annotations only you see
@end menu
@end ifinfo

@ifinfo
@node Group Annotations, Personal Annotations, Annotations, Annotations
@end ifinfo
@iftex
@unnumberedsubsec Group Annotations
@end iftex
@cindex Group Annotations

@b{@i{NOTE}}: The group annotation experiment has been terminated.  NCSA
is running the annotation server temporarily, but it will not be around
much longer.  It will be replaced with support on the server side for
adding <LINK> tags to documents.@refill

An experimental @i{annotation server} is running at NCSA.  This server
allows people to annotate any document on the Web, and have anyone else
see it.  To activate this feature in Mosaic, set the resource
Mosaic*annotationServer to hoohoo.ncsa.uiuc.edu:8001.@refill

@vindex w3-group-annotation-server
@vindex w3-group-annotation-port
In W3, if the variable @var{w3-group-annotation-server} is defined, then
it will try to contact the server and retrieve any annotations for the
current document.  This variable should be a string containing the name
of the annotation server (defaults to "hoohoo.ncsa.uiuc.edu").  To turn
off group annotation support, set this variable to @code{nil}.  If you
have a slow connection to NCSA, I'd recommend doing this.  The variable
@var{w3-group-annotation-port} defaults to 8001, and should be an
integer representing the port number the server is running on.@refill

The group annotations (if any) will appear as normal links at the bottom
of your document.  They can be selected just like any other link.@refill

Both Mosaic and W3 support multiple levels of annotation (Annotations on
annotations ad infitim).@refill

@findex w3-add-group-annotation
To create a new annotation, type @kbd{M-x w3-add-group-annotation}.
This will put you in a new buffer, in HTML-mode.  If you are not
familiar with HTML-mode, hit @kbd{C-h m} for instructions, and see the
file html-mode.el that came with W3.  At the top of this buffer is an
HTML tag (</PRE>).  If you don't want to use any HTML commands, you can
delete this and just type in your message and it should be formatted
just as you type it.  If you leave this in, you can use any HTML
formatting command (italics, headings, bold, etc) except adding a title.
When you are finished editing your annotation, type @kbd{C-c C-c}.  W3
will then prompt you for a title for your annotation, defaulting to
"Annotation by <user information>".  Hit return after typing in your
title.  If any errors are received, they will be reported in a separate
buffer.@refill

@findex w3-delete-group-annotation
To delete an annotation, you must be reading it.  Then type @kbd{M-x
w3-delete-group-annotation}.  If any errors are received, they will be
displayed in a separate buffer.@refill

I do not currently support editing group annotations.@refill

@ifinfo
@node Personal Annotations, Hyperbole Compatibility, Group Annotations, Annotations
@end ifinfo
@iftex
@unnumberedsubsec Personal Annotations
@end iftex
@cindex Personal Annotations

@vindex w3-personal-annotation-directory
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.@refill

W3 will look in the directory specified by
@var{w3-personal-annotation-directory} (defaults to
~/.mosaic-personal-annotations).  Any personal annotations for a
document will be automatically appended when it is retrieved.@refill

@findex w3-add-personal-annotation
To add a new personal annotation, type @kbd{M-x
w3-add-personal-annotation}.  This will put you in a new buffer, in
HTML-mode.  If you are not familiar with HTML-mode, hit C-h m for
instructions, and see the file html-mode.el that came with W3.  At the
top of this buffer is an HTML tag </PRE>.  If you don't want to use any
HTML commands, you can delete this and just type in your message and it
should be formatted just as you type it.  If you leave this in, you can
use any HTML formatting command (italics, headings, bold, etc) except
adding a title.  When you are finished editing your annotation, hit C-c
C-c.  It will then prompt you for a title for your annotation,
defaulting to Annotation by <user information> on <date>.@refill

@findex w3-delete-personal-annotation
To delete a personal annotation, you must be reading it.  Once reading
the annotation, type @kbd{M-x w3-delete-personal-annotation}.  It will
delete the file containing the annotation, and any references to it in
your log file.@refill

I do not currently support editing personal annotations.@refill

@ifinfo
@node Hyperbole Compatibility, Internals of W3, Personal Annotations, Top
@end ifinfo
@iftex
@unnumbered Hyperbole Compatibility
@end iftex

@cindex Hyperbole
Since hyperbole is such a general package, I have included a file
written by Jin S. Choi (jsc@@monolith.mit.edu) to add W3 support to
hyperbole.  There are 2 small changes you have to make to the hyperbole
source, but they are extremely minor (they keep hyperbole from thinking
URLs are ftp links).  See the file w3-hyperbole.el for more
information.@refill

I am considering merging W3 with hyperbole more completely, but am not
sure if this is a good idea.  If you have any strong feelings on the
subject, send mail to me at wmperry@@indiana.edu.  Any comments
welcome.@refill

@ifinfo
@node Internals of W3, Customizing Formatting, Hyperbole Compatibility, Top
@end ifinfo
@iftex
@unnumbered Internals of W3
@end iftex
@cindex Internals of W3
@cindex Using W3 from your own programs

I have done quite a bit of work trying to make a semi-clean interface to
the internals of W3.  Here is a list of functions that you can use to
take advantage of the World Wide Web.@refill

@iftex
@table @asis
@end iftex
@ifinfo
@table @code
@end ifinfo

@findex w3-clear-tmp-buffer
@vindex w3-working-buffer
@item w3-clear-tmp-buffer
This will set the current buffer to be @var{w3-working-buffer}, creating
it if necessary, and erase it.  This should usually be called before
retrieving URLs.@refill

@findex w3-convert-ask-to-form
@item w3-convert-ask-to-form
This functions takes a string that is a Gopher+ ASK block, and will
return a string that is a comparable HTML+ form.@refill

@findex w3-convert-html-to-latex
@item w3-convert-html-to-latex
This will take a buffer of HTML markup (which should be in
@var{w3-working-buffer}), and convert it into LaTeX.  This is an
adaptation of the simple sed scripts from Cern.  Does as good a job as
the html2latex program, and I usually prefer its formatting over
html2latex's.@refill

@findex w3-extension-to-mime
@vindex w3-mime-extensions
@item w3-extension-to-mime
This functions takes a file extension and returns the corresponding
MIME-type, as defined in @var{w3-mime-extensions}.  For example,
@samp{(w3-extension-to-mime ".gif")} would return
@samp{"image/gif"}.@refill

@findex w3-fetch
@item w3-fetch
This function takes a URL, a method, and a block of data as its
arguments.  It then attempts to retrieve the URL using the specified
method, using data (if any) as the body of the MIME request.  For
example: @samp{(w3-fetch "http://cs.indiana.edu/" "GET" nil)} would
retrieve the Indiana University CS home page and parse it as
HTML.@refill

@findex w3-fix-entities-in-string
@vindex w3-html-entities
@item w3-fix-entities-in-string
This function takes a string, and removes all HTML[+] entity references
from it, replacing them with the correct character(s).  It consults the
variable @var{w3-html-entities} for the entity names and translations.
For example, @samp{(w3-fix-entities-in-string "&gt;testing&lt;&amp;")}
would return @samp{">testing<&"}.@refill

@findex w3-generate-new-buffer-name
@item w3-generate-new-buffer-name
This function takes a string, and returns the first unique buffer name
using that string as a base.  For example
@samp{(w3-generate-new-buffer-name "new-buff")} would return
@samp{"new-buff<1>"} if buffer new-buff already existed.@refill

@findex w3-generate-unique-filename
@item w3-generate-unique-filename
This functions returns a string that represents a unique filename in the
/tmp directory.  For example, @samp{(w3-generate-unique-filename)} would
return @samp{"/tmp/w3-tmp129440"}.  The filename is arrived at by using
a unique prefix (w3-tmp), the uid of the current user (12944 in my
case), and a number that is incremented if a file already exists.@refill

@findex w3-get-url-at-point
@item w3-get-url-at-point
This function returns the url at a point specified by an optional
argument.  If no argument is given to the function (point) is used.
Tries to find the url closest to that point, but does not change the
users position in the buffer.  Has a preference for looking backward
when not directly on a URL.@refill

@findex w3-hexify-string
@item w3-hexify-string
This function takes a string and replaces any characters that are not
acceptable in a URL with the "escaped" encoding that is standard for
URLs (replaces the character with a % followed by the hexadecimal
representation of the ASCII value of the character).  For example,
@samp{(w3-hexify-string "this is a test")} would return
@samp{"this%20is%20a%20test"}.@refill

@findex w3-insert-entities-in-string
@item w3-insert-entities-in-string
This function takes a string and replaces any occurences of HTML[+]
reserved characters with the corresponding entity definitions.  For
example, @samp{(w3-insert-entities-in-string "<testing>")} would return
@samp{"&lt;testing&gt;"}.@refill

@findex w3-mime-viewer
@vindex w3-mime-viewers
@item w3-mime-viewer
This functions takes a string specifying a MIME content-type, and
returns a string or symbol.  If it returns a string, it specifies a
shell command to execute to view that type of file.  This string can be
passed to 'format with a file name to get the complete command to use.
If it is a symbol, it represents an emacs lisp function to call with no
arguments.@refill

@findex w3-open-stream
@item w3-open-stream
This function takes the same parameters as @code{open-network-stream},
and functions similarly.  It takes a process name, a buffer name, a host
name, and a port number or server name.  It attempts to open a network
connection to the remote host on the specified port/service name, with
output going to the buffer.  It returns the process object that is the
network connection.@refill

@vindex w3-use-telnet
@vindex w3-telnet-prog
This function is different from @code{open-network-stream} in that it
allows you to use programs in a subprocess to emulate a network
connection.  This is necessary if you are behind a firewall, or
something similar.  If the variable @var{w3-use-telnet} is @code{t},
then the program specified by @var{w3-telnet-prog} will be run in an
asynchronous subprocess.  This program should expect a command line of
the form @samp{w3-telnet-prog hostname portnumber}, and feed anything on
its standard input to the remote machine.@refill

@findex w3-retrieve
@item w3-retrieve
This function takes 3 arguments, a URL, a method type, and a data block.
It then attempts to retrieve the URL using the specified method, using
data (if any) as the body of the MIME request.  For example:
@samp{(w3-fetch "http://cs.indiana.edu/" "GET" nil)} would retrieve the
Indiana University CS home page.  This function will do @b{no} parsing
of the retrieved page, and leaves you in the buffer containing the
document you requested.  Any HTTP/1.0 redirection/authorization is done
before this function exits.@refill

@findex w3-unhex-string
@item w3-unhex-string
This is the opposite of @code{w3-hexify-string}.  It removes any %XXX
encoded characters in a string.  For example @samp{(w3-unhex-string
"this%20is%20a%20test")} would return @samp{"this is a test"}.@refill

@findex w3-upcase-region
@item w3-upcase-region
This function takes a start and end position in the current buffer as
its arguments, and converts all the text to uppercase, except for text
between < and >.  This is useful for converting regions to uppercase
without corrupting any URLs within it.@refill

@findex w3-view-this-url
@item w3-view-this-url
This function returns the URL of the zone under point (if no zone is
under point, then it returns nil).  If the optional argument is
@code{nil}, then the URL is also displayed in the minibuffer.@refill

@findex w3-view-url
@item w3-view-url
This function returns the URL of current document.  If the optional
argument is @code{nil}, then the URL is also displayed in the
minibuffer.@refill
@end table

@ifinfo
@node Customizing Formatting, Character based terminals, Internals of W3, Top
@end ifinfo
@iftex
@unnumbered Customizing Formatting
@end iftex
@cindex Customizing formatting
@cindex Specifying Fonts
@cindex Fonts
@cindex Colors

How W3 formats a document is very customizable.  How a document is
displayed depends on several things - whether the user is on a terminal
capable of graphics, and a few variables.@refill

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

@ifinfo
@menu
* General formatting::                 Changing general things about a
                                       document.
* Character based terminals::          Changing how a document is
                                       displayed on a non-graphics
                                       terminal (vt100, etc) or if
                                       @var{w3-delimit-emphasis} is @code{t}.
* Graphics workstations::              Changing how a document is
                                       displayed on a graphics terminal
                                       (Xwindows, Windows, NeXTstep,
                                       OS/2, etc)
@end menu
@end ifinfo

@ifinfo
@node General formatting, Character based terminals, Customizing Formatting, Customizing Formatting
@end ifinfo
@iftex
@unnumberedsec General formatting conventions
@end iftex
@iftex
@heading Formatting of hypertext links
@end iftex
@ifinfo
@center --------------------
@center Formatting of hypertext links
@center --------------------
@end ifinfo
@vindex w3-delimit-links
@vindex w3-link-start-delimiter
@vindex w3-link-end-delimiter
If the variable @var{w3-delimit-links} is non-@code{nil}, then hypertext
links will be surrounded by text specified by the user.  The string
@var{w3-link-start-delimiter} will be inserted just before the body of
the hyperlink, and @var{w3-link-end-delimiter} will be inserted just
after the body of the link.  All reserved characters should be replaced
with their HTML[+] entity definitions.@refill
@iftex
@heading Formatting of lists
@end iftex
@ifinfo
@center --------------------
@center Formatting of lists
@center --------------------
@end ifinfo
@vindex tab-stop-list
@vindex tab-width
@vindex w3-mode-hooks
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, you should set the
variables @var{tab-stop-list} and @var{tab-width}.  A tab every eight
spaces is considered normal, but I prefer to have a tab every four
spaces.  So @var{tab-stop-list} would be @samp{'(4 8 12 16 20 24 28 32
36 ...)}, and @var{tab-width} would be @samp{4}.  I use
@code{setq-default} in my .emacs for these, but you can also use them
from @var{w3-mode-hooks}.  Something like @samp{(add-hook 'w3-mode-hooks
(function (lambda () (setq tab-stop-width '(...)  tab-width
4))))}.@refill

@vindex w3-list-chars-assoc
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
@var{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 @code{car} of this list should be the type of
list, in all caps (ie: @samp{UL}).  The rest of the list should consist
of strings to insert at certain levels of lists.  The @code{n}th element
of this list will be used when the list is nested @code{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 '.'.@refill

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

@ifinfo
@node Character based terminals, Graphics workstations , General formatting, Customizing Formatting
@end ifinfo
@iftex
@unnumberedsec On character based terminals
@end iftex
@vindex w3-delimit-emphasis
On character based terminals, there is no easy way to show that a
certain range of text is in bold or italics.  If the variable
@var{w3-delimit-emphasis} is non-@code{nil}, then W3 can insert
characters before and after character formatting commands in HTML
documents.@refill

@vindex w3-header-chars-assoc
@vindex w3-style-chars-assoc
Two variables control what text is inserted around different markup
tags.  @var{w3-header-chars-assoc} controls what characters are inserted
around header items, and @var{w3-style-chars-assoc} controls what
characters are inserted around most other markup (italics, addresses,
etc).@refill

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

@var{w3-style-chars-assoc} is an assoc list of style tags and a list of
strings.  The @code{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 @code{car} is text to insert before the stylized text.  The
@code{cdr} is text to insert after the stylized text.  Both should have
reserved characters converted to their HTML[+] entity
definitions.@refill

@ifinfo
@node Graphics workstations, Printing, Character based terminals, Customizing Formatting
@end ifinfo
@iftex
@unnumberedsec With graphics workstations
@end iftex
@cindex Xresources
@cindex NeXTstep resources
When you are running in a graphic environemnt (Xwindows or NeXTstep for
example), the fonts and colors used by W3 to display text can be
controlled by setting a few resources.  To specify these
resources:@refill

@itemize @bullet
@item
Xwindows: Place them into your @file{~/.Xresources} file or the
@file{/usr/lib/X11/app-defaults/Emacs} file.@refill
@item
NeXTstep: If you are using the NeXTstep port of Emacs 19, you should use
the dwrite command to install these resources.  The command should look
something like: (@samp{dwrite Emacs <Style>.Attribute<item> value}, where
style and attribute are one of the choices below.@refill
@item
OS/2 or Windows: If you are using the Lucid Emacs or FSF Emacs that has
been ported to the Presentation Manager or Windows 3.x, it will tell you
where to store a file that Emacs will look at for Xresources.@refill
@end itemize

The resources for each version of emacs are the same.  For each style of
text that W3 uses, you can specify any of the following resources by
replacing <style> with the actual style name.@refill

@itemize @bullet
@item
Emacs*<Style>.AttributeFont: Font name
@item
Emacs*<Style>.AttributeForeground: Foreground color
@item
Emacs*<Style>.AttributeBackground: Background color
@item
Emacs*<Style>.AttributeUnderline: Underline text?
@end itemize

W3 uses these style names:
@iftex
@table @asis
@end iftex
@ifinfo
@table @var
@end ifinfo
@item w3-address-style
For anything in $<$ADDRESS$>$ tags.
@item w3-bold-style
For anything in bold, strong, or a definition
@item w3-default-style
For normal text
@item w3-header-style
For any headers
@item w3-italic-style
For italic text, emphasized, or addresses
@item w3-node-style
For links to other documents
@item w3-strikethru-style
For items that should be shown as struck-out.
@item w3-subscript-style
For subscripted items
@item w3-superscript-style
For superscripted items
@item w3-tt-style
For fixed width fonts, code segments, samples, or variables
@item w3-underline-style
For underlining, and citations
@end table

@ifinfo
@node Printing, Saving Files, Graphics workstations, Top
@end ifinfo
@iftex
@unnumbered Printing
@end iftex
@cindex Printing
@findex w3-print-this-url
@kindex P
@findex w3-print-url-under-point
There are two ways to print a document in W3.  Typing @kbd{P} or
@kbd{M-x w3-print-this-url} will print out the current document, and
typing @kbd{M-x w3-print-url-under-point} will attempt to print the
document the cursor is on.

You will be prompted to choose how the document will be printed.  

@vindex w3-use-html2latex
@vindex w3-print-command


@ifinfo
@node Saving Files, Using W3 behind a firewall, Printing, Top
@end ifinfo
@iftex
@unnumbered Saving Files
@end iftex

@ifinfo
@node Using W3 behind a firewall, Hook Variables, Saving Files, Top
@end ifinfo
@iftex
@unnumbered Using W3 behind a firewall
@end iftex

@ifinfo
@node Hook Variables, Miscellaneous, Using W3 behind a firewall, Top
@end ifinfo
@iftex
@unnumbered Hook Variables
@end iftex

@ifinfo
@node Miscellaneous, More Help, Hook Variables, Top
@end ifinfo
@iftex
@unnumbered Miscellaneous
@end iftex

@ifinfo
@node More Help, HTML, Miscellaneous, Top
@end ifinfo
@iftex
@unnumbered More Help
@end iftex

@cindex Relevant Newsgroups
@cindex Newsgroups
@cindex Support
If you need more help on W3, please send me mail (wmperry@@indiana.edu).
Several discussion lists have also been created for W3.  To subscribe,
send mail to <listname>-request@@indiana.edu.  All other mail should go
to <listname>@@indiana.edu@refill

@itemize @bullet
@item
w3-announce - this list is for anyone interested in 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.  You may use this if you have
written an enhancement to W3 that you wish more people to know about.
(www-announce@@info.cern.ch is included on this list).@refill
@item
w3-beta - this list is for beta testers of W3.  These brave souls test
out not-quite stable code.@refill
@item
w3-dev - a list consisting of myself and a few other people who are
interested in the internals of W3, and doing active development work.
Pretty dead right now, but I hope it will grow.@refill
@end itemize

If you need more help on the World Wide Web in general, please refer to
the newsgroup comp.infosystems.www.  There are also several discussion
lists concerning the Web.  Send mail to listserv@@info.cern.ch with a
subject line of 'subscribe <listname>'.  All mail should go to
<listname>@@info.cern.ch.  Administrative mail should go to
www-admin@@info.cern.ch.  The lists are:@refill

@itemize @bullet
@item
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.@refill
@item
www-announce - for announcements concerning the World Wide Web.  Server
changes, new servers, new software, etc.@refill
@end itemize

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

@ifinfo
@node HTML, WWW, More Help, Top
@end ifinfo
@iftex
@unnumbered HTML
@end iftex
@cindex HTML
@cindex Hypertext Markup Language

HTML is composed of a set of elements that define a document and guide
its display.  An HTML element may include a name, some attributes and
some text or hypertext, and will appear in an HTML document as
<tag_name> text </tag_name> <tag_name attribute_name=argument> text
</tag_name>, or just <tag_name>.@refill

For example: @samp{<title> My Useful Document </title>}, and @samp{<pre
width=60> A lot of text here.  </pre>}. @refill

An HTML document is composed of a single element: <html>...</html>, that
is, in turn, composed of head and body elements: <head>...</head>, and
<body>...</body>.  To allow older HTML documents to remain readable,
<html>, <head>, and <body> are actually optional within HTML
documents.@refill

@iftex
@heading Elements restricted to the head element include:
@end iftex
@ifinfo
@center Elements restricted to the head element include:
@end ifinfo

@itemize @bullet
@item
<isindex> -  Specify index file. @refill
@item
<title> .  .  .  </title> -  Specify document title. @refill
@item
<nextid> - Set a variable value.  Attribute: variable name. @refill
@item
<link> - Specify relationships to other documents.  Attributes: same as
Anchor below. @refill
@item
<base> -  Specify the name of the file in which the current document is
stored.  This is useful when link references within the document do  not
include full pathnames (i.e., are partially qualified)
@end itemize

The following sections describe elements that can be used in the body of
the document.

@iftex
@heading Text Elements
@end iftex
@ifinfo
@center Text Elements
@end ifinfo

@itemize @bullet
@item
<p> - The end of a paragraph that will be formatted before it is
displayed on the screen. @refill
@item
<pre> .  .  .  </pre> - Identifies text that has already been formatted
(preformatted) by some other system and must be displayed as is.
Preformatted text may include embedded tags, but not all tag types are
permitted.  Attribute: width. @refill
@item
<listing> .  .  .  </listing> - Example computer listing; embedded tags
will be ignored, but embedded tabs will work. @refill
@item
<plaintext> - all text from this marker to the end of the document will
not be parsed as HTML.  All newlines/tabs/spaces will be
preserved. @refill
@item
<blockquote> .  .  .  </blockquote> - Include a section of text quoted
from some other source. @refill
@end itemize

@iftex
@heading Hyperlinks or Anchors
@end iftex
@ifinfo
@center Hyperlinks or Anchors
@end ifinfo

@itemize @bullet
@item
<a name="target_anchor_name"> .  .  .  </a> -  Define a target location
in a document. @refill
@item
<a href="#anchor_name"> .  .  .  </a> - Link to a location in the same
file. @refill
@item
<a href="URL"> .  .  .  </a> - Link to another file. @refill
@item
<a href="URL#target_string"> .  .  .  </a> - Link to a target location
in another file. @refill
@end itemize

Required attributes for anchors: one of name or href.  Optional
attributes: rel, rev, urn, title, methods.@refill

@iftex
@heading Headers
@end iftex
@ifinfo
@center Headers
@end ifinfo

@itemize @bullet
@item
<h1> .  .  .  </h1> - Most prominent header.
@item
<h2> .  .  .  </h2>
@item
<h3> .  .  .  </h2>
@item
<h4> .  .  .  </h4>
@item
<h5> .  .  .  </h5>
@item
<h6> .  .  .  </h6> - Least prominent header.
@end itemize

@iftex
@heading Logical Styles
@end iftex
@ifinfo
@center Logical Styles
@end ifinfo

@itemize @bullet
@item
<em> .  .  .  </em> - Generic emphasis.
@item
<strong> .  .  .  </strong> - Stronger emphasis
@item
<code> .  .  .  </code> - Display an HTML directive
@item
<samp> .  .  .  </samp> - Include sample output
@item
<kbd> .  .  .  </kbd> - Display a keyboard key
@item
<var> .  .  .  </var> - Define a variable
@item
<dfn> .  .  .  </dfn> - Display a definition
@item
<cite> .  .  .  </cite> - Display a citation
@end itemize

@iftex
@heading Physical Styles
@end iftex
@ifinfo
@center Physical Styles
@end ifinfo

@itemize @bullet
@item
<b> .  .  .  </b> - Bold font 
@item
<i> .  .  .  </i> - Italics 
@item
<u> .  .  .  </u> - Underline
@item
<tt> .  .  .  </tt> - Typewriter font
@end itemize

@iftex
@heading List Types
@end iftex
@ifinfo
@center List Types
@end ifinfo

@itemize @bullet
@item
Definition list/glossary: <dl> ... </dl>, <dt> defines a term to be
defined, <dd> is the definition of the term.
@item
Unordered list: <ul> ... </ul>.  <li> defines an item of the list.
@item
Ordered list: <ol> ... </ol>.  <li> defines an item of the list.
@item
Interactive menu: <menu> ... </menu>.  <li> defines an item of the list.
@item
A directory list of items: <dir> ... </dir> <li> defines an item of the list.
@end itemize

@iftex
@heading Entities
@end iftex
@ifinfo
@center Entities
@end ifinfo

@iftex
@table @asis
@end iftex
@ifinfo
@table @code
@end ifinfo
@item &keyword;
Display a particular character identified by a special keyword.  For
example the entity &amp; specifies the ampersand ( & ), and the entity
&lt; specifies the less than ( < ) character. Note that the semicolon
following the keyword is required.@refill
@item &#ascii_equivalent;
Use a character literally.  Again note that the semicolon following the
ASCII numeric value is required.@refill
@item <!-- text -->
Place a comment in the HTML source
@end table

@ifinfo
@node WWW, Concept Index, HTML, Top
@end ifinfo
@iftex
@unnumbered WWW
@end iftex
@cindex WWW
@cindex World Wide Web

@ifinfo
@node Concept Index, Key Index, WWW, Top
@end ifinfo
@iftex
@unnumbered Concept Index
@end iftex
@printindex cp

@ifinfo
@node Key Index, Command Index, Concept Index, Top
@end ifinfo
@iftex
@unnumbered Key Index
@end iftex
@printindex ky

@ifinfo
@node Command Index, Variable Index, Key Index, Top
@end ifinfo
@iftex
@unnumbered Command Index
@end iftex
@printindex fn

@ifinfo
@node Variable Index, Introduction, Command Index, Top
@end ifinfo
@iftex
@unnumbered Variable Index
@end iftex
@printindex vr

@summarycontents
@contents
@bye
