[docs] Move caching and security notes from README

Author: McSinyx

README.md

@@ -466,71 +466,6 @@ vicious.register. Your function can accept `format` and `warg`
 arguments, just like workers.
 
 
-## <a name="power"></a>Power and Caching
-
-When a lot of widgets are in use they, and awesome, can generate a lot
-of wake-ups and also be very expensive for system resources. This is
-especially important when running on battery power. It was a big
-problem with awesome v2 and widgets that used shell scripts to gather
-data, and with widget libraries written in languages like Ruby.
-
-Lua is an extremely fast and efficient programming language, and
-Vicious takes advantage of that. But suspending Vicious widgets is one
-way to prevent them from draining your battery, despite that.
-
-Update intervals also play a big role, and you can save a lot of power
-with a smart approach. Don't use intervals like: 5, 10, 30, 60, … to
-avoid harmonics. If you take the 60-second mark as an example, all of
-your widgets would be executed at that point. Instead think about
-using only prime numbers, in that case you will have only a few
-widgets executed at any given time interval. When choosing intervals
-also consider what a widget actually does. Some widget types read
-files that reside in memory, others call external utilities and some,
-like the mbox widget, read big files.
-
-Vicious can also cache values returned by widget types. Caching
-enables you to have multiple widgets using the same widget type. With
-caching its worker function gets executed only once - which is also
-great for saving power.
-
-* Some widget types keep internal data and if you call one multiple times
-  without caching, the widget that executes it first would modify stored
-  values. This can lead to problems and give you inconsistent data. Remember
-  it for widget types like CPU and Network usage, which compare the old set of
-  data with the new one to calculate current usage.
-
-* Widget types that require a widget argument to be passed should be handled
-  carefully. If you are requesting information for different devices then
-  caching should not be used, because you could get inconsistent data.
-
-
-## Security
-
-At the moment only one widget type (Gmail) requires auth. information
-in order to get to the data. In the future there could be more, and
-you should give some thought to the issue of protecting your data. The
-Gmail widget type by default stores login information in the ~/.netrc
-file, and you are advised to make sure that file is only readable by
-the owner. Other than that we can not force all users to conform to
-one standard, one way of keeping it secure, like in some keyring.
-
-First let's clear why we simply don't encrypt the login information
-and store it in ciphertext. By exposing the algorithm anyone can
-reverse the encryption steps. Some claim even that's better than
-plaintext but it's just security trough obscurity.
-
-Here are some ideas actually worth your time. Users that have KDE (or
-parts of it) installed could store their login information into the
-Kwallet service and request it via DBus from the widget type. It can
-be done with tools like `dbus-send` and `qdbus`. The Gnome keyring
-should support the same, so those with parts of Gnome installed could
-use that keyring.
-
-Users of GnuPG (and its agent) could consider encrypting the netrc
-file with their GPG key. Trough the GPG Passphrase Agent they could
-then decrypt the file transparently while their session is active.
-
-
 ## Usage examples
 
 Start with a simple widget, like `date`. Then build your setup from

docs/source/caching.rst

@@ -0,0 +1,37 @@
+.. _caching:
+
+Power and Caching
+=================
+
+When a lot of widgets are in use they, and awesome, can generate a lot
+of wake-ups and also be very expensive for system resources.  This is
+especially important when running on battery power.  It was a big problem
+with awesome v2 and widgets that used shell scripts to gather data,
+and with widget libraries written in languages like Ruby.
+
+Lua is an extremely fast and efficient programming language, and Vicious
+takes advantage of that.  But suspending Vicious widgets is one way
+to prevent them from draining your battery, despite that.
+
+Update intervals also play a big role, and you can save a lot of power
+with a smart approach.  Don't use intervals like: 5, 10, 30, 60, etc.
+to avoid harmonics.  If you take the 60-second mark as an example,
+all of your widgets would be executed at that point.  Instead think about
+using only prime numbers, in that case you will have only a few widgets
+executed at any given time interval.  When choosing intervals also consider
+what a widget actually does.  Some widget types read files that reside
+in memory, others call external utilities and some, like the mbox widget,
+read big files.
+
+Vicious can also cache values returned by widget types.  Caching enables you
+to have multiple widgets using the same widget type.  With caching its worker
+function gets executed only once---which is also great for saving power.
+
+* Some widget types keep internal data and if you call one multiple times
+  without caching, the widget that executes it first would modify stored values.
+  This can lead to problems and give you inconsistent data.  Remember it
+  for widget types like CPU and Network usage, which compare the old set
+  of data with the new one to calculate current usage.
+* Widget types that require a widget argument to be passed should be
+  handled carefully.  If you are requesting information for different devices
+  then caching should not be used, because you could get inconsistent data.

docs/source/index.rst

@@ -20,6 +20,8 @@ Table of Contents
 
    usage-lua
    usage-awesome
+   caching
+   security
    copying
 
 See Also

docs/source/security.rst

@@ -0,0 +1,27 @@
+Security Notes
+==============
+
+At the moment only one widget type (Gmail) requires
+authentication information in order to get to the data.
+In the future there could be more, and you should give some thought
+to the issue of protecting your data.  The Gmail widget type by default
+stores login information in the ``~/.netrc`` file, and you are advised
+to make sure that file is only readable by the owner.  Other than that
+we can not force all users to conform to one standard,
+one way of keeping it secure, like in some keyring.
+
+First let's clear why we simply don't encrypt the login information
+and store it in ciphertext.  By exposing the algorithm anyone can
+reverse the encryption steps.  Some claim even that's better than
+plaintext but it's just security through obscurity.
+
+Here are some ideas actually worth your time.  Users that have KDE
+(or parts of it) installed could store their login information into
+the Kwallet service and request it via DBus from the widget type.
+It can be done with tools like ``dbus-send`` and ``qdbus``.
+The Gnome keyring should support the same, so those with parts of Gnome
+installed could use that keyring.
+
+Users of GnuPG (and its agent) could consider encrypting the netrc file
+with their GPG key.  Through the GPG Passphrase Agent they could then
+decrypt the file transparently while their session is active.

docs/source/usage-awesome.rst

@@ -46,7 +46,7 @@ Once you create a widget (a textbox, graph or a progressbar) call
 
 ``interval``
    Number of seconds between updates of the widget (default: 2).
-   Read section [Power and Caching](#power) for more information.
+   Read section :ref:`caching` for more information.
 
 ``warg``
    Arguments to be passed to widget types, e.g. the battery ID.