README File for Frame Product Support of ToolTalk
-------------------------------------------------

This README file explains Frame products' support of the ToolTalk protocol for
 integration of X Window System applications. It describes how to set up
 Frame products to work with other applications by sending and responding to 
ToolTalk messages.

This file explains how to integrate Frame products with the OpenWindows on Sun
Microsystems workstations. ToolTalk is supported on several other platforms.
 Check your operating system documentation for more information on ToolTalk
for your specific platform. Check application documentation to find out
whether a specific application supports ToolTalk.


TOOLTALK BACKGROUND
-------------------

ToolTalk messages allow applications (tools) to communicate with each other.
Because ToolTalk is a standard and is portable to many platforms,
application developers don't need to write special code to integrate with
 other applications.  Any application that supports ToolTalk can work with
other ToolTalk applications. In the past, Frame products relied on proprietary
messaging systems to integrate text and graphics (known as insets) from other
applications. This method required special programming for each
integrated application. 


FRAME PRODUCT FILES FOR TOOLTALK INTEGRATION
--------------------------------------------

When you install a Frame product, the ToolTalk integration programs and
setup files are automatically installed. Follow the instructions in
"Installing Frame Products" to install the product and set up your path. 

The ToolTalk integration uses the following files:

FILE                            DESCRIPTION
$FMHOME/bin/fa.tooltalk         An API client that sends and receives ToolTalk
                                messages for Frame products.
$FMHOME/bin/fmtooltalk          A program that integrates Frame products 
                                with the OpenWindows desktop environment by
                                translating desktop actions (such as double-
                                clicking a file) to ToolTalk messages. It then 
                                sends those messages to fa.tooltalk.
 
Check to make sure that these files are installed, and that they are added
to your path before you start OpenWindows. (Changes that you make after
starting OpenWindows will not apply from session to session.)

In addition, the file $FMHOME/fminit/<UILanguage>/APIArea/apiclients 
(where <UILanguage> represents the user interface language) should contain the
following instructions for automatically starting the ToolTalk API client:

   <APIclient
      <Name fa.tooltalk>
      <CommandLine $FMHOME/bin/fa.tooltalk>
      <RPCVersion 1>
      <Description Handles ToolTalk message for Frame products>>      


THE TOOLTALK SERVICE DAEMON
---------------------------

The file /usr/openwin/bin/ttsession (the ToolTalk service daemon) should be
in your path and started immediately after you start OpenWindows. We 
recommend adding the command to start this program to your .xinitrc file.
(If it is not already running, the first ToolTalk message automatically 
starts ttsession.)


CLASSING ENGINE TABLE
---------------------

The OpenWindows Classing Engine table (cetable) contains the necessary
information for other tools to recognize and handle Frame file types.
It also specifies the list of ToolTalk messages that Frame products can 
handle. It should be installed as follows:

PATH                                    DESCRIPTION
$HOME/.cetables/cetables                User level installation
/etc/cetables/cetables                  System level installation
$OPENWINHOME/lib/cetables/cetables      Network level installation

Frame provides two versions of the cetables file. Both are in 
$FMHOME/fminit/<UILanguage>/APIArea/tooltalk.

The cetables file is the binary form of the table.  If you have not
customized your cetables file for other applications, you can simply 
copy this file to the appropriate directory.

The cetables.frame file is the ASCII form of the same table. If you've 
customized your cetables file, you can merge cetables.frame into the existing
file. See the following instructions. 


MERGING CETABLES.FRAME INTO AN EXISTING CETABLES FILE
-----------------------------------------------------

To merge the cetables.frame file with an existing cetables file:

1. Make a backup copy of the cetables that you plan to modify.
   
   If the new cetables file is damaged during the merging process, you can
   use the backup version. 

2. In a UNIX window, type the following command to convert existing cetables
   to ASCII format:

   ce_db_build <TABLE_TYPE> -to_ascii /tmp/cetables

   where <TABLE_TYPE> is one of the following options for the type of 
   cetable you want to change:
	
   OPTION           DESCRIPTION
   user             User level installation
   system           System level installation
   network          Network level installation

3. Remove obsolete entries.

   Use a text editor to edit the resulting file in /tmp/cetables.  
   Look for and remove entries that are related to Frame products  
   (grep for the keyword "frame").  When you remove an
   entry, be sure to remove the parentheses in matching pairs.

4. Add the contents of the cetables.frame file to the ASCII file  
   by typing the following command:

   cat cetables.frame >> /tmp/cetables

5. Convert the merged ASCII file into the binary cetable format. 
   Type this command:

   ce_db_build <TABLE_TYPE> -from_ascii /tmp/cetables

6. To make the change take effect, exit and restart 
   OpenWindows. 



SPECIFYING THE FRAME PRODUCT NAME
---------------------------------

The cetables use a variable, FM_PROGNAME, to represent the Frame product to
start in order to execute the tooltalk messages received by fa.tooltalk.
Before you start OpenWindows and the ttsession process, you must define this
variable as the Frame product you intend to use. Enter one of the following
lines to your .login, .cshrc, or .profile file:

FOR THIS PRODUCT           ENTER THIS LINE IN             ENTER THIS LINE IN
                           .LOGIN OR .CSHRC               .PROFILE (BOURNE 
                           (C SHELL)                     OR KORN SHELL)
FrameMaker                 setenv FM_PROGNAME maker      FM_PROGNAME=maker
International FrameMaker   setenv FM_PROGNAME imaker     FM_PROGNAME=imaker
FrameBuilder               setenv FM_PROGNAME builder    FM_PROGNAME=builder
FrameViewer                setenv FM_PROGNAME viewer     FM_PROGNAME=viewer

Also add the following line to the .profile file:

export FM_PROGNAME


TESTING THE TOOLTALK INTEGRATION
--------------------------------

To make sure that Frame products are interacting properly with ToolTalk, try
double-clicking on a document icon to start a Frame product, or try printing a
document by dragging its icon to the print tool. 
