This ReadMe file describes why some changes to a user's environment are necessary to make TEX on a Mac usable in an X11.app based X11 runtime environment

This free software is intended to enable Mac OS X's X11 environment to use a TEX distribution installed somewhere in /usr/local. It solves the problems that X11 won't find TEX binaries or that it's not ad hoc possible to launch any X client from the command line in Terminal. The software creates entries in an X11 menu to launch X clients that might not exist on your system, but they're nice and useful! To accomplish the task it either changes four files or creates them, some from system templates, as X11.app would do also when launched for the first time.

The job they do is, they edit:

which makes them solve problems one surely encounters!

Problem no. 1: X11 does not find the TEX utilities

This happens although the Command Line Interface (CLI) was enabled by i-Installer or MacTeX's settexpath script or other means. The reason for this is that the system makes a difference between interactive and non-interactive (batch) shells and even between a login and a non-login shell. Mac OS X brings one more degree of complexity to it: its particular way to create a process environment, and the way a user is logged-on into the system. The latter effectively switches off the login shell's ability to set up itself by reading some specialised "dot rc" files (for example ~/.bashrc, ~/.bash_profile, ~/.bash_login for bash), at least in Mac OS X, which can be different on the OS' server version.

This all makes the means of editing the system's files /etc/csh.login and /etc/profile or a user's ~/.tcshrc (~/.cshrc) or ~/.bash_profile (or ~/.bashrc) files useless for the purpose of using X11. It even does not work to enhance ~/.xinitrc with the correct PATH value for all X clients, because it's the X server, a native Mac OS X application, from which all X clients inherit their own process environments. So it's the X server that needs to be taught and not the later launched set of a user's default X clients ...

The X server's primary teaching method is to (create and) edit the file ~/.MacOSX/environment.plist. The contents of this file is XML (eXtensible Markup Language), a list of mostly simple key/value pairs. The keys are environment variables' names like PATH, MANPATH, or DISPLAY. These and their values are copied into the process' environment upon its generation, i.e. when the X server X11.app or XDarwin.app, or whatever, is launched and can therefore be used at runtime by this server's inferior processes, the X clients, as well.

There is one side-effect of this scheme: it effects all applications running on your Mac! A faulty setting can make your Mac quite unusable. The easiest way to achieve this state is to change installation places or to move something from here to there, that the PATH value becomes faulty. The second and more real disadvantage is that you have in X11 only one TEX installation available. The means that i-Installer uses to offer you more than one TEX distribution to work with on your Mac, interfere. To become able to use distribution switching you might need to quit X11 before switching and to launch it again after switching. The script that tries to find the home of the TEX binaries first looks for /usr/texbin. If this exists then this value is saved and X11 is able to use any activated TEX distribution. Otherwise it will fail.

Problem no. 2: I can't launch an X client from Terminal

An X client, a programme that runs in the X11 Window System environment, needs to be told where, on which display, to open its window(s). This can be done on the command line with a particular argument, usually some '-d <value>' although the most useful method is via the environment variable DISPLAY. In Mac OS X's own windowing environment, Quartz, $DISPLAY plays no role, so it's not there in Terminal. One script, bash-script.sh or tcsh-script.sh, adds some code that determines a probabilistic or preliminary value of DISPLAY based on the number of other users logged-in to that Mac. The correct value of DISPLAY becomes determined later when the X server launches. This one then executes the file ~/.xinitrc which usually prepares and decorates a user's X11 Window System environment and launches a set of X clients. Here it additionally records the correct DISPLAY value in ~/.MacOSX/environment.plist, that Quartz applications launched afterwards have it set correctly. In Terminal the preliminary value of $DISPLAY cannot be corrected at this time any more from this 'remote' file, it can only be corrected by invoking manually the newly added internal 'updisp' command which upon execution reads the correctly updated value of $DISPLAY from ~/.MacOSX/environment.plist and (re-)sets it in this shell. And only in this shell!

Problem no. 3: how to launch an X client

The so-called usual way on Mac OS X and other windowing systems is via a menu. X11 offers two identical menus: one is in the  menu bar, the other pops up when you press the X11 icon in Dock and navigate to the programmes menu. From both these menus you can access an "editor" to change the menu contents, but it's also possible to do this from the command line via the defaults utility. The application or the scripts prepare some menu entries although some of them, gv, xpdf, fontforge, xv, are not regularly installed with MacTeX or the TEX i-Package. Texdoctk even cannot run because Mac OS X's Perl installation does not contain the Tk Perl module, although Mac OS X now brings TclTk to the desktop (the missing module can be installed quite easily with cpan from CPAN, the Comprehensive Perl Archive Network).

The other and maybe elder option is to launch the X clients from the command line. The shell in Terminal will have a DISPLAY value set, so the clients know where to open, the search path to find the X clients in the running shell will be contained in the PATH environment variable, both by having edited ~/.MacOSX/environment.plist before when running Make X11 aware of TeX on a Mac or the scripts. So you can just invoke '<X client> <options or arguments> &' and it will launch from Terminal! Provided the X server was already running.

Problem no. 4: some X clients in the menu do not exist or work yet

FontForge ("View Fonts") is an X client, formerly known as PfaEdit, you can install from an i-Package (as with Fink or MacPorts, the former DarwinPorts, too). If it's installed you can re-run i-Installer to create OpenType (OTF) font files of the Latin Modern TEX fonts for putting them into /Library/Fonts — good for XeTeX!

Xv ("View Images") is an old viewer (and convertor and kind of editor) for many graphics file formats (there is an effort going on to teach it JPEG2000!). It can be installed with Fink or MacPorts.

Texdoctk ("View TeX docs") is a Perl script that uses the Tcl toolkit Tk. It won't run because Apple, although bringing Perl and TclTk with recent Mac OS X versions, does not deliver the necessary interface Tk.pm between them. MacPorts does not seem to provide this interface, Fink has a few of them, each matching the system's Perl version. I am not sure whether the texdoctk script will work so easily with Fink's TK.pm package, because Perl, too, has the concept of search paths (the @INC hash) and the unusual Fink installation place would need to be explained to the system's Perl (probably in the configuration file /Library/Perl/<version number>/AppendToPath). So the best approach seems to be using cpan, a Perl script that can fetch sources from CPAN, compile, and finally install the Perl modules once they have passed the test examination, resolving all dependencies, too. Cpan needs a C compiler, best installed with the Developer Tools (meta) package from Mac OS X and possibly updated with Xcode packages (Fink and MacPorts can install pre-compiled binaries, but all depending packages would be needed in binary form also, otherwise they need a C compiler, too).

Xpdf ("View PDF") is a free PDF viewer application that also brings some useful command line utilities (pdfinfo, pdffonts, pdfimages, pdftoppm, pdftops, and pdftotext). MacPorts and Fink provide it.

Gv ("View PS or PDF") is a very fine viewer for PS or PDF files that uses Ghostscript to render the files' contents on the screen. MacPorts and Fink provide it. Gv looks better when libXaw3d is installed (from an i-Package for example).

Problem no. 5: un-doing what the application/scripts did

Problem no. 6: what kind of software is this?