My Criticism of the current state of the Documentation: What’s unique to yuck and what’s not?

[mantacid]

Disclaimer: I just picked up this language like last week, so forgive me if I’ve missed some important bible of yuck programming. However, I’ve been reading docs for quite awhile, and I find the documentation for this tool to be lacking in some important areas, namely the parts that (seem to) take after other syntaxes.

Example: I want to know how variable scope is determined, as I keep getting errors that don’t give me any clues as to what to do other than to pass it in as an argument (which doesn’t answer my original question about scope).

That’s okay, I think to myself. I know how to read documentation and find extremely obscure forum posts with the exact issue that I’m facing, so I shouldn’t have any trouble locating a more in-depth resource (foreshadowing).

So I check the main eww docs, the other guide linked in the repo’s README, forum posts, etc…. and find while the docs say that user-defined variables are globally available to your widgets, in practice the variables don’t quite work the way I’d expect that phrase to mean.

With my go-to sources exhausted, I try to deduce where else to look. I know from page 1 of the eww docs that this language is based on lisp, but I also know that it was coded in rust, but I don’t know to what extent either of these facts have on the yuck language itself.

I begin to get desperate. Perhaps I’m missing some obscurer thread on (heaven forbid) a discord server somewhere, I reason. Or maybe it’s in one of these discussions, or a bug report that was closed because the reporter also had the same problem as me and they were given the answer. No dice. I check the examples listed in dharmx’s guide, but they’re all either things I’ve already checked or they’re dotfiles that inexplicably don’t contain a single explaining comment. In a last-ditch effort, I check the actual eww command usage. Apart from one command that lists the variables scope (which doesn’t work since another command shows that I don’t have as many variables as I think I do, yet eww doesn’t tell me any of them are undefined), there’s not much that can save me now.

And so my original question goes unanswered, and I am left to my own devices. This is NEVER a good idea, because then you end up with a website where a color value gets assigned to a margin to fix some alignment in the navigation, or a metric s***-ton of regular expressions and sed commands.

I think the documentation should make it clear where to look for additional information outside the scope of the yuck language itself. Even if it’s just a short blurb saying:

Variable scope in yuck works exactly the same way as it does in ____, so go to their documentation (LINK HERE) to learn more about that.

This would be so helpful. Knowing information is great, but knowing where to find information is more useful. It’s not just variable scope either; it took me awhile to catch onto the fact that you only call variables like ${VarName} when calling it from within quotes, and you just use the name everywhere else. Providing the reader with that information, whether by including it in the docs or by linking to where it can be found, is a really important thing to do.