The OSF/Motif Documentation

        The complete Motif documentation set is made up of the
        following documents:

           * AES User Environment Volume

           * OSF/Motif Programmer's Reference

           * OSF/Motif Programmer's Guide

           * OSF/Motif Release Notes

           * OSF/Motif Style Guide

           * OSF/Motif User's Guide

        These documents are contained in one of the major
        subdirectories ( ./doc ) of the OSF/Motif 1.2 tree.

        Note:  You can print out copies of these
               documents in either PostScript or ASCII
               format. Within each manual directory are
               the subdirectories Output/draft/ps and
               Output/draft/ascii.  These directories
               contain files that you can use
               immediately, without having to build the
               document from scratch.

               The files in the Output/draft/ascii
               subdirectories are intended primarily for
               screen display.  Some of these files
               contain long lines that may be truncated
               when you send them to a printer.

        Also included in this release is OSF's documentation
        tool package, the Documentation Tools Environment
        (DTE), which you can use to rebuild the documentation.
        The DTE is separate from the OSF/Motif offering and is
        not included in any OSF/Motif support, although we
        would appreciate any comments you have about it.  For
        most people, the formatted documents we have provided
        are sufficient, but we supply our working build
        environment for the few of you who may want to rebuild
        some or all of the documents.  In order to rebuild the
        documentation you must first build the DTE.  Building
        the DTE is described in the section "Building the DTE"
        below.  If you intend to work extensively with the
        documentation and the DTE, familiarize yourself with
        the complete documentation contained in the directory
        ./doc/DTE/tools/dtedoc/dte_user.gd.

   Structure of the Documentation Directory Tree

        The ./doc directory contains the following files and
        directories:

        COPYRIGHT       This file contains a general copyright
                        notice for the OSF/Motif documentation
                        set.

        DTE             This directory contains the sources and
                        documentation for the DTE.

        Makefile        This makefile uses the DTE to build the
                        OSF/Motif documentation set.  This
                        makefile expects the DTE to be built
                        and in your path.  It has the following
                        make targets:

                        all         builds all books in
                                    PostScript and ascii with
                                    book-format.

                        ps          builds all books in
                                    PostScript.

                        ascii       builds all books in ascii.

                        clean       removes the Sync
                                    directories from each of
                                    the manual directories.
                                    These directories hold page
                                    number synchronization
                                    information and should be
                                    removed when a documents
                                    file structure changes.
                                    They are automatically
                                    regenerated by the book-
                                    format command of the DTE.

                        clobber     removes the Sync and Output
                                    directories from each of
                                    the manual directories.
                                    The Output directories
                                    contain output ready for
                                    printing.  They are
                                    automatically regenerated
                                    by the book-format command
                                    of the DTE.

        README          This file contains a description of the
                        contents of the ./doc directory.

        aes             This directory contains the source and
                        output files for the AES User
                        Environment Volume.

        man             This directory contains the source and
                        output files for the OSF/Motif
                        Programmer's Reference.

        programGuide    This directory contains the source and
                        output files for the OSF/Motif
                        Programmer's Guide.

        releaseNotes    This directory contains the source and
                        output files for the OSF/Motif Release
                        Notes.

        styleGuide      This directory contains the source and
                        output files for the OSF/Motif Style
                        Guide.

        usersGuide      This directory contains the source and
                        output files for the OSF/Motif User's
                        Guide.

        Some source directories contain a subdirectory called
        graphics.  This directory contains figures for the
        document in PostScript format.  These figures have been
        included in the PostScript output for the manuals in
        this release.  In order to print any of the PostScript
        figure files individually, you need to run a script to
        convert the format.  See the section "Printing
        PostScript Figures" below for more information.

   The man/pointer Directory

        The man directory, which contains the files for the
        OSF/Motif Programmer's Reference, contains a
        subdirectory called pointer.  This directory contains
        pointer files needed on machines without longname
        support.  The pointer files exist to help users resolve
        name conflicts when two manpage names truncate to the
        same name.

        You should install these pointer files into your
        manpage directory so that when you enter man with an
        ambiguous file name you get information from the
        pointer file directing you to an unambiguous name.  The
        pointer files are not needed on machines with longname
        support.

   Building the DTE

        To build and use the DTE you need the following:

           * Approximately 3.5 megabytes of free local storage.

           * A Documenter's Workbench package, including the
             following UNIX system commands:

                - Text processing tools:

                     - nroff

                     - troff

                     - pic

                     - tbl

                     - eqn

                     - neqn

                     - eps (or another PostScript
                       postprocessor.)

                     - tmac directory files (or other directory
                       files); these include the mm and man
                       packages.

             In most cases the following commands are all that
             is needed to build the tools:

             cd /root_path/doc/DTE/tools/src
             make TOP=/root_path/doc/DTE/tools/src MACHINE=`machine` install

             To use the documentation tools, include the
             directory:

             ./doc/DTE/tools/bin/`machine`

             in your path, and set the environment variable
             DTE_LIBDIR to

             ./doc/DTE/tools/libdata

             Note:  The character ` in the commands
                    above is a grave accent or "back
                    quote."

             The makefiles use the makefile variable InstallCmd
             to specify an installation program.  The value of
             InstallCmd is passed down by any makefile to lower
             level makefiles that it invokes.  For example, if
             InstallCmd is set to install, it will use install
             for any programs installed at that level, or at
             lower levels invoked during that execution of
             make.  InstallCmd can be set by editing the
             topmost DTE makefile, or specifying a value for
             InstallCmd on the command line.  The default value
             for InstallCmd is cp.

             We also provide a variable that specifies the make
             command to be used when a makefile needs to invoke
             a lower level makefile.  The variable is MAKE and
             its default value is make.

             The makefile variable TOP specifies the top of the
             tree where the installed DTE will reside.  This
             includes the bin, man, and libdata directories.
             This should always be specified on the command
             line, or the topmost DTE makefile should be
             edited.  The default value for TOP is /tmp/DTE,
             which will at least allow the DTE to be built
             (although it will probably not be installed where
             you want it).

             A more detailed description of the build process
             for the DTE is provided in the DTE subdirectory
             ./doc/DTE/tools/dtedoc in the files dte_build.ps,
             dte_build.sml, and dte_build.txt.

     Long File Names

        The names of some files in the DTE subdirectories are
        more than 14 characters long.  Some of these names are
        not unique to 14 characters.  If your system does not
        support file names longer than 14 characters, you may
        need to rename and reinstall these files, and you may
        need to change references to these files in the DTE
        Makefiles and Description files.  Following are the
        files with names longer than 14 characters:

        ./doc/DTE/tools/src/dte/ifdef-filter/filter_driver.c
        ./doc/DTE/tools/src/dte/ifdef-filter/site_specific.c
        ./doc/DTE/tools/src/dte/ifdef-filter/site_specific.h
        ./doc/DTE/tools/src/dte/ifdef-filter/tests/ifexpressiontest
        ./doc/DTE/tools/dtedoc/style.gd/ch02.10int_ex2.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.11ds_ex.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.2refintro.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.3tempintro.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.4comm_temp.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.5int_temp.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.7comm_ex.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.8comm_ex2.sml
        ./doc/DTE/tools/dtedoc/style.gd/ch02.9int_ex.sml

   Rebuilding the Documentation

        For detailed information on using the DTE and Semantic
        Markup Language (SML) macros, with which all OSF
        documents are formatted, please read the Documentation
        Tools Environment User's Guide and Reference, located
        in the directory:

        ./doc/DTE/tools/dtedoc/dte_user.gd

        This section contains only a very brief overview.  In
        most cases all that is needed to build the OSF/Motif
        books is:

        cd /root_path/doc
        make LIBDIR=/root_path/doc/DTE/tools/libdata all

        To rebuild an individual document, familiarize yourself
        with the book-format command by reading the appropriate
        sections of the Documentation Tools Environment User's
        Guide and Reference.  In general, you must change to
        the appropriate directory and specify book-format with
        or without options, with the parts of the document you
        want to build specified as arguments.  These parts are
        listed in the document's Description file.  For
        example, to build a PostScript version of Chapters 2
        and 4 of the OSF/Motif Programmer's Guide, enter:

        cd ./doc/programGuide
        book-format ch02 ch04

   Installing the Reference Pages

        The DTE includes a program, install-ref, that installs
        the reference pages delivered with this release.  Not
        only does this program properly install the SML based
        man pages on your system, but it also allows you to do
        the following:

           - Expand filenames for systems with longname support
             using the -expand option.

           - Reorganize the wide widget resource tables to fit
             better on an 80 column display using the -
             hacktables option.

           - Reorganize the wide widget resource tables to fit
             better on an 80 column display, but only when
             processed with nroff, using the -duptables option.
             This option allows systems that use the same
             reference pages source files for both troff and
             nroff based processing to work properly with both.

        These options and other options to this program are
        fully described in the README file in the directory
        ./doc/DTE/tools/src/installref.  To install the
        OSF/Motif reference pages with reorganized widget
        resource tables on a system that supports longnames,
        enter the following commands:

        cd /root_path/doc/DTE/tools/src/installref
        install-ref -hacktables -expand -offering motif -insert -smart \
        -doc /root_path/doc \
        -man /man_destination \
        -sml /root_path/doc/DTE/tools/libdata/macros

        where man_destination is the directory where you want
        to install reference pages.

        Note:  The install-ref command installs files in
               the destination directory with the same
               file types that they have in the source
               directory.  The names of Motif reference
               page files typically end with the
               character X, and this results in file
               types such as .1X, .3X, and .5X.  Some
               versions of the man command do not
               recognize files whose types differ from
               the traditional man section numbers.  If
               your man command has this limitation, you
               must rename the Motif reference page
               files, removing the final X.  You can
               either rename the Motif source files
               before installing the reference pages or
               rename the installed files after
               installing the reference pages.

   Including PostScript Figures

        Three of the documents provided with OSF/Motif 1.2 (the
        Programmer's Guide, Style Guide, and User's Guide)
        include figures in PostScript format.  These PostScript
        files reside in a graphics subdirectory beneath the
        source text files for each book.

        These files are included directly into the PostScript
        output for each manual using the .P! or .pI troff
        macros.  These macros are interpreted by the eroff
        processor to include PostScript files into the troff
        source.  If you are using Transcript style troff you
        may be able to include the PostScript figures directly
        into the troff source by defining the .P! macro in a
        way similar to the following:

        .de P!
        \\&
        .fl
        \\!%PB
        \\!/showpage{}def
        .fl
        .sy cat \\$1
        \\!PE
        \\!.
        .sp \\$2
        ..

   Printing PostScript Figures

        In their current form, the PostScript figure files are
        only suitable for inclusion within the text files.
        That is, you can print any of the chapters and
        appendixes that include figures and the figures will
        print in the correct positions within the text.
        However, you cannot print any of the figures
        individually in their current form.

        In order to print an individual figure, you need to
        convert it to the printable format using the conversion
        script, print-eps provided in the DTE.  print-eps takes
        a PostScript figure suitable for inclusion in a manual
        and converts it to a format suitable for printing
        separately.  The output of print-eps is sent to the
        standard output and can be piped to a printer command.

        For example, if you want to print the PostScript figure
        list1.ps from from the directory
        ./doc/programGuide/source/graphics, you should enter
        the following command.

        print-eps ./doc/programGuide/source/graphics/list1.ps | lp

        print-eps also takes arguments of -xoff and -yoff to
        specify and offset from the lower left corner in
        inches.

        Be aware that the figure conversion script can be run
        on a single PostScript file or on multiple files.
        Thus, both of the following command lines are
        acceptable:

        print-eps  -xoff  2  -yoff  4  list1.ps  list2.ps | lp

        print-eps  * | lp
