clear up documentation + revamp manpage, README, add sxwm.md

just a bunch of documentation.
see diff to see more

3 files changed, 303 insertions, 0 deletions

diff --git a/docs/sxwm.1 b/docs/sxwm.1
new file mode 100644
index 0000000..6604a0e
--- /dev/null
+++ b/docs/sxwm.1
@@ -0,0 +1,164 @@
+.TH SXWM 1 "October 2025" "sxwm" "User Commands"
+.SH NAME
+sxwm \- simple X11 window manager
+.SH SYNOPSIS
+.B sxwm
+[\-v | \-\-version]
+.SH DESCRIPTION
+.B sxwm
+is a minimal, user-friendly tiling window manager for X11.
+It is configured through a plain text file and supports on-the-fly reconfiguration.
+
+.SH LAUNCH ARGUMENTS
+.TP
+.B \-v, \-\-version
+Displays the current version of
+.B sxwm.
+
+.SH CONFIGURATION
+.B sxwm
+is configured via a simple text file located at
+.I ~/.config/sxwmrc.
+Changes can be applied instantly by reloading the configuration (MOD + r).
+
+The file uses a
+.B key : value
+format. Lines starting with
+.B #
+are ignored.
+
+.SS General Options
+.TS
+allbox;
+c c c c
+l l l l.
+Option	Type	Default	Description
+_
+mod_key	String	super	Sets the primary modifier key (alt, super, ctrl).
+gaps	Integer	10	Pixels between windows and screen edges.
+border_width	Integer	1	Thickness of window borders in pixels.
+focused_border_colour	Hex	#c0cbff	Border color for the currently focused window.
+unfocused_border_colour	Hex	#555555	Border color for unfocused windows.
+swap_border_colour	Hex	#fff4c0	Border color when selecting a window to swap (MOD+Shift+Drag).
+master_width	Integer	60	Percentage of the screen width for the master window.
+motion_throttle	Integer	60	Target FPS for mouse drag actions.
+resize_master_amount	Integer	1	Percent to increase/decrease master width.
+resize_stack_amount	Integer	20	How many pixels to increase/decrease stack windows by.
+snap_distance	Integer	5	Distance (px) before a floating window snaps to edge.
+move_window_amount	Integer	10	Number of pixels to move the window with keyboard.
+resize_window_amount	Integer	10	Number of pixels to resize the window with keyboard.
+start_fullscreen	String	"st"	Starts specified windows that should start fullscreened. Enclosed in quotes and comma-seperated.
+new_win_focus	Bool	true	Whether openening new windows should also set focus to them or keep on current window.
+warp_cursor	Bool	true	Warp the cursor to the middle of newly focused windows.
+floating_on_top	Bool	true	Whether floating windows should always draw over tiled ones
+floating_on_top	Bool	true	Whether floating windows should always draw over tiled ones
+new_win_master	Bool	false	New windows will open as master window.
+should_float	String	"st"	Always-float rule. Multiple entries should be comma-seperated. Optionally, entries can be enclosed in quotes.
+exec	String	Nothing	Command to run on startup (e.g., sxbar, picom, "autostart", etc.).
+can_swallow	String	st	Windows that can swallow.
+can_be_swallowed	String	mpv	Windows that can be swallowed.
+.TE
+
+.SH KEYBINDINGS
+.SS Syntax
+Modifiers: mod, shift, ctrl, alt, super ...
+.br
+Key: Case-insensitive keysym (e.g., Return, q, 1)
+.RS
+To find the key do
+.B xev | grep "keysym"
+and press the key in the box.
+.RE
+Action: Either an external command (in quotes) or internal function.
+.br
+move: Move to that workspace
+.br
+swap: Swap window to that workspace
+.br
+_n_: Workspace / Scratchpad number
+.br
+create: Creates a scratchpad on that slot
+.br
+toggle: Toggles the visibility of that scratchpad
+.br
+remove: Removes the scratchpad on that slot
+
+.PP
+Example syntax:
+.PP
+.EX
+bind : modifier + ... + key : action
+.EE
+.PP
+.EX
+scratchpad : modifier + ... + key : create n
+scratchpad : modifier + ... + key : toggle n
+scratchpad : modifier + ... + key : remove n
+.EE
+.PP
+.EX
+workspace : modifier + ... + key : move n
+workspace : modifier + ... + key : swap n
+.EE
+
+.SS Available Functions
+.TS
+allbox;
+c c
+l l.
+Function Name	Description
+_
+centre_window	Centre the focused window.
+close_window	Closes the focused window.
+decrease_gaps	Shrinks gaps.
+focus_next	Moves focus forward in the stack.
+focus_prev	Moves focus backward in the stack.
+focus_next_mon	Switches focus to the next monitor.
+focus_prev_mon	Switches focus to the previous monitor.
+fullscreen	Fullscreen the focused window.
+global_floating	Toggles floating state for all windows.
+increase_gaps	Expands gaps.
+master_next	Moves focused window down in master/stack order.
+master_prev	Moves focused window up in master/stack order.
+master_increase	Expands master width.
+master_decrease	Shrinks master width.
+move_next_mon	Moves the focused window to the next monitor.
+move_prev_mon	Moves the focused window to the previous monitor.
+move_win_up	Moves the focused window up (keyboard).
+move_win_down	Moves the focused window down (keyboard).
+move_win_left	Moves the focused window left (keyboard).
+move_win_right	Moves the focused window right (keyboard).
+quit	Exits sxwm.
+reload_config	Reloads config.
+resize_win_up	Resizes the focused window up (keyboard).
+resize_win_down	Resizes the focused window down (keyboard).
+resize_win_left	Resizes the focused window left (keyboard).
+resize_win_right	Resizes the focused window right (keyboard).
+stack_increase	Increase the height of the focused stack window.
+stack_decrease	Decrease the height of the focused stack window.
+switch_previous_workspace	Switch to the previous workspace.
+toggle_floating	Toggles floating state of current window.
+.TE
+
+.SS Example Bindings
+.EX
+# Launch terminal
+bind : mod + Return : "st"
+# Close window
+bind : mod + shift + q : close_window
+
+# Scratchpads
+scratchpad : mod + ctrl + Return : create 1
+scratchpad : mod + shift + b : toggle 2
+scratchpad : mod + alt + b : remove 2
+
+# Switch workspace
+workspace : mod + 3 : move 3
+# Move window to workspace
+workspace : mod + shift + 5 : swap 5
+.EE
+
+.SH DEFAULT KEYBINDINGS
+In
+.I default_sxwmrc
+file.
diff --git a/docs/sxwm.desktop b/docs/sxwm.desktop
new file mode 100644
index 0000000..ef08338
--- /dev/null
+++ b/docs/sxwm.desktop
@@ -0,0 +1,6 @@
+[Desktop Entry]
+Name=sxwm
+Comment=Simple Xorg Window Manager
+Exec=sxwm
+TryExec=sxwm
+Type=Application
diff --git a/docs/sxwm.md b/docs/sxwm.md
new file mode 100644
index 0000000..9b844d6
--- /dev/null
+++ b/docs/sxwm.md
@@ -0,0 +1,133 @@
+## Launch Arguments
+
+### `-v` or `--version`
+Displays the current version of `sxwm`
+
+
+## Configuration
+
+`sxwm` is configured via a simple text file located at `~/.config/sxwmrc`. Changes can be applied instantly by reloading the configuration (`MOD + r`).
+
+The file uses a `key : value` format. Lines starting with `#` are ignored.
+
+### General Options
+
+| Option                   | Type    | Default   | Description                                                                 |
+|--------------------------|---------|-----------|-----------------------------------------------------------------------------|
+| `mod_key`                | String  | `super`   | Sets the primary modifier key (`alt`, `super`, `ctrl`).                     |
+| `gaps`                   | Integer | `10`      | Pixels between windows and screen edges.                                    |
+| `border_width`           | Integer | `1`       | Thickness of window borders in pixels.                                      |
+| `focused_border_colour`  | Hex     | `#c0cbff` | Border color for the currently focused window.                              |
+| `unfocused_border_colour`| Hex     | `#555555` | Border color for unfocused windows.                                         |
+| `swap_border_colour`     | Hex     | `#fff4c0` | Border color when selecting a window to swap (`MOD+Shift+Drag`).            |
+| `master_width`           | Integer | `60`      | Percentage of the screen width for the master window.                       |
+| `motion_throttle`        | Integer | `60`      | Target FPS for mouse drag actions.                                          |
+| `resize_master_amount`   | Integer | `1`       | Percent to increase/decrease master width.                                  |
+| `resize_stack_amount`    | Integer | `20`      | How many pixels to increase/decrease stack windows by.                      |
+| `snap_distance`          | Integer | `5`       | Distance (px) before a floating window snaps to edge.                       |
+| `move_window_amount`     | Integer | `10`      | Number of pixels to move the window with keyboard.                          |
+| `resize_window_amount`   | Integer | `10`      | Number of pixels to resize the window with keyboard.                        |
+| `start_fullscreen`       | String  | `"st"`    | Starts specified windows that should start fullscreened. Enclosed in quotes and comma-seperated.|
+| `new_win_focus`          | Bool    | `true`    | Whether openening new windows should also set focus to them or keep on current window.|
+| `warp_cursor`            | Bool    | `true`    | Warp the cursor to the middle of newly focused windows.                     |
+| `floating_on_top`        | Bool    | `true`    | Whether floating windows should always draw over tiled ones                 |
+| `floating_on_top`        | Bool    | `true`    | Whether floating windows should always draw over tiled ones                 |
+| `new_win_master`         | Bool    | `false`   | New windows will open as master window.                                              |
+| `should_float`           | String  | `"st"`    | Always-float rule. Multiple entries should be comma-seperated. Optionally, entries can be enclosed in quotes.|
+| `exec`                   | String  | `Nothing` | Command to run on startup (e.g., `sxbar`, `picom`, "autostart", etc.).      |
+| `can_swallow`            | String  | `st`      | Windows that can swallow.                                                   |
+| `can_be_swallowed`       | String  | `mpv`     | Windows that can be swallowed.                                              |
+
+---
+
+## Keybindings
+
+### Syntax
+
+- **Modifiers**: `mod`, `shift`, `ctrl`, `alt`, `super` ...
+- **Key**: Case-insensitive keysym (e.g., `Return`, `q`, `1`)
+> To find the key do `xev | grep "keysym"` and press the key in the box.
+- **Action**: Either an external command (in quotes) or internal function.
+- **move**: Move to that worspace
+- **swap**: Swap window to that workspace
+- **_n_**: Workspace / Scratchpad number
+- **create**: Creates a scratchpad on that slot
+- **toggle**: toggles the visibility of that scratchpad
+- **remove**: Removes the scratchpad on that slot
+
+```sh
+bind : modifier + ... + key : action
+```
+
+```sh
+scratchpad : modifier + ... + key : create n
+scratchpad : modifier + ... + key : toggle n
+scratchpad : modifier + ... + key : remove n
+```
+
+```sh
+workspace : modifier + ... + key : move n
+workspace : modifier + ... + key : swap n
+```
+
+### Available Functions
+
+| Function Name        | Description                                                  |
+|----------------------|--------------------------------------------------------------|
+| `centre_window`      | Centre the focused window.                                   |
+| `close_window`       | Closes the focused window.                                   |
+| `decrease_gaps`      | Shrinks gaps.                                                |
+| `focus_next`         | Moves focus forward in the stack.                            |
+| `focus_prev`         | Moves focus backward in the stack.                           |
+| `focus_next_mon`     | Switches focus to the next monitor.                          |
+| `focus_prev_mon`     | Switches focus to the previous monitor.                      |
+| `fullscreen`         | Fullscreen the focused window.                               |
+| `global_floating`    | Toggles floating state for all windows.                      |
+| `increase_gaps`      | Expands gaps.                                                |
+| `master_next`        | Moves focused window down in master/stack order.             |
+| `master_prev`        | Moves focused window up in master/stack order.               |
+| `master_increase`    | Expands master width.                                        |
+| `master_decrease`    | Shrinks master width.                                        |
+| `move_next_mon`      | Moves the focused window to the next monitor.                |
+| `move_prev_mon`      | Moves the focused window to the previous monitor.            |
+| `move_win_up`        | Moves the focused window up (keyboard).                      |
+| `move_win_down`      | Moves the focused window down (keyboard).                    |
+| `move_win_left`      | Moves the focused window left (keyboard).                    |
+| `move_win_right`     | Moves the focused window right (keyboard).                   |
+| `quit`               | Exits `sxwm`.                                                |
+| `reload_config`      | Reloads config.                                              |
+| `resize_win_up`      | Resizes the focused window up (keyboard).                    |
+| `resize_win_down`    | Resizes the focused window down (keyboard).                  |
+| `resize_win_left`    | Resizes the focused window left (keyboard).                  |
+| `resize_win_right`   | Resizes the focused window right (keyboard).                 |
+| `stack_increase`     | Increase the height of the focused stack window.             |
+| `stack_decrease`     | Decrease the height of the focused stack window.             |
+| `switch_previous_workspace` | Switch to the previous workspace.                     |
+| `toggle_floating`    | Toggles floating state of current window.                    |
+
+### Example Bindings
+
+```yaml
+# Launch terminal
+bind : mod + Return : "st"
+# Close window
+bind : mod + shift + q : close_window
+
+# Scratchpads
+scratchpad : mod + ctrl + Return : create 1
+scratchpad : mod + shift + b : toggle 2
+scratchpad : mod + alt + b : remove 2
+
+# Switch workspace
+workspace : mod + 3 : move 3
+# Move window to workspace
+workspace : mod + shift + 5 : swap 5
+```
+
+---
+
+## Default Keybindings
+
+In `default_sxwmrc`
+
+---