General information, mostly for authors of ePiX modules :)

July 25, 2002


ePiX is a preprocessor that creates high-quality, mathematically
accurate figures for the mathematical typesetting program LaTeX . The
"program" is implementated as a C++ library and a shell script. A
source file is a short C/C++ program that is linked against the
library, and whose executable writes the desired output file. The C++
compiler is therefore an integral part of ePiX.


DESIGN

The design philosophy of ePiX is evolving, but there are a few short
guidelines that are likely to be permanent: ePiX should be

1. largely backward-compatible.
2. easy to learn and use.
3. easily customized at compile time.

In particular, function names should be well-chosen (or private:) so
as not to require renaming in the future. Mnemonic names are best; if
possible, function names should mimic LaTeX or standard mathematical
usage, e.g., 
  cis(t), which defines the <pair> cos(t) + i*sin(t),
  marker(P(a,b), OPLUS), which puts an \oplus at (a,b).


NAMESPACE

Short names are preferred over long names, but good short names should
be reserved for routines that are frequently called by the user. The
only one-letter routines in ePiX currently are "P" and "V", which
create an ordered pair or triple data structure from two or three
doubles. (Specifically, P(a,b) and V(a,b,c) are pairs, P(a,b,c) is a
triple.) Because C++ allows overloading, there is leeway in naming new
functions, but it is still desirable to use the namespace judiciously.
A new user should be able to read an ePiX source file and
have a good idea what the file depicts; function names should be
self-commenting to the extent possible.

There is no harm in having multiple functions perform the same task,
particularly if it is mathematically natural to do so. For example,
ellipse, arc, hyperbolic_line, and disk_line all draw arcs of circles,
but each meets a specific need.


CUSTOMIZABILITY

It is best if hard-wired constants that affect the output appear in
#define statements and/or are marked prominently in the source with a
comment containing the string "Magic number". Ideally, the user should
be able to change these constants at compile time. Examples of such
constants include EPIX_FILE_WIDTH, the width of the output file in
columns; EPIX_DIAM, the diameter of spots and circs in true points;
and EPIX_ARROWHEAD_WIDTH, which determines the half-width of arrows in
true points.


MODULE DEPENDENCIES

At version 0.8.5, ePiX contains the following headers, which include
each other as shown:

globals.h
    ^
    ^
 pairs.h
    ^
    ^
triples.h
    ^
    ^
lengths.h
    ^
    ^
output.h    
    ^
    ^
objects.h < < plots.h < < arcana.h
    ^           v
    ^           v
curves.h    functions.h
    ^           ^
    ^           ^
     geometry.h

At compile time, these headers are concatenated (with some filtering)
by the "make_header" script into the complete header file "epix.h",
which is installed in /usr/local/include (by default). It is essential
to run "make clean" before "make"-ing a header file for installation.

An ePiX module consists of code (module.cc) and a header (module.h).
Here and below, "module" and "MODULE" should be replaced by a short,
descriptive name, of course. The code file should contain the following
proprocessor directives:

#define _EPIX_COMPILE
#include "module.h" 

The header should start:

#ifndef _EPIX_MODULE
#define _EPIX_MODULE
 
#ifdef _EPIX_COMPILE
#include "some_header.h"
#endif  

"some_header" should be replaced by the lowest header in the hierarchy
that is required by the module, such as "pairs.h" or "objects.h". The
compiler symbol _EPIX_COMPILE ensures that all higher headers are also
included.