update README

it's time

README.md

@@ -1,50 +1,99 @@
-# dwl
+# dwl - dwm for Wayland
 
-This is the "minimum viable product" Wayland compositor based on wlroots. It
+dwl is a compact, hackable compositor for Wayland based on
-aims to implement a Wayland compositor in the fewest lines of code possible,
+[wlroots](https://github.com/swaywm/wlroots).  It is intended to fill the same
-while still supporting a reasonable set of features. Reading this code is the
+space in the Wayland world that dwm does in X11, primarily in terms of
-best starting point for anyone looking to build their own Wayland compositor
+philosophy, and secondarily in terms of functionality.  Like dwm, dwl is:
-based on wlroots.
+
+- Easy to understand, hack on, and extend with patches
+- One C source file (or a very small number) configurable via `config.h`
+- Limited to a maximum number of SLOC (to be determined)
+- Tied to as few external dependencies as possible
+
+
+dwl is not meant to provide every feature under the sun.  Instead, like dwm, it
+sticks to features which are necessary, simple, and straightforward to
+implement given the base on which it is built.  Since wlroots provides a number
+of features that are more complicated to accomplish with Xlib and select
+extensions, dwl can be in some ways more featureful than dwm *while remaining
+just as simple.*  Intended default features are:
+
+- Any features provided by dwm/Xlib: simple window borders, tags, keybindings,
+  client rules, mouse move/resize (see below for why the built-in status bar is
+  a possible exception)
+- Configurable multi-monitor layout support, including position and rotation
+- Configurable HiDPI/multi-DPI support
+- Wayland protocols needed for daily life in the tiling world: at a minimum,
+  xdg-shell and layer-shell (for bars/menus).  Protocols trivially provided by
+  wlroots may also be added.
+- Basic yes/no damage tracking to avoid needless redraws (if it can be done
+  simply and has an impact on power consumption)
+
+
+Other features under consideration are:
+
+- Additional Wayland compositor protocols which are trivially provided by
+  wlroots or can be conditionally included via `config.h` settings: xwayland,
+  xdg-portal, etc.
+- External bar support instead of a built-in status bar, to avoid taking a
+  dependency on FreeType or Pango
+- More in-depth damage region tracking
 
 
 ## Building dwl
 
-dwl is disconnected from the main wlroots build system, in order to make it
+dwl has only two dependencies: wlroots and wayland-protocols.  Simply install
-easier to understand the build requirements for your own Wayland compositors.
+these and run `make`.
-Simply install the dependencies:
 
-- wlroots
-- wayland-protocols
 
-And run `make`.
+## Configuration
+
+All configuration is done by editing `config.h` and recompiling, in the same
+manner as dwm.  There is no way to separately restart the window manager in
+Wayland without restarting the entire display server, so any changes will take
+effect the next time dwl is executed.
 
 
 ## Running dwl
 
-You can run dwl with `./dwl`. In an existing Wayland or X11 session,
+dwl can be run as-is, with no arguments. In an existing Wayland or X11 session,
-dwl will open a Wayland or X11 window respectively to act as a virtual
+this will open a window to act as a virtual display.  When run from a TTY, the
-display. You can then open Wayland windows by setting `WAYLAND_DISPLAY` to the
+Wayland server will take over the entire virtual terminal.  Clients started by
-value shown in the logs. You can also run `./dwl` from a TTY.
+dwl will have `WAYLAND_DISPLAY` set in their environment, and other clients can be
+started from outside the session by setting this variable accordingly.
 
-In either case, you will likely want to specify `-s [cmd]` to run a command at
+You can also specify a startup program using the `-s` option.  The argument to
-startup, such as a terminal emulator. This will be necessary to start any new
+this option will be run at startup as a shell command (using `sh -c`) and can
-programs from within the compositor, as dwl does not support any custom
+serve a similar function to `.xinitrc`: starting a service manager or other
-keybindings. dwl supports the following keybindings:
+startup applications.  Unlike `.xinitrc`, the display server will not shut down
-
+when this process terminates.  Instead, as dwl is shutting down, it will send
-- `Alt+Escape`: Terminate the compositor
+this process a SIGTERM and wait for it to terminate (if it hasn't already).
-- `Alt+F1`: Cycle between windows
+This make it ideal not only for initialization but also for execing into a
+user-level service manager like s6 or `systemd --user`.
 
 
-## Limitations
+## Known limitations and issues
 
-Notable omissions from dwl:
+dwl is a work in progress, and it has not yet reached its feature goals in a
+number of ways:
 
-- HiDPI support
+- Urgent/attention/focus-request not yet implemented
-- Any kind of configuration, e.g. output layout
+- Borders and selected/normal/urgent colors not implemented
-- Any protocol other than xdg-shell (e.g. layer-shell, for
+- No support for layer-shell yet
-  panels/taskbars/etc; or Xwayland, for proxied X11 windows)
+- HiDPI works, but multi-DPI is not as nice as sway, depending on the scale
-- Optional protocols, e.g. screen capture, primary selection, virtual
+  factors involved.  Perhaps scaling filters are needed?
-  keyboard, etc. Most of these are plug-and-play with wlroots, but they're
+- Monitor rotation/transform is not working yet
-  omitted for brevity.
+- Mouse resize is not precise
-- Damage tracking, which tracks which parts of the screen are changing and
+- No statusbar
-  minimizes redraws accordingly.
+- No damage tracking
+- No handling of fullscreen/fixed windows (or whatever the Wayland analogues
+  are)
+
+
+## Acknowledgements
+
+dwl began by extending the TinyWL example provided (CC0) by the sway/wlroots
+developers.  This was made possible in many cases by looking at how sway
+accomplished something, then trying to do the same in as suckless a way as
+possible.  Speaking of which, many thanks to suckless.org and the dwm
+developers and community for the inspiration.