NAME
     vt, vtdump, vttest - VT100/ANSI terminal emulator

SYNOPSIS
     vt local
     vt off
     vt telnet host [port]
     vt file
     vtdump file [cols rows]
     vttest

DESCRIPTION
     The deck's ordinary screen is a teletype: text arrives, it scrolls, and
     the e-paper redraws the part that changed.  That is the right model for a
     shell and the wrong one for anything that positions its own cursor.  Vt
     is the other screen, a VT100/ANSI emulator with a real cell grid -- cursor
     addressing, scroll regions, line drawing, reverse video.  BBSes, full-
     screen programs on the far end of a telnet session, and ANSI art files
     all need it.

     Only one vt owns the panel at a time.  While one is up the ordinary
     terminal stops drawing; when it goes away the shell view comes back.

     The grid is sized to fit the panel with the smallest available font, so
     that 80 columns fit.  On Model 4 that is 80 by 26.

     vt local puts the shell itself inside the emulator: the prompt and
     command output render through the cell grid instead of the teletype.  It
     returns immediately, so you keep typing at the same shell.  It stays up
     until vt off.

     vt telnet wraps a telnet session.  This is worth knowing about but rarely
     worth typing: telnet(1) already opens inside vt by default, and vt telnet
     exists so a session can be nested inside one you started yourself.
     Inside a session Ctrl-] opens telnet's own menu.

     Any other argument is taken as a path.  The file is fed through the
     parser and left on screen -- ANSI art, a captured session, or a streaming
     device such as /dev/eia0, which keeps painting as bytes arrive.  Press
     Ctrl-] to leave.  Files displayed this way get carriage return supplied
     on every line feed, since local files usually have bare newlines.

SEQUENCES
     What the parser acts on.  Anything else is discarded rather than printed.

     Cursor
          CUU, CUD, CUF, CUB (CSI A-D); CNL, CPL (E, F); CHA and HPA (G, `);
          VPA (d); CUP and HVP (H, f); IND, NEL, RI (ESC D, E, M); save and
          restore in both the DEC (ESC 7, ESC 8) and ANSI (CSI s, CSI u)
          spellings.

     Erase and edit
          ED (J), EL (K), IL (L), DL (M), ICH (@), ECH (X), DCH (P), SU (S),
          SD (T), REP (b).

     Regions and modes
          DECSTBM (CSI r) sets the scroll region; DECOM (CSI ?6) makes cursor
          addressing relative to it, which is how a BBS keeps a status line
          and an input line apart from the scrolling middle.  Autowrap is CSI
          ?7, cursor visibility CSI ?25, insert mode CSI 4h.

     Tabs HTS (ESC H) sets a stop at the cursor column; TBC (CSI g) clears one
          stop or, with parameter 3, all of them.

     Rendition
          SGR (CSI m).  The panel has one bit per pixel, so colour is mapped
          rather than shown: a background colour becomes inverse video, a
          bright foreground becomes bold, an ordinary foreground colour is
          dropped.  256-colour and truecolour forms are parsed so their
          parameters are not misread as further attributes.  Bold, underline
          and inverse work as themselves.

     Character sets
          ESC ( ) * + designate G0 through G3.  The DEC special graphics set
          (ESC ( 0) draws the box characters BBS menus are made of.

     Reports
          DSR (CSI 6n) replies with the cursor position, when there is a
          connection to reply on.

     Other
          RIS (ESC c) resets everything; DECALN (ESC # 8) fills the screen
          with E's; OSC strings are consumed and ignored.

     High bytes are read as UTF-8 and translated to the CP437 glyphs the fonts
     actually contain.  A malformed sequence latches the session into raw
     CP437 for the rest of its life, which is what ANSI art from a BBS wants.

DIAGNOSTICS
     vtdump feeds a file through the parser with no display at all and prints
     the resulting cell grid as text: size, cursor position, one line per row,
     then a list of cells carrying attributes.  The grid is 80 by 24 unless
     cols and rows say otherwise, so the output is identical on every build.
     It is how the emulator is tested against a reference implementation.

     vttest paints a fixed pattern -- a box in DEC line drawing, reverse video,
     absolute cursor moves -- holds it for five seconds, and exits.  It takes
     no arguments.  Use it to see whether the parser and the panel agree.

KEYS
     ctrl-]
          Leave a file display.  In a telnet session, open telnet's menu.

     While vt local is up there are no special keys; the shell has them all.
     Type vt off to get the ordinary terminal back.

EXAMPLES
     Look at a piece of ANSI art:

          vt /n/local/art/welcome.ans

     Watch a serial port as it talks:

          vt /dev/eia0

     Run the shell inside the emulator for a while:

          vt local
          ls /n/local
          vt off

FILES
     /dev/eia0
          A serial port, readable as a stream.

SEE ALSO
     telnet(1), con(1), bbs(1), gopher(1)

NOTES
     The cell grid lives in PSRAM, so a full 80-column screen costs the deck
     nothing it needs elsewhere.

     Rendering is debounced: the emulator waits for the byte stream to go
     quiet for about a third of a second before touching the panel, and then
     redraws only the rectangle that changed.  This is why a busy screen looks
     like it arrives in one piece rather than crawling.

     The cursor is not drawn on real e-paper.  Partial refresh does not
     reliably clear an inverted row of pixels, so a moving cursor leaves a
     trail of half-erased underlines behind it.  On the simulator and in the
     browser, where pixels do as they are told, it is drawn.

BUGS
     There is no alternate screen buffer.  Programs that expect one -- vim,
     less, htop -- will draw over the scrollback and leave it overwritten when
     they exit.

FRST Computer                                                            VT(1)
