A better README for libravatar plugin
[claws.git] / src / plugins / libravatar / README
1 Libravatar plugin for Claws Mail
2 ================================
3
4 1. What is it for?
5 2. Network issues
6 3. Cache details
7 4. Reporting bugs
8
9 1. What is it for?
10 ------------------
11
12 This plugin allows showing the profile picture associated to email
13 addresses provided by https://www.libravatar.org/. You can read
14 more about what is this at http://wiki.libravatar.org/description/.
15
16 By default missing profiles in the libravatar site are also searched
17 in http://gravatar.com, so it will also show pictures from gravatar
18 profiles. This can be turned off by disallowing redirects.
19
20 When profile is missing in both sites there's options to use a
21 'generated' avatar instead. It's also possible to not generate
22 anything. In that case no image will be added and the existing
23 Face/X-Face machinery will operate as usual, allowing to show the
24 avatar images provided by those headers when no profile picture
25 exists in the servers.
26
27 2. Network issues
28 -----------------
29
30 This plugin requires a reliable network connection to work. If your
31 connection is unreliable or has high latency you're going to experience
32 delays when viewing messages for first time (or always if you disable
33 cache, which is not recommended, of course).
34
35 Another option to alleviate high network latency is to install a local
36 libravatar server (see http://wiki.libravatar.org/running_your_own/),
37 then change the “base_url” hidden property on your ~/.claws-mail/clawsrc
38 file to point your local server URL instead of Libravatar project's URL.
39
40 Yet another option is using a caching proxy on your network.
41
42 This plugin uses libcurl to download images, so proxy support is
43 already implemented. You just need to set the “http_proxy” variable
44 in your environment before launching Claws Mail (see ENVIRONMENT
45 section in curl(1) manpage for details).
46
47 3. Cache details
48 ----------------
49
50 This plugin saves retrieved images for later reuse instead of making
51 a network request on every message. Cache directory is in
52 ~/.claws-mail/avatarcache. Does also save the missing ones in a
53 special file to avoid filling the cache with empty files.
54
55 You can control how much time will be kept there before trying to
56 download them again. Missing items are valid for more time, 7 times
57 your configured interval cache time. You can disable the image cache,
58 but notice that write access to avatarcache is still required.
59 Missing cache cannot be disabled.
60
61 4. Reporting bugs
62 -----------------
63
64 The TODO file contains more known issues/enhancements, please read it
65 before reporting bugs.
66
67 -- 
68 Ricardo Mones <ricardo@mones.org>
69