   This file documents the use of MIT Scheme.

   Copyright (C) 2000, 2001 Massachusetts Institute of Technology

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

Flags
=====

   Each message can have various "flags" assigned to it as a means of
classification.  Each flag has a name; different names are different
flags.  Any given flag is either present or absent on a particular
message.  A few flag names have standard meanings and are given to
messages automatically by IMAIL when appropriate.  All other flags are
assigned only by users.

`a FLAG <RET>'
     Assign the flag FLAG to the current message (`imail-add-flag').

`k FLAG <RET>'
     Remove the flag FLAG from the current message (`imail-kill-flag').

`C-M-n FLAGS <RET>'
     Move to the next message that has one of the flags FLAGS
     (`imail-next-flagged-message').

`C-M-p FLAGS <RET>'
     Move to the previous message that has one of the flags FLAGS
     (`imail-previous-flagged-message').

`C-M-l FLAGS <RET>'
     Make a summary of all messages containing any of the flags FLAGS
     (`imail-summary-by-flags').

   The `a' (`imail-add-flag') and `k' (`imail-kill-flag') commands
allow you to assign or remove any flag on the current message.

   Once you have given messages flags to classify them as you wish,
there are two ways to use the flags: in moving and in summaries.

   The command `C-M-n FLAGS <RET>' (`imail-next-flagged-message') moves
to the next message that has one of the flags FLAGS.  The argument
FLAGS specifies one or more flag names, separated by commas.  `C-M-p'
(`imail-previous-flagged-message') is similar, but moves backwards to
previous messages.  A numeric argument to either command serves as a
repeat count.

   The command `C-M-l FLAGS <RET>' (`imail-summary-by-flags') displays
a summary containing only the messages that have at least one of a
specified set of flags.  The argument FLAGS is one or more flag names,
separated by commas.  See Summaries, for information on summaries.

   If the FLAGS argument to `C-M-n', `C-M-p' or `C-M-l' is empty, it
means to use the last set of flags specified for any of these commands.

   Some flags such as `deleted' and `filed' have built-in meanings and
are assigned to or removed from messages automatically at appropriate
times.  Here is a list of built-in flags:

`seen'
     Means the message has been selected, implying that the user has
     seen it.  Assigned to a message when it is selected by the user.
     When you start IMAIL, it initially shows the first message that
     lacks this flag.

`deleted'
     Means the message is deleted.  Assigned by deletion commands and
     removed by undeletion commands (see Deleting Messages).

`filed'
     Means the message has been copied to another folder.  Assigned by
     the message-copying commands (see Multiple Folders).

`answered'
     Means you have mailed an answer to the message.  Assigned by the
     `r' command (`imail-reply').  See Sending Replies.

`forwarded'
     Means you have forwarded the message.  Assigned by the `f' command
     (`imail-forward').  See Sending Replies.

`resent'
     Means you have resent the message.  Assigned by the command `C-u f'
     (`imail-resend').  See Sending Replies.

   All other flags are assigned or removed only by the user, and have no
standard meaning.

Sending Replies
===============

   IMAIL has several commands that use Mail mode to send outgoing mail.
What this section documents are the special commands of IMAIL for
entering Mail mode.  Note that the usual keys for sending mail--`C-x
m', `C-x 4 m', and `C-x 5 m'--are available in IMAIL mode and work just
as they usually do.

`m'
     Send a message (`imail-mail').

`c'
     Continue editing the already started outgoing message
     (`imail-continue').

`r'
     Send a reply to the current IMAIL message (`imail-reply').

`f'
     Forward the current message to other users (`imail-forward').

`C-u f'
     Resend the current message to other users (`imail-resend').

   The most common reason to send a message while in IMAIL is to reply
to the message you are reading.  To do this, type `r' (`imail-reply').
This displays the `*mail*' buffer in another window, much like `C-x 4
m', but preinitializes the `Subject', `To', `CC' and `In-reply-to'
header fields based on the message you are replying to.  The `To' field
starts out as the address of the person who sent the message you
received, and the `CC' field starts out with all the other recipients
of that message.

   You can exclude certain recipients from being placed automatically in
the `CC', using the variable `imail-dont-reply-to-names'.  Its value
should be a regular expression (as a string); any recipient that the
regular expression matches is excluded from the `CC' field.  The
default value matches your own name, and any name starting with `info-'
(the value of the variable `imail-default-dont-reply-to-names').
(Those names are excluded because there is a convention of using them
for large mailing lists to broadcast announcements.)

   To omit the `CC' field completely for a particular reply, enter the
reply command with a numeric argument: `C-u r' or `1 r'.

   By default, the `Subject' field of a reply is initialized to the
contents of the `Subject' field of the message being replied to.
However, if the variable `imail-reply-with-re' is set to `#t', then the
reply subject will be prefixed with `Re:'.

   Once the `*mail*' buffer has been initialized, editing and sending
the mail goes as usual.  You can edit the presupplied header fields if
they are not right for you.  You can also use the commands of Mail mode,
including `C-c C-y' which yanks in the message that you are replying
to.  You can switch to the IMAIL buffer, select a different message
there, switch back, and yank the new current message.

   Another frequent reason to send mail in IMAIL is to "forward" the
current message to other users.  `f' (`imail-forward') makes this easy
by preinitializing the `*mail*' buffer with the current message as a
MIME attachment, and a subject designating a forwarded message.  All
you have to do is fill in the recipients and send.  When you forward a
message, recipients get a message which is "from" you, and which has the
original message in its contents.

   By default, forwarded messages are sent as MIME attachments, which
allows MIME-aware mail readers to recognize that the attachment is a
mail message and to specially present it.  However, this means that
such forwarded messages appear more complex when viewed in mail readers
that do not understand MIME.  IMAIL deliberately minimizes the amount
of encoding overhead used for MIME-forwarded messages, but some people
prefer not to use MIME at all.  For that reason, IMAIL allows you to
turn off this feature, so that forwarded messages are included in the
main body of the message (as Rmail does).  To do this, set the variable
`imail-forward-using-mime' to `#f'.

   Normally, when IMAIL forwards a message, it sends only a few of the
message's header fields.  In particular, it sends only those header
fields that you see when viewing the message in IMAIL.  Sometimes it is
desirable to send _all_ of the message's header fields; IMAIL provides
two ways to do this.  First, if you want to send all of the header
fields for a particular message, use `imail-forward' with a negative
argument, like this: `- f'.  Alternatively, you can set the variable
`imail-forward-all-headers' to `#t', which will cause _all_ forwarded
messages to retain all of their header fields.

   "Resending" is an alternative similar to forwarding; the difference
is that resending sends a message that is "from" the original sender,
just as it reached you--with a few added header fields `Resent-from'
and `Resent-to' to indicate that it came via you.  To resend a message
in IMAIL, use `C-u f'.  (`f' runs `imail-forward', which is programmed
to invoke `imail-resend' if you provide a numeric argument.)

   The `m' (`imail-mail') command is used to start editing an outgoing
message that is not a reply.  It leaves the header fields empty.  Its
only difference from `C-x 4 m' is that it makes the IMAIL buffer
accessible for `C-c C-y', just as `r' does.  Thus, `m' can be used to
reply to or forward a message.

   The `c' (`imail-continue') command resumes editing the `*mail*'
buffer, to finish editing an outgoing message you were already
composing, or to alter a message you have sent.

Message Display
===============

   IMAIL provides several variables and commands to give you control
over how messages are formatted in the message buffer.

   By default, IMAIL automatically wraps long lines at the right
margin.  It uses "adaptive fill"(1) to do the wrapping, which means
that common prefixes such as `>' and `Chris>' will be automatically
copied down with the wrapped line.  Generally, this wrapping makes
messages easier to read.  Specifically, it is important for messages
sent by clients that use "soft" line breaks, because such clients
expect the mail reader to wrap lines.  However, if you'd rather not
have IMAIL do this for you, you can disable wrapping by setting the
variable `imail-auto-wrap' to `#f'.

   Another feature of IMAIL is that it filters message headers, showing
you only the most relevant ones.  There are two variables that control
how this is done, and a command that can override the filtering.  The
variable `imail-kept-headers' contains a list of regular expressions
that are matched against message-header names (the name is everything
to the left of the colon, e.g. `From' in `From: cph').  If
`imail-kept-headers' is a non-empty list, then only the headers
matching those regular expressions are shown.  Furthermore, the shown
headers will be in the same order as the regular expressions.

   If `imail-kept-headers' is an empty list, then all of the message
headers are shown, except those matching the regular expression that is
the value of the variable `imail-ignored-headers'.  By default, the
value of `imail-ignored-headers' contains some common uninteresting
header names; this expression is identical to the default used by Rmail.
Note that `imail-ignored-headers' is a single regular expression, while
`imail-kept-headers' is a list of regular expressions.  This is because
`imail-ignored-headers' is meant to be an exact analog of the Rmail
variable `rmail-ignored-headers'.

   Regardless of how the message-header filtering is done, you can
toggle between viewing the filtered headers and the unfiltered headers
using the `t' command (`imail-toggle-header').  If filtered headers are
shown, this command replaces them with unfiltered headers, and vice
versa.

   As you can see, IMAIL performs extensive transformation of a mail
message before presenting it to you: MIME formatting, line wrapping,
and header filtering.  Sometimes, it's desirable to see the original
message, exactly as it was received, without any formatting at all.
The command `C-c C-t C-m' toggles the entire message between a
formatted view and a raw view.  This should be used with care, as a
message with a large attachment might not fit in memory in its raw form.

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

   (1) See the online help for the variable `adaptive-fill-regexp' for
more information about adaptive fill.

Summaries
=========

   A "summary" is a buffer containing one line per message to give you
an overview of the mail in an IMAIL folder.  Each line shows the
message number, the sender, the flags, and the subject.  Almost all
IMAIL commands are valid in the summary buffer also; these apply to the
message described by the current line of the summary.  Moving point in
the summary buffer selects messages as you move to their summary lines.

   A summary buffer applies to a single IMAIL folder only; if you are
editing multiple IMAIL folders, each one can have its own summary
buffer.  The summary buffer name is made by appending `-summary' to the
IMAIL buffer's name.  Normally only one summary buffer is displayed at
a time.

Making Summaries
----------------

   Here are the commands to create a summary for the current IMAIL
folder.  Once the IMAIL folder has a summary buffer, changes in the
IMAIL folder (such as deleting or expunging messages, and getting new
mail) automatically update the summary.

`h'
`C-M-h'
     Summarize all messages (`imail-summary').

`l FLAGS <RET>'
`C-M-l FLAGS <RET>'
     Summarize messages that have one or more of the specified flags
     (`imail-summary-by-flags').

`C-M-r RCPTS <RET>'
     Summarize messages that have one or more of the specified
     recipients (`imail-summary-by-recipients').

`C-M-t TOPIC <RET>'
     Summarize messages that have a match for the specified regexp
     TOPIC in their subjects (`imail-summary-by-topic').

`C-M-s REGEXP <RET>'
     Summarize messages that have a match for the specified regexp
     anywhere in their header (`imail-summary-by-regexp').

   The `h' or `C-M-h' (`imail-summary') command fills the summary
buffer for the current IMAIL folder with a summary of all the messages
in the folder.  It then displays and selects the summary buffer in
another window.

   `C-M-l FLAGS <RET>' (`imail-summary-by-flags') makes a partial
summary mentioning only the messages that have one or more of the flags
FLAGS.  FLAGS should contain flag names separated by commas.

   `C-M-r RCPTS <RET>' (`imail-summary-by-recipients') makes a partial
summary mentioning only the messages that have one or more of the
recipients RCPTS.  RCPTS should contain mailing addresses separated by
commas.

   `C-M-t TOPIC <RET>' (`imail-summary-by-topic') makes a partial
summary mentioning only the messages whose subjects have a match for
the regular expression TOPIC.

   `C-M-s REGEXP <RET>' (`imail-summary-by-regexp') makes a partial
summary mentioning only the messages whose headers contain a match for
the regular expression REGEXP.  This match includes all lines in the
header, including for example the date and from lines.

   Note that there is only one summary buffer for any IMAIL folder;
making one kind of summary discards any previously made summary.

   There are several variables that affect how summaries are displayed.
`imail-summary-height' controls the height of the summary window.  If
it is an exact positive integer, the summary window is that many lines
high.  Alternatively, if it is a real number between 0 and 1 exclusive,
the height of the summary window is computed by multiplying the number
of lines in the message window by `imail-summary-height' and rounding
to the nearest integer.

   If the variable `imail-summary-fixed-layout' is set to `#t', then an
IMAIL message buffer and its associated summary buffer are always shown
in a fixed window layout (provided the summary buffer exists).
Selecting either buffer causes all other windows in the current editor
frame to be deleted, then splits the frame into two windows showing the
summary buffer and message buffer.  Selecting any other buffer when
this layout is displayed causes both windows to be deleted, and the
other buffer displayed in a single window filling the editor frame.
Basically, this causes the message and summary buffers to be treated as
a unit most of the time.  Currently, the default for
`imail-summary-fixed-layout' is `#f', but the feature has been very
popular and the default may be changed to `#t' in a future release.

   When fixed layout is not used, the variable
`imail-summary-pop-up-message' provides a different kind of window
splitting for message and summary buffers.  If this is set to `#t' (the
default), then selecting a new message in the summary buffer causes the
message buffer to be popped up in a new window if it isn't already
visible.

   If the variable `imail-summary-highlight-message' is `#t', the
message currently selected in the message buffer is highlighted in the
summary buffer.  This aids navigation in the summary buffer and is thus
the default.  Set it to `#f' if you don't like the highlighting.

   By default, the summary buffer has five columns: flags, message
number, message length, subject, and author.  If
`imail-summary-show-date' is set to `#t', a sixth column containing an
abbreviated date appears between the message number and the subject.

   The width of the subject column is specified by the value of
`imail-summary-subject-width'; subject fields longer than this number
of characters are truncated.

Editing in Summaries
--------------------

   You can use the IMAIL summary buffer to do almost anything you can
do in the IMAIL buffer itself.  In fact, once you have a summary
buffer, there's no need to switch back to the IMAIL buffer.

   You can select and display various messages in the IMAIL buffer,
from the summary buffer, just by moving point in the summary buffer to
different lines.  It doesn't matter what Emacs command you use to move
point; whichever line point is on at the end of the command, that
message is selected in the IMAIL buffer.

   Almost all IMAIL commands work in the summary buffer as well as in
the IMAIL buffer.  Thus, `d' in the summary buffer deletes the current
message, `u' undeletes, and `x' expunges.  `o' outputs the current
message to a folder; `C-o' saves an attachment from the current
message; `r' starts a reply to it.  You can scroll the current message
while remaining in the summary buffer using <SPC> and <DEL>.

   The IMAIL commands to move between messages also work in the summary
buffer, but with a twist: they move through the set of messages
included in the summary.  They also ensure the IMAIL buffer appears on
the screen (unlike cursor motion commands, which update the contents of
the IMAIL buffer but don't display it in a window unless it already
appears).  You can always display the message indicated by point using
the <e> command (`imail-summary-select-message').

   When you are finished using the summary, type `C-x k <RET>' to
delete the summary buffer's window.

Sorting Messages
================

   IMAIL provides several commands that change the order of messages
within a folder.  These commands are closely modelled on those of
Rmail.  Note that these commands don't modify the folder itself; they
only modify the way that the folder behaves.  This means that if a
folder buffer is deleted, the sort order associated with that buffer is
deleted too.

`C-c C-s C-v'
     Sort messages of current IMAIL folder by arrival time
     (`imail-sort-by-arrival').  This is the default; this sort undoes
     any other sorting on the folder.

`C-c C-s C-d'
     Sort messages of current IMAIL folder by date
     (`imail-sort-by-date').

`C-c C-s C-s'
     Sort messages of current IMAIL folder by subject
     (`imail-sort-by-subject').

`C-c C-s C-a'
     Sort messages of current IMAIL folder by author's name
     (`imail-sort-by-author').

`C-c C-s C-r'
     Sort messages of current IMAIL folder by recipient's names
     (`imail-sort-by-recipient').

`C-c C-s C-c'
     Sort messages of current IMAIL folder by the name of the other
     correspondent (`imail-sort-by-correspondent').

   The IMAIL sort commands perform a _stable sort_: if there is no
reason to prefer either one of two messages, their order remains
unchanged.  You can use this to sort by more than one criterion.  For
example, if you use `imail-sort-by-date' and then
`imail-sort-by-author', messages from the same author appear in order
by date.

   With a numeric argument, all these commands reverse the order of
comparison.  This means they sort messages from newest to oldest, from
biggest to smallest, or in reverse alphabetical order.

Other Commands
==============

   This section documents a handful of commands and variables that don't
fit into any of the other documentation categories.

`q'
     Quit out of IMAIL (`imail-quit').  This closes all open IMAP
     connections and buries all IMAIL buffers.  With prefix argument,
     only affects the current IMAIL buffer, leaving any other IMAIL
     buffers alone.

`M-d'
     Disconnect from the IMAP server (`imail-disconnect').

`b'
     Bury the IMAIL buffer (`imail-bury').

`s'
     Save changes in the current folder to disk (`imail-save-folder').

   When you are finished reading mail in a folder, use the `q' command
(`imail-quit').  This command "closes" the folder, then buries the
buffer.  Closing a folder has different effects, depending on the type
of folder.  Closing an IMAP folder causes IMAIL to disconnect from the
IMAP server (go offline).  Closing a file folder saves any changes out
to the corresponding file.  In both cases, internal data structures may
be dropped, requiring them to be rebuilt, should the folder later be
re-opened.  In no case are any changes made to the folder's contents;
in particular, deleted messages are _not_ expunged.

   On IMAP folders, the `q' command is equivalent to `M-d b'.  On file
folders, the `q' command is equivalent to `s b'.

   The `M-d' command (`imail-disconnect') disconnects IMAIL from the
IMAP server (goes offline).  This has no effect on file folders.

   The `b' command (`imail-bury') buries the selected IMAIL buffer.
"Burying" a buffer means moving it to the bottom of the buffer list and
selecting another buffer from the top of the list.  This is similar to
the command `bury-buffer', except that any summary buffer associated
with this buffer is also buried, and if a window was created to hold
the summary buffer, it is deleted.

   The `s' command (`imail-save-folder') saves out any changes to the
selected IMAIL folder.  For file folders, this means writing the folder
back out to its file.  For IMAP folders, this no effect.  In no case
are any changes made to the folder's contents; in particular, deleted
messages are _not_ expunged.

   IMAIL normally caches IMAP message bodies in memory in order to
increase performance.  The variable `imail-body-cache-limit' gives you
some control over how this caching is done.  `imail-body-cache-limit'
is normally set to a positive integer, meaning that any message body or
in-line MIME entity whose size in bytes is less than this number is
cached.  However, caching can be entirely disabled by setting
`imail-body-cache-limit' to `#f', or made unconditional by setting it
to `#t'.

   Another thing that IMAIL caches is IMAP passwords.  This is done so
that you don't have to keep typing your password whenever you connect
to a new IMAP folder.  However, this is also a security risk, because
the password is kept in Scheme's memory.  The variable
`imail-pass-phrase-retention-time' says how long passwords are cached,
in minutes.  Normally this is set to 30 minutes, but if you are
paranoid you can set it to zero to disable password caching altogether.
Scheme keeps track of the use of each password, and deletes its copy
of the password when it has expired.  Additionally, Scheme stores
passwords in an obscured form, to prevent them being seen during casual
browsing through memory structures, but this does _not_ provide any
protection against a deliberate attempt to find the password.

GNU Free Documentation License
******************************

                        Version 1.1, March 2000
     Copyright (C) 2000  Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

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

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The "Document", below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as "you".

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has less than five).

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section entitled "History", and its title, and
          add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. In any section entitled "Acknowledgements" or "Dedications",
          preserve the section's title, and preserve in the section all
          the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section as "Endorsements" or to
          conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties-for example, statements of peer review or that the text has
     been approved by an organization as the authoritative definition
     of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     "History" in the various original documents, forming one section
     entitled "History"; likewise combine any sections entitled
     "Acknowledgements", and any sections entitled "Dedications".  You
     must delete all sections entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an "aggregate", and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.

  9. TERMINATION

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

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

   To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.1
       or any later version published by the Free Software Foundation;
       with the Invariant Sections being LIST THEIR TITLES, with the
       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.