source: trunk/third/motif/README-1.2.3 @ 12415

NOTE: OSF/MOTIF IS LICENSED SOFTWARE.  SOURCE AND OBJECT CODE IS NOT
TO BE DISTRIBUTED TO THIRD PARTIES EXCEPT AS PROVIDED BY THE TERMS OF
YOUR LICENSE AGREEMENT.  PASSIVE DISTRIBUTION TO UNIDENTIFIED PARTIES,
SUCH AS MAKING FILES AVAILABLE FOR UNRESTRICTED ELECTRONIC FILE
TRANSFER, IS STRICTLY PROHIBITED BY THE LICENSE.

THESE RESTRICTIONS APPLY TO ANY PARTY TO WHOM THE SOFTWARE HAS BEEN
DISTRIBUTED.

The Purpose of This Release

        This patch release contains approximately 425 bug fixes for
        Motif 1.2.

        The reference platforms for Motif 1.2.3 are the HP 9000/720
        running HP-UX 9.01 and an Intel 486 workstation running OSF/1
        1.2.

        OSF encourages the reporting of all bugs found in OSF/Motif
        regardless of the platform or hardware configuration in which
        the bug is found.  However, OSF will commit to accept (and
        repair according to priority) only those bugs that can be
        replicated on the current reference configurations.  A list of
        known bugs can be found in the OPENBUGS file and a list of
        bugs fixed in this release can be found in the FIXEDBUGS file,
        both on the release tape.

        Since this is a general availability product release, it has
        undergone the full quality assurance cycle at OSF.


Installing This Release

        OSF/Motif 1.2.3 is provided on magnetic tape, in tar format.

        This release is made up of a "sparse tree" of files that have
        changed since patch release 1.2.2. The new versions of the
        files should replace the corresponding Motif 1.2.2 versions of
        the files in your source tree, and then the Makefiles and then
        the binaries should be rebuilt.

        Before you install this release, you must have installed patch
        releases 1.2.1 and 1.2.2.  If you received releases 1.2.1
        through 1.2.3 combined on a single tape, and followed the
        installation instructions, you will have installed all three
        releases in the right order.

        To install the entire contents of the tape, create the
        directory that you want to be the root for the sources, make
        that the current directory, load the tape into the tape drive,
        and issue this command:

                tar xvf device_name

        After the tape is unloaded, you can use, for example, cp -f
        command to copy the sources from the current directory into
        your source tree.

        This release creates four new files: ./README-1.2.3, ./bindings/pc,
        ./lib/Mrm/MrmIswap.c and ./lib/Xm/sharedlib.c.  If you are
        using a symbolic link tree, you will need to create new links
        for them. Also ./lib/Xm/LabelDIcoI.h and ./lib/Xm/ListDIconI.h
        files were defuncted; you may wish to remove these files from the 
        source tree.
        
        If you have any problems when installing the tape, call the
        OSF/Motif support desk at (617) 621-8990.


Summary of Changes in this Release

        All changes made in this release are fixes for reported bugs.
        For details on the bugs fixed, see the file CLOSEDBUGS on this
        tape.


Bug Lists

        On the tape there are two files, OPENBUGS and CLOSEDBUGS,
        which contain, respectively, the list of all bugs from any
        version of Motif not yet closed, and all bugs from any version
        of Motif fixed in the 1.2.3 release.


Overview of the Motif Directory Structure

        This section describes the Motif directory structure.

        This file, ./README-1.2.3, summarizes the contents of the top
        level directories in the directory structure, briefly
        describes the build process, and describes bug reporting
        procedures.

        The file ./BUGREPORT is a bug report template.

        The file ./OPENBUGS contains all open bugs.

        The file ./CLOSEDBUGS contains all bugs fixed in this
        release.

        The directory ./X11R5 contains official MIT patches for
        Version 11 of the X Window System.  The patches to the Xlib
        and the X Toolkit Intrinsics are required for building and
        running Motif 1.2.3.  The file ./X11R5/README describes the
        patches and how to apply them to your X sources.  For more
        information, refer to the section "Building Motif On Your
        System."

        Note:  MIT, not OSF, is responsible for support
               of any patches in the ./X11R5 directory.
               We provide them unsupported for the
               convenience of users who might not yet
               have received the latest sources.

        The directory ./doc contains the full sources for the Motif
        documentation.  No updates for documentation are provided in
        this release.

        The directory ./lib contains the toolkit library and resource
        manager library:

           * ./lib/Xm contains the Motif widget library.

           * ./lib/Mrm contains the Motif resource manager
             library used with the uil compiler.

        The directory ./bindings contains vendor-specific bindings for
        virtual keysyms.  For more information on virtual bindings,
        see the file ./bindings/README or the VirtualBindings(3X)
        manual page in the OSF/Motif Programmer's Reference.

        The directory ./clients contains the Motif window manager, the
        User Interface Language (uil) compiler, and the xmbind client:

           * ./clients/uil contains the uil compiler and the
             callable uil interface library (libUil.a).

           * ./clients/mwm contains the Motif window manager.

           * ./clients/xmbind contains a client used to set up
             the bindings between keys on the keyboard and Motif
             virtual keys.

        The directory ./demos is an unsupported directory.

        The directory ./tools contains a single tools subdirectory,
        wml, with the Widget Meta-Language (WML) facility.

        The directory ./config contains configuration files.

        The directory ./tests contains regression tests.  No updates
        for tests are provided in this release.


Where to Get Help

        To report problems with this release, please complete the OSF
        Problem Report in the file ./BUGREPORT and mail to:

          motif-defect@osf.org or uunet!osf.org!motif-defect

        motif-defect is an alias to a person at OSF who is in charge
        of receiving and dispatching bugs reported against the latest
        released version of OSF/Motif.

        Discussions concerning the technology in this release can be
        directed to the mailing list:

          motif-talk@osf.org or uunet!osf.org!motif-talk

        If you want to be added to the motif-talk mailing list, please
        send your email address to:

          motif-talk-request@osf.org or uunet!osf.org!motif-talk-request

        Please include your company name and Motif license agreement
        number.

        Licenses with full support contracts can also call OSF for
        help.  The service number is 1-617-621-8990, and support is
        available between 8:30 AM and 5:00 PM United States Eastern
        time, Monday through Friday.  You can obtain an OSF/Motif
        software support contract for support of released versions of
        OSF/Motif by contacting OSF Direct Channels at 1-617-621-7300.


Building Motif for Your System

        This release requires no changes in the build process.  Please
        refer to the Release Notes, Chapter 6, or the section
        "Building Motif for Your System" in the README-1.2.1 file, for
        more information.

        Be sure to read the section "Tailoring the Build Process" for
        information on how to configure your system before building
        Motif.  This section includes instructions for patching your
        X11R5 sources.  The section "Motif Makefiles" describes the
        steps you should follow to build the source, including
        building the Makefiles, after you have tailored your build
        configuration.  The section "The Motif Build Tree" indicates
        how the build proceeds once it has begun.

        Motif 1.2.3 uses X11R5 Xlib and X Toolkit Intrinsics
        libraries.  The versions of these libraries used to build
        Motif must have the MIT fixes 1-25, supplied in the ./X11R5
        directory, applied to them in order for Motif to build and run
        properly.  Please read the README in that directory for more
        discussion of the patches.


Readiness for Certification

        The Motif Validation Test Suite (VTS 1.1) was run and passed
        on the following configurations:

           * Intel 486 running OSF/1 1.2, MIT R5 server

           * HP 9000/720 running HP-UX 9.01, R5 server

           * SPARCstation 2 running SunOS 4.1.2, R4 server


Making Client Makefiles with imake

        This section contains new information, written in response to
        several questions from licenses.

        Clients in the X11R5 release use the xmkmf command to build
        Makefiles.  This command executes imake, and usually sets the
        UseInstalled imake variable appropriately.

        Motif uses the UseInstalled flag, and also uses the
        UseInstalledMotif flag independently.  Thus, in general, the
        xmkmf command cannot be used for Motif clients, because of the
        need to consider the UseInstalledMotif flag separately.  Since
        xmkmf is a simple script that calls imake, it is easy to
        construct the proper call to imake using the following rules.

        In these instructions, replace {MTOP} by the toplevel
        directory with the Motif source tree, and {XTOP} by the
        toplevel ("mit") directory with the X source.  If imake has
        been installed, it is assumed that the directory containing it
        is in your PATH, and {CONFDIR} is the X configuration
        directory (usually /usr/lib/X11/config).

        When needed, the imake variables XTop and MTop are normally
        set in your site.def (to {XTOP} and {MTOP} respectively);
        however they may also be set with additional -D arguments to
        imake.

        1. With both X and Motif in their source trees, ensure the
        imake variables XTop and MTop are set, and use:

            ${XTOP}/config/imake -I{MTOP}/config

        2. With Motif in its source tree, and X installed, ensure MTop
        is set, and use:  

            imake -I{MTOP}/config -DUseInstalled

        3. With both Motif and X installed, use:

            imake -I{CONFDIR} -DUseInstalled -DUseInstalledMotif

        The configuration files currently are not designed to work
        with Motif installed and X in its source tree.

        Here is a simple Imakefile, for a single client in its own
        directory:

            LOCAL_LIBRARIES = XmClientLibs
                    DEPLIBS = XmClientDepLibs
                       SRCS = client.c
                       OBJS = client.o

            MSimpleProgramTarget(client)
            InstallProgram(client,$(BINDIR))
            DependTarget()

        Or, for a client that uses uil/mrm, replace the library
        definitions by MrmClientLibs and MrmClientDepLibs, and also
        use:

            MSimpleUilTarget(client)

        to build the client and uid file.  Look in the "demos"
        directory for more examples.


Configuration Variable Changes

        Changes have been made to the variables used by imake since 
        Motif 1.2, and some of them may affect users' Imakefiles.

        If the imake variable "DontBuildMotifDemos" is defined, the
        Motif demos are not built or rebuilt.  You must remake the
        toplevel Makefile for this to come into effect.

        The imake variable UilFlags contains site-specific flags for
        the uil compiler.  This becomes the make variable UILFLAGS.
        The make variable LOCAL_UILFLAGS (and LOCAL_UILFLAGS_1, etc)
        can also be used in Imakefiles.

        The make variable UIL_INCLUDES now correctly names the
        standard directory for uil include files.  Command lines that
        execute the uil compiler will have a -I option added referring
        to this. MSimpleUidLocaleTarget rule was created.

        Several changes were done to better support shared libraries.

        We have rewritten the hp.cf file, introducing several new
        imake variables.  Please read the file for details.


Note regarding Xt translations fix in patch 25 to X11R5


        Due to a bug fix in the Xt translation code (patch 25 to X11R5), 
        the translations in Xt are now very strictly handled, instead 
        of accepting any possible match. Because of this, in certain 
        platforms, QATS and the Motif VTS are not behaving as they did 
        in the past. This is due to incorrect assumptions made in the 
        translations for certain keyboards, for example, in those keyboards 
        in which the arrow keys are defined in the keypad. We believe that 
        this change will also influence additional Motif applications.

        A quick solution to this problem consists of creating a file 
        that is passed to the utility xmodmap and that redefines the 
        bindings for the keys in question. The following is an example of 
        what the file might look like:

!
! Always force:
!   KP_2 = Down
!   KP_8 = Up
!   KP_4 = Left
!   KP_6 = Right
!
keycode 120 = Down
keycode 76 = Up
keycode 98 = Left
keycode 100 = Right

        This file changes the bindings for the keypad keys that match the
        arrow keys so that only the arrow keys and not the keypad numbers
        are produced. This allows the application to use modifiers with the
        arrow keys.