README update

1 files changed, 145 insertions, 6 deletions

diff --git a/README.md b/README.md
index c888dda..3243fb8 100644
--- a/README.md
+++ b/README.md
@@ -7,25 +7,164 @@ Requires Python 3.4 or higher.
 Usage
 -----
 
+Pass the `--help` flag to a script to see its detailed usage information.
+
 ### track_status.py
 
 Track when people go online/offline.
 
-    usage: track_status.py [-h] [-t TIMEOUT] [-l LOG] UID [UID ...]
+    usage: track_status.py [-h] [-t TIMEOUT] [-l LOG]
+                           [--output-format {csv,log,null}] [-o OUTPUT]
+                           UID [UID ...]
+
+For example (using made up user IDs/"screen names"),
+
+    > track_status.py john.doe jane.smith
+    [2016-06-18 01:43:34] John Doe is ONLINE.
+    [2016-06-18 01:43:34] John Doe was last seen at 2016-06-18 01:33:58+03:00 using the official iPhone app.
+    [2016-06-18 01:43:34] Jane Smith is OFFLINE.
+    [2016-06-18 01:43:34] Jane Smith was last seen at 2016-06-18 01:15:47+03:00 using the web version (or an unrecognized app).
+    [2016-06-18 01:59:09] Jane Smith went ONLINE.
+    [2016-06-18 01:59:09] Jane Smith was last seen at 2016-06-18 01:59:07+03:00 using the official Android app.
+    [2016-06-18 02:10:00] John Doe went OFFLINE.
+    [2016-06-18 02:10:00] John Doe was last seen at 2016-06-18 01:54:58+03:00 using the official iPhone app.
+    ...
+
+By default, the script produces a human-readable log.
+Use the `--log` parameter to write the log to a file.
+If you want to record when people go online/offline for [further analysis],
+specify the path to a database using the `--output` parameter.
+Be careful: if the file already exists, it will be overwritten!
+
+[further analysis]: #online_durationpy
+
+### online_duration.py
+
+View the amount of time people spent online.
+
+    usage: online_duration.py [-h] [--grouping {user,date,weekday}]
+                              [--input-format {csv,log,null}]
+                              [--output-format {csv,json,img}]
+                              input [output]
+
+This script additionally requires [matplotlib] to be installed.
+
+Analyze the database produced by [track_status.py] and calculate the total
+amount of time people spent online.
+
+For example (assuming the database in "db.csv" was generated by
+[track_status.py] before):
+
+    > online_duration.py db.csv
+    89497105,John,Smith,john.smith,0:12:31
+    3698577,Jane,Smith,jane.smith,1:34:46
+
+In the example above, "John Smith" and "Jane Smith" spent approx. 13 and 95
+minutes online respectively.
+
+The output format is CSV (comma-separated values) by default.
+You can also get a JSON document:
 
-For example,
+    > online_duration.py --output-format json db.csv
+    [
+       {
+          "uid": 89497105,
+          "first_name": "John",
+          "last_name": "Smith",
+          "screen_name": "john.smith",
+          "duration": "0:12:31"
+       },
+       {
+          "uid": 3698577,
+          "first_name": "Jane",
+          "last_name": "Smith",
+          "screen_name": "jane.smith",
+          "duration": "1:34:46"
+       }
+    ]
 
-    > track_status.py egor.tensin id1
+The durations are calculated on a per-user basis by default.
+You can change that by supplying either `date` (to group by dates) or `weekday`
+(to group by weekdays) as the `--grouping` parameter value.
+For example (assuming that both Jane and Joe spent their time online on Friday,
+June 17, 2016).
+
+    > online_duration.py --output-format json --grouping date db.csv
+    [
+       {
+          "date": "2016-06-17",
+          "duration": "1:47:17"
+       }
+    ]
+
+    > online_duration.py --output-format csv --grouping weekday db.csv
+    Monday,0:00:00
+    Tuesday,0:00:00
+    Wednesday,0:00:00
+    Thursday,0:00:00
+    Friday,1:47:17
+    Saturday,0:00:00
+    Sunday,0:00:00
+
+In my opinion, the script's most useful feature is the ability to easily create
+plots that represent the text data (like in the examples above).
+To produce a plot, pass `img` as the `--output-format` parameter value and add
+a file path to write the image to.
+
+    > online_duration.py --output-format img db.csv user.png
+
+![user.png]
+
+    > online_duration.py --output-format img --grouping date db.csv date.png
+
+![date.png]
+
+    > online_duration.py --output-format img --grouping weekday db.csv weekday.png
+
+![weekday.png]
+
+[matplotlib]: http://matplotlib.org/
+[track_status.py]: #track_statuspy
+
+[user.png]: img/online_duration/user.png
+[date.png]: img/online_duration/date.png
+[weekday.png]: img/online_duration/weekday.png
 
 ### mutual_friends.py
 
 Learn who your ex and her new boyfriend are both friends with.
 
-    usage: mutual_friends.py [-h] UID [UID ...]
+    usage: mutual_friends.py [-h] [--output-format {csv,json}] UID [UID ...]
+
+For example (using made up user IDs/"screen names"),
+
+    > mutual_friends.py john.doe jane.doe
+    89497105,John,Smith,john.smith
+    3698577,Jane,Smith,jane.smith
+
+In the example above, both "John Doe" and "Jane Doe" are friends with "John
+Smith" and "Jane Smith", whose user IDs are 89497105 and 3698577 respectively.
+Their "screen names" (the part after "vk.com/" of their personal page URLs) are
+"john.smith" and "jane.smith".
 
-For example,
+The output format is CSV (comma-separated values) by default.
+You can also get a JSON document:
 
-    > mutual_friends.py egor.tensin durov
+    > mutual_friends.py --output-format json john.doe jane.doe
+    [
+       {
+          "uid": 89497105,
+          "first_name": "John",
+          "last_name": "Smith",
+          "screen_name": "john.smith"
+       },
+       {
+          "uid": 3698577,
+          "first_name": "Jane",
+          "last_name": "Smith",
+          "screen_name": "jane.smith"
+       }
+    ]
 
 License
 -------