X-Git-Url: https://git.madduck.net/etc/awesome.git/blobdiff_plain/299798e1c505d3c1477405a62e8669f37fc974b2..d2ec840058a6de4eaafe57fe66953ede542815e6:/imap.md?ds=inline

diff --git a/imap.md b/imap.md
index cf5324d..b0d5375 100644
--- a/imap.md
+++ b/imap.md
@@ -1,28 +1,16 @@
 [<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
 
-**Please be warned**: as for now, this works fine in normal link situations, but is discouraged to use it if your connection is sobbing, since it may cause some short freezes due to timeout issues. I am working on socket libraries to solve this. If you're a Python programmer, feel free to lend a hand.
+Shows mail count in a textbox fetching over IMAP.
 
----
-
-Shows mail status in a textbox over IMAP protocol.
-
-New mails are notified through a notification like this:
-
-	+---------------------------------------------------+
-	| +---+                                             |
-	| |\ /| donald@disney.org has 3 new messages        |
-	| +---+                                             |
-	|       Latest From: Mickey Mouse <boss@disney.org> |
-    |       Subject: Re: pay raise                      |
-    |                                                   |
-    |       Not after what you did yesterday.           |
-    |       Daisy told me everything [...]              |
-	|                                                   |
-	+---------------------------------------------------+
+	myimapcheck = lain.widgets.imap(args)
 
-Text will be cut if the mail is too long.
+New mails are notified like this:
 
-	myimapcheck = lain.widgets.imap(args)
+	+--------------------------------------------+
+	| +---+                                      |
+	| |\ /| donald@disney.org has 3 new messages |
+	| +---+                                      |
+	+--------------------------------------------+
 
 The function takes a table as argument. Required table parameters are:
 
@@ -38,40 +26,45 @@ Variable | Meaning | Type | Default
 --- | --- | --- | ---
 `port` | IMAP port | int | 993
 `timeout` | Refresh timeout seconds | int | 60
-`encoding` | Mail character encoding | string | autodetected
-`maxlen` | Maximum chars to display in notification | int | 200
 `is_plain` | Define whether `password` is a plain password (true) or a function that retrieves it (false) | boolean | false
 `settings` | User settings | function
 
 Let's focus better on `is_plain`.
 
-You can just set your password like this:
+The reason why it's false by default is to discourage the habit of storing passwords in plain files.
+
+You can set your password in plain like this:
 
-    args.is_plain = false
-    args.password = "mypassword"
+    myimapcheck = lain.widgets.imap({
+        is_plain = true,
+        password = "myplainpassword",
+        [...]
+    })
 
 and you'll have the same security provided by `~/.netrc`.
 
 **Or** you can use a keyring, like [python keyring](https://pypi.python.org/pypi/keyring):
 
-    args.password = "keyring get password"
+    myimapcheck = lain.widgets.imap({
+        is_plain = true,
+        password = "myplainpassword",
+        server   = "mail.autistici.org",
+        mail     = "dada@anche.no",
+    })
 
 When `is_plain == false`, it *executes* `password` before using it, so you can also use whatever password fetching solution you want.
 
-`settings` can use the string `mailcount`, whose possible values are:
+`settings` can use the value `mailcount`, an integer greater or equal to zero, and can modify `mail_notification_preset` table, which will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. 
 
-- "0"
-- "invalid credentials"
-- string number
+Default definition:
 
-and can modify `notification_preset` table, which will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. Default definition:
-
-    notification _preset = {
+    mail_notification _preset = {
        icon = lain/icons/mail.png,
-       timeout = 8,
        position = "top_left"
     }
 
+Note that `mailcount` is 0 either if there are no new mails or credentials are invalid, so make sure you get the right settings.
+
 ### output 
 
 A textbox.
\ No newline at end of file