\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 @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 * Introduction:: Overview of the W3 interface * Markup Languages Supported:: What markup languages are supported? * Supported Protocols:: What network protocols are supported? * HTTP/1.0 Support:: How W3 complies with the HTTP/1.0 specification * Mosaic Compatibility:: Different ways W3 is compatible with NCSA Mosaic. * Hyperbole Compatibility:: How to use W3 with Hyperbole * 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 * Internals of W3:: How to use W3 from your own programs * More Help:: How to get more help -- mailing lists, newsgroups, etc 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 @ifinfo @node Introduction, Setting Up, Top, 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 @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 @table @code @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. The 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 @table @code @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 @code{LISPDIR}.@refill @item make emacs This will modify the file specified by @code{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 @code{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 @table @kbd @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 @code{w3-default-homepage}. @code{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, Markup Languages Supported, 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 @table @dfn @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 @table @kbd @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 Attempts 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 Attempts 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 attempts 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 is created for the new document. If the variable @code{w3-keep-old-buffers} is non-@code{nil}, the current buffer is kept. If @code{nil}, then the current buffer is killed.@refill @findex w3-show-hotlist @item M-x w3-show-hotlist Possibly go to a link in the hotlist. A hypertext listing of the items in the hotlist is generated on the fly, and the links can be followed normally.@refill @kindex U @findex w3-use-links @item U, M-x w3-use-links Select one of the 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 reloads the current document -- the current buffer is killed, and the URL it was visiting is fetched and redisplayed. Your position within the buffer remains 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 prompts 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 @code{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 sends 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 @code{w3-keep-history} is non-@code{nil}, then W3 keeps track of all the URLs you visit in an Emacs session. This function takes all the links that are in that internal list, and formats them as hypertext links in a list.@refill @kindex q @findex w3-quit @item q, M-x w3-quit Quits WWW mode. This kills the current buffer and goes to the most recently visited buffer.@refill @kindex u @findex w3-leave-buffer @item u, M-x w3-leave-buffer This is similar to w3-quit, but the buffer is not killed, it is moved to the bottom of the buffer list (so it is the least likely to show up as the default with switch-to-buffer). @kindex button2 @findex w3-follow-mouse @item button2, M-x w3-follow-mouse This function expects to be bound to a mouse button. It movess 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-button2 @kindex C-return @findex w3-follow-inlined-image @item C-button2, C-return, M-x w3-follow-inlined-image This function tries to retrieve the inlined image that is under point. It ignores any form entry areas or hyperlinks, and blindly follows any inlined image. Useful for seeing images that are meant to be used as hyperlinks when you are not on a terminal capable of displaying graphics.@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 @table @kbd @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 displays 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 M-x w3-insert-formatted-url @findex w3-insert-formatted-url @item M-x w3-insert-formatted-url Inserts a formatted construct into a buffer. The HREF is the url of the current buffer (or link under point with prefix arg), and text of the link defaults to the title of the buffer or the text of the link under cursor. Buffer to insert into is prompted for.@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 @code{w3-global-history-file}. This only works if @code{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 @table @code @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. Includes 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 Markup Languages Supported, Supported Protocols, Basic Movement, Top @end ifinfo @iftex @unnumbered Supported Markup Languages @end iftex Two different markup languages are supported by W3. @ifinfo @center ---------- @center HTML @center ---------- @end ifinfo @iftex @unnumberedsec HTML @end iftex 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 text , text , or just .@refill For example: @samp{ My Useful Document }, and @samp{
 A lot of text here.
}. @refill An HTML document is composed of a single element: ..., that is, in turn, composed of head and body elements: ..., and .... To allow older HTML documents to remain readable, , , and are actually optional within HTML documents.@refill All the tags and attributes of HTML are fully supported in W3.@refill @ifinfo @center ---------- @center HTML+ @center ---------- @end ifinfo @iftex @unnumberedsec HTML+ @end iftex @cindex HTML+ The HTML+ language is an extension of HTML, with a large degree of backwards compatibility. See the internet draft by Dave Raggett for more information. The following HTML+ language elements are supported by W3:@refill @itemize @bullet @item FORMS -- forms are one of the most powerful aspects of HTML+. They allow the author of an HTML document to request information from the person viewing the document. Passwords, checkboxes, radio buttons, and many more types of entry fields are possible. W3 supports @b{all} the input tags, as well as GET and POST submission methods. W3 also supports the Mosaic 2.0 hack of automatically submitting forms with a NAME of isindex.@refill @item ID tags for headers and paragraphs. This makes it possible to reference points within a document and not require empty hypertext links to do it.@refill @item LINK support. LINKs allow you to specify the relevance between documents easily. This makes it possible to point to dictionaries, glossaries, or indices, or to specify the author of a document.@refill @item Annotations. Can have and notes that show up as footnotes at the bottom of a document.@refill @item BR tag for explicit line breaks @item Notes and admonishments. A way to specify a warning or other standard information. Shows appropriate bitmap if possible. Similar to warning dialogs in Windows/Macintosh.@refill @item Infinitely nested lists, and use of paragraphs and headers within lists.@refill @end itemize @ifinfo @center ---------- @center Extras @center ---------- @end ifinfo @iftex @unnumberedsec Extra Markup @end iftex There are several different markup elements that are not officially part of HTML or HTML+ that W3 supports. These are either items that have been dropped from HTML+ because they would be too difficult for other browsers to implement or have been moved into another tag. @itemize @bullet @item RENDER support. The render tag can be used to convert one tag into another. Syntax is , which will replace all tags with , and all tags with .@refill @item Entity definitions within documents. This allows you to define per-document macros. Syntax is , which will replace all occurences of &TAG; with Expansion of Tag.@refill @item Roman numerals for ordered lists. If an ordered list has an optional ROMAN attribute (@samp{
    }, then roman numerals will be used instead of normal arabic numbers.@refill @item IMG and ALT support for list items. If a list item has an IMG or ALT tag (@samp{
  1. image/gif}.@refill * Mapping gopher types to MIME types:: Going from gopher typing to MIME types. * Specifying Viewers:: How to specify external and internal viewers for files that W3 cannot handle natively. * Mailcap File:: How to set up and use a Mailcap file. Standard way to specify MIME viewers -- compatible with Mosaic and most MIME compliant mailers. @end menu @end ifinfo @ifinfo @node Adding MIME types based on file extensions, Mapping gopher types to MIME types, MIME Support, MIME Support @end ifinfo @iftex @unnumberedsubsec Adding MIME types based on file extensions @end iftex @vindex w3-mime-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.@refill 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 @code{w3-mime-extensions}.@refill This variable is an assoc list of file extensions and the corresponding MIME content-type. A sample entry looks like: @samp{(".movie" . "video/x-sgi-movie")} This makes all files that end in @file{.movie} (@file{foo.movie} and @file{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 @b{NOT} be used.@refill @cindex mime-types file @findex w3-parse-mime-types 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 W3 duplicate this in lisp, this file can be parsed using the @code{w3-parse-mime-types} function. This function is called each time w3 is loaded, and tries to parse the file @file{~/.mime-types} if it exists. This format of this file is as follows.@refill Each line contains information for one http type. These types resemble MIME types. If you plan to add new ones, you should use subtypes beginning with x-, such as application/x-myprogram. Lines beginning with # are comment lines, and suitably ignored. Each line consists of:@refill type/subtype ext1 ext2 ... ext@var{n} 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.@refill @ifinfo @node Mapping gopher types to MIME types, Specifying Viewers, Adding MIME types based on file extensions, MIME Support @end ifinfo @iftex @unnumberedsubsec Mapping gopher types to MIME types @end iftex @ifinfo @node Specifying Viewers, Mailcap File, Mapping gopher types to MIME types, MIME Support @end ifinfo @iftex @unnumberedsubsec Specifying Viewers @end iftex 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.@refill @vindex w3-mime-viewers 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. The variable @code{w3-mime-viewers} is an assoc-list contains MIME content-types and a lisp object specifying how to view a document.@refill If the lisp object is a string (ie: @samp{"xv -perfect %s"}), it specifies an external program that should be used to view the document. This is passed through the @code{format} function. The first %s will be replaced with the temporary file name the retrieved document is saved in, and then that resulting string is used as a command in a subprocess via @code{start-process}.@refill If the lisp object is a lisp symbol (ie: @samp{tar-mode}), it species a lisp function to call after visiting the buffer. This is appropriate for using major modes to view documents. The function is called with no arguments.@refill If the lisp object is a list (ie: @samp{(message "wow")}), it specifies something to be passed through @code{eval}. @ifinfo @node Mailcap File, Mosaic Compatibility, Specifying Viewers, MIME Support @end ifinfo @iftex @unnumberedsubsec Mailcap File @end iftex 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 W3 duplicate this in lisp, this file can be parsed using the @code{w3-parse-mime-types} function. This function is called each time w3 is loaded, and tries to parse the file @file{~/.mime-types} if it exists. This format of this file is specified in RFC 1343, but a brief synopsis follows (this is taken verbatim from sections of RFC 1343).@refill 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.@refill 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.@refill 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.@refill 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.@refill The optional fields, which may be given in any order, are as follows: @itemize @bullet @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @item 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.@refill @end itemize @ifinfo @node Mosaic Compatibility, Hotlist Handling, Mailcap File, 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 @code{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 @file{~/.mosaic-hotlist-default}.@refill Hotlist commands are: @table @kbd @kindex a @findex w3-add-document-to-hotlist @vindex w3-hotlist-file @item a, M-x w3-add-document-to-hotlist This adds the current document to your hotlist, with the buffer name as its identifier. Modifies the file specified by @code{w3-hotlist-file}.@refill @findex w3-remove-from-hotlist @vindex w3-hotlist-file @kindex d @item d, M-x w3-remove-from-hotlist 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 @code{w3-hotlist-file} is updated.@refill @item H, M-x w3-use-hotlist @kindex H @findex w3-use-hotlist Prompts you for the alias to jump to. You may press the spacebar or tab key for partial completions.@refill @item M-x w3-show-hotlist @findex w3-show-hotlist This converts your hotlist into an ordered list and parse it as HTML.@refill @item M-x w3-rename-hotlist-entry @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 @code{w3-hotlist-file}.@refill @end table @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 @code{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 @code{w3-global-history-file}, which defaults to @file{~/.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 @code{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 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 @code{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 @code{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 (). 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 ". 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 @code{w3-personal-annotation-directory} (defaults to @file{~/.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 . 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 on .@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, Customizing Formatting, 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 Customizing Formatting, General formatting, Hyperbole Compatibility , 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 @code{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 Setting the fill column @end iftex @ifinfo @center -------------------- @center Setting the fill column @center -------------------- @end ifinfo @vindex fill-column @vindex w3-right-border Each time a document is parsed, the @code{fill-column} is recalculated using @code{window-width} and @code{w3-right-border}. @code{w3-right-border} is an integer specifying how much room at the right edge of the screen to leave blank. The @code{fill-column} is set to @code{(- (window-width) @code{w3-right-border})}. @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 @code{w3-delimit-links} is non-@code{nil}, then hypertext links will be surrounded by text specified by the user. The string @code{w3-link-start-delimiter} will be inserted just before the body of the hyperlink, and @code{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-file-prepare-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 @code{tab-stop-list} and @code{tab-width}. A tab every eight spaces is considered normal, but I prefer to have a tab every four spaces. So @code{tab-stop-list} would be @samp{'(4 8 12 16 20 24 28 32 36 ...)}, and @code{tab-width} would be @samp{4}. I use @code{setq-default} in my .emacs for these, but you can also use them from @code{w3-mode-hooks}. Something like:@refill @example (add-hook 'w3-file-prepare-hooks (function (lambda () (setq tab-stop-width (list 4 8 16 20 24 28 32 36 40 44) tab-width 4)))) @end example @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 @code{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 directory listings @end iftex @ifinfo @center -------------------- @center Formatting of directory listings @center -------------------- @end ifinfo @vindex w3-directory-format When 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 @code{dired-mode} to peruse the listing. The variable @code{w3-directory-format} controls this behavior.@refill If the value is @code{'hypertext}, use @code{directory-files} to list them out and transform them into a hypertext document, then pass it through the parser like any other document.@refill If the value is @code{'dired}, just pass the directory off to dired using find-file. Using this option loses all the hypertext abilities of W3, and you will be unable to load documents in the directory directly into W3 by clicking with the mouse, etc.@refill @iftex @heading Formatting of gopher directories @end iftex @ifinfo @center -------------------- @center Formatting of gopher directories @center -------------------- @end ifinfo @vindex w3-use-hypertext-gopher @cindex Gopher+ @cindex ASK blocks There are two different ways of viewing gopher links. You can use the built-in support that converts gopher directories into HTML, or you can use the @file{gopher.el} package by Scott Snyder . The variable that controls this is @code{w3-use-hypertext-gopher}. If set to @code{nil}, then @file{gopher.el} is used. Any other value causes W3 to use its internal gopher support. If you use @file{gopher.el}, you lose all the hypertext capabilities of W3. All the functionality of @file{gopher.el} is now available in the hypertext version, and the hypertext version supports Gopher+ and ASK blocks. @vindex w3-gopher-labels he main way to control the display of gopher directories is by the variable @code{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. @iftex @heading Creating a horizontal rule @end iftex @ifinfo @center -------------------- @center Creating a horizontal rule @center -------------------- @end ifinfo @vindex w3-horizontal-rule-char Horizontal rules (@b{
    } 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 @code{w3-horizontal-rule-char} controls which character is used to draw a horizontal bar. This variable must be the ASCII value of the character, @b{not a string}. The variable is passed through make-string whenever a horizontal rule of a certain width is necessary.@refill @vindex w3-hrule-pixmap @findex w3-create-hrule If you are using Epoch or Lucid Emacs, then you can define a pixmap to use instead of a character representation. The variable @code{w3-hrule-pixmap} contains the X resource that is the pixmap to use. This is normally created at startup time with the function @code{w3-create-hrule} function.@refill @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 @code{w3-delimit-emphasis} is non-@code{nil}, then W3 can insert characters before and after character formatting commands in HTML documents. The defaul value of @code{w3-delimit-emphasis} is automatically set based on the type of window system and version of Emacs being used.@refill @vindex w3-header-chars-assoc @vindex w3-style-chars-assoc Two variables control what text is inserted around different markup tags. @code{w3-header-chars-assoc} controls what characters are inserted around header items, and @code{w3-style-chars-assoc} controls what characters are inserted around most other markup (italics, addresses, etc).@refill @findex w3-upcase-region @code{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 @code{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