Author: Drew DeVault <email@example.com>
Date: Thu, 25 Apr 2019 15:21:19 -0400
|A||README.md|| | ||97||+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++|
1 file changed, 97 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,97 @@
+Wio is a Wayland compositor for Linux & FreeBSD which has a similar look & feel
+to plan9's rio.
+This software is incomplete. Notably missing is a Rio-esque FUSE filesystem.
+## Basic principles
+Wio uses [wlroots](https://github.com/swaywm/wlroots) to run a simple Wayland
+compositor. Right clicking (and holding) outside of a window will bring up the
+menu. Drag the mouse to the command you'd like to execute and release the mouse.
+- **New**: Opens a new window. Click and hold the mouse, then drag, to define
+ the placement for the new window.
+- **Resize**: Resizes a window. Click the window to resize, then click and drag
+ somewhere else to define the new placement.
+- **Move**: Moves a window. Click and drag a window to move it.
+- **Delete**: Deletes a window. Click the window you want to close.
+- **Hide**: Hides a window. Open the menu again to show the window.
+Each window runs [cage](https://github.com/Hjdskes/cage) by default, and
+instructs cage to run a terminal emulator
+([alacritty](https://github.com/jwilm/alacritty) by default). This effectively
+gives each window its own private Wayland compositor. If you want to run a
+graphical application, simply run the command from the terminal and cage will
+display it full-screen within its own window.
+To access Wio's own Wayland compositor directly (for example, to take
+screenshots with [grim](https://wayland.emersion.fr/grim)), set
+`WAYLAND_DISPLAY=wayland-0` or similar. Note, however, that the only shell for
+application windows which is supported directly by Wio is xdg-shell.
+Some minor customization options are available by passing command line arguments
+ wio [-c <cage>] [-t <terminal>] [-o <output config>...]
+- **-c <cage>**: specifies the `cage` command to run new windows in
+- **-t <term>**: specifies the terminal command to run new windows in
+For the authentic rio experience, try the alacritty config in `contrib/`.
+### Output configuration
+Wio supports multihead configurations and HiDPI displays. In order to take
+advantage of this, you must pass some output configurations on the command line.
+You can specify the following options, in this order:
+- Output name (`weston-info` can list output names & modes)
+- X & Y coordinates in the multihead layout
+- Width & height of the desired mode
+- Scale factor
+Each property should be separated by a colon. Use -1 for X & Y to have Wio
+automatically place the display, and 0 to have Wio select a mode or scale factor
+automatically. You may omit any of these properties, but must include any
+property which comes before the ones you're trying to set.
+For example, to specify the X & Y coordinates of output `HDMI-A-1`, try the
+following: `-o HDMI-A-1:1920:0`. If you also want to set its mode to 720p, use
+`-o HDMI-A-1:1920:0:1280:720`. If you don't care about setting the mode but want
+to flip it, use `-o HDMI-A-1:-1:-1:0:0:0:flipped`.
+Available transforms are:
+Wio recognizes the following environment variables for basic keyboard
+Read `xkeyboard-config(7)` for details.
+## Patches, bugs, etc
+Patches, questions, feedback, and general discussions to the mailing list:
+Tickets on the [bug tracker](https://todo.sr.ht/~sircmpwn/wio).