[Emacs-diffs] /srv/bzr/emacs/trunk r107740: * os.texi (Terminal-Specific): Fix typo.

[Michael Albinus]

------------------------------------------------------------
revno: 107740
committer: Michael Albinus <address@hidden>
branch nick: trunk
timestamp: Tue 2012-04-03 10:10:17 +0200
message:
  * os.texi (Terminal-Specific): Fix typo.
  (Notifications): New section.
  
  * elisp.texi (Top):
  * vol1.texi (Top):
  * vol2.texi (Top): Add "Notifications" and "Dynamic Libraries"
  menu entries.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/os.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-01 02:44:24 +0000
+++ b/doc/lispref/ChangeLog     2012-04-03 08:10:17 +0000
@@ -1,3 +1,13 @@
+2012-04-03  Michael Albinus  <address@hidden>
+
+       * os.texi (Terminal-Specific): Fix typo.
+       (Notifications): New section.
+
+       * elisp.texi (Top):
+       * vol1.texi (Top):
+       * vol2.texi (Top): Add "Notifications" and "Dynamic Libraries"
+       menu entries.
+
 2012-04-01  Chong Yidong  <address@hidden>
 
        * files.texi (Kinds of Files): file-subdir-of-p renamed to

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-03-25 07:58:59 +0000
+++ b/doc/lispref/elisp.texi    2012-04-03 08:10:17 +0000
@@ -1390,6 +1390,8 @@
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
+* Notifications::           Desktop notifications.
+* Dynamic Libraries::       On-demand loading of support libraries.
 
 Preparing Lisp code for distribution
 

=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi       2012-03-27 00:49:32 +0000
+++ b/doc/lispref/os.texi       2012-04-03 08:10:17 +0000
@@ -35,6 +35,7 @@
 * X11 Keysyms::         Operating on key symbols for X Windows.
 * Batch Mode::          Running Emacs without terminal interaction.
 * Session Management::  Saving and restoring state with X Session Management.
+* Notifications::       Desktop notifications.
 * Dynamic Libraries::   On-demand loading of support libraries.
 @end menu
 
@@ -273,7 +274,7 @@
 @ignore
 @c I do not think this should be mentioned.  AFAICS it is just a dodge
 @c around inhibit-startup-screen not being settable on a site-wide basis.
-If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. 
+If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.
 @end ignore
 @end defopt
 
@@ -461,7 +462,7 @@
   You can also arrange to override some of the actions of the
 terminal-specific library by setting the variable
 @code{term-setup-hook}.  This is a normal hook that Emacs runs
-at the end its initialization, after loading both
+at the end of its initialization, after loading both
 your init file and any terminal-specific libraries.  You could
 use this hook to define initializations for terminals that do not
 have their own libraries.  @xref{Hooks}.
@@ -2249,6 +2250,151 @@
 @end group
 @end example
 
address@hidden Notifications
address@hidden Desktop Notifications
address@hidden desktop notifications
+
+Emacs is able to send notifications on systems which support the
+desktop notification specification of freedesktop.org.  In order to
+use this functionality, the package @code{notifications} must be loaded.
+
address@hidden notifications-notify &rest params
+This function sends a notification to the desktop via D-Bus.
+Various @var{params} can be set, none of them is mandatory:
+
address@hidden @code
address@hidden :title @var{title}
+The notification title.
+
address@hidden :body @var{text}
+The notification body text.  Depending on the implementation of the
+notification server, the text could contain HTML markups, like
address@hidden"<b>bold text</b>"}, or hyperlinks.
+
address@hidden :app-name @var{name}
+The name of the application sending the notification. Default is
address@hidden
+
address@hidden :replaces-id @var{id}
+The notification @var{id} that this notification replaces.  @var{id}
+must be the result of a previous @code{notifications-notify} call.
+
address@hidden :app-icon @var{icon-file}
+The file name of the notification icon.  If set to @code{nil}, no icon
+is displayed. Default is @code{notifications-application-icon}.
+
address@hidden :actions (@var{key} @var{title} @var{key} @var{title} ...)
+A list of actions to be applied.  @var{key} and @var{title} are both
+strings.  The default action (usually invoked by clicking the
+notification) should have a key named @samp{"default"}.  The title can
+be anything, though implementations are free not to display it.
+
address@hidden :timeout @var{timeout}
+The timeout time in milliseconds since the display of the notification
+at which the notification should automatically close.  If -1, the
+notification's expiration time is dependent on the notification
+server's settings, and may vary for the type of notification.  If 0,
+the notification never expires.  Default value is -1.
+
address@hidden :urgency @var{urgency}
+The urgency level.  It can be  @code{low}, @code{normal} or @code{critical}.
+
address@hidden :category @var{category}
+The type of notification this is, a string.
+
address@hidden :desktop-entry @var{filename}
+This specifies the name of the desktop filename representing the
+calling program, like @samp{"emacs"}.
+
address@hidden :image-data (@var{width} @var{height} @var{rowstride} 
@var{has-alpha} @var{bits} @var{channels} @var{data})
+This is a raw data image format which describes the width, height,
+rowstride, has alpha, bits per sample, channels and image data
+respectively.
+
address@hidden :image-path @var{path}
+This is represented either as a URI (@samp{file://} is the only URI
+schema supported right now) or a name in a freedesktop.org-compliant
+icon theme from @samp{$XDG_DATA_DIRS/icons}, like @samp{"mail-message-new"}.
+
address@hidden :sound-file @var{filename}
+The path to a sound file to play when the notification pops up.
+
address@hidden :sound-name @var{name}
+A themable named sound from the freedesktop.org sound naming
+specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the
+notification pops up.  Similar to the icon name, only for sounds. An
+example would be @samp{"message-new-instant"}.
+
address@hidden :suppress-sound
+Causes the server to suppress playing any sounds, if it has that
+ability.
+
address@hidden :x @var{position}
address@hidden :y @var{position}
+Specifies the X respectively Y location on the screen that the
+notification should point to.  Both arguments must be used together.
+
address@hidden :on-action @var{function}
+Function to call when an action is invoked.  The notification @var{id}
+and the @var{key} of the action are passed as arguments to the
+function.
+
address@hidden :on-close @var{function}
+Function to call when the notification has been closed by timeout or
+by the user.  The function receive the notification @var{id} and the closing
address@hidden as arguments:
+
address@hidden
address@hidden @code{expired} if the notification has expired
address@hidden @code{dismissed} if the notification was dismissed by the user
address@hidden @code{close-notification} if the notification was closed by a 
call to
address@hidden
address@hidden @code{undefined} if the notification server hasn't provided a 
reason
address@hidden itemize
address@hidden table
+
+This function returns a notification id, an integer, which can be used
+to manipulate the notification item with
address@hidden or the @code{:replaces-id}
+argument of another @code{notifications-notify} call.
+
+Example:
+
address@hidden
address@hidden
+(defun my-on-action-function (id key)
+  (message "Message %d, key \"%s\" pressed" id key))
+     @result{} my-on-action-function
address@hidden group
+
address@hidden
+(defun my-on-close-function (id reason)
+  (message "Message %d, closed due to \"%s\"" id reason))
+     @result{} my-on-close-function
address@hidden group
+
address@hidden
+(notifications-notify
+ :title "Title"
+ :body "This is <b>important</b>."
+ :actions '("Confirm" "I agree" "Refuse" "I disagree")
+ :on-action 'my-on-action-function
+ :on-close 'my-on-close-function)
+     @result{} 22
address@hidden group
+
address@hidden
+A message window opens on the desktop.  Press "I agree"
+     @result{} Message 22, key "Confirm" pressed
+        Message 22, closed due to "dismissed"
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden notifications-close-notification id
+This function closes a notification with identifier ID.
address@hidden defun
+
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries
 @cindex dynamic libraries

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-03-25 07:58:59 +0000
+++ b/doc/lispref/vol1.texi     2012-04-03 08:10:17 +0000
@@ -1412,6 +1412,8 @@
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
+* Notifications::           Desktop notifications.
+* Dynamic Libraries::       On-demand loading of support libraries.
 
 Preparing Lisp code for distribution
 

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-03-25 07:58:59 +0000
+++ b/doc/lispref/vol2.texi     2012-04-03 08:10:17 +0000
@@ -1411,6 +1411,8 @@
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
+* Notifications::           Desktop notifications.
+* Dynamic Libraries::       On-demand loading of support libraries.
 
 Preparing Lisp code for distribution