document basic use

README.md

@@ -43,3 +43,52 @@ Why use this non-standard library?
 On the other hand, if you're targeting industrial or critical applications,
 or wish to benefit from the time-tested reliability and portability of Curses,
 you should by all means use that fine library.
+
+## Basic use
+
+A program wishing to use notcurses will need to link it, ideally using the
+output of `pkg-config --libs notcurses`. It is advised to compile with the
+output of `pkg-config --cflags notcurses`. If using CMake, a support file is
+provided, and can be accessed as `notcurses`.
+
+Before calling into notcurses—and usually as one of the first calls of the
+program—be sure to call `setlocale(3)` with an appropriate UTF-8 `LC_ALL`
+locale. It is usually appropriate to pass `NULL` to `setlocale()`, relying on
+the user to properly set the `LANG` environment variable.
+
+notcurses requires an available `terminfo(5)` definition appropriate for the
+terminal. It is usually appropriate to pass `NULL` in the `termtype` field of a
+`notcurses_options` struct, relying on the user to properly set the `TERM`
+environment variable. This variable is usually set by the terminal itself. It
+might be necessary to manually select a higher-quality definition for your
+terminal, i.e. `xterm-direct` as opposed to `xterm` or `xterm-256color`.
+
+Each terminal can be prepared via a call to `notcurses_init()`, which is
+supplied a struct of type `notcurses_options`:
+
+```c
+// Configuration for notcurses_init().
+typedef struct notcurses_options {
+  // The name of the terminfo database entry describing this terminal. If NULL,
+  // the environment variable TERM is used. Failure to open the terminal
+  // definition will result in failure to initialize notcurses.
+  const char* termtype;
+  // A file descriptor for this terminal on which we will generate output.
+  // Must be a valid file descriptor attached to a terminal, or notcurses will
+  // refuse to start. You'll usually want STDOUT_FILENO.
+  int outfd;
+  // If smcup/rmcup capabilities are indicated, notcurses defaults to making
+  // use of the "alternate screen." This flag inhibits use of smcup/rmcup.
+  bool inhibit_alternate_screen;
+} notcurses_options;
+
+// Initialize a notcurses context, corresponding to a connected terminal.
+// Returns NULL on error, including any failure to initialize terminfo.
+struct notcurses* notcurses_init(const notcurses_options* opts);
+
+// Destroy a notcurses context.
+int notcurses_stop(struct notcurses* nc);
+```
+
+`notcurses_stop` should be called before exiting your program to restore the
+terminal settings and free resources.

include/notcurses.h

@@ -27,11 +27,8 @@ typedef struct notcurses_options {
   bool inhibit_alternate_screen;
 } notcurses_options;
 
-// Initialize a notcurses context. While a program can have more than one
-// context, it usually doesn't make much sense, as they're all dealing with
-// the same screen(s). Returns NULL on error, including any failure to
-// initialize the terminfo library. If termtype is NULL, the environment
-// variable TERM is used.
+// Initialize a notcurses context, corresponding to a connected terminal.
+// Returns NULL on error, including any failure to initialize terminfo.
 struct notcurses* notcurses_init(const notcurses_options* opts);
 
 // Destroy a notcurses context.