fixup! Update docs

README.md

@@ -14,15 +14,6 @@ Preproduction quality
   - But [config](./config-examples/default-config.toml) is self-explanatory
   - If you're familiar with i3, you can already make it usable for yourself
 
-## Installation
-
-1. Download the latest available zip from [releases page](https://github.com/nikitabobko/AeroSpace/releases)
-2. Unpack zip
-3. Move unpacked `AeroSpace.app` to `/Applications`
-
-Homebrew cask will be provided in the future. For now, it's better to subscribe to GitHub releases page to get notifications about
-updates
-
 ## Key features
 
 - **Manual** tiling window manager
@@ -36,7 +27,38 @@ updates
 - Proper multi-monitor support (i3-like paradigm)
 - Status menu icon displays current workspace name
 
-## [AeroSpace Guide](./docs/guide.md)
+## Installation
+
+Install via Homebrew to get autoupdates (Preferred)
+```
+brew install --cask nikitabobko/tap/aerospace
+xattr -d com.apple.quarantine /Applications/AeroSpace.app
+```
+
+### Manual installation
+
+1. Download the latest available zip from [releases page](https://github.com/nikitabobko/AeroSpace/releases)
+2. Unpack zip
+3. Move unpacked `AeroSpace.app` to `/Applications`
+
+If you see this message
+
+> "AeroSpace.app" can't be opened because Apple cannot check it for malicious software.
+
+then you can resolve it this way
+```
+xattr -d com.apple.quarantine /Applications/AeroSpace.app
+```
+
+or:
+1. navigate in Finder to /Applications/AeroSpace.app
+2. Right mouse click
+3. Open (yes, it's that stupid)
+
+## Docs
+
+- [AeroSpace Guide](./docs/guide.md)
+- [AeroSpace list of all commands](./docs/commands.md)
 
 ## How to build the project
 

config-examples/default-config.toml

@@ -21,9 +21,7 @@ start-at-login = false
 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
+# See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#layouts
 # 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,110 @@
 - [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) (Possible values: `list`, `accordion`)
+  2. Orientation (Possible values: `horizontal`, `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 nest containers as deeply 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.
+
+The tree structure can be changed 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.
+- The horizontal accordion shows left and right paddings to visually indicate the presence of other windows in those directions.
+- The vertical accordion shows top and bottom paddings to visually indicate the presence of other windows in those 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.
+
+Accordion padding is configurable via `accordion-padding` option (see [default-config.toml](../config-examples/default-config.toml))
 
 ### Normalization
-TODO DOCUMENTATION
+
+By default, AeroSpace does two types of tree normalizations:
+- Containers that have only one child are "flattened"
+- Containers that nest into each other must have opposite orientations
+
+**Example 1**
+
+According to the first normalization, such layout isn't possible:
+```
+h_list
+└── v_list
+    └── window 1
+```
+
+it will be immediately transformed into
+```
+v_list
+└── window 1
+```
+
+**Example 2**
+
+According to the second normalization, such layout isn't possible:
+```
+h_list
+├── window 1
+└── h_list
+    ├── window 2
+    └── window 3
+```
+
+it will be immediately transformed into
+```
+h_list
+├── window 1
+└── v_list
+    ├── window 2
+    └── window 3
+```
+
+Normalizations makes it easier to understand the tree structure by looking at how windows are placed on the screen.
+
+You can disable normalizations by placing these lines into your config:
+```
+enable-normalization-flatten-containers = false
+enable-normalization-opposite-orientation-for-nested-containers = false
+```
 
 ### Floating windows
 TODO DOCUMENTATION
@@ -27,6 +128,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 +137,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 +159,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
         }
     }
 }