man page work (#213)

doc/man/man3/notcurses.3.ronn

@@ -22,9 +22,9 @@ support file is provided, and can be accessed as `notcurses` (see cmake(1)).
 
 `notcurses_init(3)` can then be used to initialize a notcurses instance for a
 given `FILE*` (usually `stdout`), after calling `setlocale(3)` to prepare a
-UTF-8 locale (see [Initialization][]).
+UTF-8 locale (see [Construction][]).
 
-### Initialization
+### Construction
 
 Before calling into notcurses—and usually as one of the first calls of the
 program—be sure to call `setlocale` with an appropriate UTF-8 `LC_ALL`
@@ -37,7 +37,28 @@ control of notcurses behavior, including signal handlers, alternative screens,
 and overriding the TERM environment variable. A `terminfo` entry appropriate
 for the actual terminal must be available.
 
-### Shutdown
+### Output
+
+All output is performed on `struct ncplane*`s (see `notcurses_ncplane(3)`).
+Following initialization, a single ncplane exists, the "standard plane" (see
+`notcurses_stdplane(3)`. This plane cannot be destoyed nor manually resized,
+and is always exactly as large as the screen. Further ncplanes can be created
+with `notcurses_newplane(3)`. A total z-ordering always exists on the set of
+ncplanes, and new ncplanes are placed at the top of the z-buffer. Information
+on drawing to ncplanes is available at `notcurses_output(3)`.
+
+Output is not visible until explicitly rendered via `notcurses_render(3)`.
+
+### Input
+
+notcurses supports input from keyboards (via `stdin`) and pointing devices (via
+a broker such as GPM, X, or Wayland). Input is delivered as 32-bit Unicode
+code points. Synthesized events such as mouse button presses and arrow keys
+are mapped into Unicode's
+(Supplementary Private Use Area-B)[https://unicode.org/charts/PDF/U100000.pdf].
+Information on input is available at `notcurses_input(3)`.
+
+### Destruction
 
 Before exiting, `notcurses_stop(3)` should be called. In addition to freeing up
 resources, this is necessary to restore the terminal to a state useful for the
@@ -52,4 +73,6 @@ Nick Black <nickblack@linux.com>
 
 ## SEE ALSO
 
-notcurses-demo(1), notcurses_init(3), notcurses_stop(3), ncurses(3NCURSES), terminfo(5)
+notcurses-demo(1), notcurses_init(3), notcurses_input(3),
+notcurses_newplane(3), notcurses_output(3), notcurses_render(3),
+notcurses_stdplane(3), notcurses_stop(3), ncurses(3NCURSES), terminfo(5)

doc/man/man3/notcurses_ncplane.3.ronn

@@ -0,0 +1,39 @@
+notcurses_ncplane(3) -- operations on notcurses planes
+======================================================
+
+## SYNOPSIS
+
+`#include <notcurses.h>`
+
+`int ncplane_resize(struct ncplane* n, int keepy, int keepx, int keepleny, int keeplenx, int yoff, int xoff, int ylen, int xlen);`
+`int ncplane_move_yx(struct ncplane* n, int y, int x);`
+`void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x);`
+`int ncplane_set_default(struct ncplane* ncp, const cell* c);`
+`int ncplane_default(struct ncplane* ncp, cell* c);`
+`int ncplane_destroy(struct ncplane* ncp);`
+`int ncplane_move_top(struct ncplane* n);`
+`int ncplane_move_bottom(struct ncplane* n);`
+`int ncplane_move_above(struct ncplane* n, struct ncplane* above);`
+`int ncplane_move_below(struct ncplane* n, struct ncplane* below);`
+`struct ncplane* ncplane_below(struct ncplane* n);`
+`int ncplane_at_cursor(struct ncplane* n, cell* c);`
+`int ncplane_at_yx(struct ncplane* n, int y, int x, cell* c);`
+`void* ncplane_set_userptr(struct ncplane* n, void* opaque);`
+`void* ncplane_userptr(struct ncplane* n);`
+`const void* ncplane_userptr_const(const struct ncplane* n);`
+`void ncplane_dim_yx(const struct ncplane* n, int* restrict rows, int* restrict cols);`
+`int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);`
+`void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int* restrict x);`
+
+## DESCRIPTION
+
+
+## RETURN VALUES
+
+## AUTHORS
+
+Nick Black <nickblack@linux.com>
+
+## SEE ALSO
+
+notcurses_newplane(3), notcurses_stdplane(3)

doc/man/man3/notcurses_stdplane.3.ronn

@@ -0,0 +1,36 @@
+notcurses_stdplane(3) -- acquire the standard ncplane
+=====================================================
+
+## SYNOPSIS
+
+`#include <notcurses.h>`
+
+`struct ncplane*
+notcurses_stdplane(struct notcurses* nc);`
+
+`const struct ncplane*
+notcurses_const_stdplane(const struct notcurses* nc);`
+
+## DESCRIPTION
+
+`notcurses_stdplane` returns a handle to the standard ncplane for the context
+`nc. The standard plane always exists, and is always the same size as the
+screen. It is an error to call `ncplane_destroy(3)`, `ncplane_resize(3)`, or
+`ncplane_move(3)` on the standard plane, though it can be freely moved along
+the z-axis.
+
+A resize event does not invalidate this reference; it can be used until
+`notcurses_stop(3)` is called on `nc`.
+
+## RETURN VALUES
+
+These functions cannot fail when provided a valid `struct notcurses*`. They
+will always return a valid pointer to the standard plane.
+
+## AUTHORS
+
+Nick Black <nickblack@linux.com>
+
+## SEE ALSO
+
+notcurses_ncplane(3), notcurses_stop(3)