3 @c Please note that this file uses some constructs not supported by earlier
4 @c versions of TeX-info. You must be running one of the newer TeX-info
5 @c releases (I currently use version 3.9 from ftp://prep.ai.mit.edu/pub/gnu/)
7 @c Please do not send in bug reports about not being able to format the
8 @c document with 'makeinfo' or 'tex', just upgrade your installation.
10 @c Info formatted files are provided in the distribution, and you can
11 @c retrieve dvi, postscript, and PDF versions from the web site or FTP
12 @c site: http://www.cs.indiana.edu/elisp/w3/docs.html
15 @settitle Emacs/W3 v4.0pre.47 User's Manual
19 @c @setchapternewpage odd
23 %\global\baselineskip 30pt % for printing in double space
27 @dircategory World Wide Web
28 @dircategory GNU Emacs Lisp
30 * Emacs/W3: (w3). Emacs/W3 World Wide Web browser.
35 Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1999, 2000
36 Free Software Foundation, Inc.
39 Permission is granted to copy, distribute and/or modify this document
40 under the terms of the GNU Free Documentation License, Version 1.2 or
41 any later version published by the Free Software Foundation; with no
42 Invariant Sections, with the Front-Cover texts being ``A GNU
43 Manual''. A copy of the
44 license is included in the section entitled ``GNU Free Documentation
45 License'' in the Emacs manual.
50 @center @titlefont{Emacs/W3}
51 @center @titlefont{User's Manual}
53 @center Third Edition, Emacs/W3 Version 4.0
57 @center William M. Perry
58 @center @i{wmperry@@cs.indiana.edu}
61 @node Top, Getting Started, (dir), (dir)
64 Users can browse the World Wide Web from within Emacs by using Emacs/W3.
65 All of the widely used (and even some not very widely used) @sc{url}
66 schemes are supported, and it is very easy to add new methods as the
69 Emacs/W3 provides some core functionality that can be readily re-used
70 from any program in Emacs. Users and other package writers are
71 encouraged to @i{Web-enable} their applications and daily work routines
74 Emacs/W3 is completely customizable, both from Emacs-Lisp and from
75 stylesheets @xref{Stylesheets}. If there is any aspect of Emacs/W3 that
76 cannot be modified to your satisfaction, please send mail to the
77 @t{w3-beta@@xemacs.org} mailing list with any suggestions.
78 @xref{Reporting Bugs}.
80 This manual corresponds to Emacs/W3 $State: Exp $
83 * Getting Started:: Getting up and running with Emacs/W3
84 * Basic Usage:: Basic movement and usage of Emacs/W3.
85 * Compatibility:: Explanation of compatibility with
87 * Display Variables:: How to control Emacs/W3's look.
88 * Stylesheets:: How to control the look of web pages
89 * Supported URLs:: What @sc{url} schemes are supported.
90 * MIME Support:: Support for @sc{mime}
91 * Security:: Various security methods supported
92 * Cookies:: Emacs/W3 and cookies.
93 * Non-Unix Operating Systems:: Special considerations necessary to get
94 up and running correctly under non-unix
96 * Speech Integration:: Outputting to a speech synthesizer.
97 * Advanced Features:: Some of the more arcane features.
98 * More Help:: How to get more help---mailing lists,
100 * Future Directions:: Plans for future revisions
103 * Reporting Bugs:: How to report a bug in Emacs/W3.
104 * Dealing with Firewalls:: How to get around your firewall.
105 * Proxy Gateways:: Using a proxy gateway with Emacs/W3.
106 * Installing SSL:: Turning on @sc{ssl} support.
107 * Mailcap Files:: An explanation of Mailcap files.
111 * General Index:: General Index.
112 * Key Index:: Menus of command keys and their references.
115 @node Getting Started, Basic Usage, Top, Top
116 @chapter Getting Started
117 @cindex Clueless in Seattle
118 @cindex Getting Started
120 @vindex w3-default-homepage
122 If installed correctly, starting Emacs/W3 is quite painless. Just type
123 @kbd{M-x w3} in a running Emacs session. This will retrieve the default
124 page that has been configured --- by default the documentation for
125 Emacs/W3 at Indiana University. The default homepage is specified by
126 the @code{w3-default-homepage} variable.
128 If the default page is not retrieved correctly at startup, you will have
129 to do some customization.
131 Once started, you can use the mouse and the menu or use the following
132 key commands (for more commands and more detail, @pxref{Basic Usage, ,
140 press the backspace key,
142 @item move to the next HTML reference on the page
143 press the @kbd{TAB} key,
145 @item move to the previous HTML reference on the page
146 press the @kbd{SHIFT} and @kbd{TAB} keys at the same time. If this does
147 not work (some text terminals cannot distinguish between @kbd{TAB} and
148 @kbd{SHIFT-TAB}, pressing the @kbd{ALT} and @kbd{TAB} keys should also
152 put the cursor over it
153 and press the @kbd{RETURN} key, or @*
154 click the left mouse button on it,
156 @item fetch a @sc{url}
157 press the @kbd{Control} and @kbd{o} keys at the same time,@*
158 type the @sc{url}, and then press the @kbd{RETURN} key,
160 @item return to the last URL you were at
161 press the @kbd{l} key,
164 press the @kbd{q} key.
168 * Downloading:: Where to download Emacs/W3.
169 * Building and Installing:: Compiling and installing from source.
170 * Startup Files:: What is where, and why.
173 @node Downloading, Building and Installing, Getting Started, Getting Started
176 Emacs/W3 will work with Emacs 19.29 and later and XEmacs 19.14 and later,
177 but if you're using a 19.x Emacs then you will need to get the
178 latest custom and widget libraries.
182 Available from the GNU archive @uref{ftp://prep.ai.mit.edu/pub/gnu} or
183 one of it's many mirrors.
186 Available from the XEmacs archive @uref{http://www.xemacs.org/} or one
187 of it's many mirrors.
190 @uref{http://www.cs.indiana.edu/elisp/w3/docs.html} is the main
191 distribution point for Emacs/W3.
194 A speech synthesizer package for Emacs and XEmacs. More information is
196 @uref{http://www.cs.cornell.edu/Info/People/raman/emacspeak/}
200 @node Building and Installing, Startup Files, Downloading, Getting Started
201 @section Building and Installing
203 Emacs/W3 uses GNU @samp{configure} (@pxref{Top, , ,configure}) to
204 control installation. configure will attempt to find what version of
205 Emacs you have and where it is installed. If it finds both Emacs and
206 XEmacs, then XEmacs is used (but see below for how to change this).
207 Apart from the usual options, the following options are accepted:
214 @item --with-lispdir=@var{dir}
215 Put lisp files (*.el and *.elc) in @var{dir}. If this is not specified,
216 and neither is @samp{--with-package-dir}, then the lisp files go into
217 @file{@var{EMACS}/site-lisp}.
218 @item --with-package-dir=@var{dir}
219 If using XEmacs, install Emacs/W3 as a package in @var{dir}. Please
220 note that this and the @samp{--prefix} argument are mutually exclusive.
221 @item --with-makeinfo=@var{makeinfo}
222 Use @var{makeinfo} to build info files from Texinfo files.
223 @samp{configure} will normally find makeinfo if it's available, you
224 should only need to specify this if it's not called makeinfo or if it
225 isn't in a directory in your @samp{PATH}.
226 @item --with-custom=@var{dir}
227 Use the custom package in @var{dir}. @samp{configure} will attempt to
228 find a suitable custom package, you should not need to specify this
229 yourself if the custom package is in Emacs's @code{load-path}.
230 @item --enable-site-install
231 Install Emacs/W3 for the site, rather than just yourself. This only
232 affects whether @samp{make dotemacs} affects @file{~/.emacs} or
233 @file{site-lisp/default.el}.
237 These are the most useful of the normal @samp{configure} options.
240 @item --prefix=@var{dir}
241 This is the top level directory and by default everything is installed
242 somewhere below this. This is @file{/usr/local} by default.
243 @item --infodir=@var{dir}
244 Where to put the info files. This is @file{@var{prefix}/info} by
246 @item --data-dir=@var{dir}
247 Where to put date files (default stylesheets). This is @file{@var{prefix}/share} by
248 default unless @samp{--with-package-dir=@var{pack-dir}} was given in
249 which case they go into @file{@var{pack-dir}/etc/w3}.
252 The directory that the byte-compiled lisp files will be installed into
253 is controlled by the @samp{--prefix}, @samp{--with-package-dir} and
254 @samp{--with-lispdir} options. The directory for the info and data files is
255 likewise controlled by the @samp{--prefix}, @samp{--with-package-dir}
256 and @samp{--infodir} or @samp{--data-dir} options.
258 Normally these are the only things that need to be installed, they can
259 by compiled by @samp{make all}, or @samp{make w3} and @samp{make info}.
260 @samp{make install} will install the lisp, info and data files.
261 @samp{make all} in the @file{texi} directory will create the info files
262 and also dvi files. @sc{html} and postscript can be generated by @samp{make
263 html} and @samp{make ps} respectively.
265 @c gdj1: document the other targets, fast etc.?
267 @node Startup Files, , Building and Installing, Getting Started
268 @section Startup Files
269 @cindex Startup files
272 @vindex w3-configuration-directory
273 Emacs/W3 needs a directory for each user to store options, history and
274 the cache. @code{w3-configuration-directory} controls this directory,
275 which is @file{~/.w3} by default.
277 @subsection Emacs/W3 profile
279 @vindex w3-default-configuration-file
280 Emacs/W3 keeps a file called @file{profile} in your configuration
281 directory that sets many variables. @strong{Warning}: this file will
282 overide any options that you set in your @file{.emacs}. You @emph{must} either
283 edit @file{profile} directly or use @code{w3-menu-save-options} to save
286 If you prefer, you can set @code{w3-default-configuration-file} to
287 specify a different configuration file. This file does not need to be
288 dedicated to Emacs/W3 because Emacs/W3 will delimit its part of the file
289 so you can set this to @file{.emacs} if you want. However, while
290 Emacs/W3 will save it's options to the correct part of the file, it will
291 read (and execute) the entire file when starting.
293 @subsection Default stylesheets
294 @cindex Default stylesheet
295 @vindex w3-default-stylesheet
296 Emacs/W3 will look for style-sheets in @code{w3-configuration-directory}
297 as well as the site-wide directories. In particular it will look for
298 @file{dark.css} or @file{stylesheet-dark} if you're using a dark
299 background and @file{light.css} or @file{stylesheet-light} if you're
300 using a light background as well as @file{stylesheet} and
301 @file{default.css}. If @code{w3-default-stylesheet} is not @code{nil}
302 then the file that it names will be used as well. For more information,
307 @vindex url-global-history-file
308 @vindex url-global-history-save-interval
309 @vindex url-keep-history
310 Emacs/W3 keeps a file called @file{history} in the configuration
311 directory. This is a list of all the links you have visited. You can
312 change the file where the history is stored by setting
313 @code{url-global-history-file} to the name of the file you'd prefer.
314 @xref{Global History}.
317 @vindex w3-hotlist-file
318 @dfn{Hotlists} (sometimes called bookmarks, but not to be confused with
319 Emacs's bookmarks) are a list of @sc{url}s. Emacs/W3 supports mosaic's
320 hotlist format which associates an alias with each @sc{url} ---
321 @xref{Hotlist Handling}.
323 @c --- and also the @sc{html} style hotlists used by
324 @c lynx and netscape.
326 The @code{w3-hotlist-file} variable specifies
327 the hotlist file. It defaults to @file{.mosaic-hotlist-default}.
329 @node Basic Usage, Compatibility, Getting Started, Top
337 Emacs/W3 is similar to the Info package all Emacs users hold near and
338 dear to their hearts (@xref{Top,,Info,info, The Info Manual}, for a
339 description of Info). Basically, @kbd{space} and @kbd{backspace}
340 control scrolling, and @kbd{return} or the middle mouse button follows a
341 hypertext link. The @kbd{tab} and @kbd{Meta-tab} keys maneuver around the
342 various links on the page.
344 @b{NOTE:} Starting with Emacs/W3 4.0, form entry areas in a page can be
345 typed directly into. This is one of the main differences in navigation
346 from version 2.0. If you are used to using the @kbd{f} and @kbd{b} keys
347 to navigate around a buffer, I suggest training yourself to always use
348 @kbd{tab} and @kbd{M-tab} --- it will save time and frustration on pages
349 with lots of form fields.
351 By default, hypertext links are surrounded by '[[' and ']]' on
352 non-graphic terminals (VT100, DOS window, etc.). On a graphics
353 terminal, the links are in shown in different colors.
354 For information on how to change this, @xref{Stylesheets}.
356 There are approximately 50 keys bound to special Emacs/W3 functions.
357 The basic rule of thumb regarding keybindings in Emacs/W3 is that a
358 lowercase key takes an action on the @b{current document}, and an
359 uppercase key takes an action on the document pointed to by the
360 hypertext link @b{under the cursor}.
362 There are several areas that the keybindings fall into: movement,
363 information, action, and miscellaneous.
366 * Movement:: Moving around in the buffer.
367 * Information:: Getting information about a document.
368 * Action:: Following links, printing, etc.
369 * Miscellaneous:: Everything else.
372 @node Movement, Information, Basic Usage, Basic Usage
375 All the standard Emacs bindings for movement are still in effect, with a
376 few additions for convenience.
382 Scroll downward in the buffer. With prefix arg, scroll down that many
383 screenfuls (@code{w3-scroll-up}).
386 @findex w3-next-document
387 Goes to next document.
392 @findex w3-prev-document
393 Goes to previous document.
400 Scroll upward in the buffer. With prefix arg, scroll up that many
401 screenfuls (@code{scroll-down}).
403 @findex w3-start-of-document
405 Goes to the start of document (@code{w3-start-of-document}).
407 @findex w3-end-of-document
409 Goes to the end of document (@code{w3-end-of-document}).
412 @findex w3-widget-backward
413 @item Meta-tab, Shift-tab, b
414 Attempts to move backward one link area in the current document
415 (@code{w3-widget-backward}). Signals an error if no previous links are
420 @findex w3-widget-forward
422 Attempts to move forward one link area in the current document
423 (@code{w3-widget-forward}). Signals an error if no more links are
427 @findex w3-backward-in-history
428 @findex w3-history-backward
430 Takes one step back along the path in the current history
431 (@code{w3-history-backward}). Has no effect if at the beginning of the
435 @findex w3-forward-in-history
436 @findex w3-history-forward
438 Takes one step forward along the path in the current history
439 (@code{w3-history-forward}). Has no effect if at the end of the session
442 @findex w3-goto-last-buffer
444 Return to the last buffer shown before this buffer
445 (@code{w3-goto-last-buffer}).
449 Kill this buffer (@code{w3-quit}).
451 @findex w3-leave-buffer
453 Bury this buffer, but don't kill it (@code{w3-leave-buffer}).
456 @node Information, Action, Movement, Basic Usage
459 These functions relate information about one or more links on the
466 This shows the @sc{url} of the current document in the minibuffer
467 (@code{url-view-url}).
469 @findex w3-view-this-url
471 This shows the @sc{url} of the hypertext link under point in the
472 minibuffer (@code{w3-view-this-url}).
474 @findex w3-document-information
476 Shows miscellaneous information about the currently displayed document
477 (@code{w3-document-information}). This includes the @sc{url}, the last
478 modified date, @sc{mime} headers, the @sc{http} response code, and any
479 relationships to other documents. Any security information is also
482 @findex w3-popup-info
484 Shows information about the @sc{url} at point (@code{w3-popup-info}).
486 @findex w3-source-document
488 This shows the @sc{html} source of the current document in a separate
489 buffer (@code{w3-source-document}). The buffer's name is based on the
492 @findex w3-source-document-at-point
494 Shows the @sc{html} source of the hypertext link under point in a
495 separate buffer (@code{w3-source-document-at-point}). The buffer's name
496 is based on the document's @sc{url}.
500 This stores the current document's @sc{url} in the kill ring, and also in the
501 current window-system's clipboard, if possible (@code{w3-save-url}).
503 @findex w3-save-this-url
505 Stores the @sc{url} of the document under point in the kill ring, and also in
506 the current window-system's clipboard, if possible (@code{w3-save-this-url}).
509 @node Action, Miscellaneous, Information, Basic Usage
512 First, here are the keys and functions that bring up a new hypertext
513 page, usually creating a new buffer.
516 @findex w3-complete-link
518 Choose a link from the current buffer and follow it
519 (@code{w3-complete-link}). A completing-read is done on all the links,
520 so @kbd{space} and @kbd{TAB} can be used for completion.
522 @findex w3-follow-link
524 Pressing return when over a hyperlink attempts to follow the link
525 under the cursor (@code{w3-follow-link}).
527 Pressing return when over a form input field can cause auto-submission
528 of the form. This is for Mosaic and Netscape compatibility. If there
529 is only one item in the form other than submit or reset buttons, then
530 the form will be submitted.
532 @kindex Middle Mouse Button
533 @findex w3-follow-mouse
534 @item Middle Mouse Button
535 Attempt to follow a hypertext link under the mouse cursor
536 (@code{w3-follow-mouse}). Clicking on a form input field will prompt in
537 the minibuffer for the data to insert into the input field. Type
538 checking is done, and the data is only entered into the form when data
539 of the correct type is entered (ie: cannot enter 44 for 'date' field,
542 @kindex Control Middle Mouse Button
544 @findex w3-follow-inlined-image
545 @item Control Middle Mouse Button, Meta return
546 Tries to retrieve the inlined image that is under point
547 (@code{w3-follow-inlined-image}). It ignores any form entry areas or
548 hyperlinks, and blindly follows any inlined image. Useful for seeing
549 images that are meant to be used as hyperlinks when not on a terminal
550 capable of displaying graphics.
553 @findex w3-download-url-at-point
555 Download the @sc{url} at point (@code{w3-download-url-at-point}).
557 @findex w3-download-this-url
559 Download the current @sc{url} (@code{w3-download-this-url}).
561 @c @findex w3-show-graphics
563 @c gdj1: Bound to w3-show-graphics which isn't defined.
566 @findex w3-complete-link
568 Selects a destination from a list of all the hyperlinks in the current
569 buffer (@code{w3-complete-link}). Use @kbd{space} and @kbd{tab} to
570 complete on the links.
574 @findex w3-reload-document
576 Reloads the current document (@code{w3-reload-document}). The position
577 within the buffer remains the same (unless the document has changed
578 since it was last retrieved, in which case it should be relatively
579 close). This causes an unconditional reload from the remote server ---
580 the locally cached copy is not consulted.
582 @findex w3-refresh-buffer
584 Redraws the buffer without reloading document (@code{w3-refresh-buffer}).
588 Prompts for a @sc{url} in the minibuffer, and attempts to fetch it
589 (@code{w3-fetch}). If there are any errors, or Emacs/W3 cannot
590 understand the type of link requested, the errors are displayed in a
593 @findex w3-open-local
594 @vindex url-use-hypertext-dired
596 Opens a local file, interactively (@code{w3-open-local}). This prompts
597 for a local file name to open. The file must exist, and may be a
598 directory. If the requested file is a directory and
599 @code{url-use-hypertext-dired} is @code{nil}, then a dired-mode buffer
600 is displayed. If non@code{nil}, then Emacs/W3 automatically generates a
601 hypertext listing of the directory. The hypertext mode is the default,
602 so that all the keys and functions remain the same.
607 Save a document to the local disk as HTML Source, Formatted Text, LaTeX
608 Source, or Binary (@code{w3-save-as}).
612 @findex w3-show-history-list
614 Show the current session's history list (@code{w3-show-history-list}).
615 This takes all the links that are in that internal list, and formats
616 them as hypertext links in a list, @ref{Global History}
619 @cindex Buffer movement
620 And here are the commands to move around between Emacs/W3 buffers:
624 @findex w3-goto-last-buffer
626 Goes to the last WWW buffer seen (@code{w3-goto-last-buffer}).
628 @findex w3-print-this-url
630 Prints the current document (@code{w3-print-this-url}). Choose from several different formats to
631 print: formatted text, @sc{html} source, PostScript (with ps-print), or by using
632 LaTeX and dvips). @ref{Printing}.
634 @findex w3-print-url-under-point
636 Prints out the @sc{url} under point in a variety of formats
637 (@code{w3-print-url-under-point}). @ref{Printing}.
641 Quits WWW mode (@code{w3-quit}). This kills the current buffer and goes
642 to the most recently visited buffer.
645 @findex w3-leave-buffer
647 This (@code{w3-leave-buffer}) is similar to @code{w3-quit}, but the
648 buffer is not killed, it is moved to the bottom of the buffer list (so
649 it is the least likely to show up as the default with switch-to-buffer).
650 This is different from @code{w3-goto-last-buffer} in that it does not
651 return to the last @sc{www} page visited --- it is the same as using
652 @code{switch-to-buffer} --- the buffer left in the window is fairly
656 @node Miscellaneous, , Action, Basic Usage
657 @section Miscellaneous
663 Shows help for Emacs/W3 (@code{w3-help}).
667 Show what version of Emacs/W3 you're running (@code{w3-version}).
669 @findex w3-mail-current-document
671 Mails the current document to someone (@code{w3-mail-current-document}).
672 Choose from several different formats to mail: formatted text, @sc{html}
673 source, PostScript, or LaTeX source. When the @sc{html} source is
674 mailed, then an appropriate <base> tag is inserted at the beginning of
675 the document so that relative links may be followed correctly by whoever
678 @findex w3-mail-document-under-point
680 Mails the document pointed to by the hypertext link under point to
681 someone (@code{w3-mail-document-under-point}). Choose from several
682 different formats to mail: formatted text, @sc{html} source, PostScript,
683 or LaTeX source. When the @sc{html} source is mailed, then an
684 appropriate <base> tag is inserted at the beginning of the document so
685 that relative links may be followed correctly by whoever receives the
689 @findex url-list-processes
691 gdj1: bound to url-list-processes. What does this do?
693 @findex w3-mail-document-author
695 Send a mail to the author of the current document
696 (@code{w3-mail-document-author}).
698 @kindex M-x w3-insert-formatted-url
699 @findex w3-insert-formatted-url
700 @item M-x w3-insert-formatted-url
701 Insert a fully formatted @sc{html} link into another buffer
702 (@code{w3-insert-formatted-url}). This gets the name and @sc{url} of
703 either the current buffer, or, with a prefix arg, of the link under
704 point, and construct the appropriate <a...>...</a> markup and insert it
705 into the desired buffer.
707 @findex w3-insert-this-url
709 Inserts the @sc{url} of the current document into another buffer
710 (@code{w3-insert-this-url'}). Buffer is prompted for in the minibuffer.
711 With prefix arg, uses the @sc{url} of the link under point.
715 Selects one of the <LINK> tags from this document and fetch it
716 (@code{w3-use-links}). Links are attributes of a specific document, and
717 can tell such things as who made the document, where a table of contents
720 Link tags specify relationships between documents in two ways. Normal
721 (forward) relationships (where the link has a REL="xxx" attribute), and
722 reverse relationships (where the link has a REV="xxx" attribute). This
723 first asks what type of link to follow (Normal or Reverse), then does
724 a @code{completing-read} on only the links that have that type of
728 @node Compatibility, Display Variables, Basic Usage, Top
729 @chapter Compatibility with other Browsers
730 Due to the popularity of several other browsers, Emacs/W3 offers an easy
731 transition to its much better way of life. This ranges from being able
732 to share the same preferences files and disk cache to actually emulating
733 the keybindings used in other browsers.
736 * Emulation:: Emacs/W3 can emulate the keybindings and
737 other behaviours of other browsers.
738 * Hotlist Handling:: A hotlist is an easy way to keep track of
739 interesting Web pages without having to
740 remember the exact path to get there.
741 * Session History:: Keeping a history of documents visited
742 in one Emacs sessions allows the use of
743 'forward' and 'back' buttons easily.
744 * Global History:: Keeping a history of all the places ever
748 @node Emulation, Hotlist Handling, Compatibility, Compatibility
751 @cindex Browser emulation
752 @cindex Emulation of other browsers
754 Emacs/W3 can emulate the keybindings of lynx and netscape, but only one
755 at a time. If you want emulation permanantly turned on, then you should
756 add @code{turn-on-lynx-emulation} or @code{turn-on-netscape-emulation}
757 to @code{w3-mode-hook}.
760 * lynx:: Emulate lynx.
761 * netscape:: Emulate netscape.
762 * Masquerading:: Emacs/W3 can masquerade as another
766 @node lynx, netscape, Emulation, Emulation
767 @section Lynx emulation
768 @cindex Lynx emulation
769 @findex turn-on-lynx-emulation
770 @findex w3-lynx-emulation-minor-mode
772 @code{turn-on-lynx-emulation} turns on lynx emulation and turns off
773 netscape emulation. lynx emulation is handled by the
774 @code{w3-lynx-emulation-minor-mode} minor mode. For more information
775 about lynx style hotlists, @xref{Hotlist Handling}.
777 :: work :: Document lynx emulation@*
784 Highlight previous topic
787 @item Right arrow, Return, Enter
788 Jump to highlighted topic
791 Return to previous topic. gdj1: actually, this doesn't seem to work
795 Scroll down to next page (Page-Down)
798 Scroll up to previous page (Page-Up)
801 Scroll down to next page (Page-Down)
804 Scroll up to previous page (Page-Up)
807 Go to first page of the current document (Home)
810 Go to last page of the current document (End)
813 Scroll up to previous page (Page-Up)
816 Scroll down to next page (Page-Down)
819 Go forward two lines in the current document
822 Go back two lines in the current document
825 Go forward half a page in the current document (ignored)
828 Go back half a page in the current document (ignored)
831 Go to Toolbar or Banner in the current document, only works in XEmacs.
832 gdj1: is this what is meant by toolbar?
839 Add the current link to a bookmark file
842 Send a comment to the document owner
845 Download the current link
848 Edit the current file (ignored)
851 Goto a user specified @sc{url} or file
854 Show an index of documents (ignored)
857 Execute a jump operation (using hotlist)
860 Show a list of key mappings
863 List references (links) in current document
866 Return to main screen
869 Go to the next search string
875 Print the current document
884 Enter a search string for an external search gdj1: really?
887 Go backwards in history
890 Search for a string within the current document
896 Go to the Visited Links Page
899 Force submission of form or link with no-cache
902 Cancel transfer in progress
905 Go to the history Page gdj1: really?
908 Show file and link info
911 Toggle document source/rendered view
914 Spawn your default shell
917 Toggle image_links mode on and off (ignored)
920 Toggle pseudo_inlines mode on and off (ignorged)
923 Send an @sc{http} @sc{head} request for the current doc or link (ignored)
926 Reload current file and refresh the screen
932 Erase input line (ignored)
935 Cancel input or transfer
938 Toggle trace mode on and off (ignored)
941 Invoke the Cookie Jar Page (ignored)
944 @node netscape, Masquerading, lynx, Emulation
945 @section Netscape emulation
946 @cindex Netscape emulation
947 @findex turn-on-netscape-emulation
948 @findex w3-netscape-emulation-minor-mode
950 @code{turn-on-netscape-emulation} turns on netscape emulation and turns
951 off lynx emulation. netscape emulation is handled by the
952 @code{w3-netscape-emulation-minor-mode} minor mode. For more
953 information about netscape style hotlists, @xref{Hotlist Handling}.
959 Add the current link to a bookmark file
967 Search forward in document
983 Goto a user specified @sc{url} or file
999 Print current document
1003 Quit current document
1007 Reload document and redraw
1011 Save current document
1015 Go back in history list
1019 Go forward in history list
1038 @node Masquerading, , netscape, Emulation
1039 @section Masquerading
1040 @cindex Browser masquerading
1041 @cindex Masquerading as other browsers
1042 @findex turn-on-lynx-masquerade-mode
1043 @findex turn-on-netscape-masquerade-mode
1044 @findex turn-on-ie-masquerade-mode
1045 @findex turn-on-arena-masquerade-mode
1046 @findex turn-off-lynx-masquerade-mode
1047 @findex turn-off-netscape-masquerade-mode
1048 @findex turn-off-ie-masquerade-mode
1049 @findex turn-off-arena-masquerade-mode
1050 @findex w3-arena-masquerade-mode
1051 @findex w3-ie-masquerade-mode
1052 @findex w3-netscape-masquerade-mode
1053 @findex w3-lynx-masquerade-mode
1054 @sc{http} allows servers to ask browsers what browser they are, and what
1055 version they are. Emacs/W3 allows you to choose the reply. There are
1056 functions to masquerade as lynx, netscape, @sc{ie} or arena. For each
1057 @var{browser} there are three functions,
1058 @code{turn-on-@var{browser}-masquerade-mode},
1059 @code{turn-off-@var{browser}-masquerade-mode} and
1060 @code{w3-@var{browser}-masquerade-mode}. The purpose of the first two
1061 is clear, @code{w3-@var{browser}-masquerade-mode} takes an optional
1062 argument which toggles the mode if it's @code{nil}, turns off the mode
1063 if it's 0 and turns the mode on otherwise.
1065 If you'd prefer to masquerade as another browser, then you should call
1066 @code{w3-masquerade-stub} with three arguments: @var{arg}, @var{app} and
1067 @var{version}. @var{arg} has the same function as for
1068 @code{w3-@var{browser}-masquerade-mode}, @var{app} is the name of the
1069 browser to masquerade as and @var{version} is the version.
1071 Why would you want to masquerade as another browser when you could be
1072 advertising Emacs/W3? Well, some servers will only let certain browsers
1073 connect with them. This is cleary evil. Also some servers may alter
1074 what they present depending on the browser, this is probably a Good
1075 Thing but they might not know about Emacs/W3. Also one could argue that
1076 demanding the USER_AGENT field is a breach of privacy, Emacs/W3 doesn't
1077 have to send it (@pxref{Security}), but the server doesn't have
1078 to let you connect either.
1081 @node Hotlist Handling, Session History, Emulation, Compatibility
1082 @section Hotlist Handling
1084 Emacs/W3 supports two types of hotlist, mosaic hotlists and @sc{html} as
1085 used by lynx and netscape (which both call hotlists bookmarks).
1086 Unfortunately, not all hotlist operations are supported for @sc{html}
1087 files at the moment.
1089 In order to avoid having to traverse many documents to get to the same
1090 document over and over, Emacs/W3 supports a ``hotlist'' like Mosaic. This is
1091 a file that contains @sc{url}s and aliases. Hotlists allow quick access to any
1092 document in the Web, providing it has been visited and added to the hotlist.
1093 The variable @code{w3-hotlist-file} determines where this information
1094 is saved. The structure of the file is compatible with Mosaic's
1095 hotlist file, so this defaults to @file{~/.mosaic-hotlist-default}.
1097 Hotlist commands are:
1101 @findex w3-hotlist-apropos
1102 Shows the hotlist entries matching a regular expression.
1105 @findex w3-hotlist-add-document
1106 @vindex w3-hotlist-file
1108 Adds the current document to the hotlist, with the buffer name as its
1109 identifier. Modifies the file specified by @code{w3-hotlist-file}. If
1110 this is given a prefix-argument (via @kbd{C-u}), the title is prompted
1111 for instead of automatically defaulting to the document title.
1113 @findex w3-hotlist-delete
1114 @vindex w3-hotlist-file
1117 Prompts for the alias of the entry to kill. Pressing the spacebar or
1118 tab will list out partial completions. The internal representation of
1119 the hotlist and the file specified by @code{w3-hotlist-file} are
1124 @findex w3-hotlist-rename-entry
1125 @vindex w3-hotlist-file
1126 Some hotlist item names can be very unwieldy (`Mosaic for X level 2 fill
1127 out form support'), or uninformative (`Index of /'). Prompts for the
1128 item to rename in the minibuffer---use the spacebar or tab key for
1129 completion. After having chosen an item to rename, prompts for a new
1130 title until a unique title is entered. Modifies the file specified by
1131 @code{w3-hotlist-file}.
1135 @findex w3-use-hotlist
1136 Prompts for the alias to jump to. Pressing the @key{spacebar} or
1137 @key{tab} key shows partial completions.
1141 @findex w3-show-hotlist
1142 Converts the hotlist into @sc{html} and displays it.
1146 @findex w3-hotlist-append
1147 Appends another hotlist file to the one currently in memory.
1151 @findex w3-hotlist-add-document-at-point
1152 Add the document pointed to by the hyperlink under point to the hotlist.
1154 @findex w3-hotlist-refresh
1155 @vindex w3-hotlist-file
1158 This rereads the default hostlist file specified by
1159 @code{w3-hotlist-file}.
1164 @node Session History, Global History, Hotlist Handling, Compatibility
1166 @cindex History Lists
1168 Almost all web browsers keep track of the @sc{url}s followed from a page, so
1169 that it can provide @b{forward} and @b{back} buttons to keep a @i{path}
1170 of @sc{url}s that can be traversed easily.
1172 @vindex url-keep-history
1173 If @code{url-keep-history} is non-@code{nil}, then Emacs/W3 keeps track
1174 of all the @sc{url}s visited in an Emacs session. If @code{t} then
1175 Emacs/W3 will save the history list at the end of each session to the
1176 @code{url-global-history-file} file. The history list is simply a list
1177 of all the @sc{url}s visited in the session.
1179 @findex w3-show-history-list
1180 To view a listing of the history for this session of Emacs/W3, use
1181 @code{M-x w3-show-history-list} (@kbd{Hv}) from any buffer, and Emacs/W3
1182 generates an @sc{html} document showing every @sc{url} visited since
1183 Emacs started (or cleared the history list), and then format it. Any of
1184 the links can be chosen and followed to the original document. To clear
1185 the history list, choose 'Clear History' from the 'Options' menu.
1187 @findex w3-forward-in-history
1188 @findex w3-backward-in-history
1190 Another twist on the history list mechanism is the fact that all
1191 Emacs/W3 buffers remember what @sc{url}, buffer, and buffer position of the
1192 last document, and also keeps track of the next location jumped @b{to}
1193 from that buffer. This means that the user can go forwards and
1194 backwards very easily along the path taken to reach a particular
1195 document. To go forward, use the function @code{w3-forward-in-history} (@kbd{F}),
1196 to go backward, use the function @code{w3-backward-in-history}
1197 (@kbd{B}). To view the entire history, use @code{w3-show-history-list}
1201 @node Global History, , Session History, Compatibility
1202 @section Global History
1204 Most web browsers also support the idea of a ``history'' of @sc{url}s
1205 the user has visited, and it displays them in a different style than
1206 normal @sc{url}s. Emacs/W3 will read and write history files generated
1207 by Emacs/W3, Mosaic v1 and v2 or netscape. Emacs/W3 looks at the file
1208 contents to determine the type of history.
1210 @vindex url-keep-history
1211 @vindex url-global-history-file
1212 @vindex url-global-history-save-interval
1213 If the variable @code{url-keep-history} is @code{t}, then Emacs/W3 keeps
1214 a list of all the @sc{url}s visited in a session. The file is
1215 automatically written to disk every
1216 @code{url-global-history-save-interval} seconds and when exiting emacs.
1217 The list is added to those already in the file specified by
1218 @code{url-global-history-file}, which defaults to @file{~/mosaic.hst}
1219 for MS operating systems, @file{~/mosaic.global-history} for @sc{vms} and
1220 @file{~/.w3/history} for everything else.
1222 If any @sc{url} in the list is found in the file, it is not saved, but new
1223 ones are added at the end of the file.
1225 The function that saves the global history list is smart enough to
1226 notice what style of history list is being used (Netscape, Emacs/W3, or
1227 XMosaic), and writes out the new additions appropriately.
1229 @cindex Completion of URLs
1230 @cindex Usefulness of global history
1231 One of the nice things about keeping a global history files is that Emacs/W3
1232 can use it as a completion table. When doing @kbd{M-x w3-fetch}, pressing
1233 the @kbd{tab} or @kbd{space} key will show all completions for a
1234 partial @sc{url}. This is very useful, especially for very long @sc{url}s that
1235 are not in a hotlist, or for seeing all the pages from a particular web
1236 site before choosing which to retrieve.
1238 @node Display Variables, Stylesheets, Compatibility, Top
1239 @section Display Variables
1241 Emacs/W3 has many variable for you to fiddle with to get the display
1245 @item w3-display-frames
1246 @vindex w3-display-frames
1247 You can control what Emacs/W3 does with frame by setting
1248 @code{w3-display-frames}. It can be
1251 Emacs/W3 will pretend not to understand frames at all.
1253 Emacs/W3 will show hyperlinks to frames but will not fetch them (the same
1256 This is similar to @code{as-nil}, but Emacs/W3 will ask if you want to
1257 retrieve the frames.
1259 Emacs/W3 will dispaly the hyperlinks and fetch the frames.
1264 Emacs/W3 lets @emph{you} decide what characters to use for bullets in
1265 unordered lists by setting @code{w3-bullets}. It is a association list,
1266 mapping list types to characters. By default it is @code{((disc . ?*)
1267 (circle . ?o) (square . ?#) (none . ? ))}.
1270 @vindex w3-echo-link
1271 You can decide what should be displayed when tabbing through links by
1272 setting the @code{w3-echo-link} variable. It is a list and may contain
1273 the following symbols,
1276 Display the @sc{url} of the target.
1278 Display the text of the link.
1280 Display the title attribute of the link.
1282 Display the name or id attribute of the link.
1285 The default is @code{(title url text name)}.
1287 @item w3-horizontal-rule-char
1288 @vindex w3-horizontal-rule-char
1289 Many @sc{html} pages use horizontal lines (rules) to seperate sections
1290 of the page. You can control what character Emacs/W3 will use to draw
1291 these by setting @code{w3-horizontal-rule-char}. If it is a character
1292 (@emph{not} a string) then Emacs/W3 will replicate that character across
1293 the screen, if it is @code{nil} then Emacs/W3 will use a terminal
1294 graphics character if possible. It is @code{nil by default}.
1296 @item w3-use-terminal-characters
1297 @vindex w3-use-terminal-characters
1298 When Emacs/W3 draws table and rules, it needs to approximate line
1299 somehow. If @code{w3-use-terminal-characters} it @code{non-nil} (the
1300 default) then Emacs/W3 will use terminal graphics characters if they are
1303 @item w3-use-terminal-characters-on-tty
1304 @vindex w3-use-terminal-characters-on-tty
1305 Using terminal graphics characters on ttys will trigger display bugs in
1306 both XEmacs and FSF Emacs, but the display is usually readable with FSF
1307 Emacs. @code{w3-use-terminal-characters-on-tty} controls whether to use
1308 terminal graphics characters on ttys, it is @code{nil} by default.
1310 @item w3-use-terminal-glyphs
1311 @vindex w3-use-terminal-glyphs
1312 Emacs/W3 can use glyphs rather than text properties for terminal
1313 graphics characters. Glyphs do not work with the most recent versions
1314 of XEmacs. This is @code{t} by default.
1316 @item w3-defined-link-types
1317 @vindex w3-defined-link-types
1318 @code{w3-defined-link-types} is a list of names that have special
1319 significance as the values of @samp{REL} or @samp{REV} attributes of
1320 <link> elements. All members should be in lowercase.
1322 @item w3-auto-image-alt
1323 @vindex w3-auto-image-alt
1324 Some people do not feel it's worth their time to add @code{alt} tags to
1325 their images, but Emacs/W3 can create @code{alt} tags on the fly for
1326 images that do not have them. To control this you can set
1327 @code{w3-auto-image-alt} to one of the following:
1330 Do not create @code{alt} tags
1332 The string will be run through format with the filename of the image and
1333 so may have a single @code{%s}, for example @code{"[IMAGE(%s)]"}
1335 The function will be called with the filename of the images as the
1336 argument. This is the default, with @code{w3-default-image-alt-func}
1340 @item w3-min-img-size, w3-default-image-alt-func, w3-dummy-img-alt-repl
1341 @vindex w3-min-img-size
1342 @vindex w3-dummy-img-alt-repl
1343 @findex w3-default-image-alt-func
1344 @code{w3-default-image-alt-func} returns @code{w3-dummy-img-alt-repl}
1345 (@samp{*} by default) if the image's height and width are both less than
1346 @code{w3-min-img-size} pixels (15 by default) and if the filename
1347 matches the @code{w3-dummy-img-re} regular expression. Otherwise,
1348 @code{w3-default-image-alt-func} returns the filename enclosed in a
1351 @item w3-icon-format
1352 @vindex w3-icon-format
1353 Emacs/W3 will expect the standard icons to be in the format specified by
1354 @code{w3-icon-format}. This is @code{gif} by default, but could be
1355 @code{xpm}, @code{xbm} or any other format for that matter. It is added
1356 as a file extension to the icon name, but the variable's value must be a
1357 symbol. If @code{nil}, then the server decides.
1359 @item w3-delay-image-loads
1360 @vindex w3-delay-image-loads
1361 You can choose whether Emacs/W3 retrieves images with the document, or
1362 delays loading them by setting @code{w3-delay-image-loads}. By default
1363 this is @code{t} if you compiled XEmacs with support for gifs, jpegs,
1364 pngs or imagick and @code{nil} otherwise.
1366 @item w3-image-mappings
1367 @vindex w3-image-mappings
1368 @code{w3-image-mappings} controls the mapping of @sc{mime} types to
1369 image types for the @samp{image} package. Each entry is a cons cell of
1370 a @sc{mime} type string and an image-type symbol.
1372 @item w3-max-menu-length
1373 @vindex w3-max-menu-length
1374 Emacs/W3 will split menus into smaller submenus if they are longer than
1375 @code{w3-max-menu-length}.
1377 @item w3-max-menu-width
1378 @vindex w3-max-menu-width
1379 The maximum width of a pulldown menu choice.
1381 @item w3-right-margin
1382 @vindex w3-right-margin
1383 Emacs/W3's right margin is controlled by @code{w3-right-margin}. This
1384 is subtracted from @code{(window-width)} for each Emacs/W3 buffer and
1385 used as the fill-column. It is 2 by default.
1387 @item w3-maximum-line-length
1388 @vindex w3-maximum-line-length
1389 The maximum length of a line. If @code{nil} (the default) then lines
1390 can extend to the window margin.
1392 @item w3-modeline-format
1393 @vindex w3-modeline-format
1394 You can specify the modeline to use in @samp{w3-mode} by setting this.
1396 @item w3-honor-stylesheets
1397 @vindex w3-honor-stylesheets
1398 If this is non-@code{nil} (the default) then Emacs/W3 will let a
1399 document specify a @sc{css} stylesheet.
1401 @item w3-user-colors-take-precedence
1402 @vindex w3-user-colors-take-precedence
1403 Emacs/W3 will ignore a document's attempts to define certain colours if
1404 @code{w3-user-colors-take-precedence} it non-@code{nil}. The default is @code{nil}.
1406 @item w3-user-fonts-take-precedence
1407 @vindex w3-user-fonts-take-precedence
1408 Emacs/W3 will ignore attempts by stylesheets or font tags to change
1409 certain fonts if this is non-@code{nil}.
1412 @subsection Asynchronous behaviour
1415 @item url-be-asynchronous
1416 @vindex url-be-asynchronous
1417 If this is non-@code{nil} then document retrievals over @sc{http} will
1418 be down in the background.
1420 @item url-default-retrieval-proc
1421 @vindex url-default-retrieval-proc
1422 This controls what happens when an asynchronous retrievel completes. It
1423 is @code{url-default-callback} by default but can be any function taking
1424 one argument. The argument specifies the file that has been retrieved.
1425 If there is no buffer associated with the file, then
1426 @code{url-default-callback} just puts a message in the minibuffer saying
1427 that the retrieval is complete, otherwise the action depends on the
1430 @item w3-do-incremental-display
1431 @vindex w3-do-incremental-display
1432 Emacs/W3 can de incremental display of pages if
1433 @code{w3-do-incremental-display} is @code{t}. It is @code{nil} by default.
1437 You might want Emacs/W3 to notify you discreetly when it has finished
1438 preparing a page for your reading pleasure. You can control Emacs/W3's
1439 behaviour in this situation by way of the @code{w3-notify} variable. It
1440 may take the following values:
1443 Puts the Emacs/W3 page in its own frame.
1445 Make the Emacs/W3 page the current buffer and only window.
1447 Make the Emacs/W3 page the current buffer in the same window. This is
1450 Make the Emacs/W3 page the current buffer in the other window.
1452 Display the Emacs/W3 page in the other window, but don't make it the
1455 Don't display Emacs/W3 page, but print a message when ready and beep.
1457 The same as @code{polite}, but don't beep.
1459 Make no indication that the page is ready, in fact any other value is
1466 @node Stylesheets, Supported URLs, Display Variables, Top
1467 @chapter Stylesheets
1468 The way in which Emacs/W3 formats a document is very customizable. All
1469 formatting is now controlled by a default stylesheet set by the user
1470 with the @code{w3-default-stylesheet} variable. Emacs/W3 currently
1471 supports the @sc{W3C} recommendation for Cascading Style Sheets, Level 1
1472 (commonly known as @sc{CSS1}) with a few experimental items from other
1473 W3C proposals. Wherever Emacs/W3 diverges from the specification, it
1474 will be clearly documented, and will be changed once a full standard is
1477 Support for @sc{dsssl} is progressing, but spare time is at an all-time
1478 low. If anyone would like to help, please contact the author.
1480 The following sections closely parallel the @sc{css1} specification so
1481 it should be very easy to look up what Emacs/W3 supports when browsing
1482 through the @sc{css1} specification. Please note that a lot of the text
1483 in the following sections comes directly from the specification as
1487 * Terminology:: Terms used in the rest of this chapter.
1488 * Basic Concepts:: Why are stylesheets useful? Getting started.
1489 * Pseudo-Classes/Elements:: Special classes for elements.
1490 * The Cascade:: How stylesheets are combined.
1491 * Properties:: What properties you can set on elements.
1492 * Units:: What you can set them to.
1495 @node Terminology, Basic Concepts, Stylesheets, Stylesheets
1496 @section Terminology
1500 HTML attribute, ie: @samp{align=center} --- align is the attribute.
1502 The author of an HTML document.
1503 @item block-level element
1504 An element which has a line break before and after (e.g.@: 'H1' in @sc{html}).
1506 The part of the UA's drawing surface onto which documents are rendered.
1508 A subelement in @sc{sgml} terminology.
1509 @item contextual selector
1510 A selector that matches elements based on their position in the document
1511 structure. A contextual selector consists of several simple
1512 selectors. E.g., the contextual selector 'H1.initial B' consists of two
1513 simple selectors, 'H1.initial' and 'B'.
1515 Cascading Style Sheets.
1517 A property (e.g. 'font-size') and a corresponding value (e.g. '12pt').
1519 The designer of a style sheet.
1525 A generic identifier in @sc{sgml} terminology.
1526 @item fictional tag sequence
1527 A tool for describing the behavior of pseudo-classes and pseudo-elements.
1529 The size for which a font is designed. Typically, the size of a font is
1530 approximately equal to the distance from the bottom of the lowest letter
1531 with a descender to the top of the tallest letter with an ascender and
1532 (optionally) with a diacritical mark.
1533 @item @sc{html} extension
1534 Markup introduced by UA vendors, most often to support certain visual
1535 effects. The @sc{font}, @sc{center} and @sc{blink} elements are examples
1536 of HTML extensions, as is the @sc{bgcolor} attribute. One of the goals
1537 of @sc{css} is to provide an alternative to @sc{html} extensions.
1538 @item inline element
1539 An element which does not have a line break before and after
1540 (e.g. '@sc{strong}' in @sc{html})
1541 @item intrinsic dimensions
1542 The width and height as defined by the element itself, not imposed by
1543 the surroundings. In this specification it is assumed that all replaced
1544 elements -- and only replaced elements -- come with intrinsic
1546 @item parent element
1547 The containing element in @sc{sgml} terminology.
1548 @item pseudo-element
1549 Pseudo-elements are used in @sc{css} selectors to address typographical
1550 items (e.g. the first line of an element) rather than structural
1553 Pseudo-classes are used in @sc{css} selectors to allow information
1554 external to the @sc{html} source (e.g. the fact that an anchor has been
1555 visited or not) to classify elements.
1557 A stylistic parameter that can be influenced through @sc{css}.
1559 The person for whom the document is rendered.
1560 @item replaced element
1561 An element that the @sc{css} formatter only knows the intrinsic
1562 dimensions of. In @sc{html}, @sc{img}, @sc{input}, @sc{textarea},
1563 @sc{select} and @sc{object} elements can be examples of replaced
1564 elements. E.g., the content of the @sc{img} element is often replaced by
1565 the image that the @sc{src} attribute points to. @sc{css1} does not
1566 define how the intrinsic dimensions are found.
1568 A declaration (e.g. 'font-family: helvetica') and its selector
1571 A string that identifies what elements the corresponding rule applies
1572 to. A selector can either be a simple selector (e.g. 'H1') or a
1573 contextual selector (e.g. @sc{'h1 b'}) which consists of several simple
1576 Standard Generalized Markup Language, of which @sc{html} is an
1578 @item simple selector
1579 A selector that matches elements based on the element type and/or
1580 attributes, and not the element's position in the document
1581 structure. E.g., 'H1.initial' is a simple selector.
1583 A collection of rules.
1585 User Agent, often a web browser or web client.
1587 Synonymous with reader.
1589 The priority of a rule.
1592 @node Basic Concepts, Pseudo-Classes/Elements, Terminology, Stylesheets
1593 @section Basic Concepts
1595 Designing simple style sheets is easy. One needs only to know a little
1596 HTML and some basic desktop publishing terminology. E.g., to set the
1597 text color of 'H1' elements to blue, one can say:
1600 H1 @{ color: blue @}
1603 The example above is a simple CSS rule. A rule consists of two main
1604 parts: selector ('H1') and declaration ('color: blue'). The declaration
1605 has two parts: property ('color') and value ('blue'). While the example
1606 above tries to influence only one of the properties needed for rendering
1607 an HTML document, it qualifies as a style sheet on its own. Combined
1608 with other style sheets (one fundamental feature of CSS is that style
1609 sheets are combined) it will determine the final presentation of the
1612 The selector is the link between the HTML document and the style sheet, and
1613 all HTML element types are possible selectors.
1615 @node Pseudo-Classes/Elements, The Cascade, Basic Concepts, Stylesheets
1616 @section Pseudo-Classes/Elements
1618 In @sc{css1}, style is normally attached to an element based on its
1619 position in the document structure. This simple model is sufficient for
1620 a wide variety of styles, but doesn't cover some common effects. The
1621 concept of pseudo-classes and pseudo-elements extend addressing in
1622 @sc{css1} to allow external information to influence the formatting
1625 Pseudo-classes and pseudo-elements can be used in @sc{css} selectors,
1626 but do not exist in the @sc{html} source. Rather, they are "inserted" by
1627 the @sc{ua} under certain conditions to be used for addressing in style
1628 sheets. They are referred to as "classes" and "elements" since this is a
1629 convenient way of describing their behavior. More specifically, their
1630 behavior is defined by a fictional tag sequence.
1632 Pseudo-elements are used to address sub-parts of elements, while
1633 pseudo-classes allow style sheets to differentiate between different
1636 The only support pseudo-classes in Emacs/W3 are on the anchor tag
1639 User agents commonly display newly visited anchors differently from
1640 older ones. In @sc{css1}, this is handled through pseudo-classes on the
1644 A:link @{ color: red @} /* unvisited link */
1645 A:visited @{ color: blue @} /* visited links */
1646 A:active @{ color: lime @} /* active links */
1649 All 'A' elements with an 'HREF' attribute will be put into one and only
1650 one of these groups (i.e. target anchors are not affected). UAs may
1651 choose to move an element from 'visited' to 'link' after a certain
1652 time. An 'active' link is one that is currently being selected (e.g. by
1653 a mouse button press) by the reader.
1655 The formatting of an anchor pseudo-class is as if the class had been
1656 inserted manually. A @sc{ua} is not required to reformat a currently
1657 displayed document due to anchor pseudo-class transitions. E.g., a style
1658 sheet can legally specify that the 'font-size' of an 'active' link
1659 should be larger that a 'visited' link, but the UA is not required to
1660 dynamically reformat the document when the reader selects the 'visited'
1663 Pseudo-class selectors do not match normal classes, and vice versa. The
1664 style rule in the example below will therefore not have any influence:
1667 A:link @{ color: red @}
1669 <A CLASS=link NAME=target5> ... </A>
1672 In @sc{css1}, anchor pseudo-classes have no effect on elements other
1673 than 'A'. Therefore, the element type can be omitted from the selector:
1676 A:link @{ color: red @}
1677 :link @{ color: red @}
1680 The two selectors above will select the same elements in CSS1.
1682 Pseudo-class names are case-insensitive.
1684 Pseudo-classes can be used in contextual selectors:
1687 A:link IMG @{ border: solid blue @}
1690 Also, pseudo-classes can be combined with normal classes:
1693 A.external:visited @{ color: blue @}
1695 <A CLASS=external HREF="http://out.side/">external link</A>
1698 If the link in the above example has been visited, it will be rendered
1699 in blue. Note that normal class names precede pseudo-classes in the
1702 @node The Cascade, Properties, Pseudo-Classes/Elements, Stylesheets
1703 @section The Cascade
1705 In @sc{css}, more than one style sheet can influence the presentation
1706 simultaneously. There are two main reasons for this feature: modularity
1707 and author/reader balance.
1711 A style sheet designer can combine several (partial) style sheets to
1715 @@import url(http://www.style.org/pastoral);
1716 @@import url(http://www.style.org/marine);
1718 H1 @{ color: red @} /* override imported sheets */
1720 @item author/reader balance
1721 Both readers and authors can influence the presentation through style
1722 sheets. To do so, they use the same style sheet language thus reflecting
1723 a fundamental feature of the web: everyone can become a publisher. The
1724 @sc{ua} is free to choose the mechanism for referencing personal style
1728 Sometimes conflicts will arise between the style sheets that influence
1729 the presentation. Conflict resolution is based on each style rule having
1730 a weight. By default, the weights of the reader's rules are less than
1731 the weights of rules in the author's documents. I.e., if there are
1732 conflicts between the style sheets of an incoming document and the
1733 reader's personal sheets, the author's rules will be used. Both reader
1734 and author rules override the @sc{ua}'s default values.
1736 The imported style sheets also cascade with each other, in the order
1737 they are imported, according to the cascading rules defined below. Any
1738 rules specified in the style sheet itself override rules in imported
1739 style sheets. That is, imported style sheets are lower in the cascading
1740 order than rules in the style sheet itself. Imported style sheets can
1741 themselves import and override other style sheets, recursively.
1743 In @sc{css1}, all '@@import' statements must occur at the start of a
1744 style sheet, before any declarations. This makes it easy to see that
1745 rules in the style sheet itself override rules in the imported style
1748 NOTE: The use of !important in @sc{css} stylesheets is unsupported at
1751 Conflicting rules are intrinsic to the CSS mechanism. To find the value
1752 for an element/property combination, the following algorithm must be
1757 Find all declarations that apply to the element/property in
1758 question. Declarations apply if the selector matches the element in
1759 question. If no declarations apply, the inherited value is used. If
1760 there is no inherited value (this is the case for the 'HTML' element and
1761 for properties that do not inherit), the initial value is used.
1763 Sort the declarations by explicit weight: declarations marked
1764 '!important' carry more weight than unmarked (normal) declarations.
1766 Sort by origin: the author's style sheets override the reader's style
1767 sheet which override the UA's default values. An imported style sheet
1768 has the same origin as the style sheet from which it is imported.
1770 Sort by specificity of selector: more specific selectors will override
1771 more general ones. To find the specificity, count the number of ID
1772 attributes in the selector (a), the number of CLASS attributes in the
1773 selector (b), and the number of tag names in the selector
1774 (c). Concatenating the three numbers (in a number system with a large
1775 base) gives the specificity. Some examples:
1777 LI @{...@} /* a=0 b=0 c=1 -> specificity = 1 */
1778 UL LI @{...@} /* a=0 b=0 c=2 -> specificity = 2 */
1779 UL OL LI @{...@} /* a=0 b=0 c=3 -> specificity = 3 */
1780 LI.red @{...@} /* a=0 b=1 c=1 -> specificity = 11 */
1781 UL OL LI.red @{...@} /* a=0 b=1 c=3 -> specificity = 13 */
1782 #x34y @{...@} /* a=1 b=0 c=0 -> specificity = 100 */
1784 Pseudo-elements and pseudo-classes are counted as normal elements and
1785 classes, respectively.
1787 Sort by order specified: if two rules have the same weight, the latter
1788 specified wins. Rules in imported style sheets are considered to be
1789 before any rules in the style sheet itself.
1792 The search for the property value can be terminated whenever one rule
1793 has a higher weight than the other rules that apply to the same
1794 element/property combination.
1796 This strategy gives author's style sheets considerably higher weight
1797 than those of the reader. It is therefore important that the reader has
1798 the ability to turn off the influence of a certain style sheet,
1799 e.g. through a pull-down menu.
1801 A declaration in the 'STYLE' attribute of an element has the same weight
1802 as a declaration with an ID-based selector that is specified at the end
1806 <STYLE TYPE="text/css">
1807 #x97z @{ color: blue @}
1810 <P ID=x97z STYLE="color: red">
1813 In the above example, the color of the 'P' element would be
1814 red. Although the specificity is the same for both declarations, the
1815 declaration in the 'STYLE' attribute will override the one in the
1816 'STYLE' element because of cascading rule number 5.
1818 The @sc{ua} may choose to honor other stylistic @sc{html} attributes,
1819 for example 'ALIGN'. If so, these attributes are translated to the
1820 corresponding @sc{css} rules with specificity equal to 1. The rules are
1821 assumed to be at the start of the author style sheet and may be
1822 overridden by subsequent style sheet rules. In a transition phase, this
1823 policy will make it easier for stylistic attributes to coexist with
1826 @node Properties, Units, The Cascade, Stylesheets
1829 In the text below, the allowed values for each property are listed
1830 with a syntax like the following:
1834 Value: [ <length> | thick | thin ]@{1,4@}
1835 Value: <uri>? <color> [ / <color> ]?
1836 Value: <uri> || <color>
1839 The words between < and > give a type of value. The most common types
1840 are <length>, <percentage>, <url>, <number>and <color> these are
1841 described in the section on [[units]]. The more specialized types
1842 (e.g. <font-family>and <border-style>) are described under the property
1845 Other words are keywords that must appear literally, without quotes. The
1846 slash (/) and the comma (,) must also appear literally.
1848 Several things juxtaposed mean that all of them must occur, in the given
1849 order. A bar (|) separates alternatives: one of them must occur. A
1850 double bar (A || B) means that either A or B or both must occur, in any
1851 order. Brackets ([]) are for grouping. Juxtaposition is stronger than
1852 the double bar, and the double bar is stronger than the bar. Thus "a b |
1853 c || d e" is equivalent to "[ a b ] | [ c || [ d e ]]".
1855 Every type, keyword, or bracketed group may be followed by one of the
1856 following modifiers:
1860 An asterisk (*) indicates that the preceding type, word or group is
1861 repeated zero or more times.
1863 A plus (+) indicates that the preceding type, word or group is repeated
1866 A question mark (?) indicates that the preceding type, word or group is
1869 A pair of numbers in curly braces (@{A,B@}) indicates that the preceding
1870 type, word or group is repeated at least A and at most B times.
1873 Other than the value the following information is also shown.
1875 @multitable @columnfractions .3 .7
1876 @item Supported Values: @tab If this is present, it lists the parts of
1877 the specification that Emacs/W3 currently supports.
1878 @item Unsupported Values: @tab If this is present, it represents the
1879 parts of the specifcation that Emacs/W3 does not support.
1880 @item Initial: @tab The default value for the property, unless
1881 explicitly set in a stylesheet.
1882 @item Applies to: @tab What type of elements this property can be attached to.
1883 @item Inherited: @tab Yes or no
1884 @item Percentage values: @tab What a percentage value applies to when given.
1888 * Font Properties:: Selecting fonts, styles, and sizes.
1889 * Colors and Backgrounds:: Controlling colors, front and back.
1890 * Text Properties:: Alignment, decoration, and more!
1891 * Box Properties:: Borders, padding, and margins, oh my!
1892 * Classification:: Changing whitespace and display policies.
1893 * Media Selection:: Conditionalize stylesheets on media-type.
1894 * Speech Properties:: Speech output controlled by stylesheets.
1897 @node Font Properties, Colors and Backgrounds, Properties, Properties
1898 @subsection Font Properties
1900 Setting font properties will be among the most common uses of style
1901 sheets. Unfortunately, there exists no well-defined and universally
1902 accepted taxonomy for classifying fonts, and terms that apply to one
1903 font family may not be appropriate for others. E.g. 'italic' is commonly
1904 used to label slanted text, but slanted text may also be labeled as
1905 being @b{Oblique}, @b{Slanted}, @b{Incline}, @b{Cursive} or
1906 @b{Kursiv}. Therefore it is not a simple problem to map typical font
1907 selection properties to a specific font.
1909 The properties defined by CSS1 are described in the following sections.
1911 * font-family:: Groups of fonts.
1912 * font-style:: Normal, italic, or oblique?
1913 * font-variant:: Small-caps, etc.
1914 * font-weight:: How bold can you go?
1915 * font-size:: How big is yours?
1916 * font:: Shorthand for all of the above.
1919 @node font-family, font-style, Font Properties, Font Properties
1920 @subsubsection font-family
1922 @multitable @columnfractions .20 .8
1923 @item Supported Values: @tab [[<family-name> | <generic-family>],]* [<family-name> | <generic-family>]
1924 @item Initial: @tab User specific
1925 @item Applies to: @tab all elements
1926 @item Inherited: @tab yes
1927 @item Percentage values: @tab N/A
1929 The value is a prioritized list of font family names and/or generic
1930 family names. Unlike most other CSS1 properties, values are separated
1931 by a comma to indicate that they are alternatives:
1934 BODY @{ font-family: gill, helvetica, sans-serif @}
1937 There are two types of list values:
1941 The name of a font family of choice. In the last example, "gill" and
1942 "helvetica" are font families.
1943 @item <generic-family>
1944 In the example above, the last value is a generic family name. The
1945 following generic families are defined:
1948 'serif' (e.g. Times)
1950 'sans-serif' (e.g. Helvetica)
1952 'cursive' (e.g. Zapf-Chancery)
1954 'fantasy' (e.g. Western)
1956 'monospace' (e.g. Courier)
1960 Style sheet designers are encouraged to offer a generic font family as a
1963 Font names containing whitespace should be quoted:
1966 BODY @{ font-family: "new century schoolbook", serif @}
1968 <BODY STYLE="font-family: 'My own font', fantasy">
1971 If quoting is omitted, any whitespace characters before and after the
1972 font name are ignored and any sequence of whitespace characters inside
1973 the font name is converted to a single space.
1975 @node font-style, font-variant, font-family, Font Properties
1976 @subsubsection font-style
1978 @multitable @columnfractions .2 .8
1979 @item Supported Values: @tab normal | italic | oblique
1980 @item Initial: @tab normal
1981 @item Applies to: @tab all elements
1982 @item Inherited: @tab yes
1983 @item Percentage values: @tab N/A
1986 The 'font-style' property selects between normal (sometimes referred to
1987 as "roman" or "upright"), italic and oblique faces within a font family.
1989 A value of 'normal' selects a font that is classified as 'normal' in the
1990 UA's font database, while 'oblique' selects a font that is labeled
1991 'oblique'. A value of 'italic' selects a font that is labeled 'italic',
1992 or, if that is not available, one labeled 'oblique'.
1994 The font that is labeled 'oblique' in the UA's font database may
1995 actually have been generated by electronically slanting a normal font.
1997 Fonts with Oblique, Slanted or Incline in their names will typically be
1998 labeled 'oblique' in the UA's font database. Fonts with Italic, Cursive
1999 or Kursiv in their names will typically be labeled 'italic'.
2002 H1, H2, H3 @{ font-style: italic @}
2003 H1 EM @{ font-style: normal @}
2006 In the example above, emphasized text within 'H1' will appear in a
2009 @node font-variant, font-weight, font-style, Font Properties
2010 @subsubsection font-variant
2012 @multitable @columnfractions .2 .8
2013 @item Value: @tab normal | small-caps
2014 @item Initial: @tab normal
2015 @item Applies to: @tab all elements
2016 @item Inherited: @tab yes
2017 @item Percentage values: @tab N/A
2020 Another type of variation within a font family is the small-caps. In a
2021 small-caps font the lower case letters look similar to the uppercase
2022 ones, but in a smaller size and with slightly different proportions. The
2023 'font-variant' property selects that font.
2025 A value of 'normal' selects a font that is not a small-caps font,
2026 'small-caps' selects a small-caps font. It is acceptable (but not
2027 required) in CSS1 if the small-caps font is a created by taking a normal
2028 font and replacing the lower case letters by scaled uppercase
2029 characters. As a last resort, uppercase letters will be used as
2030 replacement for a small-caps font.
2032 The following example results in an 'H3' element in small-caps, with
2033 emphasized words in oblique small-caps:
2036 H3 @{ font-variant: small-caps @}
2037 EM @{ font-style: oblique @}
2040 There may be other variants in the font family as well, such as fonts
2041 with old-style numerals, small-caps numerals, condensed or expanded
2042 letters, etc. CSS1 has no properties that select those.
2044 @node font-weight, font-size, font-variant, Font Properties
2045 @subsubsection font-weight
2047 @multitable @columnfractions .3 .7
2048 @item Supported Values: @tab normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
2049 @item Unsupported Values: @tab bolder | lighter
2050 @item Initial: @tab normal
2051 @item Applies to: @tab all elements
2052 @item Inherited: @tab yes
2053 @item Percentage values: @tab N/A
2056 The 'font-weight' property selects the weight of the font. The values
2057 '100' to '900' form an ordered sequence, where each number indicates a
2058 weight that is at least as dark as its predecessor. The keyword 'normal'
2059 is synonymous with '400', and 'bold' is synonymous with '700'. Keywords
2060 other than 'normal' and 'bold' have been shown to be often confused with
2061 font names and a numerical scale was therefore chosen for the 9-value
2065 P @{ font-weight: normal @} /* 400 */
2066 H1 @{ font-weight: 700 @} /* bold */
2069 The 'bolder' and 'lighter' values select font weights that are relative
2070 to the weight inherited from the parent:
2073 STRONG @{ font-weight: bolder @}
2076 There is no guarantee that there will be a darker face for each of the
2077 'font-weight' values; for example, some fonts may have only a normal and
2078 a bold face, others may have eight different face weights. There is no
2079 guarantee on how a UA will map font faces within a family to weight
2080 values. The only guarantee is that a face of a given value will be no
2081 less dark than the faces of lighter values.
2083 @node font-size, font, font-weight, Font Properties
2084 @subsubsection font-size
2086 @multitable @columnfractions .3 .7
2087 @item Supported Values: @tab <absolute-size> | <length>
2088 @item Unsupported Values: @tab <percentage> | <relative-size>
2089 @item Initial: @tab medium
2090 @item Applies to: @tab all elements
2091 @item Inherited: @tab yes
2092 @item Percentage values: @tab relative to parent element's font size
2096 @item <absolute-size>
2097 An <absolute-size> keyword is an index to a table of font sizes computed
2098 and kept by the UA. Possible values are:
2116 On a computer screen a scaling factor of 1.5 is suggested between
2117 adjacent indexes; if the 'medium' font is 10pt, the 'large' font could
2118 be 15pt. Different media may need different scaling factors. Also, the
2119 UA should take the quality and availability of fonts into account when
2120 computing the table. The table may be different from one font family to
2122 @item <relative-size>
2123 A <relative-size> keyword is interpreted relative to the table of font
2124 sizes and the font size of the parent element. Possible values are
2125 @b{larger} or @b{smaller}. For example, if the parent element has a font
2126 size of 'medium', a value of 'larger' will make the font size of the
2127 current element be 'large'. If the parent element's size is not close to
2128 a table entry, the UA is free to interpolate between table entries or
2129 round off to the closest one. The UA may have to extrapolate table
2130 values if the numerical value goes beyond the keywords.
2133 Length and percentage values should not take the font size table into
2134 account when calculating the font size of the element.
2136 Negative values are not allowed.
2138 On all other properties, 'em' and 'ex' length values refer to the font
2139 size of the current element. On the 'font-size' property, these length
2140 units refer to the font size of the parent element.
2142 Note that an application may reinterpret an explicit size, depending on
2143 the context. E.g., inside a VR scene a font may get a different size
2144 because of perspective distortion.
2149 P @{ font-size: 12pt; @}
2150 BLOCKQUOTE @{ font-size: larger @}
2151 EM @{ font-size: 150% @}
2152 EM @{ font-size: 1.5em @}
2155 If the suggested scaling factor of 1.5 is used, the last three
2156 declarations are identical.
2158 @node font, , font-size, Font Properties
2161 @multitable @columnfractions .2 .8
2162 @item Value: @tab [ <font-style> || <font-variant> || <font-weight> ]? <font-size> [ / <line-height> ]? <font-family>
2163 @item Initial: @tab not defined for shorthand properties
2164 @item Applies to: @tab all elements
2165 @item Inherited: @tab yes
2166 @item Percentage values: @tab allowed on <font-size> and <line-height>
2168 The 'font' property is a shorthand property for setting 'font-style'
2169 'font-variant' 'font-weight' 'font-size', 'line-height' and
2170 'font-family' at the same place in the style sheet. The syntax of this
2171 property is based on a traditional typographical shorthand notation to
2172 set multiple properties related to fonts.
2174 For a definition of allowed and initial values, see the previously
2175 defined properties. Properties for which no values are given are set to
2176 their initial value.
2179 P @{ font: 12pt/14pt sans-serif @}
2180 P @{ font: 80% sans-serif @}
2181 P @{ font: x-large/110% "new century schoolbook", serif @}
2182 P @{ font: bold italic large Palatino, serif @}
2183 P @{ font: normal small-caps 120%/120% fantasy @}
2186 In the second rule, the font size percentage value ('80%') refers to the
2187 font size of the parent element. In the third rule, the line height
2188 percentage refers to the font size of the element itself.
2190 In the first three rules above, the 'font-style', 'font-variant' and
2191 'font-weight' are not explicitly mentioned, which means they are all
2192 three set to their initial value ('normal'). The fourth rule sets the
2193 'font-weight' to 'bold', the 'font-style' to 'italic' and implicitly
2194 sets 'font-variant' to 'normal'.
2196 The fifth rule sets the 'font-variant' ('small-caps'), the 'font-size'
2197 (120% of the parent's font), the 'line-height' (120% times the font
2198 size) and the 'font-family' ('fantasy'). It follows that the keyword
2199 'normal' applies to the two remaining properties: 'font-style' and
2202 @node Colors and Backgrounds, Text Properties, Font Properties, Properties
2203 @subsection Colors and Backgrounds
2205 These properties describe the color (often called foreground color) and
2206 background of an element (i.e. the surface onto which the content is
2207 rendered). One can set a background color and/or a background image. The
2208 position of the image, if/how it is repeated, and whether it is fixed or
2209 scrolled relative to the canvas can also be set.
2211 The 'color' property inherits normally. The background properties do not
2212 inherit, but the parent element's background will shine through by
2213 default because of the initial 'transparent' value on
2216 NOTE: Currently, Emacs/W3 can only show background images under XEmacs.
2217 Emacs 19 doesn't have the support in its display code yet.
2220 * color:: Foreground colors.
2221 * background-color:: Background colors.
2222 * background-image:: Background images.
2223 * background-repeat:: Controlling repeating of background images.
2224 * background-attachment:: Where background images are drawn.
2225 * background-position:: Where background images are drawn.
2226 * background:: Shorthand for all background properties.
2229 @node color, background-color, Colors and Backgrounds, Colors and Backgrounds
2230 @subsubsection color
2232 @multitable @columnfractions .2 .8
2233 @item Value: @tab <color>
2234 @item Initial: @tab User specific
2235 @item Applies to: @tab all elements
2236 @item Inherited: @tab yes
2237 @item Percentage values: @tab N/A
2240 This property describes the text color of an element (often referred to
2241 as the foreground color). There are different ways to specify red:
2244 EM @{ color: red @} /* natural language */
2245 EM @{ color: rgb(255,0,0) @} /* RGB range 0-255 */
2248 See @ref{Color Units} for a description of possible color values.
2250 @node background-color, background-image, color, Colors and Backgrounds
2251 @subsubsection background-color
2253 @multitable @columnfractions .2 .8
2254 @item Value: @tab <color> | transparent
2255 @item Initial: @tab transparent
2256 @item Applies to: @tab all elements
2257 @item Inherited: @tab no
2258 @item Percentage values: @tab N/A
2261 This property sets the background color of an element.
2264 H1 @{ background-color: #F00 @}
2267 @node background-image, background-repeat, background-color, Colors and Backgrounds
2268 @subsubsection background-image
2270 @multitable @columnfractions .2 .8
2271 @item Value: @tab <url> | none
2272 @item Initial: @tab none
2273 @item Applies to: @tab all elements
2274 @item Inherited: @tab no
2275 @item Percentage values: @tab N/A
2278 This property sets the background image of an element. When setting a
2279 background image, one should also set a background color that will be
2280 used when the image is unavailable. When the image is available, it is
2281 overlaid on top of the background color.
2284 BODY @{ background-image: url(marble.png) @}
2285 P @{ background-image: none @}
2288 @node background-repeat, background-attachment, background-image, Colors and Backgrounds
2289 @subsubsection background-repeat
2291 This property is not supported at all under Emacs/W3.
2293 @node background-attachment, background-position, background-repeat, Colors and Backgrounds
2294 @subsubsection background-attachment
2296 This property is not supported at all under Emacs/W3.
2298 @node background-position, background, background-attachment, Colors and Backgrounds
2299 @subsubsection background-position
2301 This property is not supported at all under Emacs/W3.
2303 @node background, , background-position, Colors and Backgrounds
2304 @subsubsection background
2306 @multitable @columnfractions .2 .8
2307 @item Value: @tab <background-color> || <background-image> || <background-repeat> || <background-attachment> || <background-position>
2308 @item Initial: @tab not defined for shorthand properties
2309 @item Applies to: @tab all elements
2310 @item Inherited: @tab no
2311 @item Percentage values: @tab allowed on <background-position>
2314 The 'background' property is a shorthand property for setting the
2315 individual background properties (i.e., 'background-color',
2316 'background-image', 'background-repeat', 'background-attachment' and
2317 'background-position') at the same place in the style sheet.
2319 Possible values on the 'background' properties are the set of all
2320 possible values on the individual properties.
2323 BODY @{ background: red @}
2324 P @{ background: url(chess.png) gray 50% repeat fixed @}
2327 The 'background' property always sets all the individual background
2328 properties. In the first rule of the above example, only a value for
2329 'background-color' has been given and the other individual properties
2330 are set to their initial value. In the second rule, all individual
2331 properties have been specified.
2333 @node Text Properties, Box Properties, Colors and Backgrounds, Properties
2334 @subsection Text Properties
2347 @node word-spacing, letter-spacing, Text Properties, Text Properties
2348 @subsubsection word-spacing
2350 @multitable @columnfractions .3 .7
2351 @item Supported Values: @tab normal
2352 @item Unsupported Values: @tab <length>
2353 @item Initial: @tab normal
2354 @item Applies to: @tab all elements
2355 @item Inherited: @tab yes
2356 @item Percentage values: @tab N/A
2359 The length unit indicates an addition to the default space between
2360 words. Values can be negative, but there may be implementation-specific
2361 limits. The UA is free to select the exact spacing algorithm. The word
2362 spacing may also be influenced by justification (which is a value of the
2366 H1 @{ word-spacing: 0.4em @}
2369 Here, the word-spacing between each word in 'H1' elements would be
2372 NOTE: Emacs/W3 cannot currently support this, due to limitations in
2373 Emacs. It may be implemented in the future.
2375 @node letter-spacing, text-decoration, word-spacing, Text Properties
2376 @subsubsection letter-spacing
2378 @multitable @columnfractions .3 .7
2379 @item Supported Values: @tab normal
2380 @item Unsupported Values: @tab <length>
2381 @item Initial: @tab normal
2382 @item Applies to: @tab all elements
2383 @item Inherited: @tab yes
2384 @item Percentage values: @tab N/A
2387 The length unit indicates an addition to the default space between
2388 characters. Values can be negative, but there may be
2389 implementation-specific limits. The UA is free to select the exact
2390 spacing algorithm. The letter spacing may also be influenced by
2391 justification (which is a value of the 'align' property).
2394 BLOCKQUOTE @{ letter-spacing: 0.1em @}
2397 Here, the letter-spacing between each character in 'BLOCKQUOTE' elements
2398 would be increased by '0.1em'.
2400 NOTE: Emacs/W3 cannot currently support this, due to limitations in
2401 Emacs. It may be implemented in the future.
2403 @node text-decoration, vertical-align, letter-spacing, Text Properties
2404 @subsubsection text-decoration
2406 @multitable @columnfractions .3 .7
2407 @item Supported Values: @tab none | underline | line-through | blink
2408 @item Unsupported Values: @tab overline
2409 @item Initial: @tab none
2410 @item Applies to: @tab all elements
2411 @item Inherited: @tab no, but see clarification below
2412 @item Percentage values: @tab N/A
2415 This property describes decorations that are added to the text of an
2416 element. If the element has no text (e.g. the 'IMG' element in HTML) or
2417 is an empty element (e.g. '<EM></EM>'), this property has no effect. A
2418 value of 'blink' causes the text to blink.
2420 The color(s) required for the text decoration should be derived from the
2421 'color' property value.
2423 This property is not inherited, but elements should match their
2424 parent. E.g., if an element is underlined, the line should span the
2425 child elements. The color of the underlining will remain the same even
2426 if descendant elements have different 'color' values.
2429 A:link, A:visited, A:active @{ text-decoration: underline @}
2432 The example above would underline the text of all links (i.e., all 'A'
2433 elements with a 'HREF' attribute).
2435 NOTE: The 'line-through' property is only supported under XEmacs
2436 currently. A patch has been sent to the Emacs maintainers to add
2437 support for this, but it has not made it into the main distribution
2440 @node vertical-align, text-transform, text-decoration, Text Properties
2441 @subsubsection vertical-align
2443 This is currently unsupported in Emacs/W3.
2445 @node text-transform, text-align, vertical-align, Text Properties
2446 @subsubsection text-transform
2448 @multitable @columnfractions .3 .7
2449 @item Supported Values: @tab none
2450 @item Unsupported Values: @tab capitalize | uppercase | lowercase
2451 @item Initial: @tab none
2452 @item Applies to: @tab all elements
2453 @item Inherited: @tab yes
2454 @item Percentage values: @tab N/A
2459 Uppercases the first character of each word.
2461 Uppercases all letters of the element.
2463 Lowercases all letters of the element.
2465 Neutralizes inherited value.
2468 The actual transformation in each case is human language dependent.
2471 H1 @{ text-transform: uppercase @}
2474 The example above would put 'H1' elements in uppercase text.
2476 NOTE: This capability was in the previous version of Emacs/W3, but has
2477 not been reimplemented in the new display code yet. Please feel free to
2480 @node text-align, text-indent, text-transform, Text Properties
2481 @subsubsection text-align
2483 @multitable @columnfractions .2 .8
2484 @item Value: @tab left | right | center | justify
2485 @item Initial: @tab User specific
2486 @item Applies to: @tab block-level elements
2487 @item Inherited: @tab yes
2488 @item Percentage values: @tab N/A
2491 This property describes how text is aligned within the element. The
2492 actual justification algorithm used is UA and human language dependent.
2496 DIV.center @{ text-align: center @}
2499 Since 'text-align' inherits, all block-level elements inside the 'DIV'
2500 element with 'CLASS=center' will be centered. Note that alignments are
2501 relative to the width of the element, not the canvas.
2503 @node text-indent, line-height, text-align, Text Properties
2504 @subsubsection text-indent
2506 Not currently implemented in Emacs/W3.
2508 @node line-height, , text-indent, Text Properties
2509 @subsubsection line-height
2511 Not currently implemented in Emacs/W3.
2513 @node Box Properties, Classification, Text Properties, Properties
2514 @subsection Box Properties
2516 @multitable @columnfractions .2 .8
2519 @node Classification, Media Selection, Box Properties, Properties
2520 @subsection Classification
2522 These properties classify elements into categories more than they set
2523 specific visual parameters.
2525 The list-style properties describe how list items (i.e. elements with a
2526 'display' value of 'list-item') are formatted. The list-style properties
2527 can be set on any element, and it will inherit normally down the
2528 tree. However, they will only be have effect on elements with a
2529 'display' value of 'list-item'. In HTML this is typically the case for
2536 * list-style-image::
2537 * list-style-position::
2541 @node display, white-space, Classification, Classification
2542 @subsubsection display
2544 @multitable @columnfractions .2 .8
2545 @item Value: @tab block | inline | list-item | none
2546 @item Extensions: @tab line
2547 @item Initial: @tab inline
2548 @item Applies to: @tab all elements
2549 @item Inherited: @tab no
2550 @item Percentage values: @tab N/A
2553 This property describes how/if an element is displayed on the canvas
2554 (which may be on a printed page, a computer display etc.).
2556 An element with a 'display' value of 'block' opens whitespace suitable
2557 for a paragraph break. Typically, elements like 'H1' and 'P' are of
2558 type 'block'. A value of 'list-item' is similar to 'block' except that a
2559 list-item marker is added. In HTML, 'LI' will typically have this value.
2561 An element with a 'display' value of 'inline' results in a new inline
2562 box on the same line as the previous content.
2564 A value of 'none' turns off the display of the element, including
2565 children elements and the surrounding box.
2568 P @{ display: block @}
2569 EM @{ display: inline @}
2570 LI @{ display: list-item @}
2571 IMG @{ display: none @}
2574 The last rule turns off the display of images.
2576 A value of 'line' results in a single line break. Emacs/W3 needs this
2577 extension to be able to fully specify the behaviour of @sc{br} and
2578 @sc{hr} elements within a stylesheet.
2580 NOTE: Emacs/W3 defaults to using 'inline' for this property, which is a
2581 slight deviation from the specification.
2583 @node white-space, list-style-type, display, Classification
2584 @subsubsection white-space
2586 @multitable @columnfractions .2 .8
2587 @item Value: @tab normal | pre | nowrap
2588 @item Initial: @tab normal
2589 @item Applies to: @tab block-level elements
2590 @item Inherited: @tab yes
2591 @item Percentage values: @tab N/A
2594 This property declares how whitespace inside the element is handled: the
2595 'normal' way (where whitespace is collapsed), as 'pre' (which behaves
2596 like the 'PRE' element in HTML) or as 'nowrap' (where wrapping is done
2597 only through BR elements):
2600 PRE @{ white-space: pre @}
2601 P @{ white-space: normal @}
2604 @node list-style-type, list-style-image, white-space, Classification
2605 @subsubsection list-style-type
2607 @multitable @columnfractions .2 .8
2608 @item Value: @tab disc | circle | square | decimal | lower-roman | upper-roman | lower-alpha | upper-alpha | none
2609 @item Initial: @tab disc
2610 @item Applies to: @tab elements with 'display' value 'list-item'
2611 @item Inherited: @tab yes
2612 @item Percentage values: @tab N/A
2615 This property is used to determine the appearance of the list-item
2616 marker if 'list-style-image' is 'none' or if the image pointed to by the
2617 URL cannot be displayed.
2621 OL @{ list-style-type: decimal @} /* 1 2 3 4 5 etc. */
2622 OL @{ list-style-type: lower-alpha @} /* a b c d e etc. */
2623 OL @{ list-style-type: lower-roman @} /* i ii iii iv v etc. */
2626 @node list-style-image, list-style-position, list-style-type, Classification
2627 @subsubsection list-style-image
2629 @multitable @columnfractions .2 .8
2630 @item Value: @tab <url> | none
2631 @item Initial: @tab none
2632 @item Applies to: @tab elements with 'display' value 'list-item'
2633 @item Inherited: @tab yes
2634 @item Percentage values: @tab N/A
2637 This property sets the image that will be used as the list-item
2638 marker. When the image is available it will replace the marker set with
2639 the 'list-style-type' marker.
2641 NOTE: This is currently unimplemented in Emacs/W3.
2644 UL @{ list-style-image: url(http://png.com/ellipse.png) @}
2647 @node list-style-position, list-style, list-style-image, Classification
2648 @subsubsection list-style-position
2650 @multitable @columnfractions .3 .7
2651 @item Supported Values: @tab outside
2652 @item Unsupported Values: @tab inside
2653 @item Initial: @tab outside
2654 @item Applies to: @tab elements with 'display' value 'list-item'
2655 @item Inherited: @tab yes
2656 @item Percentage values: @tab N/A
2659 The value of 'list-style-position' determines how the list-item marker
2660 is drawn with regard to the content. For a formatting example see
2663 @node list-style, , list-style-position, Classification
2664 @subsubsection list-style
2666 @multitable @columnfractions .2 .8
2667 @item Value: @tab <keyword> || <position> || <url>
2668 @item Initial: @tab not defined for shorthand properties
2669 @item Applies to: @tab elements with 'display' value 'list-item'
2670 @item Inherited: @tab yes
2671 @item Percentage values: @tab N/A
2674 The 'list-style' property is a shorthand notation for setting the three
2675 properties 'list-style-type', 'list-style-image' and
2676 'list-style-position' at the same place in the style sheet.
2679 UL @{ list-style: upper-roman inside @}
2680 UL UL @{ list-style: circle outside @}
2681 LI.square @{ list-style: square @}
2684 Setting 'list-style' directly on 'LI' elements can have unexpected
2688 <STYLE TYPE="text/css">
2689 OL.alpha LI @{ list-style: lower-alpha @}
2690 UL LI @{ list-style: disc @}
2702 Since the specificity (as defined in the cascading order) is higher for
2703 the first rule in the style sheet in the example above, it will override
2704 the second rule on all 'LI' elements and only 'lower-alpha' list styles
2705 will be used. It is therefore recommended to set 'list-style' only on
2706 the list type elements:
2709 OL.alpha @{ list-style: lower-alpha @}
2710 UL @{ list-style: disc @}
2713 In the above example, inheritance will transfer the 'list-style' values
2714 from 'OL' and 'UL' elements to 'LI' elements.
2716 A URL value can be combined with any other value:
2719 UL @{ list-style: url(http://png.com/ellipse.png) disc @}
2722 In the example above, the 'disc' will be used when the image is
2725 @node Media Selection, Speech Properties, Classification, Properties
2726 @subsection Media Selection
2728 To specify that a stylesheet declaration should only apply when using a
2729 certain media type (ie: different font families preferred when printing
2730 versus on-screen presentation), the declarations should be wrapped in
2731 the proposed @b{@@media} directive.
2733 The @@media directive takes two arguments, the media type, and a block
2734 of style declarations.
2738 BODY @{ font-size: 10pt @}
2739 H1 @{ font-size: 14pt @}
2742 The '@@media' construct also allows to put include style sheet rules
2743 for various media in the same style sheet:
2747 BODY @{ font-size: 10pt @}
2750 BODY @{ font-size: 12pt @}
2754 Currently, the following media types are defined.
2757 Output for paged opaque material, and for documents viewed on screen in
2760 A continuous presentation for computer screens.
2762 Paged presentation for projected presentations.
2764 For braille tactile feedback devices.
2768 The stylesheet will only be applied if the user is using a light background.
2770 The stylesheet will only be applied if the user is using a dark background.
2772 The stylesheet will only be applied if the user is running in Emacs 19.
2774 The stylesheet will only be applied if the user is running in XEmacs 19.
2776 The default value, the style sheet applies to all output devices.
2779 @node Speech Properties, , Media Selection, Properties
2780 @subsection Speech Properties
2782 Those of us who are sighted are accustomed to visual presentation of
2783 @sc{html} documents, frequently on a bitmapped display. This is not the
2784 only possible presentation method, however. Aural presentation, using a
2785 combination of speech synthesis and 'audio icons', provides an
2786 alternative presentation. This form of presentation is in current use by
2787 the blind and print-impaired communities.
2789 Often such aural presentation occurs by converting the document to plain
2790 text and feeding this to a 'screen reader' -- software or hardware that
2791 simply reads all the characters on the screen. This results in less
2792 effective presentation than would be the case if the document structure
2795 There are other large markets for aural presentation, including in-car
2796 and home entertainment use; aurual or mixed aural/visual presentation is
2797 thus likely to increase in importance over the next few years. Realizing
2798 that that the aural rendering is essentially independent of the visual
2803 Allows orthogonal aural and visual views.
2805 Allows browsers to optionally implement both aural and visual views to
2806 produce truly multimodal documents.
2824 * speak-punctuation::
2830 @node volume, pause-before, Speech Properties, Speech Properties
2831 @subsubsection volume
2833 @multitable @columnfractions .2 .8
2834 @item Value: @tab <percentage> | mute | x-soft | soft | medium | loud | x-loud
2835 @item Initial: @tab medium
2836 @item Applies to: @tab all elements
2837 @item Inherited: @tab yes
2838 @item Percentage values: @tab relative to user-specified mapping
2841 The legal range of percentage values is 0% to 100%. There is a fixed
2842 mapping between keyword values and percentages:
2857 Volume refers to the median volume of the waveform. In other words, a
2858 highly inflected voice at a volume of 50 might peak well above
2859 that. Note that '0%' does not mean the same as "mute". 0% represents the
2860 minimum audible volume level and 100% corresponds to the maximum
2861 comfortable level. The UA should allow the values corresponding to 0%
2862 and 100% to be set by the user. Suitable values depend on the equipment
2863 in use (speakers, headphones), the environment (in car, home theater,
2864 library) and personal preferences. Some examples:
2868 A browser for in-car use has a setting for when there is lots of
2869 background noise . 0% would map to a fairly high level and 100% to a
2870 quite high level. The overall values are likely to be human adjustable
2871 for comfort, for example with a physical volume control: what this
2872 proposal does is adjust the dynamic range.
2874 Another speech browser is being used in the home, late at night, (don't
2875 annoy the neighbors) or in a shared study room. 0% is set to very quiet
2876 and 100% to a fairly quiet level, too. As with the first example, there
2877 is a low slope; the dynamic range is reduced. The actual volumes are low
2878 here, wheras they were high in the first example.
2880 In a quiet and isolated house, an expensive hifi home theatre setup. 0%
2881 is set fairly low and 100% to quite high; there is wide dynamic range.
2884 The same authors stylesheet could be used in all cases, simply by
2885 mapping the 0 and 100 points suitably at the client side.
2887 @node pause-before, pause-after, volume, Speech Properties
2888 @subsubsection pause-before
2890 @multitable @columnfractions .2 .8
2891 @item Value: @tab <time> | <percentage>
2892 @item Initial: @tab UA specific
2893 @item Applies to: @tab all elements
2894 @item Inherited: @tab no
2895 @item Percentage values: @tab speed
2898 This property specifies the pause before elements. It may be given in an
2899 absolute units (seconds, milliseconds) or as a relative value in which
2900 case it is relative to the reciprocal of the 'speed' property: if speed
2901 is 120 words per minute (ie a word takes half a second -- 500
2902 milliseconds) then a pause-before of 100% means a pause of 500 ms and a
2903 pause-before of 20% means 100ms.
2905 Using relative units gives more robust stylesheets in the face of large
2908 @node pause-after, pause, pause-before, Speech Properties
2909 @subsubsection pause-after
2911 @multitable @columnfractions .2 .8
2912 @item Value: @tab <time> | <percentage>
2913 @item Applies to: @tab all elements
2914 @item Inherited: @tab no
2915 @item Percentage values: @tab speed
2918 This property specifies the pause after elements. Values are specified
2919 the same way as 'pause-before'.
2921 @node pause, cue-before, pause-after, Speech Properties
2922 @subsubsection pause
2924 @multitable @columnfractions .2 .8
2925 @item Value: @tab [<time> | <percentage> ]@{1,2@};
2926 @item Applies to: @tab all elements
2927 @item Inherited: @tab no
2928 @item Percentage values: @tab speed
2931 The 'pause' property is a shorthand for setting 'pause-before' and
2932 'pause-after'. The first value is pause-before and the second is
2933 pause-after. If only one value is given, it applies to both properties.
2938 H1 @{ pause: 20ms @} /* pause-before: 20ms; pause-after: 20ms */
2939 H2 @{ pause: 30ms 40ms @} /* pause-before: 30ms; pause-after: 40ms */
2940 H3 @{ pause-after: 10ms @} /* pause-before: ?; pause-after: 10ms */
2943 @node cue-before, cue-after, pause, Speech Properties
2944 @subsubsection cue-before
2946 @multitable @columnfractions .2 .8
2947 @item Value: @tab <url> | none
2948 @item Initial: @tab none
2949 @item Applies to: @tab all elements
2950 @item Inherited: @tab no
2952 Auditory icons are another way to distinguish semantic elements. Sounds
2953 may be played before, and/or after the element to delimit it. The same
2954 sound can be used both before and after, using the cue property.
2959 A @{ cue-before: url(bell.aiff); cue-after: url(dong.wav) @}
2960 H1 @{ cue-before: url(pop.au); cue-after: url(pop.au) @}
2961 H1 @{ cue: url(pop.au) @} /* same as previous */
2964 @node cue-after, cue, cue-before, Speech Properties
2965 @subsubsection cue-after
2969 @node cue, play-during, cue-after, Speech Properties
2974 @node play-during, speed, cue, Speech Properties
2975 @subsubsection cue-during
2977 @multitable @columnfractions .2 .8
2978 @item Value: @tab <url> | mix | none
2979 @item Initial: @tab mix
2980 @item Applies to: @tab all elements
2981 @item Inherited: @tab no
2983 Similar to the cue-before and cue-after properties, this indicates sound
2984 to be played during an element as a background (ie the sound is mixed in
2990 BLOCKQUOTE.sad @{ cue-during: url(violins.aiff) @}
2993 @node speed, voice-family, play-during, Speech Properties
2994 @subsubsection speed
2996 @multitable @columnfractions .2 .8
2997 @item Value: @tab <words-per-minute> | x-slow | slow | medium | fast | x-fast | faster | slower
2998 @item Initial: @tab medium
2999 @item Applies to: @tab all elements
3000 @item Inherited: @tab yes
3003 Specifies the speaking rate. Note that both absolute and relative
3004 keyword values are allowed (compare with @ref{font-weight}).
3006 @node voice-family, pitch, speed, Speech Properties
3007 @subsubsection voice-family
3009 @multitable @columnfractions .2 .8
3010 @item Value: @tab [[<specific-voice> | <generic-voice>],]* [<specific-voice> | <generic-voice>]
3011 @item Initial: @tab device-specific
3012 @item Applies to: @tab all elements
3013 @item Inherited: @tab yes
3016 The value is a prioritized list of voice family names. Generic families
3017 are male, female, and child.
3019 Examples of specific voice families are: comedian, paul, lisa
3024 H1 @{ voice-family: announcer, male @}
3025 P.part.romeo @{ voice-family: romeo, male @}
3026 P.part.juliet @{ voice-family: juliet, female @}
3029 @node pitch, pitch-range, voice-family, Speech Properties
3030 @subsubsection pitch
3032 @multitable @columnfractions .2 .8
3035 @node pitch-range, stress, pitch, Speech Properties
3036 @subsubsection pitch-range
3038 @multitable @columnfractions .2 .8
3041 @node stress, richness, pitch-range, Speech Properties
3042 @subsubsection stress
3044 @multitable @columnfractions .2 .8
3045 @item Value: @tab <percentage>
3046 @item Initial: @tab medium
3047 @item Applies to: @tab all elements
3048 @item Inherited: @tab yes
3051 Specifies the level of stress (assertiveness or emphasis) of the
3052 speaking voice. English is a stressed language, and different parts of a
3053 sentence are assigned primary, secondary or tertiary stress. The value
3054 of property 'stress' controls the amount of inflection that results from
3055 these stress markers.
3057 Increasing the value of this property results in the speech being more
3058 strongly inflected. It is in a sense dual to property 'pitch-range' and
3059 is provided to allow developers to exploit higher-end auditory displays.
3061 @node richness, speak-punctuation, stress, Speech Properties
3062 @subsubsection richness
3064 @multitable @columnfractions .2 .8
3065 @item Value: @tab <percentage>
3066 @item Initial: @tab medium (50%)
3067 @item Applies to: @tab all elements
3068 @item Inherited: @tab yes
3071 Specifies the richness (brightness) of the speaking voice. Different
3072 speech devices may require the setting of one or more device-specific
3073 parameters to achieve this effect.
3075 The effect of increasing richness is to produce a voice that carries --
3076 reducing richness produces a soft, mellifluous voice.
3078 @node speak-punctuation, speak-date, richness, Speech Properties
3079 @subsubsection speak-punctuation
3081 @multitable @columnfractions .2 .8
3082 @item Value: @tab code | none
3083 @item Initial: @tab none
3084 @item Applies to: @tab all elements
3085 @item Inherited: @tab yes
3088 'code' indicates that punctuation such as semicolons, braces, and so on
3089 are to be spoken literally. The default value of 'none' means that
3090 punctuation is not spoken but instead is rendered naturally as various
3093 @node speak-date, speak-numeral, speak-punctuation, Speech Properties
3094 @subsubsection speak-date
3096 @multitable @columnfractions .2 .8
3097 @item Value: @tab myd | dmy | ymd | none
3098 @item Initial: @tab none
3099 @item Applies to: @tab all elements
3100 @item Inherited: @tab no
3103 This is a hint that the element contains a date and also how that date
3104 should be spoken. month-day-year is common in the USA, while
3105 day-month-year is common in Europe and year-month-day is also used.
3107 This should really be an HTML tag not a stylesheet property, since it
3108 gives semantic information about the content.
3110 @node speak-numeral, speak-time, speak-date, Speech Properties
3111 @subsubsection speak-numeral
3113 @multitable @columnfractions .2 .8
3114 @item Value: @tab digits | continous
3115 @item Initial: @tab none
3116 @item Applies to: @tab all elements
3117 @item Inherited: @tab yes
3120 @node speak-time, , speak-numeral, Speech Properties
3121 @subsubsection speak-time
3123 @multitable @columnfractions .2 .8
3124 @item Value: @tab 24 | 12 | none
3125 @item Initial: @tab none
3126 @item Applies to: @tab all elements
3127 @item Inherited: @tab yes
3130 @node Units, , Properties, Stylesheets
3135 * Percentage Units::
3142 @node Length Units, Percentage Units, Units, Units
3143 @subsection Length Units
3145 @node Percentage Units, Color Units, Length Units, Units
3146 @subsection Percentage Units
3148 @node Color Units, URLs, Percentage Units, Units
3149 @subsection color Units
3151 @node URLs, Angle Units, Color Units, Units
3154 @node Angle Units, Time Units, URLs, Units
3155 @subsection Angle Units
3157 These are the legal angle units:
3167 @node Time Units, , Angle Units, Units
3168 @subsection Time Units
3170 These are the legal time units:
3179 @node Supported URLs, MIME Support, Stylesheets, Top
3180 @chapter Supported URLs
3182 ::WORK:: List supported URL types, specific RFCs, etc.
3184 @dfn{Uniform Resource Locators} (@sc{url}s) are a specific form of
3185 @dfn{Uniform Resource Identifiers} (@sc{uri}) described in @sc{rfc}2396
3186 which updates @sc{rfc}1738 and @sc{rfc}1808.
3188 @sc{rfc2016} defines uniform resource agents.
3190 @sc{uri} have the form @var{scheme}:@var{scheme-specific-part}, where @var{scheme}
3191 appears in the menu below for @sc{url}s supported by Emacs/W3.
3193 @sc{ftp, nfs, http, https}, @code{rlogin}, @code{telnet}, tn3270,
3194 @sc{irc} and gopher @sc{url}s all have the form
3195 @var{scheme}://[@var{userinfo}@@]@var{hostname}[:@var{port}][/@var{path}]
3196 where @samp{[} and @samp{]} delimit optional parts. @var{userinfo}
3197 sometimes takes the form @var{userinfo}:@var{password} but you should
3198 beware of the security risks of sending cleartext passwords.
3199 @var{hostname} may be a domain name or a dotted decimal address. If the
3200 @samp{:@var{port}} is omitted then Emacs/W3 will use the well known port
3201 for that service. With the possible exception of @code{telnet}, it is
3202 very rare for ports to be specified, and it is possible using a
3203 non-standard port may have undesired consequences if a different service
3204 is listening on that port (eg. a gopher @sc{url} specifying the
3205 @sc{smtp} port can cause mail to be sent), but @xref{Other Variables,
3206 url-bad-port-list}. The meaning of the @var{path} component depends on
3210 * file:: Local file access.
3211 * ftp:: Remote file access via ftp.
3212 * nfs:: Remote file access via NFS.
3213 * info:: Access to the Emacs Info system.
3214 * http/https:: @sc{http/1.0} support.
3215 * mailto:: Sending simple electronic mail.
3216 * mailserver:: Slightly more complicated electronic mail.
3217 * news/nntp/snews:: Reading and sending Usenet news.
3218 * rlogin/telnet/tn3270:: Legacy host connections.
3219 * irc:: Internet Relay Chat.
3220 * data:: Embedding the data within the URL itself.
3221 * gopher:: Gopher and Gopher+.
3222 * finger:: The old favorite.
3226 @node file, ftp, Supported URLs, Supported URLs
3227 @section File @sc{url}s
3229 @cindex File @sc{url}s
3231 @vindex url-directory-index-file
3232 This allows Emacs/W3 to read arbitary files from hosts. Compressed
3233 files are handled, but support is hard-coded so that
3234 @code{jka-compr-compression-info-list} and so on have no affect.
3235 Suffixes recognized are @samp{.z}, @samp{.gz} and @samp{.Z}. If the
3236 @sc{url} points to a directory, then it will try to retrieve a file
3237 named by @code{url-directory-index-file} (@file{index.html} by default)
3238 and parse it, otherwise you get a directory listing in @samp{dired}
3239 mode. If the @sc{url} refers to a file on a remote host, then Emacs/W3
3240 uses @samp{ange-ftp} (@pxref{Top, , ange-ftp}) or @samp{efs}
3241 (@pxref{Top, , efs}) to retrive the file. ftp:// and file:// are
3242 synonymous for Emacs/W3.
3244 @node ftp, nfs, file, Supported URLs
3245 @section @sc{ftp} @sc{url}s
3248 For details of usage see @ref{file}. In Emacs/W3 file and @sc{ftp} @sc{url}s
3249 are synonymous and files on the localhost are retrieved directly rather
3250 than by @sc{ftp}. Emacs/W3 relies on @samp{ange-ftp}
3251 (@pxref{Top, , ange-ftp}) or @samp{efs} (@pxref{Top, , efs}) to do the actual
3254 @node nfs, info, ftp, Supported URLs
3255 @section @sc{nfs} @sc{url}s
3257 @cindex @sc{nfs} @sc{url}s
3259 @vindex url-nfs-automounter-directory-spec
3260 gdj1: have I misunderstood the point of this?
3261 Since @sc{nfs} is fairly transparent to the user (at least when it's
3262 working), there isn't very much to say here. An nfs @sc{url} is similar
3263 to a file @sc{url} except that it points to a file on a remote host that
3264 is handled by the automounter on the local host. The variable
3265 @code{url-nfs-automounter-directory-spec} may need to be tweaked
3266 depending on local configuration. The @sc{nfs} @sc{url} is defined in
3269 @node info, http/https, nfs, Supported URLs
3272 @cindex info @sc{url}s
3273 Info @sc{url}s are not an officially recognised @sc{url} (gdj1: is this
3274 right?), but Emacs/W3 will parse them to produce a reference to a
3275 TeXinfo node, or @samp{Top} if one is not specified. @samp{Info-mode}
3276 will be used to browse the document.
3278 @node http/https, mailto, info, Supported URLs
3282 @vindex url-honor-refresh-requests
3283 @vindex url-be-anal-about-file-attributes
3284 The HyperText Transfer Protocol is the protocol used to get documents
3285 from the World Wide Web. Emacs/W3 supports @sc{http} version 1.0 as
3286 defined in @sc{rfc}1945 --- now superseded by version 1.1 defined in
3289 If @code{url-honor-refresh-requests} is @code{nil} then @samp{Refresh}
3290 headers will not be honoured, if @code{t} then they will always be
3291 honoured, otherwise the user will be asked for each request. The
3292 default is @code{t}. @code{url-be-anal-about-file-attributes} controls
3293 whether @sc{http} is used to discover file attributes, or whether
3294 they're just guessed. The default is @code{nil} which means that
3295 Emacs/W3 will make educated guesses.
3297 @sc{https} is a secure version of @sc{http} defined in @sc{rfc}2069
3298 (gdj1: ?). Emacs/W3 requires @sc{ssl} to handle this, @xref{Installing SSL}.
3300 @node mailto, mailserver, http/https, Supported URLs
3302 @vindex url-mail-command
3304 @cindex mailto @sc{url}s
3305 A mailto @sc{url} will send an email message to the address in the
3306 @sc{url}, for example @samp{mailto:foo@@bar.com} would compose a
3307 message to foo@@bar.com. Emacs/W3 uses the command specified by the
3308 @code{url-mail-command} variable to compose the email, this is @code{url-mail} by
3309 default which uses Gnu's @samp{message} mode (@pxref{Top, Message, , message}) if
3310 available, otherwise the standard @code{mail} command. An X-Url-From
3311 header field containing the @sc{url} of the document that contained the
3312 mailto @sc{url} is added, as is an X-Mailer header field containing the
3313 version of Emacs/W3 being used.
3315 @sc{rfc}2368 extends the definition of mailto @sc{url}s in @sc{rfc1738}.
3316 The form of a mailto @sc{url} is
3317 @samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
3318 where an arbitary number of @var{header}s can be added. If the
3319 @var{header} is @samp{body}, then @var{contents} is put in the body
3320 otherwise a @var{header} header field is created with @var{contents} as its
3321 contents. Note that Emacs/W3 does not consider any headers as
3322 `dangerous' so you should check them before sending the message.
3324 Email messages are defined in @sc{rfc}822.
3326 @node mailserver, news/nntp/snews, mailto, Supported URLs
3329 @cindex mailserver @sc{url}s
3330 A mailserver @sc{url} allows you to send an email to a person, but this
3331 @sc{url} optionally specifies a subject and a body. The basic format is
3332 @samp{mailserver:[@var{mailbox}/@var{subject}[/@var{body}]}. Thus,
3333 @samp{mailserver:foo@@bar.com/wibble/flibble} will compose a message to
3334 foo@@bar.com with @var{subject} as the subject and @var{body} already in
3335 the body of the email. Note that both the subject and the body are
3336 @dfn{hex}ed, but the subject cannot contain newlines.
3338 @node news/nntp/snews, rlogin/telnet/tn3270, mailserver, Supported URLs
3339 @section news/nntp/snews
3343 @cindex news @sc{url}s
3344 @vindex url-news-use-article-mode
3345 @vindex url-news-server
3346 @vindex url-default-ports
3347 If the @sc{url} doesn't specify a host, then the host in
3348 @code{url-news-server} will be used, and unless the @sc{url} has a port
3349 the news port as defined in @code{url-default-ports} (119) will be used.
3350 The username and password specified in the @sc{url} will be used if
3351 present. The @sc{url} may contain a message-id, in which case that
3352 article is displayed; it may contain a newsgroup in which case Gnus is
3353 used to display the newsgroup; or it may by empty in which case Gnus is
3354 called with no arguments. Emacs/W3 requires Gnus v5.x or Red, Quassia
3355 or Pterodactyl Gnus, @xref{Top, , ,gnus, Gnus}. The variable
3356 @code{url-news-use-article-mode} controls the displaying of news
3357 articles; if non-@code{nil} then articles are displayed in Gnus article
3358 mode, otherwise they are turned into @sc{html} and rendered by Emacs/W3.
3360 An @sc{nntp url} is the same as a news @sc{url}, except that the
3361 @sc{url} may specify an article by its number.
3363 @node rlogin/telnet/tn3270, irc, news/nntp/snews, Supported URLs
3364 @section rlogin/telnet/tn3270
3368 @cindex rlogin @sc{url}s
3369 @cindex telnet @sc{url}s
3370 @cindex tn3270 @sc{url}s
3371 To handle rlogin, telnet and tn3270 @sc{url}s, Emacs/W3 runs an
3372 @code{rlogin}, @code{telnet} or @code{tn3270} session (the program names
3373 and arguments are hardcoded) in a @code{terminal-emulator} buffer.
3374 Well-known ports are used if the @sc{url} does not specify a port.
3377 @node irc, data, rlogin/telnet/tn3270, Supported URLs
3380 @cindex @sc{irc url}s
3381 @vindex url-irc-function
3382 @dfn{Internet Relay Chat} (@sc{irc}) is handled by handing off the @sc{irc}
3383 session to a function named in @code{url-irc-function}. This function
3384 must take five argumenst, @var{host}, @var{port}, @var{channel},
3385 @var{user} and @var{password}. The @var{channel} argument specifies the
3386 channel to join immediately, this can be @code{nil}. By default this is
3387 @code{url-irc-zenirc} which processes the arguments and lets
3388 @code{zenirc} handle the session.
3390 @node data, gopher, irc, Supported URLs
3391 @cindex data @sc{url}s
3394 Data @sc{url}s contain @sc{mime} data in the @sc{url} itself, by default
3395 the data is 8bit encoded @samp{text/plain}, but the @sc{url} can specify either
3396 or both the content-type and the encoding. Emacs/W3 will parse the
3397 @sc{url}'s data as @sc{mime} and display it appropriately. @xref{MIME Support}.
3399 @node gopher, finger, data, Supported URLs
3402 @cindex gopher @sc{url}s
3403 @vindex url-gopher-labels
3404 @vindex url-gopher-icons
3405 @vindex url-gopher-to-mime
3406 @vindex url-use-hypertext-gopher
3407 @dfn{Gopher} (Go for) was in someways the precurser to the world wide
3408 web and is becoming rarer as the web becomes more powerful.
3409 Nevertheless, there are still many gopher sites around and Emacs/W3
3410 supports this protocol (of course). The variable
3411 @code{url-gopher-labels} maps gopher types to something else (gdj: ?)
3412 for displaying the gopher menus. @code{url-gopher-icons} maps gopher
3413 types to pictures. @code{url-gopher-to-mime} maps gopher types to
3414 @sc{mime} types. If @code{url-use-hypertext-gopher} is non-@code{nil},
3415 then gopher pages will be turned into @sc{html} for Emacs/W3 to parse
3416 and display normally, otherwise Emacs/W3 will let @samp{gopher.el}
3417 handle all gopher requests which will lose gopher+ support and inlined
3418 searching. This is @code{t} by default.
3420 @node finger, netrek, gopher, Supported URLs
3423 @cindex finger @sc{url}s
3424 Finger @sc{url}s will finger a given user at a given host, or @samp{localhost}
3425 if no host is specified, processing the results to create an @sc{html}
3426 page for Emacs/W3 to display.
3428 @node netrek, , finger, Supported URLs
3430 This is unsupported at present.
3433 @node MIME Support, Security, Supported URLs, Top
3434 @chapter MIME Support
3435 @sc{mime} is an emerging standard for multimedia mail. It offers a very
3436 flexible typing mechanism. The type of a file or message is specified
3437 in two parts, separated by a '/'. The first part is the general
3438 category of the data (text, application, image, etc.). The second part
3439 is the specific type of data (postscript, png, jpeg, etc.). So
3440 @samp{text/html} specifies an @sc{html} document, whereas
3441 @samp{image/x-xwindowdump} specifies an image of an Xwindow taken with
3442 the @file{xwd} program.
3445 This typing allows much more flexibility in naming files. @sc{http}/1.0
3446 servers can now send back content-type headers in response to a request,
3447 and not have the client second-guess it based on file extensions. @sc{html}
3448 files can now be named @file{something.png} (not a great idea, but
3452 * Adding MIME types based on file extensions:: How to map file
3453 extensions onto MIME
3454 types (e.g., @samp{.png ->
3456 * Specifying Viewers:: How to specify external and internal viewers
3457 for files that Emacs/W3 cannot handle natively.
3460 @node Adding MIME types based on file extensions, Specifying Viewers, MIME Support, MIME Support
3461 @section Adding MIME types based on file extensions
3463 @vindex mm-mime-extensions
3464 For some protocols however, it is still necessary to guess the content
3465 of a file based on the file extension. This type of guess-work should
3466 only be needed when accessing files via @sc{ftp}, local file access, or old
3467 @sc{http}/0.9 servers.
3469 Instead of specifying how to view things twice, once based on
3470 content-type and once based on the file extension, it is easier to map
3471 file extensions to MIME content-types. The variable that controls this
3472 is @code{mm-mime-extensions}.
3474 This variable is an assoc list of file extensions and the corresponding
3475 MIME content-type. A sample entry looks like: @samp{(".movie"
3476 . "video/x-sgi-movie")} This makes all files that end in @file{.movie}
3477 (@file{foo.movie} and @file{bar.movie}) be interpreted as SGI animation
3478 files. If a content-type is defined for the document, then this is
3479 over-ridden. Regular expressions can @b{NOT} be used.
3481 @cindex mime-types file
3482 @findex mm-parse-mimetypes
3483 Both Mosaic and the NCSA @sc{http} daemon rely on a separate file for mapping
3484 file extensions to MIME types. Instead of having the users of Emacs/W3
3485 duplicate this in lisp, this file can be parsed using the
3486 @code{url-parse-mimetypes} function. This function is called each time
3487 w3 is loaded. It tries to locate mimetype files in several places. If
3488 the environment variable @code{MIMETYPES} is nonempty, then this is
3489 assumed to specify a UNIX-like path of mimetype files (this is a colon
3490 separated string of pathnames). If the @code{MIMETYPES} environment
3491 variable is empty, then Emacs/W3 looks for these files:
3495 @file{~/.mime-types}
3497 @file{/etc/mime-types}
3499 @file{/usr/etc/mime-types}
3501 @file{/usr/local/etc/mime-types}
3503 @file{/usr/local/www/conf/mime-types}
3506 Each line contains information for one @sc{http} type. These types resemble
3507 MIME types. To add new ones, use subtypes beginning with x-, such as
3508 application/x-myprogram. Lines beginning with # are comment lines, and
3509 suitably ignored. Each line consists of:
3511 type/subtype ext1 ext2 ... ext@var{n}
3513 type/subtype is the MIME-like type of the document. ext* is any number
3514 of space-separated filename extensions which correspond to the MIME
3517 @node Specifying Viewers, , Adding MIME types based on file extensions, MIME Support
3518 @section Specifying Viewers
3520 Not all files look as they should when parsed as an @sc{html} document
3521 (whitespace is stripped, paragraphs are reformatted, and lots of little
3522 changes that make the document look unrecognizable). Files may be
3523 passed to external programs or Emacs Lisp functions to be viewed.
3525 Not all files can be viewed accurately from within an Emacs session (PNG
3526 files for example, or audio files). For this reason, the user can
3527 specify file "viewers" based on MIME content-types. This is done with
3528 a standard mailcap file. @xref{Mailcap Files}.
3530 @findex mm-add-mailcap-entry
3531 As an alternative, the function @code{mm-add-mailcap-entry} can also be
3532 used from an appropriate hook. @xref{Hooks}. This functions takes three
3533 arguments, the major type ("@i{image}"), the minor type ("@i{png}"), and
3534 an assoc list of information about the viewer. Please see the @sc{url}
3535 documentation for more specific information on what this assoc list
3538 @node Security, Cookies, MIME Support, Top
3542 There are an increasing number of ways to authenticate a user to a web
3543 service. Emacs/W3 tries to support as many as possible. Emacs/W3
3547 @item Basic Authentication
3548 @cindex Security, Basic
3549 @cindex HTTP/1.0 Authentication
3550 @cindex Authentication, Basic
3551 The weakest authentication available, not recommended if serious
3552 security is necessary. This is simply a string that looks like
3553 @samp{user:password} that has been Base64 encoded, as defined in RFC
3555 @item Digest Authentication
3556 @cindex Security, Digest
3557 @cindex HTTP/1.0 Authentication
3558 @cindex Authentication, Digest
3559 Jeffery L. Hostetler, John Franks, Philip Hallam-Baker, Ari Luotonen,
3560 Eric W. Sink, and Lawrence C. Stewart have an internet draft for a new
3561 authentication mechanism. For the complete specification, please see
3562 draft-ietf-http-digest-aa-01.txt in the nearest internet drafts
3563 archive@footnote{One is ftp://ds.internic.net/internet-drafts}.
3564 @item SSL Encryption
3565 @cindex HTTP/1.0 Authentication
3566 @cindex Secure Sockets Layer
3568 @cindex Gag Puke Retch
3569 @cindex Exportability
3570 @cindex Export Restrictions
3571 SSL is the @code{Secure Sockets Layer} interface. Emacs/W3 supports
3572 @sc{http} transfers over an SSL encrypted channel, if the appropriate
3573 files have been installed. @xref{Installing SSL}.
3577 @vindex url-privacy-level
3578 Sometimes you don't want people to know who you are, or where you've
3579 been. @sc{http} is quite happy to tell everyone it meets who you are
3580 and where you've come from. @code{url-privacy-level} can be used to set
3581 how much information is given, it can be a list of the following symbols
3585 Do not send email address. This just sets
3586 @code{url-personal-mail-address} to @code{nil}.
3588 Do not send operating system
3590 Do not send the last location
3592 Do not send the User-Agent string (for an alternative approach,
3593 @pxref{Masquerading}).
3595 Never accept cookies (@pxref{Cookies})
3598 Alternatively @code{url-privacy-level} can be a single symbol,
3601 Send all information.
3603 Don't send the last location. Equivalent to @code{(lastloc)}
3605 Don't send the email address or last location. Equivalent to
3606 @code{(email lastloc)}
3608 Don't send anything. Equivalent to @code{(email os lastloc agent cookie)}
3611 If you change @code{url-privacy-level} then you should also call
3612 @code{url-setup-privacy-info} to make sure that the changes propogate.
3614 @node Cookies, Non-Unix Operating Systems, Security, Top
3618 @sc{http} is a stateless protocol which means that the server sees every
3619 request for pages independently with no idea of how it relates to any
3620 other request. Therefore the server has no idea whether or not you've
3621 seen a page before, or whether you've registered (if that's an option).
3622 Cookies@footnote{In computer terms a @dfn{cookie} is data that a
3623 program holds but which has no meaning in itself. Cookies are not
3624 processed by the program (indeed the program may not even know
3625 what data they hold or what format it's in) but is passed to libraries or
3626 servers which do understand it.} are used to add state to @sc{http}
3627 sessions. Cookies are defined in @sc{rfc2109}.
3629 @vindex url-cookie-file
3630 Cookies are saved in the file specified in @code{url-cookie-file}, which
3631 is @code{@var{w3-configuration-directory}/cookies} by default. Note
3632 that this file should probably not be world writable, and possibly not
3633 even world readable.
3635 @vindex url-cookie-untrusted-urls
3636 @vindex url-cookie-trusted-urls
3637 @vindex url-cookie-confirmation
3638 Some people see cookies as an invasion of privacy while others see them
3639 as a product of badly designed websites and buggy servers. Emacs/W3
3640 lets you unconditionally reject all cookies by adding @code{cookie} to
3641 @code{url-privacy-level} or setting it to @code{paranoid}
3642 (@pxref{Security}) but for those who want finer control over what to
3643 accept and reject, Emacs/W3 offers @code{url-cookie-trusted-urls} and
3644 @code{url-cookie-untrusted-urls} which are lists of regular expressions
3645 that match @sc{url}s from which cookies should be accepted and rejected
3646 respectively. If a @sc{url} matches patterns in both of these, then
3647 Emacs/W3 decides whether to accept or not based on the most specific
3648 match (the most specific match being the shortest match).
3649 @c gdj1: This doesn't seem right.
3650 Note that Emacs/W3 only considers the first match for each variable, so
3651 the regular expressions should be in increasing order of generality.
3653 For even more control over which cookies are accepted, you can set
3654 @code{url-cookie-confirmation} to non-@code{nil}, in which case every
3655 time a cookie is offered Emacs/W3 will ask if you want to accept it.
3656 This only applies to cookies that would otherwise be accepted, Emacs/W3
3657 will still reject cookies from @sc{url}s matched in
3658 @code{url-cookie-untrusted-urls}.
3660 @node Non-Unix Operating Systems, Speech Integration, Cookies, Top
3661 @chapter Non-Unix Operating Systems
3662 @cindex Non-Unix Operating Systems
3665 * VMS:: The wonderful world of VAX|AXP-VMS!
3666 * OS/2:: The next-best thing to Unix.
3667 * MS-DOS:: The wonderful world of MS-DOG!
3668 * Windows:: Windows NT, Chicago/Windows 95.
3671 @node VMS, OS/2, Non-Unix Operating Systems, Non-Unix Operating Systems
3678 :: WORK :: VMS Specific instriuctions
3680 @node OS/2, MS-DOS, VMS, Non-Unix Operating Systems
3685 :: WORK :: OS/2 Specific instructions
3687 @node MS-DOS, Windows, OS/2, Non-Unix Operating Systems
3694 :: WORK :: DOS Specific instructions
3696 @node Windows, , MS-DOS, Non-Unix Operating Systems
3698 @cindex Windows (32-Bit)
3699 @cindex 32-Bit Windows
3703 :: WORK :: 32bit Windows Specific instructions
3705 @node Speech Integration, Advanced Features, Non-Unix Operating Systems, Top
3706 @chapter Speech Integration
3708 :: WORK :: Emacspeak integration
3710 @node Advanced Features, More Help, Speech Integration, Top
3711 @chapter Advanced Features
3714 * Disk Caching:: Improving performance by using a local disk cache
3715 * Printing:: Emacs/W3 can print @sc{html} by various methods.
3716 * Interfacing to Mail/News:: How to make VM understand hypertext links
3717 * Debugging HTML:: How to make Emacs/W3 display warnings about invalid
3718 @sc{html}/@sc{html}+ constructs.
3719 * Hooks:: Various hooks to use throughout Emacs/W3
3720 * Other Variables:: Miscellaneous variables that control the real
3724 @node Disk Caching, Printing, Advanced Features, Advanced Features
3725 @section Disk Caching
3727 @cindex Persistent Cache
3730 A cache stores the information on a page on the local machine. When
3731 requesting a page that is in the cache, Emacs/W3 can retrieve the page
3732 from the cache more quickly than retrieving the page again from its
3733 location out on the network. With a well-populated cache, browsing the
3734 web is dramatically faster.
3736 The first time a page is requested, Emacs/W3 retrieves the page from the
3737 network. When requesting a page that is in the cache, Emacs/W3 checks
3738 to see if the page has changed since it was last retrieved from the
3739 remote machine. If it has not changed, the local copy is used, saving
3740 the transmission of the file over the network.
3742 @vindex url-automatic-caching
3743 @cindex Turning on caching
3744 @cindex Cleaning the cache
3745 @cindex Clearing the cache
3746 @cindex Cache cleaning
3747 @cindex Limiting the size of the cache
3748 To turn on disk caching, set the variable @code{url-automatic-caching}
3749 to non-@code{nil}, or choose the 'Caching' menu item (under `Options').
3750 That is all there is to it. Running the @code{clean-cache} shell script
3751 fist is recommended, to allow for future cleaning of the cache. This
3752 shell script will remove all files that have not been accessed since it
3753 was last run. To keep the cache pared down, it is recommended that this
3754 script be run from @i{at} or @i{cron} (see the manual pages for
3755 crontab(5) or at(1) for more information)
3758 @cindex Relying on cache
3759 @cindex Cache only mode
3760 @cindex Standalone mode
3761 @cindex Browsing with no network connection
3762 @cindex Netless browsing
3763 @vindex url-standalone-mode
3764 With a large cache of documents on the local disk, it can be very handy
3765 when traveling, or any other time the network connection is not active
3766 (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely
3767 solely on its cache, and avoid checking to see if the page has changed
3768 on the remote server. In the case of a dial-on-demand PPP connection,
3769 this will keep the phone line free as long as possible, only bringing up
3770 the PPP connection when asking for a page that is not located in the
3771 cache. This is very useful for demonstrations as well. To turn this
3772 feature on, set the variable @code{url-standalone-mode} to
3773 non-@code{nil}, or choose the `Use Cache Only' menu item (under
3776 @findex url-cache-expired
3777 @vindex url-cache-ignored-protocols
3778 @vindex url-cache-directory
3779 @vindex url-cache-creation-function
3780 @code{url-cache-expired} decides whether or not a cache entry has
3781 expired. It is a function that take two times as it parameters and
3782 returns non-@code{nil} if the second time is ``too old'' when compared
3783 with the first time. @code{url-cache-ignored-protocols} is a list of
3784 protocols that will never be cached, this is @code{'("www" "about"
3785 "https" "mailto")} by default. @code{url-cache-directory} sets the
3786 directory to store the cache files,
3787 @file{"@var{w3-configuration-directory}cache/"} by default.
3788 @code{url-cache-creation-function} sets the type of cache to use, it is
3789 a function that takes a @sc{url} as an argument and returns the absolute
3790 pathname of the cache-file corresponding to that @sc{url}. You may
3791 write your own function or use one of the two ready built functions,
3792 @code{url-cache-create-filename-using-md5} and
3793 @code{url-cache-create-filename-human-readable}. The advantage of
3794 @code{url-cache-create-filename-using-md5} is that there are very few
3795 cache collisions but is only ``suitably fast'' if you're not using
3796 XEmacs. @code{url-cache-create-filename-human-readable} will give a
3797 filename more obviously connected to the @sc{url}, but it is more likely
3798 to conflict with other files.
3800 @node Printing, Interfacing to Mail/News, Disk Caching, Advanced Features
3807 If you want to print an @sc{html} document, then Emacs/W3 needs to
3808 convert it into something that can be printed. You can choose from
3811 @item @sc{html} source
3812 This will simply print the raw @sc{html} source code using
3813 @code{lpr-buffer}. An appropriate <base> tag is inserted at the
3814 beginning of the document. @c gdj1: really?
3816 @item Formatted text
3817 This will print the rendered document using @code{lpr-buffer}; so the
3818 conversion is handled by Emacs. This will print plain ASCII.
3821 @vindex w3-postscript-print-function
3822 This will call the function in @code{w3-postscript-print-function},
3823 which is @code{ps-print-buffer-with-faces} by default. This just tells
3824 Emacs to generate postscript as best it can.
3827 Emacs/W3 can generate a LaTeX equivalent of the @sc{html} document.
3829 @vindex w3-print-command
3830 @code{w3-print-command} contains a command string to print @file{dvi}
3831 files. It is @samp{lpr -h -d} by default.
3834 There are several variables controlling what the final LaTeX document looks like.
3836 :: WORK :: Document the new LaTeX backend
3840 @item w3-latex-use-latex2e
3841 @vindex w3-latex-use-latex2e
3842 If non-@code{nil}, configures the LaTeX engine to use the LaTeX2e
3843 syntax. A @code{nil} value indicates that LaTeX 2.0.9 compabibility
3844 will be used instead.
3845 @item w3-latex-docstyle
3846 @vindex w3-latex-docstyle
3847 The document style to use when printing or mailing converted @sc{html} files
3849 @item w3-latex-packages
3850 @vindex w3-latex-packages
3851 List of LaTeX packages to include. Currently this is only used if
3852 @code{w3-latex-use-latex2e} is non-@code{nil}.
3853 @item w3-latex-use-maketitle
3854 @vindex w3-latex-use-maketitle
3855 If non-@code{nil}, the LaTeX engine will use real LaTeX title pages for
3857 @item w3-latex-print-links
3858 @vindex w3-latex-print-links
3859 If non-@code{nil}, prints the @sc{url}s of hypertext links as endnotes at the
3860 end of the document. If set to @code{footnote}, prints the @sc{url}'s as
3861 footnotes on each page.
3866 @node Interfacing to Mail/News, Debugging HTML, Printing, Advanced Features
3867 @section Interfacing to Mail/News
3868 @cindex Interfacing to Mail/News
3870 @cindex Using Emacs/W3 with VM
3872 @cindex Using Emacs/W3 with Gnus
3874 @cindex Using Emacs/W3 with RMAIL
3876 More and more people are including @sc{url}s in their signatures, and within
3877 the body of mail messages. It can get quite tedious to type these into
3878 the minibuffer to follow one.
3880 @vindex browse-url-browser-function
3881 With the latest versions of VM (the 5.9x series of betas) and Gnus
3882 (5.x), @sc{url}s are automatically highlighted, and can be followed with the
3883 mouse or the return key. How the @sc{url}s are viewed is determined by the
3884 variable @code{browse-url-browser-function}, and it should be set to the
3885 symbol @code{browse-url-w3}.
3887 To access @sc{url}s from within RMAIL, the following hook should do the
3890 (add-hook 'rmail-mode-hook
3893 (define-key rmail-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
3894 (define-key rmail-mode-map "\r" 'w3-maybe-follow-link))))
3897 @node Debugging HTML, Hooks, Interfacing to Mail/News, Advanced Features
3898 @section Debugging HTML
3900 @cindex Invalid HTML
3902 @vindex w3-debug-buffer
3903 @vindex w3-debug-html
3904 @vindex w3-display-errors-hook
3905 @vindex w3-html-errors-font-lock-keywords
3906 For those people that are adventurous, or are just as anal as I am about
3907 people writing valid @sc{html}, set the variable @code{w3-debug-html} to
3908 @code{t} and see what happens. Alternatively, you can set it to
3909 @code{style} to warn about stylistic issues as well. The debugging
3910 information will be written to the buffer named by
3911 @code{w3-debug-buffer}, @file{*HTML Debug*} by default. To control
3912 font-lock highlighting in the @sc{html} error buffer, use
3913 @code{w3-html-errors-font-lock-keywords}. After Emacs/W3 has displayed
3914 @sc{html} errors for a page, it runs @code{w3-display-errors-hook}.
3917 If a Emacs/W3 thinks it has encountered invalid @sc{html}, then a debugging
3918 message is displayed.
3920 :: WORK :: Need to list the different values w3-debug-html can have, and@*
3921 :: WORK :: what they do ::
3923 gdj1: Does this refer to the macro? And if so, why?
3925 @node Hooks, Other Variables, Debugging HTML, Advanced Features
3929 These are the various hooks that can be used to customize some of
3930 Emacs/W3's behavior. They are arranged in the order in which they would
3931 happen when retrieving a document. These are all 'normal hooks' in
3932 standard Emacs-terminology, meaning they are functions (or lists of
3933 functions) that are called consecutively.
3936 @vindex w3-load-hook
3938 These hooks are run the first time a @sc{url} is fetched. All the
3939 Emacs/W3 variables are initialized before this hook is run.
3941 These hooks are run after a buffer has been parsed and displayed, but
3942 before any inlined images are downloaded and converted.
3943 @item w3-source-file-hook
3944 These hooks are run after displaying a document's source.
3947 @node Other Variables, , Hooks, Advanced Features
3948 @section Miscellaneous variables
3950 There are lots of variables that control the real nitty-gritty of Emacs/W3
3951 that the beginning user probably shouldn't mess with. Here they are.
3954 @item url-bad-port-list
3955 @vindex url-bad-port-list
3956 List of ports to warn the user about connecting to. Defaults to just
3957 the mail, @sc{nntp} and chargen ports so a malicious @sc{html} author
3958 cannot spoof mail or news to other people.
3959 @item url-confirmation-func
3960 @vindex url-confirmation-func
3961 What function to use for asking yes or no functions. Possible values
3962 are @code{'yes-or-no-p} or @code{'y-or-n-p}, or any function that takes
3963 a single argument (the prompt), and returns @code{t} only if a positive
3964 answer is gotten. Defaults to @code{'yes-or-no-p}.
3966 @item url-passwd-entry-func
3967 @vindex url-passwd-entry-func
3968 This is a symbol indicating which function to call to read in a
3969 password. If this variable is @code{nil} at startup, it is initialized
3970 depending on whether @dfn{EFS} or @dfn{ange-ftp} is being used. This
3971 function should accept the prompt string as its first argument, and the
3972 default value as its second argument.
3974 @item url-max-password-attempts
3975 @vindex url-max-password-attempts
3976 When a protected document is requested, Emacs/W3 will prompt for a
3977 password. @code{url-max-password-attempts} controls how many attempts
3978 should be allowed, it is 5 by default.
3980 @item w3-reuse-buffers
3981 @vindex w3-reuse-buffers
3982 Determines what happens when @code{w3-fetch} is called on a document
3983 that has already been loaded into another buffer. Possible values are:
3984 @code{nil}, @code{yes}, and @code{no}. @code{nil} will ask the user if
3985 Emacs/W3 should reuse the buffer (this is the default value). A value of
3986 @code{yes} means assume the user wants to always reuse the buffer. A
3987 value of @code{no} means assume the user always wants to re-fetch the
3990 @item url-show-status
3991 @vindex url-show-status
3992 Whether to show progress messages in the minibuffer.
3993 @code{url-show-status} controls if a running total of the
3994 number of bytes transferred is displayed. This Can cause a large
3995 performance hit if using a remote X display over a slow link, or a
3996 terminal with a slow modem.
3998 @item mm-content-transfer-encodings
3999 @vindex mm-content-transfer-encodings
4000 An assoc list of @var{Content-Transfer-Encodings} or
4001 @var{Content-Encodings} and the appropriate decoding algorithms for each.
4002 If the @code{cdr} of a node is a list, then this specifies the decoder is
4003 an external program, with the program as the first item in the list, and
4004 the rest of the list specifying arguments to be passed on the command line.
4005 If using an external decoder, it must accept its input from @code{stdin}
4006 and send its output to @code{stdout}.
4008 If the @code{cdr} of a node is a symbol whose function definition is
4009 non-@code{nil}, then that encoding can be handled internally. The function
4010 is called with 2 arguments, buffer positions bounding the region to be
4011 decoded. The function should completely replace that region with the
4012 unencoded information.
4014 Currently supported transfer encodings are: base64, x-gzip, 7bit, 8bit,
4015 binary, x-compress, x-hqx, and quoted-printable.
4017 @item url-uncompressor-alist
4018 @vindex url-uncompressor-alist
4019 An assoc list of file extensions and the appropriate uncompression
4020 programs for each. This is used to build the Accept-encoding header for
4021 @sc{http}/1.0 requests.
4023 @item w3-do-scripting
4024 @vindex w3-do-scripting
4025 If this is non-@code{nil} then Emacs/W3 will do clien-side scripting.
4026 This is @code{nil} by default.
4028 @item url-external-retrieval-program, url-external-retrieval-args
4029 @vindex url-external-retrieval-program
4030 @vindex url-external-retrieval-args
4031 @c gdj1: Find out what this means.
4032 @code{url-external-retrieval-program} names the external program that is
4033 run to retrieve @sc{url}s. It is @file{www} by default.
4034 @code{url-external-retrieval-args} specifies the arguments that will be
4035 passed to it, @samp{("-source")} by default.
4037 @item w3-netscape-compatible-comments
4038 @vindex w3-netscape-compatible-comments
4039 Not everyone uses proper @sc{html} comments. To allow for the presence
4040 of lesser browsers, Emacs/W3 will honour the incorrect netscape-style
4041 comments (@samp{<! >}) if @code{w3-netscape-compatible-comments} is
4042 non-@code{nil}. This is @code{t} by default, but it shouldn't need to
4045 @item font-blink-interval
4046 @vindex font-blink-interval
4047 This controls how often blinks occur for text inside @samp{<blink>}
4048 tags. It is 0.5 seconds by default.
4050 @item url-inhibit-mime-parsing
4051 @vindex url-inhibit-mime-parsing
4052 This controls whether to parse @sc{mime} headers in a message. If it is
4053 @code{nil} then the headers are parsed and deleted.
4055 @item url-mime-language-string
4056 @vindex url-mime-language-string
4057 This is used to set the contents of the @samp{Accept-language:} field in
4058 @sc{http/1.0} requests. If it is @code{nil} then the field isn't added
4059 and the server's default language version is retrieved, if it is
4060 @code{*} then the first available langauge version is retrieved. If it
4061 is a string, then it should be the desired language.
4062 @c gdj1: find out how http/1.0 differs from http/1.1 here.
4064 @item url-multiple-p
4065 @vindex url-multiple-p
4066 If this is non-@code{nil} then multiple queries are possible through
4067 @file{ *URL-<i>*} buffers.
4069 @item url-personal-mail-address
4070 @vindex url-personal-mail-address
4071 @code{url-personal-mail-address} contains your full email address. This
4072 is sent in the @sc{from} field in an @sc{http/1.0} request, but
4073 @ref{Security} for how to prevent this. If @code{nil} (the default),
4074 then it will be set to @code{user-mail-address} if non-@code{nil}, else
4075 it will be @code{(user-real-login-name)} at @code{(system-name)}.
4077 @item url-temporary-directory, w3-temporary-directory
4078 @vindex url-temporary-directory
4079 @vindex w3-temporary-directory
4080 @code{url-temporary-directory} and @code{w3-temporary-directory} control
4081 where temporary files are placed. If @samp{TMPDIR} is set then they
4082 default to that, otherwise @file{/tmp}.
4084 @item w3-documentation-root
4085 @vindex w3-documentation-root
4086 This specifies the location of the Emacs/W3 documentation, it
4087 @emph{must} end in a slash.
4089 @item w3-popup-menu-on-mouse-3
4090 @vindex w3-popup-menu-on-mouse-3
4091 If you like context-sensitive menus then you're bound to like
4092 @code{w3-popup-menu-on-mouse-3}. If non-@code{nil} (the default) then
4093 Emacs/W3 will bind mouse-3 to provide context-sensitive menus. This
4094 might not work at the moment. If @code{w3-popup-menu-on-mouse-3} is
4095 @code{nil}, then Emacs/W3 will not change the binding of mouse-3.
4097 @item w3-track-mouse
4098 @vindex w3-track-mouse
4099 If @code{w3-track-mouse} is non-@code{nil} (the default) then Emacs/W3
4100 will display the @sc{url} under the mouse in the echo-area.
4103 @vindex w3-use-menus
4104 If @code{w3-use-menus} is @code{nil} then Emacs/W3 will not provide a
4105 menu interface. If it is @samp{1}, then Emacs/W3 will add a @samp{W3}
4106 item to the Emacs menubar. If it is a list then Emacs/W3 will add its
4107 own menubar. The following symbols may appear in the list to control
4108 what Emacs/W3 puts in its menubar.
4111 A list of file related commands
4113 Various standard editing commands (copy/paste)
4115 Controlling various things about the document view
4119 Bookmark / hotlist control
4123 The standard buffers menu
4125 A toggle button to switch back to normal emacs menus
4127 Control style information and who gets to set what
4129 Various search engines
4133 This may appear once in the list. All menus after this will be
4134 displayed flush right.
4139 @node More Help, Future Directions, Advanced Features, Top
4141 @cindex Relevant Newsgroups
4144 For more help on Emacs/W3, please send me mail
4145 (@i{wmperry+w3@@cs.indiana.edu}). Several discussion lists have also been
4146 created for Emacs/W3. To subscribe, send mail to
4147 @i{majordomo@@indiana.edu}, with the body of the message 'subscribe
4148 @var{listname} @var{<email addres>}'. All other mail should go to
4149 @i{<listname>@@indiana.edu}.
4154 w3-announce -- this list is for anyone interested in Emacs/W3, and
4155 should in general only be used by me. The gnu.emacs.sources newsgroup
4156 and a few other mailing lists are included on this. Please only use
4157 this list for major package releases related to Emacs/W3.
4158 (@i{www-announce@@w3.org} is included on this list).
4160 w3-beta -- this list is for beta testers of Emacs/W3. These brave souls test
4161 out not-quite stable code.
4163 w3-dev -- a list consisting of myself and a few other people who are
4164 interested in the internals of Emacs/W3, and doing active development work.
4165 Pretty dead right now, but I hope it will grow.
4168 For help on the World Wide Web in general, please refer to the
4169 comp.infosystems.www.* newsgroups. There are also several discussion
4170 lists concerning the Web. Send mail to @i{<listname>-request@@w3.org}
4171 with a subject line of 'subscribe <listname>'. All mail should go to
4172 @i{<listname>@@w3.org}. Administrative mail should go to
4173 @i{www-admin@@w3.org}. The lists are:
4178 www-talk -- for general discussion of the World Wide Web, where its
4179 going, new features, etc. All the major developers are subscribed to
4182 www-announce -- for announcements concerning the World Wide Web. Server
4183 changes, new servers, new software, etc.
4186 As a last resort, mail me. I'll try to answer as quickly as I can.
4188 @node Future Directions, Reporting Bugs, More Help, Top
4189 @chapter Future Directions
4190 Changes are constantly being made to the Emacs browser (hopefully all
4191 for the better). This is a list of the things that are being worked on
4197 need to support HTTP/0.9 (http://c2.com:8080) responses
4199 /etc/mailcap cannot overide builtin mm-mime-data stuff?
4201 try to protect people from using '~' in file URLs
4203 keystrokes entered while in w3-pause self-insert under XEmacs --- the
4204 loop around dispatch-event needs to be smarter about what it
4207 border-color can have multiple color specifications, but we
4208 currently choke with 'args out of range' when we see this.
4210 widget appears to be stealing button3 to mean 'activate' --- this is
4211 bogus! We lose all context-sensitive menus because of this.
4213 We still seem to be growing the line size under Emacs 19.x/20.x
4215 It would be really nice if w3 buffers were put into w3-mode as soon
4216 as they were created. Then if the rendering craps out somehow then
4217 the buffer could be browsed such as it was. Ideally, links and
4218 widgets would be functional.
4220 document how to translate Netscape foo.pac files to emacs lisp
4222 Should we stop using reporter.el?
4228 background colors are not heeded on table rows (<tr>). Same
4229 properties on individual cells or the table as a whole work fine.
4231 <br> in <dd> hosed --- margins in general tend to be too big sometimes.
4233 client side imagemaps have to be in the same buffer (actually in the
4234 smae buffer, _BEFORE_ the usemap directive on an image) --- fix to be
4235 able to use imagemaps in different files, any position, etc, etc.
4241 cache a formatted version of documents, with enough info to recreate
4242 the widgets in them.
4244 w3-preview-region command
4246 LDAP support (XEmacs)
4248 New proxy type for sending requests via mail to a mail->web->mail gateway.
4250 Emacspeak Interaction
4254 some way of specifying in a stylesheet whether certain text is
4255 inaudible. use the 'inaudible text property for this.
4257 Full Aural-CSS support
4261 more sophisticated filling algorithm. I'm not sure exactly what
4262 would be sufficient but breaking lines after punctuation seems like
4263 it would solve most of the problem.
4265 When fetching images for viewing (not inlining), W3 should at least
4266 have an option of displaying it inline, ala Netscape.
4268 Widget library merging
4272 Write a font selection widget
4274 Write a voice selection widget
4276 Write a mailcap entry widget
4280 Custom library merging
4282 @item Add custom support for MM
4289 Abstract out current support
4291 Do something similar to GNUS 'backends' to provide easy way to add new
4292 bookmark formats, etc.
4296 Write a new major mode for handling CSS style sheets
4303 Emacspeak Integration
4307 Need option to turn off table rendering and print it out as a
4308 table that is viewable with emacspeak-table-ui.el
4312 Write a text/xml parser
4314 Completely rewrite display code again
4318 Abstract everything out to follow parse->flow objects->render model
4320 Base all stylesheet stuff off of DSSSL
4324 New rendering backends
4328 Native postscript output
4341 implement <spacer> from netscape 3.0b5
4343 reimplement w3-show-headers
4345 Handle math environment using the calc library
4347 Better integration with the parser
4352 @node Reporting Bugs, Dealing with Firewalls, Future Directions, Top
4353 @appendix Reporting Bugs
4354 @cindex Reporting Bugs
4356 @cindex Contacting the author
4358 If any bugs are discovered in Emacs/W3, please report them to the
4359 mailing list @t{w3-beta@@xemacs.org} --- this is where the brave souls
4360 who beta test the latest versions of Emacs/W3 reside, and are generally
4361 very responsive to bug reports.
4363 @findex w3-submit-bug
4364 Please make sure to use the bug submission feature of Emacs/W3, so that
4365 all relevant information will be sent along with your bug report. By
4366 default this is bound to the `@key{w}' key when in an Emacs/W3 buffer,
4367 or you can use @key{M-x w3-submit-bug} from anywhere within Emacs.
4369 For problems that are causing emacs to signal and error, please send a
4370 backtrace. You can get a backtrace by @kbd{M-x setvariable RET
4371 debug-on-error RET t RET}, and then reproduce the error.
4373 If the problem is visual, please capture a copy of the output and mail
4374 it along with the bug report (preferably as a MIME attachment, but
4375 anything will do). You can use the @code{xwd} program under X-windows
4376 for this, or @key{Alt-PrintScreen} under Windows 95/NT. Sorry, but I
4377 don't remember what the magic incarnation is for doing a screen dump
4378 under NeXTstep or OS/2.
4380 If the problem is actually causing Emacs to crash, then you will need to
4381 also mail the maintainers of the various Emacs distributions with the
4382 bug. Please use the @t{gnu.emacs.bug} newgroup for reporting bugs with
4383 GNU Emacs 19, and @t{comp.emacs.xemacs} for reporting bugs with XEmacs
4384 19 or XEmacs 20. I am actively involved with the beta testing of the
4385 latest versions of both branches of Emacs, and if I can reproduce the
4386 problem, I will do my best to see it gets fixed in the next release.
4388 It is also important to always maintain as much context as possible in
4389 your responses. I get so much email from my various Emacs-activities
4390 and work, that I cannot remember everything. If you send a bug report,
4391 and I send you a reply, and you reply with 'no that didn't work', then
4392 odds are I will have no clue what didn't work, much less what that was
4393 trying to fix in the first place. It will be much quicker and less
4394 painful if I don't have to waste a round-trip email exchange saying
4395 'what are you talking about'.
4397 @node Dealing with Firewalls, Proxy Gateways, Reporting Bugs, Top
4398 @appendix Dealing with Firewalls
4399 By default, Emacs can support standard @sc{tcp}/@sc{ip} network
4400 connections on almost all the platforms it runs on (Unix, @sc{vms},
4401 Windows, etc). However, there are several situations where it is not
4407 It is becoming more and more common to be behind a firewall or some
4408 other system that restricts your outbound network activity, especially
4409 if you are like me and away from the wonderful world of academia.
4410 Emacs/W3 has several different methods to get around firewalls (not to
4411 worry though --- none of them should get you in trouble with the local
4412 @sc{mis} department.)
4414 @item Emacs cannot resolve hostnames.
4415 @cindex Faulty hostname resolvers
4416 @cindex Broken SunOS libc
4417 @cindex Hostname resolution
4418 This happens quite often on SunOS workstations and some ULTRIX machines.
4419 Some C libraries do not include the hostname resolver routines in their
4420 static libraries. If Emacs was linked statically, and was not linked
4421 with the resolver libraries, it wil not be able to get to any machines
4422 off the local network. This is characterized by being able to reach
4423 someplace with a raw ip number, but not its hostname
4424 (@url{http://129.79.254.191/} works, but
4425 @url{http://www.cs.indiana.edu/} doesn't).
4427 The best solution for this problem is to recompile Emacs, making sure to
4428 either link dynamically (if available on your operating system), or
4429 include the @file{-lresolv}.
4431 @cindex url-gateway-broken-resolution
4432 If you do not have the disk space or the appropriate permissions to
4433 recompile Emacs, another alternative is using the @file{nslookup}
4434 program to do hostname resolution. To turn this on, set the variable
4435 @code{url-gateway-broken-resolution} in your @file{~/.emacs} file. This
4436 runs the program specified by @code{url-gateway-nslookup-program} (by
4437 default "@code{nslookup}" to do hostname resolution. This program should
4438 expect a single argument on the command line --- the hostname to resolve,
4439 and should produce output similar to the standard Unix @file{nslookup}
4443 Name: www.cs.indiana.ed
4444 Address: 129.79.254.191
4448 @item Using @sc{term} (or @sc{term}-like) Networking Software
4449 @sc{term} @footnote{@sc{term} is a user-level protocol for emulating
4450 @sc{ip} over a serial line. More information is available at
4451 @url{ftp://sunsite.unc.edu/pub/Linux/apps/comm/term}} for slip-like
4452 access to the internet.
4454 @sc{note}: XEmacs and Emacs 19.22 or later have patches to enable native
4455 @sc{term} networking. To enable it, @code{#define TERM} in the
4456 appropriate s/*.h file for the operating system, then change the
4457 @code{SYSTEM_LIBS} definition to include the @file{termnet} library that
4458 comes with the latest versions of @sc{term}.
4460 If you run into any problems with the native @sc{term} networking
4461 support in Emacs or XEmacs, please let @t{wmperry+w3@@cs.indiana.edu} know,
4462 as he is responsible for the original support.
4465 @vindex url-gateway-local-host-regexp
4466 Emacs/W3 has support for using the gateway mechanism for certain
4467 domains, and directly connecting to others. The variable
4468 @code{url-gateway-local-host-regexp} controls this behaviour. This is a
4469 regular expression @footnote{Please see the full Emacs distribution for
4470 a description of regular expressions} that matches local hosts that do
4471 not require the use of a gateway. If @code{nil}, then all connections
4472 are made through the gateway.
4474 @vindex url-gateway-method
4475 Emacs/W3 supports several methods of getting around gateways. The
4476 variable @code{url-gateway-method} controls which of these methods is
4477 used. This variable can have several values (use these as symbol names,
4478 not strings), ie: @samp{(setq url-gateway-method 'telnet)}. Possible
4483 Use this method if you must first telnet and log into a gateway host,
4484 and then run telnet from that host to connect to outside machines.
4486 @vindex url-gateway-telnet-host
4487 @vindex url-gateway-telnet-parameters
4488 @vindex url-gateway-telnet-password-prompt
4489 @vindex url-gateway-telnet-user-name
4490 @vindex url-gateway-prompt-pattern
4491 @vindex url-gateway-telnet-login-prompt
4492 @vindex url-gateway-telnet-password
4494 @item url-gateway-telnet-host
4495 The gateway host to telnet to. Once logged in there, you then telnet
4496 out to the hosts you want to connect to.
4497 @item url-gateway-telnet-parameters
4498 This should be a list of parameters to pass to the @file{telnet} program.
4499 @item url-gateway-telnet-password-prompt
4500 This is a regular expression that matches the password prompt when
4502 @item url-gateway-telnet-login-prompt
4503 This is a regular expression that matches the username prompt when
4505 @item url-gateway-telnet-user-name
4506 The username to log in with.
4507 @item url-gateway-telnet-password
4508 This is the password to send when logging in.
4509 @item url-gateway-prompt-pattern
4510 This is a regular expression that matches the shell prompt.
4515 This method is identical to the @code{telnet} method, but uses
4516 @file{rlogin} to log into the remote machine without having to send the
4517 username and password over the wire every time.
4519 @vindex url-gateway-rlogin-host
4520 @vindex url-gateway-rlogin-parameters
4521 @vindex url-gateway-rlogin-user-name
4522 @vindex url-gateway-prompt-pattern
4524 @item url-gateway-rlogin-host
4525 Host to @samp{rlogin} to before telnetting out.
4526 @item url-gateway-rlogin-parameters
4527 Parametres to pass to @samp{rsh}.
4528 @item url-gateway-rlogin-user-name
4529 User name to use when logging in to the gateway.
4530 @item url-gateway-prompt-pattern
4531 This is a regular expression that matches the shell prompt.
4535 Masanobu UMEDA (@i{umerin@@mse.kyutech.ac.jp}) has written a very small
4536 application that you can run in a subprocess to do the network
4540 Use if the firewall has a @sc{socks} gateway running on it. @sc{socks}
4541 v5 protocol is defined in @sc{rfc1928}.
4543 @vindex socks-password
4544 @vindex socks-username
4545 @vindex socks-timeout
4546 @vindex socks-server
4547 @vindex socks-server-aliases
4548 @vindex socks-network-aliases
4549 @vindex socks-redirection-rules
4550 @vindex socks-nslookup-program
4552 @item socks-password
4553 If this is @code{nil} then you will be asked for the passward, otherwise
4554 it will be used as the password for authenticating you to the @sc{socks}
4557 @item socks-username
4558 This is the username to use when authenticating yourself to the
4559 @sc{socks} server. By default this is your login name
4562 This controls how long, in seconds, Emacs/W3 will wait for responses from the
4563 @sc{socks} server; it is 5 by default.
4566 Thiss the default server, it take the form (@samp{"Default server"}
4567 @var{server} @var{port} @var{version}) where @var{version} can be either
4570 @item socks-server-aliases
4571 This a list of server aliases. It is a list of aliases of the form
4572 @code{(alias hostname port version)}.
4574 @item socks-network-aliases
4575 This a list of network aliases. Each entry in the list takes the form
4576 @code{(alias (network))} where @var{alias} is a string that names the
4577 @var{network}. The networks can contain a pair (not a dotted pair) of
4578 @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip}
4579 address and a netmask, a domain name or a unique hostname or @sc{ip}
4582 @item socks-redirection-rules
4583 This a list of redirection rules. Each rule take the form
4584 @code{(Destination network Connection type)} where @var{Destination
4585 network} is a network alias from @code{socks-network-aliases} and
4586 @var{Connection type} can be @code{nil} in which case a direct
4587 connection is used, or it can be an alias from
4588 @code{socks-server-aliases} in which case that server is used as a
4591 @item socks-nslookup-program
4592 This the @samp{nslookup} program. It is @samp{nslookup} by default.
4597 @c This probably shouldn't be documented
4600 This means that Emacs/W3 should use the builtin networking code of
4601 Emacs. This should be used only if there is no firewall, or the Emacs
4602 source has already been hacked to get around the firewall.
4605 Emacs/W3 should now be able to get outside the local network. If none
4606 of this makes sense, its probably my fault. Please check with the
4607 network administrators to see if they have a program that does most of
4608 this already, since somebody somewhere at the company has probably been
4609 through something similar to this before, and would be much more
4610 helpful/knowledgeable about the local setup than I would be. But feel
4611 free to mail me as a last resort.
4613 @node Proxy Gateways, Installing SSL, Dealing with Firewalls, Top
4614 @appendix Proxy Gateways
4615 @vindex url-proxy-services
4616 @cindex Proxy Servers
4618 @cindex Proxies, environment variables
4621 In late January 1993, Kevin Altis and Lou Montulli proposed and
4622 implemented a new proxy service. This service requires the use of
4623 environment variables to specify a gateway server/port # to send
4624 protocol requests to. Each protocol (@sc{http}, @sc{wais}, gopher,
4625 @sc{ftp}, etc.) can have a different gateway server. The environment
4626 variables are @code{PROTOCOL}_proxy, where @code{PROTOCOL} is one of the
4627 supported network protocols (gopher, file, @sc{http}, @sc{ftp}, etc.)
4630 @cindex Proxies, exclusion lists
4632 For companies with internal intranets, it will usually be helpful to
4633 define a list of hosts that should be contacted directly, @b{not} sent
4634 through the proxy. The @code{NO_PROXY} environment variable controls
4635 what hosts are able to be contacted directly. This should be a comma
4636 separated list of hostnames, domain names, or a mixture of both.
4637 Asterisks can be used as a wildcard. For example:
4640 NO_PROXY=*.aventail.com,home.com,*.seanet.com
4643 tells Emacs/W3 to contact all machines in the @b{aventail.com} and
4644 @b{seanet.com} domains directly, as well as the machine named
4647 @vindex url-proxy-services
4648 @cindex Proxies, setting from lisp
4649 For those adventurous souls who enjoy writing regular expressions, all
4650 the proxy settings can be manipulated from Emacs-Lisp. The variable
4651 @code{url-proxy-services} controls this. This is an assoc list, keyed
4652 on the protocol type (@sc{http}, gopher, etc) in all lowercase. The
4653 @code{cdr} of each entry should be the @sc{address} of the proxy server
4654 to contact, followed by ":" and the port number to use. In the case of
4655 the special "no_proxy" entry, it should be a regular expression that
4656 matches any hostnames that should be contacted directly.
4659 (setq url-proxy-services
4660 '(("http" . "proxy.aventail.com:80")
4661 ("no_proxy" . "^.*\\(aventail\\|seanet\\)\.com")))
4664 @node Installing SSL, Mailcap Files, Proxy Gateways, Top
4665 @appendix Installing SSL
4666 @cindex HTTP/1.0 Authentication
4667 @cindex Secure Sockets Layer
4669 @cindex Gag Puke Retch
4670 @cindex Exportability
4671 @cindex Export Restrictions
4672 In order to use SSL in Emacs/W3, an implementation of SSL is necessary.
4673 Emacs/W3 is configued to work out of the box with SSLeay 0.6.6 or later.
4674 For best results, you should apply a patch that makes the SSLeay client
4675 much quieter about what it reports.
4677 You can download SSLeay from
4678 @url{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/}
4680 The following variables control how the external program is invoked.
4683 @item ssl-program-name
4684 @vindex ssl-program-name
4685 The name of the program to run, as a string.
4688 (setq ssl-program-name "s_client")
4691 @item ssl-program-arguments
4692 @vindex ssl-program-arguments
4693 This should be used if your SSL program needs command line switches to
4694 specify any behaviour (certificate file locations, etc). This is a list
4695 of strings and symbols.
4697 The special symbols 'host and 'port may be used in the list of arguments
4698 and will be replaced with the hostname and service/port that will be
4702 (setq ssl-program-arguments '("-host" host
4705 "-CApath /usr/local/ssl/certs"))
4708 The default is ("-host" host "-port" service "-verify"
4709 @var{ssl-certificate-verification-policy} -CApath @var{ssl-certificate-directory}).
4711 @vindex ssl-certificate-directory
4712 @code{ssl-certificate-directory} is the directory in which @sc{ca}
4713 certificates are stored. It is
4714 @code{@var{w3-configuration-directory}/cert} by default.
4716 @vindex ssl-rehash-program-name
4717 @code{ssl-rehash-program-name} is the program that is run after adding a
4718 certificate to the @code{ssl-certificate-directory} directory. It is
4719 run with the directory name as an argument and defaults to @code{c_rehash}.
4721 @vindex ssl-view-certificate-program-name
4722 @vindex ssl-view-certificate-program-arguments
4723 @code{ssl-view-certificate-program-name} names the program that can
4724 produce a human-readable view of a certificate. It is @code{x509} by
4725 default and is called with the arguments listed in
4726 @code{ssl-view-certificate-program-arguments} which is @code{("text"
4727 "-inform" "DER")} by default.
4729 @vindex ssl-certificate-directory-style
4730 @code{ssl-certificate-directory-style} specifies the type of certificate
4731 database to use. It's default (and at the moment, only possible value)
4732 is @code{ssleay} which specifies a directory or pem encoded certificates
4735 @vindex ssl-certificate-verification-policy
4736 You can decide how high up the chain of certificates should
4737 be verified by setting @code{ssl-certificate-verification-policy}. Possible
4743 Verification required
4745 Reject connection if verification fails
4747 SSL_VERIFY_CLIENT_ONCE
4751 @node Mailcap Files, Temporary, Installing SSL, Top
4752 @appendix Mailcap Files
4753 NCSA Mosaic and almost all other WWW browsers rely on a separate file
4754 for mapping MIME types to external viewing programs. This takes some of
4755 the burden off of browser developers, so each browser does not have to
4756 support all image formats, or postscript, etc. Instead of having the
4757 users of Emacs/W3 duplicate this in lisp, this file can be parsed using
4758 the @code{mm-parse-mailcaps} function. This function is called each
4759 time Emacs/W3 is loaded. It tries to locate mimetype files in several
4760 places. If the environment variable @code{MAILCAPS} is nonempty, then
4761 this is assumed to specify a UNIX-like path of mimetype files (this is a
4762 colon separated string of pathnames). If the @code{MAILCAPS}
4763 environment variable is empty, then Emacs/W3 looks for these
4772 @file{/usr/etc/mailcap}
4774 @file{/usr/local/etc/mailcap}
4777 This format of this file is specified in RFC 1343, but a brief synopsis
4778 follows (this is taken verbatim from sections of RFC 1343).
4780 Each mailcap file consists of a set of entries that describe the proper
4781 handling of one media type at the local site. For example, one line
4782 might tell how to display a message in Group III fax format. A mailcap
4783 file consists of a sequence of such individual entries, separated by
4784 newlines (according to the operating system's newline
4785 conventions). Blank lines and lines that start with the "#" character
4786 (ASCII 35) are considered comments, and are ignored. Long entries may
4787 be continued on multiple lines if each non-terminal line ends with a
4788 backslash character ('\', ASCII 92), in which case the multiple lines
4789 are to be treated as a single mailcap entry. Note that for such
4790 "continued" lines, the backslash must be the last character on the line
4793 Each mailcap entry consists of a number of fields, separated by
4794 semi-colons. The first two fields are required, and must occur in the
4795 specified order. The remaining fields are optional, and may appear in
4798 The first field is the content-type, which indicates the type of data
4799 this mailcap entry describes how to handle. It is to be matched against
4800 the type/subtype specification in the "Content-Type" header field of an
4801 Internet mail message. If the subtype is specified as "*", it is
4802 intended to match all subtypes of the named content-type.
4804 The second field, view-command, is a specification of how the message or
4805 body part can be viewed at the local site. Although the syntax of this
4806 field is fully specified, the semantics of program execution are
4807 necessarily somewhat operating system dependent.
4809 The optional fields, which may be given in any order, are as follows:
4812 The "compose" field may be used to specify a program that can be used to
4813 compose a new body or body part in the given format. Its intended use
4814 is to support mail composing agents that support the composition of
4815 multiple types of mail using external composing agents. As with the
4816 view- command, the semantics of program execution are operating system
4817 dependent. The result of the composing program may be data that is not
4818 yet suitable for mail transport---that is, a Content-Transfer-Encoding
4819 may need to be applied to the data.
4821 The "composetyped" field is similar to the "compose" field, but is to be
4822 used when the composing program needs to specify the Content-type header
4823 field to be applied to the composed data. The "compose" field is
4824 simpler, and is preferred for use with existing (non-mail-oriented)
4825 programs for composing data in a given format. The "composetyped" field
4826 is necessary when the Content-type information must include auxilliary
4827 parameters, and the composition program must then know enough about mail
4828 formats to produce output that includes the mail type
4831 The "edit" field may be used to specify a program that can be used to
4832 edit a body or body part in the given format. In many cases, it may be
4833 identical in content to the "compose" field, and shares the
4834 operating-system dependent semantics for program execution.
4836 The "print" field may be used to specify a program that can be used to
4837 print a message or body part in the given format. As with the
4838 view-command, the semantics of program execution are operating system
4841 The "test" field may be used to test some external condition (e.g. the
4842 machine architecture, or the window system in use) to determine whether
4843 or not the mailcap line applies. It specifies a program to be run to
4844 test some condition. The semantics of execution and of the value
4845 returned by the test program are operating system dependent. If the
4846 test fails, a subsequent mailcap entry should be sought. Multiple test
4847 fields are not permitted---since a test can call a program, it can
4848 already be arbitrarily complex.
4850 The "needsterminal" field indicates that the view-command must be run on
4851 an interactive terminal. This is needed to inform window-oriented user
4852 agents that an interactive terminal is needed. (The decision is not
4853 left exclusively to the view-command because in some circumstances it
4854 may not be possible for such programs to tell whether or not they are on
4855 interactive terminals.) The needsterminal command should be assumed to
4856 apply to the compose and edit commands, too, if they exist. Note that
4857 this is NOT a test---it is a requirement for the environment in which
4858 the program will be executed, and should typically cause the creation of
4859 a terminal window when not executed on either a real terminal or a
4862 The "copiousoutput" field indicates that the output from the
4863 view-command will be an extended stream of output, and is to be
4864 interpreted as advice to the UA (User Agent mail- reading program) that
4865 the output should be either paged or made scrollable. Note that it is
4866 probably a mistake if needsterminal and copiousoutput are both
4869 The "description" field simply provides a textual description,
4870 optionally quoted, that describes the type of data, to be used
4871 optionally by mail readers that wish to describe the data before
4872 offering to display it.
4874 The "x11-bitmap" field names a file, in X11 bitmap (xbm) format, which
4875 points to an appropriate icon to be used to visually denote the presence
4876 of this kind of data.
4878 Any other fields beginning with "x-" may be included for local or
4879 mailer-specific extensions of this format. Implementations should
4880 simply ignore all such unrecognized fields to permit such extensions,
4881 some of which might be standardized in a future version of this
4885 @node Temporary, General Index, Mailcap Files, Top
4886 @comment node-name, next, previous, upGeneral Index
4888 @c @appendix Temporary
4890 @c @subsection base64
4893 @c gdj1: What is DSSSL?
4895 @c @vindex font-maximum-slippage
4896 @c @item font-maximum-slippage
4897 @c This specifies how much a font can vary from the desired size. It is a
4898 @c string and the default value is @samp{1pt}.
4900 @c @vindex font-family-mappings
4901 @c @item font-family-mappings
4902 @c This is an alist that tells Emacs/W3 what fonts correspond to the
4903 @c @sc{html} font families. The format is @code{(@var{html_family}
4904 @c . (@var{fonts}))}.
4908 @node General Index, Key Index, Temporary, Top
4909 @appendix General Index
4911 @node Key Index, , General Index, Top