[docs] Move basic instructions from README

README.md

@@ -13,126 +13,6 @@ Lua libraries, but may depend on additional system utilities (see widget
 description).
 
 
-## Usage
-
-When provided by an operating system package, or installed from source
-into the Lua library path Vicious, can be used as a regular Lua
-library, to be used stand-alone or to feed widgets of any window
-manager (e.g. Ion, WMII). It is compatible with Lua version 5.1 and above.
-
-```lua
-> widgets = require("vicious.widgets.init")
-> print(widgets.volume(nil, "Master")[1])
-100
-```
-
-
-## Usage within Awesome
-
-To use Vicious with Awesome, install the package from your operating
-system provider, or download the source code and move it to your
-awesome configuration directory in `$XDG_CONFIG_HOME` (usually `~/.config`):
-
-```bash
-$ git clone https://github.com/vicious-widgets/vicious.git
-$ mv vicious $XDG_CONFIG_HOME/awesome/
-```
-
-Vicious will only load modules for widget types you intend to use in
-your awesome configuration, to avoid having useless modules sitting in
-your memory.
-
-Then add the following to the top of your `rc.lua`:
-
-```lua
-local vicious = require("vicious")
-```
-
-### Register a widget
-
-Once you create a widget (a textbox, graph or a progressbar) call
-`vicious.register()` to register it with Vicious:
-
-    vicious.register(widget, wtype, format, interval, warg)
-
-#### widget
-
-*Awesome* widget created with `widget()` or `awful.widget()` (in case of a
-graph or a progressbar).
-
-#### wtype
-
-Type: Vicious widget or `function`:
-
-* Vicious widget type: any of the available (default, or custom)
-  [widget type provided by Vicious](#widgets).
-* function: custom function from your own *Awesome* configuration can be
-  registered as widget types (see [Custom widget types](#custom-widget)).
-
-#### format
-
-Type: `string` or `function`:
-
-* string: `$key` will be replaced by respective value in the table `t` returned
-  by the widget type. I.e. use `$1`, `$2`, etc. to retrieve data from an
-  integer-indexed table (a.k.a. array); `${foo bar}` will be substituted by
-  `t["{foo bar}"]`.
-* `function (widget, args)` can be used to manipulate data returned by the
-  widget type (see [Format functions](#format-func)).
-
-#### interval
-
-Number of seconds between updates of the widget (default: 2). Read section
-[Power and Caching](#power) for more information.
-
-#### warg
-
-Some widget types require an argument to be passed, for example the battery ID.
-
-`vicious.register` alone is not much different from
-[awful.widget.watch](https://awesomewm.org/doc/api/classes/awful.widget.watch.html),
-which has been added to Awesome since version 4.0. However, Vicious offers more
-advanced control of widgets' behavior by providing the following functions.
-
-### Unregister a widget
-
-    vicious.unregister(widget, keep)
-
-If `keep == true`, `widget` will be suspended and wait for activation.
-
-### Suspend all widgets
-
-    vicious.suspend()
-
-See [example automation script](http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh)
-for the "laptop-mode-tools" start-stop module.
-
-### Restart suspended widgets
-
-    vicious.activate(widget)
-
-If `widget` is provided only that widget will be activated.
-
-### Enable caching of a widget type
-
-    vicious.cache(wtype)
-
-Enable caching of values returned by a widget type.
-
-### Force update of widgets
-
-    vicious.force(wtable)
-
-`wtable` is a table of one or more widgets to be updated.
-
-### Get data from a widget
-
-    vicious.call(wtype, format, warg)
-
-Fetch data from `wtype` to use it outside from the wibox
-([example](#call-example)).
-
-
 ## <a name="widgets"></a>Widget types
 
 Widget types consist of worker functions that take two arguments `format` and

docs/source/index.rst

@@ -16,6 +16,8 @@ library, but may depend on additional system utilities.
    :maxdepth: 2
    :caption: Contents:
 
+   usage-lua
+   usage-awesome
    copying
 
 Indices and tables

docs/source/usage-awesome.rst

@@ -0,0 +1,117 @@
+Usage within Awesome
+====================
+
+To use Vicious with Awesome, install the package from your operating system
+provider, or download the source code and move it to your awesome
+configuration directory in ``$XDG_CONFIG_HOME`` (usually ``~/.config``)::
+
+   git clone https://github.com/vicious-widgets/vicious.git
+   mv vicious $XDG_CONFIG_HOME/awesome/
+
+Vicious will only load modules for widget types you intend to use in
+your awesome configuration, to avoid having useless modules sitting in
+your memory.
+
+Then add the following to the top of your ``rc.lua``:
+
+.. code-block:: lua
+
+   local vicious = require("vicious")
+
+Register a Widget
+-----------------
+
+Once you create a widget (a textbox, graph or a progressbar) call
+``vicious.register()`` to register it with Vicious::
+
+   vicious.register(widget, wtype, format, interval, warg)
+
+``widget``
+   Awesome_ widget created with ``widget()`` or ``awful.widget()``
+   (in case of a graph or a progressbar).
+
+``wtype`` of type Vicious widget or ``function``
+   * Vicious widget type: any of the available (default, or custom)
+     [widget type provided by Vicious](#widgets).
+   * function: custom function from your own *Awesome* configuration can be
+     registered as widget types (see [Custom widget types](#custom-widget)).
+
+``format`` of type ``string`` or ``function``
+   * string: ``$key`` will be replaced by respective value in the table ``t``
+     returned by the widget type. I.e. use ``$1``, ``$2``, etc. to retrieve data
+     from an integer-indexed table (a.k.a. array); ``${foo bar}`` will be
+     substituted by ``t["{foo bar}"]``.
+   * ``function (widget, args)`` can be used to manipulate data returned by the
+     widget type (see [Format functions](#format-func)).
+
+``interval``
+   Number of seconds between updates of the widget (default: 2).
+   Read section [Power and Caching](#power) for more information.
+
+``warg``
+   Arguments to be passed to widget types, e.g. the battery ID.
+
+``vicious.register`` alone is not much different from awful.widget.watch_,
+which has been added to Awesome since version 4.0.  However, Vicious offers
+more advanced control of widgets' behavior by providing the following functions.
+
+Unregister a Widget
+-------------------
+
+::
+
+   vicious.unregister(widget, keep)
+
+If ``keep == true``, ``widget`` will be suspended and wait for activation.
+
+Suspend All Widgets
+-------------------
+
+::
+
+   vicious.suspend()
+
+See `example automation script`_ for the "laptop-mode-tools" start-stop module.
+
+Restart Suspended Widgets
+-------------------------
+
+::
+
+   vicious.activate(widget)
+
+If ``widget`` is provided only that widget will be activated.
+
+Enable Caching of a Widget Type
+-------------------------------
+
+::
+
+   vicious.cache(wtype)
+
+Enable caching of values returned by a widget type.
+
+Force update of widgets
+-----------------------
+
+::
+
+   vicious.force(wtable)
+
+where ``wtable`` is a table of one or more widgets to be updated.
+
+Get Data from a Widget
+----------------------
+
+::
+
+   vicious.call(wtype, format, warg)
+
+Fetch data from ``wtype`` to use it outside from the wibox
+([example](#call-example)).
+
+.. _Awesome: https://awesomewm.org/
+.. _awful.widget.watch:
+   https://awesomewm.org/doc/api/classes/awful.widget.watch.html
+.. _example automation script:
+   http://sysphere.org/~anrxc/local/sources/lmt-vicious.sh

docs/source/usage-lua.rst

@@ -0,0 +1,15 @@
+Usage as a Lua Library
+======================
+
+When provided by an operating system package, or installed from source
+into the Lua library path, Vicious can be used as a regular Lua_ library,
+to be used stand-alone or to feed widgets of any window manager
+(e.g. Ion, WMII).  It is compatible with Lua 5.1 and above.
+
+.. code-block:: lua
+
+   > widgets = require("vicious.widgets.init")
+   > print(widgets.volume(nil, "Master")[1])
+   100
+
+.. _Lua: https://www.lua.org/