From bc85f40704530ed2a04ed4a4ebeadf384e8eb18b Mon Sep 17 00:00:00 2001 From: Brenden Matthews Date: Mon, 11 Mar 2024 18:37:30 -0400 Subject: [PATCH] Tidy up docs --- doc/config_settings.yaml | 55 +++++++++---------- doc/lua.yaml | 116 +++++++++++++++++++-------------------- doc/variables.yaml | 35 ++++++------ 3 files changed, 104 insertions(+), 102 deletions(-) diff --git a/doc/config_settings.yaml b/doc/config_settings.yaml index ab393f4f..96e43e9b 100644 --- a/doc/config_settings.yaml +++ b/doc/config_settings.yaml @@ -172,6 +172,13 @@ values: Create an API token at https://github.com/settings/tokens/new?scopes=notifications&description=conky. + - name: graph_gradient_mode + desc: |- + Changes the color space used for interpolation. Arguments are hcl, hsv, + and rgb (default). + args: + - (rgb|hcl|hsv) + default: rgb - name: hddtemp_host desc: |- Hostname to connect to for hddtemp objects. @@ -218,15 +225,6 @@ values: Imlib2 image cache size, in bytes. Increase this value if you use $image lots. Set to 0 to disable the image cache. default: 4194304 - - name: lua_mouse_hook - desc: |- - This function, if defined, will be called by Conky upon receiving mouse - events from X or Wayland. A table containing event information will be - passed to this function as the first argument. Use this hook for detecting - mouse input and acting on it. Conky requires that the function declaration - has a 'conky_' prefix to prevent accidental calls to the wrong function. - args: - - function_name - name: lowercase desc: Boolean value, if true, text is rendered in lower case. - name: lua_draw_hook_post @@ -253,6 +251,15 @@ values: - [function arguments] - name: lua_load desc: Loads the Lua scripts separated by spaces. + - name: lua_mouse_hook + desc: |- + This function, if defined, will be called by Conky upon receiving mouse + events from X or Wayland. A table containing event information will be + passed to this function as the first argument. Use this hook for detecting + mouse input and acting on it. Conky requires that the function declaration + has a 'conky_' prefix to prevent accidental calls to the wrong function. + args: + - function_name - name: lua_shutdown_hook desc: |- This function, if defined, will be called by Conky at @@ -415,18 +422,17 @@ values: background opacity to 0%. - name: own_window_type desc: |- - if own_window is yes, you may specify type normal, desktop, - dock, panel, utility or override. Desktop windows are special - windows that have no window decorations; are always visible on your - desktop; do not appear in your pager or taskbar; and are sticky across - all workspaces. Utility windows are like desktop windows, - except they appear above everything else rather than below. - Panel windows reserve space along a desktop edge, just - like panels and taskbars, preventing maximized windows from - overlapping them. The edge is chosen based on the alignment option. - Override windows are not under the control of the window manager. - Hints are ignored. This type of window can be useful for certain - situations. + If own_window is yes, you may specify type normal, desktop, dock, panel, + utility or override. Desktop windows are special windows that have no + window decorations; are always visible on your desktop; do not appear in + your pager or taskbar; and are sticky across all workspaces. Utility + windows are like desktop windows, except they appear above everything + else rather than below. Panel windows reserve space along a desktop edge, + just like panels and taskbars, preventing maximized windows + from overlapping them. The edge is chosen based on the alignment + option. Override windows are not under the control of the window + manager. Hints are ignored. This type of window can be useful for + certain situations. default: normal - name: pad_percents desc: Pad percentages to this many decimals (0 = no padding). @@ -454,13 +460,6 @@ values: desc: Shows the time range covered by a graph. - name: show_graph_scale desc: Shows the maximum value in scaled graphs. - - name: graph_gradient_mode - desc: |- - Changes the color space used for interpolation. Arguments are hcl, hsv, - and rgb (default). - args: - - (rgb|hcl|hsv) - default: rgb - name: stippled_borders desc: Border stippling (dashing) in pixels. - name: store_graph_data_explicitly diff --git a/doc/lua.yaml b/doc/lua.yaml index e9538cea..1923060a 100644 --- a/doc/lua.yaml +++ b/doc/lua.yaml @@ -30,6 +30,50 @@ desc: |- API, Conky will export a few additional functions for the creation of certain structures. These are documented below. values: + - name: RsvgDimensionData:create() + desc: |- + Call this method to return a new RsvgDimensionData + structure. A creation function for this structure is not provided + by the Rsvg API. + + After calling this, you should use `tolua.takeownership(rect)` on the return + value to ensure ownership is passed properly. + - name: RsvgDimensionData:destroy() + desc: |- + Call this method to free memory allocated by + `RsvgDimensionData:create`. + + You should call `tolua.releaseownership(dd)` before calling this function to + avoid double-frees, but only if you previously called + `tolua.takeownership(dd)` + - name: RsvgDimensionData:get() + desc: |- + Gets the values of an existing RsvgDimensionData. + - name: RsvgDimensionData:set(x, y, width, height) + desc: |- + Sets the values of an existing RsvgDimensionData. + - name: RsvgRectangle:create() + desc: |- + Call this method to return a new RsvgRectangle + structure. A creation function for this structure is not provided + by the Rsvg API. + + After calling this, you should use `tolua.takeownership(rect)` on the return + value to ensure ownership is passed properly. + - name: RsvgRectangle:destroy() + desc: |- + Call this method to free memory allocated by + `RsvgRectangle:create`. + + You should call `tolua.releaseownership(rect)` before calling this function to + avoid double-frees, but only if you previously called + `tolua.takeownership(rect)` + - name: RsvgRectangle:get() + desc: |- + Gets the values of an existing RsvgRectangle. + - name: RsvgRectangle:set(x, y, width, height) + desc: |- + Sets the values of an existing RsvgRectangle. - name: cairo_font_extents_t:create() desc: |- Call this function to return a new cairo_font_extents_t @@ -64,6 +108,20 @@ values: You should call `tolua.releaseownership(cm)` before calling this function to avoid double-frees, but only if you previously called `tolua.takeownership(cm)` + - name: cairo_place_image(file, cr, x, y, width, height, alpha) + desc: |- + Renders an image onto a cairo_t, using imlib2. In some cases using a cairo_t and exact coordinates is more + useful. + + | Argument | Description | + |---------------------|--------------------------------------------------------------------------------------| + | file | Path to the image to render. | + | cr | The `cairo_t` to render to. | + | x,y | Position to render the image. | + | width, height | The width and height to draw the image | + | alpha | The transparency of the image 1.0 is solid 0.0 is fully translucent. | + + require('cairo_imlib2_helper') in your lua file. - name: cairo_text_extents_t:create() desc: |- Call this function to return a new cairo_text_extents_t @@ -137,50 +195,6 @@ values: NOTE: This table is only defined when X support is enabled. - - name: RsvgRectangle:create() - desc: |- - Call this method to return a new RsvgRectangle - structure. A creation function for this structure is not provided - by the Rsvg API. - - After calling this, you should use `tolua.takeownership(rect)` on the return - value to ensure ownership is passed properly. - - name: RsvgRectangle:destroy() - desc: |- - Call this method to free memory allocated by - `RsvgRectangle:create`. - - You should call `tolua.releaseownership(rect)` before calling this function to - avoid double-frees, but only if you previously called - `tolua.takeownership(rect)` - - name: RsvgRectangle:set(x, y, width, height) - desc: |- - Sets the values of an existing RsvgRectangle. - - name: RsvgRectangle:get() - desc: |- - Gets the values of an existing RsvgRectangle. - - name: RsvgDimensionData:create() - desc: |- - Call this method to return a new RsvgDimensionData - structure. A creation function for this structure is not provided - by the Rsvg API. - - After calling this, you should use `tolua.takeownership(rect)` on the return - value to ensure ownership is passed properly. - - name: RsvgDimensionData:destroy() - desc: |- - Call this method to free memory allocated by - `RsvgDimensionData:create`. - - You should call `tolua.releaseownership(dd)` before calling this function to - avoid double-frees, but only if you previously called - `tolua.takeownership(dd)` - - name: RsvgDimensionData:set(x, y, width, height) - desc: |- - Sets the values of an existing RsvgDimensionData. - - name: RsvgDimensionData:get() - desc: |- - Gets the values of an existing RsvgDimensionData. - name: ret_scale_x,ret_scale_y:cairo_draw_image(file, cs, x, y, scale_x, scale_y) desc: |- Renders an image onto a cairo_surface_t, using imlib2. Returns the amount the image was scaled by @@ -195,17 +209,3 @@ values: | | Default value: No Scaling (1.0,1.0) | require('cairo_imlib2_helper') in your lua file. - - name: cairo_place_image(file, cr, x, y, width, height, alpha) - desc: |- - Renders an image onto a cairo_t, using imlib2. In some cases using a cairo_t and exact coordinates is more - useful. - - | Argument | Description | - |---------------------|--------------------------------------------------------------------------------------| - | file | Path to the image to render. | - | cr | The `cairo_t` to render to. | - | x,y | Position to render the image. | - | width, height | The width and height to draw the image | - | alpha | The transparency of the image 1.0 is solid 0.0 is fully translucent. | - - require('cairo_imlib2_helper') in your lua file. \ No newline at end of file diff --git a/doc/variables.yaml b/doc/variables.yaml index efdb7241..4bbba72e 100644 --- a/doc/variables.yaml +++ b/doc/variables.yaml @@ -181,7 +181,6 @@ values: default: BAT0 args: - (num) - - name: battery_short desc: |- Battery status and remaining percentage capacity of ACPI or APM battery. @@ -865,9 +864,9 @@ values: args: - N - name: ibm_thinklight - desc: - "If running the IBM ACPI, displays the status of your\nThinkLight\u2122. Value\ - \ is either 'on', 'off' or 'unknown'." + desc: |- + If running the IBM ACPI, displays the status of your + ThinkLight™. Value is either 'on', 'off' or 'unknown'. - name: ibm_volume desc: |- If running the IBM ACPI, displays the "master" volume, @@ -951,24 +950,28 @@ values: desc: |- If Pulseaudio's default sink is muted, display everything between $if_pa_sink_muted and the corresponding $else or $endif. + - name: if_pa_source_muted + desc: |- + If Pulseaudio's default source (e.g. your microphone) is muted, display + everything between $if_pa_source_muted and the corresponding $else or $endif. - name: if_pa_source_running desc: |- If Pulseaudio's default source is running (e.g. a program is accessing your microphone), display everything between $if_pa_source_running and the corresponding $else or $endif. - - name: if_pa_source_muted - desc: |- - If Pulseaudio's default source (e.g. your microphone) is muted, display - everything between $if_pa_source_muted and the corresponding $else or $endif. - name: if_running - desc: - "If PROCESS is running, display everything between\n$if_running and the corresponding\ - \ $else or $endif. Note that PROCESS\nmay be either a full command line with arguments\ - \ (without the\ndirectory prefix), or simply the name of an executable. For example,\n\ - either of the following will be true if there is a running process\nwith the command\ - \ line `/usr/bin/conky -u 5`:\n\n* `${if_running conky -u 5}` or\n* `${if_running\ - \ conky}`\n \nIt is important not to include trailing spaces. For example,\ - \ `${if_running\nconky }` will be false." + desc: |- + If PROCESS is running, display everything between `$if_running` and the + corresponding `$else` or `$endif`. Note that PROCESS may be either a full + command line with arguments (without the directory prefix), or simply the + name of an executable. For example, either of the following will be true + if there is a running process with the command line `/usr/bin/conky -u + 5`: + * `${if_running conky -u 5}` or + * `${if_running conky}` + + It is important not to include trailing spaces. For example, + `${if_running conky }` will be false. args: - (process) - name: if_smapi_bat_installed