Readme for GLKDos 0.19.1
by L. Ross Raszewski
Based upon GlkTerm 0.7.2 by Andrew Plotkin

Implements Glk 0.6.1
Library source for DJGPP and compatable compilers.


This implementation of the GLK specification is mostly compatable
with GlkTerm, with the following features:
Sound (AIFF and MOD) support
Color
run-time configuration (press Alt-F1 to access the menu)
screen capture
user macro keys
Shell-to-dos
Copy buffer ("clipboard")
graphics-mode output 
User-settable fonts
Scrollable virtual screen
Graphics windows
Blorb images in graphics and textbuffer windows.
Open file listbox
sglk extensions
User-configurable keybindings
Mouse
The sound, configuration, and output modules are optional at compile-time;
it may be useful to use a less-fully featured glkDOS if the application
does not require certain features, as it will reduce compile time and
executable size (or if you don't want to be bothered to go out searching
for the required libraries)
the makefile includes targets for building eight different versions of the
library:

glkDOS classic: (glkt)
 supports sound and user configuration files. Sound support is provided
 via Allegro and JGMod, which are required for compilation of glkDOS
 programs. Text output is provided by PDCurses (compatable curses
 libraries may be substituted), which is required for compilation.
 Config file support is provided by GNU Flex, which is required for
 compilation
glkDOS without sound: (glks)
 glkDOS classic without sound support. Allegro and JGMod are not
 required for compilation.
glkDOS without config files: (glkc)
 glkDOS classic without config file support. Flex is not required.
glkDOS bare-bones: (glkn)
 The smallest version of the glkDOS library. Provides neither sound nor
 configuration files, and thus requires only curses.
glkDOS classic, PC-BIOS accelerated version: (glkd)
 This version is almost identical to glkDOS classic, but uses DJGPP specific
 functions for accessing PC video memory in an optimized manner.
Allegro glkDOS: (glka/glkan)
 In addition to sound, Allegro may also be used for text output. This build
 supports several graphical resolutions, several user fonts, and a
 "virtual screen", which can be used to simulate a higher resolution than
 is actually in use.  This build requires Allegro, JGMod, and flex, but not
 the curses library. (The curses.h is required to build the library itself,
 however). "glka" also provides support for displaying Blorb images. It
 requires zlib, libpng, and the independant jpeg group's software.
glkDOS/Unix: (glku)
 There has been some desire expressed to have the suite of advanced glkDOS
 features available on unix systems. In response, I have retroported
 glkDOS back to its origins.
 This mode is experimental, and should be treated with care.

And a menu-driven system exists to pick-and-choose glk features and build
glkDOS accordingly.

Some video cards may require VBE/AF drivers to run Alegro GlkDOS correctly.
The free VBE/AF driver is available from the allegro homepage

questions, comments, and suggestions should be mailed to L. Ross Raszewski,
rraszews@acm.org

Also included is a precompiled version of the GLKDos library.
-----------------

GlkDOS: 0.9.2 -- a (formerly) brief users guide.

( Aside: This document contains some commentary.
    It's set off in little "aside" notations, and explains some of
    the reasoning behind what might be considered "strange" or "bad"
    decisions on my part.
)

1. Compiling glkdos

[This section is largely superceded by the graphical configuration toy.]

Compiling glkDOS is facilitated by the graphical configuration system.
type "config" to start the system.  You will be presented with a screen
like this:

                              GlkDOS Configuration                              
                                                                                
        Target                            CSCR module                           
  *default (glkt)                         curses                                
   alleg (glka)                           dos                                   
   dos (glkd)                             allegro                               
   allegn (glkan)                         unix ncurses                          
   no_sound (glks)                                                              
   no_config (glkc)                                                             
   no_frills (glkn)                                                             
   unix (glku)                                                                  
   custom (glk)                                                                 
                                                                                
                                                                                
   Options                                                                      
   [*] sound                             Write makefile and compile             
   [*] config files                                                             
   [ ] graphics                                                                 
                                                                                
                                                                                
                                                                                
                                                                                

Use the up and down arrow keys to navigate, <TAB> to switch between option
groups, and <ENTER> to select an option. <ESCAPE> quits.

a '*' indicates selected options. Certain option groups are incompatable,
and will be "greyed out" (graphics is only available under allegro, for
example. Likewise, sound is always included under allegro). Most importantly,
the 'Options' and 'CSCR Module' selections are only available when 'custom'
is selected.

Once you've chosen the combination you want, selecting
"write makefile and compile" builds the glk library.

If you're building a "custom" library, the library is called "libglk.a",
and the makefile "make.gll". Otherwise, the naming conventions below apply.

Also, once a custom build has been made using the configurator, the
makefile target 'make custom' becomes available, which
builds the library according to whatever specifications were last used in
the graphical tool.
                                                                                



1.1 Compiling the curses version of glkdos

1.1.1 Compiling the full suite of glkdos (curses library) features: (glkt)
        requires:
         DJGPP 2.7.2.1
         GNU Make
         GNU flex
         PDCurses or compatable curses library
         Allegro game programming library
         JGMod module player library

This distribution of GlkDOS defaults to this configuration. After unpacking
the source, run "make" at your command prompt.  Assuming all goes well, this
should create libglkt.a, the GlkDOS library binary, and make.glk, the makefile
definitions for using GlkDOS.

NOTE:: You may need to set the makefile variable BASE_LIBS to the name of
your curses library.  For most standard DJGPP Curses installations, you will
want:
BASE_LIBS = -lcurso

1.1.2 Compiling glkdos without config file support: (glkc)
        requires:
         As in section 1.1, EXCEPT:
          GNU flex

Make GlkDOS compile without config file support, build the library with
the following command: 

make no_config

This will build libglkc.a without config file support, and make.glc.
It is not necessary to link the flex library when building Glk
programs for this library.


1.1.3 Compiling glkdos without sound: (glks)
	requires:
         As in section 1.1, EXCEPT:
          Allegro game programming library
          JGMod module player library

to build GlkDOS without sound support, use the following make command:

make no_sound

This will build libglks.a without sound support, and make.gls. It is
not necessary to link the standard math library, allegro, or jgmod to
build glk applications

1.1.4 Compiling with neither sound nor config files (glkn)

make no_frills

1.2 Compiling the PC-BIOS accelerated version of glkDOS
 requires
         DJGPP 2.7.2.1
         GNU Make
         GNU flex
         Allegro game programming library
         JGMod module player library

 type 'make dos' to build libglkd.a and make.gld

 This version of the library supports all the features of glkDOS classic.

 Targets are not provided for compiling the PC-BIOS versions with
 features omitted. Such functionality can be easily constructed by careful
 examination of the other makefile targets, or via the configuration toy.

(Aside: why do this version at all?
 This version of glkDOS was designed for users without curses, who wanted
 a smaller binary, or who needed a (very) slightly faster glk.
 It adds several additional sub-features:
  screen redraws are synchronized to the monitor refresh
  the original screen state is restored on exit
 Also, this version is a stepping-stone toward a proposed dual-mode glkDOS
)
1.3 Compiling the allegro version of glkDOS

1.3.1 Compiling glkDOS/Allegro without image support (glkan)
        requires:
         DJGPP 2.7.2.1
         GNU Make
         GNU flex
         Allegro game programming library
         JGMod module player library

type

make allegn

This will build libglkan.a and make.glg.  The allegro version of glkDOS
supports sound and config files, but does not offer text-mode only output.

The "glkan" version offers graphics windows, but only the rectangle drawing
functions are available for such windows. (this is the "stripped down"
version of glkDOS/Allegro, and is provided only because it is substantially
smaller, and requires fewer outside libraries to compile)

1.3.2 Compiling glkDOS/Allegro with image support (glka)
   requires:
    As section 1.2.1, plus
    Zlib compression library
    The Independant Jpeg Group's jpeg library
    libpng png library
type
make alleg

This will build libglka.a and make.gla.  This allegro version additionally
supports jpeg and png images.

1.4 Compiling glkDOS/Unix
 GlkDOS/Unix can only be compiled on a *nix machine.
  requires:
    gcc
    flex
    ncurses
    make
  'make unix' will produce libglku.a and make.glu

1.5 To compile all the libraries at once:

make all

will build the following libraries:

libglkt.a       GlkDOS with sound and config file support
libglks.a       GlkDOS with config file support
libglkc.a       GlkDOS with sound support
libglkn.a       GlkDOS without config file or sound support
libglka.a       GlkDOS with allegro graphical output.
libglkan.a      GlkDOS/Allegro without jpeg or PNG support.
libglkd.a       GlkDOS with PC-BIOS acceleration
and the following makefile supplements:
make.glk        for libglkt
make.gls        for libglks
make.glc        for libglkc
make.gln        for libglkn
make.gla        for libglka
make.glg        for libglkan
make.gld        for libglkd
* make all will _not_ build GlkDOS/Unix, nor will it build the "custom"
  glk.

1.5 Other Makefile targets:
 target         effect                                  requires
 source_arc     produces glktds.zip source archive      zip archiver
 bin_arc        produces glktdb.zip library archive     zip archiver
 dist           source_arc bin_arc                      zip archiver
 clean          removes all intermediate files          rm
 config         produces config.exe to use the cdos CSCR module
 custom         rebuilds the last "custom" library      config's makefile.cst 

the "zip archiver" is any command line program which can generate zip files.
the makefile variable "ZIP" holds the name of this archiver

2. compiling with glkdos

2.1  Implementation-dependant features.

GlkDOS provides several platform-bound features which are not directly part
of Glk.  They involve additional code which should be added to a Glk program
only when it is compiled under glkDOS.

2.1.1 file name base

**This section is superceeded by the sglk control sglk_set_basename.
  glkdos_set_basename still works, but shoudl be considered "less portable"

Since Glk does not know anything about the program which it is running,
it is difficult to make prompted file names provide sensible defaults. Some
platforms may have facilities which make it possible for glk to infer a
something about what it is doing, but DOS does not. 

GlkDOS allows the author to specify the "base name" for default file names
during library initialization. The function:

glkdos_set_basename(char *str);

sets the base of the prompted file names to str. (subsequent user input
will change the default).  This function should be called at the
same time as the parsing of command line parameters (probably from
glkunix_startup_code; see below), though it will still function if
called later.

If glkdos_set_basename is never called, the library will try its darndest to
choose a sensible default (by extracting the base name of the executable).


2.1.2 glk startup code.

GlkDOS uses the startup code identical to glkterm.  The following is
an extract from the glkterm documentation elaborating...

(Unlike set_basename, these functions still use the "glkunix" prefix;
this is in order to allow programs to use the same code between unix and
DOS glks)
---------------------
When you compile a Glk program and link it with GlkTerm, you must supply
one more file: you must define a function called glkunix_startup_code(),
and an array glkunix_arguments[]. These set up various Unix-specific
options used by the Glk library. There is a sample "glkstart.c" file
included in this package; you should modify it to your needs.

The glkunix_arguments[] array is a list of command-line arguments that
your program can accept. The library will sort these out of the command
line and pass them on to your code. The array structure looks like this:

typedef struct glkunix_argumentlist_struct {
    char *name;
    int argtype;
    char *desc;
} glkunix_argumentlist_t;

extern glkunix_argumentlist_t glkunix_arguments[];

In each entry, name is the option as it would appear on the command line
(including the leading dash, if any.) The desc is a description of the
argument; this is used when the library is printing a list of options.
And argtype is one of the following constants:

    glkunix_arg_NoValue: The argument appears by itself.
    glkunix_arg_ValueFollows: The argument must be followed by another
argument (the value).
    glkunix_arg_ValueCanFollow: The argument may be followed by a value,
optionally. (If the next argument starts with a dash, it is taken to be
a new argument, not the value of this one.)
    glkunix_arg_NumberValue: The argument must be followed by a number,
which may be the next argument or part of this one. (That is, either
"-width 20" or "-width20" will be accepted.)
    glkunix_arg_End: The glkunix_arguments[] array must be terminated
with an entry containing this value.

To accept arbitrary arguments which lack dashes, specify a name of ""
and an argtype of glkunix_arg_ValueFollows.

If you don't care about command-line arguments, you must still define an
empty arguments list, as follows:

glkunix_argumentlist_t glkunix_arguments[] = {
    { NULL, glkunix_arg_End, NULL }
};

Here is a more complete sample list:

glkunix_argumentlist_t glkunix_arguments[] = {
    { "", glkunix_arg_ValueFollows, "filename: The game file to load."
},
    { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
    { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
the NUM, if given)." },
    { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
    { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
    { NULL, glkunix_arg_End, NULL }
};

This would match the arguments "thingfile -goo -wob8 -bom -hum song".

After the library parses the command line, it does various occult
rituals of initialization, and then calls glkunix_startup_code().

int glkunix_startup_code(glkunix_startup_t *data);

This should return TRUE if everything initializes properly. If it
returns FALSE, the library will shut down without ever calling your
glk_main() function.

The data structure looks like this:

typedef struct glkunix_startup_struct {
    int argc;
    char **argv;
} glkunix_startup_t;

The fields are a standard Unix (argc, argv) list, which contain the
arguments you requested from the command line. In deference to custom,
argv[0] is always the program name.

You can put other startup code in glkunix_startup_code(). This should
generally be limited to finding and opening data files. There are a few
Unix Glk library functions which are convenient for this purpose:

strid_t glkunix_stream_open_pathname(char *pathname, glui32 textmode, 
    glui32 rock);

This opens an arbitrary file, in read-only mode. Note that this function
is *only* available during glkunix_startup_code(). It is inherently
non-portable; it should not and cannot be called from inside glk_main().


-----------------

2.1.3 sglk

sglk is a set of extensions to glk which are unique to this library.
they take advantage of the platform to increase flexibility.

These features are, of course, non-portable, and "should not be used".
(Alternatively, if these features are found handy, they may be added
to future glk versions, but that's up to Zarf)

Other Glk porters are asked to be kind and consider implementing as
many of these functions as is convenient.

The header file for sglk is sglk.h. It defines the following functions:

void sglk_set_style(strid_t str, glui32 fg, glui32 bg, glui32 attr);
 This function "tweaks" the appearance of the given stream. Its output
 will be set to the specified foreground and background colors (or
 as close as glkDOS can come to matching them). The special value
 SGLK_DEFAULT means "whatever color the current style is usually
 rendered in"
 attr is a bitmask specifying one or more of the following flags:
 SGLK_BOLD: Render in high-intensity
 SGLK_DIM:  Render in low-intensity
 SGLK_ITAL: Ignored, for compatability with nitfol
 SGLK_FIXED: Ignored, for compatability with nitfol
 SGLK_REVERSE: reverse fg and bg (which may be default)
 The effects of sglk_set_style are cancelled by a call to glk_set_style
 or by the call sglk_set_style(str,SGLK_DEFAULT,SGLK_DEFAULT,0);
 The practical effect of using this is to set the current output style to a
 "new magic style" whose metrics are those of the previous style with the
 given "tweaks".

glui32 sglk_color_distinguish(glui32 col1, glui32 col2)
 GlkDOS renders text in 4-bit color; 3 bits represent the presence of
 blue, green, and red, and the remaining bit specifies the intensity.
 the intense bit is set if the high-order bit is set for blue, red, or green
 in the glk color number, so 0x7f0000 is low-intensity red, and 0x000080 is
 bright blue.
 This function returns non-zero if the given colors render differently
 in 4-bit color.

glui32 sglk_color_distinguish_graphics(glui32 c1, glui32 c2)
 GlkDOS/Allegro uses 16 bit color; Glk uses 24. This function returns
 nonzero if the two given colors are distinct within a graphics window.
 This function always returns false in non-graphical versions.

void sglk_get_default_colors(glui32 *fg, glui32 *bg);
 This function gets the current default fore and background colors
 and stores them in the pointers provided. If the "normbg" option
 is selected, bg is set to the background color of style_Normal.
 If one or both pointers are NULL, that value is not stored.

void *sglk_get_image(winid_t win, glsi32 x,glsi32 y,
                                  glui32 width,glui32 height);
 This function captures part of a graphics window, and returns an opaque
 reference to it. The image can be drawn again using the sglk versions of
 the glk graphics functions.

void sglk_delete_image(void *b);
 This function destroys an image returned by sglk_get_image

glui32 sglk_image_draw(winid_t win, void *b, glsi32 val1, glsi32 val2);
glui32 sglk_image_draw_scaled(winid_t win, void *b, 
    glsi32 val1, glsi32 val2, glui32 width, glui32 height);

 These functions are equivalent to their glk counterparts, but take opaque
 sglk-image objects instead of blorb image numbers.
 
void sglk_set_basename(char *str)
 This function sets the "base" for automatically generated file names.
 (see section 2.1.1 for mre details)

void sglk_request_abilities(glui32 a)
 This function should only be called early in the startup code. It announces
 which glk features the program wants. Although it currently does nothing,
 other glks might use this to determine which components to load/initialize
 (a future version of glkDOS might combine curses and allegro versions, and
 use this to determine which screen interface to use)
 a is a bitwise OR of the following flags:
 SGLK_GRAPHICS   : the program wants graphics
 SGLK_SOUND      : the program wants sound
 SGLK_MOUSE      : the program wants the mouse
 A Z-machine or glulx interpreter might check the story file for use of sound
 and pictures, and set the abilites aprpriately, so that the application is run
 in text or graphics mode as is apropriate.

2.2 Linking the relevant files

The makefile for glkDOS creates (in addition to the library) a corresponding 
make.gl[kcsna], which "describes" how to link a glk program to glklib.
It provides the makefile variables GLK_LIB (which has the gcc command
to link the GlkDOS library), and LINK_LIBS (which has the gcc commands
to link the other needed libraries).

The make.gl? also provides one further variable: GLKFILE, which is the full
name of the glk library. If you want targets in your makefile to depend on
the "freshness" of the glk library itself, you can use this variable
to get at the apropos .a file.

Essentially, compile your glk program, and link it with your startup
code and the libraries.

Included with this distribution is a generic makefile, makefile.gd, which
will build simple glk programs using glkDOS

make -f makefile.gd foo

will build "foo" from "foo.c" using glkDOS.

this makefile supports the following makefile variables:

GLKDIR=.                the directory containing the glk headers and library
GLKMAKE=make.glk        the make.gl? for the desired glkDOS version
GLKSTART=glkstart.o     the object file for the glkterm startup code
PROGDEPS=%.o            the dependant files for the target
PROGTARGET=%            the desired target



3. Using glkDOS based applications

3.1 The command line
 GlkDOS-built applications support the following arguments to the glk
library: 

  -width NUM: manual screen width (if not specified, will try to measure)
  -height NUM: manual screen height (ditto)
        Set screen dimentions (in characters)

  -ml BOOL: use message line (default 'yes')
	Display messages from the library in a separate line at the 
        screen bottom. Disabling this gives you one extra line of screen,
        but may hide warning or error messages.

  -historylen NUM: length of command history (default 20)

  -revgrid BOOL: reverse text in grid (status) windows (default 'no')
	Inverts the normal color settings in textgrid windows

  -border BOOL: draw borders between windows (default 'no')
	Draws a visible border around windows

  -latin BOOL: assume latin1 codepage (default: 'no')
	Try to use latin1 encoding (only partially functional, due to
	DOS limitations that I haven't worked around yet)

  -normbg BOOL: match background to "normal" style (default: 'yes')
	Paint the background of the entire screen (particularly, after
	a screen clear) with the color of the normal style, rather
	than the default color

  -fg NUM: default foreground color (default: 7)
  -bg NUM: default background color (default: 1)
	default screen color

  -gl BOOL: show links in grid windows (default: 'no')
  -bl BOOL: show links in buffer windows (default: 'yes')
        GlkDOS indicates the presence of hyperlinks by printing an
        annotation [#] at the begining of each link. Since this may cause
        calculations in grid windows to be inaccurate, annotations
        are not shown for textgrid windows by default. These options
        alter the normal display of link annotations.

  -normal/emphasis/preform/header/subheader/alert/note/blockquote/user1/user2
	NUM:
    individual style appearances (see config menu for defaults)

	set the attributes for a particular style. The number is
	calculated based on the style metrics, and is displayed by the 
	config menu.


  -sound BOOL: play sound (default: 'yes')

  -more BOOL: display "[MORE]" pager (default: 'yes')
  -percent BOOL: display percentage pager (default: 'no')
  -fraction BOOL: display fractional pager (default: 'yes')
        GlkDOS offers three "pager" indicators, which appear in the
        message line when a scrollable window is not positioned
        at its bottom (ie, a full page of text has just been printed)
        Any combination of these pagers can be enabled at any time.

        more: the traditional [MORE] prompt
        fraction: shows the current window position as a fraction
                (last visible line/total lines)
        percent: shows the percentage of the buffer which is above the
                 current window position

  -credits: display library credits
  -version: display Glk library version
  -help: display library options

The following options have no meaning except in the allegro version of the
library

  -db BOOL: reduce flicker via screen buffering (default: 'yes')
        GlkDOS can maintain a memory buffer to minimize the frequency
        of video-memory writes. Using this buffering will greatly reduce
        flicker, however it requires more memory at run-time and
        may result in a slight screen lag at high resolutions 
        If a buffer cannot be created, glk will halt with
        an error message. Use this option to disable buffering (alternatively,
        reducing the virtual resolution may make double-buffering possible
        again). Since the virtual screen uses this buffer, disabling
        double buffering also disables the virtual screen. Glk will
        print a warning but will not halt if you try to set a
        virtual resolution while buffering is off.

  -res NUM: set resolution to NUM (default: 2)
        Sets the screen resolution. The available resolutions are:
        1: 320x200
        2: 640x480
        3: 800x600
        4: 1024x768
        5: 1280x1024
        If allegro cannot set the desired resolution, glk will terminate with
        an error message. This is the size of the "real" screen, and is
        independant of the virtual screen

  -vresx NUM: set virtual X-resolution to NUM (default: 0=use screen size)
  -vresy NUM: set virtual y-resolution to NUM (default: 0=use screen size)
        Sets the size of the virtual screen, in pixels. The default setting
        is for the virtual screen to use the same dimentions as the physical
        screen, but it may be set smaller or larger to any size, so long
        as sufficient memory is available for the virtual screen buffer.

  -font NUM: use font NUM from the font datafile (default: 0=use builtin font)
        Tells GLK to use the specified font from the font file.
        (use -fl to display a list of available fonts)
        The builtin font (0) is an 8x8 font, which resembles the PC bios font,
        and is always available. Other font availability depends on the
        supplied font datafile

  -cpl NUM: scale (non-builtin) font to NUM characters per line
      (default: 0=do not rescale)
        The fonts in the font datafile can be resized to accommodate the
        screen resolution. This may cause undesirable distortion of the font
        (fonts become blocky if scaled up, and lose clarity of scaled down),
        so a variety of fonts are provided whose unscaled size is appropriate
        to different ranges of resolutions.

        (Note: due to rounding, the font may not be scaled to exactly the
        desired characters per line -- Glk will scale the font as closely
        as possible)
        
  -fl: display a list of all available fonts

  -dvorak BOOL: Remap for dvorak keyboard (default: 'no')
    remap the keyboard for dvorak. This is not necessary on all
    dvorak keyboards. The curses version will perform mapping automatically
    on a correctly configured dvorak keyboard.
    ** This option is depreciated. Use the International Keyboard Support
       package avialable from the glkDOS distribution site. ***
    
3.2 The on-line configurator	


While running a glkDOS application, press Alt-F1 to bring up the 
runtime-configuration manager:



 GlkDOS Configuration       

  > Message Line [YES]
    Reverse textgrid [NO]
    Pager [ MORE FRACTION ]
    Display window borders [NO]
    Show links in buffer windows
    Sound (if available) [ON]
    Forground Color [7]
    Background Color [1]
    Match background to style_Normal [YES]
    Set attributes for style: Normal [768]
    Default foreground color
    Default background color
    Force high intensity
    Force low intensity
    Reverse
    Lock attributes
    Apply these settings to all current windows
    Write these settings to file


These options have roughly the same meanings as their counterparts on the
command line options list.  The arrow keys cycle between settable options,
and pressing <enter> will toggle the setting of the selected value.

The number printed beside a style name is used by GlkDOS as a descriptor
for the current attributes of the style.  This number can be entered on the
command line or in a glkDOS config file to change the style's default
appearance.

'Lock Attributes' toggles which attributes of the currently selected style
are "locked".  Locked attributes are not changed by stylehints set within
a glk program.

'Apply these settings' makes changes in the editor apply to windows
already on the screen.  If you do not select this option, any changes you
make will only be applied to windows created AFTER you leave the
configuration manager.

'Write settings' saves the current glkDOS configuration to a config file
(see below)


Press 'q' or escape to leave the menu


3.3 glkDOS configuration files.

If glkDOS is compiled with support for config files, then on startup, glkDOS
programs will look for a configuration file.  If the environment
(or DJGPP.ENV) variable GLKCFG is set, glkDOS will try to open the file
listed there. Otherwise, glkDOS will attempt to read from the file glk.cfg
in the current working directory. (if the variable GLKDIR is set, it will
then concatenate it to the beginning of the config file name and look for
that file, so if GLKDIR="d:\djgpp\", and GLKCFG is unset, it will first try
glk.cfg, then d:\djgpp\glk.cfg)
A glk configuration file contains one or more of the following lines. If
two settings conflict, the last occurance is used.  These options override
glkDOS defaults, and are overridden by command line options.

Each setting corresponds to a glkDOS command line argument:

WIDTH <num>                         equivalent to -width
HEIGHT <num>                        equivalent to -height
MESSAGELINE (on, off)               equivalent to -ml
HISTORY <num>                       equivalent to -historylen
REVERSE GRID                        equivalent to -revgrid yes
NORMAL GRID                         equivalent to -revgrid no
BORDER (off,on)                     equivalent to -border
LATIN1 (off,on)                     equivalent to -latin
NORMALIZE BACKGROUND                equivalent to -normbg yes
DEFAULT BACKGROUND                  equivalent to -normbg no
FOREGROUND <num>                    equivalent to -fg
BACKGROUND <num>                    equivalent to -bg
SOUND (on,off)                      equivalent to -sound
MORE (on,off)                       equivalent to -more
FRACT (on,off)                      equivalent to -fraction
PERCENT (on,off)                    equivalent to -percent
RESOLUTION <num>		    equivalent to -res
VIRTUAL_WIDTH <num>		    equivalent to -vresx
VIRTUAL_HEIGHT <num>		    equivalent to -vresy
CPL <num>			    equivalent to -cpl
BUFFER (on,off)			    equivalent to -db
GRIDLINK (on,off)                   equivalent to -gl
BUFFERLINK (on,off)                 equivalent to -bl
DVORAK (on, off)                    equivalent to -dvorak
the following commands take as an argument the value given by the
configuration manager for the corresponding style

NORMAL                              equivalent to -(style name)
EMPHASIS
PREFORMATTED
HEADER
SUBHEADER
ALERT
NOTE
BLOCKQUOTE
USER1
USER2
LINK                                 (LINK is not a real style; it is the
                                      font used when printing link
                                      annotations)

Finally, the option 'BINDKEY' is specific to glkDOS config files. It allows
you to override the default key bindings for glkDOS applications. Note that
binding a key does NOT invalidate the current binding, but new bindings will
"shadow" the original, overriding it in apropriate windows.

BINDKEY keycode command

 keycode is a decimal (base 10) number corresponding to the key to be bound
 ( see cscr.h for the keycodes; printable characters correspond to their
   ascii values, control-letters correspond to their placement in the alphabet
   (so ^A has keycode 1, ^B is 2, etc).)
 and 'command' is one of the glkDOS internal command names (which can be
 revealed by toggling the 'reveal codes' option.) see next section.

*** UNIX ONLY:
 whether or not extended keys will be honored correctly depends on your
 terminal settings and the key translator in cncurses.c

(Aside: improvments to the cncurses, calleg, and cdos key translators are
 more than welcome
)

You cannot rebind ^C (curses) or control-alt-end (allegro)
3.4 Special keys
The following keys have special meaning in glkDOS:

ALT-F1          bring up the configuration manager
ALT-F2          Capture current screen to scrxxxxx.txt or scrxxxxx.bmp
ALT-F3          Execute a named command
Tab             switch focus to the next window
^O              Input key by keycode
^R              Reveal codes
^L              redraw the screen
^Z              Shell to DOS (COMSPEC environment variable or command.com)
^C              Terminate glkDOS (curses versions)
Ctrl-alt-END    Terminate glkDOS (allegro versions)
Ctrl-Tab        generate a hyperlink event (if one is pending)

General keys for a text buffer window:
^Home           Jump to the beginning of the buffer
^End            Jump to the bottom of the buffer
^Up             Scroll up one line
^Down           Scroll down one line
PageUp,^Y       Scroll up one page
PageDown,^V     Scroll down one page

Keys for line input in a buffer:
Insert          toggle overwrite mode
Enter           signal completion of input
<-              move the cursor back a character
->              move the cursor forward a character
Home,^A         jump to the beginning of input
End,^E          jump to the end of input
Backspace       delete the character BEFORE the cursor
Delete          delete the character UNDER the cursor/delete to mark
F5-F8           User macros
^F5-^F8         Set user macro to contents of copy buffer
^K              (Kill-line) move all characters AFTER the cursor to copy buffer
^U              (Undo-line) clear the input buffer
^Q              (Quote-on) Set the mark
^Del,^W         (Wipe) Move text up to the mark into the copy buffer    +
^Ins,^S         (Save) Copy text up to the mark into the copy buffer    +
Alt-Ins,^X      (Xtract) Paste the contents of the copy buffer to the input *+
Up, ^P          (Previous) recall the previous input buffer from history
Down,^N         (Next) recall the next input buffer from history

(*) In the allegro version, Shift-Insert also performs this function
(+) The PC-BIOS accelerated version does not honor alt-ins, ^ins or ^del
( Aside: if anyone can work out why, e-mail me!
)
** UNIX ONLY:
  The keys ^Q, ^S, and ^Z have special meaning in unix shells. ^<space>
  serves to set the mark in unix. Use ^Insert to copy text, and
  suspend/resume is handled by the shell.
  To send an <escape> keycode, it is necessary to press escape twice in
  rapid succession.
  To send ^Tab, press escape, then tab, in rapid succession
 
Special commands have an internal name, which can be displayed by
revealing the codes. The command names are:

toggle_overwrite        reveal_codes    shell           change_focus
refresh                 setup           screencap       exec_command
accept_key              insert_key      arbitrary_key   accept_line
move_left               move_right      begin_line      end_line
delete_backward         delete_forward  end_line        undo_input
kill_line               scroll_to_top   scroll_up       scroll_to_bottom
page_up                 page_down       get_link        accept
history_prev            history_next    set_macro_[1-4] macro_[1-4]
buffer_extract          buffer_wipe     buffer_save     set_mark

These values are (mostly) accepted by the 'Bindkey' config file option

( Aside: these keybindings do not apply in the setup menu or the
   file listbox.
)
3.5 Hyperlinks

GlkDOS supports the GLK Hyperlink capability. When a link is started,
GlkDOS prints an annotation in the output window giving the number
of the link.

Since this may generate unwanted noise in the output, the user
can turn link annotation on or off at runtime. Link annotations are
on by default in buffer windows, and off in grid windows. It is not
recomended that links be turned on in grid windows, as this may
disrupt the intended flow of text.

To select a hyperlink, press control-tab. If any windows desire a
hyperlink input, the glk messageline will display partial text of the
last printed hyperlink. Pressing <UP> will cycle backwards through
hyperlinks in the order they were issued, and pressing <DOWN> cycles
forward. Pressing enter causes the currently displayed hyperlink to be
executed. Press escape or 'q' to cancel the hyperlink input.

3.6 Screen capture

GlkDOS offers the ability to dump the current screen to disk. Press Alt-F2
to make a screen capture.

In curses versions of glkDOS, the screen dump is an ascii text file layed out
to mimic the appearance of the screen (note that the effect of styled text
will not be visible in the output file).  The output file is placed in the
current directory, and is named scrXXXXX.txt, where XXXXX is the first
unused number (so the first screen capture made in a directory will
be called scr00000.txt, the second scr00001.txt, and so on. glkDOS will not
overwrite existing scrXXXXX.txt files. Up to 10000 screen capture files
may be created in any directory).

In the allegro version, the screen dump is a truecolor BMP file at the
current virtual resolution. (note that this can be quite large; at 640x480,
a screen capture is almost 1 megabyte) The output file will reflect the
exact layout of the screen, including styles as they appeared when the
capture was made. Files are named as in the curses version, except that the
file extension is .bmp

(Aside: Why BMP?
 Allegro does not provide native support for PNG or JPEG files. Of the
 formats which it DOES natively support (bmp, tga, and pcx), BMP is the
 best supported on modern systems. For the sake of speed and easy programming,
 BMP is therefore the format of GlkDOS/Allegro screen dumps.
)

Screen capture is not available under allegro if buffering is
turned off.

You cannot capture the GlkDOS configuration screen or the file listbox.

3.7 Copy Buffer and user macros

GlkDOS offers a 1024-character "copy buffer", which can be used to store a
frequently used string of text.

Text is inserted into the copy buffer using the "mark". The mark is set by
pressing ^Q. When the mark is set, the following keys will copy all
text between the cursor and the mark into the copy buffer:
 ^W, ^Del : MOVE text to copy buffer (Wipe/Cut)
 ^S, ^Ins : COPY text to the copy buffer (Save/Copy)
When the mark is not set, text may be copied to the buffer using ^K, which
is equivalent to the sequence ^Q^E^W

( Aside: The copy buffer only works for line input in a text buffer.
   It's implementationally complex. Patches are welcome.
)

Additionally, when the mark is set, <DELETE> will delete all text
between the cursor and the mark.

To recall the text from the copy buffer, type ^X

( Aside: These keys differ slightly from the common key bindings.
 In most DOS/Win applications, the "CUI" keyset is used for text editing.
 However, some CUI keys (shift-insert and shifted-arrow keys) are not
 available using the curses library. The keys used here are closer to
 those used by GNU/Emacs.  The most notable exception
 is that the mark is set by ^Q instead of control-space.  This too is
 because curses won't return that character. The key ^S  was chosen
 for "copy" due to its mnemonic value, and the slightly clumsier ^X
 was chosen for "extract (paste)", primarily because the three keys
 ^W, ^S and ^X form a line down a standard QWERTY keyboard
)

GlkDOS also has 4 slots reserved for "user macros".  Pressing ^F5-^F8 sets
the corresponding macro key to the current contents of the copy buffer.
Later, pressing the corresponding F-key will print out the macro.

3.8 DOS Shell

GlkDOS can suspend its operation and enable a user DOS session.
Pressing ^Z will invoke the command interpreter listed in the environment
variable COMSPEC. If COMSPEC is unset, it executes "command", the default
DOS interpreter.  Type "exit" (or exit the shell as usual) to resume GLK.

( Aside: ^Z is the common unix keybinding for "suspend", which the DOS shell
  emulates as best it can
)
Note that in allegro versions, there will be a noticable lag when entering
or leaving a DOS shell as the video mode resets.

Shelling to DOS while audio is playing may have undesirable effects, and is
not recomended.

3.9 File naming convenions

GlkDOS uses the following file extensions. Extensions marked with a (*)
indicate that the extension is a default value, which may be overridden

Extension       Format                  Usage
.TXT            Text                    GlkDOS/Curses screen capture
.TXT (*)        Text                    ASCII datafile
.BMP            Windows BMP             GlkDOS/Allegro screen capture
.BLB (*)        Blorb                   Blorb resource (+)
.DAT            Allegro grabber         Font data
.DAT (*)        Binary                  Binary datafile
.SAV (*)        Binary                  Savefile
.SCR (*)        Text                    Transcript
.REC (*)        Text                    Command record
.CFG (*++)      GlkDOS config           GlkDOS config file

(+) Glk never actually refers to a blorb file by name. the BLB extension
is listed here simply for completeness, as most glk applications will use
this extension for blorb data.

(++) While a config file may have any name, glkDOS always writes output
config files to "glk.cfg"

The following extensions are not used by glk per se, but are common in glk
applications.  They are included here to alert users that using these
extensions might have the undesirable effect of overwriting important data.

Extension       Function
.GAM            TADS gamefile
.HEX            Hugo gamefile
.DAT            Z-code gamefile (infocom)
.ZIP            Z-code gamefile (late infocom)
.Z[3,5,8]       Z-code gamefile (inform)
.ULX            Glulx gamefile
.INF            Inform source
.T              Tads source
.HUG            Hugo Source
.C              C source
.CC,.CPP        C++ source
.A,.LIB         Compiled library

3.10 The File list box

 If a program prompts for a file name, you can either type in the name
 you want for the file, or select a file from the file list box.

 To access the file list box, press <up> while at the file selection
 prompt.  You will be presented with a list of available files and
 directories.

( Aside: Why doesn't the file list box just come up all the time?
   I don't really like file list boxes that much in console apps. If I know
   the file name, it's easier for me to just type it in. If I don't, then maybe
   I'll want the list box to look at. Whatever.
)
 The file list box has four fields which may be navigated. Pressing
 <TAB> toggles which field is active (denoted by the location of the
 cursor)

 Files:
      This is a list of files in the current directory (which is displayed
      at the top of the screen).  You can use the arrow keys to navigate the
      list. (home and end jump to the top and bottom).  Typing a letter
      will take you to the next entry beginning with that letter.
      Pressing <ENTER> will copy the current selection to the File prompt
      and switch focus there. Numbers appear at the top and bottom of the
      display to indicate that unseen files exist outside the visible list
      area
 Directories:
     This is a list of directories. It behaves like the files list. Pressing
     enter will switch the current directory to the one selected.
 File:
     The currently selected file. You can edit this as normal. Pressing
     enter will accept the current value as input.
 Filter:
     This is a wildcard expression which specifies which files are to be
     listed in the file box. Pressing enter will refresh the directory listing
     based on the new value of this filter.

 Pressing escape cancels the file input.

 
4 Allegro Extended features

4.1 The Virtual Screen
 When buffering is turned on, Allegro GlkDOS writes its output to a 
"virtual screen" in memory.  While the size of the physical screen is 
determined by the resolutions available on your video card, the 
virtual screen can be of any size (limited by memory, of course)

By default, the virtual screen is matched to the size of the physical screen,
but this can be overridden by the command line options -vresx and
-vresy.  If the virtual resolution is smaller than the physical
resolution, only part of the physical screen will contain output.
Contrarywise, if the virtual resolution is greater than the physical
screen size, only part of the virtual screen is displayed.
You can think of the physical screen as a "window" (in the
non-computing sense) through which the virtual screen is viewed.  For
example, if the resolution is set to its default (640x480), and the
virtual resolution is set to 800x600, the screen model would look like
this: (apologies for the ascii art)

+--------------+------+
| Physical     |      |
|  Screen      |      |
| (viewable    |      |
|   window)    |      |
+--------------+      |
| Virtual Screen      |
| (Non-viewable)      |
+---------------------+

GLK will render the screen as if the resolution were actually 800x600.
This might at first seem a little useless, but it is possible to
scroll the virtual screen at run-time.

To move the viewable area, use the numeric keypad:
1: scroll the viewable window to the far right
2: scroll the viewable window down
3: scroll the viewable window to the bottom
4: scroll the viewable window to the left
6: scroll the viewable window to the right
7: scroll the viewable window to the far left
8: scroll the viewable window up
9: scroll the viewable window to the top

(These keys correspond to the layout fo the directional arrows on the numeric
pad.)
For virtual scrolling to work, Num-Lock must be turned _ON_ and Scroll-lock
must be turned _OFF_ (if you use the numeric keypad frequently, press
scroll-lock to disable virtual scrolling)

(Aside: I know that these keys are inconvenient for laptop users.
 There were very few keys left.
)
This mode can be especially helpfull when running GlkDOS applications on a
machine with limited video resources; many programs will not display
correctly on very small screens (inform compiled programs often display
broken status lines and box quotes if the screen width is too small.)
starting glkDOS with the options -res 1 -vresx 640 -vresy 480 will emulate
the default screen settings as a virtual screen of 640x480 on a physical
screen of 320x200. The virtual screen can also be used, say, to make
decorative GLK windows invisible, by scrolling them outside the viewable
region, or as a form of alternative paging, or to magnify glk's output
(a 640x480 virtual screen with a 320x200 physical screen could be considered
to be a 640x480 screen with a 320x200 "magnifying glass")

4.2 Font support

4.2.1 using fonts
Allegro GlkDOS can use a number of fonts to improve the appearance of text
in a Glk application.

One font, the 8x8 "standard" font, is built into GlkDOS. This is the
default font used by Glk, and emulates the PC bios font.

Other fonts are available, and are provided in the font datafile.
When GlkDOS starts, if an alternative font is requested, GlkDOS looks
for the font datafile. If the environment (or DJGPP.ENV) variable GLKFONT
is set, GlkDOS tries to load that file, otherwise it looks in the current
directory for "font.dat".  Failing that, if GLKDIR is set, it looks there
for GLKFONT or font.dat.  If no font file is found, glk will exit with an
error message if an attempt is made to use a different font or display the
font list.

The command line option -fl will print out the list of fonts available.
The font datafile can be modified without recompiling the library or
GlkDOS-built programs.

Alternative fonts each have their own size. Because of the Allegro font
format, fonts will generally look best at their default size, however, since
fonts vary in size, it may be desirable to rescale a font for a specifc
video mode (the included courier 12pt font, for example, prints only 65
characters per line in 640x480, and thus may reveal limitations in
some inform games). The -cpl option rescales a font so that it displays
the specified number of characters per line on the virtual screen (Glk
will try to scale the font as closely as it can to the specified size,
but due to scaling issues, this may not be exactly the same size
requested.)

Note that scaling a font down loses data; it is very dificult to find a
font which remains readable if it is scaled to fit 80 characters across
a 320x200 screen. Likewise, scaling up may cause the font to become blocky,
though for some fonts the effect is not profound.  The font list
contains a description of the point size at which the font was rendered,
which may be helpful in deciding which font to use for a certain video mode
(note that a large font tends to scale better both up and down than a
small one).  This should not be taken as an absolute indication of font
size, however (for example, the font 6x13 12 pt. prints at 106
characters per line in 640x480, while 7x14 12 pt prints 80 characters per
line. Monotype 12 pt prints only 65).

4.2.2 Font file format

The font.dat file is in the allegro datafile format, which can easily be
created using the utilities which come with the allegro library.

The first entry in the data file is the font description, a text file
which is printed in response to the -fl option.  The first thing in
this file MUST be the number of fonts in the datafile

Individual fonts are created from PCX bitmaps. While these are technically
proportional fonts, for Glk to work properly, every character in the file
must have the same width.  The exact specifications of the font data file
are left to the allegro documentation.

If every character in the font is not of the same width, GlkDOS scales
the font characters to the width of the letter 'M'. This may produce
unwanted distortion, so it is recomended that user hand-edit the font
bitmap so that every character is the same width, by scaling or centering
the character as looks best

It is also possible to add an 8x8 or 8x16 font to the datafile, but this
is not recomended, as attempting to scale such a font will cause Glk to
fail.

Future versions may add support for other font formats, but proportional
font support is not a priority.

( Aside: I don't like proportional fonts.
  Which is not enough to keep me from implementing them. However,
  doing so would mean that a very large percentage of the GlkDOS code
  would no longer be portable between curses and allegro versions, which is.
)

the font.dat file must be distributed with any program which uses
GlkDOS/Allegro, or only the builtin font will be available.

If you wish to distribute a modified font datafile, it is requested that you
leave the standard fonts in their original order to minimize user confusion.

Even better, if you design a new font that works with GlkDOS, send it to
the author for inclusion in the main distribution.

( Aside: Unless it's broken, I'll do it. Promise.
)

4.3 Graphics
 GlkDOS/Allegro (glka) supports the full suite of graphics capabilities
 promised under, as well as the sglk graphical extensions.

 GlkDOS's graphics support has the following limitations:

  * Graphics window sizes are not exact.
     GlkDOS/Allegro will pad the size of a graphics window to the next
     even character-sized unit. This ensures that no "dead space" occurs
     in adjacent text windows.
( Aside: That's not the real reason
  the real reason is that the curses version of GlkDOS measures the screen
  in character-units rather than pixels. In order to use the same (tested,
  documented) code for both versions, I opted to pad the graphics window.
)
     You will always get _at least_ as much space
     as you request, if it's possible, but you will more often than not get
     slightly more space. The extra space is fully usable, and will
     be returned by reading the window's size attributes. Alternatively,
     you can always safely ignore this space and it will serve as a
     visible boundary to the window.
  * Margin-aligned images are not quite accurate.
     Text does not "flow around" margin aligned images quite the way it
     should; left-aligned images are rendered as inline-up at the
     beginning of a line of text. Right-aligned images appear at the right
     margin on a line of their own.
( Aside: Margin-aligning images is HARD.
)
  * window_flow_break is unimplemented. because of the way aligned images
    are shown, the newline which prefaces a margin aligned image will
    always cause the image to be alighed properly, so the cascade effect that
    the spec warns of cannot happen.
  * Transparency in PNG images is not supported. My PNG library doesn't handle
    it, so neither do I.


4.4 International Keyboard support
 Allegro will translate the keyboard for Non-QWERTY/US keyboards, with the
 help of the International Support Package available from the GlkDOS
 distribution site.  It is necessary to alter the allegro config file to
 reflect the keybaord used, or Allegro will assume that the keyboard is
 a US/QWERTY.

 This package superceeds the now-obsolete -dvorak option.

5 Mouse Support
 GlkDOS should support any reasonable mouse with an allegro-compatable or
 INT33 driver (that is, a DOS mouse driver; if you can generally use your
 mouse in DOS, you can use it in GlkDOS) There are no options relevant to
 the mouse itself. A mouse pointer is displayed only when mouse input
 is pending in some window.

 The mouse is not supported in GlkDOS for Unix.

 The gestalt MouseInput selector will correctly identify whether or not the
 mouse is accessable.

 Mouse clicks *ONLY* trigger MouseInput events. They ARE NOT used for
 selecting Hyperlinks.

Version History...
( Aside: I pretty much allocate a new version number whenever I feel like it.
  As of 0.9.1, even-middle-number versions specify developmental releases.
  Odd numbers specify "production" releases. The first number is the major-
  version number of the GLK it supports (so it'll become 1 whenever Glk itself
  does, or when I reach version 100, whichever comes first) The last digit
  is supposed to represent minor features or bug fixes, but I might shoehorn
  a few in order to make the major version numbers work out right.
  Also, I wasn't really keeping track of changes from version 6 back, so I
  pretty much just made up the numbers below that. version 0.1.1 was called
  "GlkTerm 0.7.2/DOS DJGPP port 0.1"
)
0.19.1: Mouse support & underlying cscr functionality
0.18.6: Reordered cscr modules for readability
0.18.5: Undocumented the obsolete -revquote option.
0.18.4: Fixed style_measure and style_distinguish to be window-specific
0.18.3: Revamped color support; the background of each window is now the
         glk background (style_Normal or the default) at the time of
         window creation. Thanks to Adam Cadre for getting this method
         instatutionalized as the de facto practice.
0.18.2: Curses module rewritten to not use curses's background mechanism
         This is a touch clumsier, but gets rid of its annoying habit of
         fiddling with the intensity bits on text that shouldn't be
         thusly adjusted. This does result in slightly eccentric coloration
         of the message line, but you can't have everything.
0.18.1: Updated the dispatch layer
        Added GLKFILE to the make.*
0.17.1: Added the custom makefile generator.
0.16.1: Upgraded to glk 0.6.1
         SoundMusic and GraphicsTransparency gestalt selectors
         stylehint_Reverse
0.15.2: Added documentation to cscr
        Removed redundant cscr functions
        Optimized cdos a little more
0.15.1: Added customizable keybindings
        Added PC-BIOS accelerated version
0.14.3: Added dvorak support under allegro (kludgy)
0.14.2: Improved color mechanism
0.14.1: Provisional unix retroport
0.13.4: Added cncurses.c, unix/ncurses output api
0.13.3: removed cscr's dependancy on curses.h for keybindings.
0.13.2: Fixed a bug in echo_to_link that only manifests in linux
0.13.1: Graphics in textbuffer windows
0.12.5: New cscr naming conventions
0.12.4: Removed redundant cscr functions
0.12.3: improved listbox to process directories from the 'to' line
        Added scrolling markers to the listbox
        added autojump to the listbox
0.12.2: source code cleaning
0.12.1: File list box
        sglk extensions
0.11.1: Graphics
        Improved file naming conventions, glkdos_set_basename
        Simplified the color support mechanism by complicating cscr.
         Should perform slightly better.
0.10.7: Graphics windows
0.10.6: rewrote key handler, added arbitrary key and exec-command
0.10.5: Added user macros
0.10.4: More copy buffer keys
0.10.3: Shell to dos added
0.10.2: Added copy buffer
0.10.1: Added hyperlink support
        Source code restructuring
        Removed some unused code
        Added conversion of proportional fonts
0.9.2 : Added generic makefile
0.9.1 : Upgraded GlkDOS to glk 0.6.0
0.8.4 : Improved the version information, tidied up the makefile
0.8.3 : Added font support
0.8.2 : Fixed various color bugs
0.8.1 : Added Allegro graphics capability. Major source revision should
        increase portability (All screen output is now collected in a
        single file. Porters need only implement the declarations of
        cscr.h to change the output API. ccurses.c implements output
        via curses, and calleg.c implements it via allegro)
0.7.3 : Fixed a bug which prevented timer events from occuring correctly
0.7.2 : Fixed an oversight that made it impossible to compile glkdos without
        a modified libc (name collision between curses and conio)
0.7.1 : Fixed stylehint support to comply with glk specification
        Added configuration file support
        Added makefile options to build without sound
0.6.1 : Fixed a bug in the sound system
0.5.2 : Enhanced the runtime menu
0.5.1 : Added run-time configuration menu
0.4.1 : Added partial latin1 support
0.3.2 : Added jgmod sound support
0.3.1 : Added Allegro sound support
0.2.3 : Remapped special keys to DOS/Win conventions
0.2.2 : Added high-resolution timer
0.2.2 : Added color
0.1.1 : Initial release, essentially a straight port of glkterm



