Moved specification and ChangeLog documentation.

1 files changed, 2 insertions, 365 deletions

diff --git a/SPECIFICATION b/SPECIFICATION
index 91e3798..06563f2 100644
--- a/SPECIFICATION
+++ b/SPECIFICATION
@@ -1,366 +1,3 @@
-FreeDesktop proposed notifications spec
-=======================================
-
-(c) 2004 Mike Hearn <mike@navi.cx>
-    2004 Christian Hammond <chipx86@chipx86.com>
-
-ChangeLog:
-
-v0.1:
-  * Initial version
-v0.2:
-  * Add replaces field to protocol
-
----------------------------------------------------------------------
-
-OVERVIEW
-
-This is a draft standard for a desktop notifications service, through
-which applications can generate passive popups (sometimes known as
-"poptarts") to notify the user in an asynchronous manner of events.
-
-This specification explicitly does not include other types of
-notification presentation such as modal message boxes, window manager
-decorations or window list annotations.
-
-Example use cases include:
-
-* Presence changes in IM programs: for instance, MSN Messenger on
-  Windows pioneered the use of passive popups to indicate presence
-  changes.
-
-* New mail notification
-
-* Low disk space/battery warnings
-
-
-
-BASIC DESIGN
-
-In order to ensure that multiple notifications can easily be
-displayed at once, and to provide a convenient implementation, all
-notifications are controlled by a single session-scoped service which
-exposes a DBUS interface.
-
-On startup, a conforming implementation should take the
-"org.freedesktop.Notifications" service on the session bus. This
-service will be referred to as the "notification server" or just "the
-server" in this document. It can optionally be activated automatically
-by the bus process, however this is not required and notification
-server clients must not assume that it is available.
-
-The server should implement the "org.freedesktop.Notifications" interface on
-an object with the path "/org/freedesktop/Notifications". This is the
-only interface required by this version of the specification.
-
-A notification has the following components:
-
-- Application name: This is the optional name of the application sending
-  the notification. This should be the application's formal name, rather
-  than some sort of ID.
-
-- Application icon: An optional byte array containing the application's icon.
-  This should be in PNG or GIF formats.
-
-- Replaces ID: An optional ID of an existing notification that this
-  notification is intended to replace.
-
-- Notification Type ID: An optional ID representing the notification type.
-  See the NOTIFICATION TYPES section below.
-
-- Urgency level: The urgency of the notification. See the URGENCY LEVELS
-  section below.
-
-- A summary: This is a single line overview of the notification. For
-  instance "You have mail" or "A friend has come online". Tip: It
-  should generally not be longer than 40 characters though this is not
-  a requirement and server implementations should word wrap if
-  necessary. The summary must be encoded using UTF-8.
-
-- An optional body: This is a multi-line body of text. Each line is a
-  paragraph, server implementations are free to word wrap them as they
-  see fit.
-
-  The text may contain simple markup as specified in the MARKUP
-  section below. It must be encoded using UTF-8.
-
-  If the body is omitted just the summary is displayed.
-
-- An optional array of images: See the ICONS/SOUNDS section below.
-
-- An optional sound: See the ICONS/SOUNDS section below.
-
-- An dictionary of actions. The actions send a request message back to the
-  notification client when invoked. This functionality may not be
-  implemented by the notification server, conforming clients should
-  check if it is available before using it (see the GetCapabilities message
-  in the PROTOCOL section). An implementation is free to ignore any
-  requested by the client. As an example one possible rendering of
-  actions would be as buttons in the notification popup.
-
-- An optional dictionary of hints: See the HINTS section below.
-
-- An expiration time: the timestamp in seconds since the epoch that the
-  notification should close. If one wishes to have an expiration of 5 seconds
-  from now, they must grab the current timestamp and add 5 seconds to it.
-
-  If zero, the notification's expiration time is dependent on the
-  notification server's settings, and may vary for the type of
-  notification.
-
-  The expiration time should be respected by implementations, but this is
-  not required (this is for compatibility with KNotify).
-
-Each notification displayed is allocated a unique ID by the server.
-This is unique within the session - while the notification server is
-running the ID will not be recycled unless the capacity of a uint32 is
-exceeded.
-
-This can be used to hide the notification before the expiration time
-is reached. It can also be used to atomically replace the notification
-with another: this allows you to (for instance) modify the contents of
-a notification while it's on-screen.
-
-
-BACKWARDS COMPATIBILITY
-
-Clients should try and avoid making assumptions about the presentation and
-abilities of the notification server. The message content is the most
-important thing.
-
-Clients can check with the server what capabilities are supported
-using the GetCapabilities message. See the PROTOCOL section.
-
-If a client requires a response from a passive popup, it should be
-coded such that a non-focus-stealing message box can be used instead
-and the notification server is only used when available.
-
-
-MARKUP
-
-Description text may contain markup. The markup is XML-based, and consists
-of a small subset of HTML along with a few additional tags.
-
-The following tags can optionally be supported:
-
-- <b>...</b> - Bold
-- <i>...</i> - Italic
-- <u>...</u> - Underline
-- <a href="...">...</a> - Hyperlink
-
-TODO: What else do we want here?
-
-
-ICONS/SOUNDS
-
-A notification can optionally include an array of images and/or a
-single sound. The array of images specifies frames in an animation,
-animations always loop. Implementations are free to ignore the
-image/sound data, and implementations that support images may not
-support animation.
-
-If the image array has more than one element, a "primary frame" can
-be specified - if not specified it defaults to the first frame. For
-implementations that support images but not animation (for instance a
-KNotify bridge), only the primary frame will be used.
-
-Each element of the array must have the same type as the first
-element, mixtures of strings and blobs are not allowed. The element
-types can be one of the following:
-
-* [string] Icon theme name. Any string that does not begin with the /
-  character is assumed to be an icon theme name and is looked up
-  according to the spec. The best size to fit the servers chosen
-  presentation will be used. This is the recommended way of
-  specifying images.
-
-* [string] Absolute path. Any string that begins with a / will be
-  used as an absolute file path. Implementations should support at
-  minimum files of type image/png and image/svg.
-
-* [binary] A data stream may be embedded in the message. This is
-  assumed to be of type image/png.
-
-A sound can be specified, this will be played by the notification
-server when the notification is displayed. FIXME: elaborate here.
-
-
-NOTIFICATION TYPES:
-
-Write me.
-
-
-URGENCY LEVELS:
-
-Write me.
-
-
-HINTS:
-
-Write me.
-
-
-PROTOCOL
-
-The following messages must be supported by all implementations.
-
-* GetCapabilities
-
-  This message takes no parameters.
-
-  It returns an array of strings. Each string describes an optional
-  capability implemented by the server. The following values are
-  defined by this spec:
-
-  "body": Supports body text. Some implementations may only show the
-          summary (for instance, onscreen displays, marquee/scrollers)
-
-  "markup": Supports markup in the body text. If marked up text is sent
-            to a server that does not give this cap, the markup will show
-            through as regular text so must be stripped clientside.
-
-  "static-image" : Supports display of exactly 1 frame of any given
-                   image array.  This value is mutually exclusive with
-                   "multi-image", it is a protocol error for the
-                   server to specify both.
-
-  "multi-image": The server will render an animation of all the frames
-                 in a given image array. The client may still specify
-                 multiple frames even if this cap and/or static-image
-                 is missing, however the server is free to ignore them
-                 and use only the primary frame.
-
-  "sound": The server will play the specified sound. Even if this cap
-           is missing, a sound may still be specified however the
-           server is free to ignore it.
-
-  "actions": The server will provide the specified actions to the
-             user. Even if this cap is missing, actions may still be
-             specified by the client, however the server is free to
-             ignore them.
-
-  New vendor-specific caps may be specified as long as they start with
-  "x-vendorname", so for instance "x-gnome-foo-cap". Caps may not
-  contain spaces in their names (FIXME: this feels right but is it
-  really necessary?)
-
-* Notify
-
-  This message requires the following parameters in the exact order
-  shown. For some parameters multiple types may be acceptable
-
-  STRING/NIL application name: the name of the application sending the
-  notification.
-
-  BYTE ARRAY/NIL application icon: the optional icon for the calling
-  application.
-
-  UINT32 replaces: if non-zero this is the notification ID that
-  this notification replaces. The server must atomically (ie with
-  no flicker or other visual cues) replace the given notification
-  with this one. This allows clients to effectively modify the
-  notification while it's active.
-
-  STRING/NIL notification type: the type ID of the notification, for
-  potential server categorization and logging purposes. See the
-  NOTIFICATION TYPES section.
-
-  BYTE urgency: The urgency level:
-    0 - low urgency
-    1 - medium
-    2 - high
-    3 - critical
-
-  See the URGENCY LEVELS section for more information.
-
-  Other values should be treated as "medium" in this version of the spec.
-
-  STRING summary
-
-  STRING/NIL body: if nil the body is considered omitted.
-
-  ARRAY images: the array may be empty.
-
-  STRING/NIL sound: if nil the sound is considered omitted.
-
-  DICT actions: each dictionary key is the localized name of the
-  action, and each key maps to a UINT32 containing an action
-  code. This code will be reported back to the client if the action
-  is invoked by the user.
-
-  DICT hints: optional hints that can be passed to the server from the
-  client. Although clients and servers should never assume to support such
-  hints, they can be used to pass along information such as the process
-  PID or window ID. See the HINTS section.
-
-  UINT32/NIL expire time: if nil the notification never times out.
-  If non-nil, a UNIX time_t (since the epoch) at which point the notification
-  will be automatically closed. If zero, use the default server timeout.
-
-
-  If replaces is NIL, return is a UINT32 that will never be reused
-  within a session unless more than MAXINT notifications have been
-  generated (ie an acceptable implementation for this is just an
-  incrementing counter). The returned UINT32 will never be zero, as
-  this is an invalid ID.
-
-  If replaces is not NIL, return is the same as replaces.
-
-* CloseNotification
-
-  This message indicates that the notification should be removed from
-  the users view. It can be used, for instance, if the event the
-  notification pertains to is no longer relevant or to cancel a
-  notification with no expiration. It takes one UINT32 parameter, the ID
-  of the notificaton to cancel. The NotificationClosed signal is emitted by this
-  method.
-
-* GetServerInformation
-
-  This message takes no parameters, and returns the following values in an array:
-
-  STRING name: the product name of the server
-  STRING vendor: "kde"/"freedesktop.org"/"Microsoft" etc etc
-  STRING version: a version spec of arbitrary format
-
-All implementations must emit the following signals:
-
-* NotificationClosed
-
-  A completed notification is one that has timed out, or been
-  dismissed by the user.
-
-  Has two parameters:
-
-  * UINT32 id: containing the ID of the notification that was
-               completed.
-  * UINT32 reason: 1 for expires, 2 for being dismissed by the user,
-                   3 for "other".
-
-  The ID specified in the signal is invalidated *before* the signal
-  is sent and may not be used in any further communications with the
-  server.
-
-The following signals MAY be emitted by the server.
-
-* Invoked
-
-  This signal is emitted when:
-
-  - The user performs some global "invoking" action upon a notification,
-    for instance by clicking on its graphical representation
-  - The user invokes a specific action as specified in the original
-    Notify request, for example by clicking on the action button.
-
-  ActionInvoked has two parameters:
-
-  * UINT32 id: The ID of the notification containing the invoked action.
-
-  * UINT32 action_id: Zero means the default invoke action that can be
-                      performed on any notification. 1+ is the index in
-                      the actions array originally specified.
-
-  Clients should not assume the server will generate this signal: some
-  servers may not support user interaction at all, or may not support
-  the concept of being able to "invoke" a notification.
+This document has moved.
 
+Please see docs/ for the new version of the specification.