Monitor Documentation Update - Make it Easier to Understand

[andar1an]

While learning how to interact with monitor configuration, I encountered many posts of people also confused about this section of documentation.

I suggest making it more clear regarding the calculations that are actually happening in docs, it is very ambiguous right now, especially if one assumes multiplication and not division is used for scaling operation. It was a good learning point to understand logical pixels, but it is not clear in docs.

Some potential calculation examples (apologies if mistakes, just a starting point)

Centering a Display Above another display:

-ve y
^
|
|_  _  > +ve x

# bottom display
monitor = eDP-1, 2560x1440@60, 0x0, 2

# centered top display (with various scale and resolution options (-ve is up on y and left on x axis)
# (displayAx-axis/displayAscale - displaybx-axis/displayBscale)/2  "x"  -(displayby-axis/DisplayBscale) = (2560/2-3850/1.25)/2 x -2160/1.25
monitor = HDMI-A-1, 3840x2160@30, -900x-1728, 1.25 
# monitor = HDMI-A-1, 3840x2160@30, -320x-1080, 2 # (2560/2-3840/2)/2 x -2160/2
# monitor = HDMI-A-1, 2560x1440@60, -640x-1440, 1 # (2560/2-2560/1)/2 x -1440/1

Moral is have a few example with varying resolutions, scales, and positions and hopefully diagrams so it is easier to determine what is being done. The language and examples right now are rough to understand.

[fufexan]

For simple usecases of "I want my monitor up/down/left/right" there already exists the simpler auto-{up/down/left/right}. But it's not very visible in the wiki.

But we can also include examples such as yours to clarify things.

[andar1an]

I noticed the auto options, and even tried them. They are wonderful, but they do not work well for those with varying size monitors where one may want to be more explicit about where a mouse transition across displays occurs (which is why I was playing with centering).

I was also shown wdisplays which may also be nice to mention in wiki if it has not been. I don't recall seeing it, but it could be somewhere.

I think a few diagrams here would be really powerful, especially since they can be language agnostic.

[fufexan]

I think a few diagrams here would be really powerful, especially since they can be language agnostic.

We could probably integrate Mermaid.

I was also shown wdisplays which may also be nice to mention in wiki if it has not been. I don't recall seeing it, but it could be somewhere.

It isn't mentioned currently, but it could be mentioned in Useful Utilities/Other, along with kanshi, shikane, wlr-randr, nwg-displays.

[andar1an]

Cool, I am new to the tiling and wayland world, will need to look into those too!

I like Mermaid as well, but there are also a few other options now too like d2: https://d2lang.com/.

In Rust there is a project called aquamarine that makes it easier to integrate mermaid diagrams into Rustdocs - I don't know much about C++ world, but maybe there is something similar.

[fufexan]

Our wiki uses hugo, and mermaid is pretty easy to integrate, that's why I mentioned it. Also, the wiki is not generated from doxygen or the like.

D2 looks nice, I'll look into what we can do.

[Bugg4]

mermaid is pretty easy to integrate

Just found out Hugo already supports both mermaid and other diagram formats: https://gohugo.io/content-management/diagrams/

[andar1an]

I wonder if they plan to support D2 as that is also a Go project. GoAT seems fun, will need to try that!

[Bugg4]

Looks like there's an old issue still open for it, with some interest, but no progress made yet: gohugoio/hugo#10579