notcurses-info.1: describe output

NEWS.md

@@ -9,6 +9,7 @@ rearrangements of Notcurses.
   * Fixed bugs in `ncvisual_blitset_geom()` and `ncvisual_render()` when using
     `NCVISUAL_OPTION_CHILDPLANE` in certain configurations.
   * Fixed some serious bugs in the OpenImageIO backend.
+  * Disabled Synchronized Update Mode for Kitty in response to upstream bugs.
 
 * 2.3.7 (2021-06-29)
   * Deprecated `NCSTYLE_REVERSE` and `NCSTYLE_DIM`. The remainder are safe,

doc/man/man1/notcurses-info.1.md

@@ -21,6 +21,41 @@ The Unicode half block, quadrant, sextant, and Braille glyphs are all included
 in the output. If their appearance is irregular, it might behoove you to choose
 another font.
 
+The first five lines (the Notcurses initialization banner; see **notcurses_init(3)**)
+provide:
+
+* The Notcurses version and the derived terminal name, possibly including the
+  terminal version. If Notcurses was able to unambiguously query the connected
+  terminal, the internal name for the terminal will be shown. Otherwise, the
+  terminal described by the **TERM** environment variable will be displayed.
+  The terminal version is only acquired via query.
+* The current cell geometry, cell-pixel geometry, and the derived window pixel
+  geometry, the size of the **crender** structure, the number of colors in the
+  palette, and whether RGB TrueColor is supported.
+* The compiler name and version used to build Notcurses, the size of the
+  **nccell** structure, and the endianness with which Notcurses was compiled.
+  This buildtime endianness must match the runtime endianness.
+* The version of libterminfo against which Notcurses was compiled.
+* The version and name of the multimedia backend.
+
+The next five lines describe properties of the terminal environment:
+
+* The first line indicates that a given capability is present with a plus sign
+  ('+'), or not present/detected with a minus sign ('-'):
+  * rgb: Colors can be specified as RGB wit eight bits/channel
+  * ccc: Palette can be reprogrammed
+  * af: Foreground color can be set
+  * ab: Background color can be set
+  * sum: Synchronized Update Mode is supported
+  * u7: Cursor position reporting
+  * cup: Cursor can be arbitrarily placed
+  * vpa: Cursor can be moved to an absolute vertical coordinate
+  * hpa: Cursor can be moved to an absolute horizontal coordinate
+  * sgr0: Styling can be reset via a single escape
+  * op: Colors can be reset via a single escape
+  * fgop: Foreground can be reset via a single escape
+  * bgop: Background can be reset via a single escape
+
 # OPTIONS
 
 # NOTES

src/info/main.c

@@ -220,7 +220,7 @@ tinfo_debug_caps(struct ncplane* n, const tinfo* ti, const char* indent){
   tinfo_debug_cap(n, "ccc", ti->caps.can_change_colors, colory, colorn, ' ');
   tinfo_debug_cap(n, "af", get_escape(ti, ESCAPE_SETAF), colory, colorn, ' ');
   tinfo_debug_cap(n, "ab", get_escape(ti, ESCAPE_SETAB), colory, colorn, ' ');
-  tinfo_debug_cap(n, "asu", get_escape(ti, ESCAPE_BSU), colory, colorn, ' ');
+  tinfo_debug_cap(n, "sum", get_escape(ti, ESCAPE_BSUM), colory, colorn, ' ');
   tinfo_debug_cap(n, "u7", get_escape(ti, ESCAPE_DSRCPR), colory, colorn, ' ');
   tinfo_debug_cap(n, "cup", get_escape(ti, ESCAPE_CUP), colory, colorn, ' ');
   tinfo_debug_cap(n, "vpa", get_escape(ti, ESCAPE_VPA), colory, colorn, ' ');

src/lib/direct.c

@@ -767,11 +767,11 @@ ncdirect_stop_minimal(void* vnc){
     rl_deprep_terminal();
 #endif
   }
+  if(nc->tcache.pixel_shutdown){
+    ret |= nc->tcache.pixel_shutdown(nc->ttyfp);
+  }
   ret |= reset_term_attributes(&nc->tcache, nc->ttyfp);
   if(nc->ctermfd >= 0){
-    if(nc->tcache.pixel_shutdown){
-      ret |= nc->tcache.pixel_shutdown(nc->ctermfd);
-    }
     const char* cnorm = get_escape(&nc->tcache, ESCAPE_CNORM);
     if(cnorm && tty_emit(cnorm, nc->ctermfd)){
       ret = -1;

src/lib/internal.h

@@ -785,8 +785,8 @@ int sixel_init(const tinfo* t, int fd);
 int sixel_init_inverted(const tinfo* t, int fd);
 int sprite_init(const tinfo* t, int fd);
 int sprite_clear_all(const tinfo* t, FILE* fp);
-int kitty_shutdown(int fd);
-int sixel_shutdown(int fd);
+int kitty_shutdown(FILE* fp);
+int sixel_shutdown(FILE* fp);
 uint8_t* sixel_trans_auxvec(const struct tinfo* ti);
 uint8_t* kitty_trans_auxvec(const struct tinfo* ti);
 // these three all use absolute coordinates

src/lib/kitty.c

@@ -640,10 +640,10 @@ int kitty_clear_all(FILE* fp){
   return term_emit("\e_Ga=d\e\\", fp, false);
 }
 
-int kitty_shutdown(int fd){
+int kitty_shutdown(FILE* fp){
   // FIXME need to close off any open kitty bitmap emission, or we will
   // lock up the terminal
-  (void)fd;
+  (void)fp;
   return 0;
 }
 

src/lib/notcurses.c

@@ -57,15 +57,15 @@ notcurses_stop_minimal(void* vnc){
   // be sure to write the restoration sequences *prior* to running rmcup, as
   // they apply to the screen (alternate or otherwise) we're actually using.
   const char* esc;
+  // ECMA-48 suggests that we can interrupt an escape code with a NUL
+  // byte. if we leave an active escape open, it can lock up the terminal.
+  // we only want to do it when in the middle of a rasterization, though. FIXME
+  if(nc->tcache.pixel_shutdown){
+    ret |= nc->tcache.pixel_shutdown(nc->ttyfp);
+  }
+  ret |= notcurses_mouse_disable(nc);
+  ret |= reset_term_attributes(&nc->tcache, nc->ttyfp);
   if(nc->ttyfd >= 0){
-    // ECMA-48 suggests that we can interrupt an escape code with a NUL
-    // byte. if we leave an active escape open, it can lock up the terminal.
-    // we only want to do it when in the middle of a rasterization, though. FIXME
-    if(nc->tcache.pixel_shutdown){
-      ret |= nc->tcache.pixel_shutdown(nc->ttyfd);
-    }
-    ret |= notcurses_mouse_disable(nc);
-    ret |= reset_term_attributes(&nc->tcache, nc->ttyfp);
     if((esc = get_escape(&nc->tcache, ESCAPE_RMCUP))){
       if(sprite_clear_all(&nc->tcache, nc->ttyfp)){
         ret = -1;

src/lib/render.c

@@ -1084,7 +1084,7 @@ notcurses_rasterize_inner(notcurses* nc, ncpile* p, FILE* out, unsigned* asu){
 #define MIN_ASU_SIZE 4096 // FIXME
   if(*asu){
     if(nc->rstate.mstrsize >= MIN_ASU_SIZE){
-      const char* endasu = get_escape(&nc->tcache, ESCAPE_ESU);
+      const char* endasu = get_escape(&nc->tcache, ESCAPE_ESUM);
       if(endasu){
         if(fprintf(out, "%s", endasu) < 0){
           return -1;
@@ -1110,7 +1110,7 @@ raster_and_write(notcurses* nc, ncpile* p, FILE* out){
   // will we be using application-synchronized updates? if this comes back as
   // non-zero, we are, and must emit the header. no ASU without a tty, and we
   // can't have the escape without being connected to one...
-  const char* basu = get_escape(&nc->tcache, ESCAPE_BSU);
+  const char* basu = get_escape(&nc->tcache, ESCAPE_BSUM);
   unsigned useasu = basu ? 1 : 0;
   // if we have ASU support, emit a BSU speculatively. if we do so, but don't
   // actually use an ESU, this BASU must be skipped on write.

src/lib/sixel.c

@@ -923,8 +923,8 @@ int sixel_rebuild(sprixel* s, int ycell, int xcell, uint8_t* auxvec){
 
 // 80 (sixel scrolling) is enabled by default. 8452 is not. XTSAVE/XTRESTORE
 // would be better, where they're supported.
-int sixel_shutdown(int fd){
-  return tty_emit("\e[?8452l", fd);
+int sixel_shutdown(FILE* fp){
+  return term_emit("\e[?8452l", fp, false);
 }
 
 uint8_t* sixel_trans_auxvec(const tinfo* ti){

src/lib/termdesc.c

@@ -336,11 +336,11 @@ add_smulx_escapes(tinfo* ti, size_t* tablelen, size_t* tableused){
 
 static int
 add_appsync_escapes_sm(tinfo* ti, size_t* tablelen, size_t* tableused){
-  if(get_escape(ti, ESCAPE_BSU)){
+  if(get_escape(ti, ESCAPE_BSUM)){
     return 0;
   }
-  if(grow_esc_table(ti, "\x1b[?2026h", ESCAPE_BSU, tablelen, tableused) ||
-     grow_esc_table(ti, "\x1b[?2026l", ESCAPE_ESU, tablelen, tableused)){
+  if(grow_esc_table(ti, "\x1b[?2026h", ESCAPE_BSUM, tablelen, tableused) ||
+     grow_esc_table(ti, "\x1b[?2026l", ESCAPE_ESUM, tablelen, tableused)){
     return -1;
   }
   return 0;
@@ -348,11 +348,11 @@ add_appsync_escapes_sm(tinfo* ti, size_t* tablelen, size_t* tableused){
 
 static int
 add_appsync_escapes_dcs(tinfo* ti, size_t* tablelen, size_t* tableused){
-  if(get_escape(ti, ESCAPE_BSU)){
+  if(get_escape(ti, ESCAPE_BSUM)){
     return 0;
   }
-  if(grow_esc_table(ti, "\x1bP=1s\x1b\\", ESCAPE_BSU, tablelen, tableused) ||
-     grow_esc_table(ti, "\x1bP=2s\x1b\\", ESCAPE_ESU, tablelen, tableused)){
+  if(grow_esc_table(ti, "\x1bP=1s\x1b\\", ESCAPE_BSUM, tablelen, tableused) ||
+     grow_esc_table(ti, "\x1bP=2s\x1b\\", ESCAPE_ESUM, tablelen, tableused)){
     return -1;
   }
   return 0;

src/lib/termdesc.h

@@ -68,8 +68,8 @@ typedef enum {
   ESCAPE_DSRCPR,   // "u7" cursor position report
   // Application synchronized updates, not present in terminfo
   // (https://gitlab.com/gnachman/iterm2/-/wikis/synchronized-updates-spec)
-  ESCAPE_BSU,      // Begin Synchronized Update
-  ESCAPE_ESU,      // End Synchronized Update
+  ESCAPE_BSUM,     // Begin Synchronized Update Mode
+  ESCAPE_ESUM,     // End Synchronized Update Mode
   ESCAPE_MAX
 } escape_e;
 
@@ -134,7 +134,7 @@ typedef struct tinfo {
   // execute move (erase old graphic, place at new location) if non-NULL
   int (*pixel_move)(const struct ncpile* p, struct sprixel* s, FILE* out);
   int (*pixel_destroy)(const struct notcurses* nc, const struct ncpile* p, FILE* out, struct sprixel* s);
-  int (*pixel_shutdown)(int fd);    // called during context shutdown
+  int (*pixel_shutdown)(FILE* fp);  // called during context shutdown
   int (*pixel_clear_all)(FILE* fp); // called during context startup
   uint8_t* (*pixel_trans_auxvec)(const struct tinfo* ti); // create tranparent auxvec
   // sprixel parameters. there are several different sprixel protocols, of