Clarify the structure of XMonad.StackSet.Stack type

[unclechu]

Description

Add extra comment lines with examples making it more clear how the data is organized. By looking at the existing comment it wasn’t really clear for me what’s going on. I though adding an example like this would make it much easier to understand.

Checklist

• I've read CONTRIBUTING.md

• I've confirmed these changes don't belong in xmonad-contrib instead

  It’s just a comment for the core type.

• I've considered how to best test these changes (property, unit,
  manually, ...) and concluded: XXX

  Nothing to test, it’s just a comment.

• I updated the CHANGES.md file

  Nothing to mention there as the actual code didn’t change at all.

[geekosaur]

For what it's worth, the Stack is a simple list zipper. I think we were short on pointers to zipper documentation in the releases, but git has them.

I'll take a closer look at this tomorrow; it's bedtime here.

[geekosaur]

So to expand on zippers, the behavior of up and down follows from the definition of a list zipper and how Haskell lists work. Imagine you start with the first window in focus, so up is empty and the other windows are in down.

up = [], focus = 1, down = [2, 3, 4, 5]

Now you move down the zipper: focus is pushed onto up and down is popped into focus.

up = [1], focus = 2, down = [3, 4, 5]

Now repeat it, and you'll note that up is naturally reversed as you go.

up = [2, 1], focus = 3, down = [4, 5]

Moving in the other direction is equally easy because of that reversal: push focus onto down and pop up into focus.

up = [1], focus = 2, down = [3, 4, 5]

This is the essence of a zipper: it lets you move a focus through a data structure. Zippers can also be defined for various kinds of trees, supporting move-up, move-down, move-left, and move-right operations (see the example in https://wiki.haskell.org/Zipper).

[slotThe]

I think the original ASCII art

   +-- master:  < '7' >
up |            [ '2' ]
   +---------   [ '3' ]
focus:          < '4' >
dn +----------- [ '8' ]

is actually quite clear; what problems did you have with understanding it?

[unclechu]

@slotThe like what is this +-- master: < '7' >. What <> and [] mean here. What is dn? Is it down? Why then focus is not fs? Is <7> part of of up? Why the order is 7, 2, 3? Why 4 comes after 7 then, etc? IMO this is one of the most confusing ASCII art I’ve ever seen, it leaves so many questions open and doesn’t even answer one to me 🤷

---

@geekosaur Thanks for explanation. Though I already figured that out. The point of the change is to help others who want to fiddle around with it to have a clear and transparent view on what the data looks like. I think just this piece alone would make it much clearer:

-- > 1 2 3 4 <5> 6 7 8 9
--
-- Where @<5>@ is the currently focused window.
-- Then the stack would look like this:
--
-- > Stack { focus = 5
-- >       , up    = [4, 3, 2, 1]
-- >       , down  = [6, 7, 8, 9] }

[TheMC47]

First, thanks for your contribution!

@slotThe like what is this +-- master: < '7' >. What <> and [] mean here. What is dn? Is it down? Why then focus is not fs? Is <7> part of of up? Why the order is 7, 2, 3? Why 4 comes after 7 then, etc? IMO this is one of the most confusing ASCII art I’ve ever seen, it leaves so many questions open and doesn’t even answer one to me 🤷

I suggest clarifying the questions and adapting the ASCII explanation instead of creating a new example. So change the art and the surrounding text in a way that you have no more questions.

[slotThe]

@unclechu friendly ping :)

[slotThe]

I will close this for now, feel free to reopen when you get back to this!