From 6b7b987940cdd6e28991957cec56571673b425ab Mon Sep 17 00:00:00 2001
From: Lorenzo Cogotti <lcg@doublefourteen.io>
Date: Wed, 17 Aug 2022 13:35:30 +0200
Subject: [PATCH] [README] Improve project description and usage docs.

---
 README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 03c83e2..ddf2ba1 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,106 @@
 Yui - A Declarative UI library for LÖVE
 =======================================
 
-**Yui** - Yet another User Interface, is an attempt to ease the process of assembling trivial menu-like GUIs for your game using [LÖVE](https://love2d.org).
+**Yui** - Yet another User Interface, is a library to create menu-like GUIs
+for games using the [LÖVE](https://love2d.org) engine.
 
 ## Why is that?
 
 Because I'm spending so much time tweaking and customizing existing libraries,
 I might as well make my own.
 
+## Features
+
+**Yui** fills the following gaps:
+
+* Immediate mode UIs tend to clutter LÖVE `update()` code a lot, using a declarative approach - that is:
+  describing how the UI should look upfront, and then letting the UI code `update()` and `draw()` itself accordingly,
+  makes for a cleaner code.
+* Adapt to different sources of input easily (keyboard, mouse, touch, gamepad).
+* Out of the box internationalization.
+* Out of the box keyboard navigation across widgets.
+* Simple layouts (place widget in columns or rows, or possibly build rows made of several columns - grids).
+* Custom widgets support.
+* Custom theme support.
+* Custom input sources support.
+* Sufficiently compact, straightforward and hackable code.
+
+**Yui** does have some downsides:
+
+* The declarative approach makes UIs harder to change drastically from frame to frame.
+  * **Yui** tries to ameliorate this, allowing widgets property tweening, it's still less powerful
+    compared to an all out immediate UI approach.
+* Features come with a price, **Yui**'s code tries to be small and simple, but there are definitely smaller
+  (and less featureful) frameworks out there.
+
 ## Dependencies
 
 **Yui** depends on:
 
 * [gear](https://git.doublefourteen.io/lua/gear) for general algorithms.
 * [moonspeak](https://git.doublefourteen.io/lua/moonspeak) for its localization functionality.
+* ...and any of their dependencies.
+
+You may either download each of them manually and place them inside a `lib` subdirectory, or use
+[crush](https://git.doublefourteen.io/lua/crush) to do the work for you.
+
+1. Clone this repository.
+
+```sh
+git clone https://git.doublefourteen.io/lua/yui
+```
+
+2. Move to repository root directory:
+
+```sh
+cd yui
+```
+
+3. Resolve dependencies using **crush**.
+
+```sh
+lua crush.lua
+```
+
+You should now see a `lib` subdirectory containing the necessary dependencies.
+
+## Integrating yui in my project using crush
+
+1. Download the latest [crush.lua](https://git.doublefourteen.io/lua/crush/src/branch/master/crush.lua) file and
+   place it in your project's root directory.
+
+2. Create a `.lovedeps` text file in your project's root with the following dependency entry:
+
+```lua
+{
+    yui = "https://git.doublefourteen.io/lua/yui",
+
+    -- ...more dependencies, if necessary...
+}
+```
+
+3. **Yui** can now be downloaded directly by `crush` to the project's `lib` directory,
+   along with any other dependency:
+
+```sh
+lua crush.lua
+```
+
+4. You may now use `yui` in your project by `require()`-ing it.
+
+```lua
+local yui = require 'lib.yui'
+```
+
+5. Any project depending on yours may now fetch your project's dependencies (including `yui`)
+   automatically using `crush`, following the above procedure.
+
+## Documentation
+
+...Ouch.
+
+Documentation and examples are underway, however the source code is (IMHO) sufficiently
+straightforward and disciplined to have sufficient overview of the functionality.
 
 ## Acknowledgement
 
@@ -27,3 +114,11 @@ Widgets offered by **yui** are also inspired by **SUIT**.
 
 See [ACKNOWLEDGEMENT](README.ACKNOWLEDGEMENT) for full SUIT license
 information and copyright notice.
+
+## Similar projects
+
+* [SUIT](https://github.com/vrld/SUIT) an excellent, simple and flexible framework for immediate UIs.
+
+## License
+
+Zlib, see [LICENSE](LICENSE) for details.