Currently, GeX is the most rapidly developing part of the VTeX system. The online documentation we provide is not likely to be ever complete since new features become frequently.


Why GeX?

Starting with version 6.2, VTeX's PDF backend includes an integrated PostScript processor. This allows easy one-pass handling of GeX replaces the lengthy and bug-prone 3-pass model of

with straightforward one-pass .tex to .pdf conversion.

GeX vs GhostScript

Comparing to .eps inclusion done by GhostScript (or epstopdf) calls, GeX offers much better performance and output quality. Inline PostScript inclusion, on the other hand, is a totally new feature: this is this a feature that only VTeX/GeX supports. The advantage of GeX over GhostScript image embedding is apparent from the following pictures:
GeX
GS

Here we include the same .eps file with both GeX and GhostScript (a new \special{GS+}/\special{GS-} was added to VTeX just for the sake of this comparison). Besides being cleaner, the first picture (GeX output) takes less space and takes less time to compile.

Note: The images in this HTML version of documentation are cropped and magnified; see the PDF documentation for more juicy details.

Note: Three main differences between the pictures are: (1) GhostScript rasterizes fonts into bitmaps, GeX keeps them as Type1; (2) Color rendering done by GeX is identical to what would be produced by Acrobat but different by what is done by GhostScript; (3) some words for unclear reasons dissappeared from the GhostScript output, they are present in both GeX and Distiller outputs. "Running" is set in different fonts: the original picture did not provide the font used for this word; the substitution performed by GeX and GhostScript were different and neither is at fault here.

For reference, this is the VTeX code used to place the pictures:
\hbox to \textwidth{
||\includegraphics[width=5cm]{olympics.eps} \hss
\special{GS+}%
\includegraphics[width=5cm]{olympics.eps}%
\special{GS-}%
||%
}

The .eps inclusion is likely to be the main initial application of GeX. However, in our view it is the inline PostScript which would lead to new and interesting applications.

Why call it GeX?

The GeX name [pronounced g-e-k-s] stands for Graphics EXtensions.

While the current extensions are generally compatible with the PostScript language, GeX is intended to be a TeX-resident extension, not an Acrobat clone. Even in the current implementation there are facilities for communication between TeX and PostScript; these facilities are likely to be further developed. While it is our intention to stay PostScript-compatible to a degree needed for .eps and inline PostScript support we envision further enhancing GeX with features that are decisively non-PostScript.


Using GeX

To enable GeX, use the

-ox

switch on the VTeX command line. GeX initialization will take place only when GeX is explicitly called for the first time. Notice that GeX works only in the PDF backend mode; in other modes the switch will be ignored.

Note: The -ox2 switch will initialize GeX in Level II PostScript mode.

Troubleshooting

GeX initialization would fail if GeX cannot locate the base fonts.

GeX requires the base-13 fonts to be available. Make sure that the aliasing.pst file lists them and that the .tfm files for them are in tfm.lib.

The base-13 fonts are the 4 variants of Times, Helvetica, and Courier each, plus the Symbol font.


GeX Syntax

Supported PostScript operators

GeX currently supports a large subset of PostScript, including most of Level I implementation and some Level II operators.

Since not the full PostScript operator set is supported, it is possible (and even easy) to write a valid PostScript code which will be rejected by GeX; on the other hand, the supported subset includes all the ``practically'' used operators, so GeX would handle correctly most .eps that do appear in vivo. Testing of GeX on a large random set of .eps files downloaded from Internet shows that GeX correctly handles more than 99% of them. The supported instruction set at this time consists of 221 PostScript operators and several extension operators described below.

Supported additional operators

The following additional operators are understood by GeX.

TeX-GeX interface

The GeX engine is invoked from VTeX with the \special's:

Note that if you are going to use GeX primarily for inclusion of ready-made .eps files, you should use a high-level package like graphics rather than VTeX's \special's.

In GeX mode, VTeX allows to precede a \special with the \immediate command. \immediate \special's are passed to GeX right away, while TeX is still doing formatting. At this time there is no way to use the .pdf code that could be generated during the execution of an \immediate \special; however, the GeX kernel can be used for computations; and the results of such computation can be passed back to TeX. One practical example of this is the letterspacing implementation.

To report the results from GeX to TeX, set the \psconsole integer parameter to a number between 0 and 255:

\psconsole=100

This instructs GeX to write the output to the \toks### register rather then to the console (### is the number passed via \psconsole. By default, \psconsole is set to -1 and GeX output goes to the .log file; when \psconsole is in the 0--255 range, the output goes to the corresponding \toks register.)

The output is always appended to \toks; multiple outputs from GeX get concatenated within the \toks register. The only ways to clear the \toks register are via a TeX assignment

\toks100={}

or by restoring the register on a TeX group closing.

Notice further that you should use the PostScript print operator to place information into a \the\toks register. This is because the other output operators (=, pstack) append newline characters and the resulting contents will be difficult to parse in TeX. (Also, the actual format of the output of these operators may change in the future versions of GeX.) Since print allows only string arguments, you may need to use the cvs operator to convert other PostScript types to strings (see an example below).

If you intend to retrieve information from GeX with \immediate\special, make sure to flush GeX output once at the beginning:

\immediate\special{pS: }

The reason for this is that GeX is initialized when a first \special{pS:...} is encountered; during its first-time initialization it produces some output which normally goes to the .log file and you do not want to be appended to the \toks variable. Supplying an empty call to GeX forces it to be initialized and the initialization output to be written to the .log file.

Here is a small example of using GeX inline:
\documentclass{article}
\begin{document}

\immediate\special{pS: \the\year\space srand}
% This also will initialize GeX

\def\rand{%
\immediate\special{pS: }%
\psconsole 100
\immediate\special{pS: rand 10 string cvs print}%
The number is = \the\toks100.
\psconsole -1
\toks100={}
}

\rand\par\rand\par\rand\par
\end{document}

[You may want to cut out the text of this example and try it yourself.]

GeX version 6.3 supports these additional extensions operators:



PDF Bugs

Unfortunately, both the PDF standard and Adobe's implementation are not bug-free. Some of the more interesting bugs are described here.

Degenerate matrices

Near-degenerate matrix transforms cause a serious problem with the Acrobat's 16-bit computational limit. It can be shown that the problem is not solvable correctly in general; and Adobe Acrobat Distiller would fail on degenerate transforms.


The example file
% lwid.ps
0 0 moveto
gsave 100 200 lineto 2 3 scale 1 0 0 setrgbcolor stroke grestore
gsave 200 100 lineto 0.5 0.3 scale 0 1 0 setrgbcolor stroke grestore
gsave 200 200 lineto 0 0 1 setrgbcolor
[0.186718 -0.565306 0.873838 -2.64563 0 0] setmatrix
stroke grestore
showpage

should produce three lines from the origin. Distiller, however, will miss the blue line. GeX, on the other hand, will produce correct output:

Near-degenerate matrices are not a perverted abberation: they tend to be generated by some common software, especially the CorelDraw. The particular set of numbers in the source above came from a Corel example.

While GeX does the work correctly in all cases, some distortion in the line widths is possible and is not avoidable.

Level 1 strokeadjust

Some graphics programs (Freehand is one) output Level I PS code which fits the coordinates to an integer grid. This code, if executed literally, will produce rather disasterous results with GeX (left):

The nature of the problem is a bug (or feature) in the Freehand adjustment code which does not bother to check for the device matrix and assumes that it corresponds to the output pixel resolution of 300 dpi or higher (which would imply a device matrix [N 0 0 N .. ..]; N>4). However, the GeX device matrix is chosen to be an identity, to avoid extra rounding by TeX's->GeX's coordinate translation. This causes extremely coarse coordinate rounding. To avoid this problem, set the \GeXinnerscale counter to at least 4. The example above, for example, was produced with
\hbox to \textwidth{
||\includegraphics[width=5cm]{gears.eps} \hss
GeXinnerscale=4%
\includegraphics[width=5cm]{gears.eps}
||%
}

Notice that the Level II strokeadjust operator does not cause a problem since it is totally ignored by GeX.

Font name collision bug

There seems to be a bug in many versions of Acrobat which results in (different) fonts with names starting with |------... being treated as a single font. To avoid this problem, we replace such names with |xxxxxx.... This, however, would cause a collision if you actually have a font with such name installed.

Encoding bug

Under Windows, the Acrobat seems to ignore the /StandardEncoding specification and uses the WinAnsiEncoding instead. This may lead to incorrect character substitution for some codes in the 2nd half of the ASCII set. To overcome this problem, we always include the encoding vector, even if the font is not reencoded.

Dirty Tricks

show redefinition

In order to accomodate packages such as PSTricks and PSFrag, VTeX keeps track of redefinition of the show PostScript primitive within the GeX engine. In addition to supporting the mentioned packages, this allows rather nice font effects to be implemented with very simple inline code.

Simple outline

The below examples were produced with the

\def\outl#1{\special{pS: save /show{false charpath stroke}def}
#1\special{pS: restore}}

macro.

Wider outline with color

The

\def\outla#1{\special{pS: save /show{false 3 setlinewidth 1 0 0
setrgbcolor charpath stroke}def} #1\special{pS: restore}}

macro produces

Filled letter with outline

The

\def\outlb#1{\special{pS: save /show{false charpath gsave 2 setlinewidth
1 0 0 setrgbcolor stroke grestore 0 1 0 setrgbcolor fill}def}
#1\special{pS: restore}}

macro produces

Charpath shown

We can also get inside the character representation (something which PostScript would not do on Type 1 fonts):

\def\outlc#1{\special{pS: save /show{false charpath gsave
0 setlinewidth
1 0 0 setrgbcolor
stroke grestore
0 setlinewidth 0 0 0 setrgbcolor
{rct}
{rct}
{rct 1 0 0 0 setcmykcolor rct rct 0 0 0 setrgbcolor}
{} pathforall }def}
#1\special{pS: restore}}

to obtain:
Here is a magnified fragment of the same picture:

Fragment repositioning

Several examples in PSTricks use the PostScript commands to move the text around in order to land it in an appropriate place on a drawing. VTeX keeps track of PostScript attempts to group the TeX output; when such activity is detected, VTeX generates PostScript code rather than PDF and feeds this code into the GeX engine. \newpage

Letterspacing

Here is a feeble attempt in implementing letterspacing. Since Knuth explicitly warned against TeX supporting letterspacing, we accomplish this in GeX.

All examples below will letterspace with extra 2-pt space.

Thus,

\immediate\special{pS: /k 2 def}%

Notice that \immediate\special is not normal TeX: it causes a backend special to be evaluated right away, rather than waiting for the output cycle. Let
\def\forcefont{\hbox to 0pt{\phantom{!}}} \def\as#1{\forcefont\special{pS: k 0 (#1) ashow}}

A first attempt is to simply plug-in ashow:
Letterspacing: \as{Letter-spaced text here.}!

to obtain

does not work very well: the exclamation mark overlaps the L. Indeed, there is no way TeX would know how much space the \special would need.

Here is a macro that will measure the required width:

\newdimen\tmpz
\def\sw#1{%
\forcefont
\psconsole 255
\immediate\special{pS: (#1) dup stringwidth pop exch length 1 sub k mul add
10 string cvs print}%
\message{Result=[\the\toks255]}
\tmpz=\the\toks255pt
}

We call GeX in the \immediate mode since we want to reuse the result to set the string.

\sw{Letter-spaced text here.}

Now, it will work correctly:

Letterspacing: \hbox to \tmpz{\as{Letter-spaced text here.}\hss}!

Note: Of course, it makes more sense to write a single macro but this example is provided for illustration purposes only.

Note: Even more sense would be to build the output code in the \immediate phase and re-use it later (one call to GeX, rather than two); such a feature might be added later.

Note: One possible pitfall: GeX executes a save-restore pair on each emitted page. Thus it is important to assure that no page breaks would occur in the middle of calls to GeX.


Special Cases

PSTricks

GeX can handle PSTricks files. Notice that in order to deal with some of the more tricky tricks, GeX plays some tricks of its own. Two tricks that appear in PSTricks are show redefinition and fragment repositioning.

PSFrag

GeX can handle PSFrag files. The entire PSFrag system is built around the fragment repositioning hack.

MetaPost

While GeX can handle MetaPost-generated files, it is important to state that MetaPost outputs invalid EPS files. Rather than use the standard fonts or embed fonts into the EPS, MetaPost merely includes declarations like

/cmr10 /cmr10 def

and expects post-processing to find and substitute the fonts. Instead of such post-postprocessing, GeX ignores (processes, which is the same really) this declaration, but requires either explicit loading of needed fonts via the .loadfont extension

\special{pS: /cmr10 .loadfont}

(one such command for each required font) or enabling of the autoloading feature via the .autofontload extension

\special{pS: 1 .autofontload}

These commands must be issued before a MetaPost-generated file is actually included.