** Enhanced GlkTerm **

This library is an enhanced version of GlkTerm. It is modified rather than
the official version of GlkTerm, although it is believed to be compatible
in most cases. This file contains documentation for the new features. In
addition to new features, there are also some minor bug fixes.

See also the gtoption.h file.


=== Preferences ===

The file ~/.glktermrc contains user preferences. You can also set the
environment variable named GLKTERMRC to specify a different filename for
the user preferences file.

Blank lines and lines starting with # are comments.

Defining the value of a preference is done by the name and then a equal
sign and then the value. For boolean preferences, use "y" for yes and "n"
for no (without the quotation marks).

Possible preferences include:

* screenwidth: Override the screen width (same as -width).

* screenheight: Override the screen height (same as -height).

* messageline: Boolean; yes to display the message line.

* reverse_textgrids: Boolean; yes to make text grid windows to be reverse
video, or no to make not reverse video.

* window_borders: Boolean, and defines whether or not window borders are
displayed. If not set, uses the window border hint instead.

* precise_timing: Same as -precise. This allows timing more precise than
deciseconds if it is set to yes, but can load the CPU more.

* historylen: Number of history entries (normally 20).

* prompt_defaults: Same as -defprompt. If yes (the default setting), then
the filename is already filled in if glk_fileref_create_by_prompt() is
called (the user can still edit it, though).

* style_override: Boolean; yes if you want to customize the styles. This
is necessarily if you are using the user style preferences. If you do not
specify this, the default settings are used for all styles.

* border_graphics: Boolean; yes if you want to use line graphics (in
curses, the ACS_ constants) instead of ASCII for window borders.

* border_style: User style for window borders. See section below about the
syntax of user styles.

* use_colors: Boolean, and must be yes to enable colours in user styles.

* clear_message: Boolean; if yes, clear the message line when glk_select()
is called or when ctrl-L is pushed.

* auto_focus: Boolean; if yes, auto focus a suitable window when an event
is requested or if you push a key that cannot be used in the current
window but is suitable for another one. This is yes by default.

* more_message: Boolean; if yes, display "--More--" on the message line
when the text does not all fit on the screen at once, if it has not yet
reached the end of the text buffer. Only if it is the active window.

* typable_controls: If yes (which is the default setting), then it reports
most control characters as typable, but if no then it doesn't. This does
not control which control characters actually are acceptable, though; it
only controls the report with gestalt_CharInput.

* typable_specials: This is similar to typable_controls, although it
affects the report of special characters (such as F1, F2, etc) instead.
Furthermore, gestalt_LineTerminatorKey is affected too.

* temporary_filename: Requires OPT_USE_MKSTEMP. If set, the last six
characters must be "XXXXXX", and then mkstemp() is used to make temporary
filenames rather than using tmpnam(). The "XXXXXX" are replaced by
something new each time it is called.

* readonly: Force all file streams opened from Glk filerefs to be read
only, except for glk_fileref_create_by_prompt() if fmode is something
other than filemode_Read. The glkunix_ functions can still open files for
writing; this preference only affects Glk fileref functions. Also, if this
is set, temporary files are not available.

* auto_suffix: If yes (the default), the filename suffix by usage is
automatically added if glk_fileref_create_by_name() is called. If no, then
there is no suffix.

* prompt_raw_filename: If yes, glk_fileref_create_by_prompt() does not
mangle filenames entered by the user; the entered filename is instead used
directly, as a native filename relative to the current directory. Leading
and trailing spaces are still trimmed, however. This does not affect
glk_fileref_create_by_name() or any other function.

* clock_skew: A number of seconds to skew the system clock; can be a
positive or negative number, or zero. This affects date/time functions.
(To change the timezone, set the TZ environment variable.)

* restrict_files: If yes, glk_fileref_create_by_name() will fail if the
name is not specified by a user filename mapping.

* pause_warning: If yes, pause when a warning message is displayed. (A
warning message is normally displayed if the Glk functions are misused,
although there are a few other cases too, such as restrict_files.)

* more_exit: If yes, paging is possible when glk_exit() is called.

* User styles: The preference name starts with "B" (for text buffer
windows), "G" (for text grid windows), or "S" (for both kind), and is then
followed by a number indicating the style to set (0 for style_Normal; see
glk.h for the style numbers). See section of user styles for the syntax of
this option. You must also set style_override for this to work.

Another command in the user preference file is a name in square brackets.
This causes the rest of the file to be ignored, unless the environment
variable called GLKTERMRC_SECTION is set, in which case if it matches the
name in the brackets then it reads those settings but if it doesn't
match then the settings are ignored (settings before any named section are
still read regardless of this setting).

You can also specify filename mappings. This starts with / and then a Glk
filename, and then = and the native filename. This is checked when
glk_fileref_create_by_name() is called; if it is mapped (regardless of the
specified usage), it will use the specified native filename instead of
figuring it out by itself. If you double the initial slash then it will
allow writing to that file even if readonly is set.


=== User styles ===

The syntax of a user style is zero or more of the following characters, in
any order, except that no more than one digit should be specified.

  a   Alternate character set
  b   Bold or bright
  d   Dim
  i   Invisible
  k   Blinking
  p   Protected
  r   Reverse video
  s   Best highlighting mode of the terminal
  u   Underlined
  0   Black on black
  1   Red on black
  2   Green on black
  3   Yellow on black
  4   Blue on black
  5   Purple on black
  6   Cyan on black
  7   White on black

Which ones are supported depends on the terminal in use; see the curses
documentation for further details.


=== Command-line arguments ===

There are two new options:

-- means that all further arguments are plain arguments and should not be
treated as options. This allows filenames starting with a minus sign.

-glkext is followed by a user preference string, and sets it. This
overrides the corresponding setting in the .glktermrc file.


