From 2dffc5ae1e544247100e79ecf1826d0641ba7349 Mon Sep 17 00:00:00 2001
From: nick black <dankamongmen@gmail.com>
Date: Thu, 21 Nov 2019 09:06:36 -0500
Subject: [PATCH] document basic use

---
 README.md           | 49 +++++++++++++++++++++++++++++++++++++++++++++
 include/notcurses.h |  7 ++-----
 2 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 1f4ff6bf6..918f456c1 100644
--- a/README.md
+++ b/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.
diff --git a/include/notcurses.h b/include/notcurses.h
index 39af2c651..0d1543f0d 100644
--- a/include/notcurses.h
+++ b/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.