Merge pull request #2 from keszybz/master

Python 3 and UTF-8

1 files changed, 29 insertions, 8 deletions

diff --git a/README.md b/README.md
index 21e9111..3fc925e 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 journald-python
 ===============
 
-Python module for native access to the journald facilities in recent versions of systemd. In particular, this capability includes passing key/value pairs as fields that journald can use for filtering.
+Python module for native access to the journald facilities in recent
+versions of systemd. In particular, this capability includes passing
+key/value pairs as fields that journald can use for filtering.
 
 Installation
 ============
@@ -17,16 +19,35 @@ Usage
 Quick example:
 
     import journald
-    journald.send('MESSAGE=Hello world.')
-    journald.send('MESSAGE=Hello, again, world.', 'FIELD2=Greetings!', 'FIELD3=Guten tag.')
-    journald.send('ARBITRARY=anything', 'FIELD3=Greetings!')
+    journald.send('Hello world')
+    journald.send('Hello, again, world', FIELD2='Greetings!', FIELD3='Guten tag')
+    journald.send('Binary message', BINARY=b'\xde\xad\xbe\xef')
+
+There is one required argument -- the message, and additional fields
+can be specified as keyword arguments. Following the journald API, all
+names are uppercase.
+
+The journald sendv call can also be accessed directly:
+
+    import journald
+    journald.sendv('MESSAGE=Hello world')
+    journald.sendv('MESSAGE=Hello, again, world', 'FIELD2=Greetings!',
+                   'FIELD3=Guten tag')
+    journald.sendv('MESSAGE=Binary message', b'BINARY=\xde\xad\xbe\xef')
+
+The two examples should give the same results in the log.
 
 Notes:
 
- * Each argument must be in the form of a KEY=value pair, environmental variable style.
- * Unlike the native C version of journald's sd_journal_send(), printf-style substitution is not supported. Perform any substitution using Python's % operator or .format() capabilities first.
- * The base message is usually sent in the form MESSAGE=hello. The MESSAGE field is, however, not required.
- * Invalid or zero arguments results in nothing recorded in journald.
+ * Unlike the native C version of journald's sd_journal_send(),
+   printf-style substitution is not supported. Perform any
+   substitution using Python's % operator or .format() capabilities
+   first.
+ * The base message is usually sent in the form MESSAGE=hello. The
+   MESSAGE field is, however, not required.
+ * A ValueError is thrown is thrown if sd_journald_sendv() results in
+   an error. This might happen if there are no arguments or one of them
+   is invalid.
 
 Viewing Output
 ==============