TEAL 0.4 - developer graphical text editor for DOS
================================================

Build with Borland C++ 3.1:

  BUILD

Clean-build and run all regression tests:

  CHECK

Source tree:
  SRC\             editor implementation and XMS assembly bridge
  INCLUDE\         TEAL module headers
  TESTS\           standalone regression tests and test fixtures
  ASSETS\FONTS\    original Spleen PSF font sources
  ASSETS\PARSERS\  external language definition files
  DOCS\            third-party license notices
  TOOLS\           host-side asset generation utilities
  BUILD\           generated objects, executables and staged runtime files

BUILD.BAT leaves runnable TEAL and AMBER distributions in BUILD\. The
source root contains only build scripts, response files, configuration
templates, project metadata and this documentation.

CHECK builds TEAL and AMBER, then runs the XMS driver, paged XMS store,
document/piece-table and video-cell regression suites.  It leaves a nonzero DOS
ERRORLEVEL if compilation, linking, an output check or any test fails.

Run:

  BUILD\TEAL ASSETS\EXAMPLE.TXT
  BUILD\TEAL ASSETS\EXAMPLE.TXT /TEXT
  BUILD\TEAL ASSETS\EXAMPLE.TXT /320
  BUILD\TEAL ASSETS\EXAMPLE.TXT /640
  BUILD\TEAL ASSETS\EXAMPLE.TXT /800
  BUILD\TEAL ASSETS\EXAMPLE.TXT /1024

If the file does not exist, TEAL starts with an empty new document.
Before overwriting an existing file, TEAL copies its previous on-disk
contents to a DOS-compatible .BAK name (for example TEST.TXT becomes
TEST.BAK).  Each later save refreshes the backup with the version that
existed immediately before that save.

After returning to DOS, TEAL prints a short summary with the number of
changed lines and changed bytes relative to the file opened at startup.

Video modes:
  /TEXT      native BIOS 80x25 color text mode
  /TEXT28    native VGA 80x28 color text mode
  /TEXT50    native VGA 80x50 color text mode
  no switch  VESA 800x600x256
  /320       planar VGA Mode X 320x240x256
  /640       VESA 640x480x256
  /800       VESA 800x600x256
  /1024      VESA 1024x768x256

The VESA modes use a classic banked frame buffer and require a VESA BIOS
that supports standard modes 101h, 103h and 105h.
The text modes write character and attribute cells directly to B800h and
maps the active RGB theme onto the standard 16-color VGA text palette.

Configuration:
  TEAL reads TEAL.CFG as standard JSON beside its executable. If it
  is missing, it is recreated from the built-in defaults. Command-line
  video switches override CFG. The "configuration" object contains editor
  behavior and the selected theme. The sibling "themes" object contains
  every available color scheme.
  Theme colors use #RRGGBB values. TEAL assigns them to private VGA
  palette slots and programs the VGA DAC after entering the video mode.
  The display remains 256-color, but each configured color is freely
  selectable from the 24-bit RGB range (the VGA DAC stores 6 bits/channel).
  The default cursor is a non-blinking full-cell block; cursor behavior is
  part of each theme. F4 opens the graphical settings dialog for word wrap,
  wrap column, startup resolution and theme. Saving writes these values
  directly to TEAL.CFG; a new resolution takes effect on the next start.
  When word wrap and Wrap guide are enabled, a subtle vertical guide marks
  wrapColumn throughout the editing area. Its visibility is stored as
  wrapGuideVisible; its color comes from wrap_guide in the active theme.
  A theme may contain sparse "text_mode" and "graphics_mode" objects.
  Colors listed there override the shared theme value only in that video
  kind; omitted colors automatically inherit the common value. This keeps
  both modes visually related without forcing them to share unsuitable UI
  surface colors.

Keys:
  F1              full-screen keyboard shortcut help
  F2              move focus between editor and sidebar; opens it if needed
  Ctrl+F2         open or close the project sidebar
  F3              find next match
  F4              settings dialog
  F9              open the classic menu bar
  Alt+F/E/S/V/O/H open File/Edit/Search/View/Options/Help menu
  F12             toggle editor UI bars/full-screen editing area
  Ctrl+S          save
  Ctrl+A          select the entire document
  Ctrl+Z          undo (up to 50 editing steps)
  Ctrl+I          toggle insert/overwrite mode
  Ctrl+G          go to line
  Ctrl+F          find text (search wraps at end of file)
  Ctrl+R          replace next match (Tab/Shift+Tab changes field)
  Ctrl+M          jump to matching (), {}, [], "" or ''
  Ctrl+Shift+M    select text between matching delimiters
  Ctrl+C          copy selected text to TEAL's internal clipboard
  Ctrl+X          cut selected text to TEAL's internal clipboard
  Ctrl+V          replace selection / paste from internal clipboard
  Ctrl++          increase font size
  Ctrl+-          decrease font size
  Ctrl+W          close the active editor tab
  Ctrl+Q, Alt+F4  quit
  Arrow keys      move cursor
  Shift+movement  select text
  Esc             cancel selection
  Home, End       start/end of line
  PgUp, PgDn      move one screen
  Backspace, Del  delete
  Enter           new line

Menus:
  TEAL's classic menu bar is rendered by TEAL's own VGA/VESA renderer.
  It adds no Fastgraph dependency and no work to the normal typing or
  scrolling path. Use Left/Right to change menus, Up/Down to select an
  item, Enter to run it and Esc to close the menu. Dropdown foreground
  and background colors are configured with menu_fg and menu_bg. The
  one-pixel dropdown outline uses menu_border.

Themes:
  Each object below "themes" in TEAL.CFG defines one complete editor
  color scheme. TEAL and AMBER include TealLight, TealDark, OceanDark,
  OceanLight, RealTealDark, NordDark, MaterialLight, MaterialDark,
  XCodeLight, AmberLight and AmberDark. TEAL defaults to OceanLight and
  AMBER defaults to AmberLight.
  Mode-specific overrides support window, menu, mnemonic, button and gutter
  colors. The supplied themes keep their classic text-window surfaces while
  graphical dialog backgrounds follow the corresponding textarea color.
  The Settings dialog lists every loaded theme; choose one with Space and
  Up/Down, then Save.

  TEAL reads and writes the merged configuration directly in TEAL.CFG.
  Standard JSON does not support // comments. When TEAL.CFG is edited,
  its contents are not overwritten by the automatic settings save on exit.

TEAL uses the Spleen monospaced bitmap font by Frederic Cambus,
distributed under the BSD 2-Clause license (see DOCS\SPLEEN.LIC). The original
PSF sources are under ASSETS\FONTS: SPLEEN5.PSF (5x8), SPLEEN6.PSF (6x12)
and SPLEEN16.PSF
(8x16). Spleen 6x12 is the default, approximately 10 point. Ctrl++ and
Ctrl+- switch sizes while TEAL is running. MKFONT.PY converts the first
256 CP437 glyphs to the generated INCLUDE\FONTDAT.H header. No external font is
needed at runtime.
Maximum file size is 60 KB.

The default 320x240 display is unchained planar VGA Mode X. Scrolling uses
the VGA latches to copy all four pixel planes in parallel. At startup TEAL
builds normal and inverted planar glyph caches. A dirty-cell cache ensures
that only changed text cells are copied to VGA memory.

Word wrap is configured through F4 and TEAL.CFG; Ctrl+W closes the active tab.
Wrapped lines are stored
as real line breaks in the file. Opening a file immediately wraps existing
text. Disabling wrap does not join lines back together.
The wrap column is configurable through F4 or wrapColumn in TEAL.CFG.

Find and Replace provide Case sensitive, Wrap search and Highlight matches
checkboxes.  Up/Down moves between fields and options, Space toggles an
option, Tab jumps to OK, Enter confirms and Esc cancels.  F3 selects the
next match. TEAL.CFG stores these options as searchCaseSensitive,
searchWrap and searchHighlight.

Tabs and indentation:
  tabSize selects the visual tab width (1 through 16).
  translateTabsToSpaces=false inserts literal tab characters. When true,
  Tab inserts spaces instead. With useTabStops=true, Tab advances to the
  next tab stop and Backspace/Delete remove adjacent indentation spaces
  up to the previous/next stop. With useTabStops=false, Tab inserts exactly
  tabSize spaces. autoIdent=true copies the leading tab/space indentation
  of the current line when Enter creates a new line. smartIdent=true adds
  one more indentation level after C-like if, for, while, switch, else and
  do statements, opening braces and labels. smartIdent only has an effect
  while autoIdent is enabled.
  On load TEAL examines leading indentation on every line. Files dominated
  by literal tabs keep literal-tab editing; files dominated by spaces use
  spaces, and TEAL infers a likely tabSize from their common indentation.
  Mixed or inconclusive files retain the safer literal-tab behavior or the
  existing CFG width.
