search

brndnmtthws / conky

Light-weight system monitor for X, Wayland (sort of), and other things, too
https://conky.cc
GNU General Public License v3.0
7.16k stars 615 forks source link

With line numbers of files at [doc]: usage of module name can be a bit confusing + few other suggestions to [doc/*] #1301

Closed ZjYwMj closed 6 months ago

ZjYwMj commented 1 year ago

Referring to:

  1. doc/man.md.j2#L92-L94: Do add that in many cases, if the user just waits a few seconds after a new configuration has been written to disk, conky is likely to sense its configuration has changed. And reload the new configuration automatically.
  2. doc/variables.yaml#L61: Do add: , with a shift of N (num) pixels. A negative N (num) shifts to the right. Also note for doc/variables.yaml#L63 that a num of 0 is optional.
  3. doc/variables.yaml#L65: Do replace space with pixels. And add A negative N (num) shifts to the right. Also note for doc/variables.yaml#L67 that a num of 0 is optional.
  4. doc/variables.yaml#L771-L772: I find the use of the 2 words module name a bit misleading, even though there seem to be an attempt to clarify. In my view, a module name is the name of kernel module as given by lsmod. While /sys/class/hwmon/hwmon?/name does not always identical to the related kernel module name. I think the word module should be dropped, and a direct relation to the name, as given by /sys/class/hwmon/hwmon?/name should be stated.
brndnmtthws commented 1 year ago

These are all good suggestions, would you like to take a stab at writing a PR for these changes?

ZjYwMj commented 1 year ago

I am not sure I followed, but here is attempt # 1: (and why does \#1 not being escaped here?)

--- a/man.md.j2 2022-12-04 18:42:01.125761827 +0000
+++ b/man.md.j2 2022-12-04 18:56:19.598437828 +0000
@@ -91,7 +91,11 @@

 An easy way to force Conky to reload your *\~/.config/conky/conky.conf*:
 \"killall -SIGUSR1 conky\". Saves you the trouble of having to kill and
-then restart.
+then restart. Alternatively, depending how the conky executable was 
+built, but as of 2022 this is the usual way, just replace the prevoius
+configuration file with a newer version. Write a newer version in place 
+of the old one. Conky will sense that, seemingly exit, and after a short 
+while will reappear. With the newer version of the configuration.

 # OPTIONS

Does that close to what you had in mind? Will you accept similar patches for the other 3 items? I was close to add that a user better copy its old configuration, to get a backup. Should he, or conky, will not be satisfied.

brndnmtthws commented 1 year ago

That looks alright to me. The best thing is to open a PR so I can provide feedback on the changes there.

ZjYwMj commented 1 year ago

In order to test my understanding of creating a pull request, I submitted a pull request with only a partial fix to this issue. It can be seen in the pull request I have created 2 commits, where a single commit can suffice. However, this is probably will be seen only at my external repository. And not in conky main repository. In addition, I have hard time submitting a request to fully close this issue. Such a request seem to include the patch for pr #1343 for the 2nd time. Which is why I postpone submitting a pull request that will fully close this issue until there is a decision about pr #1343.

ZjYwMj commented 1 year ago

I think pr #1343 asks to pull one patch to doc/man.md.j2. And a 2nd patch to doc/variables.yaml. I am not getting along well with github interface. I tried to create a pull request only to the doc/man.md.j2 patch suggested in this issue. I made couple of attempts. With a feature branch in my forked repository, and with a commit to my main forked repository. Eventually, I saw my pull request here. That is, in the upstream repository pull request. Thinking I know how to create pull requests to my satisfaction, I changed the main branch of my forked repository to include one of the patches suggested here to doc/variables.yaml. Then I tried to create a 2nd pull request for that commit only. Hoping to have two pull requests, each one to a different file. Realizing my 2nd pull request also repeat the pull request for doc/man.md.j2, I though I withdraw it by not approving it. I expected the 2nd pull request not to be sent. Yet I see that there is one pull request, with two patches. Each patch for a different file. That is not what I thought I am approving. I probably had to create two separate feature branches in my repository. One branch will have only doc/man.md.j2` modified. And the 2nd branch will have only doc/variables.yaml modified. But I seemed not to be able to see pull request for a feature branch at the upstream repository pull requests. Which is why I continue modifying the main branch of my repository. I hope I manged to make myself clear.

rubyFeedback commented 1 year ago

I am not getting along well with github interface.

Or simply copy/paste the new file here. :D

ZjYwMj commented 1 year ago

The suggested new file for man.md.j2 should be obtained by the patch already reviewed at pull request #1343. It, #1343, has only a partial patch for doc/variables.yaml. A full version of the suggested doc/variables.yaml is:

# See README.md for details on doc processing.
#
# The `desc` field can be formatted with markdown, but please do not include
# headings (lines beginning with `#`) in the `desc` field.
#
# The supported fields are:
#
#  * `name`: the name of the thing
#  * `desc`: a markdown-formatted description of the thing
#  * `args`: optional list of arguments
#  * `default`: an optional default value, if applicable
---
desc: |-
  To configure what Conky displays, you must supply some variables in the
  `conky.text` section of your configuration. In this secton you'll find a
  listing of the available variables. Some of them may require build options to
  be enabled at compile time for them to work.

  Colours are parsed using `XParseColor()`, there might be a list of them:
  `/usr/share/X11/rgb.txt`. Colour can be also in `#rrggbb` format (hex).

  Some objects may create threads, and sometimes these threads will not be
  destroyed until Conky terminates. There is no way to destroy or clean up
  threads while Conky is running. For example, if you use an MPD variable,
  the MPD thread will keep running until Conky dies. Some threaded objects
  will use one of the parameters as a `key`, so that you only have 1
  relevant thread running (for example, the $curl, and $rss
  objects launch one thread per URI).

  Optional arguments are generally denoted with paretheses (i.e., `(optional)`).
values:
  - name: acpiacadapter
    desc: |-
      ACPI AC adapter state. On linux, the adapter option
      specifies the subfolder of `/sys/class/power_supply` containing the state
      information (tries `AC` and `ADP1` if there is no argument given).
      Non-linux systems ignore it.
    args:
      - (adapter)
  - name: acpifan
    desc: ACPI fan state.
  - name: acpitemp
    desc: ACPI temperature in C.
  - name: addr
    desc: |-
      IP address for an interface, or "No Address" if no address
      is assigned.
    args:
      - (interface)
  - name: addrs
    desc: |-
      IP addresses for an interface (if one - works like addr).
      Linux only.
    args:
      - (interface)
  - name: adt746xcpu
    desc: CPU temperature from therm_adt746x.
  - name: adt746xfan
    desc: Fan speed from therm_adt746x.
  - name: alignc
    default: 0
    desc: |-
      Align text to centre, with a shift of N (num) pixels. A
      negative N (num) shifts to the right.
    args:
      - (num)
  - name: alignr
    default: 0
    desc: |-
      Right-justify text, with a shift of N (num) pixels. A
      negative N (num) is accepted, and actually makes no
      difference.
    args:
      - (num)
  - name: apcupsd
    desc: |-
      Sets up the connection to apcupsd daemon. Prints nothing.
    default: localhost:3551
    args:
      - host
      - port
  - name: apcupsd_cable
    desc: Prints the UPS connection type.
  - name: apcupsd_charge
    desc: Current battery capacity in percent.
  - name: apcupsd_lastxfer
    desc: Reason for last transfer from line to battery.
  - name: apcupsd_linev
    desc: Nominal input voltage.
  - name: apcupsd_load
    desc: Current load in percent.
  - name: apcupsd_loadbar
    desc: Bar showing current load.
  - name: apcupsd_loadgauge
    desc: Gauge that shows current load.
    args:
      - (height),(width)
  - name: apcupsd_loadgraph
    desc: History graph of current load.
    args:
      - (height),(width)
      - (gradient colour 1)
      - (gradient colour 2)
      - (scale)
      - (-t)
      - (-l)
  - name: apcupsd_model
    desc: Prints the model of the UPS.
  - name: apcupsd_name
    desc: Prints the UPS user-defined name.
  - name: apcupsd_status
    desc: Prints current status (on-line, on-battery).
  - name: apcupsd_temp
    desc: Current internal temperature.
  - name: apcupsd_timeleft
    desc: Time left to run on battery.
  - name: apcupsd_upsmode
    desc: Prints the UPS mode (e.g. standalone).
  - name: apm_adapter
    desc: Display APM AC adapter status. FreeBSD, OpenBSD only.
  - name: apm_battery_life
    desc: Display APM battery life in percent. FreeBSD, OpenBSD only.
  - name: apm_battery_time
    desc: |-
      Display remaining APM battery life in hh:mm:ss or "unknown"
      if AC adapterstatus is on-line or charging. FreeBSD, OpenBSD only.
  - name: audacious_bar
    desc: Progress bar.
    args:
      - (height),(width)
  - name: audacious_bitrate
    desc: Bitrate of current tune.
  - name: audacious_channels
    desc: Number of audio channels of current tune.
  - name: audacious_filename
    desc: Full path and filename of current tune.
  - name: audacious_frequency
    desc: Sampling frequency of current tune.
  - name: audacious_length
    desc: Total length of current tune as MM:SS.
  - name: audacious_length_seconds
    desc: Total length of current tune in seconds.
  - name: audacious_main_volume
    desc: The current volume fetched from Audacious.
  - name: audacious_playlist_length
    desc: Number of tunes in playlist.
  - name: audacious_playlist_position
    desc: Playlist position of current tune.
  - name: audacious_position
    desc: Position of current tune (MM:SS).
  - name: audacious_position_seconds
    desc: Position of current tune in seconds.
  - name: audacious_status
    desc: Player status (Playing/Paused/Stopped/Not running).
  - name: audacious_title
    desc: |-
      Title of current tune with optional maximum length
      specifier.
    args:
      - (max length)
  - name: battery
    desc: |-
      Battery status and remaining percentage capacity of ACPI or
      APM battery. ACPI battery number can be given as argument.
    default: BAT0
    args:
      - (num)
  - name: battery_bar
    desc: |-
      Battery percentage remaining of ACPI battery in a bar. ACPI battery number
      can be given as argument (use `all` to get the mean percentage remaining for
      all batteries).
    default: BAT0
    args:
      - (height),(width)
      - (num)
  - name: battery_percent
    desc: |-
      Battery percentage remaining for ACPI battery. ACPI battery
      number can be given as argument (use `all` to get the
      mean percentage remaining for all batteries).
    default: BAT0
    args:
      - (num)
  - name: battery_power_draw
    desc: |-
      Battery power draw in watts
    default: BAT0
    args:
      - (num)

  - name: battery_short
    desc: |-
      Battery status and remaining percentage capacity of ACPI or APM battery.
      ACPI battery number can be given as argument. This mode display a short
      status, which means that C is displayed instead of charging, D for
      discharging, F for full, N for not present, E for empty and U for unknown.
    default: BAT0
    args:
      - (num)
  - name: battery_status
    desc: |-
      Battery status for ACPI battery. ACPI battery number can be
      given as arguments.
    default: BAT0
    args:
      - (num)
  - name: battery_time
    desc: |-
      Battery charge/discharge time remaining of ACPI battery.
      ACPI battery number can be given as argument.
    default: BAT0
    args:
      - (num)
  - name: blink
    desc: Let 'text_and_other_conky_vars' blink on and off.
    args:
      - text_and_other_conky_vars
  - name: buffers
    desc: Amount of memory buffered.
  - name: cached
    desc: Amount of memory cached.
  - name: cat
    desc: |-
      Reads a file and displays the contents in conky. This is
      useful if you have an independent process generating output that you
      want to include in conky.
    args:
      - file
  - name: catp
    desc: |-
      Reads a file and displays the contents in conky. This is
      useful if you have an independent process generating output that you
      want to include in conky. This differs from $cat in that it parses the
      contents of the file, so you can insert things like
      `${color red}hi!${color}` in your file and have it correctly parsed by
      Conky.
    args:
      - file
  - name: cmdline_to_pid
    desc: PID of the first process that has string in its commandline.
    args:
      - string
  - name: cmus_aaa
    desc: Print aaa status of cmus (all/artist/album).
  - name: cmus_album
    desc: Prints the album of the current cmus song.
  - name: cmus_artist
    desc: Prints the artist of the current cmus song.
  - name: cmus_curtime
    desc: Current time of the current cmus song.
  - name: cmus_date
    desc: Print the date of the current cmus song.
  - name: cmus_file
    desc: Print the file name of the current cmus song.
  - name: cmus_genre
    desc: Print the genre name of the current cmus song.
  - name: cmus_percent
    desc: Percent of song's progress.
  - name: cmus_progress
    desc: cmus' progress bar.
    args:
      - (height),(width)
  - name: cmus_random
    desc: Random status of cmus (on/off).
  - name: cmus_repeat
    desc: Repeat status of cmus (song/all/off).
  - name: cmus_state
    desc: Current state of cmus (playing, paused, stopped etc).
  - name: cmus_timeleft
    desc: Time left of the current cmus song.
  - name: cmus_title
    desc: Prints the title of the current cmus song.
  - name: cmus_totaltime
    desc: Total length of the current cmus song.
  - name: cmus_track
    desc: Print track number of current cmus song.
  - name: color
    desc: |-
      Change drawing color to _color_ which is a name of a color
      or a hexcode preceded with #, e.g. `#0A1B2C`. If you use ncurses only
      the following colors are supported: red, green, yellow, blue, magenta,
      cyan, black, and white.
    args:
      - (color)
  - name: colorN
    desc: |-
      Change drawing color to colorN configuration option, where N
      is a digit between 0 and 9, inclusively.
  - name: combine
    desc: |-
      Places the lines of var2 to the right of the lines of var1
      separated by the chars that are put between var1 and var2. For
      example: `${combine ${head /proc/cpuinfo 2} - ${head /proc/meminfo 1}}`
      gives as output `cpuinfo_line1 - meminfo_line1` on line 1 and
      `cpuinfo_line2 -` on line 2. $combine vars can also be nested to place
      more vars next to each other.
    args:
      - var1
      - var2
  - name: conky_build_arch
    desc: CPU architecture Conky was built for.
  - name: conky_build_date
    desc: Date Conky was built.
  - name: conky_version
    desc: Conky version.
  - name: cpu
    desc: |-
      CPU usage in percents. For SMP machines, the CPU number can
      be provided as an argument. ${cpu cpu0} is the total usage, and ${cpu
      cpuX} (X >= 1) are individual CPUs.
    args:
      - (cpuN)
  - name: cpubar
    desc: |-
      Bar that shows CPU usage, height is bar's height in pixels.
      See $cpu for more info on SMP.
    args:
      - (cpuN)
      - (height),(width)
  - name: cpugauge
    desc: |-
      Elliptical gauge that shows CPU usage, height and width are
      gauge's vertical and horizontal axis respectively. See $cpu for more
      info on SMP.
    args:
      - (cpuN)
      - (height),(width)
  - name: cpugovernor
    desc: |-
      The active CPU scaling governor, defaulting to the first core.
      See $cpu for more info on SMP. Linux only.
    args:
      - (cpuN)
  - name: cpugraph
    desc: |-
      CPU usage graph, with optional colours in hex, minus the #.
      See $cpu for more info on SMP. Uses a logarithmic scale (to see small
      numbers) when you use the -l switch. Takes the switch '-t' to use a
      temperature gradient, which makes the gradient values change depending
      on the amplitude of a particular graph value (try it and see).
    args:
      - (cpuN)
      - (height),(width)
      - (gradient colour 1)
      - (gradient colour 2)
      - (scale)
      - (-t)
      - (-l)
  - name: curl
    desc: |-
      Download data from URI using Curl at the specified interval.
      The interval may be a positive floating point value (0 is allowed),
      otherwise defaults to 15 minutes. Most useful when used in conjunction
      with Lua and the Lua API. This object is threaded, and once a thread
      is created it can't be explicitly destroyed. One thread will run for
      each URI specified. You can use any protocol that Curl supports.
    args:
      - url
      - (interval_in_minutes)
  - name: desktop
    desc: |-
      Number of the desktop on which conky is running or the
      message "Not running in X" if this is the case.
  - name: desktop_name
    desc: |-
      Name of the desktop on which conky is running or the message
      "Not running in X" if this is the case.
  - name: desktop_number
    desc: |-
      Number of desktops or the message "Not running in X" if this
      is the case.
  - name: disk_protect
    desc: |-
      Disk protection status, if supported (needs kernel-patch).
      Prints either "frozen" or "free " (note the padding).
    args:
      - device
  - name: diskio
    desc: |-
      Displays current disk IO. Device is optional, and takes the
      form of sda for /dev/sda. A block device label can be specified with
      label:foo and a block device partuuid can be specified with
      partuuid:40000000-01.
    args:
      - (device)
  - name: diskio_read
    desc: Displays current disk IO for reads. Device as in diskio.
    args:
      - (device)
  - name: diskio_write
    desc: Displays current disk IO for writes. Device as in diskio.
    args:
      - (device)
  - name: diskiograph
    desc: |-
      Disk IO graph, colours defined in hex, minus the #. If scale
      is non-zero, it becomes the scale for the graph. Uses a logarithmic
      scale (to see small numbers) when you use -l switch. Takes the switch
      '-t' to use a temperature gradient, which makes the gradient values
      change depending on the amplitude of a particular graph value (try it
      and see).
    args:
      - (device)
      - (height),(width)
      - (gradient colour 1)
      - (gradient colour 2)
      - (scale)
      - (-t)
      - (-l)
  - name: diskiograph_read
    desc: |-
      Disk IO graph for reads, colours defined in hex, minus the
      #. If scale is non-zero, it becomes the scale for the graph. Device as
      in diskio. Uses a logarithmic scale (to see small numbers) when you
      use -l switch. Takes the switch '-t' to use a temperature gradient,
      which makes the gradient values change depending on the amplitude of a
      particular graph value (try it and see).
    args:
      - (device)
      - (height),(width)
      - (gradient colour 1)
      - (gradient colour 2)
      - (scale)
      - (-t)
      - (-l)
  - name: diskiograph_write
    desc: |-
      Disk IO graph for writes, colours defined in hex, minus the
      #. If scale is non-zero, it becomes the scale for the graph. Device as
      in diskio. Uses a logarithmic scale (to see small numbers) when you
      use -l switch. Takes the switch '-t' to use a temperature gradient,
      which makes the gradient values change depending on the amplitude of a
      particular graph value (try it and see).
    args:
      - (device)
      - (height),(width)
      - (gradient colour 1)
      - (gradient colour 2)
      - (scale)
      - (-t)
      - (-l)
  - name: distribution
    desc: |-
      The name of the distribution. It could be that some of the
      untested distributions will show up wrong or as "unknown", if that's
      the case post a bug on sourceforge, make sure it contains the name of
      your distribution, the contents of and if there is a file that
      only exists on your distribution, also add the path of that file in
      the bug. If there is no such file, please add another way which we can
      use to identify your distribution.
    other:
      filename: /proc/version
  - name: downspeed
    desc: Download speed in suitable IEC units.
    args:
      - (net)
  - name: downspeedf
    desc: Download speed in KiB with one decimal.
    args:
      - (net)
  - name: downspeedgraph
    desc: |-
      Download speed graph, colours defined in hex, minus the #.
      If scale is non-zero, it becomes the scale for the graph. Uses a
      logarithmic scale (to see small numbers) when you use -l switch. Takes
      the switch '-t' to use a temperature gradient, which makes the
      gradient values change depending on the amplitude of a particular
      graph value (try it and see).
    args:
      - (netdev)
      - (height),(width)
      - (gradient colour 1)
      - (gradient colour 2)
      - (scale)
      - (-t)
      - (-l)
  - name: draft_mails
    desc: |-
      Number of mails marked as draft in the specified mailbox or
      mail spool if not. Only maildir type mailboxes are supported, mbox
      type will return -1.
    args:
      - (maildir)
      - (interval)
  - name: else
    desc: Text to show if any of the above are not true.
  - name: endif
    desc: Ends an $if block.
  - name: entropy_avail
    desc: Current entropy available for crypto freaks.
  - name: entropy_bar
    desc: Normalized bar of available entropy for crypto freaks.
    args:
      - (height),(width)
  - name: entropy_perc
    desc: |-
      Percentage of entropy available in comparison to the
      poolsize.
  - name: entropy_poolsize
    desc: Total size of system entropy pool for crypto freaks.
  - name: eval
    desc: |-
      Evaluates given string according to the rules of conky.text
      interpretation, i.e. parsing any contained text object specifications
      into their output, any occurring '$$' into a single '$' and so on. The
      output is then being parsed again.
    args:
      - string
  - name: exec
    desc: |-
      Executes a shell command and displays the output in conky.
      Warning: this takes a lot more resources than other variables. I'd
      recommend coding wanted behaviour in C/C++ and posting a patch.
    args:
      - command
  - name: execbar
    desc: |-
      Same as exec, except if the first value returned is a value
      between 0-100, it will use that number to draw a horizontal bar. The
      height and width parameters are optional, and default to the
      default_bar_height and default_bar_width config settings,
      respectively.
    args:
      - (height),(width)
      - command
  - name: execgauge
    desc: |-
      Same as exec, except if the first value returned is a value
      between 0-100, it will use that number to draw a round gauge (much
      like a vehicle speedometer). The height and width parameters are
      optional, and default to the default_gauge_height and
      default_gauge_width config settings, respectively.
    args:
      - (height),(width)
      - command
  - name: execgraph
    desc: |-
      Draws a horizontally scrolling graph with values from 0-100 plotted on the
      vertical axis. All parameters following the command are optional. Gradient
      colors can be specified as hexadecimal values with no 0x or # prefix. Use
      the -t switch to enable a temperature gradient, so that small values are
      "cold" with color 1 and large values are "hot" with color 2. Without the -t
      switch, the colors produce a horizontal gradient spanning the width of the
      graph. The scale parameter defines the maximum value of the graph.  Use the
      -l switch to enable a logarithmic scale, which helps to see small values.
      The default size for graphs can be controlled via the default_graph_height
      and default_graph_width config settings.

      If you need to execute a command with spaces, you have a
      couple options:

      1. wrap your command in double-quotes, or
      2. put your command into a separate file, such as ~/bin/myscript.sh, and use
      that as your execgraph command.

      Remember to make your script executable!

      In the following example, we set up execgraph to display seconds (0-59) on a
      graph that is 50px high and 200px wide, using a temperature gradient with
      colors ranging from red for small values (FF0000) to yellow for large values
      (FFFF00). We set the scale to 60.

  ${execgraph ~/seconds.sh 50,200 FF0000 FFFF00 60 -t}
  ```
args:
  - command
  - (height),(width)
  - (gradient color 1)
  - (gradient color 2)
  - (scale)
  - (-t)
  - (-l)
ZjYwMj commented 1 year ago

I have rechecked alignr with a negative num, such as alignr -100. With small values of num, I couldn't observe a noticeable change. Which is why I assumed, in the above file, that negative values are ignored. However, with smaller values of num, that are larger with their absolute value (|-100| == abs(-100) == 100), there seem to be an attempt to shift the string to the right. Which, in my case, resulted with a chopped string. Possibly because, in my case, it hits the window border. What is the meaning of shifting a right justified string to the right?

github-actions[bot] commented 7 months ago

This issue is stale because it has been open 365 days with no activity. Remove stale label or comment, or this issue will be closed in 30 days.

github-actions[bot] commented 6 months ago

This issue was closed because it has been stalled for 30 days with no activity.