Possible copy-paste errors in documentation for ExecClient

[jjramsey]

There are two indications of problems with the documentation for ExecClient.

First, it has the sentence "The id is used to address the socket ..." even though ExecClient doesn't appear to involve sockets, at least not explicitly. (Indeed, it looks like the only difference between the documentation for ExecClient and the documentation for SocketClient is that the former contains the words "command to execute" instead of "a socket address"

Second, it seems to imply that the command to execute will somehow cause a trigger event, but there's no indication of how this happens. If I look at the example configs for "alsa.widget" and "rfkill.source", they superficially look similar to a waybar custom module or yambar script module running in continuous mode. Apparently, the executable causes a trigger event by flushing to standard output, but this isn't clear from the documentation at all.

[LBCrion]

Thank you! I updated the doc. Please let me know if this reads better or feel free to propose any better wording you can think of.

On Sun, Jul 7, 2024 at 3:28 PM J. J. Ramsey @.***> wrote:

There are two indications of problems with the documentation for ExecClient.

First, it has the sentence "The id is used to address the socket ..." even though ExecClient doesn't appear to involve sockets, at least not explicitly. (Indeed, it looks like the only difference between the documentation for ExecClient and the documentation for SocketClient is that the former contains the words "command to execute" instead of "a socket address"

Second, it seems to imply that the command to execute will somehow cause a trigger event, but there's no indication of how this happens. If I look at the example configs for "alsa.widget" and "rfkill.source", they superficially look similar to a waybar custom module or yambar script module running in continuous mode. Apparently, the executable causes a trigger event by flushing to standard output, but this isn't clear from the documentation at all.

— Reply to this email directly, view it on GitHub https://github.com/LBCrion/sfwbar/issues/199, or unsubscribe https://github.com/notifications/unsubscribe-auth/ASHPFFE3TLYZ33S7OUVQJ23ZLFF7TAVCNFSM6AAAAABKPNCPKWVHI2DSMVQWIX3LMV43ASLTON2WKOZSGM4TIMBXHA3TONA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[jjramsey]

It helps, but I'd recommend a couple things.

First, I'd amend, "The id can be used to write to the standard input of the executable" to "The id can be used to write to the standard input of the executable (provided that the executable takes standard input)". That would make clearer that an ExecClient doesn't have to take standard input.

Second, I'd add an example such as this:

scanner ExecClient("stdbuf -oL foo.sh BAR BAZ", "foo") {
  Foo_foo = Json(".foo")
  Foo_bar = Json(".bar")
}

where foo.sh is:

#!/bin/sh

. ~/foo_funcs.sh # Defines example funcs "do_something" &
                 # "do_something_else".

while true
do
    foo=`do_something "$1"`
    bar=`do_something_else "$2"`
    echo "{\"foo\": \"$foo\", \"bar\": \"$bar\"}"
    sleep 1
done

This would not only show what ExecClient does, but also show the kind of strings that Json() works on.

Then you can mention sfwbar files that use ExecClient, such as alsa.widget and rfkill.source, and suggest to the reader that they can look at those files for further examples.

I would also recommend explaining what $ is doing in the exec("getweather.sh") that you already have, presuming that isn't a typo.

[LBCrion]

I added the above, except for the example script. Still thinking where would be the best place to add it. I think it would be a bit confusing if I add it to the scanner section of the doc, since it's not part of the scanner syntax.

Perhaps it would make sense to write a separate doc with primers of common config patterns.

On Mon, Jul 8, 2024 at 2:08 PM J. J. Ramsey @.***> wrote:

It helps, but I'd recommend a couple things.

First, I'd amend, "The id can be used to write to the standard input of the executable" to "The id can be used to write to the standard input of the executable (provided that the executable takes standard input)". That would make clearer that an ExecClient doesn't have to take standard input.

Second, I'd add an example such as this:

scanner ExecClient("stdbuf -oL foo.sh BAR BAZ", "foo") { Foo_foo = Json(".foo") Foo_bar = Json(".bar") }

where foo.sh is:

!/bin/sh

. ~/foo_funcs.sh # Defines example funcs "do_something" &

"do_something_else".

while truedo foo=do_something "$1" bar=do_something_else "$2" echo "{\"foo\": \"$foo\", \"bar\": \"$bar\"}" sleep 1done

This would not only show what ExecClient does, but also show the kind of strings that Json() works on.

Then you can mention sfwbar files that use ExecClient, such as alsa.widget and rfkill.source, and suggest to the reader that they can look at those files for further examples.

I would also recommend explaining what $ is doing in the exec("getweather.sh") that you already have, presuming that isn't a typo.

— Reply to this email directly, view it on GitHub https://github.com/LBCrion/sfwbar/issues/199#issuecomment-2214030835, or unsubscribe https://github.com/notifications/unsubscribe-auth/ASHPFFHSHO4UX7TDIAFZARLZLKFLDAVCNFSM6AAAAABKPNCPKWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMJUGAZTAOBTGU . You are receiving this because you commented.Message ID: @.***>