diff --git a/README.md b/README.md
index af094ef..bc43436 100644
--- a/README.md
+++ b/README.md
@@ -102,137 +102,6 @@ vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3)
```
-## Format functions
-
-You can use a function instead of a string as the format parameter.
-Then you are able to check the value returned by the widget type and
-change it or perform some action. You can change the color of the
-battery widget when it goes below a certain point, hide widgets when
-they return a certain value or maybe use `string.format` for padding.
-
-Do not confuse this with just coloring the widget, in those cases standard
-Pango markup can be inserted into the format string.
-
-The format function will get the widget as its first argument, table
-with the values otherwise inserted into the format string as its
-second argument, and will return the text/data to be used for the
-widget.
-
-### Examples
-
-#### Hide mpd widget when no song is playing
-
-```lua
-mpdwidget = wibox.widget.textbox()
-vicious.register(
- mpdwidget,
- vicious.widgets.mpd,
- function (widget, args)
- if args["{state}"] == "Stop" then
- return ''
- else
- return ('MPD: %s - %s'):format(
- args["{Artist}"], args["{Title}"])
- end
- end)
-```
-
-#### Use string.format for padding
-
-```lua
-uptimewidget = wibox.widget.textbox()
-vicious.register(uptimewidget, vicious.widgets.uptime,
- function (widget, args)
- return ("Uptime: %02d %02d:%02d "):format(
- args[1], args[2], args[3])
- end, 61)
-```
-
-When it comes to padding it is also useful to mention how a widget can be
-configured to have a fixed width. You can set a fixed width on your textbox
-widgets by changing their `width` field (by default width is automatically
-adapted to text width). The following code forces a fixed width of 50 px to the
-uptime widget, and aligns its text to the right:
-
-```lua
-uptimewidget = wibox.widget.textbox()
-uptimewidget.width, uptimewidget.align = 50, "right"
-vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
-```
-
-#### Stacked graph
-
-Stacked graphs are handled specially by Vicious: `format` functions passed to
-the corresponding widget types must return an array instead of a string.
-
-```lua
-cpugraph = wibox.widget.graph()
-cpugraph:set_stack(true)
-cpugraph:set_stack_colors({"red", "yellow", "green", "blue"})
-vicious.register(cpugraph, vicious.widgets.cpu,
- function (widget, args)
- return {args[2], args[3], args[4], args[5]}
- end, 3)
-```
-
-The snipet above enables graph stacking/multigraph and plots usage of all four
-CPU cores on a single graph.
-
-#### Substitute widget types' symbols
-
-If you are not happy with default symbols used in volume, battery, cpufreq and
-other widget types, use your own symbols without any need to modify modules.
-The following example uses a custom table map to modify symbols representing
-the mixer state: on or off/mute.
-
-```lua
-volumewidget = wibox.widget.textbox()
-vicious.register(volumewidget, vicious.widgets.volume,
- function (widget, args)
- local label = {["♫"] = "O", ["♩"] = "M"}
- return ("Volume: %d%% State: %s"):format(
- args[1], label[args[2]])
- end, 2, "PCM")
-```
-
-#### Get data from the widget
-
-`vicious.call` could be useful for naughty notification and scripts:
-
-```lua
-mybattery = wibox.widget.textbox()
-vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
-mybattery:buttons(awful.util.table.join(
- awful.button(
- {}, 1,
- function ()
- naughty.notify{title = "Battery indicator",
- text = vicious.call(vicious.widgets.bat,
- "Remaining time: $3", "0")}
- end)))
-```
-
-Format functions can be used as well:
-
-```lua
-mybattery:buttons(awful.util.table.join(
- awful.button(
- {}, 1,
- function ()
- naughty.notify{
- title = "Battery indicator",
- text = vicious.call(
- vicious.widgets.bat,
- function (widget, args)
- return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
- "Remaining time", args[3],
- "Wear level", args[4],
- "Present rate", args[5])
- end, "0")}
- end)))
-```
-
-
## Contributing
For details, see CONTRIBUTING.md. Vicious is licensed under GNU GPLv2+,
diff --git a/docs/source/format.rst b/docs/source/format.rst
new file mode 100644
index 0000000..49b93c4
--- /dev/null
+++ b/docs/source/format.rst
@@ -0,0 +1,137 @@
+.. _format-func:
+
+Format Functions
+================
+
+You can use a function instead of a string as the format parameter.
+Then you are able to check the value returned by the widget type
+and change it or perform some action. You can change the color of
+the battery widget when it goes below a certain point, hide widgets
+when they return a certain value or maybe use ``string.format`` for padding.
+
+Do not confuse this with just coloring the widget, in those cases
+standard Pango markup can be inserted into the format string.
+
+The format function will get the widget as its first argument, table with
+the values otherwise inserted into the format string as its second argument,
+and will return the text/data to be used for the widget.
+
+Examples
+--------
+
+Hide mpd widget when no song is playing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: lua
+
+ mpdwidget = wibox.widget.textbox()
+ vicious.register(
+ mpdwidget,
+ vicious.widgets.mpd,
+ function (widget, args)
+ if args["{state}"] == "Stop" then
+ return ''
+ else
+ return ('MPD: %s - %s'):format(
+ args["{Artist}"], args["{Title}"])
+ end
+ end)
+
+Use string.format for padding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: lua
+
+ uptimewidget = wibox.widget.textbox()
+ vicious.register(uptimewidget, vicious.widgets.uptime,
+ function (widget, args)
+ return ("Uptime: %02d %02d:%02d "):format(
+ args[1], args[2], args[3])
+ end, 61)
+
+When it comes to padding it is also useful to mention how a widget
+can be configured to have a fixed width. You can set a fixed width on
+your textbox widgets by changing their ``width`` field (by default width
+is automatically adapted to text width). The following code forces
+a fixed width of 50 px to the uptime widget, and aligns its text to the right:
+
+.. code-block:: lua
+
+ uptimewidget = wibox.widget.textbox()
+ uptimewidget.width, uptimewidget.align = 50, "right"
+ vicious.register(uptimewidget, vicious.widgets.uptime, "$1 $2:$3", 61)
+
+Stacked graph
+^^^^^^^^^^^^^
+
+Stacked graphs are handled specially by Vicious: ``format`` functions passed
+to the corresponding widget types must return an array instead of a string.
+
+.. code-block:: lua
+
+ cpugraph = wibox.widget.graph()
+ cpugraph:set_stack(true)
+ cpugraph:set_stack_colors{ "red", "yellow", "green", "blue" }
+ vicious.register(cpugraph, vicious.widgets.cpu,
+ function (widget, args)
+ return { args[2], args[3], args[4], args[5] }
+ end, 3)
+
+The snipet above enables graph stacking/multigraph and plots usage of all four
+CPU cores on a single graph.
+
+Substitute widget types' symbols
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are not happy with default symbols used in volume, battery, cpufreq and
+other widget types, use your own symbols without any need to modify modules.
+The following example uses a custom table map to modify symbols representing
+the mixer state: on or off/mute.
+
+.. code-block:: lua
+
+ volumewidget = wibox.widget.textbox()
+ vicious.register(volumewidget, vicious.widgets.volume,
+ function (widget, args)
+ local label = { ["🔉"] = "O", ["🔈"] = "M" }
+ return ("Volume: %d%% State: %s"):format(
+ args[1], label[args[2]])
+ end, 2, "PCM")
+
+.. _call-example:
+
+Get data from the widget
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+:lua:func:`vicious.call` could be useful for naughty notification and scripts:
+
+.. code-block:: lua
+
+ mybattery = wibox.widget.textbox()
+ vicious.register(mybattery, vicious.widgets.bat, "$2%", 17, "0")
+ mybattery:buttons(awful.util.table.join(awful.button(
+ {}, 1,
+ function ()
+ naughty.notify{ title = "Battery indicator",
+ text = vicious.call(vicious.widgets.bat,
+ "Remaining time: $3", "0") }
+ end)))
+
+Format functions can be used as well:
+
+.. code-block:: lua
+
+ mybattery:buttons(awful.util.table.join(awful.button(
+ {}, 1,
+ function ()
+ naughty.notify{
+ title = "Battery indicator",
+ text = vicious.call(
+ vicious.widgets.bat,
+ function (widget, args)
+ return ("%s: %10sh\n%s: %14d%%\n%s: %12dW"):format(
+ "Remaining time", args[3],
+ "Wear level", args[4],
+ "Present rate", args[5])
+ end, "0") }
+ end)))
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 05109a4..7e115e7 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -16,12 +16,13 @@ Table of Contents
-----------------
.. toctree::
- :maxdepth: 2
+ :titlesonly:
usage-lua
usage-awesome
widgets
custom
+ format
caching
security
copying
diff --git a/docs/source/usage-awesome.rst b/docs/source/usage-awesome.rst
index 0af59d1..5d97921 100644
--- a/docs/source/usage-awesome.rst
+++ b/docs/source/usage-awesome.rst
@@ -48,7 +48,7 @@ call ``vicious.register`` to register it with Vicious:
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)).
+ by the widget type (see :ref:`format-func`).
:param interval: number of seconds between updates of the widget
(default: 2). See :ref:`caching` for more information.
@@ -111,7 +111,7 @@ vicious.call
.. lua:function:: vicious.call(wtype, format, warg)
Fetch data from the widget type to use it outside of the widget
- ([example](#call-example)).
+ (:ref:`example `).
:param wtype:
either of
@@ -130,7 +130,7 @@ vicious.call
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)).
+ by the widget type (see :ref:`format-func`).
:param warg: arguments to be passed to widget types, e.g. the battery ID.