diff --git a/doc/man/man3/index.txt b/doc/man/man3/index.txt new file mode 100644 index 000000000..3b7be1826 --- /dev/null +++ b/doc/man/man3/index.txt @@ -0,0 +1,9 @@ +notcurses(3) notcurses.3.ronn +notcurses_init(3) notcurses_init.3.ronn +notcurses_stdplane(3) notcurses_stdplane.3.ronn +notcurses_ncplane(3) notcurses_ncplane.3.ronn +notcurses_cell(3) notcurses_cell.3.ronn +notcurses_input(3) notcurses_input.3.ronn +notcurses_output(3) notcurses_output.3.ronn +notcurses_render(3) notcurses_render.3.ronn +notcurses_stop(3) notcurses_stop.3.ronn diff --git a/doc/man/man3/notcurses.3.ronn b/doc/man/man3/notcurses.3.ronn index ce6fa1365..a2a233c94 100644 --- a/doc/man/man3/notcurses.3.ronn +++ b/doc/man/man3/notcurses.3.ronn @@ -20,8 +20,8 @@ output of `pkg-config --libs notcurses` (see pkg-config(1)). 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` (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 +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 [Construction][]). ### Construction @@ -30,24 +30,24 @@ 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` locale. It is usually appropriate to use `setlocale(LC_ALL, "")`, relying on the user to properly set the `LANG` environment variable. notcurses will -refuse to start if `nl_langinfo(3)` doesn't indicate UTF-8. +refuse to start if nl_langinfo(3) doesn't indicate UTF-8. -`notcurses_init` accepts a `struct notcurses_options` allowing fine-grained +notcurses_init(3) accepts a `struct notcurses_options` allowing fine-grained 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. ### Output -All output is performed on `struct ncplane*`s (see `notcurses_ncplane(3)`). +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, +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 +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)`. +on drawing to ncplanes is available at notcurses_output(3). -Output is not visible until explicitly rendered via `notcurses_render(3)`. +Output is not visible until explicitly rendered via notcurses_render(3). ### Input @@ -55,16 +55,16 @@ 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)`. +[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 +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 -shell. By default, `notcurses_init` installs signal handlers to catch all +shell. By default, notcurses_init(3) installs signal handlers to catch all signals which would normally terminate the process. The new handlers will try -to call `notcurses_stop`, and then propagate the received signal to the +to call notcurses_stop(3), and then propagate the received signal to the previous action. ## AUTHORS diff --git a/doc/man/man3/notcurses_init.3.ronn b/doc/man/man3/notcurses_init.3.ronn index a5660810b..a8113df61 100644 --- a/doc/man/man3/notcurses_init.3.ronn +++ b/doc/man/man3/notcurses_init.3.ronn @@ -27,12 +27,12 @@ notcurses_option` passed as `opts` controls behavior. Only one instance should be associated with a given terminal at a time, though it is no problem to have multiple instances in a given process. On success, a pointer to a valid `struct notcurses` is returned. `NULL` is returned on failure. Before the process exits, -`notcurses_stop(3)` should be called to reset the terminal and free up +notcurses_stop(3) should be called to reset the terminal and free up resources. -An appropriate `terminfo(5)` entry must exist for the terminal. This entry is +An appropriate terminfo(5) entry must exist for the terminal. This entry is usually selected using the value of the `TERM` environment variable (see -`getenv(3)`), but a non-`NULL` value for `termtype` will override this. An +getenv(3)), but a non-`NULL` value for `termtype` will override this. An invalid terminfo specification can lead to reduced performance, reduced display capabilities, and/or display errors. notcurses natively targets 24bpp/8bpc RGB color, and it is thus desirable to use a terminal with the @@ -46,7 +46,7 @@ via a command-line option. notcurses furthermore hides the cursor by default, but `retain_cursor` can prevent this (the cursor can be dynamically enabled or disabled during -execution via `notcurses_cursor_enable(3)` and `notcurses_cursor_disable(3)`). +execution via notcurses_cursor_enable(3) and notcurses_cursor_disable(3)). If `clear_screen_start` is set to `true`, the screen will be cleared as part of `notcurses_init`. Otherwise, whatever's on the screen at entry will remain @@ -55,18 +55,18 @@ there until changed. `notcurses_init` typically emits some diagnostics at startup, including version information and some details of the configured terminal. This can be inhibited with `suppress_banner`. This will also inhibit the performance summary normally -printed by `notcurses_stop`. +printed by notcurses_stop(3). ### Fatal signals It is important to reset the terminal before exiting, whether terminating due to intended operation or a received signal. This is usually accomplished by -explicitly calling `notcurses_stop` during shutdown. For convenience, notcurses +explicitly calling notcurses_stop(3) during shutdown. For convenience, notcurses by default installs signal handlers for various signals typically resulting in process termination (see `signal(7)`). These signal handlers call -`notcurses_stop` for each `struct notcurses` in the process, and then propagate +notcurses_stop(3) for each `struct notcurses` in the process, and then propagate the signal to any previously-configured handler. These handlers are disabled -upon entry to `notcurses_stop`. +upon entry to notcurses_stop(3). To prevent signal handler registration, set `no_quit_sighandlers` to `true`. No means is provided to selectively register fatal signal handlers. If this is @@ -77,17 +77,17 @@ done, the caller ought be sure to effect similar functionality themselves. `SIGWINCH` (SIGnal WINdow CHange) is delivered to the process when the terminal is resized. The default action is to ignore it (`SIG_IGN`). notcurses installs a handler for this signal. The handler causes notcurses to update its idea of -the terminal's size using `TIOCGWINSZ` (see `ioctl_tty(2)`), and generates an -`NCKEY_RESIZE` input event (see `notcurses_input(3)`. This signal handler can be +the terminal's size using `TIOCGWINSZ` (see ioctl_tty(2)), and generates an +`NCKEY_RESIZE` input event (see notcurses_input(3). This signal handler can be inhibited by setting `no_winch_sighandler` to `true`. If this is done, the caller should probably watch for the signal, and invoke `notcurses_resize()` upon its receipt. A resize event does not invalidate any references returned earlier by notcurses. The content of any new screen area is undefined until the next call -to `notcurses_render(3)`, unless `clear_screen_start` is set `true`, in which +to notcurses_render(3), unless `clear_screen_start` is set `true`, in which case new area is cleared. This is true even if an existing `struct ncplane` -(see `notcurses_ncplane(3)`) overlaps the new area, since the signal could +(see notcurses_ncplane(3)) overlaps the new area, since the signal could arrive while the ncplanes are being modified. Signal handlers are quite restricted as to what actions they can perform, so minimal work is perfomed in the handler proper. @@ -99,15 +99,15 @@ Thus, in the absence of `no_winch_sighandler`, `SIGWINCH` results in: * queuing of a `NCKEY_RESIZE` input event (if there is space in the queue) * blanking of the new screen area (if `clear_screen_start` is set) -Upon the next call to `notcurses_render` or `notcurses_resize`, the standard -plane (see `notcurses_stdplane(3)`) will be resized to the new screen size. The -next `notcurses_render` call will function as expected across the new screen +Upon the next call to notcurses_render(3) or notcurses_resize(3), the standard +plane (see notcurses_stdplane(3)) will be resized to the new screen size. The +next notcurses_render(3) call will function as expected across the new screen geometry. ## RETURN VALUES `NULL` is returned on failure. Otherwise, the return value points at a valid -`struct notcurses`, which can be used until it is provided to `notcurses_stop`. +`struct notcurses`, which can be used until it is provided to notcurses_stop(3). ## AUTHORS diff --git a/doc/man/man3/notcurses_stop.3.ronn b/doc/man/man3/notcurses_stop.3.ronn index 4aa415589..1c183617f 100644 --- a/doc/man/man3/notcurses_stop.3.ronn +++ b/doc/man/man3/notcurses_stop.3.ronn @@ -11,8 +11,8 @@ notcurses_stop(3) -- free up notcurses and restore the console `notcurses_stop` frees up any resources associated with the `struct notcurses*` provided as `nc`, and attempts to restore the terminal to its state prior to -calling `notcurses_init(3)`. It also unregisters any signal handlers put into -place by `notcurses_init`. `nc` must not be used following the call. +calling notcurses_init(3). It also unregisters any signal handlers put into +place by notcurses_init(3). `nc` must not be used following the call. ## RETURN VALUES