Improve Layout Documentation, Add Screenshots

[pjones]

Problem Description

We need to audit all of the layout modules and improve their documentation. Many don't even say what they do or are very confusing. It would also be nice to take a screenshot of each layout and include it in the xmonad wiki with a link to the screenshot in the module documentation.

What to do?

1. Add a bullet item to the layouts wiki page
2. List the name of the layout and its description
3. Add the layout to your xmonad configuration (or to xmonad-testing), load up some impressive looking windows, and take a screenshot.
4. Check the layout off the list in this issue

Module Checklist

• [ ] Accordion.hs
• [ ] AutoMaster.hs
• [ ] AvoidFloats.hs
• [ ] BinaryColumn.hs
• [ ] BinarySpacePartition.hs
• [ ] BorderResize.hs
• [ ] BoringWindows.hs
• [ ] ButtonDecoration.hs
• [ ] CenteredMaster.hs
• [ ] Circle.hs
• [ ] Column.hs
• [ ] Combo.hs
• [ ] ComboP.hs
• [ ] Cross.hs
• [ ] Decoration.hs
• [ ] DecorationAddons.hs
• [ ] DecorationMadness.hs
• [ ] Dishes.hs
• [ ] MultiDishes.hs
• [ ] DragPane.hs
• [ ] DraggingVisualizer.hs
• [ ] Drawer.hs
• [ ] Dwindle.hs
• [ ] DwmStyle.hs
• [ ] FixedColumn.hs
• [ ] Fullscreen.hs
• [ ] Gaps.hs
• [ ] Grid.hs
• [ ] GridVariants.hs
• [ ] Groups.hs
• [ ] Groups.Examples.hs
• [ ] Groups.Helpers.hs
• [ ] Groups.Wmii.hs
• [ ] Hidden.hs
• [ ] HintedGrid.hs
• [ ] HintedTile.hs
• [ ] IM.hs
• [ ] IfMax.hs
• [ ] ImageButtonDecoration.hs
• [ ] IndependentScreens.hs
• [ ] LayoutBuilder.hs
• [ ] LayoutBuilderP.hs
• [ ] LayoutCombinators.hs
• [ ] LayoutHints.hs
• [ ] LayoutModifier.hs
• [ ] LayoutScreens.hs
• [ ] LimitWindows.hs
• [ ] MagicFocus.hs
• [x] Magnifier.hs
• [ ] Master.hs
• [ ] Maximize.hs
• [ ] MessageControl.hs
• [ ] Minimize.hs
• [ ] Monitor.hs
• [ ] Mosaic.hs
• [ ] MosaicAlt.hs
• [ ] MouseResizableTile.hs
• [ ] MultiColumns.hs
• [ ] MultiToggle.hs
• [ ] MultiToggle.Instances.hs
• [ ] MultiToggle.TabBarDecoration.hs
• [ ] Named.hs
• [ ] NoBorders.hs
• [ ] NoFrillsDecoration.hs
• [ ] OnHost.hs
• [ ] OneBig.hs
• [ ] PerScreen.hs
• [ ] PerWorkspace.hs
• [ ] PositionStoreFloat.hs
• [ ] Reflect.hs
• [ ] Renamed.hs
• [ ] ResizableTile.hs
• [ ] ResizableThreeColumns.hs
• [ ] ResizeScreen.hs
• [ ] Roledex.hs
• [ ] ShowWName.hs
• [ ] SimpleDecoration.hs
• [ ] SimpleFloat.hs
• [ ] Simplest.hs
• [ ] SimplestFloat.hs
• [ ] SortedLayout.hs
• [ ] Spacing.hs
• [ ] Spiral.hs
• [ ] Square.hs
• [ ] StackTile.hs
• [ ] StateFull.hs
• [ ] Stoppable.hs
• [ ] SubLayouts.hs
• [ ] TabBarDecoration.hs
• [ ] Tabbed.hs
• [ ] TallMastersCombo.hs
• [ ] ThreeColumns.hs
• [ ] ToggleLayouts.hs
• [ ] TrackFloating.hs
• [ ] TwoPane.hs
• [ ] TwoPanePersistent.hs
• [ ] VoidBorders.hs
• [ ] WindowArranger.hs
• [ ] WindowNavigation.hs
• [ ] WindowSwitcherDecoration.hs
• [ ] WorkspaceDir.hs
• [ ] ZoomRow.hs

[pjones]

I expect that several people are going to be involved in this issue. Things I would love to see come out of this:

• Identify overlapping functionality between multiple layouts that could be merged into a single module. In other words, let's clean up the layouts, many of them do the same thing (i.e., LayoutBuilder and Combo).

• Deprecate older novelty layouts such as Roledex. We might need to take a vote on which layouts should be deprecated.

• Remove all of the redundant comments that mention how to modify your configuration file. Let's move that out into proper documentation somewhere. Each layout can then focus on describing its own features.

Anything else?

[pjones]

To make this a bit easier, let's break this issue into several phases and we'll focus on phase one for now.

Phase 1: Document all of the existing layouts. For each layout:

1. Add a bullet item to the layouts wiki page

2. List the name of the layout and its description

3. Add the layout to your xmonad configuration (or to xmonad-testing), load up some impressive looking windows, and take a screenshot.

4. Check the layout off the list in this issue

For now let's focus on concrete layouts. That is, skip layout combinators and layout modifiers.

[bforte]

I went ahead and split up all the modules into two groups: Modifiers and Layouts. For the layouts I included a short description with a minimal setup to get a working layoutHook for a screenshot session. Also I started gathering information about possible changes (see here), these are just first ideas. Any opinions/suggestions about these? How should we continue from here?

About the screenshots: What's impressive looking? Should it be a light or dark theme? Should the layout be kept unmodified, ie. no spacing or noFrillsDeco, what background image etc.?

Another suggestion would be to just generate/create a visual description like the image below (possibly add a red border around the master)? (Some of) these could also be transformed/converted to *.xbm files and used in statusbars which would be cool.

[xrvdg]

This is a great idea. I spent the last two days configuring XMonad and the docs can definitely be improved regarding the layouts.

However, I think the approach suggested here is not the primary way to go. The approach sketched here, using phases, works if someone would systematically go through all the layouts and documents them. But seeing how little activity this issue has seen, I doubt that this is going to happen.

Therefore I would suggest a more ad hoc way approach. 1) Create an issue to start a discussion about an aspect of the layouts. Be it overlapping functionality, suggestion to deprecate, etc. This way there won't be multiple discussion going on in the comments of this issue. 2) From the new issue link back to this issue. Now this issue can act as an overview and as a place more meta discussions; for example, the visual description suggestion of bforte.

I am not familiar with the way GitHub handles and groups issues, but it seems rather simplistic. So this is what I came up with.

[mikenrafter]

I'm up for the task (the screenshot part). This weekend, I'll formulate a script to take these screenshots en massé. Then run it. I'll generate them with the alacritty terminal visible, btm system manager, a clean librewolf instance, and random themes, courtesy of pywal. That way, people will get a chance to see what different themes look like with layouts. Plus, these screenshots will be unixPorn-rice-esk, making them more appealing to users.

Things to consider:

• Should I use a default xmobar config for the layouts? My current one is very visually pleasing.
• I'm planning on keeping struts enabled. Thoughts?
• Where would we host these screenshots?
  • People cloning the repository wouldn't want these screenshots.
  • Does the github-wiki allow separate storage?

[geekosaur]

What do you mean by separate storage? That said, we really aren't using the github wiki yet. I've been trying to migrate us from the Haskell wiki, but it's been slow going because (for example) the FAQ page is positively primordial (doesn't even know about cabal much less stack, assumes you still run runhaskell Setup.hs to install things).

[liskin]

Where would we host these screenshots?

• People cloning the repository wouldn't want these screenshots.
• Does the github-wiki allow separate storage?

We've been using GitHub attachments (attach an image when writing a comment or editing a file through GitHub web interface, then copy the image URI and use it elsewhere) so far, but there's some risk these URIs will stop working in 5 or 10 years. If you want to mitigate that risk, it's probably okay to place the images on the xmonad.org website.

[mikenrafter]

Alright, xmonad.org it is.

Any thoughts on the screenshot style? Or does my ricing-idea seem good?

[geekosaur]

My own thought would be that we're focusing on the layouts, so ricing other things just draws attention away from the important part.

[slotThe]

Any thoughts on the screenshot style? Or does my ricing-idea seem good?

Maybe you could post an example screenshot? But I also think that the focus should really be on the layout in question

[mikenrafter]

Examples made manually with my current config: Or

[mikenrafter]

In these examples I rearranged the windows for their optimal use-case.
In my script, I will make an automated variant of the same.

I'll also plug XMobar into the colors.

I also plan on having 2+ screenshots for some layout modifiers, like magnifier.

[geekosaur]

That's actually a good idea, to show not only (say) before/after of Magnifier but also how it combines with various base layouts.

[liskin]

Examples made manually with my current config:

I find these screenshots somewhat lacking in contrast due to the background color being very similar to the terminal background. Can you perhaps try using a background color that's distinctly not black/white, to make the layout itself stand out? Alternatively drop the white browser window and just use white background.

Basically what I'd love to see is this level of clarity. It doesn't need to be perfectly clean, but the background color seems like an easy win. :-)

[slotThe]

Perhaps using thick borders instead of gaps could also increase the contrast

[mikenrafter]

I also plan on having 2+ screenshots for some layout modifiers, like magnifier.

And, to show how different stackset focal-points affect the behavior, like: magnifier'.

Perhaps using thick borders instead of gaps could also increase the contrast

I'll tweak it for clarity. Either more gaps, &/or thicker borders. I'll fiddle with it.

... somewhat lacking in contrast due to the background color being very similar to the terminal background.

Yes, I'll use something brighter. As a pywal user, I find the themes hard to read upon, unless there's a different background. So, in my latest theme generation, I've used a custom bg, and I find it much more legible and distinct.

[mikenrafter]

Progress update: spent a few hours making layouts. I'm almost ready to run the script. Just need to fix some ambiguous names...

[mikenrafter]

https://github.com/mikenrafter/xmonad-layout-screenshots
There's my first round of work. Some layouts will need manual intervention.

[slotThe]

@mikenrafter what's the status here? It would really be neat if we could include it in 0.17.1 (which may or may not be released soon-ish)

[mikenrafter]

As far as I'm concerned, it's all production-ready.
It's under the Unlicense, use as you please.

[slotThe]

As far as I'm concerned, it's all production-ready.

Oh, I see; thanks! You said that some required manual intervention, so I figured you were still trying things out. Would you like to prepare a PR with these then?

As a side-note, I'm not sure I get the joke

What do you call Linux' bodyguards with no balls? | Unix

and perhaps these "official" pictures would do good without that :)

[geekosaur]

As a side-note, I'm not sure I get the joke

What do you call Linux' bodyguards with no balls? | Unix

"Eunuchs"

[liskin]

Basically what I'd love to see is this level of clarity. It doesn't need to be perfectly clean, but the background color seems like an easy win. :-)

I probably mentioned this in IRC, but to have it on record: cleaner images compress way better, whereas what we have here so far is on the order of dozens/hundreds of megabytes, which is just too much IMO.