\input texinfo
@c
@c Please note that this file uses some constructs not supported by earlier
@c versions of TeX-info. You must be running one of the newer TeX-info
@c releases (I currently use version 3.9 from ftp://prep.ai.mit.edu/pub/gnu/)
@c
@c Please do not send in bug reports about not being able to format the
@c document with 'makeinfo' or 'tex', just upgrade your installation.
@c
@c Info formatted files are provided in the distribution, and you can
@c retrieve dvi, postscript, and PDF versions from the web site or FTP
@c site: http://www.cs.indiana.edu/elisp/w3/docs.html
@c
@setfilename w3.info
@settitle Emacs/W3 v4.0pre.47 User's Manual
@iftex
@c @finalout
@end iftex
@c @setchapternewpage odd
@c @smallbook
@tex
\overfullrule=0pt
%\global\baselineskip 30pt % for printing in double space
@end tex
@synindex cp fn
@synindex vr fn
@dircategory World Wide Web
@dircategory GNU Emacs Lisp
@direntry
* Emacs/W3: (w3). Emacs/W3 World Wide Web browser.
@end direntry
@copying
@end copying
Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1999, 2000
Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual''. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
@end quotation
@c
@titlepage
@sp 6
@center @titlefont{Emacs/W3}
@center @titlefont{User's Manual}
@sp 4
@center Third Edition, Emacs/W3 Version 4.0
@sp 1
@center November 1999
@sp 5
@center William M. Perry
@center @i{wmperry@@cs.indiana.edu}
@end titlepage
@page
@node Top, Getting Started, (dir), (dir)
@top W3
Users can browse the World Wide Web from within Emacs by using Emacs/W3.
All of the widely used (and even some not very widely used) @sc{url}
schemes are supported, and it is very easy to add new methods as the
need arises.
Emacs/W3 provides some core functionality that can be readily re-used
from any program in Emacs. Users and other package writers are
encouraged to @i{Web-enable} their applications and daily work routines
with the library.
Emacs/W3 is completely customizable, both from Emacs-Lisp and from
stylesheets @xref{Stylesheets}. If there is any aspect of Emacs/W3 that
cannot be modified to your satisfaction, please send mail to the
@t{w3-beta@@xemacs.org} mailing list with any suggestions.
@xref{Reporting Bugs}.
This manual corresponds to Emacs/W3 $State: Exp $
@menu
* Getting Started:: Getting up and running with Emacs/W3
* Basic Usage:: Basic movement and usage of Emacs/W3.
* Compatibility:: Explanation of compatibility with
other browsers.
* Display Variables:: How to control Emacs/W3's look.
* Stylesheets:: How to control the look of web pages
* Supported URLs:: What @sc{url} schemes are supported.
* MIME Support:: Support for @sc{mime}
* Security:: Various security methods supported
* Cookies:: Emacs/W3 and cookies.
* Non-Unix Operating Systems:: Special considerations necessary to get
up and running correctly under non-unix
OS's.
* Speech Integration:: Outputting to a speech synthesizer.
* Advanced Features:: Some of the more arcane features.
* More Help:: How to get more help---mailing lists,
newsgroups, etc.
* Future Directions:: Plans for future revisions
Appendices:
* Reporting Bugs:: How to report a bug in Emacs/W3.
* Dealing with Firewalls:: How to get around your firewall.
* Proxy Gateways:: Using a proxy gateway with Emacs/W3.
* Installing SSL:: Turning on @sc{ssl} support.
* Mailcap Files:: An explanation of Mailcap files.
* Temporary::
Indices:
* General Index:: General Index.
* Key Index:: Menus of command keys and their references.
@end menu
@node Getting Started, Basic Usage, Top, Top
@chapter Getting Started
@cindex Clueless in Seattle
@cindex Getting Started
@kindex M-x w3
@vindex w3-default-homepage
@findex w3
If installed correctly, starting Emacs/W3 is quite painless. Just type
@kbd{M-x w3} in a running Emacs session. This will retrieve the default
page that has been configured --- by default the documentation for
Emacs/W3 at Indiana University. The default homepage is specified by
the @code{w3-default-homepage} variable.
If the default page is not retrieved correctly at startup, you will have
to do some customization.
Once started, you can use the mouse and the menu or use the following
key commands (for more commands and more detail, @pxref{Basic Usage, ,
Basic Usage}).
@table @asis
@item move forward
press the space bar,
@item move backwards
press the backspace key,
@item move to the next HTML reference on the page
press the @kbd{TAB} key,
@item move to the previous HTML reference on the page
press the @kbd{SHIFT} and @kbd{TAB} keys at the same time. If this does
not work (some text terminals cannot distinguish between @kbd{TAB} and
@kbd{SHIFT-TAB}, pressing the @kbd{ALT} and @kbd{TAB} keys should also
work.
@item follow a link
put the cursor over it
and press the @kbd{RETURN} key, or @*
click the left mouse button on it,
@item fetch a @sc{url}
press the @kbd{Control} and @kbd{o} keys at the same time,@*
type the @sc{url}, and then press the @kbd{RETURN} key,
@item return to the last URL you were at
press the @kbd{l} key,
@item quit W3 mode
press the @kbd{q} key.
@end table
@menu
* Downloading:: Where to download Emacs/W3.
* Building and Installing:: Compiling and installing from source.
* Startup Files:: What is where, and why.
@end menu
@node Downloading, Building and Installing, Getting Started, Getting Started
@section Downloading
Emacs/W3 will work with Emacs 19.29 and later and XEmacs 19.14 and later,
but if you're using a 19.x Emacs then you will need to get the
latest custom and widget libraries.
@table @asis
@item Emacs
Available from the GNU archive @uref{ftp://prep.ai.mit.edu/pub/gnu} or
one of it's many mirrors.
@item XEmacs
Available from the XEmacs archive @uref{http://www.xemacs.org/} or one
of it's many mirrors.
@item Emacs/W3
@uref{http://www.cs.indiana.edu/elisp/w3/docs.html} is the main
distribution point for Emacs/W3.
@item Emacspeak
A speech synthesizer package for Emacs and XEmacs. More information is
available at
@uref{http://www.cs.cornell.edu/Info/People/raman/emacspeak/}
@end table
@node Building and Installing, Startup Files, Downloading, Getting Started
@section Building and Installing
Emacs/W3 uses GNU @samp{configure} (@pxref{Top, , ,configure}) to
control installation. configure will attempt to find what version of
Emacs you have and where it is installed. If it finds both Emacs and
XEmacs, then XEmacs is used (but see below for how to change this).
Apart from the usual options, the following options are accepted:
@table @samp
@item --with-xemacs
Use XEmacs.
@item --with-emacs
Use Emacs.
@item --with-lispdir=@var{dir}
Put lisp files (*.el and *.elc) in @var{dir}. If this is not specified,
and neither is @samp{--with-package-dir}, then the lisp files go into
@file{@var{EMACS}/site-lisp}.
@item --with-package-dir=@var{dir}
If using XEmacs, install Emacs/W3 as a package in @var{dir}. Please
note that this and the @samp{--prefix} argument are mutually exclusive.
@item --with-makeinfo=@var{makeinfo}
Use @var{makeinfo} to build info files from Texinfo files.
@samp{configure} will normally find makeinfo if it's available, you
should only need to specify this if it's not called makeinfo or if it
isn't in a directory in your @samp{PATH}.
@item --with-custom=@var{dir}
Use the custom package in @var{dir}. @samp{configure} will attempt to
find a suitable custom package, you should not need to specify this
yourself if the custom package is in Emacs's @code{load-path}.
@item --enable-site-install
Install Emacs/W3 for the site, rather than just yourself. This only
affects whether @samp{make dotemacs} affects @file{~/.emacs} or
@file{site-lisp/default.el}.
@end table
These are the most useful of the normal @samp{configure} options.
@table @samp
@item --prefix=@var{dir}
This is the top level directory and by default everything is installed
somewhere below this. This is @file{/usr/local} by default.
@item --infodir=@var{dir}
Where to put the info files. This is @file{@var{prefix}/info} by
default.
@item --data-dir=@var{dir}
Where to put date files (default stylesheets). This is @file{@var{prefix}/share} by
default unless @samp{--with-package-dir=@var{pack-dir}} was given in
which case they go into @file{@var{pack-dir}/etc/w3}.
@end table
The directory that the byte-compiled lisp files will be installed into
is controlled by the @samp{--prefix}, @samp{--with-package-dir} and
@samp{--with-lispdir} options. The directory for the info and data files is
likewise controlled by the @samp{--prefix}, @samp{--with-package-dir}
and @samp{--infodir} or @samp{--data-dir} options.
Normally these are the only things that need to be installed, they can
by compiled by @samp{make all}, or @samp{make w3} and @samp{make info}.
@samp{make install} will install the lisp, info and data files.
@samp{make all} in the @file{texi} directory will create the info files
and also dvi files. @sc{html} and postscript can be generated by @samp{make
html} and @samp{make ps} respectively.
@c gdj1: document the other targets, fast etc.?
@node Startup Files, , Building and Installing, Getting Started
@section Startup Files
@cindex Startup files
@cindex .w3
@vindex w3-configuration-directory
Emacs/W3 needs a directory for each user to store options, history and
the cache. @code{w3-configuration-directory} controls this directory,
which is @file{~/.w3} by default.
@subsection Emacs/W3 profile
@cindex profile
@vindex w3-default-configuration-file
Emacs/W3 keeps a file called @file{profile} in your configuration
directory that sets many variables. @strong{Warning}: this file will
overide any options that you set in your @file{.emacs}. You @emph{must} either
edit @file{profile} directly or use @code{w3-menu-save-options} to save
your settings.
If you prefer, you can set @code{w3-default-configuration-file} to
specify a different configuration file. This file does not need to be
dedicated to Emacs/W3 because Emacs/W3 will delimit its part of the file
so you can set this to @file{.emacs} if you want. However, while
Emacs/W3 will save it's options to the correct part of the file, it will
read (and execute) the entire file when starting.
@subsection Default stylesheets
@cindex Default stylesheet
@vindex w3-default-stylesheet
Emacs/W3 will look for style-sheets in @code{w3-configuration-directory}
as well as the site-wide directories. In particular it will look for
@file{dark.css} or @file{stylesheet-dark} if you're using a dark
background and @file{light.css} or @file{stylesheet-light} if you're
using a light background as well as @file{stylesheet} and
@file{default.css}. If @code{w3-default-stylesheet} is not @code{nil}
then the file that it names will be used as well. For more information,
@xref{Stylesheets}.
@subsection History
@cindex history
@vindex url-global-history-file
@vindex url-global-history-save-interval
@vindex url-keep-history
Emacs/W3 keeps a file called @file{history} in the configuration
directory. This is a list of all the links you have visited. You can
change the file where the history is stored by setting
@code{url-global-history-file} to the name of the file you'd prefer.
@xref{Global History}.
@subsection Hotlists
@vindex w3-hotlist-file
@dfn{Hotlists} (sometimes called bookmarks, but not to be confused with
Emacs's bookmarks) are a list of @sc{url}s. Emacs/W3 supports mosaic's
hotlist format which associates an alias with each @sc{url} ---
@xref{Hotlist Handling}.
@c gdj1:
@c --- and also the @sc{html} style hotlists used by
@c lynx and netscape.
@c And others?
The @code{w3-hotlist-file} variable specifies
the hotlist file. It defaults to @file{.mosaic-hotlist-default}.
@node Basic Usage, Compatibility, Getting Started, Top
@chapter Basic Usage
@cindex Basic Usage
@kindex space
@kindex backspace
@kindex return
@kindex tab
@kindex M-tab
Emacs/W3 is similar to the Info package all Emacs users hold near and
dear to their hearts (@xref{Top,,Info,info, The Info Manual}, for a
description of Info). Basically, @kbd{space} and @kbd{backspace}
control scrolling, and @kbd{return} or the middle mouse button follows a
hypertext link. The @kbd{tab} and @kbd{Meta-tab} keys maneuver around the
various links on the page.
@b{NOTE:} Starting with Emacs/W3 4.0, form entry areas in a page can be
typed directly into. This is one of the main differences in navigation
from version 2.0. If you are used to using the @kbd{f} and @kbd{b} keys
to navigate around a buffer, I suggest training yourself to always use
@kbd{tab} and @kbd{M-tab} --- it will save time and frustration on pages
with lots of form fields.
By default, hypertext links are surrounded by '[[' and ']]' on
non-graphic terminals (VT100, DOS window, etc.). On a graphics
terminal, the links are in shown in different colors.
For information on how to change this, @xref{Stylesheets}.
There are approximately 50 keys bound to special Emacs/W3 functions.
The basic rule of thumb regarding keybindings in Emacs/W3 is that a
lowercase key takes an action on the @b{current document}, and an
uppercase key takes an action on the document pointed to by the
hypertext link @b{under the cursor}.
There are several areas that the keybindings fall into: movement,
information, action, and miscellaneous.
@menu
* Movement:: Moving around in the buffer.
* Information:: Getting information about a document.
* Action:: Following links, printing, etc.
* Miscellaneous:: Everything else.
@end menu
@node Movement, Information, Basic Usage, Basic Usage
@section Movement
All the standard Emacs bindings for movement are still in effect, with a
few additions for convenience.
@table @kbd
@findex w3-scroll-up
@kindex space
@item space
Scroll downward in the buffer. With prefix arg, scroll down that many
screenfuls (@code{w3-scroll-up}).
@item M-space
@kindex M-space
@findex w3-next-document
Goes to next document.
@c gdj1: check
@item M-del
@kindex M-del
@findex w3-prev-document
Goes to previous document.
@c gdj1: check
@kindex backspace
@kindex C-?
@findex scroll-down
@item backspace, C-?
Scroll upward in the buffer. With prefix arg, scroll up that many
screenfuls (@code{scroll-down}).
@kindex <
@findex w3-start-of-document
@item <
Goes to the start of document (@code{w3-start-of-document}).
@kindex >
@findex w3-end-of-document
@item >
Goes to the end of document (@code{w3-end-of-document}).
@kindex b
@kindex Meta-tab
@findex w3-widget-backward
@item Meta-tab, Shift-tab, b
Attempts to move backward one link area in the current document
(@code{w3-widget-backward}). Signals an error if no previous links are
found.
@kindex f
@kindex tab
@kindex n
@findex w3-widget-forward
@item tab, f, n
Attempts to move forward one link area in the current document
(@code{w3-widget-forward}). Signals an error if no more links are
found.
@kindex B
@kindex HB
@findex w3-backward-in-history
@findex w3-history-backward
@item B, HB
Takes one step back along the path in the current history
(@code{w3-history-backward}). Has no effect if at the beginning of the
session history.
@kindex F
@kindex H F
@findex w3-forward-in-history
@findex w3-history-forward
@item F, HF
Takes one step forward along the path in the current history
(@code{w3-history-forward}). Has no effect if at the end of the session
history.
@kindex l
@findex w3-goto-last-buffer
@item l
Return to the last buffer shown before this buffer
(@code{w3-goto-last-buffer}).
@kindex q
@findex w3-quit
@item q
Kill this buffer (@code{w3-quit}).
@kindex Q, u
@findex w3-leave-buffer
@item Q, u
Bury this buffer, but don't kill it (@code{w3-leave-buffer}).
@end table
@node Information, Action, Movement, Basic Usage
@section Information
These functions relate information about one or more links on the
current document.
@table @kbd
@kindex v
@findex url-view-url
@item v
This shows the @sc{url} of the current document in the minibuffer
(@code{url-view-url}).
@kindex V
@findex w3-view-this-url
@item V
This shows the @sc{url} of the hypertext link under point in the
minibuffer (@code{w3-view-this-url}).
@kindex i
@findex w3-document-information
@item i
Shows miscellaneous information about the currently displayed document
(@code{w3-document-information}). This includes the @sc{url}, the last
modified date, @sc{mime} headers, the @sc{http} response code, and any
relationships to other documents. Any security information is also
displayed.
@kindex I
@findex w3-popup-info
@item I
Shows information about the @sc{url} at point (@code{w3-popup-info}).
@kindex s
@findex w3-source-document
@item s
This shows the @sc{html} source of the current document in a separate
buffer (@code{w3-source-document}). The buffer's name is based on the
document's @sc{url}.
@kindex S
@findex w3-source-document-at-point
@item S
Shows the @sc{html} source of the hypertext link under point in a
separate buffer (@code{w3-source-document-at-point}). The buffer's name
is based on the document's @sc{url}.
@kindex k
@findex w3-save-url
@item k
This stores the current document's @sc{url} in the kill ring, and also in the
current window-system's clipboard, if possible (@code{w3-save-url}).
@kindex K
@findex w3-save-this-url
@item K
Stores the @sc{url} of the document under point in the kill ring, and also in
the current window-system's clipboard, if possible (@code{w3-save-this-url}).
@end table
@node Action, Miscellaneous, Information, Basic Usage
@section Action
First, here are the keys and functions that bring up a new hypertext
page, usually creating a new buffer.
@table @kbd
@kindex m
@findex w3-complete-link
@item m
Choose a link from the current buffer and follow it
(@code{w3-complete-link}). A completing-read is done on all the links,
so @kbd{space} and @kbd{TAB} can be used for completion.
@kindex return
@findex w3-follow-link
@item return
Pressing return when over a hyperlink attempts to follow the link
under the cursor (@code{w3-follow-link}).
Pressing return when over a form input field can cause auto-submission
of the form. This is for Mosaic and Netscape compatibility. If there
is only one item in the form other than submit or reset buttons, then
the form will be submitted.
@kindex Middle Mouse Button
@findex w3-follow-mouse
@item Middle Mouse Button
Attempt to follow a hypertext link under the mouse cursor
(@code{w3-follow-mouse}). Clicking on a form input field will prompt in
the minibuffer for the data to insert into the input field. Type
checking is done, and the data is only entered into the form when data
of the correct type is entered (ie: cannot enter 44 for 'date' field,
etc).
@kindex Control Middle Mouse Button
@kindex Meta return
@findex w3-follow-inlined-image
@item Control Middle Mouse Button, Meta return
Tries to retrieve the inlined image that is under point
(@code{w3-follow-inlined-image}). It ignores any form entry areas or
hyperlinks, and blindly follows any inlined image. Useful for seeing
images that are meant to be used as hyperlinks when not on a terminal
capable of displaying graphics.
@kindex D
@findex w3-download-url-at-point
@item D
Download the @sc{url} at point (@code{w3-download-url-at-point}).
@kindex d
@findex w3-download-this-url
@item d
Download the current @sc{url} (@code{w3-download-this-url}).
@c @kindex G
@c @findex w3-show-graphics
@c @c @item G
@c gdj1: Bound to w3-show-graphics which isn't defined.
@c @kindex p
@kindex m
@findex w3-complete-link
@item m
Selects a destination from a list of all the hyperlinks in the current
buffer (@code{w3-complete-link}). Use @kbd{space} and @kbd{tab} to
complete on the links.
@kindex r
@kindex g
@findex w3-reload-document
@item r, g
Reloads the current document (@code{w3-reload-document}). The position
within the buffer remains the same (unless the document has changed
since it was last retrieved, in which case it should be relatively
close). This causes an unconditional reload from the remote server ---
the locally cached copy is not consulted.
@kindex R
@findex w3-refresh-buffer
@item R
Redraws the buffer without reloading document (@code{w3-refresh-buffer}).
@kindex C-o
@findex w3-fetch
@item C-o
Prompts for a @sc{url} in the minibuffer, and attempts to fetch it
(@code{w3-fetch}). If there are any errors, or Emacs/W3 cannot
understand the type of link requested, the errors are displayed in a
hypertext buffer.
@kindex o
@findex w3-open-local
@vindex url-use-hypertext-dired
@item o
Opens a local file, interactively (@code{w3-open-local}). This prompts
for a local file name to open. The file must exist, and may be a
directory. If the requested file is a directory and
@code{url-use-hypertext-dired} is @code{nil}, then a dired-mode buffer
is displayed. If non@code{nil}, then Emacs/W3 automatically generates a
hypertext listing of the directory. The hypertext mode is the default,
so that all the keys and functions remain the same.
@kindex M-s
@findex w3-save-as
@item M-s
Save a document to the local disk as HTML Source, Formatted Text, LaTeX
Source, or Binary (@code{w3-save-as}).
@kindex Hv
@kindex C-c C-b
@findex w3-show-history-list
@item Hv, C-c C-b
Show the current session's history list (@code{w3-show-history-list}).
This takes all the links that are in that internal list, and formats
them as hypertext links in a list, @ref{Global History}
@end table
@cindex Buffer movement
And here are the commands to move around between Emacs/W3 buffers:
@table @kbd
@kindex l
@findex w3-goto-last-buffer
@item l
Goes to the last WWW buffer seen (@code{w3-goto-last-buffer}).
@kindex p
@findex w3-print-this-url
@item p
Prints the current document (@code{w3-print-this-url}). Choose from several different formats to
print: formatted text, @sc{html} source, PostScript (with ps-print), or by using
LaTeX and dvips). @ref{Printing}.
@kindex P
@findex w3-print-url-under-point
@item P
Prints out the @sc{url} under point in a variety of formats
(@code{w3-print-url-under-point}). @ref{Printing}.
@kindex q
@findex w3-quit
@item q
Quits WWW mode (@code{w3-quit}). This kills the current buffer and goes
to the most recently visited buffer.
@kindex Q
@kindex u
@findex w3-leave-buffer
@item u, Q
This (@code{w3-leave-buffer}) is similar to @code{w3-quit}, but the
buffer is not killed, it is moved to the bottom of the buffer list (so
it is the least likely to show up as the default with switch-to-buffer).
This is different from @code{w3-goto-last-buffer} in that it does not
return to the last @sc{www} page visited --- it is the same as using
@code{switch-to-buffer} --- the buffer left in the window is fairly
random.
@end table
@node Miscellaneous, , Action, Basic Usage
@section Miscellaneous
@table @kbd
@kindex ?
@findex w3-help
@item ?
Shows help for Emacs/W3 (@code{w3-help}).
@kindex C-c C-v
@findex w3-version
@item C-c C-v
Show what version of Emacs/W3 you're running (@code{w3-version}).
@kindex M-m
@findex w3-mail-current-document
@item M-m
Mails the current document to someone (@code{w3-mail-current-document}).
Choose from several different formats to mail: formatted text, @sc{html}
source, PostScript, or LaTeX source. When the @sc{html} source is
mailed, then an appropriate tag is inserted at the beginning of
the document so that relative links may be followed correctly by whoever
receives the mail.
@kindex M-M
@findex w3-mail-document-under-point
@item M-M
Mails the document pointed to by the hypertext link under point to
someone (@code{w3-mail-document-under-point}). Choose from several
different formats to mail: formatted text, @sc{html} source, PostScript,
or LaTeX source. When the @sc{html} source is mailed, then an
appropriate tag is inserted at the beginning of the document so
that relative links may be followed correctly by whoever receives the
mail.
@kindex A-t
@kindex M-t
@findex url-list-processes
@item M-t, A-t
gdj1: bound to url-list-processes. What does this do?
@kindex c
@findex w3-mail-document-author
@item c
Send a mail to the author of the current document
(@code{w3-mail-document-author}).
@kindex M-x w3-insert-formatted-url
@findex w3-insert-formatted-url
@item M-x w3-insert-formatted-url
Insert a fully formatted @sc{html} link into another buffer
(@code{w3-insert-formatted-url}). This gets the name and @sc{url} of
either the current buffer, or, with a prefix arg, of the link under
point, and construct the appropriate ... markup and insert it
into the desired buffer.
@kindex M-tab
@findex w3-insert-this-url
@item M-tab
Inserts the @sc{url} of the current document into another buffer
(@code{w3-insert-this-url'}). Buffer is prompted for in the minibuffer.
With prefix arg, uses the @sc{url} of the link under point.
@kindex U
@findex w3-use-links
@item U
Selects one of the tags from this document and fetch it
(@code{w3-use-links}). Links are attributes of a specific document, and
can tell such things as who made the document, where a table of contents
is located, etc.
Link tags specify relationships between documents in two ways. Normal
(forward) relationships (where the link has a REL="xxx" attribute), and
reverse relationships (where the link has a REV="xxx" attribute). This
first asks what type of link to follow (Normal or Reverse), then does
a @code{completing-read} on only the links that have that type of
relationship.
@end table
@node Compatibility, Display Variables, Basic Usage, Top
@chapter Compatibility with other Browsers
Due to the popularity of several other browsers, Emacs/W3 offers an easy
transition to its much better way of life. This ranges from being able
to share the same preferences files and disk cache to actually emulating
the keybindings used in other browsers.
@menu
* Emulation:: Emacs/W3 can emulate the keybindings and
other behaviours of other browsers.
* Hotlist Handling:: A hotlist is an easy way to keep track of
interesting Web pages without having to
remember the exact path to get there.
* Session History:: Keeping a history of documents visited
in one Emacs sessions allows the use of
'forward' and 'back' buttons easily.
* Global History:: Keeping a history of all the places ever
visited on the web.
@end menu
@node Emulation, Hotlist Handling, Compatibility, Compatibility
@section Emulation
@cindex Browser emulation
@cindex Emulation of other browsers
@vindex w3-mode-hook
Emacs/W3 can emulate the keybindings of lynx and netscape, but only one
at a time. If you want emulation permanantly turned on, then you should
add @code{turn-on-lynx-emulation} or @code{turn-on-netscape-emulation}
to @code{w3-mode-hook}.
@menu
* lynx:: Emulate lynx.
* netscape:: Emulate netscape.
* Masquerading:: Emacs/W3 can masquerade as another
browser.
@end menu
@node lynx, netscape, Emulation, Emulation
@section Lynx emulation
@cindex Lynx emulation
@findex turn-on-lynx-emulation
@findex w3-lynx-emulation-minor-mode
@code{turn-on-lynx-emulation} turns on lynx emulation and turns off
netscape emulation. lynx emulation is handled by the
@code{w3-lynx-emulation-minor-mode} minor mode. For more information
about lynx style hotlists, @xref{Hotlist Handling}.
:: work :: Document lynx emulation@*
@table @kbd
@kindex down
@item Down arrow
Highlight next topic
@kindex up
@item Up arrow
Highlight previous topic
@kindex right
@kindex return
@item Right arrow, Return, Enter
Jump to highlighted topic
@kindex left
@item Left arrow
Return to previous topic. gdj1: actually, this doesn't seem to work
quite right.
@kindex +
@item +
Scroll down to next page (Page-Down)
@kindex -
@item -
Scroll up to previous page (Page-Up)
@kindex space
@item SPACE
Scroll down to next page (Page-Down)
@kindex b
@item b
Scroll up to previous page (Page-Up)
@kindex C-a
@item C-a
Go to first page of the current document (Home)
@kindex C-b
@item C-e
Go to last page of the current document (End)
@kindex C-b
@item C-b
Scroll up to previous page (Page-Up)
@kindex C-f
@item C-f
Scroll down to next page (Page-Down)
@kindex C-n
@item C-n
Go forward two lines in the current document
@kindex C-p
@item C-p
Go back two lines in the current document
@kindex )
@item )
Go forward half a page in the current document (ignored)
@kindex (
@item (
Go back half a page in the current document (ignored)
@kindex #
@item #
Go to Toolbar or Banner in the current document, only works in XEmacs.
gdj1: is this what is meant by toolbar?
@kindex ?
@kindex h
@item ?, h
Help (this screen)
@kindex a
@item a
Add the current link to a bookmark file
@kindex c
@item c
Send a comment to the document owner
@kindex d
@item d
Download the current link
@kindex e
@item e
Edit the current file (ignored)
@kindex g
@item g
Goto a user specified @sc{url} or file
@kindex i
@item i
Show an index of documents (ignored)
@kindex j
@item j
Execute a jump operation (using hotlist)
@kindex k
@item k
Show a list of key mappings
@kindex l
@item l
List references (links) in current document
@kindex m
@item m
Return to main screen
@kindex n
@item n
Go to the next search string
@kindex o
@item o
Set your options
@kindex p
@item p
Print the current document
@kindex q
@item q
Quit
@kindex r
@item r
Delete hotlist entry
@kindex s
@item s
Enter a search string for an external search gdj1: really?
@kindex u
@item u
Go backwards in history
@kindex /
@item /
Search for a string within the current document
@kindex v
@item v
View a bookmark file
@kindex V
@item V
Go to the Visited Links Page
@kindex x
@item x
Force submission of form or link with no-cache
@kindex z
@item z
Cancel transfer in progress
@kindex backspace
@item [backspace]
Go to the history Page gdj1: really?
@kindex =
@item =
Show file and link info
@kindex \
@item \
Toggle document source/rendered view
@kindex !
@item !
Spawn your default shell
@kindex *
@item *
Toggle image_links mode on and off (ignored)
@kindex [
@item [
Toggle pseudo_inlines mode on and off (ignorged)
@kindex ]
@item ]
Send an @sc{http} @sc{head} request for the current doc or link (ignored)
@kindex C-r
@item C-r
Reload current file and refresh the screen
@kindex C-w
@item C-w
Refresh the screen
@kindex C-u
@item C-u
Erase input line (ignored)
@kindex C-g
@item C-g
Cancel input or transfer
@kindex C-t
@item C-t
Toggle trace mode on and off (ignored)
@kindex C-k
@item C-k
Invoke the Cookie Jar Page (ignored)
@end table
@node netscape, Masquerading, lynx, Emulation
@section Netscape emulation
@cindex Netscape emulation
@findex turn-on-netscape-emulation
@findex w3-netscape-emulation-minor-mode
@code{turn-on-netscape-emulation} turns on netscape emulation and turns
off lynx emulation. netscape emulation is handled by the
@code{w3-netscape-emulation-minor-mode} minor mode. For more
information about netscape style hotlists, @xref{Hotlist Handling}.
@table @kbd
@kindex M-a
@item M-a
Add the current link to a bookmark file
@kindex M-b
@item M-b
Show hotlist file.
@kindex M-f
@item M-f
Search forward in document
@kindex M-g
@item M-g
Reapeat last search
@kindex M-h
@item M-h
Show history window
@kindex M-i
@item M-i
Load images
@kindex M-l
@item M-l
Goto a user specified @sc{url} or file
@kindex M-m
@item M-m
Send mail
@kindex M-n
@item M-n
Open new frame
@kindex M-o
@item M-o
Open a local file
@kindex M-p
@item M-p
Print current document
@kindex M-q
@item M-q
Quit current document
@kindex M-r
@item M-r
Reload document and redraw
@kindex M-s
@item M-s
Save current document
@kindex M-left
@item M-[left]
Go back in history list
@kindex M-right
@item M-[right]
Go forward in history list
@kindex left
@item [left]
Scroll left
@kindex right
@item [right]
Scroll right
@kindex up
@item [up]
Scroll up
@kindex down
@item [down]
Scroll down
@end table
@node Masquerading, , netscape, Emulation
@section Masquerading
@cindex Browser masquerading
@cindex Masquerading as other browsers
@findex turn-on-lynx-masquerade-mode
@findex turn-on-netscape-masquerade-mode
@findex turn-on-ie-masquerade-mode
@findex turn-on-arena-masquerade-mode
@findex turn-off-lynx-masquerade-mode
@findex turn-off-netscape-masquerade-mode
@findex turn-off-ie-masquerade-mode
@findex turn-off-arena-masquerade-mode
@findex w3-arena-masquerade-mode
@findex w3-ie-masquerade-mode
@findex w3-netscape-masquerade-mode
@findex w3-lynx-masquerade-mode
@sc{http} allows servers to ask browsers what browser they are, and what
version they are. Emacs/W3 allows you to choose the reply. There are
functions to masquerade as lynx, netscape, @sc{ie} or arena. For each
@var{browser} there are three functions,
@code{turn-on-@var{browser}-masquerade-mode},
@code{turn-off-@var{browser}-masquerade-mode} and
@code{w3-@var{browser}-masquerade-mode}. The purpose of the first two
is clear, @code{w3-@var{browser}-masquerade-mode} takes an optional
argument which toggles the mode if it's @code{nil}, turns off the mode
if it's 0 and turns the mode on otherwise.
If you'd prefer to masquerade as another browser, then you should call
@code{w3-masquerade-stub} with three arguments: @var{arg}, @var{app} and
@var{version}. @var{arg} has the same function as for
@code{w3-@var{browser}-masquerade-mode}, @var{app} is the name of the
browser to masquerade as and @var{version} is the version.
Why would you want to masquerade as another browser when you could be
advertising Emacs/W3? Well, some servers will only let certain browsers
connect with them. This is cleary evil. Also some servers may alter
what they present depending on the browser, this is probably a Good
Thing but they might not know about Emacs/W3. Also one could argue that
demanding the USER_AGENT field is a breach of privacy, Emacs/W3 doesn't
have to send it (@pxref{Security}), but the server doesn't have
to let you connect either.
@node Hotlist Handling, Session History, Emulation, Compatibility
@section Hotlist Handling
Emacs/W3 supports two types of hotlist, mosaic hotlists and @sc{html} as
used by lynx and netscape (which both call hotlists bookmarks).
Unfortunately, not all hotlist operations are supported for @sc{html}
files at the moment.
In order to avoid having to traverse many documents to get to the same
document over and over, Emacs/W3 supports a ``hotlist'' like Mosaic. This is
a file that contains @sc{url}s and aliases. Hotlists allow quick access to any
document in the Web, providing it has been visited and added to the hotlist.
The variable @code{w3-hotlist-file} determines where this information
is saved. The structure of the file is compatible with Mosaic's
hotlist file, so this defaults to @file{~/.mosaic-hotlist-default}.
Hotlist commands are:
@table @kbd
@item ha
@kindex ha
@findex w3-hotlist-apropos
Shows the hotlist entries matching a regular expression.
@kindex hi
@findex w3-hotlist-add-document
@vindex w3-hotlist-file
@item hi
Adds the current document to the hotlist, with the buffer name as its
identifier. Modifies the file specified by @code{w3-hotlist-file}. If
this is given a prefix-argument (via @kbd{C-u}), the title is prompted
for instead of automatically defaulting to the document title.
@findex w3-hotlist-delete
@vindex w3-hotlist-file
@kindex hd
@item hd
Prompts for the alias of the entry to kill. Pressing the spacebar or
tab will list out partial completions. The internal representation of
the hotlist and the file specified by @code{w3-hotlist-file} are
updated.
@item hr
@kindex hr
@findex w3-hotlist-rename-entry
@vindex w3-hotlist-file
Some hotlist item names can be very unwieldy (`Mosaic for X level 2 fill
out form support'), or uninformative (`Index of /'). Prompts for the
item to rename in the minibuffer---use the spacebar or tab key for
completion. After having chosen an item to rename, prompts for a new
title until a unique title is entered. Modifies the file specified by
@code{w3-hotlist-file}.
@item hu
@kindex hu
@findex w3-use-hotlist
Prompts for the alias to jump to. Pressing the @key{spacebar} or
@key{tab} key shows partial completions.
@item hv
@kindex hv
@findex w3-show-hotlist
Converts the hotlist into @sc{html} and displays it.
@item hA
@kindex hA
@findex w3-hotlist-append
Appends another hotlist file to the one currently in memory.
@item hI
@kindex hI
@findex w3-hotlist-add-document-at-point
Add the document pointed to by the hyperlink under point to the hotlist.
@findex w3-hotlist-refresh
@vindex w3-hotlist-file
@kindex hR
@item hR
This rereads the default hostlist file specified by
@code{w3-hotlist-file}.
@end table
@node Session History, Global History, Hotlist Handling, Compatibility
@section History
@cindex History Lists
Almost all web browsers keep track of the @sc{url}s followed from a page, so
that it can provide @b{forward} and @b{back} buttons to keep a @i{path}
of @sc{url}s that can be traversed easily.
@vindex url-keep-history
If @code{url-keep-history} is non-@code{nil}, then Emacs/W3 keeps track
of all the @sc{url}s visited in an Emacs session. If @code{t} then
Emacs/W3 will save the history list at the end of each session to the
@code{url-global-history-file} file. The history list is simply a list
of all the @sc{url}s visited in the session.
@findex w3-show-history-list
To view a listing of the history for this session of Emacs/W3, use
@code{M-x w3-show-history-list} (@kbd{Hv}) from any buffer, and Emacs/W3
generates an @sc{html} document showing every @sc{url} visited since
Emacs started (or cleared the history list), and then format it. Any of
the links can be chosen and followed to the original document. To clear
the history list, choose 'Clear History' from the 'Options' menu.
@findex w3-forward-in-history
@findex w3-backward-in-history
@findex w3-fetch
Another twist on the history list mechanism is the fact that all
Emacs/W3 buffers remember what @sc{url}, buffer, and buffer position of the
last document, and also keeps track of the next location jumped @b{to}
from that buffer. This means that the user can go forwards and
backwards very easily along the path taken to reach a particular
document. To go forward, use the function @code{w3-forward-in-history} (@kbd{F}),
to go backward, use the function @code{w3-backward-in-history}
(@kbd{B}). To view the entire history, use @code{w3-show-history-list}
(@kbd{Hv}).
@node Global History, , Session History, Compatibility
@section Global History
Most web browsers also support the idea of a ``history'' of @sc{url}s
the user has visited, and it displays them in a different style than
normal @sc{url}s. Emacs/W3 will read and write history files generated
by Emacs/W3, Mosaic v1 and v2 or netscape. Emacs/W3 looks at the file
contents to determine the type of history.
@vindex url-keep-history
@vindex url-global-history-file
@vindex url-global-history-save-interval
If the variable @code{url-keep-history} is @code{t}, then Emacs/W3 keeps
a list of all the @sc{url}s visited in a session. The file is
automatically written to disk every
@code{url-global-history-save-interval} seconds and when exiting emacs.
The list is added to those already in the file specified by
@code{url-global-history-file}, which defaults to @file{~/mosaic.hst}
for MS operating systems, @file{~/mosaic.global-history} for @sc{vms} and
@file{~/.w3/history} for everything else.
If any @sc{url} in the list is found in the file, it is not saved, but new
ones are added at the end of the file.
The function that saves the global history list is smart enough to
notice what style of history list is being used (Netscape, Emacs/W3, or
XMosaic), and writes out the new additions appropriately.
@cindex Completion of URLs
@cindex Usefulness of global history
One of the nice things about keeping a global history files is that Emacs/W3
can use it as a completion table. When doing @kbd{M-x w3-fetch}, pressing
the @kbd{tab} or @kbd{space} key will show all completions for a
partial @sc{url}. This is very useful, especially for very long @sc{url}s that
are not in a hotlist, or for seeing all the pages from a particular web
site before choosing which to retrieve.
@node Display Variables, Stylesheets, Compatibility, Top
@section Display Variables
Emacs/W3 has many variable for you to fiddle with to get the display
just right.
@table @code
@item w3-display-frames
@vindex w3-display-frames
You can control what Emacs/W3 does with frame by setting
@code{w3-display-frames}. It can be
@table @code
@item nil
Emacs/W3 will pretend not to understand frames at all.
@item as-nil
Emacs/W3 will show hyperlinks to frames but will not fetch them (the same
behaviour as lynx).
@item ask
This is similar to @code{as-nil}, but Emacs/W3 will ask if you want to
retrieve the frames.
@item t
Emacs/W3 will dispaly the hyperlinks and fetch the frames.
@end table
@item w3-bullets
@vindex w3-bullets
Emacs/W3 lets @emph{you} decide what characters to use for bullets in
unordered lists by setting @code{w3-bullets}. It is a association list,
mapping list types to characters. By default it is @code{((disc . ?*)
(circle . ?o) (square . ?#) (none . ? ))}.
@item w3-echo-link
@vindex w3-echo-link
You can decide what should be displayed when tabbing through links by
setting the @code{w3-echo-link} variable. It is a list and may contain
the following symbols,
@table @code
@item url
Display the @sc{url} of the target.
@item text
Display the text of the link.
@item title
Display the title attribute of the link.
@item name
Display the name or id attribute of the link.
@end table
The default is @code{(title url text name)}.
@item w3-horizontal-rule-char
@vindex w3-horizontal-rule-char
Many @sc{html} pages use horizontal lines (rules) to seperate sections
of the page. You can control what character Emacs/W3 will use to draw
these by setting @code{w3-horizontal-rule-char}. If it is a character
(@emph{not} a string) then Emacs/W3 will replicate that character across
the screen, if it is @code{nil} then Emacs/W3 will use a terminal
graphics character if possible. It is @code{nil by default}.
@item w3-use-terminal-characters
@vindex w3-use-terminal-characters
When Emacs/W3 draws table and rules, it needs to approximate line
somehow. If @code{w3-use-terminal-characters} it @code{non-nil} (the
default) then Emacs/W3 will use terminal graphics characters if they are
available.
@item w3-use-terminal-characters-on-tty
@vindex w3-use-terminal-characters-on-tty
Using terminal graphics characters on ttys will trigger display bugs in
both XEmacs and FSF Emacs, but the display is usually readable with FSF
Emacs. @code{w3-use-terminal-characters-on-tty} controls whether to use
terminal graphics characters on ttys, it is @code{nil} by default.
@item w3-use-terminal-glyphs
@vindex w3-use-terminal-glyphs
Emacs/W3 can use glyphs rather than text properties for terminal
graphics characters. Glyphs do not work with the most recent versions
of XEmacs. This is @code{t} by default.
@item w3-defined-link-types
@vindex w3-defined-link-types
@code{w3-defined-link-types} is a list of names that have special
significance as the values of @samp{REL} or @samp{REV} attributes of
elements. All members should be in lowercase.
@item w3-auto-image-alt
@vindex w3-auto-image-alt
Some people do not feel it's worth their time to add @code{alt} tags to
their images, but Emacs/W3 can create @code{alt} tags on the fly for
images that do not have them. To control this you can set
@code{w3-auto-image-alt} to one of the following:
@table @asis
@item @code{nil}
Do not create @code{alt} tags
@item string
The string will be run through format with the filename of the image and
so may have a single @code{%s}, for example @code{"[IMAGE(%s)]"}
@item function
The function will be called with the filename of the images as the
argument. This is the default, with @code{w3-default-image-alt-func}
being the function.
@end table
@item w3-min-img-size, w3-default-image-alt-func, w3-dummy-img-alt-repl
@vindex w3-min-img-size
@vindex w3-dummy-img-alt-repl
@findex w3-default-image-alt-func
@code{w3-default-image-alt-func} returns @code{w3-dummy-img-alt-repl}
(@samp{*} by default) if the image's height and width are both less than
@code{w3-min-img-size} pixels (15 by default) and if the filename
matches the @code{w3-dummy-img-re} regular expression. Otherwise,
@code{w3-default-image-alt-func} returns the filename enclosed in a
@samp{[]} pair.
@item w3-icon-format
@vindex w3-icon-format
Emacs/W3 will expect the standard icons to be in the format specified by
@code{w3-icon-format}. This is @code{gif} by default, but could be
@code{xpm}, @code{xbm} or any other format for that matter. It is added
as a file extension to the icon name, but the variable's value must be a
symbol. If @code{nil}, then the server decides.
@item w3-delay-image-loads
@vindex w3-delay-image-loads
You can choose whether Emacs/W3 retrieves images with the document, or
delays loading them by setting @code{w3-delay-image-loads}. By default
this is @code{t} if you compiled XEmacs with support for gifs, jpegs,
pngs or imagick and @code{nil} otherwise.
@item w3-image-mappings
@vindex w3-image-mappings
@code{w3-image-mappings} controls the mapping of @sc{mime} types to
image types for the @samp{image} package. Each entry is a cons cell of
a @sc{mime} type string and an image-type symbol.
@item w3-max-menu-length
@vindex w3-max-menu-length
Emacs/W3 will split menus into smaller submenus if they are longer than
@code{w3-max-menu-length}.
@item w3-max-menu-width
@vindex w3-max-menu-width
The maximum width of a pulldown menu choice.
@item w3-right-margin
@vindex w3-right-margin
Emacs/W3's right margin is controlled by @code{w3-right-margin}. This
is subtracted from @code{(window-width)} for each Emacs/W3 buffer and
used as the fill-column. It is 2 by default.
@item w3-maximum-line-length
@vindex w3-maximum-line-length
The maximum length of a line. If @code{nil} (the default) then lines
can extend to the window margin.
@item w3-modeline-format
@vindex w3-modeline-format
You can specify the modeline to use in @samp{w3-mode} by setting this.
@item w3-honor-stylesheets
@vindex w3-honor-stylesheets
If this is non-@code{nil} (the default) then Emacs/W3 will let a
document specify a @sc{css} stylesheet.
@item w3-user-colors-take-precedence
@vindex w3-user-colors-take-precedence
Emacs/W3 will ignore a document's attempts to define certain colours if
@code{w3-user-colors-take-precedence} it non-@code{nil}. The default is @code{nil}.
@item w3-user-fonts-take-precedence
@vindex w3-user-fonts-take-precedence
Emacs/W3 will ignore attempts by stylesheets or font tags to change
certain fonts if this is non-@code{nil}.
@end table
@subsection Asynchronous behaviour
@table @code
@item url-be-asynchronous
@vindex url-be-asynchronous
If this is non-@code{nil} then document retrievals over @sc{http} will
be down in the background.
@item url-default-retrieval-proc
@vindex url-default-retrieval-proc
This controls what happens when an asynchronous retrievel completes. It
is @code{url-default-callback} by default but can be any function taking
one argument. The argument specifies the file that has been retrieved.
If there is no buffer associated with the file, then
@code{url-default-callback} just puts a message in the minibuffer saying
that the retrieval is complete, otherwise the action depends on the
buffer.
@item w3-do-incremental-display
@vindex w3-do-incremental-display
Emacs/W3 can de incremental display of pages if
@code{w3-do-incremental-display} is @code{t}. It is @code{nil} by default.
@item w3-notify
@vindex w3-notify
You might want Emacs/W3 to notify you discreetly when it has finished
preparing a page for your reading pleasure. You can control Emacs/W3's
behaviour in this situation by way of the @code{w3-notify} variable. It
may take the following values:
@table @code
@item newframe
Puts the Emacs/W3 page in its own frame.
@item bully
Make the Emacs/W3 page the current buffer and only window.
@item semibully
Make the Emacs/W3 page the current buffer in the same window. This is
the default.
@item aggressive
Make the Emacs/W3 page the current buffer in the other window.
@item friendly
Display the Emacs/W3 page in the other window, but don't make it the
current buffer.
@item polite
Don't display Emacs/W3 page, but print a message when ready and beep.
@item quiet
The same as @code{polite}, but don't beep.
@item meek
Make no indication that the page is ready, in fact any other value is
equivalent to meek.
@end table
@end table
@node Stylesheets, Supported URLs, Display Variables, Top
@chapter Stylesheets
The way in which Emacs/W3 formats a document is very customizable. All
formatting is now controlled by a default stylesheet set by the user
with the @code{w3-default-stylesheet} variable. Emacs/W3 currently
supports the @sc{W3C} recommendation for Cascading Style Sheets, Level 1
(commonly known as @sc{CSS1}) with a few experimental items from other
W3C proposals. Wherever Emacs/W3 diverges from the specification, it
will be clearly documented, and will be changed once a full standard is
available.
Support for @sc{dsssl} is progressing, but spare time is at an all-time
low. If anyone would like to help, please contact the author.
The following sections closely parallel the @sc{css1} specification so
it should be very easy to look up what Emacs/W3 supports when browsing
through the @sc{css1} specification. Please note that a lot of the text
in the following sections comes directly from the specification as
well.
@menu
* Terminology:: Terms used in the rest of this chapter.
* Basic Concepts:: Why are stylesheets useful? Getting started.
* Pseudo-Classes/Elements:: Special classes for elements.
* The Cascade:: How stylesheets are combined.
* Properties:: What properties you can set on elements.
* Units:: What you can set them to.
@end menu
@node Terminology, Basic Concepts, Stylesheets, Stylesheets
@section Terminology
@table @dfn
@item attribute
HTML attribute, ie: @samp{align=center} --- align is the attribute.
@item author
The author of an HTML document.
@item block-level element
An element which has a line break before and after (e.g.@: 'H1' in @sc{html}).
@item canvas
The part of the UA's drawing surface onto which documents are rendered.
@item child element
A subelement in @sc{sgml} terminology.
@item contextual selector
A selector that matches elements based on their position in the document
structure. A contextual selector consists of several simple
selectors. E.g., the contextual selector 'H1.initial B' consists of two
simple selectors, 'H1.initial' and 'B'.
@item @sc{css}
Cascading Style Sheets.
@item declaration
A property (e.g. 'font-size') and a corresponding value (e.g. '12pt').
@item designer
The designer of a style sheet.
@item document
@sc{html} document.
@item element
@sc{html} element.
@item element type
A generic identifier in @sc{sgml} terminology.
@item fictional tag sequence
A tool for describing the behavior of pseudo-classes and pseudo-elements.
@item font size
The size for which a font is designed. Typically, the size of a font is
approximately equal to the distance from the bottom of the lowest letter
with a descender to the top of the tallest letter with an ascender and
(optionally) with a diacritical mark.
@item @sc{html} extension
Markup introduced by UA vendors, most often to support certain visual
effects. The @sc{font}, @sc{center} and @sc{blink} elements are examples
of HTML extensions, as is the @sc{bgcolor} attribute. One of the goals
of @sc{css} is to provide an alternative to @sc{html} extensions.
@item inline element
An element which does not have a line break before and after
(e.g. '@sc{strong}' in @sc{html})
@item intrinsic dimensions
The width and height as defined by the element itself, not imposed by
the surroundings. In this specification it is assumed that all replaced
elements -- and only replaced elements -- come with intrinsic
dimensions.
@item parent element
The containing element in @sc{sgml} terminology.
@item pseudo-element
Pseudo-elements are used in @sc{css} selectors to address typographical
items (e.g. the first line of an element) rather than structural
elements.
@item pseudo-class
Pseudo-classes are used in @sc{css} selectors to allow information
external to the @sc{html} source (e.g. the fact that an anchor has been
visited or not) to classify elements.
@item property
A stylistic parameter that can be influenced through @sc{css}.
@item reader
The person for whom the document is rendered.
@item replaced element
An element that the @sc{css} formatter only knows the intrinsic
dimensions of. In @sc{html}, @sc{img}, @sc{input}, @sc{textarea},
@sc{select} and @sc{object} elements can be examples of replaced
elements. E.g., the content of the @sc{img} element is often replaced by
the image that the @sc{src} attribute points to. @sc{css1} does not
define how the intrinsic dimensions are found.
@item rule
A declaration (e.g. 'font-family: helvetica') and its selector
(e.g. @sc{'H1'}).
@item selector
A string that identifies what elements the corresponding rule applies
to. A selector can either be a simple selector (e.g. 'H1') or a
contextual selector (e.g. @sc{'h1 b'}) which consists of several simple
selectors.
@item @sc{sgml}
Standard Generalized Markup Language, of which @sc{html} is an
application.
@item simple selector
A selector that matches elements based on the element type and/or
attributes, and not the element's position in the document
structure. E.g., 'H1.initial' is a simple selector.
@item style sheet
A collection of rules.
@item @sc{ua}
User Agent, often a web browser or web client.
@item user
Synonymous with reader.
@item weight
The priority of a rule.
@end table
@node Basic Concepts, Pseudo-Classes/Elements, Terminology, Stylesheets
@section Basic Concepts
Designing simple style sheets is easy. One needs only to know a little
HTML and some basic desktop publishing terminology. E.g., to set the
text color of 'H1' elements to blue, one can say:
@example
H1 @{ color: blue @}
@end example
The example above is a simple CSS rule. A rule consists of two main
parts: selector ('H1') and declaration ('color: blue'). The declaration
has two parts: property ('color') and value ('blue'). While the example
above tries to influence only one of the properties needed for rendering
an HTML document, it qualifies as a style sheet on its own. Combined
with other style sheets (one fundamental feature of CSS is that style
sheets are combined) it will determine the final presentation of the
document.
The selector is the link between the HTML document and the style sheet, and
all HTML element types are possible selectors.
@node Pseudo-Classes/Elements, The Cascade, Basic Concepts, Stylesheets
@section Pseudo-Classes/Elements
In @sc{css1}, style is normally attached to an element based on its
position in the document structure. This simple model is sufficient for
a wide variety of styles, but doesn't cover some common effects. The
concept of pseudo-classes and pseudo-elements extend addressing in
@sc{css1} to allow external information to influence the formatting
process.
Pseudo-classes and pseudo-elements can be used in @sc{css} selectors,
but do not exist in the @sc{html} source. Rather, they are "inserted" by
the @sc{ua} under certain conditions to be used for addressing in style
sheets. They are referred to as "classes" and "elements" since this is a
convenient way of describing their behavior. More specifically, their
behavior is defined by a fictional tag sequence.
Pseudo-elements are used to address sub-parts of elements, while
pseudo-classes allow style sheets to differentiate between different
element types.
The only support pseudo-classes in Emacs/W3 are on the anchor tag
(...).
User agents commonly display newly visited anchors differently from
older ones. In @sc{css1}, this is handled through pseudo-classes on the
'A' element:
@example
A:link @{ color: red @} /* unvisited link */
A:visited @{ color: blue @} /* visited links */
A:active @{ color: lime @} /* active links */
@end example
All 'A' elements with an 'HREF' attribute will be put into one and only
one of these groups (i.e. target anchors are not affected). UAs may
choose to move an element from 'visited' to 'link' after a certain
time. An 'active' link is one that is currently being selected (e.g. by
a mouse button press) by the reader.
The formatting of an anchor pseudo-class is as if the class had been
inserted manually. A @sc{ua} is not required to reformat a currently
displayed document due to anchor pseudo-class transitions. E.g., a style
sheet can legally specify that the 'font-size' of an 'active' link
should be larger that a 'visited' link, but the UA is not required to
dynamically reformat the document when the reader selects the 'visited'
link.
Pseudo-class selectors do not match normal classes, and vice versa. The
style rule in the example below will therefore not have any influence:
@example
A:link @{ color: red @}
...
@end example
In @sc{css1}, anchor pseudo-classes have no effect on elements other
than 'A'. Therefore, the element type can be omitted from the selector:
@example
A:link @{ color: red @}
:link @{ color: red @}
@end example
The two selectors above will select the same elements in CSS1.
Pseudo-class names are case-insensitive.
Pseudo-classes can be used in contextual selectors:
@example
A:link IMG @{ border: solid blue @}
@end example
Also, pseudo-classes can be combined with normal classes:
@example
A.external:visited @{ color: blue @}
external link
@end example
If the link in the above example has been visited, it will be rendered
in blue. Note that normal class names precede pseudo-classes in the
selector.
@node The Cascade, Properties, Pseudo-Classes/Elements, Stylesheets
@section The Cascade
In @sc{css}, more than one style sheet can influence the presentation
simultaneously. There are two main reasons for this feature: modularity
and author/reader balance.
@table @i
@item modularity
A style sheet designer can combine several (partial) style sheets to
reduce redundancy:
@example
@@import url(http://www.style.org/pastoral);
@@import url(http://www.style.org/marine);
H1 @{ color: red @} /* override imported sheets */
@end example
@item author/reader balance
Both readers and authors can influence the presentation through style
sheets. To do so, they use the same style sheet language thus reflecting
a fundamental feature of the web: everyone can become a publisher. The
@sc{ua} is free to choose the mechanism for referencing personal style
sheets.
@end table
Sometimes conflicts will arise between the style sheets that influence
the presentation. Conflict resolution is based on each style rule having
a weight. By default, the weights of the reader's rules are less than
the weights of rules in the author's documents. I.e., if there are
conflicts between the style sheets of an incoming document and the
reader's personal sheets, the author's rules will be used. Both reader
and author rules override the @sc{ua}'s default values.
The imported style sheets also cascade with each other, in the order
they are imported, according to the cascading rules defined below. Any
rules specified in the style sheet itself override rules in imported
style sheets. That is, imported style sheets are lower in the cascading
order than rules in the style sheet itself. Imported style sheets can
themselves import and override other style sheets, recursively.
In @sc{css1}, all '@@import' statements must occur at the start of a
style sheet, before any declarations. This makes it easy to see that
rules in the style sheet itself override rules in the imported style
sheets.
NOTE: The use of !important in @sc{css} stylesheets is unsupported at
this time.
Conflicting rules are intrinsic to the CSS mechanism. To find the value
for an element/property combination, the following algorithm must be
followed:
@enumerate
@item
Find all declarations that apply to the element/property in
question. Declarations apply if the selector matches the element in
question. If no declarations apply, the inherited value is used. If
there is no inherited value (this is the case for the 'HTML' element and
for properties that do not inherit), the initial value is used.
@item
Sort the declarations by explicit weight: declarations marked
'!important' carry more weight than unmarked (normal) declarations.
@item
Sort by origin: the author's style sheets override the reader's style
sheet which override the UA's default values. An imported style sheet
has the same origin as the style sheet from which it is imported.
@item
Sort by specificity of selector: more specific selectors will override
more general ones. To find the specificity, count the number of ID
attributes in the selector (a), the number of CLASS attributes in the
selector (b), and the number of tag names in the selector
(c). Concatenating the three numbers (in a number system with a large
base) gives the specificity. Some examples:
@example
LI @{...@} /* a=0 b=0 c=1 -> specificity = 1 */
UL LI @{...@} /* a=0 b=0 c=2 -> specificity = 2 */
UL OL LI @{...@} /* a=0 b=0 c=3 -> specificity = 3 */
LI.red @{...@} /* a=0 b=1 c=1 -> specificity = 11 */
UL OL LI.red @{...@} /* a=0 b=1 c=3 -> specificity = 13 */
#x34y @{...@} /* a=1 b=0 c=0 -> specificity = 100 */
@end example
Pseudo-elements and pseudo-classes are counted as normal elements and
classes, respectively.
@item
Sort by order specified: if two rules have the same weight, the latter
specified wins. Rules in imported style sheets are considered to be
before any rules in the style sheet itself.
@end enumerate
The search for the property value can be terminated whenever one rule
has a higher weight than the other rules that apply to the same
element/property combination.
This strategy gives author's style sheets considerably higher weight
than those of the reader. It is therefore important that the reader has
the ability to turn off the influence of a certain style sheet,
e.g. through a pull-down menu.
A declaration in the 'STYLE' attribute of an element has the same weight
as a declaration with an ID-based selector that is specified at the end
of the style sheet:
@example
@end example
In the above example, the color of the 'P' element would be
red. Although the specificity is the same for both declarations, the
declaration in the 'STYLE' attribute will override the one in the
'STYLE' element because of cascading rule number 5.
The @sc{ua} may choose to honor other stylistic @sc{html} attributes,
for example 'ALIGN'. If so, these attributes are translated to the
corresponding @sc{css} rules with specificity equal to 1. The rules are
assumed to be at the start of the author style sheet and may be
overridden by subsequent style sheet rules. In a transition phase, this
policy will make it easier for stylistic attributes to coexist with
style sheets.
@node Properties, Units, The Cascade, Stylesheets
@section Properties
In the text below, the allowed values for each property are listed
with a syntax like the following:
@example
Value: N | NW | NE
Value: [ | thick | thin ]@{1,4@}
Value: ? [ / ]?
Value: ||
@end example
The words between < and > give a type of value. The most common types
are , , , and these are
described in the section on [[units]]. The more specialized types
(e.g. and ) are described under the property
where they appear.
Other words are keywords that must appear literally, without quotes. The
slash (/) and the comma (,) must also appear literally.
Several things juxtaposed mean that all of them must occur, in the given
order. A bar (|) separates alternatives: one of them must occur. A
double bar (A || B) means that either A or B or both must occur, in any
order. Brackets ([]) are for grouping. Juxtaposition is stronger than
the double bar, and the double bar is stronger than the bar. Thus "a b |
c || d e" is equivalent to "[ a b ] | [ c || [ d e ]]".
Every type, keyword, or bracketed group may be followed by one of the
following modifiers:
@itemize @bullet
@item
An asterisk (*) indicates that the preceding type, word or group is
repeated zero or more times.
@item
A plus (+) indicates that the preceding type, word or group is repeated
one or more times.
@item
A question mark (?) indicates that the preceding type, word or group is
optional.
@item
A pair of numbers in curly braces (@{A,B@}) indicates that the preceding
type, word or group is repeated at least A and at most B times.
@end itemize
Other than the value the following information is also shown.
@multitable @columnfractions .3 .7
@item Supported Values: @tab If this is present, it lists the parts of
the specification that Emacs/W3 currently supports.
@item Unsupported Values: @tab If this is present, it represents the
parts of the specifcation that Emacs/W3 does not support.
@item Initial: @tab The default value for the property, unless
explicitly set in a stylesheet.
@item Applies to: @tab What type of elements this property can be attached to.
@item Inherited: @tab Yes or no
@item Percentage values: @tab What a percentage value applies to when given.
@end multitable
@menu
* Font Properties:: Selecting fonts, styles, and sizes.
* Colors and Backgrounds:: Controlling colors, front and back.
* Text Properties:: Alignment, decoration, and more!
* Box Properties:: Borders, padding, and margins, oh my!
* Classification:: Changing whitespace and display policies.
* Media Selection:: Conditionalize stylesheets on media-type.
* Speech Properties:: Speech output controlled by stylesheets.
@end menu
@node Font Properties, Colors and Backgrounds, Properties, Properties
@subsection Font Properties
Setting font properties will be among the most common uses of style
sheets. Unfortunately, there exists no well-defined and universally
accepted taxonomy for classifying fonts, and terms that apply to one
font family may not be appropriate for others. E.g. 'italic' is commonly
used to label slanted text, but slanted text may also be labeled as
being @b{Oblique}, @b{Slanted}, @b{Incline}, @b{Cursive} or
@b{Kursiv}. Therefore it is not a simple problem to map typical font
selection properties to a specific font.
The properties defined by CSS1 are described in the following sections.
@menu
* font-family:: Groups of fonts.
* font-style:: Normal, italic, or oblique?
* font-variant:: Small-caps, etc.
* font-weight:: How bold can you go?
* font-size:: How big is yours?
* font:: Shorthand for all of the above.
@end menu
@node font-family, font-style, Font Properties, Font Properties
@subsubsection font-family
@multitable @columnfractions .20 .8
@item Supported Values: @tab [[ | ],]* [ | ]
@item Initial: @tab User specific
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The value is a prioritized list of font family names and/or generic
family names. Unlike most other CSS1 properties, values are separated
by a comma to indicate that they are alternatives:
@example
BODY @{ font-family: gill, helvetica, sans-serif @}
@end example
There are two types of list values:
@table @b
@item
The name of a font family of choice. In the last example, "gill" and
"helvetica" are font families.
@item
In the example above, the last value is a generic family name. The
following generic families are defined:
@itemize @bullet
@item
'serif' (e.g. Times)
@item
'sans-serif' (e.g. Helvetica)
@item
'cursive' (e.g. Zapf-Chancery)
@item
'fantasy' (e.g. Western)
@item
'monospace' (e.g. Courier)
@end itemize
@end table
Style sheet designers are encouraged to offer a generic font family as a
last alternative.
Font names containing whitespace should be quoted:
@example
BODY @{ font-family: "new century schoolbook", serif @}
@end example
If quoting is omitted, any whitespace characters before and after the
font name are ignored and any sequence of whitespace characters inside
the font name is converted to a single space.
@node font-style, font-variant, font-family, Font Properties
@subsubsection font-style
@multitable @columnfractions .2 .8
@item Supported Values: @tab normal | italic | oblique
@item Initial: @tab normal
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The 'font-style' property selects between normal (sometimes referred to
as "roman" or "upright"), italic and oblique faces within a font family.
A value of 'normal' selects a font that is classified as 'normal' in the
UA's font database, while 'oblique' selects a font that is labeled
'oblique'. A value of 'italic' selects a font that is labeled 'italic',
or, if that is not available, one labeled 'oblique'.
The font that is labeled 'oblique' in the UA's font database may
actually have been generated by electronically slanting a normal font.
Fonts with Oblique, Slanted or Incline in their names will typically be
labeled 'oblique' in the UA's font database. Fonts with Italic, Cursive
or Kursiv in their names will typically be labeled 'italic'.
@example
H1, H2, H3 @{ font-style: italic @}
H1 EM @{ font-style: normal @}
@end example
In the example above, emphasized text within 'H1' will appear in a
normal face.
@node font-variant, font-weight, font-style, Font Properties
@subsubsection font-variant
@multitable @columnfractions .2 .8
@item Value: @tab normal | small-caps
@item Initial: @tab normal
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
Another type of variation within a font family is the small-caps. In a
small-caps font the lower case letters look similar to the uppercase
ones, but in a smaller size and with slightly different proportions. The
'font-variant' property selects that font.
A value of 'normal' selects a font that is not a small-caps font,
'small-caps' selects a small-caps font. It is acceptable (but not
required) in CSS1 if the small-caps font is a created by taking a normal
font and replacing the lower case letters by scaled uppercase
characters. As a last resort, uppercase letters will be used as
replacement for a small-caps font.
The following example results in an 'H3' element in small-caps, with
emphasized words in oblique small-caps:
@example
H3 @{ font-variant: small-caps @}
EM @{ font-style: oblique @}
@end example
There may be other variants in the font family as well, such as fonts
with old-style numerals, small-caps numerals, condensed or expanded
letters, etc. CSS1 has no properties that select those.
@node font-weight, font-size, font-variant, Font Properties
@subsubsection font-weight
@multitable @columnfractions .3 .7
@item Supported Values: @tab normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
@item Unsupported Values: @tab bolder | lighter
@item Initial: @tab normal
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The 'font-weight' property selects the weight of the font. The values
'100' to '900' form an ordered sequence, where each number indicates a
weight that is at least as dark as its predecessor. The keyword 'normal'
is synonymous with '400', and 'bold' is synonymous with '700'. Keywords
other than 'normal' and 'bold' have been shown to be often confused with
font names and a numerical scale was therefore chosen for the 9-value
list.
@example
P @{ font-weight: normal @} /* 400 */
H1 @{ font-weight: 700 @} /* bold */
@end example
The 'bolder' and 'lighter' values select font weights that are relative
to the weight inherited from the parent:
@example
STRONG @{ font-weight: bolder @}
@end example
There is no guarantee that there will be a darker face for each of the
'font-weight' values; for example, some fonts may have only a normal and
a bold face, others may have eight different face weights. There is no
guarantee on how a UA will map font faces within a family to weight
values. The only guarantee is that a face of a given value will be no
less dark than the faces of lighter values.
@node font-size, font, font-weight, Font Properties
@subsubsection font-size
@multitable @columnfractions .3 .7
@item Supported Values: @tab |
@item Unsupported Values: @tab |
@item Initial: @tab medium
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab relative to parent element's font size
@end multitable
@table @b
@item
An keyword is an index to a table of font sizes computed
and kept by the UA. Possible values are:
@itemize @bullet
@item
xx-small
@item
x-small
@item
small
@item
medium
@item
large
@item
x-large
@item
xx-large
@end itemize
On a computer screen a scaling factor of 1.5 is suggested between
adjacent indexes; if the 'medium' font is 10pt, the 'large' font could
be 15pt. Different media may need different scaling factors. Also, the
UA should take the quality and availability of fonts into account when
computing the table. The table may be different from one font family to
another.
@item
A keyword is interpreted relative to the table of font
sizes and the font size of the parent element. Possible values are
@b{larger} or @b{smaller}. For example, if the parent element has a font
size of 'medium', a value of 'larger' will make the font size of the
current element be 'large'. If the parent element's size is not close to
a table entry, the UA is free to interpolate between table entries or
round off to the closest one. The UA may have to extrapolate table
values if the numerical value goes beyond the keywords.
@end table
Length and percentage values should not take the font size table into
account when calculating the font size of the element.
Negative values are not allowed.
On all other properties, 'em' and 'ex' length values refer to the font
size of the current element. On the 'font-size' property, these length
units refer to the font size of the parent element.
Note that an application may reinterpret an explicit size, depending on
the context. E.g., inside a VR scene a font may get a different size
because of perspective distortion.
Examples:
@example
P @{ font-size: 12pt; @}
BLOCKQUOTE @{ font-size: larger @}
EM @{ font-size: 150% @}
EM @{ font-size: 1.5em @}
@end example
If the suggested scaling factor of 1.5 is used, the last three
declarations are identical.
@node font, , font-size, Font Properties
@subsubsection font
@multitable @columnfractions .2 .8
@item Value: @tab [ || || ]? [ / ]?
@item Initial: @tab not defined for shorthand properties
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab allowed on and
@end multitable
The 'font' property is a shorthand property for setting 'font-style'
'font-variant' 'font-weight' 'font-size', 'line-height' and
'font-family' at the same place in the style sheet. The syntax of this
property is based on a traditional typographical shorthand notation to
set multiple properties related to fonts.
For a definition of allowed and initial values, see the previously
defined properties. Properties for which no values are given are set to
their initial value.
@example
P @{ font: 12pt/14pt sans-serif @}
P @{ font: 80% sans-serif @}
P @{ font: x-large/110% "new century schoolbook", serif @}
P @{ font: bold italic large Palatino, serif @}
P @{ font: normal small-caps 120%/120% fantasy @}
@end example
In the second rule, the font size percentage value ('80%') refers to the
font size of the parent element. In the third rule, the line height
percentage refers to the font size of the element itself.
In the first three rules above, the 'font-style', 'font-variant' and
'font-weight' are not explicitly mentioned, which means they are all
three set to their initial value ('normal'). The fourth rule sets the
'font-weight' to 'bold', the 'font-style' to 'italic' and implicitly
sets 'font-variant' to 'normal'.
The fifth rule sets the 'font-variant' ('small-caps'), the 'font-size'
(120% of the parent's font), the 'line-height' (120% times the font
size) and the 'font-family' ('fantasy'). It follows that the keyword
'normal' applies to the two remaining properties: 'font-style' and
'font-weight'.
@node Colors and Backgrounds, Text Properties, Font Properties, Properties
@subsection Colors and Backgrounds
These properties describe the color (often called foreground color) and
background of an element (i.e. the surface onto which the content is
rendered). One can set a background color and/or a background image. The
position of the image, if/how it is repeated, and whether it is fixed or
scrolled relative to the canvas can also be set.
The 'color' property inherits normally. The background properties do not
inherit, but the parent element's background will shine through by
default because of the initial 'transparent' value on
'background-color'.
NOTE: Currently, Emacs/W3 can only show background images under XEmacs.
Emacs 19 doesn't have the support in its display code yet.
@menu
* color:: Foreground colors.
* background-color:: Background colors.
* background-image:: Background images.
* background-repeat:: Controlling repeating of background images.
* background-attachment:: Where background images are drawn.
* background-position:: Where background images are drawn.
* background:: Shorthand for all background properties.
@end menu
@node color, background-color, Colors and Backgrounds, Colors and Backgrounds
@subsubsection color
@multitable @columnfractions .2 .8
@item Value: @tab
@item Initial: @tab User specific
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
This property describes the text color of an element (often referred to
as the foreground color). There are different ways to specify red:
@example
EM @{ color: red @} /* natural language */
EM @{ color: rgb(255,0,0) @} /* RGB range 0-255 */
@end example
See @ref{Color Units} for a description of possible color values.
@node background-color, background-image, color, Colors and Backgrounds
@subsubsection background-color
@multitable @columnfractions .2 .8
@item Value: @tab | transparent
@item Initial: @tab transparent
@item Applies to: @tab all elements
@item Inherited: @tab no
@item Percentage values: @tab N/A
@end multitable
This property sets the background color of an element.
@example
H1 @{ background-color: #F00 @}
@end example
@node background-image, background-repeat, background-color, Colors and Backgrounds
@subsubsection background-image
@multitable @columnfractions .2 .8
@item Value: @tab | none
@item Initial: @tab none
@item Applies to: @tab all elements
@item Inherited: @tab no
@item Percentage values: @tab N/A
@end multitable
This property sets the background image of an element. When setting a
background image, one should also set a background color that will be
used when the image is unavailable. When the image is available, it is
overlaid on top of the background color.
@example
BODY @{ background-image: url(marble.png) @}
P @{ background-image: none @}
@end example
@node background-repeat, background-attachment, background-image, Colors and Backgrounds
@subsubsection background-repeat
This property is not supported at all under Emacs/W3.
@node background-attachment, background-position, background-repeat, Colors and Backgrounds
@subsubsection background-attachment
This property is not supported at all under Emacs/W3.
@node background-position, background, background-attachment, Colors and Backgrounds
@subsubsection background-position
This property is not supported at all under Emacs/W3.
@node background, , background-position, Colors and Backgrounds
@subsubsection background
@multitable @columnfractions .2 .8
@item Value: @tab || || || ||
@item Initial: @tab not defined for shorthand properties
@item Applies to: @tab all elements
@item Inherited: @tab no
@item Percentage values: @tab allowed on
@end multitable
The 'background' property is a shorthand property for setting the
individual background properties (i.e., 'background-color',
'background-image', 'background-repeat', 'background-attachment' and
'background-position') at the same place in the style sheet.
Possible values on the 'background' properties are the set of all
possible values on the individual properties.
@example
BODY @{ background: red @}
P @{ background: url(chess.png) gray 50% repeat fixed @}
@end example
The 'background' property always sets all the individual background
properties. In the first rule of the above example, only a value for
'background-color' has been given and the other individual properties
are set to their initial value. In the second rule, all individual
properties have been specified.
@node Text Properties, Box Properties, Colors and Backgrounds, Properties
@subsection Text Properties
@menu
* word-spacing::
* letter-spacing::
* text-decoration::
* vertical-align::
* text-transform::
* text-align::
* text-indent::
* line-height::
@end menu
@node word-spacing, letter-spacing, Text Properties, Text Properties
@subsubsection word-spacing
@multitable @columnfractions .3 .7
@item Supported Values: @tab normal
@item Unsupported Values: @tab
@item Initial: @tab normal
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The length unit indicates an addition to the default space between
words. Values can be negative, but there may be implementation-specific
limits. The UA is free to select the exact spacing algorithm. The word
spacing may also be influenced by justification (which is a value of the
'align' property).
@example
H1 @{ word-spacing: 0.4em @}
@end example
Here, the word-spacing between each word in 'H1' elements would be
increased by '1em'.
NOTE: Emacs/W3 cannot currently support this, due to limitations in
Emacs. It may be implemented in the future.
@node letter-spacing, text-decoration, word-spacing, Text Properties
@subsubsection letter-spacing
@multitable @columnfractions .3 .7
@item Supported Values: @tab normal
@item Unsupported Values: @tab
@item Initial: @tab normal
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The length unit indicates an addition to the default space between
characters. Values can be negative, but there may be
implementation-specific limits. The UA is free to select the exact
spacing algorithm. The letter spacing may also be influenced by
justification (which is a value of the 'align' property).
@example
BLOCKQUOTE @{ letter-spacing: 0.1em @}
@end example
Here, the letter-spacing between each character in 'BLOCKQUOTE' elements
would be increased by '0.1em'.
NOTE: Emacs/W3 cannot currently support this, due to limitations in
Emacs. It may be implemented in the future.
@node text-decoration, vertical-align, letter-spacing, Text Properties
@subsubsection text-decoration
@multitable @columnfractions .3 .7
@item Supported Values: @tab none | underline | line-through | blink
@item Unsupported Values: @tab overline
@item Initial: @tab none
@item Applies to: @tab all elements
@item Inherited: @tab no, but see clarification below
@item Percentage values: @tab N/A
@end multitable
This property describes decorations that are added to the text of an
element. If the element has no text (e.g. the 'IMG' element in HTML) or
is an empty element (e.g. ''), this property has no effect. A
value of 'blink' causes the text to blink.
The color(s) required for the text decoration should be derived from the
'color' property value.
This property is not inherited, but elements should match their
parent. E.g., if an element is underlined, the line should span the
child elements. The color of the underlining will remain the same even
if descendant elements have different 'color' values.
@example
A:link, A:visited, A:active @{ text-decoration: underline @}
@end example
The example above would underline the text of all links (i.e., all 'A'
elements with a 'HREF' attribute).
NOTE: The 'line-through' property is only supported under XEmacs
currently. A patch has been sent to the Emacs maintainers to add
support for this, but it has not made it into the main distribution
yet.
@node vertical-align, text-transform, text-decoration, Text Properties
@subsubsection vertical-align
This is currently unsupported in Emacs/W3.
@node text-transform, text-align, vertical-align, Text Properties
@subsubsection text-transform
@multitable @columnfractions .3 .7
@item Supported Values: @tab none
@item Unsupported Values: @tab capitalize | uppercase | lowercase
@item Initial: @tab none
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
@table @b
@item 'capitalize'
Uppercases the first character of each word.
@item 'uppercase'
Uppercases all letters of the element.
@item 'lowercase'
Lowercases all letters of the element.
@item 'none'
Neutralizes inherited value.
@end table
The actual transformation in each case is human language dependent.
@example
H1 @{ text-transform: uppercase @}
@end example
The example above would put 'H1' elements in uppercase text.
NOTE: This capability was in the previous version of Emacs/W3, but has
not been reimplemented in the new display code yet. Please feel free to
send me patches.
@node text-align, text-indent, text-transform, Text Properties
@subsubsection text-align
@multitable @columnfractions .2 .8
@item Value: @tab left | right | center | justify
@item Initial: @tab User specific
@item Applies to: @tab block-level elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
This property describes how text is aligned within the element. The
actual justification algorithm used is UA and human language dependent.
Example:
@example
DIV.center @{ text-align: center @}
@end example
Since 'text-align' inherits, all block-level elements inside the 'DIV'
element with 'CLASS=center' will be centered. Note that alignments are
relative to the width of the element, not the canvas.
@node text-indent, line-height, text-align, Text Properties
@subsubsection text-indent
Not currently implemented in Emacs/W3.
@node line-height, , text-indent, Text Properties
@subsubsection line-height
Not currently implemented in Emacs/W3.
@node Box Properties, Classification, Text Properties, Properties
@subsection Box Properties
@multitable @columnfractions .2 .8
@end multitable
@node Classification, Media Selection, Box Properties, Properties
@subsection Classification
These properties classify elements into categories more than they set
specific visual parameters.
The list-style properties describe how list items (i.e. elements with a
'display' value of 'list-item') are formatted. The list-style properties
can be set on any element, and it will inherit normally down the
tree. However, they will only be have effect on elements with a
'display' value of 'list-item'. In HTML this is typically the case for
the 'LI' element.
@menu
* display::
* white-space::
* list-style-type::
* list-style-image::
* list-style-position::
* list-style::
@end menu
@node display, white-space, Classification, Classification
@subsubsection display
@multitable @columnfractions .2 .8
@item Value: @tab block | inline | list-item | none
@item Extensions: @tab line
@item Initial: @tab inline
@item Applies to: @tab all elements
@item Inherited: @tab no
@item Percentage values: @tab N/A
@end multitable
This property describes how/if an element is displayed on the canvas
(which may be on a printed page, a computer display etc.).
An element with a 'display' value of 'block' opens whitespace suitable
for a paragraph break. Typically, elements like 'H1' and 'P' are of
type 'block'. A value of 'list-item' is similar to 'block' except that a
list-item marker is added. In HTML, 'LI' will typically have this value.
An element with a 'display' value of 'inline' results in a new inline
box on the same line as the previous content.
A value of 'none' turns off the display of the element, including
children elements and the surrounding box.
@example
P @{ display: block @}
EM @{ display: inline @}
LI @{ display: list-item @}
IMG @{ display: none @}
@end example
The last rule turns off the display of images.
A value of 'line' results in a single line break. Emacs/W3 needs this
extension to be able to fully specify the behaviour of @sc{br} and
@sc{hr} elements within a stylesheet.
NOTE: Emacs/W3 defaults to using 'inline' for this property, which is a
slight deviation from the specification.
@node white-space, list-style-type, display, Classification
@subsubsection white-space
@multitable @columnfractions .2 .8
@item Value: @tab normal | pre | nowrap
@item Initial: @tab normal
@item Applies to: @tab block-level elements
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
This property declares how whitespace inside the element is handled: the
'normal' way (where whitespace is collapsed), as 'pre' (which behaves
like the 'PRE' element in HTML) or as 'nowrap' (where wrapping is done
only through BR elements):
@example
PRE @{ white-space: pre @}
P @{ white-space: normal @}
@end example
@node list-style-type, list-style-image, white-space, Classification
@subsubsection list-style-type
@multitable @columnfractions .2 .8
@item Value: @tab disc | circle | square | decimal | lower-roman | upper-roman | lower-alpha | upper-alpha | none
@item Initial: @tab disc
@item Applies to: @tab elements with 'display' value 'list-item'
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
This property is used to determine the appearance of the list-item
marker if 'list-style-image' is 'none' or if the image pointed to by the
URL cannot be displayed.
Fo example:
@example
OL @{ list-style-type: decimal @} /* 1 2 3 4 5 etc. */
OL @{ list-style-type: lower-alpha @} /* a b c d e etc. */
OL @{ list-style-type: lower-roman @} /* i ii iii iv v etc. */
@end example
@node list-style-image, list-style-position, list-style-type, Classification
@subsubsection list-style-image
@multitable @columnfractions .2 .8
@item Value: @tab | none
@item Initial: @tab none
@item Applies to: @tab elements with 'display' value 'list-item'
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
This property sets the image that will be used as the list-item
marker. When the image is available it will replace the marker set with
the 'list-style-type' marker.
NOTE: This is currently unimplemented in Emacs/W3.
@example
UL @{ list-style-image: url(http://png.com/ellipse.png) @}
@end example
@node list-style-position, list-style, list-style-image, Classification
@subsubsection list-style-position
@multitable @columnfractions .3 .7
@item Supported Values: @tab outside
@item Unsupported Values: @tab inside
@item Initial: @tab outside
@item Applies to: @tab elements with 'display' value 'list-item'
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The value of 'list-style-position' determines how the list-item marker
is drawn with regard to the content. For a formatting example see
section 4.1.3.
@node list-style, , list-style-position, Classification
@subsubsection list-style
@multitable @columnfractions .2 .8
@item Value: @tab || ||
@item Initial: @tab not defined for shorthand properties
@item Applies to: @tab elements with 'display' value 'list-item'
@item Inherited: @tab yes
@item Percentage values: @tab N/A
@end multitable
The 'list-style' property is a shorthand notation for setting the three
properties 'list-style-type', 'list-style-image' and
'list-style-position' at the same place in the style sheet.
@example
UL @{ list-style: upper-roman inside @}
UL UL @{ list-style: circle outside @}
LI.square @{ list-style: square @}
@end example
Setting 'list-style' directly on 'LI' elements can have unexpected
results. Consider:
@example
level 1
level 2
@end example
Since the specificity (as defined in the cascading order) is higher for
the first rule in the style sheet in the example above, it will override
the second rule on all 'LI' elements and only 'lower-alpha' list styles
will be used. It is therefore recommended to set 'list-style' only on
the list type elements:
@example
OL.alpha @{ list-style: lower-alpha @}
UL @{ list-style: disc @}
@end example
In the above example, inheritance will transfer the 'list-style' values
from 'OL' and 'UL' elements to 'LI' elements.
A URL value can be combined with any other value:
@example
UL @{ list-style: url(http://png.com/ellipse.png) disc @}
@end example
In the example above, the 'disc' will be used when the image is
unavailable.
@node Media Selection, Speech Properties, Classification, Properties
@subsection Media Selection
To specify that a stylesheet declaration should only apply when using a
certain media type (ie: different font families preferred when printing
versus on-screen presentation), the declarations should be wrapped in
the proposed @b{@@media} directive.
The @@media directive takes two arguments, the media type, and a block
of style declarations.
@example
@@media print @{
BODY @{ font-size: 10pt @}
H1 @{ font-size: 14pt @}
@}
@end example
The '@@media' construct also allows to put include style sheet rules
for various media in the same style sheet:
@example
@@media print @{
BODY @{ font-size: 10pt @}
@}
@@media screen @{
BODY @{ font-size: 12pt @}
@}
@end example
Currently, the following media types are defined.
@table @b
@item Print
Output for paged opaque material, and for documents viewed on screen in
print preview mode.
@item Screen
A continuous presentation for computer screens.
@item Projector
Paged presentation for projected presentations.
@item Braille
For braille tactile feedback devices.
@item Speech
Aural presentation.
@item Light
The stylesheet will only be applied if the user is using a light background.
@item Dark
The stylesheet will only be applied if the user is using a dark background.
@item Emacs
The stylesheet will only be applied if the user is running in Emacs 19.
@item XEmacs
The stylesheet will only be applied if the user is running in XEmacs 19.
@item All
The default value, the style sheet applies to all output devices.
@end table
@node Speech Properties, , Media Selection, Properties
@subsection Speech Properties
Those of us who are sighted are accustomed to visual presentation of
@sc{html} documents, frequently on a bitmapped display. This is not the
only possible presentation method, however. Aural presentation, using a
combination of speech synthesis and 'audio icons', provides an
alternative presentation. This form of presentation is in current use by
the blind and print-impaired communities.
Often such aural presentation occurs by converting the document to plain
text and feeding this to a 'screen reader' -- software or hardware that
simply reads all the characters on the screen. This results in less
effective presentation than would be the case if the document structure
were retained.
There are other large markets for aural presentation, including in-car
and home entertainment use; aurual or mixed aural/visual presentation is
thus likely to increase in importance over the next few years. Realizing
that that the aural rendering is essentially independent of the visual
rendering:
@itemize @bullet
@item
Allows orthogonal aural and visual views.
@item
Allows browsers to optionally implement both aural and visual views to
produce truly multimodal documents.
@end itemize
@menu
* volume::
* pause-before::
* pause-after::
* pause::
* cue-before::
* cue-after::
* cue::
* play-during::
* speed::
* voice-family::
* pitch::
* pitch-range::
* stress::
* richness::
* speak-punctuation::
* speak-date::
* speak-numeral::
* speak-time::
@end menu
@node volume, pause-before, Speech Properties, Speech Properties
@subsubsection volume
@multitable @columnfractions .2 .8
@item Value: @tab | mute | x-soft | soft | medium | loud | x-loud
@item Initial: @tab medium
@item Applies to: @tab all elements
@item Inherited: @tab yes
@item Percentage values: @tab relative to user-specified mapping
@end multitable
The legal range of percentage values is 0% to 100%. There is a fixed
mapping between keyword values and percentages:
@itemize @bullet
@item
'x-soft' = '0%'
@item
'soft' = '25%'
@item
'medium' = '50%'
@item
'loud' = '75%'
@item
'x-loud' = '100%'
@end itemize
Volume refers to the median volume of the waveform. In other words, a
highly inflected voice at a volume of 50 might peak well above
that. Note that '0%' does not mean the same as "mute". 0% represents the
minimum audible volume level and 100% corresponds to the maximum
comfortable level. The UA should allow the values corresponding to 0%
and 100% to be set by the user. Suitable values depend on the equipment
in use (speakers, headphones), the environment (in car, home theater,
library) and personal preferences. Some examples:
@itemize @bullet
@item
A browser for in-car use has a setting for when there is lots of
background noise . 0% would map to a fairly high level and 100% to a
quite high level. The overall values are likely to be human adjustable
for comfort, for example with a physical volume control: what this
proposal does is adjust the dynamic range.
@item
Another speech browser is being used in the home, late at night, (don't
annoy the neighbors) or in a shared study room. 0% is set to very quiet
and 100% to a fairly quiet level, too. As with the first example, there
is a low slope; the dynamic range is reduced. The actual volumes are low
here, wheras they were high in the first example.
@item
In a quiet and isolated house, an expensive hifi home theatre setup. 0%
is set fairly low and 100% to quite high; there is wide dynamic range.
@end itemize
The same authors stylesheet could be used in all cases, simply by
mapping the 0 and 100 points suitably at the client side.
@node pause-before, pause-after, volume, Speech Properties
@subsubsection pause-before
@multitable @columnfractions .2 .8
@item Value: @tab