Update docs

.gitignore

@@ -2,6 +2,7 @@
 /.build
 # IDK, AppCode randomly creates this EMPTY file. I have no idea what this is
 /default.profraw
+/.DS_Store
 
 # XCode User settings
 xcuserdata/

README.md

@@ -4,27 +4,25 @@ AeroSpace is a tiling window manager for macOS.
 
 ## Project status
 
-🚧 **Active development** 🚧
+Public Beta. Feedback is very much welcome
 
-Preproduction quality
-- Expect bugs
-- Expect not polished experience
-- Expect breaking changes in the config format
-- [The documentation](./docs/guide.md) is not yet ready
-  - But [config](./config-examples/default-config.toml) is self-explanatory
-  - If you're familiar with i3, you can already make it usable for yourself
+- I encourage you to try AeroSpace and [share the general feedback](https://github.com/nikitabobko/AeroSpace/issues/11).
+  In particular, I'm interested in issues that block you from using AeroSpace.
+- I already use AeroSpace on daily basis and I'm happy with it
+- [The documentation](./docs/guide.md) covers all major things you need to know
+- Expect minor breaking changes in the config format. Once the project reaches 1.0 the config is guaranteed to preserve backwards
+  compatibility
 
 ## Key features
 
-- **Manual** tiling window manager
+- **Manual** tiling window manager based on a [tree paradigm](./docs/guide.md#tree)
 - [i3](https://i3wm.org/) inspired
 - AeroSpace employs its [own emulation of virtual workspaces](./docs/guide.md#emulation-of-virtual-workspaces) instead of relying
-  on native macOS Spaces due to
-  their considerable limitations
-- Plain text configuration (dotfiles friendly)
+  on native macOS Spaces due to [their considerable limitations](./docs/guide.md#emulation-of-virtual-workspaces)
+- Plain text configuration (dotfiles friendly). See: [default-config.toml](./config-examples/default-config.toml)
 - ~~CLI scriptable~~ [[PLANNED]](https://github.com/nikitabobko/AeroSpace/issues/3)
-- Doesn't require disabling SIP (System Integrity Protection)
-- Proper multi-monitor support (i3-like paradigm)
+- No need to disable SIP (System Integrity Protection)
+- [Proper multi-display support](./docs/guide.md#multiple-displays) (i3-like paradigm)
 - Status menu icon displays current workspace name
 
 ## Installation

docs/commands.md

@@ -75,7 +75,8 @@ Sets focus to the nearest window in [the tree](./guide.md#tree) in the given dir
 
 [Contrary to i3](https://i3wm.org/docs/userguide.html#_focusing_moving_containers), `focus` command doesn't have a separate
 argument to focus floating windows. From `focus` command perspective, floating windows are part of [the tree](./guide.md#tree).
-The floating window parent is determined as the smallest tiling container that contains the center of the floating window.
+The floating window parent container is determined as the smallest tiling container that contains the center of the floating
+window.
 
 This technique eliminates the need for an additional binding for floating windows.
 
@@ -87,7 +88,7 @@ This technique eliminates the need for an additional binding for floating window
 join-with (left|down|up|right)
 ```
 
-Puts the currently focused window and the nearest container in the specified direction under a common parent container.
+Puts the currently focused window and the nearest node in the specified direction under a common parent container.
 
 Given this layout
 ```
@@ -129,8 +130,16 @@ found layout.
 mode name_of_the_target_mode
 ```
 
+Activates the specified [binding mode](./guide.md#bindings-modes)
+
 ## move-container-to-workspace
 
+```
+move-container-to-workspace target_workspace_name
+```
+
+Moves currently focused window to the specified workspace
+
 ## move-through
 
 ```
@@ -227,10 +236,53 @@ v_list
 
 ## move-workspace-to-display
 
+```
+move-workspace-to-display (next|prev)
+```
+
+Moves currently active workspace to the next or previous display
+
 ## reload-config
 
+```
+reload-config
+```
+
+Reloads currently active config. This command doesn't have any arguments.
+
 ## resize
 
+```
+resize (smart|width|height) [+|-]number
+```
+
+Resizes the currently active window
+
+The dimension to resize is chosen by the first argument
+
+- `width` changes width
+- `height` changes height
+- `smart` changes width if the parent has horizontal orientation, and it changes height if the parent has vertical orientation
+
+Second argument controls how much the size is changes
+
+- If the `number` is prefixed with `+` then the dimension is increased
+- If the `number` is prefixed with `-` then the dimension is decreased
+- If the `number` is prefixed with neither `+` nor `-` then the command changes the absolute value of the dimension
+
 ## workspace-back-and-forth
 
+```
+workspace-back-and-forth
+```
+
+Switches between currently active workspace and previously active workspace back and forth. This command doesn't have any
+arguments.
+
 ## workspace
+
+```
+workspace target_workspace_name
+```
+
+Activates the specified workspace

docs/guide.md

@@ -2,32 +2,69 @@
 
 **Table of contents**
 
+- [Configuring AeroSpace](#configuring-aerospace)
+  - [Binding modes](#bindings-modes)
+  - [Commands](#commands)
 - [Tree](#tree)
   - [Layouts](#layouts)
   - [Normalization](#normalization)
   - [Floating windows](#floating-windows)
-- [Default keybindings](#default-keybindings)
-- [Configuring AeroSpace](#configuring-aerospace)
-  - [Binding modes](#bindings-modes)
-  - [Commands](#commands)
 - [Emulation of virtual workspaces](#emulation-of-virtual-workspaces)
   - [A note on mission control](#a-note-on-mission-control)
   - [A note on 'Displays have separate Spaces'](#a-note-on-displays-have-separate-spaces)
 - [Multiple displays](#multiple-displays)
 
+## Configuring AeroSpace
+
+AeroSpace will read config file from `~/.aerospace.toml`. Please see the following config samples:
+- 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 easy to read, and it supports comments. See [TOML site for more
+info](https://toml.io/en/)
+
+### Binding modes
+
+You can create multiple sets of bindings by creating different binding modes. When you switch to a different binding mode, all
+the bindings from the current mode are deactivated, and only the bindings specified in the new mode become active. The initial
+binding mode that AeroSpace starts out with is "main".
+
+This feature is absolutely identical to the one [in i3](https://i3wm.org/docs/userguide.html#binding_modes)
+
+Working with binding modes consists of two parts: 1. defining a binding to switch to the binding mode and 2. declaring the binding
+mode itself.
+
+```toml
+[mode.main.binding] # Declare 'main' binding mode
+alt-r = 'mode resize' # 1. Define a binding to switch to 'resize' mode
+
+[mode.resize.binding] # 2. Declare 'resize' binding mode
+minus = 'resize smart -50'
+equal = 'resize smart +50'
+```
+
+### Commands
+
+AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
+
 ## 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).
 
+**Definition.** Each non-leaf node is called a "Container"
+
+> [!WARNING]
+> i3 has a different terminology. In i3, terms "container" and "node" are the same.
+
 - Each workspace contains its own single root node
-- Each non-leaf node can contain arbitrary number of children nodes
+- Each container 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:
+- Every container 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.
+When we say "layout of the window", we refer to the layout of the window's parent container.
 
 It's easier to understand tree tiling model by looking at examples
 
@@ -123,46 +160,54 @@ enable-normalization-opposite-orientation-for-nested-containers = false
 ```
 
 ### Floating windows
-TODO DOCUMENTATION
 
-Normally, floating windows are not part of the tiling tree. But it's not the case with `focus` command. From `focus` command
-perspective, floating windows are part of the tree. 
+Normally, floating windows are not considered to be part of the [tiling tree](#tree). But it's not the case with
+[`focus`](./commands.md#focus) command.
 
-## Default keybindings
+From [`focus`](./commands.md#focus) command perspective, floating windows are part of [the tree](#tree). The floating window
+parent container is determined as the smallest tiling container that contains the center of the floating window.
 
-TODO DOCUMENTATION the idea behind default keybindings
+This technique eliminates the need for an additional binding for focusing floating windows.
 
-## Configuring AeroSpace
+## Emulation of virtual workspaces
 
-AeroSpace will read config file from `~/.aerospace.toml`. Please see the following config samples:
-- 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)
+Native macOS Spaces have a lot of problems.
 
-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/)
+- The animation for Spaces switching is slow
+  - You can't disable animation for Spaces switching (you can only make it slightly faster by turning on `Reduce motion` setting,
+    but it's suboptimal)
+- You have a limit of Spaces (up to 16 Spaces with one monitor)
+- You can't create, delete, reorder Spaces with hotkeys
+- Apple doesn't provide public API to create, delete, reorder and switch Spaces
 
-### Binding modes
-TODO DOCUMENTATION. For now you can refer to https://i3wm.org/docs/userguide.html#binding_modes
+Since Spaces are so hard to deal with, AeroSpace reimplements Spaces and calls them "Workspaces". The idea is that if the
+workspace isn't active then all of its windows are placed outside of the visible area of the screen, at the bottom right corner.
+Once you switch back to the workspace, (e.g. by the means of [`workspace`](./commands.md#workspace) command) windows are placed
+back to the visible area of the screen.
 
-### Commands
+When you quit the AeroSpace or when the AeroSpace is about to crash, AeroSpace will place all windows back to the visible area of
+the screen.
 
-AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
+> [!NOTE]
+> For better or worse, macOS doesn't allow to place windows outside of the visible area entirely. You will still be able to see a
+> few pixels of "hidden" windows at the bottom right corner of your screen. That means, that if AeroSpace crashes badly you will
+> still be able to manually "unhide" the windows by dragging these few pixels to the center of the screen.
 
-## Emulation of virtual workspaces
+The supposed workflow of using AeroSpace workspaces is to only have one macOS Space (or as many as monitors you have, if `Displays
+have separate Spaces` is enabled) and don't interact with macOS Spaces anymore.
 
-The supposed workflow is to only have one macOS Space (or as many as monitors you have) and don't interact with macOS spaces in
-any way
+### A note on mission control
 
-When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen
+For some reason, mission control doesn't like that AeroSpace puts a lot of windows at the bottom right corner of the screen.
+Mission control shows windows too small even if it has enough space to show them bigger.
 
-### A note on mission control
-TODO DOCUMENTATION
-Enable 'Group windows by application'
+To workaround it, you can enable `System Settings -> Desktop & Dock -> Group windows by application` setting. For some weird
+reason, it helps.
 
 ### A note on 'Displays have separate Spaces'
 
 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.
+whether this option is enabled or disabled.
 
 Overview of 'Displays have separate Spaces'
 
@@ -172,8 +217,27 @@ Overview of 'Displays have separate Spaces'
 | 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
-TODO DOCUMENTATION. Add difference with i3
 
+- The pool of workspaces is shared between displays
+- Each display shows its own workspace. The showed workspaces are called "active" workspaces
+- Different displays can't show the same workspace at the same time
+- Each workspace (even invisible, even empty) has a display assigned to it
+- By default, all workspaces are assigned to the "main" display (You can find the "main" display in `System -> Displays`)
+
+When you switch to a workspace:
+1. AeroSpace takes the assigned display of the workspace and makes the workspace active on the display
+2. AeroSpace focuses the workspace
+
+You can move workspace to a different display with [`move-workspace-to-display`](./commands.md#move-workspace-to-display) command. 
+
+The idea of making pool of workspaces shared is based on **the observation** that most users have a limited set of workspaces on
+their secondary displays. Secondary displays are frequently dedicated to specific tasks (browser, shell), or for monitoring
+various activities such as logs and dashboards. Thus, using one workspace per each secondary displays and "the rest" on the main
+display often makes sense.
+
+> [!NOTE]
+> The only difference between AeroSpace and i3 is switching to empty workspaces. When you switch to an empty workspace, AeroSpace
+> puts the workspace on an assigned display; i3 puts the workspace on currently active display.
+> - I find that AeroSpace model works better with **the observation** listed above.
+> - AeroSpace model is more consistent (it works the same for empty workspaces and non-empty workspaces)