diff --git a/README.md b/README.md
index 10bcff5..6211e7a 100644
--- a/README.md
+++ b/README.md
@@ -37,13 +37,264 @@ luacheck .
## Configuration Documentation
-<!-- TO DO -->
+This project is fully-customizable from configuration. It means that you can _safely_ pull latest changes without tweaking any Lua code (:sunglasses:).
+The main idea is to describe the content of two "columns", displayed on your screen (please refer to the screen-shot above).
+To achieve this, you can either use pre-defined types of entity (detailed below) or tweak global settings.
+
+<details>
+<summary>Comprehensive documentation of the `config.json` file</summary>
+<p>
+
+<!-- JS syntax to allow comments in JSON ;-) -->
+
+```javascript
+{
+ "settings": {
+ "conky": {
+ // Specific settings related to Conky itself.
+ // You can read further information about them here : <https://github.com/brndnmtthws/conky/wiki/Configurations#settings>.
+ // Entries present by default are mostly mine, working against a Cinnamon setup.
+ },
+ "timers": {
+ // Number of iterations to wait before drawing anything on the screen.
+ // It allows Conky to initialize its internals and gather some data before rendering anything.
+ // You MAY lower this value at your own risks.
+ "startup_threshold": 3,
+
+ // Number of iterations to wait before checking the user configuration (and reloading Conky if it changed).
+ // Use `null` to disable this behavior (default).
+ "config_autoreload": null,
+
+ // Number of iterations to wait before gathering current screen resolutions (and reloading Conky if it changed).
+ // This option is very useful if you are used to plug your laptop on a dock or play with multiple screens.
+ "resolution_autodetect": null
+ },
+ "display": {
+ // The width (in pixels) of the two columns drawn on screen.
+ // You MAY lower this value, but don't forget about very long content that could be displayed (i.e. IPv6 addresses).
+ "columns_width": 460,
+
+ // A subcommand to be run in order to retrieve the current screen dimensions (output MUST be formatted as `${WIDTH}x${HEIGHT}`).
+ "resolution_exec": "xdpyinfo | grep dimensions | tr -s ' ' | cut -d ' ' -f 3"
+ },
+ "font": {
+ // The font size and family to be used when writing down text on the screen.
+ // The font family SHOULD be a "Monospaced" one (see <https://en.wikipedia.org/wiki/Monospaced_font>).
+ "size": 15,
+ "family": "Consolas"
+ },
+ "colors": {
+ // Below colors are defined as RGBA values.
+ // Keys speak for themselves.
+ "default": [1, 1, 1, 1],
+ "clock_second_hand": [1, 0, 0, 1],
+ "bar_background": [0.4, 0.4, 0.4, 1],
+ "graph_in": [0, 0.5, 0.66, 1],
+ "graph_out": [1, 0.5, 0, 1]
+ },
+ "temperature": {
+ // The temperature unit that will be employed.
+ // You can either specify `F` for Fahrenheit or `C` for Celsius (default).
+ "unit": "C",
+
+ // The degree symbol that should be set before the unit.
+ // Please be careful, the one set by default required you to use a font family supporting Unicode.
+ "degree": "°",
+
+ // The string that will be added to any temperature exceeding the set threshold (see `{drive,sensor}_temperature` entities below)
+ "warning": "/!\\"
+ }
+ },
+ "content": {
+ // Entities are represented by a list of objects, each one containing (at least) a `type`.
+ // This first list will describe entities set within the left column.
+ "left": [
+ {
+ // This entity will display a clock, as present on the screen-shot above.
+ "type": "clock"
+ },
+ {
+ // This entity will render the current date-time and output it as a 'text' object.
+ // This is a regular 'text' object underly, so you MAY tweak the `align_center` setting (see `text` entity below).
+ "type": "date_time",
+ "format": "%H:%M:%S, %A %d/%m/%Y",
+ "align_center": true
+ },
+ {
+ // This entity will display an horizontal line, allowing you to separate entities and thus creating "blocks".
+ "type": "separator"
+ },
+ {
+ // A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'text' object.
+ // For example, the lines below would produce : "Hostname: ${nodename}".
+ //
+ // `arg` is fully-optional and MAY be omitted.
+ //
+ // `align_center` is fully-optional and defaults to `false`.
+ "type": "text",
+ "var": "nodename",
+ "arg": "",
+ "name": "Hostname",
+ "align_center": false
+ },
+ {
+ // This is the most powerful entity currently available.
+ // It allows you to execute (synchronously though) a subcommand and show the (STDOUT) result as a 'text' object.
+ // For example, on Debian, the lines below MIGHT produce : "Updates: 42 available".
+ //
+ // `interval` represents the number of iterations to wait before executing the command again (the output is cached).
+ // Please be careful, with `update_interval` Conky setting set to 2 seconds, such a command would be executed each 3600 * 2 seconds, or 2 hours.
+ // You MAY set `interval` to `null` to completely disable value update (the first obtained output would be kept until reloading).
+ // Inversely, you MAY set `interval` to `0` (or even omit the entry) to update it during each iteration (use at your own risks).
+ //
+ // `pre_text` and `post_text` (fully-optional values) allow you to respectively set some texts before and after obtained output.
+ // `align_center` acts described above for `text` entities.
+ //
+ // When the command fails, `on_error` content will be displayed.
+ "type": "command",
+ "exec": "apt list --upgradable -qq 2> /dev/null | wc -l",
+ "name": "Updates",
+ "interval": 3600,
+ "pre_text": "",
+ "post_text": " available",
+ "align_center": false,
+ "on_error": "Not detected"
+ },
+ {
+ // A typical entity that would evaluate `var` and `arg` through Conky and show the result as a 'bar' object.
+ // `arg` is fully-optional and MAY be omitted.
+ //
+ // `show_percent` allows you to add the numerical percentage value next to the `name` of your 'bar' object (disabled by default).
+ //
+ // You MAY use `bar` with any variable evaluating to a valid percentage.
+ "type": "bar",
+ "var": "battery_percent",
+ "arg": "",
+ "name": "Battery",
+ "show_percent": false
+ },
+ {
+ // `brightness` is a very specific entity.
+ // Through `cur_file` and `max_file`, it computes a brightness percentage ratio and produces a 'bar' object.
+ // You SHOULD specify an `interval` to avoid opening and reading two files during each iteration.
+ //
+ // For this entity, `name` is fully-optional and defaults to "Brightness" when not specified.
+ //
+ // `show_percent` is also available and MAY be tweaked.
+ //
+ // Please be careful, set file paths below MAY NOT work on your system.
+ "type": "brightness",
+ "name": "Brightness",
+ "cur_file": "/sys/class/backlight/intel_backlight/actual_brightness",
+ "max_file": "/sys/class/backlight/intel_backlight/max_brightness",
+ "interval": 10,
+ "show_percent": false
+ },
+ {
+ // This entity allows you to show a 'top'-like output for processes, based on their CPU usage.
+ // `max_processes` MAY be set between `1` and `10` (defaults to `10`).
+ "type": "top_processes",
+ "max_processes": 5
+ },
+ {
+ /* ... */
+ }
+ ],
+ // This second list will describe entities set within the right column.
+ "right": [
+ {
+ // This entity relies entirely on the LM-SENSORS program.
+ // It underly uses a `sensors` call to retrieve temperature information from a chip.
+ // The identifier of the `chip` to prompt MUST be specified and could be found by manually running `sensors -A`.
+ // The final displayed value correspond to the chip temperature inputs average.
+ //
+ // `interval` acts as described for `command` type entity (see above).
+ //
+ // `threshold` represents the maximum temperature value that could be reached before adding the symbol specified in `settings.temperature.warning` (see above).
+ // You can either specify Celsius or Fahrenheit, as long as it is consistent to the unit specified in `settings.temperature.unit` (see above too).
+ //
+ // When no temperature could be computed, `on_error` will be displayed.
+ "type": "sensor_temperature",
+ "name": "CPUs",
+ "chip": "coretemp-isa-0000",
+ "interval": 5,
+ "threshold": 70,
+ "on_error": "Not detected"
+ },
+ {
+ // This entity works as the `sensor_temperature` above, but relies on the HDDTEMP program.
+ // You'll have to specify the path to the targeted drive.
+ //
+ // `wake_up` allows you to force drive wake up if needed to measure its temperature (disabled by default).
+ //
+ // `interval`, `threshold` and `on_error` acts as described for `sensor_temperature` type entity (see above).
+ "type": "drive_temperature",
+ "drive": "/dev/sda",
+ "wake_up": false,
+ "interval": 5,
+ "threshold": 60,
+ "on_error": "Not detected"
+ },
+ {
+ // This entity is a handy wrapper to the 'bar' entity.
+ // By specifying any partition `mount_point`, it will display a 'bar' representing its usage.
+ // `show_percent` acts as described above for `bar` entities (see above).
+ "type": "partition_usage",
+ "mount_point": "/home/",
+ "show_percent": false
+ },
+ {
+ // This entity will display two graphs representing the I/O rate of the specified `drive`.
+ // To set graphs colors, please refer to `settings.colors.graph_{in,out}`.
+ "type": "drive_io",
+ "drive": "/dev/sda"
+ },
+ {
+ // This entity will display two graphs representing the I/O rate of the specified network `interface`.
+ // As `drive_io` above, please refer to `settings.colors.graph_{in,out}` to set graphs colors.
+ //
+ // Please be careful, such an entity will be skipped when the interface is down (see `if_up_strictness` for further information).
+ "type": "network_interface_io",
+ "interface": "enp0s25"
+ },
+ {
+ // This entity will display each IP addresses associated to the specified network `interface`.
+ // `hide_v6` allows you to hide any IPv6 address (disabled by default).
+ //
+ // Please be careful, such an entity will be skipped when the interface is down (see `if_up_strictness` for further information).
+ "type": "network_interface_addr",
+ "interface": "enp0s25",
+ "hide_v6": false
+ },
+ {
+ // This entity is a disguised 'text' object.
+ // It allows you to show Conky version, with `{pre,post}_text` (active as within the `command` entity).
+ //
+ // `align_center` is available and acting as described above.
+ //
+ // It could be very useful to give you credits on screen-shot for instance.
+ "type": "version",
+ "pre_text": "Horloge's script on ",
+ "post_text": "",
+ "align_center": true
+ },
+ {
+ /* ... */
+ }
+ ]
+ }
+}
+```
+
+</p>
+</details>
## Frequently asked questions
-### My Conky does not work, it <insert your very specific issue details>. What should I do ?
+### My Conky does not work, it \[insert your very specific issue details here\]. What should I do ?
-Please, refer to the [official Conky's FAQ](https://github.com/brndnmtthws/conky/wiki/FAQ) first.
+Please, refer to the [official Conky's FAQ](https://github.com/brndnmtthws/conky/wiki/FAQ) first.
+If you can't find anything helpful, please [contact me](mailto:dev+conky@samuel.domains) with Conky terminal output attached.
### Your script is cool but I'd like to install it elsewhere. How could I achieve that ?
@@ -53,6 +304,9 @@ You'll have to tweak your `conky` execution with an additional environment varia
CONKY_PATH="/another/path/to/" conky -c /another/path/to/conky.lua
```
+> Rationale : There is no way to fetch the project location from the configuration file itself (`conky.lua`).
+> Fortunately for us, we may read Conky environment variables !
+
### How can I get the same background image ?
[There](https://unsplash.com/photos/44t1AZNIMIE) it is !
diff --git a/lua/loading.lua b/lua/loading.lua
index c5b50ca..bd5779d 100644
--- a/lua/loading.lua
+++ b/lua/loading.lua
@@ -335,13 +335,13 @@ function loading.load_entities(display, number_of_updates)
CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_WEIGHT_NORMAL)
cairo_set_font_size(display, _settings.font.size)
- -- Load entities in the left-column.
+ -- Load entities in the left column.
for _, entity in ipairs(_content.left) do _load_entity(entity) end
- -- Reset the "cursor" position to draw on the right-column.
+ -- Reset the "cursor" position to draw on the right column.
x_pos, y_pos = (conky_window.width - _settings.display.columns_width), 0
- -- Load entities in the right-column.
+ -- Load entities in the right column.
for _, entity in ipairs(_content.right) do _load_entity(entity) end
end