tmisu

commit c4131503bf120cdc6ce2addeefd1e9a32f9d02ff
parent f96762c99192b2e3e89243685045f0e1b643bde2
Author: Santtu Lakkala <inz@inz.fi>
Date:   Sat, 26 Feb 2022 14:16:59 +0200

Update doc

Diffstat:
M
README.md
 | 
63
++++++++++++++++++++++++++++++++++-----------------------------

1 file changed, 34 insertions(+), 29 deletions(-)
diff --git a/README.md b/README.md
@@ -1,46 +1,59 @@
 # Desktop notifications, the UNIX way
 
 tmisu is a notification daemon based on tiramisu that outputs notifications
-to STDOUT in order to allow the user to process notifications any way they prefer.
+to STDOUT in order to allow the user to process notifications any way they
+prefer.
 
-tmisu is basically a rewrite without GLib, and using libdbus instead.
+tmisu as originally a tiramisu rewrite without GLib, and using libdbus instead.
 
 # Why?
 
-By allowing users to determine what is done with notifications, there is infinitely more possibilities presented
-to the end-user than a simple notification daemon that displays a block of text on the screen and nothing more.
+By allowing users to determine what is done with notifications, there are
+infinitely more possibilities presented to the end-user than a simple
+notification daemon that displays a block of text on the screen and nothing
+more.
 
-Users could have notifications display in a pre-existing bar, make a control panel of some sort that shows
-notifications, push notifications to their phone if their computer has been idle for an amount of time,
-make notifications more accessible with text-to-speech, and so much more.
+Users could have notifications display in a pre-existing bar, make a control
+panel of some sort that shows notifications, push notifications to their phone
+if their computer has been idle for an amount of time, make notifications more
+accessible with text-to-speech, and so much more.
 
 # Installation
 
-Clone the repository and build the project. Then move tmisu to a location that is specified in `$PATH`.
-
+Clone the repository and build the project. Then move tmisu to a location that
+is specified in `$PATH`.
 ```
 $ git clone https://git.inz.fi/tmisu/
 $ cd ./tmisu
 $ make
 
-# cp ./tmisu /usr/bin/tmisu
-# chmod +x /usr/bin/tmisu
+# cp ./tmisu /usr/local/bin/tmisu
 ```
-
 #### Note that the use of a pound symbol (#) denotes escalated privileges.
 #### On most Linux systems this can be done with the usage of `sudo`
 
 # Usage
 
-Redirecting output of tmisu to the input of another program is the ideal methodology to using
-tmisu.
-
+Redirecting output of tmisu to the input of another program is the ideal
+methodology to using tmisu.
 ```
 tmisu | your-application
 ```
 
-By default tmisu outputs notifications in a psuedo-key-value line format.
-You can supply the `-j` flag to output notification data in JSON format.
+By default tmisu prints the summaries of all current notifications on one line
+or empty line if there are no notifications.
+
+In JSON mode, tmisu will output all current notifications on one line as an
+JSON array.
+
+tmisu can also be made to call external programs when notifications arrive,
+the programs are expected to act like [herbe](https://github.com/dudik/herbe),
+staying running until notifications has been handled, or it has expired, and
+return 0 if an action should be performed. tmisu will then signal the first
+action defined for the notification.
+
+If the notifications expire, or are explicitly closed, tmisu will signal the
+invoked program with SIGTERM.
 
 ### Example of default output
 
@@ -49,17 +62,8 @@ $ tmisu
 ```
 
 ```
-app_name: evolution-mail-notification
-app_icon: evolution
-replaces_id: 0
-timeout: -1
-hints:
-    desktop-entry: org.gnome.Evolution
-    urgency: 1
-actions:
-    Show INBOX: default
-summary: New email in Evolution
-body: You have received 4 new messages.
+New email in Evolution
+
 ```
 
 ### Example of JSON output
@@ -69,7 +73,8 @@ $ tmisu -j
 ```
 
 ```
-{"app_name": "evolution-mail-notification", "app_icon": "evolution", "replaces_id": 0, "timeout": -1, "hints": {"desktop-entry": "org.gnome.Evolution", "urgency": 1}, "actions": {"Show INBOX": "default"}, "summary": "New email in Evolution", "body": "You have received 4 new messages."}
+[{"app_name": "evolution-mail-notification", "app_icon": "evolution", "replaces_id": 0, "timeout": -1, "hints": {"desktop-entry": "org.gnome.Evolution", "urgency": 1}, "actions": {"Show INBOX": "default"}, "summary": "New email in Evolution", "body": "You have received 4 new messages."}]
+[]
 ```
 
 #### Note that only a single process can claim the org.freedesktop.Notifications name at a given time, so any other running notification daemon must be killed before running tmisu.