WIP guide

README.md

@@ -2,7 +2,7 @@
 
 AeroSpace is a tiling window manager for macOS.
 
-## Status
+## Project status
 
 🚧 **Work in progress.** Not usable yet 🚧
 
@@ -14,14 +14,17 @@ I will publish first release once I believe it's usable, so subscribe to release
 
 - **Manual** tiling window manager
 - [i3](https://i3wm.org/) inspired
-- AeroSpace employs its **own emulation of virtual workspaces** instead of relying on native macOS Spaces due to
+- 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)
 - **[PLANNED]** CLI scriptable
 - Doesn't require disabling SIP (System Integrity Protection)
 - Proper multi-monitor support (i3-like paradigm)
 - Status menu icon displays current workspace name
 
+## [AeroSpace Guide](./docs/guide.md)
+
 ## How to build the project
 
 You would need a Mac.
@@ -37,43 +40,43 @@ Firstly, install [xcodegen](https://github.com/yonaskolb/XcodeGen). Then run in
 ./run-tests.sh
 ```
 
-## Todo
-
-- is dialog, is resizable, is modal?
-- select parent and kill several windows at once
-- select parent -> outline several windows?
-  - OR: outline with "SLSSetWindowOpacity"
-  - OR: "shake" windows
-- CLI interface
-- Check all todos in code
-- move vs swap
-- what is src/Assets.xcassets ?
-- license
-- unminimize apps automatically
-- minimized apps handling
-- macOS fullscreen apps handling
-- unhide apps automatically
-
-## Challenges
-
-- Window overlapping
-- "floating" window layout
-- windows' min/max sizes
-
-## Known Special windows to check
-
-- XCode welcome screen
-- Finder preview
-- Finder tabs
-- Chrome create bookmark window
-- Toolbox window
-- IntelliJ dialog windows (e.g. "Add to git")
-- IntelliJ project structure modal window blocks main window resize
-- VLC full screen window (eh, I wish every fullscreen window in macOS worked like that)
-- iTerm drop down window
-- Chrome cmd+f window
-
-## Limitations of macOS API
-
-- It's not possible to find to what monitor window is assigned
-- It's not possible to __reliably__ know what monitor is currently active
+## Values of the project
+
+**Values**
+- AeroSpace is targeted at advanced users and developers
+- Keyboard centric
+- Never break configuration files or existing workflows (Guaranteed once AeroSpace reaches 1.0 version)
+- AeroSpace doesn't use GUI, unless necessarily
+  - AeroSpace will never provide a GUI for configuration. For advanced users, it's easier to edit a configuration file in text
+    editor rather than navigating through checkboxes in GUI.
+  - Status menu icon is ok, because visual feedback is needed
+- Provide _practical_ features. Fancy appearance features are not _practical_
+- If "dark magic" (aka "private APIs", "code injections", etc) can be avoided, it must be avoided
+  - Right now, AeroSpace uses only a [single private API](./src/Bridged-Header.h). Everything else is [macOS public accessibility
+    API](https://developer.apple.com/documentation/applicationservices/axuielement_h).
+  - AeroSpace will never require you to disable SIP (System Integrity Protection). For example, yabai [requires you to disable
+    SIP](https://github.com/koekeishiya/yabai/issues/1863) to use some of its features. AeroSpace will either find another way
+    (e.g. [emulation of workspaces](./docs/guide.md#emulation-of-virtual-workspaces)) or will not implement this feature at all
+    (window transparency and window shadowing are not _practical_ features)
+
+**Non Values**
+- Play nicely with existing macOS features. If limitations are imposed then AeroSpace won't play nicely with existing macOS
+  features
+  - E.g. AeroSpace doesn't acknowledge the existence of macOS Spaces, and it uses [emulation of its own
+    workspaces](./docs/guide.md#emulation-of-virtual-workspaces)
+
+## Tip of the day
+
+```bash
+defaults write -g NSWindowShouldDragOnGesture YES
+```
+
+Now, you can move windows by holding `ctrl`+`cmd` and dragging any part of the window (not necessarily the window title)
+
+Source: [reddit](https://www.reddit.com/r/MacOS/comments/k6hiwk/keyboard_modifier_to_simplify_click_drag_of/)
+
+## Related projects
+
+If AeroSpace doesn't work for you, take a look at projects by other authors:
+- [Amethyst](https://github.com/ianyh/Amethyst)
+- [yabai](https://github.com/koekeishiya/yabai)

config-examples/default-config.toml

@@ -1,26 +1,50 @@
-# For all possible keys and modifiers see: https://github.com/nikitabobko/AeroSpace/blob/main/src/config/keysMap.swift
+# You can use it to add commands that run after login to macOS user session.
+# 'start-at-login' needs to be 'true' for 'after-login-command' to work
+# For the list of available commands see: https://github.com/nikitabobko/AeroSpace/blob/main/docs/commands.md
+after-login-command = []
 
-# todo review defaults
+# You can use it to add commands that run after AeroSpace startup.
+# 'after-startup-command' is run after 'after-login-command'
+# For the list of available commands see: https://github.com/nikitabobko/AeroSpace/blob/main/docs/commands.md
+after-startup-command = []
 
-after-login-command = [] # You can use it to add command or commands that run after login to macOS user session.
-after-startup-command = [] # You can use it to add command or commands that run after startup.
+# Visual indent makes it easier to understand that containers of the same orientation are nested.
+# If you have 'auto-opposite-orientation-for-nested-containers' enabled then there is no way to observe the indent
 indent-for-nested-containers-with-the-same-orientation = 30
-enable-normalization-flatten-containers = true
-enable-normalization-opposite-orientation-for-nested-containers = true
+
+# todo Not tested
 start-at-login = false
+
+# todo drop. I don't see any value in providing configuration for this option. Why would anyone may want to set it
+#  to 'false'?
 floating-windows-on-top = true
-main-layout = 'h_list' # todo change
-DEBUG-all-windows-are-floating = false # todo drop
-accordion-padding = 30 # todo dp?
 
+# Normalization. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#normalization
+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
+# The 'accordion-padding' specifies the size of the padding. You can set 0 to disable the padding feature
+accordion-padding = 30
+main-layout = 'h_list' # TODO SUBJECT TO CHANGE
+
+# DEBUG KEY. DON'T USE IT
+DEBUG-all-windows-are-floating = false # TODO DROP
+
+# It's a declaration of 'main' binding mode. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#bindings-modes
+# 'main' binding mode must be always presented
 [mode.main.binding]
+
+# For all possible keys and modifiers see: https://github.com/nikitabobko/AeroSpace/blob/main/src/config/keysMap.swift
+# For all possible commands see: https://github.com/nikitabobko/AeroSpace/blob/main/docs/commands.md
+
 alt-enter = 'exec-and-forget open -n /System/Applications/Utilities/Terminal.app'
 
 alt-slash = 'layout h_list v_list' # todo layout vs change-parent-container-kind
 alt-comma = 'layout h_accordion v_accordion'
 
-# todo focus floating binding
-
 alt-h = 'focus left'
 alt-j = 'focus down'
 alt-k = 'focus up'
@@ -106,6 +130,7 @@ alt-shift-z = 'move-container-to-workspace Z'
 alt-tab = 'workspace-back-and-forth'
 alt-shift-tab = 'move-workspace-to-display next'
 
+# It's a declaration of binding mode. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#bindings-modes
 [mode.service.binding]
 r = ['flatten-workspace-tree', 'mode main']
 o = ['reload-config', 'mode main']
@@ -115,6 +140,7 @@ backslash = ['close-all-windows-but-current', 'mode main']
 esc = 'mode main'
 enter = 'mode main'
 
+# It's a declaration of binding mode. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#bindings-modes
 [mode.move-in.binding]
 alt-shift-h = ['move-in left', 'mode main']
 alt-shift-j = ['move-in down', 'mode main']

docs/guide.md

@@ -0,0 +1,65 @@
+# AeroSpace Guide
+
+**Table of contents**
+
+- [Tree](#tree)
+  - [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)
+
+## Tree
+TODO DOCUMENTATION. This section is yet to be written, for now you can refer to https://i3wm.org/docs/userguide.html#tree
+
+### Normalization
+TODO DOCUMENTATION
+
+### Floating windows
+TODO DOCUMENTATION
+
+Normally, floating windows are not part of the tiling tree except for the 'focus' command. From 'focus' command perspective,
+floating windows are part of the tree.
+
+## Default keybindings
+TODO DOCUMENTATION the idea behind default keybindings
+
+## Configuring AeroSpace
+
+AeroSpace will read config file from `~/.aerospace.toml`. Please see the following config samples:
+- The default config 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/)
+
+### Binding modes
+TODO DOCUMENTATION
+
+### Commands
+
+AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
+
+## Emulation of virtual workspaces
+
+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
+
+When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen
+
+### A note on mission control
+TODO DOCUMENTATION
+Enable 'Group windows by application'
+
+### A note on 'Displays have separate Spaces'
+TODO DOCUMENTATION
+
+## Multiple displays
+TODO DOCUMENTATION
+TODO DOCUMENTATION. Add difference with i3
+