From a0d00c8aa31d1179ea92b1251bc5ec4cdcc5db29 Mon Sep 17 00:00:00 2001 From: nick black Date: Sat, 28 Dec 2019 20:57:10 -0500 Subject: [PATCH] man page work (#213) --- doc/man/man3/notcurses.3.ronn | 31 +++++++++++++++++--- doc/man/man3/notcurses_ncplane.3.ronn | 39 ++++++++++++++++++++++++++ doc/man/man3/notcurses_stdplane.3.ronn | 36 ++++++++++++++++++++++++ 3 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 doc/man/man3/notcurses_ncplane.3.ronn create mode 100644 doc/man/man3/notcurses_stdplane.3.ronn diff --git a/doc/man/man3/notcurses.3.ronn b/doc/man/man3/notcurses.3.ronn index 39a61c561..ce6fa1365 100644 --- a/doc/man/man3/notcurses.3.ronn +++ b/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 ## 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) diff --git a/doc/man/man3/notcurses_ncplane.3.ronn b/doc/man/man3/notcurses_ncplane.3.ronn new file mode 100644 index 000000000..312a31873 --- /dev/null +++ b/doc/man/man3/notcurses_ncplane.3.ronn @@ -0,0 +1,39 @@ +notcurses_ncplane(3) -- operations on notcurses planes +====================================================== + +## SYNOPSIS + +`#include ` + +`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 + +## SEE ALSO + +notcurses_newplane(3), notcurses_stdplane(3) diff --git a/doc/man/man3/notcurses_stdplane.3.ronn b/doc/man/man3/notcurses_stdplane.3.ronn new file mode 100644 index 000000000..511e48c8b --- /dev/null +++ b/doc/man/man3/notcurses_stdplane.3.ronn @@ -0,0 +1,36 @@ +notcurses_stdplane(3) -- acquire the standard ncplane +===================================================== + +## SYNOPSIS + +`#include ` + +`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 + +## SEE ALSO + +notcurses_ncplane(3), notcurses_stop(3)