source: trunk/third/motif/README1.2.5 @ 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 one hundred (100) bug 
        fixes for the OSF/Motif 1.2 source code base. The number of
        Change Requests (CRs) resolved for this release is approximately
        one hundred and fifty (150).  All fixes were implemented in the
        ./lib/Xm source code.

        This patch release contains source code addressing defects reported
        against versions up through Release 1.2.4.  In addition, this patch
        release includes new functionality and enhancements to converge the
        OSF/Motif source code with the Common Desktop Environment (CDE) 1.0
        version of Motif.  Please refer to the section of this document
        entitled "New Functionality and Enhancements to support the
        Common Desktop Environment (CDE)".

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

        Motif 1.2.5 is 64-bit clean using the DEC Alpha OSF/1
        V1.3 Rev. 111 as the test platform.

        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 CLOSEDBUGS file,
        both on the release media.

        In addition, OSF has added a list of bugs that we do not intend 
        to fix.  These bugs can be found in the WILLNOTFIXBUGS file.  In 
        the majority of cases, the reason we do not intend to fix these 
        bugs is because doing so would create larger problems for our
        Motif Software Support subscribers.

        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.5 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.4. The new versions of the
        files should replace the corresponding Motif 1.2.4 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, 1.2.2, 1.2.3 and 1.2.4. 

        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, the cp -f
        command to copy the sources from the current directory into
        your source tree.


        These release creates the following new files under ./lib/Xm 
        directory:

        ColorObj.c
        ColorObj.h
        ColorObjP.h
        DtHash.c
        Hash.c
        HashP.h 
        IconFile.c
        IconFile.h
        IconFileP.h
        IconG.c
        IconG.h
        IconGP.h
        ImageCachI.h
        LabelDIcoI.h 
        ListDIconI.h
        TemplateB.h
        TemplateBP.h
        XmMsgI.h
        Xm.msg
        XpmCrDataFI.c
        XpmCrDataFP.c 
        XpmCrIFData.c
        XpmCreate.c
        XpmData.c
        XpmHashtable.c
        XpmMisc.c
        XpmParse.c
        XpmRdFToI.c
        XpmRgb.c
        XpmScan.c
        _DtHashP.h
        _VirtKeysI.h
        _xpmI.h
        _xpmP.h
        regexp.c
        regexpI.h

        If you encounter problems installing this release from the
        distribution media, please contact the OSF 
        Motif software support help desk:
        
                Telphone:       (617) 621-8990.
        
                Email:          motif-defect@osf.org
                                        or
                                uunet!osf.org!motif-defect

                Web URL:        http://web2.osf.org:8001



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.


Overview of the Motif Directory Structure

        This section describes the Motif directory structure.

        This file, ./README-1.2.5, 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 file ./WILLNOTFIXBUGS contains all bugs that OSF will 
        not fix.

        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.5.  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:  No new X11R5 patch is needed for this release.
               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. A new file, CDElibXm.ps, is postscript format
        document.  This document was developed and donated by external
        CDE/Motif Pre-Structured Technology (PST) providers.  It 
        describes the new functionality and enhancements provided
        in this release to support the Common Desktop Environment (CDE).

        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 OSF.  Problem
        reports can be electronically sent to OSF via email or our World
        Wide Web (WWW) interface:

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

                                or

                        http://web2.osf.org:8001        

        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.

        Licensees with full support contracts can also call OSF for
        help.  The service telephone number is 1-617-621-8990, and 
        support is available between the hours of 8:30 AM and 5:00 PM 
        United States Eastern time, Monday through Friday.  

        To obtain a OSF/Motif software support contract for support of 
        released versions of OSF/Motif, you can contact OSF Direct 
        Channels:

                Telephone:       (617) 621-7300
                
                Email:           direct@osf.org
                                        or
                                 uunet!osf.org!direct

                Postal Address:  OSF Direct
                                 11 Cambridge Center
                                 Cambridge, MA 02142
                                 USA

Building Motif for Your System

        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.5 uses X11R5 Xlib and X Toolkit Intrinsics
        libraries.  The versions of these libraries used to build
        Motif must have the MIT fixes 1-26, 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.


        At OSF we have found the following sequence of commands
        to be most convenient:

        cd $MTOP
        make Makefile 
        make Makefiles 
        make includes                   
        make depend
        make -k
        
        The above "make includes" step is critical, otherwise the old
        header files will still be included, potentially resulting in
        compiler errors and undefined results.

        You can perform the entire make process by issuing one of the
        following commands from the top of the Motif source tree:

        make World "BOOTSTRAPCFLAGS=-IXTop/X11"

        or

        make Everything "BOOTSTRAPCFLAGS=-IXTop/X11"

        The difference between these commands is that the World
        target removes all object files from the tree.  You may
        prefer to use make Everything after changing some
        settings in the configuration files.

        To install Motif libraries, clients, and header files,
        use the command make install from the top of the Motif
        tree.


Readiness for Certification

        The Motif Validation Test Suite (VTS) version 1.1.1 was used to 
        verify the quality of this release 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, R5 server

           * DEC Alpha running DEC OSF/1 V1.3 Rev. 111, R5 server


New Functionality and Enhancements to support the Common Desktop 
Environment (CDE)

        This release includes new functionality and enhancements to
        converge OSF/Motif 1.2 source code with the Common Desktop 
        Environment's version of Motif. 

        New Functionality:

        * Complete localization of toolkit error messages
        
        * XmGetPixmap() and XmGetPixmapByDepth() use the environmental variable
          XMICONSEARCHPATH or XMICONBMSEARCHPATH as the icon search path. If
          neither of these variables is set, then they use XBLANGPATH, which
          is the OSF/Motif behavior.


        Enhancements:

        * Optionally allowing mouse button 2 on a three-button mouse to be used
          to extend the current selection. This is equivalent to the OPEN LOOK 
          Adjust function.

        * Allowing Tab to be used to move through a group of PushButton widgets
          and gadgets, ArrowButton widgets and gadgets, and DrawnButton widgets 
          and gadgets.

        * Allowing mouse button 3 to activate a CascadeButton menu.

        * Providing three new resources{pathMode, fileFilterStyle and 
          dirTextLabelString} for the XmFileSelectionBox widget.

        * Allowing multiple virtual key bindings.

        * Providing visual enhancements.


        Each of the preceding enchancements can be controlled by a resource:
        either a widget resource or an application-wide resource. The
        default values for this resource provide behavior and API's that are
        identical to that of OSF/Motif 1.2.4. In addition, each of the 
        enhancements has a unique "ifdef" that can be set in the 
        ./lib/Xm/Imakefile.

        
XmString data size fix

        This fix (CR 10079) improves backward compatibility with applications 
        built with previous versions of the shared library.

        Add the flag -DXM_STRINGS_1_2_2_STATE to the DEFINES macro in 
        ./lib/Xm/Imakefile to enable this fix.