blackbeard420/notcurses
1
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses synced 2025-03-09 09:09:03 -04:00
Code Issues Projects Releases Wiki Activity

Further reduction of our gigantic README

Browse Source 
Extract Curses differences and adaptation sections, and
move them to doc/CURSES.md. Reference this new document
in README.md. We now have sufficiently few sections that
we can dispense with the ToC. Do so.
This commit is contained in:
nick black 2021-02-06 13:45:27 -05:00
parent c784eb660d
commit 2cd8b9d82e
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
4 changed files with 92 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
README.md
View File

@ -44,19 +44,6 @@ most of the functionality of Notcurses.
<img src="https://repology.org/badge/vertical-allrepos/notcurses.svg" alt="Packaging status" align="right">
</a>
* [Introduction](#introduction)
* [Requirements](#requirements)
* [Building](#building)
* [Included tools](#included-tools)
* [Documentation](#documentation)
* [Differences from Curses](#differences-from-curses)
* [Adapting NCURSES programs](#adapting-ncurses-programs)
* [Environment notes](#environment-notes)
* [TrueColor detection](#TrueColor-detection)
* [Fonts](#fonts)
* [FAQs](#faqs)
* [Useful links](#useful-links)
## Introduction
Notcurses abandons the X/Open Curses API bundled as part of the Single UNIX
@ -144,92 +131,17 @@ necessary data files. It can be run by itself, or via `make test`.
## Documentation
With `-DUSE_PANDOC=on` (the default), a full set of man pages and XHTML
will be built from `doc/man`. The following Markdown documentation is included
directly:
* Per-release [News](NEWS.md) for packagers, developers, and users.
* The `TERM` environment variable and [various terminal emulators](TERMINALS.md).
* Notes on [contributing](doc/CONTRIBUTING.md) and [hacking](doc/HACKING.md).
* There's a semi-complete [reference guide](USAGE.md).
* A list of [other TUI libraries](doc/OTHERS.md).
* Abbreviated [history](doc/HISTORY.md) and thanks.
## Differences from Curses
The biggest difference, of course, is that Notcurses is not an implementation
of X/Open (aka XSI) Curses, nor part of SUS4-2018.
The detailed differences between Notcurses and NCURSES (a high-quality, ubiquitous
implementation of Curses) probably can't be fully enumerated, and if they
could, no one would want to read them. With that said, some design decisions
might surprise NCURSES programmers:
* There is no distinct `PANEL` type. The z-buffer is a fundamental property,
and all drawable surfaces are ordered along the z axis. There is no
equivalent to `update_panels()`.
* Scrolling is disabled by default, and cannot be globally enabled.
* The Curses `cchar_t` has a fixed-size array of `wchar_t`. The Notcurses
`cell` instead supports a UTF-8 encoded extended grapheme cluster of
arbitrary length. The only supported encodings are ASCII via `ANSI_X3.4-1968`
and Unicode via `UTF-8`.
* The cursor is disabled by default, when supported (`civis` capability).
* Echoing of input is disabled by default, and `cbreak` mode is used by default.
* Colors are usually specified as 24 bits in 3 components (RGB). If necessary,
these will be quantized for the actual terminal. There are no "color pairs",
but indexed palettes are supported.
* There is no distinct "pad" concept (these are NCURSES `WINDOW`s created with
the `newpad()` function). All drawable surfaces can exceed the display size.
* Multiple threads can freely call into Notcurses, so long as they're not
accessing the same data. In particular, it is always safe to concurrently
mutate different `ncplane`s in different threads.
* NCURSES has thread-ignorant and thread-semi-safe versions, trace-enabled and
traceless versions, and versions with and without support for wide characters.
Notcurses is one library: no tracing, UTF-8, thread safety.
* There is no `ESCDELAY` concept; Notcurses expects that all bytes of a
keyboard escape sequence arrive at the same time. This improves latency
and simplifies the API.
* It is an error in NCURSES to print to the bottommost, rightmost coordinate of
the screen when scrolling is disabled (because the cursor cannot be advanced).
Failure to advance the cursor does not result in an error in Notcurses (but
attempting to print at the cursor when it has been advanced off the plane *does*).
* Notcurses has no support for soft labels (`slk_init()`, etc.), subwindows
which share memory with their parents, nor the NCURSES tracing functionality
(`trace(3NCURSES)`).
### Adapting NCURSES programs
Do you really want to do such a thing? NCURSES and the Curses API it implements
are far more portable and better-tested than Notcurses is ever likely to be.
Will your program really benefit from Notcurses's advanced features? If not,
it's probably best left as it is.
Otherwise, most NCURSES concepts have clear partners in Notcurses. Any functions
making implicit use of `stdscr` ought be replaced with their explicit
equivalents. `stdscr` ought then be replaced with the result of
`notcurses_stdplane()` (the standard plane). `PANEL`s become `ncplane`s; the
Panels API is otherwise pretty close. Anything writing a bare character will
become a simple `cell`; multibyte or wide characters become complex `cell`s.
Color no longer uses "color pairs". You can easily enough hack together a
simple table mapping your colors to RGB values, and color pairs to foreground
and background indices into said table. That'll work for the duration of a
porting effort, certainly.
I have adapted two large (~5k lines of C UI code each) programs from NCURSES to
Notcurses, and found it a fairly painless process. It was helpful to introduce
a shim layer, e.g. `compat_mvwprintw` for NCURSES's `mvwprintw`:
```c
static int
compat_mvwprintw(struct ncplane* nc, int y, int x, const char* fmt, ...){
va_list va;
va_start(va, fmt);
if(ncplane_vprintf_yx(nc, y, x, fmt, va) < 0){
va_end(va);
return ERR;
}
va_end(va);
return OK;
}
```
These are pretty obvious, implementation-wise.
* [Differences from](doc/CURSES.md) Curses and adapting Curses programs.
## Environment notes

82
doc/CURSES.md Normal file
View File

@ -0,0 +1,82 @@
# Notcurses viz Curses/NCURSES
The biggest difference, of course, is that Notcurses is neither an
implementation of X/Open (aka XSI) Curses, nor part of SUS4-2018.
## Differences from Curses
The detailed differences between Notcurses and NCURSES (a high-quality, ubiquitous
implementation of Curses) probably can't be fully enumerated, and if they
could, no one would want to read them. With that said, some design decisions
might surprise NCURSES programmers:
* There is no distinct `PANEL` type. The z-buffer is a fundamental property,
and all drawable surfaces are ordered along the z axis. There is no
equivalent to `update_panels()`.
* Scrolling is disabled by default, and cannot be globally enabled.
* The Curses `cchar_t` has a fixed-size array of `wchar_t`. The Notcurses
`cell` instead supports a UTF-8 encoded extended grapheme cluster of
arbitrary length. The only supported encodings are ASCII via `ANSI_X3.4-1968`
and Unicode via `UTF-8`.
* The cursor is disabled by default, when supported (`civis` capability).
* Echoing of input is disabled by default, and `cbreak` mode is used by default.
* Colors are usually specified as 24 bits in 3 components (RGB). If necessary,
these will be quantized for the actual terminal. There are no "color pairs",
but indexed palettes are supported.
* There is no distinct "pad" concept (these are NCURSES `WINDOW`s created with
the `newpad()` function). All drawable surfaces can exceed the display size.
* Multiple threads can freely call into Notcurses, so long as they're not
accessing the same data. In particular, it is always safe to concurrently
mutate different `ncplane`s in different threads.
* NCURSES has thread-ignorant and thread-semi-safe versions, trace-enabled and
traceless versions, and versions with and without support for wide characters.
Notcurses is one library: no tracing, UTF-8, thread safety.
* There is no `ESCDELAY` concept; Notcurses expects that all bytes of a
keyboard escape sequence arrive at the same time. This improves latency
and simplifies the API.
* It is an error in NCURSES to print to the bottommost, rightmost coordinate of
the screen when scrolling is disabled (because the cursor cannot be advanced).
Failure to advance the cursor does not result in an error in Notcurses (but
attempting to print at the cursor when it has been advanced off the plane *does*).
* Notcurses has no support for soft labels (`slk_init()`, etc.), subwindows
which share memory with their parents, nor the NCURSES tracing functionality
(`trace(3NCURSES)`).
## Adapting NCURSES programs
Do you really want to do such a thing? NCURSES and the Curses API it implements
are far more portable and better-tested than Notcurses is ever likely to be.
Will your program really benefit from Notcurses's advanced features? If not,
it's probably best left as it is.
Otherwise, most NCURSES concepts have clear partners in Notcurses. Any functions
making implicit use of `stdscr` ought be replaced with their explicit
equivalents. `stdscr` ought then be replaced with the result of
`notcurses_stdplane()` (the standard plane). `PANEL`s become `ncplane`s; the
Panels API is otherwise pretty close. Anything writing a bare character will
become a simple `cell`; multibyte or wide characters become complex `cell`s.
Color no longer uses "color pairs". You can easily enough hack together a
simple table mapping your colors to RGB values, and color pairs to foreground
and background indices into said table. That'll work for the duration of a
porting effort, certainly.
I have adapted two large (~5k lines of C UI code each) programs from NCURSES to
Notcurses, and found it a fairly painless process. It was helpful to introduce
a shim layer, e.g. `compat_mvwprintw` for NCURSES's `mvwprintw`:
```c
static int
compat_mvwprintw(struct ncplane* nc, int y, int x, const char* fmt, ...){
va_list va;
va_start(va, fmt);
if(ncplane_vprintf_yx(nc, y, x, fmt, va) < 0){
va_end(va);
return ERR;
}
va_end(va);
return OK;
}
```
These are pretty obvious, implementation-wise.

1
doc/OTHERS.md
View File

@ -39,3 +39,4 @@
* [libsixel](https://github.com/saitoha/libsixel) (C)
* [viu](https://github.com/atanunq/viu) (Rust)
* [grafterm](https://github.com/slok/grafterm) (Go)
* [timg](https://github.com/hzeller/timg) (C++)

8
doc/man/man3/notcurses.3.md
View File

@ -44,10 +44,10 @@ 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.
**ncdirect_init(3)** makes available a very restricted subset of
Notcurses functionality. This subset is intended to be interleaved with
user-generated output, and is limited to coloring and styling. Direct mode is
documented in **notcurses_direct(3)**.
**ncdirect_init(3)** makes available a restricted subset of Notcurses
functionality. This subset is intended to be interleaved with user-generated
output, and is limited to coloring and styling. Direct mode is documented in
**notcurses_direct(3)**.
## Output