=======================
Protermcap Builder 1.0a
=======================

Introduction
------------
The Protermcap Builder is meant to do the following: 

1) Assist PROGRESS Version 7 TTY end-users to develop PROGRESS terminal 
entries for terminals that are not currently supported in the 
$DLC/protermcap file.

2) Allow users to modify existing entries from $DLC/protermcap or other 
file.


Several assumptions are made for the use of this application when the 
objective is to create a new entry for a terminal that is not currently 
supported in $DLC/protermcap:

1) The application must be run with a terminal that is supported in 
$DLC/protermcap.

2) It is strongly recommended that the user have the terminal manual for 
the terminal they are writing an entry for. This is to ensure that all 
necessary terminal capabilities and their escape sequences are known and 
can be entered into the application if they cannot be provided from some 
other source.

3) The user should have the escape sequences for the Function Keys, if 
any, and keys such as Page-Up, Page-Down, Home, Delete, Backspace, ...


A quick way to get the necessary escape sequences for specific keys is 
to use the 'vi trick'. 

1) Run UNIX vi on the terminal you are writing a terminal entry for. No 
file name is necessary.

2) Press 'i' to start insert mode.

3) Press 'ctrl-v'. (See '^' on screen)

4) Press the key you want the escape sequence for. You should see it on 
the screen. If you do not get a sequence, then either the key does not 
send anything, or you must use the terminal documentation to find out 
what the sequence is.

For example, when vi trick is performed with a wyse60 terminal for the 
F1 key, vi displays ^A@ and goes to the next line, this means that the 
escape sequence is ^A@\r (where \r is a 'return'). For a vt100, hitting 
the PF1 key shows ^[OP , which also can be written as \EOP . For all 
intents and purposes, ^[ and \E are identical sequences for the ESC 
character.


How to run the Protermcap Builder
---------------------------------
The source code and required files reside in a directory called 
$DLC/src/proterm. 

Add this directory to your PATH. For example: 
PATH=$PATH:$DLC/src/proterm;export PATH.
Alternatively, you may want to copy the contents of the proterm
directory to another working directory and run it from there.

Create a new empty database called 'proterm' using the command: 
'prodb proterm empty'.

Start Progress with your new proterm database and load the .df
and .d's using the data dictionary.

Use the shell script called 'proterm' to run the application. It 
connects to the database called 'proterm.db', adds $DLC/src/proterm 
to your PROPATH and runs the first procedure called 'pt-main.p'.


Functionality
-------------
Create a New Entry:

A user can create a new terminal entry from scratch or with an existing 
terminal entry in termcap, terminfo or $PROTERMCAP as a starting point. 
The entry can then be modified/viewed/saved within the application.

Open an Entry:

A user can open and read in a terminal entry from $PROTERMCAP or another 
file. The entry can then be modified/viewed/saved within the 
application.

In both cases (New and Open), the application detects whether an entry 
has a 'tc' (or branch) to another entry and also attempts to read this 
entry from the same location. The application also maintains a disk file 
called termtype.imp which is a log of what is being imported into the 
Protermcap Builder when a terminal entry is being read in.

Save an Entry:

By default, the application saves the new/modified entry to disk with 
the name termtype.NEW, where termtype is the name of the terminal you 
specified when the entry was created/opened.

Save As:

Here, a user has the opportunity to change the termtype and title of the 
terminal entry currently in memory and write it out to a file name that 
the user specifies.


Creating a New Entry
--------------------
1) Press ENTER-MENUBAR and choose New from the Menu.

2) Enter the terminal type and title for this entry.

3) Select whether you want to create this entry:
     a) Manually - enter all terminal capabilities, key bindings and 
                   colors.
     b) With a base terminal - Use the entry of a terminal as defined in
                   termcap, terminfo or protermcap as a starting point.

   If the user chooses to create the entry manually, the user is brought 
   to a menu which allows the modification of the entry.

   If the user chooses to use a base terminal, the entry is read in from 
   the source specified.

4) Main Menu: The user can select from several selections to modify Key
   Bindings, Colors or Terminal Capabilities.

5) When all modifications are done, press ENTER-MENUBAR and select Save 
   or Save As. The Exit selection will also allow you to execute the 
   Save function before exiting the application.


Modifying an existing entry
---------------------------
1) Press ENTER-MENUBAR and choose Open from the Menu.

2) Enter the terminal type and the location to read it from, Protermcap 
   as defined by $PROTERMCAP or another file.

3) The entry is read in and the user is presented with the Main Menu, 
   where any modifications can be made.


Main Menu
---------
The user can elect to modify Keybindings, Colors or Terminal 
Capabilities of the entry currently being worked on. Selecting Preview 
allows the user to view what the Protermcap Builder has currently stored 
in memory.

1) Keybindings - This selection allows a user to view/define PROGRESS 
Key Function / Key Label mappings. For example, a user may want the 
PROGRESS 'GO' function to occur when a user presses 'CTRL-X' and 'F1'. 
Here is where these associations are maintained.

Upon selecting Keybinding, the user is asked what the ESC char is 
defined as for the terminal currently being defined. They may select '\E 
or ^[' (for most terminals), '\E[23~' (for VT terminals), or 'Other' and 
the user enters a different sequence.

If the default PROGRESS key functions, located in the 'v7kf' entry in 
$DLC/protermcap, were not read in by means of a 'tc=v7kf', the 
application will ask if the user wants to read them in. Accepting this 
is especially useful when defining a new entry manually. 

Finally, the user is presented with a screen which allows the browsing, 
adding, deleting and modification of Key Function/ Key Label pairs.

2) Colors - This selection allows a user to view/define PROGRESS color 
entries. A valid color entry consists of a Color number between 5 and 
127, a Foreground color, a Background color and the escape sequence.

Upon selecting Colors, the user can select a color number by moving the 
slider widget with the left and right arrow keys. If a definition exists 
for a color number, the selection lists for background and foreground 
colors are repositioned to these colors, if they are defined, and the 
escape sequence for the color definition appears below them. When a 
change is made by changing an entry or defining a new one, the user must 
selection the "Save" button to save it. Selecting the "Revert" button 
causes a definition to revert back to its state since the last "Save".

3) Terminal Capabilities - This selection allows a user to maintain 
escape sequences for the terminals' capability codes. These capabilities 
are definitions such as Cursor On, Cursor Off, Arrow keys, etc. The 
escape sequences for these capabilities can be found in the terminal 
manual, or if the user elects to start with the terminal entry from the 
termcap, terminfo or protermcap files.

Upon selecting Terminal Capabilities, the user can scroll the 
capabilities in the browser widget on the left and maintain the escape 
sequences on the right of the frame. The user must select the "Save" 
button to store the escape sequence with the Term. Function. Changes can 
be reverted to the last saved value by selecting "Revert". Note that 
those terminal capabilities that are Boolean, have escape sequences of 
blanks when Off and "<set>" when On.

4) Preview - This selection allows a user to view what the currently 
loaded terminal entry would like as it would be saved. Use the arrow 
keys and page up/down to view all the data. Selecting the "Close" button 
will return the user to the Main Menu frame.


How to Exit the Protermcap Builder
----------------------------------
Selecting Exit from the Menubar will exit the application. If a terminal 
entry is currently in memory, the application will display a dialog-box 
to warn the user and give them an opportunity to Save it before exiting.


Known problems
--------------
Colors may not be handled properly when reading in an entry. V7-type 
color entries may lose the 'color normal' part of their escape 
sequences. V6-type color entries are not supported at this time.

Does not yet support the Vermont Views termcap entries.
