fixup! Update docs

config-examples/default-config.toml

@@ -22,8 +22,8 @@ enable-normalization-flatten-containers = true
 enable-normalization-opposite-orientation-for-nested-containers = true
 
 # Accordion is a layout where windows are placed on top of each other.
-# - Horizontal accordion puts paddings on left and right to make it clear that containers exist in these directions
-# - Vertical accordion puts paddings on above and below to make it clear that containers exist in these directions
+# - Horizontal accordion puts paddings on left and right to make it clear that other windows exist in these directions
+# - Vertical accordion puts paddings on above and below to make it clear that other windows exist in these directions
 # The 'accordion-padding' specifies the size of the padding. You can set 0 to disable the padding feature
 accordion-padding = 30
 

docs/commands.md

@@ -107,11 +107,97 @@ mode name_of_the_target_mode
 ## move-through
 
 ```
-move-through (left|down|up|right)
+move-through (left|down|up|right) [floating_pixel]
 ```
 
+Moves the window in the given direction. The optional `floating_pixel` argument specifies how far the window should be moved if
+it is floating. The default is 50 pixels
+
 This command is an analog of [i3's move command](https://i3wm.org/docs/userguide.html#move_direction)
 
+**Example 1**
+
+Given this layout
+```
+h_list
+├── window 1 (focused)
+└── window 2
+```
+
+`move-through right` will result in the following layout
+```
+h_list
+├── window 2
+└── window 1 (focused)
+```
+
+**Example 2**
+
+Given this layout
+```
+h_list
+├── window 1
+├── window 2 (focused)
+└── v_list
+    ├── window 3
+    └── window 4
+```
+
+`move-through right` will result in the following layout
+```
+h_list
+├── window 1
+└── v_list
+    ├── window 3
+    ├── window 2 (focused)
+    └── window 4
+```
+
+**Example 3**
+
+Given this layout
+```
+h_list
+├── window 1
+└── v_list
+    ├── window 3
+    ├── window 2 (focused)
+    └── window 4
+```
+
+`move-through left` will result in the following layout
+```
+h_list
+├── window 1
+├── window 2 (focused)
+└── v_list
+    ├── window 3
+    └── window 4
+```
+
+**Implicit container example**
+
+In some cases, `move-through` needs to implicitly create a container to fullfill your command.
+
+Given this layout
+```
+h_list
+├── window 1
+├── window 2 (focused)
+└── window 3
+```
+
+`move-through up` will result in the following layout
+```
+v_list
+├── window 2  (focused)
+└── h_list
+    ├── window 1
+    └── window 3
+```
+
+`v_list` is an implicitly created container.
+
 ## move-workspace-to-display
 
 ## reload-config

docs/guide.md

@@ -3,6 +3,7 @@
 **Table of contents**
 
 - [Tree](#tree)
+  - [Layouts](#layouts)
   - [Normalization](#normalization)
   - [Floating windows](#floating-windows)
 - [Default keybindings](#default-keybindings)
@@ -15,10 +16,64 @@
 - [Multiple displays](#multiple-displays)
 
 ## Tree
-TODO DOCUMENTATION. This section is yet to be written, for now you can refer to https://i3wm.org/docs/userguide.html#tree
+
+AeroSpace stores all windows and containers in a tree. AeroSpace tree tiling model is [inspired by
+i3](https://i3wm.org/docs/userguide.html#tree).
+
+- Each workspace contains its own single root node
+- Each non-leaf node can contain arbitrary number of children nodes
+- Windows are the only possible leaf nodes. Windows contain zero children nodes
+- Every non-leaf node has two properties:
+  1. [Layout](#layouts) (list or accordion)
+  2. Orientation (horizontal or vertical)
+
+When we say "layout of the window", we refer to the layout of the window's parent.
+
+It's easier to understand tree tiling model by looking at examples
+
+![](./.assets/h_list.png)
+![](./.assets/tree.png)
+
+You can have as deeply layout as you want to.
+
+You can navigate in the tree in 4 possible cardinal directions (left, down, up, right). You use [focus
+command](./commands.md#focus) to navigate in the tree.
+
+You can change the tree structure with two commands:
+- [move-through](./commands.md#move-through)
+- [move-in](./commands.md#move-in)
+
+### Layouts
+
+In total, AeroSpace provides 4 possible layouts:
+- horizontal list (in i3, it's called "horizontal split")
+- vertical list (in i3, it's called "vertical split")
+- horizontal accordion (analog of i3's "tabbed layout")
+- vertical accordion (analog of i3's "stacked layout")
+
+From the previous section, you're already familiar with the List layout.
+
+Accordion is a layout where windows are placed on top of each other.
+- Horizontal accordion puts paddings on left and right to make it clear that other windows exist in these directions
+- Vertical accordion puts paddings on above and below to make it clear that other windows exist in these directions
+
+Horizontal accordion looks like this
+
+<img src="./.assets/h_accordion.png" width="60%" height="60%">
+
+Vertical accordion looks like this
+
+<img src="./.assets/v_accordion.png" width="60%" height="60%">
+
+Just like in a list layout, you can use the [focus](./commands.md#focus) command to navigate an accordion layout.
+
+You can navigate the windows in an `h_accordion` by using the `focus (left|right)` command, while in a `v_accordion`, you can
+navigate the windows using the `focus (up|down)` command.
 
 ### Normalization
-TODO DOCUMENTATION
+
+By default, AeroSpace does two types of normalizations to the tree:
+- Containers that have only one child are "flattened".
 
 ### Floating windows
 TODO DOCUMENTATION
@@ -27,6 +82,7 @@ Normally, floating windows are not part of the tiling tree. But it's not the cas
 perspective, floating windows are part of the tree. 
 
 ## Default keybindings
+
 TODO DOCUMENTATION the idea behind default keybindings
 
 ## Configuring AeroSpace
@@ -35,8 +91,8 @@ AeroSpace will read config file from `~/.aerospace.toml`. Please see the followi
 - The default config contains all possible keys with comments: [default-config.toml](../config-examples/default-config.toml)
 - i3 like config: [i3-like-config-example.toml](../config-examples/i3-like-config-example.toml)
 
-AeroSpace uses TOML format for the config. TOML is a popular format with open specification. TOML is easy to read, and it supports
-comments. See [TOML site for more info](https://toml.io/en/)
+AeroSpace uses TOML format for the config. TOML is easy to read, and it supports comments. See [TOML site for more
+info](https://toml.io/en/)
 
 ### Binding modes
 TODO DOCUMENTATION
@@ -57,7 +113,18 @@ TODO DOCUMENTATION
 Enable 'Group windows by application'
 
 ### A note on 'Displays have separate Spaces'
-TODO DOCUMENTATION
+
+AeroSpace doesn't care about `System Settings -> Desktop & Dock -> Displays have separate Spaces` setting. It works equally good
+whether this option is turned off or on.
+
+Overview of 'Displays have separate Spaces'
+
+|                                                             | 'Displays have separate Spaces' is enabled | 'Displays have separate Spaces' is disabled |
+|-------------------------------------------------------------|--------------------------------------------|---------------------------------------------|
+| When the first display is in fullscreen                     | 😊 Second monitor operates independently   | 😔 Second monitor is unusable black screen  |
+| Is it possible to place a window on the border of monitors? | 😔 No                                      | 😊 Yes                                      |
+| macOS status bar ...                                        | ... is displayed on both monitors          | ... is displayed only on main monitor       |
+
 
 ## Multiple displays
 TODO DOCUMENTATION

src/command/FocusCommand.swift

@@ -6,6 +6,7 @@ struct FocusCommand: Command {
         guard let currentWindow = focusedWindowOrEffectivelyFocused else { return }
         let workspace = currentWindow.workspace
         // todo floating windows break mru
+        // todo floating non AXStandardWindow shouldn't be part of the tree
         let floatingWindows = makeFloatingWindowsSeenAsTiling(workspace: workspace)
         defer {
             restoreFloatingWindows(floatingWindows: floatingWindows, workspace: workspace)

src/command/MoveThroughCommand.swift

@@ -22,7 +22,7 @@ struct MoveThroughCommand: Command {
                 moveOut(window: currentWindow, direction: direction)
             }
         case .workspace: // floating window
-            break // todo
+            break // todo support moving floating windows
         }
     }
 }