Contribution to Documentation

[prmadev]

Hello!
Thanks for eww!

I'm trying to build an abstraction kind of library for configuring eww and I have noticed that the documentation needs some clarifications, examples, and things here and there.

I would love to know if you have any opinion on this matter and open to pull requests for this.

I also can open up issue(s) for what I find, if you prefer to do them yourself.

Thanks in advance!

[elkowar]

I'm very much open to PRs that improve the documentation!
Generally, I'd love to keep the introductory Guide relatively short and to the point, although if there are points that are obviously insufficient, those should of course be elaborated on. I'd recommend just noting down the points you find lacking so we can discuss further, and maybe get some input from other users as well ^^

[prmadev]

Definitly. I will!

For now, there are a few points. I will incrementally add them here with sufficient explanation.

to start with, widgets can do with a more concise explanations.
for example:
something like this line:
valign: string how to align this vertically. possible values: "fill", "baseline", "center", "start", "end"
There are three possible improvements I would suggest.

1. First and the most important: Mentioning the default value of it can be extremely helpful. otherwise one has to find out what it is through the code, or eww inspector.

2. Though these values are perfectly clear to the intiated, it may offer friction to others not familiar with these, to understand the behavior. A link to a brief and preferable visual explanation would go a long way to improve the confused new user.

3. an example of how this configuration would look like would generally be very helpful. Though on this point, something like inline css style would show a more need. This for example can be somewhat helpful to someone that is not clear on if they should surround their css inside {} or even .CLASS{}.

So what I would suggest as a whole would look something like this:

valign: string how to align this vertically. default value: "fill", possible values: "fill", "baseline", "center", "start", "end". [further explanation](...)
example: `(box :valign "baseline")`

Though I'm not insisting on this format, I think these information should exist in the documentations. Mostly these kinds of explanations are useful mostly in reference type pages, like widgets which may not be counted as introductory guides.

[elkowar]

Hmm, with providing examples I see the mostly unrelated issue of maintainability becoming an issue. Providing an example for every attribute would more than double the amount of documentation for each widget - and inconsistently providing examples is also ugly.

Specifically with regards to layout related attributes and widgets, such as the align, expand and space-evenly properties, what I have been thinking about is having a dedicated page that just goes over layouts.
There, I think we could either just write a guide, and / or basically generate examples that include all possible (useful and meaningful) combinations of these and show their result.

Layout in eww is one of the most confusing parts definitely, and sadly that's hard to fix as it's mostly due to the complexity of how the underlying gtk widgets behave.

Another alternative I have considered would be making one ginormous example widget which basically goes over all existing widgets, has some text as well as some useage demos for them.
Im not sure how that would be best implemented, but I'd love to basically have an example config which demonstrates "this is how Box layout works:" by giving clearly understandable nested boxes and then having dropdowns for the user to change between the different values for v/halign, v/hexpand, space-evenly, and so on. That way, users could easily experiment and learn interactively.

All of these add a good bit of maintenance burden as theyd have to be quite large. However, especially that last option of having an example show all or at least most widgets could also be interesting as a means of testing somehow.

[prmadev]

Honestly, I agree with the maintenance burden. And that's why I prioritized my suggestions.
I agree that examples can be too harsh, and may be a better option for a version 1.0 rather than the development versions.

But I think even now, specifying the defaults is probably the most crucial deficit in the docs and they can also act as an alternative to a complete dedicated example section, for now.

As for the other solutions that you have mentioned, I agree that all of them are nice. But the complexity of the second option, may be difficult for uninitiated as a guide, but it may actually be awesome as a reference documentation. But the presentation can be tricky as one may need to consider both different sizes of monitors and also the complexity of having all that scss files.

Now, I'm not sure if you have anything in mind, But I'm happy to work on any of the mentioned solutions or discuss further any of them.