⟦f17ef2de4⟧

TextFile







                    X Window System, Version 11, Release 5

                                 Release Notes

                            MIT X Consortium staff

                      MIT Laboratory for Computer Science



Copyright (C) 1991 by the Massachusetts Institute of Technology.

Permission to use, copy, modify, and distribute this document for  any  purpose
and without fee is hereby granted, provided that the above copyright notice and
this permission notice appear in all copies, and that the name of  MIT  not  be
used  in advertising or publicity pertaining to this document without specific,
written prior permission.  MIT makes no representations about  the  suitability
of  this document for any purpose.  It is provided ``as is'' without express or
implied warranty.

X Window System is a trademark of MIT.



This document describes how to build, install, and get started with  Release  5
of  the  X Window System from MIT and gives a brief overview of the contents of
the release.

1.  For the Impatient Explorer

For those of you who will try to build the  distribution  without  reading  the
entire release notes first, here is a quick summary of what to do.

If you want to build with gcc, edit  mit/config/site.def  by  uncommenting  the
HasGcc line.

If  you   want   to   install   into   somewhere   other   than   /usr/bin/X11,
/usr/include/X11,  etc.,  edit  mit/config/site.def by uncommenting the Projec-
tRoot lines and changing "/usr/X11R5" to whatever directory you want to install
into.  (Do not use DESTDIR.)

Check the appropriate mit/config/vendor.cf file to make sure  that  OSMajorVer-
sion and OSMinorVersion are set correctly (change them if necessary).

Find the BootstrapCFlags line, if any, in the vendor.cf file.  If  there  isn't
one, cd to the mit directory and type:

     make World >& world.log

If there is a BootstrapCFlags, take its value1 and type:
_________________________
1.  If you are using the x386.cf file, you will have  to  compute  the  correct
value.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 2 -


     make World BOOTSTRAPCFLAGS="value" >& world.log

Do not call the output file ``make.log'', or it will be deleted.  If the  build
is successful, you can install most of it with:

     make install >& install.log

You can install man pages with:

     make install.man >& man.log

You can install lint libraries (if desired) with:

     make install.ln >& lintlib.log

If things fail, read the rest of the release notes.

2.  Brief Overview of the Distribution

(If you want, you can skip to the  next  chapter  first,  and  get  your  build
started.   While  it is compiling you will have plenty of time to read the rest
of the release notes.)

There are two parts to the Release 5 distribution: MIT software and  documenta-
tion, and user-contributed software and documentation.  The MIT part contains:

X Consortium Standards

     The MIT X Consortium produces standards:  documents which  define  network
     protocols, programming interfaces, and other aspects of the X environment.
     See the XStandards man page for a list of standards.  See the  XConsortium
     man page for information about the X Consortium.

Sample Implementations

     For most of our standards, we provide  sample  implementations  to  demon-
     strate  proof  of  concept.   These are not reference implementations; the
     written specifications define the standards.

Fonts

     A collection of bitmap and outline fonts are included in the distribution,
     contributed by various individuals and companies.

Utility Libraries

     A number of libraries, such as the Athena Widget Set, are included.  These
     are  not  standards,  but are used in building MIT applications and may be
     useful in building other applications.

Sample Programs

     We also provide a number of application programs.  A  few  of  these  pro-
     grams,  such  as  xdm,  should  be  considered  essential  in  almost  all



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 3 -


     environments.  The rest of the applications carry no special status,  they
     are  simply  programs  that have been developed and/or maintained by MIT X
     Consortium staff.  In some cases, you will  find  better  substitutes  for
     these programs in the user-contributed software.

The user-contributed part contains whatever  people  contribute.   You  find  a
variety  of software and documentation here: application programs, demos, exam-
ples, libraries, Asian input methods, X server extensions, etc.

2.1.  Structure of the MIT Sources

All of the MIT sources are under a single directory, mit.  Sources  are  organ-
ized into the following subdirectories:

clients

     This directory contains most of the sample applications.  See the  program
     man pages for details.

config

     This directory contains configuration files and the imake program used  to
     build the release.  Details are covered in other sections below.

demos

     This directory contains a small collection of graphics demonstration  pro-
     grams,  a  few  utility/test  programs, and some performance demonstration
     programs.  These are by no means the ``best'' demo programs  around,  they
     just happen to be ones we try to maintain.

doc

     This directory contains troff sources to X  Consortium  standards,  server
     internals documentation, documentation for various utility libraries, some
     useful tutorial material.

extensions

     This directory contains implementations of X server extensions,  both  the
     server  internals and the application programming libraries, and some test
     programs.  Of particular note here, new in Release 5, is  PEX,  the  PHIGS
     Extension  to  X  used  for 3D graphics, and the PHIGS programming library
     which interfaces to the PEX protocol.

fonts

     This directory contains bitmap fonts in source form, some outline fonts, a
     sample  font  server, a utility font library used by the X server and font
     server, a client font library for interacting with the  font  server,  and
     programs for building fonts and querying the font server.






X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 4 -


hardcopy

     This directory contains pre-generated PostScript files for the client  man
     pages  and  for most of the documentation found in the doc directory.  The
     files are compressed with compress to save disk space.  If you do not have
     compress  on your system, you will find a version in the mit/util/compress
     directory.

include

     This directory contains various library-independent C header files  and  a
     collection of bitmap files.

lib

     This directory contains programming libraries and support files.  Of  note
     are  Xlib  (the  lowest-level  C  programming  interface  to X), Xt (the X
     Toolkit Intrinsics), Xmu (an eclectic set of utility functions), Xaw  (the
     Athena Widget Set), and CLX (a Common Lisp interface to X).

man

     This directory contains a few top-level man pages about the release  (gen-
     eral  information, server access control mechanisms, the X Consortium, and
     X Consortium standards),  and  man  pages  for  some  of  the  programming
     libraries.

rgb

     This directory contains a program to generate the color database  used  by
     the X server and sample databases.

server

     This directory contains the  X  server  sources,  both  device-independent
     (dix)  and  device-dependent (ddx).  In this release, there is support for
     building the following servers:

     DECstation 2100/3100 monochrome and color displays
     DECstation 5000 CX and MX displays
     IBM RS/6000 skyway adapter
     Apple Macintosh monochrome and color displays
     MIPS monochrome and color displays
     OMRON LUNA monochrome displays (color displays operate in monochrome)
     Tektronix 4319 color display
     VAXstation QVSS and QDSS displays
     Sun monochrome and 8-bit color displays (with GX support)
     Various VGA displays under System V/386

     If your favorite hardware is not listed above, please do not blame  us  at
     MIT,  we  ship what Consortium members provide.  Only in a few cases do we
     try to maintain device-specific software for our own development needs.

util



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 5 -


     This directory contains miscellaneous utility programs and  shell  scripts
     used to build, maintain, and install the release.

3.  Building the Release

The core distribution (code under the mit directory) has been built and  tested
at MIT on the following systems:

     AIX 3.1.5, on IBM RS/6000
     Apollo SR10.3 (very minimal testing, bsd4.3 only)
     AT&T Unix System V Release 4 V2, on AT&T WGS6386
     A/UX 2.0.1
     HP-UX 7.0, on HP9000/s300
     IRIX 4.0
     Mach 2.5 Version 1.13, on OMRON Luna 88k
     NEWS-OS 4.1, on Sony NWS-1850
     NEWS-OS 5.0U, on Sony NWS-3710
     SunOS 4.1.1, on Sun 3, Sparc 1, and Sparc 2
     Ultrix-32 4.2, VAX and RISC
     UNICOS 5.1
     UTek 4.0
     VAX 4.3bsd (with unknown local changes)

In somes cases, we have not used the most recent version of the operating  sys-
tem  (sorry).   Support for earlier versions of the operating systems listed is
not claimed, and not guaranteed.

In addition to the systems above, support has been provided by vendors for:

     AIX 2.2 and AOS 4.3, on IBM RT
     AIX 1.2.1, on IBM PS/2
     ConvexOS V9.0
     DG/UX 4.32
     INTERACTIVE UNIX Version 2.2.1
     Mach 2.5 Version 1.40, on OMRON Luna 68k
     Motorola R32V2/R3V6.2 and R40V1
     RISCOS 4.50
     UNIOS-B 4.3BSD UNIX: 2.00
     Unix System V/386 Release 3.2, on ESIX, SCO, and AT&T (``work in progress'')
     Unix System V/386 Release 4.0, on DELL

3.1.  Unpacking the Distribution

The distribution normally comes as multiple tar files, either on tape or across
a  network.   Create  a directory to hold the distribution, cd to it, and untar
everything from that directory.  For example:

     mkdir sourcedir
     cd sourcedir
     tar xfp tar-file-or-tape-device

If you have obtained compressed and split tar files over the network, then  the
sequence for each part of the mit directory might be:




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 6 -


     cd ftp-dir/mit-N
     cat mit-N.?? | uncompress | (cd sourcedir; tar xfp -)

The sequence for each part of the contrib directory might be:

     cd ftp-dir/contrib-N
     cat contrib-N.?? | uncompress | (cd sourcedir; tar xfp -)

The sourcedir directory you choose can be anywhere in any of  your  filesystems
that  is  convenient  to  you.  After extracting the release, you should end up
with an mit subdirectory, and  a  contrib  subdirectory  if  you  unpack  user-
contributed  software.   You  will  need  about  100 megabytes of disk space to
unpack the mit directory contents; building it will of course require more disk
space.

3.2.  Symbolic Link Trees

If you expect to build the distribution on more than one machine using a shared
source tree, or you just want to keep the source tree pure, you may want to use
the shell script mit/util/scripts/lndir.sh to create a symbolic  link  tree  on
each  build  machine.   This is fairly expensive in disk space, however.  To do
this, create a directory for the build, cd to it, and type:

     sourcedir/mit/util/scripts/lndir.sh sourcedir

where sourcedir is the pathname of the directory where you stored the  sources.
All  of  the  build  instructions  given below should then be done in the build
directory on each machine, rather than in the source directory.

The shell script is reasonably portable but quite slow to execute.  If you want
you can instead try compiling a similar C program, but it is slightly tricky to
do before the distribution is built; cd to the directory mit/util/progs and try
typing:

     ln -s ../../include X11
     cc -o lndir -I. lndir.c

If it compiles and links, it will probably work; otherwise you can try typing:

     cc -o lndir -I. -DNOSTDHDRS lndir.c

If it still fails, use the shell script.

3.3.  Setting Configuration Parameters

You will notice that few if any of  the  subdirectories  under  mit  contain  a
Makefile,  but  they do contain an Imakefile.  The Imakefile is a template file
used to create a Makefile containing build rules and variables appropriate  for
the  target  machine.  The Makefile is generated by the program imake.  Most of
the configuration work prior to building the release is to  set  parameters  so
that imake will generate correct files.

The directory mit/config contains configuration files that control how the dis-
tribution  is  built.  On systems directly supported by this distribution, only



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 7 -


minimal editing of these files should be necessary.  If your system is not sup-
ported  by  the distribution but conforms to ANSI C and POSIX.1 and has socket-
style networking, then you should be able to build  a  new  configuration  file
relatively easily.  Otherwise, edits to many files throughout the system may be
necessary.  We only deal with minor editing for supported systems here.

The main files to be concerned with in the mit/config  directory  are  site.def
and  one  of  the  vendor.cf  files.  The site.def file should be used for most
site-specific configuration customizations.  The .cf file should normally  only
need to be edited if you are using a different release of the operating system.

3.3.1.  The vendor.cf File

Find the appropriate .cf file from this table:

     AIX                      ibm.cf
     AOS                      ibm.cf
     Apollo                   apollo.cf
     AT&T Unix SVR4           att.cf
     A/UX                     macII.cf
     BSD                      bsd.cf
     ConvexOS                 convex.cf
     DG/UX                    DGUX.cf
     HP-UX                    hp.cf
     INTERACTIVE              x386.cf
     IRIX                     sgi.cf
     Mach (Luna)              luna.cf
     Motorola                 moto.cf
     NEWS-OS                  sony.cf
     RISCOS                   Mips.cf
     SunOS                    sun.cf
     Ultrix                   ultrix.cf
     UNICOS                   cray.cf
     UTek                     pegasus.cf
     UNIOS-B                  luna.cf
     Unix System V/386        x386.cf

Look through this file, and check the OSMajorVersion and OSMinorVersion values.
The  numbers have been preset to what was tested at MIT or what was supplied by
the vendor.  If  the  version  numbers  match  the  operating  system  you  are
currently  running, all is well.  If they do not, you will need to edit to file
to make them correct.  In a few cases (specifically changing UNICOS from 5.1 to
6.0)  there  should not be a problem in moving the version numbers forward to a
newer release.  However, if you are moving the version  numbers  backwards,  or
moving forward to a version that hasn't been pre-tested, you may have problems,
and you have have to edit other parts of the file (and possibly other files) to
get things to work.

You can browse through the rest of the items in the .cf file, but most of  them
you should not need to edit.

3.3.2.  The site.def File

There are  two  main  variables  to  set  in  the  site.def  file:  HasGcc  and



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 8 -


ProjectRoot.   If  you are going to compile the distribution with gcc, find the
line that looks like

     /* #define HasGcc YES */

and remove the comment markers, turning it into

     #define HasGcc YES

If you are sharing a single site.def across multiple systems, you can do  some-
thing  more  complicated.   For example, if you only want to use gcc on a Sun 3
(but not on Sparcs) you might use this:

     #ifdef SunArchitecture
     #define HasGcc mc68000
     #endif

The most common error when using gcc is to fail to run the  fixincludes  script
(from  the gcc distribution) when installing gcc.  Make sure you have done this
before compiling the release.  Another common error is likely to be  using  gcc
ANSI  C  include  files when the vendor operating system supplies correct ones.
The gcc include files assert.h, limits.h, and stddef.h are prime candidates for
not installing.

The ProjectRoot  variable  controls  where  the  software  will  eventually  be
installed.   The  default  as  distributed  for most systems is to install into
``system'' directories: /usr/bin/X11, /usr/include/X11, /usr/lib, and  /usr/man
(this  is  the  behaviour  when  ProjectRoot is not defined).  If you prefer to
install into alternate directories, the simplest thing to do is to set  Projec-
tRoot.   Find the four ProjectRoot lines in the site.def file, and again remove
the ``/*'' and ``*/'' comment markers that  surround  them.   You  will  see  a
default  choice  for  ProjectRoot  of  /usr/X11R5;  if you don't like that one,
replace it with another.  Assuming you have set  the  variable  to  some  value
/path,  files  will  be installed into /path/bin, /path/include/X11, /path/lib,
and /path/man.

Note that in a few cases (ibm.cf and x386.cf) the vendor-supplied .cf file sup-
plies  a ProjectRoot by default.  If you want to accept this one, do not uncom-
ment the one in site.def; otherwise the one you place in site.def will override
the default setting.

The directories where the software will be installed are compiled in to various
programs  and  files  during the build process, so it is important that you get
the configuration correct at the outset.  If you change your  mind  later,  you
will want to do a ``make Everything'' to rebuild correctly.

Notice that the site.def file  was  two  parts,  one  protected  with  ``#ifdef
BeforeVendorCF''  and  one with ``#ifdef AfterVendorCF''.  The file is actually
processed twice, once before the .cf file and once after.  About the only thing
you need to set in the ``before'' section is HasGcc; just about everything else
can be set in the ``after'' section.

There are a large number of parameters that you can modify to change what  gets
built  and  how  it gets built.  An exhaustive list and explanation will not be



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                     - 9 -


given here; you can browse through mit/config/README to see a list  of  parame-
ters.   However,  here  are  some  notable  parameters  that you can set in the
``after'' section:

BuildXsi and BuildXimp

     New in this release, Xlib contains  support  for  internationalized  input
     methods,  using  library-  or  network-based  implementation methods.  The
     implementation details internal to Xlib can vary considerably depending on
     the  types  of  input  methods  supported.  In this release, two different
     implementations are supported, named Xsi and Ximp.   As  distributed,  the
     default  on  all  systems  except  Sony  is  Xsi.  If you want to use Ximp
     instead, add this:

     #define BuildXimp YES

BuildServer

     This controls whether or not an X server is built.  If the variable is not
     set  to NO in the .cf file, then the default is to build a server.  If you
     want to disable the server, add this:

     #define BuildServer NO

BuildFonts

     Compiled fonts take up a lot of disk space.  In this release, the compiled
     form  (called  ``pcf'') can be shared across all machines of all architec-
     tures, so you may only want to build the fonts on one machine.  To disable
     font building, add this:

     #define BuildFonts NO

BuildPex

     PEX is an X extension supporting 3-D graphics and  the  PHIGS  programming
     interface.   The  PEX  sources are known to cause some compilers to exceed
     their static symbol table sizes.  If this happens to you, you can  disable
     PEX by adding this:

     #define BuildPex NO

ManSuffix

     User program man pages are installed by default in  subdirectory  ``mann''
     with suffix ``.n''.  You can change this to ``man1'' and ``.1'', for exam-
     ple, by adding this:

     #define ManSuffix 1

InstallLibManPages

     By default, the programming library man pages (Xlib,  Xt,  various  exten-
     sions)  are  installed along with all of the other man pages.  The library



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 10 -


     pages constitute a considerable number of files.  If you do not expect  to
     be  programming  with X, or prefer using other forms of documentation, you
     can disable installation of the library pages by adding this:

     #define InstallLibManPages NO

InstallXdmConfig and InstallXinitConfig

     The xdm and xinit programs are the normal  ways  to  run  X  servers.   By
     default,  the configuration files for these programs are not installed, to
     avoid inadvertently destroying existing configuration files.  If  you  are
     not  yet using xdm or xinit, or will be installing into a new destination,
     or do not wish to retain your old configuration files, add these:

     #define InstallXdmConfig YES
     #define InstallXinitConfig YES

XdmServersType

     Some of the xdm config files are generated based on configuration  parame-
     ters.   One  of  the  files  controls  whether  an  X server is started by
     default.  By default the choice is made based on whether an  X  server  is
     built  as  part  of this distribution (the BuildServer parameter).  If you
     are not building a server, but you will be running a product server on the
     workstation under xdm, you should add this:

     #define XdmServersType ws

HasXdmAuth

     This release supports  a  DES-based  form  of  authorization  called  XDM-
     AUTHORIZATION-1.   The  source  file  mit/lib/Xdmcp/Wraphelp.c,  which  is
     necessary for this to compile, might not be included in your  distribution
     due to possible export regulations; if it is not included and you are a US
     citizen, you should be able to obtain  the  file  over  the  network.   To
     enable building of this mechanism, add this:

     #define HasXdmAuth YES

InstallFSConfig

     New to this release is a network font server, fs.  By default, the  confi-
     guration  files  for  the  font  server  are  not installed.  To have them
     installed, add this:

     #define InstallFSConfig YES

MotifBC

     If you want to use the Release 5 Xlib and Xt with Motif 1.1, you will need
     to enable a backward compatibility flag, by adding this:

     #define MotifBC YES




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 11 -


3.4.  System Pitfalls

On a few systems, you are likely to have build problems unless  you  make  some
minor  changes  to  the  system.  Naturally, you should exercise caution before
making changes to system files, but these are our recommendations based on  our
experience.

On VAX Ultrix systems, you may find that <stdlib.h>  contains  declarations  of
malloc,  calloc,  and  realloc with a return value of ``void *''.  You may find
this causes problems when compiling with a non-ANSI-C compiler, in which case a
workaround  is  to  change the return values to ``char*'' in the ``#else'' sec-
tion.

Ultrix may not provide <locale.h> unless you load the Internationalization sub-
set.   You  will  need  this file to compile the distribution (or else you will
need to reset a configuration parameter, see below).

On SunOS systems, you may find that statically linking (when debugging) against
both  Xlib  and  the  libc  will result in unresolved symbols to dynamic linker
functions, because Xlib contains calls to wcstombs.   Either  link  dynamically
against libc, or compile and link the stub routines in mit/util/misc/dlsym.c.

On Sun 3s, the default is to compile library files  with  no  special  floating
point assumptions.  If all of your Sun 3s have floating point hardware, you may
want to change this, for better performance of Xlib color functions.  For exam-
ple, in the ``after'' section of your site.def file, you might add:

     #if defined(SunArchitecture) && defined(mc68000)
     #undef LibraryCCOptions
     #define SharedLibraryCCOptions -f68881 -pipe
     #endif

On AOS, you may find that <stdarg.h> is missing.  In that case, you  should  be
able to copy mit/util/misc/rt.stdarg.h to create the file.

On some System V/386 systems, you may find when using gcc  in  ANSI  mode  that
there are inconsistent declarations between <memory.h> and <string.h>.  In that
case, you may find it convenient to remove <memory.h> and make  it  a  link  to
<string.h>.

On some System V/386 systems, you may need to build and install a  dbm  library
before  building  the  X  server  and  RGB  database.   One  can  be  found  in
contrib/util/sdbm.

3.4.1.  Internationalization

This release has support for internationalization, based  on  the  ANSI  C  and
POSIX  locale  model.   On some systems, you may discover that while the locale
interface is supported, only the ``C'' locale is actually provided in the  base
operating system.  If you have such a system, and would like to experiment with
a broader set of locales, the Xlib implementation contains support you can use,
although  use  of  this override has not really be tested.  You need to add the
following defines to the StandardDefines parameter:




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 12 -


     -DX_WCHAR -DX_LOCALE

In most cases you will have to directly edit the .cf file to do this,  or  else
you  will  have to know what the rest of the values are supposed to be, and add
this to site.def:

     #undef StandardDefines
     #define StandardDefines previous-values -DX_WCHAR -DX_LOCALE

It is also possible to directly edit the file mit/include/Xosdefs.h,  but  this
is not recommended.

With this setup, you will have to be careful that the system's  declaration  of
wchar_t (in <stddef.h>) never gets used; this might be tricky.

3.5.  Typing ``make World''

One more piece of information is required before building,  at  least  on  some
systems: bootstrap flags.  Look in your .cf file for a line of the form

     #define BootstrapCFlags value

If there isn't one things are simple, otherwise things are only  slightly  more
complicated.   If  there is more than one (for example, in ibm.cf, moto.cf, and
sony.cf), then you need to select the right one; it should be pretty obvious by
the  grouping  according  to operating system type.  Note that on A/UX you only
need this value if you are using gcc, and that on a  Sun  you  only  need  this
value if you are using an earlier version of the operating system.

If you are using x386.cf, you will have  to  ``compute''  the  value  from  the
information given in the file.  You may also need to do other preparatory work;
please read mit/server/ddx/x386/README.

If no value is required on your system, you can cd to  the  mit  directory  and
start the build with:

     make World >& world.log

If a value is required, start the build with:

     make World BOOTSTRAPCFLAGS="value" >& world.log

You can call the output file something other than  ``world.log'',  but  do  not
call  it  ``make.log''  because  files with this name are automatically deleted
during the ``cleaning'' stage of the build.

Because the build can take several hours to complete, you will probably want to
run it in the background, and keep a watch on the output.  For example:

     make World >& world.log &
     tail -f world.log

If something goes wrong, the easiest thing is to just start over (typing ``make
World''  again)  once  you  have  corrected the problem.  It is possible that a



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 13 -


failure will corrupt the top-level Makefile.  If that  happens,  simply  delete
the file and recreate a workable substitute with:

     cp Makefile.ini Makefile

When the build completes, examine the world.log file for errors.  If you search
for  `:'  (colon) characters, and skip the obvious compile lines, it is usually
pretty easy to spot any errors.2

4.  Installing the Release

Although it is possible to test the release before installing it, it is  a  lot
easier  to  test  after it has been installed.  If everything is built success-
fully, you can install the software by typing the following as root,  from  the
mit directory:

     make install >& install.log

Again, you might want to run this in the background and use tail to  watch  the
progress.

You can install the man pages by typing the following as  root,  from  the  mit
directory:

     make install.man >& man.log

You can install lint libraries (useful if your systems does does  not  have  an
ANSI C compiler) by typing the following as root, from the mit directory:

     make install.ln >& lintlib.log

4.1.  Setting Up xterm

If your /etc/termcap  and  /usr/lib/terminfo  databases  do  not  have  correct
entries   for   xterm,   sample   entries   are   provided   in  the  directory
mit/clients/xterm/.  System V users may need to compile and  install  the  ter-
minfo entry with the tic utility.

Since each xterm will need a separate pseudoterminal,  you  need  a  reasonable
number  of  them for normal execution.  You probably will want at least 32 on a
small, multiuser system.  On most systems, each pty has two devices,  a  master
and    a   slave,   which   are   usually   named   /dev/tty[pqrstu][0-f]   and
/dev/pty[pqrstu][0-f].  If you don't have at least the  ``p''  and  ``q''  sets
configured (try typing ``ls /dev/?ty??''), you should have your system adminis-
trator add them.  This is commonly done by running the MAKEDEV  script  in  the
/dev directory with appropriate arguments.



_________________________
2.  Searching for colon does not work particularly well on the RS/6000  because
it  appears in command lines when building shared libraries.  Try searching for
colon followed by space.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 14 -


4.2.  Starting Servers at System Boot

The xdm program is designed to be run automatically at system startup.   Please
read the xdm man page for details on setting up configuration files; reasonable
sample files are in mit/clients/xdm/config.  If your  system  uses  an  /etc/rc
file  at  boot  time, you can usually enable xdm by placing the following at or
near the end of the file:

     if [ -f /usr/bin/X11/xdm ]; then
             /usr/bin/X11/xdm; echo -n ' xdm'
     fi

The example here uses /usr/bin/X11, but if you have installed into a  different
directory  (for example by setting ProjectRoot) then you need to substitute the
correct directory.

If you are going to use the font server, you can also start it at boot time  by
adding this:

     if [ -f /usr/bin/X11/fs ]; then
             /usr/bin/X11/fs &; echo -n ' fs'
     fi

If you are unsure about how system boot works, or if your system does  not  use
/etc/rc, consult your system administrator for help.

5.  Rebuilding the Release

You shouldn't need this right away, but eventually you are  probably  going  to
make changes to the sources, for example by applying public patches distributed
by MIT.  If only C source files are changed, you should be able to rebuild just
by going to the mit directory and typing:

     make >& make.log

If configuration files are changed, the safest thing to do is type:

     make Everything >& every.log

``Everything'' is similar to ``World'' in that it rebuilds every Makefile,  but
unlike  ``World''  it does not delete the existing objects, libraries, and exe-
cutables, and only rebuilds what is out of date.

Note  that  in  both  kinds  of  rebuilds  you  do  not  need  to  supply   the
BootstrapCFlags value any more, the information is already recorded.

6.  Building Contributed Software

The software in contrib is not set up to have everything  built  automatically.
It  is  assumed  that  you will build individual pieces as you find the desire,
time, and/or disk space.  You need to have the MIT software built and installed
before  building  the  contributed  software.  To build a program or library in
contrib, look in its directory for any special build instructions (for example,
a  README  file).   If  there  are  none,  and there is an Imakefile, cd to the



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 15 -


directory and type:

     xmkmf -a
     make >& make.log

This will build a Makefile in the directory and all  subdirectories,  and  then
build  the software.  If the build is successful, you should be able to install
it using the same commands used for the mit software:

     make install >& install.log
     make install.man >& man.log

7.  Filing Bug Reports

If you find a reproducible bug in software in the mit directory, or  find  bugs
in the mit documentation, please send a bug report to MIT using the form in the
file mit/bug-report and the destination address:

     xbugs@expo.lcs.mit.edu

Please try to provide all of the information requested on the  form  if  it  is
applicable;  the  little  extra  time you spend on the report will make it much
easier for us to reproduce, find, and fix the bug.  Receipt of bug  reports  is
generally acknowledged, but sometimes it can be delayed by a few weeks.

Bugs in contrib software should not be reported to MIT.  Consult the documenta-
tion for the individual software to see where (if anywhere) to report the bug.

8.  Public Fixes

We occasionally put out patches to the MIT software, to fix any  serious  prob-
lems   that   are   discovered.    Such   fixes   (if  any)  can  be  found  on
export.lcs.mit.edu, in the directory pub/R5/fixes, using anonymous ftp.   Fixes
are  applied using the patch program; a copy of it is included in the directory
mit/util/patch.

For those without ftp access, individual fixes can be  obtained  by  electronic
mail by sending a message to

     xstuff@expo.lcs.mit.edu

(Note that the host here is ``expo'', not ``export''.)  In the usual case,  the
message  should  have  a subject line and no body, or a single-line body and no
subject, in either case the line looking like:

     send fixes number

where number is a decimal number, starting from  one.   To  get  a  summary  of
available fixes, make the line:

     index fixes

If you need help, make the line:




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 16 -


     help

Some mailers produce mail headers  that  are  unusable  for  extracting  return
addresses.   If you use such a mailer, you won't get any response.  If you hap-
pen to know an explicit return path, you can include include one in the body of
your message, and the daemon will use it.  For example:

     path user%host.bitnet@mitvma.mit.edu
         or
     path host1!host2!user@uunet.uu.net

9.  Configuring for a New Architecture

Here is a very brief overview of the files that imake reads.  All the files are
in  the  mit/config  directory,  except  for the Imakefile in the directory for
which the Makefile is being created.  The processing order is:

     Imake.tmpl               variables not related specifically to X
         site.def             site-specific BeforeVendorCF part
         *.cf                 machine-specific
             *Lib.rules       shared library rules
         site.def             site-specific AfterVendorCF part
         Project.tmpl         X-specific variables
             *Lib.tmpl        shared library variables
         Imake.rules          rules
     Imakefile                specific to the program or library
         Library.tmpl         library rules
         Server.tmpl          server rules
The indentation levels indicate what files include other files.

9.1.  Imake.tmpl

The first part of Imake.tmpl determines which .cf file to include.  If your cpp
defines  a  unique  symbol, that should be used to select the file.  Otherwise,
you should place a -D symbol definition in BootstrapCFlags in your .cf file and
use that.  The canonical code to add to Imake.tmpl is:

     #ifdef symbol
     #define MacroIncludeFile <symbol.cf>
     #define MacroFile symbol.cf
     #undef symbol
     #define SymbolArchitecture
     #endif /* symbol */

9.2.  imakemdep.h

You also need to edit the file imakemdep.h.  There  are  three  parts  to  this
file.   The first contains defines (beyond BootstrapCFlags) or compiler options
that are required to get imake itself built the first time.

The next section is for imake itself.  There is a hook in case  your  cpp  col-
lapses  tabs down to single spaces.  There is also a way to override the cpp to
use.  Finally, add specific defines to pass to cpp when  processing  configura-
tion files.



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 17 -


The last section is for makedepend, to tell it about  predefined  symbols  that
will be used to control inclusion of header files.


9.3.  vendor.cf

Most of the rest of your vendor-specific configuration information  goes  here.
We  won't  try  to  tell you everything you need; study the other .cf files and
copy from systems that are similar.  One good rule to follow is to  not  define
anything that will get the correct default value from somewhere else; this will
make it easier to see what is special, and will make it  easier  for  sites  to
customize in their site.def.

If you have shared libraries, the convention  is  to  place  the  configuration
rules and standard parameters in a file named osLib.rules, and to place version
number parameters and make variables in a file named osLib.tmpl.  Look  at  the
existing files and mimic them.

9.4.  Other Files

Unfortunately, for a new system there are a potentially large number  of  files
that you may have to modify.  Only the most prominent ones are listed here.

     mit/include/Xfuncs.h
     mit/include/Xmd.h
     mit/include/Xos.h
     mit/include/Xosdefs.h
     mit/clients/xload/get_load.c
     mit/clients/xman/vendor.c
     mit/clients/xman/vendor.h
     mit/clients/xterm/main.c
     mit/lib/X/Xlibnet.h
     mit/server/include/servermd.h

10.  Writing Portable Code

In this section we give a brief introduction to using various header  files  to
aid in writing portable code.

10.1.  <X11/Xosdefs.h>

The file <X11/Xosdefs.h> defines symbols that describe the  system  environment
for  ANSI  C  and  POSIX.   We  likely will extend it to other standards in the
future.  We have found these symbols useful in writing portable code, and  hope
that  other writers of X software will use them as well.  This file is not part
of any X Consortium standard, it is simply part of our software distribution.

<X11/Xosdefs.h> can be included directly by a file, or it will be automatically
included when you include <X11/Xos.h>.

The symbols in <X11/Xosdefs.h> tell when you can, for example, do

     #include <stdlib.h>




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 18 -


without getting a ``no such header file'' error from the compiler.  If the sys-
tem provides a declaration for a function or value for a constant, it is impor-
tant to use the system's definition rather than providing  your  own,  particu-
larly  because  you  might not use function prototypes and the system might, or
vice versa.

<X11/Xosdefs.h> currently controls two symbols: X_NOT_STDC_ENV and X_NOT_POSIX.

X_NOT_STDC_ENV means the system does not have ANSI C header files.   Thus,  for
example,  if  X_NOT_STDC_ENV  is not defined, it is safe to include <stdlib.h>.
Do not confuse this symbol with  __STDC__,  which  says  whether  the  compiler
itself  supports  ANSI  C  semantics.  X_NOT_STDC_ENV is independent, and tells
what header files it is safe to include.

Lack of the symbol X_NOT_STDC_ENV does not mean that the system has <stdarg.h>.
This  header  file is part of ANSI C, but we have found it more useful to check
for it separately because many systems have all the ANSI C files we need except
this one.  __STDC__ is used to control inclusion of this file.

An example of using X_NOT_STDC_ENV might be to know when  the  system  declares
getenv:

     #ifndef X_NOT_STDC_ENV
     #include <stdlib.h>
     #else
     extern char *getenv();
     #endif

We usually put the standard case first in our code, using ``#ifndef''.

X_NOT_POSIX means the system does not have POSIX.1 header files.  Lack of  this
symbol  does not mean that the POSIX environment is the default.  You may still
have to define _POSIX_SOURCE before including the  header  file  to  get  POSIX
definitions.3

An example of using X_NOT_POSIX might be to  determine  the  type  that  getuid
would be declared by in <pwd.h>:

     #include <pwd.h>
     #ifndef X_NOT_POSIX
         uid_t uid;
     #else
         int uid;
         extern int getuid();
     #endif
         uid = getuid();

Note that both of these symbols, when declared, state a  non-compliance.   This
was  chosen  so that porting to a new, standard platform would be easier.  Only
_________________________
3.  We have found it very unfortunate that POSIX did not define a standard sym-
bol that means ``give me POSIX, plus any non-conflicting vendor-specific defin-
itions''.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 19 -


non-standard platforms need to add themselves to <X11/Xosdefs.h> to turn on the
appropriate symbols.

Not all systems for which we leave these symbols undefined strictly  adhere  to
the  relevant standards.  Thus you will sometimes see checks for a specific O/S
near a check for one of the Xosdefs.h symbols.  However, we have found it  most
useful  to  label  systems  as conforming even if they have some holes in their
compliance.  Presumably these holes will become fewer as time goes on.

10.2.  <X11/Xos.h>

In general, <X11/Xos.h> should be used instead of the following header files:

     <string.h>
     <strings.h>
     <sys/types.h>
     <sys/file.h>
     <fcntl.h>
     <sys/time.h>
     <unistd.h>
This file is not part of any X Consortium standard, it is simply  part  of  our
software distribution.

Some common routines for which you need to  include  <X11/Xos.h>  before  using
are:

     index
     rindex
     strchr
     strrchr
     (all the other standard string routines)
     gettimeofday
     time

Data types and constants that should be obtained with <X11/Xos.h> are:

     caddr_t
     O_RDONLY
     O_RDWR
     (and other open constants)
     R_OK
     W_OK
     X_OK
     (and other fcntl constants)

Unfortunately, we did not create a header file for declaring malloc  correctly,
and it can be a bit tricky.  You can use what we currently have by copying, for
example, from mit/lib/Xt/Alloc.c:

     #ifndef X_NOT_STDC_ENV
     #include <stdlib.h>
     #else
     char *malloc(), *realloc(), *calloc();
     #endif



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 20 -


     #if defined(macII) && !defined(__STDC__)  /* stdlib.h fails to define these */
     char *malloc(), *realloc(), *calloc();
     #endif /* macII */

10.3.  <X11/Xfuncs.h>

This file contains definitions of bcopy, bzero, and bcmp.4 You  should  include
this  header  in  any file that uses these functions.  This file is not part of
any X Consortium standard, it is simply part of our software distribution.

10.4.  <X11/Xfuncproto.h>

This file contains definitions for writing function declarations to  get  func-
tion  prototypes to work right.  It deals with ANSI C compilers as well as pre-
ANSI C compilers that have parts of function prototypes implemented.  This file
is  not  part  of  any X Consortium standard, it is simply part of our software
distribution.

For external header files that might get used from C++, you should wrap all  of
your function declarations like this:

     _XFUNCPROTOBEGIN
     function declarations
     _XFUNCPROTOEND
When in doubt, assume that the header file might get used from C++.

A typical function declaration uses NeedFunctionPrototypes, like this:

     extern Atom XInternAtom(
     #if NeedFunctionPrototypes
         Display*            /* display */,
         _Xconst char*       /* atom_name */,
         Bool                /* only_if_exists */
     #endif
     );

If there are const parameters, use the symbol _Xconst instead, as above.  If it
is  plausible  to pass a string literal to a char* parameter, then it is a good
idea to declare the parameter with _Xconst, so that literals can be  passed  in
C++.

If there are nested function prototypes, use NeedNestedPrototypes:

     extern Bool XCheckIfEvent(
     #if NeedFunctionPrototypes
         Display*            /* display */,
         XEvent*             /* event_return */,
         Bool (*) (
     #if NeedNestedPrototypes
                    Display*                 /* display */,
_________________________
4.  Yes, we should have used the ANSI C function names, but we thought  we  had
too much existing code using the BSD names.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 21 -


                    XEvent*                  /* event */,
                    XPointer                 /* arg */
     #endif
                  )          /* predicate */,
         XPointer            /* arg */
     #endif
     );

If there is a variable argument list, use NeedVarargsPrototypes:

     extern char *XGetIMValues(
     #if NeedVarargsPrototypes
         XIM /* im */, ...
     #endif
     );

If you have parameter types that will widen in  K&R  C,  then  you  should  use
NeedWidePrototypes:

     extern XModifierKeymap *XDeleteModifiermapEntry(
     #if NeedFunctionPrototypes
         XModifierKeymap*    /* modmap */,
     #if NeedWidePrototypes
         unsigned int        /* keycode_entry */,
     #else
         KeyCode             /* keycode_entry */,
     #endif
         int                 /* modifier */
     #endif
     );

If   you   use   _Xconst,   NeedNestedPrototypes,   NeedVarargsPrototypes,   or
NeedWidePrototypes,  then your function implementation also has to have a func-
tion prototype.  For example:

     #if NeedFunctionPrototypes
     Atom XInternAtom (
         Display *dpy,
         _Xconst char *name,
         Bool onlyIfExists)
     #else
     Atom XInternAtom (dpy, name, onlyIfExists)
         Display *dpy;
         char *name;
         Bool onlyIfExists;
     #endif
     {
         ...
     }

Actually, anytime you use a function prototype in a header file, you should use
a  function  prototype in the implementation, as required by ANSI C.  The MIT X
sources do not follow this (we've never had time to make all the changes),  and
there  are  almost certainly compilers that will complain if the implementation



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 22 -


does not match the declaration.

10.5.  Other Symbols

Do not use the names class, new, or index as variables or struct members.   The
names  class  and  new  are reserved words in C++, and you may find your header
files used by a C++ program someday.  Depending on your system,  index  can  be
defined  as  strchr  or  a macro in <X11/Xos.h>; this may cause problems if you
include this header file.

The following system-specific symbols are commonly used in X sources  where  OS
dependencies intrude:5

     USG       based on System V Release 2
     SYSV      based on System V Release 3
     SVR4      System V Release 4

For other system-specific symbols, look at the  StandardDefines  parameters  in
the mit/config/*.cf files.

11.  What's New, What's Changed

In this section we briefly describe some of the more significant  new  features
of Release 5.

11.1.  New standards

The following standards are new in Release 5:

X Font Service Protocol

     Instead of forcing each X server to read all fonts  from  the  filesystem,
     the  X  Font  Server Protocol makes it possible to manage fonts separately
     from the X server, directing the X server to request fonts  via  this  new
     Consortium standard network protocol from a font server.  In addition, for
     fonts which take a long time to open, this allows the X server to continue
     with other clients while the font server services the font requests.

XLFD changes for scalable fonts

     The X Logical Font Description standard has been  compatibly  enhanced  to
     allow clients to specify and use scalable fonts.

X Input Device Extension

     This extension has been promoted from Draft Standard  to  full  Consortium
     Standard with this release.

Inter-Client Communications Conventions

     This  standard  has  been  updated  to  cover  the  new  X  Device   Color
_________________________
5.  At most one of these symbols should be defined on a given system!




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 23 -


     Characterization Conventions for device-independent color support in Xlib.

11.2.  General

We have tried hard with this release to make our  code  use  standard  features
from  POSIX.1  and  ANSI  C  when possible.  A new include file <X11/Xosdefs.h>
describes which systems comply or do not comply with these standards.

Two new X authorization schemes are included, a DES  based  private-key  system
which  was described in the R4 XDMCP document - XDM-AUTHORIZATION-1 (along with
the associated XDMCP authentication system XDM-AUTHENTICATION-1)  and  the  Sun
Secure  RPC based SUN-DES-1 system, which uses the SunOS supplied security sys-
tem.

11.3.  Clients

Most clients participate in the WM_DELETE_WINDOW protocol.

New clients:  editres,  viewres,  xconsole,  xcmsdb.   New  demos:  beach_ball,
auto_box,  gpc,  xcmstest,  xgas,  x11perf.   Xlswins  has  been removed; it is
replaced by xwininfo -tree.  Moved to contrib: muncher, plaid.  Completely  new
implementation: bitmap and xmag.  Other changes of note:

editres

     Editres is a tool that allows users and application developers to view the
     full widget hierarchy of any X Toolkit client that speaks the Editres pro-
     tocol.  In addition editres will help the user construct resource specifi-
     cations,  allow the user to apply the resource to the application and view
     the results dynamically.  Once the user is happy with a resource  specifi-
     cation,  editres  will  append the resource string to the user's resources
     file.

xdm

     Xdm can now display a menu of hosts for XDMCP-capable terminals using  the
     new chooser client.  This is useful for X terminals that do not themselves
     offer such a menu.  XDMCP works with STREAMS.   A  new  setup  program  is
     invoked  by  xdm prior to putting up the login window; this program can be
     used to run xsetroot, xcmsdb,  and  do  any  other  custom  initialization
     required.

xterm

     Cuts of wrapped lines are now treated as a single line.   Cuts  of  multi-
     page  regions  now work and highlight correctly.  Pasting large amounts of
     data into xterm now works (on systems with properly-working pty  implemen-
     tations).   New arguments have been added to the send-signal action: quit,
     alarm.  The titeInibit resource has been  modified  to  also  inhibit  the
     escape  sequence  which  switches  to the alternate screen.  Two new items
     have been added to the VT Fonts menu: 5x7 (Tiny) and  10x20  (Huge).   The
     following  resources  have  been  added:  resizeGravity, bellSuppressTime,
     appcursorDefault, appkeypadDefault, ginTerminator,  autoWrap.   The  Xterm
     Control  Sequences  document  is  up to date.  Xterm is installed securely



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 24 -


     when made setuid on SunOS 4.1.1 with shared libraries.

xmh

     Xmh now uses the MH environment variable, if set.  Xmh now supports check-
     ing   for   mail   in   multiple  maildrops.   Enhanced  participation  in
     WM_PROTOCOLS has been added.  New resources have  been  added,  including:
     checkpointInterval,  checkpointNameFormat,  mailInterval,  rescanInterval,
     showOnInc, noMailBitmap, newMailBitmap, newMailIconBitmap, and noMailIcon-
     Bitmap.   New  actions  have  been added: XmhWMProtocols, XmhShellCommand,
     XmhCheckForNewMail, XmhViewMarkDelete.  Better  recovery  from  unexpected
     inconsistencies with the filesystem has been implemented.  Better POP sup-
     port has been  added.   See  the  file  mit/clients/xmh/CHANGES  for  more
     details.

oclock

     Oclock has a new -transparent option.

xload

     Xload is secure on SunOS 4.1.1 with shared libraries.

xditview

     Xditview now supports pic, scalable fonts, settable device resolution, and
     has a better user interface.

11.4.  Libraries in General

All of the useful libraries now use function prototypes by default for  systems
which  support  them.  SunOS shared libraries now use much less swap space than
in R4.  In addition, System V Release 4 and AIX 3.1 shared libraries  are  also
supported  now.   Configuring  new shared library systems should be much easier
than before.

11.5.  Xlib

Two new major pieces of functionality have been added to Xlib: device  indepen-
dent  color,  and  internationalization (i18n).  In addition, a few other addi-
tions and improvements have been made.

11.5.1.  Xlib Manual

The Xlib manual has been reorganized for Release 5.   Unfortunately,  this  may
cause  considerable  confusion  for  a  while when people quote section numbers
without reference to the release.  However, we feel that the  new  organization
is a considerable improvement.

11.5.2.  Device-independent Color

The Xcms  (X  Color  Management  System)  functions  in  Xlib  support  device-
independent color spaces derivable from the CIE XYZ color space.  This includes
the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as the  TekHVC  color



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 25 -


space.   In  addition, linear RGB intensity value space has been added, as well
as gamma correction for device RGB  values,  and  a  uniform  syntax  has  been
adopted  for specifying colors in strings.  Xlib now supports client-side color
name databases, and the existing Xlib functions that  use  color  names  (e.g.,
XLookupColor  and  XAllocNamedColor)  now  handle all color spaces, so that the
contrivance of using XParseColor followed by XAllocColor is  no  longer  neces-
sary.   Xlib  provides  direct  programming  interfaces  for dealing with color
values in different spaces, and for converting  between  spaces.   New  device-
independent color spaces can also be added.  For details on the new color func-
tionality, read Chapter 6 of the new Xlib manual.

Monitors are characterized by data stored on root window  properties;  the  new
xcmsdb  program can be used to set these properties.  Unfortunately, you need a
color analyzer instrument to generate characterizations; choosing a random  one
will  almost  certainly produce inaccurate colors.  However, you will find some
sample    database    files    in    mit/clients/xcmsdb/datafiles    and     in
contrib/clients/ca100/monitors.

11.5.3.  Internationalization

An internationalized application is one which is adaptable to the  requirements
of  different  native languages, local customs, and character string encodings.
The process of adapting the operation to a particular  native  language,  local
custom,  or string encoding is called localizaton.  A goal of internationaliza-
tion is to permit localization without program source modifications or recompi-
lation.

Internationalization in Xlib is based on the concept of  a  locale.   A  locale
defines  the  ``localized''  behavior of a program at run-time.  Locales affect
Xlib in its:

o    Encoding and processing of input method text

o    Encoding of resource files and values

o    Encoding and imaging of text strings

o    Encoding and decoding for inter-client text communication

Characters from various languages are represented in a computer using an encod-
ing.   Different  languages  have  different encodings, and there are even dif-
ferent encodings for the same characters in the same language.

Xlib provides support for localized text imaging and text input.  Sets of func-
tions  are  provided  for  multibyte  (char*)  text  as  well as wide character
(wchar_t) text in the form supported by the host C language  environment.   For
details  on  the new internationalization functionality, read Chapter 13 of the
new Xlib manual.

Two sample implementations of the internationalization mechanisms exist in this
release,  one  called Xsi and one called Ximp.  You will find documentation for
them  in  mit/doc/I18N  and  contrib/im,  and  locale   definition   files   in
mit/lib/nls.   In  contrib/im  you  will  also  find network-based Input Method
servers.



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 26 -


Unfortunately, none of the programs in the MIT software use  the  new  interna-
tionalization  facilities.   However,  you  will  find  some  sample clients in
contrib/im, and internationalized versions  of  some  of  the  MIT  clients  in
contrib/clients.

11.5.4.  Keysyms

By default a database of all registered vendor-private keysyms gets  installed,
so that Xlib can map between keysym values and names.

11.5.5.  Resource Databases

A new SCREEN_RESOURCES property has been  defined,  permitting  screen-specific
resources  to be set, so that (for example) colors can be specified for a color
screen and not effect a monochrome screen on the same server.  The xrdb program
has been enhanced to ``do the right thing'' automatically in most cases.

New functions have been defined to merge a resource database  directly  from  a
file,  and  to  combine  two  databases with either ``augment'' or ``override''
semantics.

A ``#include'' syntax is now supported in resource files.  A  specific  example
of  using this is to have a customized app-defaults file (in an Xt application)
include the base app-defaults file.

A new reserved component name, ``?'', has been defined that  matches  a  single
level  in  the  resource hierarchy.  This makes it easier to override resources
specified in app-defaults files.

A new function, XrmEnumerateDatabase, has been defined to search  for  matching
entries  in  a resource database.  The appres program has been enhanced in this
release to become a convenient interface to this function.

A new function, XrmPermStringToQuark, has been introduced to avoid having  Xlib
allocate needless storage for constant strings.

11.5.6.  Extensions

A new function has been added to permit an extension  to  convert  errors  with
additional data into Xlib format, and one has been added to permit an extension
to print out the values in an error handler.

11.5.7.  Miscellaneous

A new type XPointer has been introduced, replacing  uses  of  the  non-standard
type caddr_t.  Old programs using caddr_t will still work, of course.

11.5.8.  Performance

The new color and internationalization facilities have the  unfortunate  effect
of  making  executables  quite  a bit larger on systems that do not have shared
libraries.

The resource  database  functions  have  been  completely  rewritten  for  this



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 27 -


release.   Databases should be significantly smaller in memory, and loading and
parsing resources should be faster.

11.6.  Xt Intrinsics

At the data structure level, Release 5 retains  complete  binary  compatibility
with  Release  4.   The specification of the ObjectPart, RectObjPart, CorePart,
CompositePart,  ShellPart,   WMShellPart,   TopLevelShellPart,   and   Applica-
tionShellPart  instance  records was made less strict to permit implementations
to add internal fields to these structures.  Any implementation that chooses to
do  so  would,  of  course,  force a recompilation.  The Xlib specification for
XrmValue and XrmOptionDescRec was updated to use a new type, XPointer, for  the
addr  and value fields respectively, to avoid ANSI C conformance problems.  The
definition of XPointer is binary compatible with the previous implementation.

11.6.1.  baseTranslations Resource

A new pseudo-resource, XtNbaseTranslations, was defined to  permit  application
developers  to  specify  translation tables in application defaults files while
still giving end users the ability to  augment  or  override  individual  event
sequences.   This  change will affect only those applications that wish to take
advantage of the new functionality, or those widgets that may  have  previously
defined a resource named ``baseTranslations''.

Applications wishing to take advantage of the new  functionality  would  change
their application defaults file, e.g., from

     app.widget.translations: value
to

     app.widget.baseTranslations: value
If it is important to the application to preserve complete compatibility of the
defaults  file  between  different  versions  of  the application running under
Release 4 and Release 5, the full translations can be replicated  in  both  the
``translations'' and the ``baseTranslations'' resource.

11.6.2.  Resource File Search Path

The current specification allows implementations greater flexibility in  defin-
ing  the  directory  structure  used to hold the application class and per-user
application defaults files.  Previous specifications required the  substitution
strings to appear in the default path in a certain order, preventing sites from
collecting all the files for a specific application together in one  directory.
The Release 5 specification allows the default path to specify the substitution
strings in any order within a single path entry.  Users will need to pay  close
attention to the documentation for the specific implementation to know where to
find these files and how  to  specify  their  own  XFILESEARCHPATH  and  XUSER-
FILESEARCHPATH values when overriding the system defaults.

11.6.3.  Customization Resource

XtResolvePathname supports  a  new  substitution  string,  %C,  for  specifying
separate application class resource files according to arbitrary user-specified
categories.  The primary motivation for this addition was  separate  monochrome



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 28 -


and color application class defaults files.  The substitution value is obtained
by querying the current resource database for  the  application  resource  name
``customization'',  class  ``Customization''.   Any application that previously
used this resource name and class will need to be aware of  the  possibly  con-
flicting semantics.

11.6.4.  Per-Screen Resource Database

To allow a user to specify separate preferences for each screen of a display, a
per-screen  resource  specification string has been added and multiple resource
databases are created; one for each screen.  This will affect  any  application
that  modified  the  (formerly  unique)  resource  database associated with the
display subsequent to the Intrinsics database  initialization.   Such  applica-
tions will need to be aware of the particular screen on which each shell widget
is to be created.

Although the wording of the specification changed substantially in the descrip-
tion  of  the process by which the resource database(s) is initialized, the net
effect is the same as in prior releases with the exception of  the  added  per-
screen  resource specification and the new customization substitution string in
XtResolvePathname.

11.6.5.  Internationalization of Applications

Internationalization as defined by ANSI is a technology that allows support  of
an  application in a single locale.  In adding support for internationalization
to the Intrinsics the restrictions of this model have been followed.   In  par-
ticular, the new Intrinsics interfaces are designed to not preclude an applica-
tion from using other alternatives.  For this  reason,  no  Intrinsics  routine
makes  a  call  to  establish  the  locale.   However, a convenience routine to
establish the locale at initialize time has been provided, in  the  form  of  a
default  procedure that must be explicitly installed if the application desires
ANSI C locale behavior.

As many objects in X, particularly resource databases, now inherit  the  global
locale  when  they  are  created, applications wishing to use the ANSI C locale
model should use the new function XtSetLanguageProc to do so.

The internationalization additions also define event filters as a part  of  the
Xlib  Input  Method  specifications.   The  Intrinsics  enable the use of event
filters through additions to XtDispatchEvent.  Applications  that  may  not  be
dispatching  all  events through XtDispatchEvent should be reviewed in the con-
text of this new input method mechanism.

In order to permit internationalization of error messages the name and path  of
the error database file is now allowed to be implementation dependent.  No ade-
quate standard mechanism has yet been suggested  to  allow  the  Intrinsics  to
locate the database from localization information supplied by the client.

The previous specification for the syntax of the language string  specified  by
xnlLanguage has been dropped to avoid potential conflicts with other standards.
The language string syntax is now implementation-defined.  The  example  syntax
cited is consistent with the previous specification.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 29 -


11.6.6.  Permanently Allocated Strings

In order to permit additional memory savings, an Xlib interface  was  added  to
allow  the  resource  manager  to  avoid copying certain string constants.  The
Intrinsics  specification  was  updated  to  explicitly  require   the   Object
class_name,   resource_name,  resource_class,  resource_type,  default_type  in
resource tables, Core  actions  string  field,  and  Constraint  resource_name,
resource_class,  resource_type,  and  default_type  resource  fields to be per-
manently allocated.  This explicit  requirement  is  expected  to  affect  only
applications that may create and destroy classes on the fly.

11.6.7.  Arguments to Existing Functions

The  args  argument  to  XtAppInitialize,   XtVaAppInitialize,   XtOpenDisplay,
XtDisplayInitialize,  and  XtInitialize  were changed from Cardinal* to int* to
conform to pre-existing convention and avoid otherwise annoying typecasting  in
ANSI C environments.

11.6.8.  Implementation

Function prototypes are now fully supported in the header files.

<X11/Intrinsic.h> no longer includes <X11/Xos.h> by default.  Inclusion of this
file  was a bug in earlier releases.  If you have old code that depends on this
bug, you can define -DXT_BC when you compile to get back the old behaviour.

String constants are now defined in a single array, saving memory and  external
symbols.   Note  that because the new implementation uses #defines, string con-
stants in widget header files which duplicate a constant defined by  Xt  should
either be removed or protected from a collision.

The translation manager facilities have been completely reimplemented  in  this
release,  resulting in substantially less memory consumed by some applications.
A number of other memory-saving changes have been implemented,  and  in  a  few
cases execution time should be faster.

The default keycode to keysym translator deals with all Latin keysyms.

11.6.9.  Extension Events

Unfortunately, the Xt standard as of R5 still does not address  the  issues  of
integrating events from protocol extensions into the normal Xt dispatch mechan-
ism.  The adventurous will find a set of patches to Xt in  contrib/lib/Xt  that
attempt to address this problem.  These patches are non-standard, experimental,
subject to change, not guaranteed, may adversely affect your ability  to  apply
public patches from MIT, and have not reviewed by the X Consortium.

11.7.  PEX

The PEX Sample Implementation (SI) is composed of several parts. The major com-
ponents  are  the extension to the X Server, which implements the PEX protocol,
and the client side Application Protocol  Interface  (API),  which  provides  a
mechanism  by  which  clients can generate PEX protocol.  The API provided with
the PEX-SI is the ISO IS PHIGS Binding and the yet  to  be  standardized  PHIGS



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 30 -


PLUS Binding.

In addition to these major components, several other minor components are  pro-
vided.   These  include documentation, 3D fonts for PEX, demos, and a verifica-
tion suite called InsPEX.  Also provided in contrib are additional example pro-
grams and demos.

These elements are located in the following area:

The   PEX   server   extension   is   located   in   the   directories    under
mit/extensions/server/PEX.    Device   independent   portions  are  located  in
mit/extensions/server/PEX/dipex.  Device  dependent  functionality  appears  in
mit/extensions/server/PEX/ddpex.   Operating system font dependent code appears
in mit/extensions/server/PEX/ospex.  General purpose server include  files  are
in mit/extensions/server/PEX/include.

The API code  is  located  under  the  directory  mit/extensions/lib/PEX.   The
PHIGS/PHIGS PLUS Binding routines are in the c_binding subdirectory.  The PHIGS
Monitor (PM), a separate process started at  client  runtime  to  handle  PHIGS
Input  functionality,  is  in  the  cp subdirectory.  Other code located in the
various subdirectories handles PHIGS archival, error  handling,  and  comprises
the internal library level that PHIGS calls to generate the PEX Protocol.

All PEX documentation is located in the directory mit/doc/extensions/PEX,  with
pregenerated PostScript files in mit/hardcopy/extensions/PEX.  The PEX Protocol
Specification itself is in the Proto subdirectory.  All SI documentation is  in
the  SI  subdirectory.   Three  subdirectories  there  contain  an Architecture
Specification, a Porting Guide (with  implementation  details),  and  a  User's
Guide.   The  sources  and programs used to generate these files are located in
the mit/doc/extensions/PEX/SI directory.  Also located there is the PHIGS  sub-
directory which contains PHIGS man pages and macros for printing these pages.

Font source for PEX and utilities to build them are located  in  the  directory
mit/fonts/PEX.  Two stroke fonts are supplied.

The PEX verification tool InsPEX can be found in the mit/extensions/test/InsPEX
directory.   Shell  scripts are provided there to run InsPEX.  More information
on InsPEX is available in the User's Guide.

Demos for PEX can be found in the mit/demos directory.  Two demos and the  NCGA
Graphics  Performance  Characterization  (GPC)  Suite  can be found there.  The
demos are in the mit/demos/auto_box and mit/demos/beach_ball  directories,  and
are  named  auto_box  and  beach_ball  respectively.  The GPC suite is found in
mit/demos/gpc.  This suite consists of demos  (in  the  objects  subdirectory),
benchmarks  (various  directories  below benchmarks) and tests (in tests).  For
more information on how to run these demos see the User's Guide.

There are also several unsupported demos and examples available in contrib.  In
contrib/demos/beach_ball2  a newer version of the beach_ball demo with enhanced
functionality can  be  found.   In  contrib/examples/PEX  various  PHIGS  based
clients that demonstrate how to use PEX via the PHIGS API are available.






X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 31 -


11.7.1.  Standards and Functionality

This release conforms to the PEX Protocol  Specification  V5.0P.   The  release
comes  with 2 fonts, Roman and Roman_M (see the User's Guide for more details).
It implements the minimum required HLHSR (Hidden Line/ Hidden Surface  Removal)
for PHIGS compliance (i.e., NONE).  The release only supports 8-bit color.

The API binding has been updated to the ISO IS PHIGS  binding.   The  directory
mit/util/PEX  contains  sed  scripts  for converting programs from the previous
binding to the new binding.  These scripts do most of the work, but some manual
editing  is  still needed.  There is a README file in this directory with notes
and information.

The PHIGS Binding provides most PHIGS/PHIGS PLUS functionality.  The full PHIGS
Input Model (Valuator, Locator, Stroke, Choice, String, Pick) is implemented in
a device independent manner using the  Athena  Widget  Set.   PHIGS/PHIGS  PLUS
functionality  includes,  but  is not limited to the following graphical primi-
tives:  Polylines, Polymarkers, Fill Areas, Triangle Strips, NURBS  Curves  and
Surfaces,  2D  and  3D  Text.  Other operations include Depth Cueing, Modelling
Clip, Backface removal, Lighting Models and Surface Reflection.

Functionality not completed in this release is as follows:

In the API:

     Mapping of PHIGS font ids to PEX fonts

In the Server:

     Backface Attributes and Distinguish Flag
     Font sharing between clients
     Patterns, Hatches and associated attributes
     Color Interpolation
     Transparency
     Depth Cueing for Markers
     Z-buffering
     Double Buffering

In InsPEX:

     Completion of port to ISO IS PHIGS Binding

11.7.2.  PEX and PHIGS Documents

The following documents are provided with this release:

     PEX-SI User Guide
     PEX-SI Graphics Library Manual Pages
     PEX-SI Architecture Specification
     PEX-SI Porting Guide

They are located in subdirectories of mit/doc/extensions/PEX.  Please read  the
PEX-SI  User's  Guide  for  descriptions  of the documents and how to use them.
Instructions for printing the documents are provided in a README file  in  each



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 32 -


of the document directories.

The User's Guide is provided as a starting  point  in  the  documentation.   It
describes  the  various  documents  provided  with  the  release,  and includes
instructions on using the clients, the  API  and  the  server  code.   It  also
includes specifications for the server functionality and archive format.

The Graphics Library Manual Pages are for the client-side library,  written  to
the ISO IS binding.

The Architecture Specification describes the  PEX-SI  architecture  at  a  high
level.

The Porting Guide is intended as an extension to  the  Architecture  Specifica-
tion.  There is a lot of good information in this document, and it is organized
fairly well, but it lacks some polish.  It is not a complete document.

11.7.3.  InsPEX

This release of InsPEX includes coverage of all the PHIGS PLUS graphics  primi-
tives, such as fill area sets with data, quadrilateral meshes, triangle strips,
and NURBS.  PHIGS PLUS attributes such as  direct  color  specification,  depth
cuing, and lighting are also exercised.

The testing of input is somewhat limited by the problem of simulating mouse and
keyboard  input in a reliable and portable fashion.  For the pick, locator, and
stroke devices, simulating the mouse events is straightforward, but  since  the
string,  valuator,  and choice devices are built upon a toolkit (Athena Widgets
in the PEX-SI's case), getting window id's  for  the  appropriate  windows  and
sending mouse clicks to the right place on those windows is more difficult, and
probably impossible to do in a way that could  be  quickly  ported  to  another
toolkit  along  with these input devices.  The technology for automatic testing
of software using a graphical user interface under X has not progressed to  the
point where this functionality could be tested in a way that would be useful to
all the potential users of InsPEX.

For nearly all of the tests that use image comparison to verify graphical  out-
put, reference images have been supplied.  Due to outstanding bugs in the code,
however, some tests are shipped without reference images.   Also,  since  back-
facing  attributes  are  not  implemented, the images saved for these tests are
actually incorrect.  These have been shipped, however, because they  still  can
be  helpful  to  someone  porting  the PEX-SI.  It should be expected that when
backfacing attributes are implemented, these tests will  fail  and  image  com-
parison will be required.

Along with the README in the main InsPEX directory, there is a sample log file,
sample.log,  and  an  automatically-generated summary of all the current tests,
test_descrip.  See the README for a description of how that file was generated.

11.8.  Athena Widget Set

Many minor bugs have been fixed.  The Xaw examples have been moved to  contrib.
However,  please  note that the Athena Widgets have been and continue to be low
on our priority list, so many bugs remain (particularly in the Text widget) and



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 33 -


many  requests for enhancements have not been implemented.  Because some incom-
patible changes have been made, the shared library major version number on Suns
has been incremented.

Header Files

     Function prototypes have been added to the public interfaces.

AsciiSrc

     No warning message is printed when the file  cannot  be  written  to;  the
     return  value should be enough info.  GetValues on the string resource was
     failing when "useStringInPlace" was set to true;  fixed.   A  memory  leak
     when  freeing  pieces in a source of type "ascii String" has been plugged.
     The buffer is now updated whenever the  "string"  resource  is  set  using
     XtSetValues.  If the type is file then the file is read in again.

Box

     Box.h now includes <X11/Xmu/Converters.h> for the orientation resources.

Clock

     Changed to be a subclass of Simple instead of Core.

Command

     A bug in changing the shape style back to Rectangular has been fixed.

Dialog

     The Icon resource type has changed from Pixmap to Bitmap.

Form

     The geometry handler now will now disallow  geometry  management  requests
     that  will force the child outside the Form's window.  EdgeType names have
     been changed to have prefix ``Xaw'' instead of ``Xt'', but the old defini-
     tions  are still around with a #define.  The string-to-widget converter no
     longer caches resources.

Logo

     Changed to be a subclass of Simple instead of  Core.   Reverse  video  now
     works correctly.

Mailbox

     Changed to be a subclass of Simple instead of  Core.   Reverse  video  now
     works correctly.

MenuButton

     The MenuButton widget no longer places a server grab on itself.   Instead,



X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 34 -


     PopupMenu  is  registered  as a grab action.  As a result of this, clients
     which popped up menus without using XtMenuPopup or MenuPopup or  PopupMenu
     in  the  menu  button  translations will fail to have a grab active.  They
     should make a call to XtRegisterGrabAction on the  appropriate  action  in
     the application initialization routine, or use a different translation.

Paned

     Paned.h now includes <X11/Xmu/Converters.h> for the orientation resources.

Panner

     This widget is new in R5, see the Xaw manual for details.

Porthole

     This widget is new in R5, see the Xaw manual for details.

Repeater

     This widget is new in R5, see the Xaw manual for details.

Scrollbar

     Changed to be a subclass of Simple instead of Core.   The  type  of  thumb
     resource has changes from Pixmap to Bitmap.  However, if applications pro-
     vide the resource conversion, the SetValues method can still  handle  pix-
     maps of correct depth.

Simple

     A color cursor converter has been added, as well as the new  new  resource
     types: XtNpointerColor, XtNpointerColorBackground, and XtNcursorName.

SmeBSB

     The Right bitmaps are now painted in the correct location.  Right and Left
     Bitmaps can be specified in resource files, and at startup time.

Text

     If there is no current selection the the selection extends from the insert
     point,  rather  than  some  random location.  Forward (Backward) Paragraph
     works at the paragraph boundaries now.  Selecting a word  now  transitions
     correctly  at both end points.  An infinite loop when using fill paragraph
     in a read only text widget has been found and fixed.   When  the  "resize"
     resource  is  set the text will start up with exactly enough space to con-
     tain the text in the widget.  A bug that could cause an infinite loop when
     Meta-Q  was used to invoke the form-paragraph function on a read-only text
     widget has been fixed.  Problems dealing with exposure  events  have  been
     fixed.   In  TextP.h,  the  names of the following symbolic constants have
     each had the prefix Xaw added to them: XawLF, XawCR, XawTAB, XawBS, XawSP,
     XawDEL, and XawBSLASH.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 35 -


Toggle

     The widget state is preserved across changes in  sensitivity.   A  string-
     to-widget converter is registered for radio groups.

Tree

     This widget is new in R5, see the Xaw manual for details.

Paned

     A bug that caused XtGeometryYes returns to have bogus values,  and  caused
     panes to get random sizes, has been fixed.

Vendor

     Support has been added for the editres protocol.  All  applications  using
     the  Athena  Widgets  are automatically editable with editres.  A bug that
     cause Shell to ignore all but first child has been fixed.

Viewport

     XawPannerReport support has been added.

11.9.  X Server

Considerably more work speeding up the server has been  done,  particularly  in
the  cfb  and  mfb  code.   The font interfaces are completely new.  Compressed
fonts are not supported in  the  release.   Other  changes  are  documented  in
mit/doc/Server/r5.tbl.ms.

11.10.  Fonts

Font Server

     A sample implementation of the server side of the X Font Service  Protocol
     is  provided in a new program, fs.  On the Macintosh, a special version of
     the server called MacFS can be used to serve TrueType fonts.

New Font Format

     Both the X server and the font server use a new font format, pcf (portable
     compiled  font).   Pcf  is readable across different machines and contains
     more information about a font than the old snf format.  Fonts in snf  for-
     mat can still be used.

Font Applications

     The following new utilities talk to the font  server:  fsinfo,  fslsfonts,
     fstobdf,  and showfont.  To build pcf fonts, bdftosnf has been replaced by
     bdftopcf.






X Window System Release Notes   August 29, 1991         X Version 11, Release 5





                                    - 36 -


Scalable Fonts

     Bitstream, Inc. has donated an outline scaling engine along with a set  of
     sample  fonts,  matching the donated bitmap fonts included with Release 4.
     In addition, a usable (but not very pretty) bitmap scaling engine has been
     implemented  which  allows  the  use of all other fonts at arbitrary point
     sizes.

Font Changes

     Many misc fonts now have ISO Latin-1 upper half characters and  some  tun-
     ing.   The  following  sets  of  fonts  are new: Latin/Hebrew in ISO8859-8
     encoding, Kanji in JISX0208.1983-0  encoding,6  Hangul  in  KSC5601.1987-0
     encoding.

12.  Acknowledgements

The MIT Release 5 distribution is brought to you by the MIT  X  Consortium.   A
cast  of thousands, literally, have made this release possible.  We cannot pos-
sibly acknowledge them all here.  The names of all people who made it a reality
will  be found in the individual documents and source files.  We greatly appre-
ciate the work that everyone has put into this release.

                              Hoping you enjoy Release 5,

                              Donna Converse
                              Stephen Gildea
                              Susan Hardy
                              Jay Hersh
                              Keith Packard
                              David Sternlicht
                              Bob Scheifler
                              Ralph Swick

                              (R5 Survival Club)









_________________________
6.  The JIS Kanji fonts were purchased on behalf of the MIT X  Consortium  from
the  Japanese  Standards  Association,  1-24,  Akasaka 4, Minato-ku, Tokyo 107,
Japan.  They were converted to BDF format, keeping within the  JIS  rules.   In
keeping with JIS rules, these fonts should not be transformed into other encod-
ings, they should only be used in the JISX0208.1983-0  encoding.   It  is  also
strongly  recommended  that  companies wishing to use these fonts in commercial
products should purchase the original JIS font  standards  directly  from  JSA.
The purchase price is nominal.




X Window System Release Notes   August 29, 1991         X Version 11, Release 5
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦f17ef2de4⟧ TextFile

Derivation

TextFile
