programmable terminal color redefinition and theming SciTECO curses UI based on Scintilla styles

 * The first 16 colors of the terminal palette can be redefined
   using the 3EJ property - with all restrictions that ncurses
   and UNIX terminals impose on us.
   It is still important to be able to redefine the palette for
   some color schemes like Solarized since it may be difficult
   for users to set up the terminal emulator's palette manually.
   Also when using PDCurses, setting the palette is port-specific
   or only possible using init_color(). In order to allow color
   redefinitions across all curses ports it makes sense if SciTECO
   gives access to the color initialization of curses even if it can
   guarantee very little about its semantics in general.
 * 3EJ is completely ignored for GTK+
 * use the STYLE_DEFAULT of the current document to style the message line.
   Fg and bg colors are reversed to guarantee a good contrast to the
   Scintilla view.
   Errors are still hardcoded to a red background, warnings to yellow
   and info messages to green.
   This allows color-scheming more of SciTECO given that the
   red, yellow and green terminal colors are not changed fundamentally
   in the terminal's palette.
 * info line is now also styled using STYLE_DEFAULT (reverse colors).
   The Q-Register and buffer names are now written out using format_str()
   which means that control characters are written out in REVERSE just
   like in the command line.
   String::canonicalize_ctl() is still used to canonicalize window
   titles.
 * Command line is now modelled as a curses Pad and "blitted" to the
   command line window. This allowed simplification of the command line
   drawing code and introduction of format_str().
   The command line is now styled according to STYLE_DEFAULT (original
   fg and bg colors).
   The rubbed-out part of the command line can now longer be shown in
   bold black - or even bold light black - since that is not visible in
   all color themes. Instead it is now only shown in bold.
   Command line theming problems will be gone once we use a Scintilla
   view for the command line.
 * The popup widget is now styled according to STYLE_CALLTIP.
 * This means that all relevant parts of SciTECO's user interface
   can now be themed. This allows the creation of themes that redefine
   the terminal palette radically (e.g. Solarized) and the creation of
   "bright" themes (e.g. Solarized/bright).
 * theming of the non-scintilla-view parts of SciTECO is currently
   unsupported on GTK+. The reason is that both the popup widget
   and command line widgets have to be rewritten completely in GTK+
   and are work in progress, so adapting the current code would be
   a waste of time.
 * Added a manual section about the UI and theming.

1 files changed, 85 insertions, 0 deletions

diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template
index efe8538..3807640 100644
--- a/doc/sciteco.7.template
+++ b/doc/sciteco.7.template
@@ -609,6 +609,85 @@ so for instance \(lq~/foo\(rq will complete a file
 in the user's home directory.
 .
 .
+.SH USER INTERFACE
+.
+\*(ST can be built with support for different textual and
+graphical user interfaces.
+In \*(ST's batch mode, there is little difference between
+the user interfaces (as no graphical window will be visible).
+Naturally the interfaces have different graphical capabilities
+but \*(ST tries to provide a consistent look and feel across
+all user interfaces and reasonable defaults to make writing
+user-interface agnostic macros and profiles easier.
+The user interface will always be segmented into the following
+areas from top of the program window to bottom:
+.IP \(bu 2
+The \fIinfo area\fP identifying the currently edited buffer or
+Q-Register.
+This area is currently sometimes omitted.
+If technically possible, \*(ST will include the same information in the
+window's title.
+.IP \(bu
+The \fIScintilla area\fP displaying the current document's
+contents.
+This corresponds to a Scintilla view (see section \fBBUFFER RING\fP)
+and can be customized extensively using Scintilla messages
+(see the \fBES\fP command).
+.IP \(bu
+The \fImessage area\fP which will show the last \*(ST message
+that occurred.
+This area will show errors, warnings, \(lquser messages\(rq
+and other notes and tries to highlight them appropriately.
+.IP \(bu
+The auto-completion \fIpopup area\fP which is only shown when
+presenting the user with a choice of auto-completions.
+This area will overlap the \fIScintilla\fP and \fImessage
+areas\fP.
+.IP \(bu
+The \fIcommand line area\fP, showing the currently effective
+and rubbed-out command line as it is edited.
+This is currently a single line of text that is scrolled
+automatically.
+.
+.SS Colors and Theming
+.
+\*(ST supports customizing its look predominantly by setting
+up the current Scintilla view using Scintilla messages
+(see the \fBES\fP command and Scintilla documentation).
+Most visual properties of the Scintilla view can be set
+via its styles.
+This is also how syntax highlighting (lexing) is set up.
+.LP
+The \fBSTYLE_DEFAULT\fP (32) style defines the default foreground,
+background color, font etc. and is initialized to white on
+black with some monospaced font by \*(ST.
+The \fBSTYLE_DEFAULT\fP is also accessed by \*(ST to style the
+\fIinfo area\fP, \fImessage area\fP (if it is empty or when
+showing \(lquser messages\(rq) and \fIcommand line area\fP.
+The info and message areas are styled reverse to the setting
+of this style to provide good contrast, i.e. with foreground and
+background colors swapped.
+The colors used to highlight errors, warnings and other messages
+in the \fImessage area\fP are currently hardcoded and cannot
+be customized.
+The command line area on the other hand will be styled with
+the original colors of \fBSTYLE_DEFAULT\fP and should look
+similar to the current Scintilla view.
+.LP
+The \fBSTYLE_CALLTIP\fP (38) style is also accessed by
+\*(ST to style the \fIpopup area\fP and is initialized
+to black on (light) blue by \*(ST.
+.LP
+On curses user interfaces, only a selection of 16 terminal
+colors can be used, although it is possible to request changing
+the default color mapping (see \fBEJ\fP command).
+.LP
+Scintilla styles will usually be set up in the profile
+macro or \fBED\fP hook (for syntax highlighting).
+\*(ST ships with a standard library with color schemes
+and lexer configurations for a wide range of languages.
+.
+.
 .SH ARITHMETICS AND EXPRESSIONS
 .
 \*(ST abstracts classic TECO's scheme of commands accepting at most
@@ -1679,6 +1758,12 @@ Scintilla messages and other documentation:
 .UR http://scintilla.org/ScintillaDoc.html
 Scintilla
 .UE
+.TP
+Scinterm manual, documenting the mapping of
+\(lqRGB\(rq values to terminal colors on curses user interfaces:
+.UR http://foicica.com/scinterm/manual.html
+Scinterm manual
+.UE
 .
 .
 .SH AUTHOR