Go backward to Ipe command line options
Go up to Top
Go forward to Interfacing with Ipe

The Ipe file format

Ipe stores files in the Integrated Picture Environment format. To my knowledge, this is the only file format that incorporates LaTeX text and Postscript drawing information into a single file. (Other systems like xfig or JPdraw can create pictures with both LaTeX and Postscript information, but need three different files: one for the internal format, one with LaTeX, and one with Postscript data.) At the same time, it is also an Encapsulated Postscript file, and can be included by other packages that can handle this EPS-format. You might wonder how all this is done.

Here is an example of an Ipe file, containing two text objects, one minipage object, and a polygon with six segments.

  %!PS-Adobe-2.0 EPSF-1.2
  %%Creator: Ipe 5.0
  %%BoundingBox: 205 345 394 454
  %%EndComments
  {\catcode37=9\def\IPEdummy{({{)}} pop
  %%}\makeatletter\let\@notdefinable\relax
  %%\def\IPEc#1[#2]#3{\newcommand{#1}[#2]{#3}\ignorespaces}\@ifundefined
  %%{selectfont}{\let\selectfont\relax\def\fontsize#1#2{}}{}\makeatother
  %%\IPEc\IPEput[4]{\put(0,0){\special{psfile=\IPEfile}}}
  %%\IPEc\IPEmp[2]{\minipage[t]{#1bp}#2\special{color pop}\endminipage}
  %%\IPEc\IPEtext[1]{\makebox(0,0)[lb]{#1\special{color pop}}}
  %%\IPEc\IPEfs[1]{\IPEcolfs{0 0 0}{#1}}
  %%\IPEc\IPEcolfs[2]{\dimen0=#2pt\fontsize{#2}{1.2\dimen0}\selectfont
  %%\special{color push rgb #1}}
  %%\IPEc\IPEsize[2]{\unitlength1bp\ignorespaces}
  %%\IPEsize{187}{106}
  %%\begin{picture}(187,106)(206,346)
  %%\IPEput{205}{345}{394}{454}
  %%\put(214,430){\IPEtext{\IPEfs{10}$s_0$}}
  %%\put(302,446){\IPEtext{\IPEfs{10}\rm this is the top vertex}}
  %%\put(306,398){\IPEmp{35}{\IPEfs{10}\rm inside a
  %%box life
  %%is nice}}
  %%\end{picture}\endinput}
  %% Ipe postscript prologue
  /IpeDict 60 dict def
  IpeDict begin
  /origmatrix matrix currentmatrix def
 
  /sg {setgray} bind def
  /sc {setrgbcolor} bind def
  /ss {0 setdash setlinewidth} bind def
  ... more Postscript definitions
  end
  end
  %% Ipe prologue end
 
  IpeDict begin 326 406 translate
 
  % Preamble 1
  %%\documentclass[a4paper]{article}
  % Group
 
  % Line
  % ss 0
  1.2 [] ss
  np % # 6
  -120 -60 mt
  60 -60 lt
  60 -20 lt
  -20 32 lt
  -40 -20 lt
  -100 20 lt
  cl % cl
  % fi
  0.8 sg fi
  % End
 
  % Text
  % xy -112 24
  % sk 0
  % f 3 10
  % s s_0
  % End
 
  % Text
  % xy -24 40
  % sk 0
  % f 0 10
  % s this is the top vertex
  % End
 
  % Text
  % xy -20 -8
  % bb 35.0094 30.85
  % sk 0
  % f 0 10
  % s inside a
  % s box life
  % s is nice
  % End
 
  % End
 
  end %% of Ipe figure

As you can see, after some initial balderdash, an Ipe file essentially consists of a single picture environment. This environment is hidden behind percent signs, the comment character in Postscript. This makes it possible to use the same file as a Postscript file--the Postscript interpreter does not see this part at all.

The magic sits in the line

   {\catcode37=9\def\IPEdummy{({{)}} pop

When the Postscript interpreter interprets this line, it has no effect. But when LaTeX reads it, it turns off the `%'-character--from that moment on, all percent signs will simply be ignored. This explains how LaTeX manages to look at the picture environment.

The next few lines define some commands used in the environment itself. They can be customized to scale the figure, or to adapt to a different dvi-to-Postscript converter. The command \IPEsize, for instance, was mentioned before. It is given the actual size of the picture, and is responsible to set unitlength, IPEscale, and IPEwidth. The next lines of the file contain the actual picture environment. It contains several entries placed with \put. The first entry is the magic one. It places a box containing a \special which includes the Ipe file again when the DVI-file is converted to Postscript, and at that time it will be interpreted as a Postscript file. The \Ipe command saves the file name of the file in macro \IPEfile, where it is re-used by \IPEput. Therefore, as long as you run LaTeX and dvips in the same directory, you don't have to worry about incorrect absolute path names.

The rest of the picture environment contains \put entries for the text objects. \IPEtext makes a box and interprets its argument in LaTeX's LR-mode. \IPEmp makes a minipage with the given width, and interprets its argument in paragraph mode. The \IPEfs macro calls the \IPEcolfs macro discussed before.

LaTeX reads the file up to the \endinput command, where it returns to the surrounding LaTeX document. Therefore it will not encounter the Postscript information, which comes later in the file.

The rest of the file contains Postscript data. First comes a series of definitions, constituting the Postscript dictionary IpeDict. These are the Postscript commands necessary to interpret the body of the Ipe file. Interspersed with the Postscript data there are the keywords that Ipe uses to read back the file itself, see ipe input.

To summarize: an Ipe file contains both LaTeX and Postscript information, and is actually read twice in the process of converting a LaTeX document to a Postscript file, once by LaTeX, and then again by dvips.