Updated documentation.

README.md

@@ -1,8 +1,47 @@
 # BTUI - Bruce's Text User Interface Library
 
 BTUI is a minimal, embeddable single header file alternative to bloatware like
-ncurses. BTUI aims to be under 1/1,000th the size of ncurses, while also
-providing a more usable and modern API.
+ncurses. BTUI aims to be less than 1% the size of
+ncurses,<sup>1(#footnote1)</sup> while also providing a better API for the
+programmer who is not afraid to roll up their sleeves and manage their own
+state. If you want a drop-in TUI library that lets you switch into TUI mode,
+write some strings to the screen with 24-bit color, and get user keypresses,
+then this is the library for you!
+
+<a name="footnote1">1</a>: Currently, BTUI is somewhere between 0.5% and 0.1%
+the size of ncurses, but even *counting the number of lines of code in ncurses*
+is hard.
+
+## Cleanup by Default
+
+Once BTUI is enabled, you can manually disable TUI Mode (e.g. if you want to
+temporarily drop back to the regular shell). However, BTUI will always
+automatically put the terminal back in a normal state when your program exits,
+even in the event of a segfault or other blockable signal. BTUI can't do
+anything about unblockable signals like SIGKILL though, so don't use `killall
+-9 myprog` unless you want a gunked up terminal, just use `kill myprog`
+instead. If your terminal *does* get gunked up, you can always run the `reset`
+shell command to reset it.
+
+## Easy 24-bit Colors
+
+BTUI supports 24-bit colors. It's dead easy, just `btui_set_fg(bt, r, g, b)`
+(foreground color) or `btui_set_bg(bt, r, g, b)` (background color). Try `make
+rainbow` to see a demo of 24-bit colors in action. This has been supported by
+most terminals for aeons, but most TUI applications still default to using the
+same 8 colors. It doesn't have to be that way! (Although you can still use
+those colors with `btui_set_attributes(bt, BTUI_BG_RED | BTUI_FG_BLACK)` and so
+forth.)
+
+## User Input
+
+BTUI lets you get keyboard input for all keypress events handled by your
+terminal, including mouse clicking and dragging. Warning: BTUI also hooks in to
+`Ctrl-c`, `Ctrl-d`, `Ctrl-z`, and other keyboard events that normally have very
+specific behavior in terminal programs. If you want that specific behavior,
+then you'll have to implement it manually. The upside is that you're able to
+handle it gracefully and do whatever cleanup you want. If you want to provide
+`Ctrl-z` suspend functionality, you can use `btui_suspend(bt)`.
 
 ## Language Bindings
 
@@ -20,8 +59,8 @@ constants, including terminal escape values and keycodes.
     char *btui_keyname(int key, char *buf);
     int btui_keynamed(const char *name);
     int btui_set_attributes(btui_t *bt, attr_t attrs);
-    int btui_set_fg_rgb(btui_t *bt, unsigned char r, unsigned char g, unsigned char b);
-    int btui_set_bg_rgb(btui_t *bt, unsigned char r, unsigned char g, unsigned char b);
+    int btui_set_fg(btui_t *bt, unsigned char r, unsigned char g, unsigned char b);
+    int btui_set_bg(btui_t *bt, unsigned char r, unsigned char g, unsigned char b);
     int btui_set_fg_hex(btui_t *bt, int hex);
     int btui_set_bg_hex(btui_t *bt, int hex);
     #define btui_printf(bt, ...) fprintf((bt)->out, __VA_ARGS__)
@@ -33,6 +72,7 @@ constants, including terminal escape values and keycodes.
     #define btui_clear_right(bt) fputs("\033[K", (bt)->out)
     #define btui_clear_left(bt) fputs("\033[1K", (bt)->out)
     #define btui_clear_line(bt) fputs("\033[2K", (bt)->out)
+    #define btui_suspend(bt) kill(getpid(), SIGTSTP)
 
 See [C/test.c](C/test.c) for example usage.
 
@@ -44,6 +84,7 @@ be propagated out of the function, but the terminal will be cleaned up nicely
 before the error is printed. Here's a simple example program:
 
     require("btui")(function(bt)
+        -- Run this code within the TUI, using "bt" as the TUI object
         ...
     end)
 
@@ -55,11 +96,13 @@ before the error is printed. Here's a simple example program:
     bt:clear(type="screen") -- Clear the terminal. Options are: "screen", "right", "left", "above", "below", "line"
     bt:flush() -- Flush the terminal output. Most operations do this anyways.
     bt:move(x, y) -- Move the cursor to the given position. (0,0) is the top left corner.
+    -- R,G,B values are in the range [0.0, 1.0]:
     bt:withfg(r,g,b, fn) -- Set the foreground color to (r,g,b), call fn, then reset the foreground color to default
     bt:withbg(r,g,b, fn) -- Set the background color to (r,g,b), call fn, then reset the background color to default
     bt:withattributes(attrs..., fn) -- Set the given attributes, call fn, then unset them
     bt:setattributes(attrs...) -- Set the given attributes
     bt:unsetattributes(attrs...) -- Unset the given attributes
+    bt:suspend() -- Suspend the current process and drop back into normal terminal mode
     bt:width() -- Return the scren width
     bt:height() -- Return the screen height
 
@@ -68,3 +111,38 @@ See [Lua/test.lua](Lua/test.lua) for example usage.
 ### Python API
 
 Coming soon.
+
+## FAQ
+
+### Why not use ncurses? It's already installed almost everywhere!
+
+[Ncurses](https://invisible-island.net/ncurses/) is pretty ubiquitous among
+amateur TUI developers, however it's a really messy paradigm to work with, and
+it comes with hundreds of thousands of lines of code bloat. There's also tons
+of compatibility problems across different versions of ncurses. Using ncurses
+is a headache, and writing a wrapper around ncurses just adds more bloat on top
+of a mountain of bloat. So, if you want to write a really nice TUI library for
+your language of choice, BTUI is a good option for a foundation to build off
+of. BTUI handles all the low-level C stuff like setting terminal attributes and
+interrupt handlers, but after that, it mostly just gets out of the way and lets
+you write the bytes you want, with just a few helper functions that make
+writing the right bytes easy.
+
+### Why not use termbox?
+
+[Termbox](https://github.com/nsf/termbox) is an okay library, but its API is
+built around modifying terminal cells one-at-a-time using function calls. This
+approach has two major flaws: it's very bad for performance and it makes the
+API very awkward to use if you want to write strings to the screen. Termbox
+uses its own custom internal write-buffering to reduce write calls and help
+performance, but in my experience, there is still noticeable lag when doing
+large amounts of writes compared to just using plain ol' C `fprintf()`
+buffering.
+
+Also, termbox is intended to be used as a system-installed library, but BTUI is
+much simpler to use: just drop the .h file into your project and `#import
+"btui.h"`!
+
+## License
+
+BTUI is released under the MIT license. See [LICENSE](LICENSE) for details.