This file belongs to the MFTOEPS package.

-----------------------------------------------------------------------------

OVERVIEW

The package MFTOEPS belongs to the public domain. You are entitled to do with
the files of which it consists whatever you wish. If you alter a file,
however, please remove the line containing the comment

              `This file belongs to the MFTOEPS package.'

in order to avoid a mess.

The kernel of this little package is the METAFONT program MFTOEPS.MF written
by Bogus\l{}aw Jackowski, Piotr Pianowski and Marek Ry\'cko. The aim of the
program is to produce EPS (encapsulated PostScript) files readable by
CorelDRAW!(R), Adobe Illustrator(TM) and Fontographer(R).

The user of the package is supposed to be familiar a bit with METAFONT and
PostScript. Donald E. Knuth's ``The METAFONTbook'' and Adobe's ``PostScript
Language Reference Manual'' (both by Addison-Wesley Publishing Company, Inc.)
should be consulted in the case of doubts.

There is a bunch of simple examples in the subdirectory M2ESAMP. The
directory ../PROGS contains DOS batch files and other programs which,
possibly after some adjustments, can be used to generate EPS files.

Roughly, the machinery works as follows: the resulting PostScript code
is written by METAFONT to a LOG file; the LOG file is then processed
either by AWK or by TeX (see the PROGS subdirectory) in order to extract
the PostScript code. The idea seems straightforward; however, even
a partial conciliation of the worlds of CorelDRAW! and Adobe Illustrator
was not so much straightforward.

-----------------------------------------------------------------------------

In addition to the main MFTOEPS package, there are two ``bonus'' packages in
directories ../EPSTOMF and ../ROEX. EPSTOMF converts ``canonical'' EPS files,
i.e., files conforming the structure of the files generated by the MFTOEPS
package, into the METAFONT lingo; ROEX is a set of METAFONT macros
accomplishing the task of removing overlaps and expanding strokes (for
details see there).

-----------------------------------------------------------------------------

INTERFACE SYNOPSIS

Conventions: In the following we shall use words `number,' `pair,' `string,'
and `path' as an abbreviation for `numeric expression,' `pair expression,'
`string expression,' and `path expression,' respectively. The signs `less'
and `greater,' used for marking parameters of macros, are
``meta-characters,'' i.e., they do not belong to the METAFONT code.

There are fifteen interface macros defined in the MFTOEPS.MF file:
          eps_mode_setup
          write_preamble
          write_postamble
          set_BB
          find_BB
          reset_BB
          fill_C
          draw_C
          clip_C
          fix_line_width
          fix_line_join
          fix_line_cap
          fix_line_miter_limit
          fix_fill_cmyk
          fix_draw_cmyk

COMMAND   eps_mode_setup
USAGE     eps_mode_setup <an optional number (0 or 1)>;
REMARKS   This command should be used instead of the usual |mode_setup|
          command. The forms |EPS_mode_setup| and |EPS_mode_setup 1|
          are equivalent. One of them (preferably the former one) should
          be used for normal processing. Invoking |EPS_mode_setup 0|
          is meant primariliy for testing purposes and is supposed
          to be used by experienced programmers who know what they are doing.
          There are two predefined constants in MFTOEPS.MF to be used in this
          context, namely, |no_export_level=0| and |compatibility_level=1|.
          It is advisable to use the names of the constants rather than
          bare numbers.

COMMAND   write_preamble
USAGE     write_preamble <string>;
REMARKS   This command initialises the process of writing of the PostScript
          code. The string expression is the name (without extension)
          of the resulting EPS file; the extension is always |.EPS|.
          METAFONT is switched to the |batchmode| in order to avoid
          slowing down the process by writing mess(ages) to the terminal.
          The inspection of the log file is thus highly recommended.

COMMAND   write_postamble
USAGE     write_postamble;
REMARKS   This command ends writing of the PostScript code, switches METAFONT
          back to the |errorstopmode|, and performs neccessary ``last minute''
          actions (see below).

COMMANDS  set_BB find_BB reset_BB
USAGE     set_BB <four numbers or two pairs separated by commas>;
          find_BB <a list of paths separated by commas>;
          reset_BB;
REMARKS   Commands |set_BB| or |find_BB| should be invoked prior to
          invoking |write_preamble|. |set_BB| sets the coordinates of
          the corners of the bounding box of a graphic object; it is
          useful when the bounding box of a graphic object is
          known in advance or if it is required to force an artificial
          bounding box. |find_BB| computes the respective bounding box
          for a list of paths; if several |find_BB| statements are
          used, the common bounding box is calculated for all paths
          that appeared in the arguments. The result is stored in the
          variables |xl_crd|, |yl_crd|, |xh_crd|, and |yh_crd|.  There
          are two functions, |llxy| and |urxy|, returning pairs
          |(xl_crd,yl_crd)| and |(xh_crd,yh_crd)|, respectively. The
          last command, |reset_BB|, makes |xl_crd|, |yl_crd|,
          |xh_crd|, and |yh_crd| undefined (the initial situation);
          |reset_BB| is performed by the |write_postamble| macro,
          which is convenient in the case of generating several
          several EPS files in a single METAFONT run.

COMMANDS  fill_C draw_C
USAGE     fill_C <a list of paths separated by commas>;
          draw_C <a list of paths separated by commas>;
REMARKS   These commands are to be used instead of the usual
          METAFONT |fill| and |draw| ones. They cause that a list of paths
          followed by the PostScript operation |eofill| (|fill_C|) or |stroke|
          (|draw_C|) is translated to a PostScript code. The list of paths
          constitutes a single curve in the sense of PostScript.

COMMAND   clip_C
USAGE     clip_C <a list of paths separated by commas, possibly empty>;
REMARKS   The macro |clip_C| with a non-empty parameter works similarly to
          the |fill_C| command, except that the |eoclip| operator is issued
          instead of |eofill|. This causes an appropriate change of
          the current clipping area. According to PostScript's principles,
          the resulting area is a set product of the current clipping
          area and the area specified in the argument of the |eoclip|
          command. The empty parameter marks the end of the scope
          of the most recent |clip_C| command with a non-empty parameter.
          In other words, nested |clip_C| commands form a ``stack'' structure.
          If needed, the appropriate number of parameterless |clip_C|
          commands is issued by the |write_postamble| macro, thus
          the user needs not to care about it.
          WARNING: files produced with the use of |clip_C| are
          interpreted properly by Adobe Illustrator (provided paths
          directions are defined properly) but not by CorelDRAW! (ver. 3.0).

COMMANDS  fix_line_width fix_line_join fix_line_cap fix_miter_limit fix_dash
USAGE     fix_line_width <a non-negative number (dimension)>;
          fix_line_join <a number (0, 1 or 2)>;
          fix_line_cap <a number (0, 1 or 2)>;
          fix_miter_limit <a number greater or equal 1>;
          fix_dash (<a list of numbers (dimensions), possibly empty>)
                   <number (dimension)>;
REMARKS   These command are to be used in connection with the |draw_C|
          command. |fix_line_width| fixes the thickness of the outline.
          The other three commands correspond to PostScript operations
          |setlinejoin|, |setlinecap|, |setmiterlimit|, and |setdash| (see
          ``PostScript Language Reference Journal'' for details).

          All commands should be used after |write_preamble|, as
          |write_preamble| sets the default thickness (0.4pt), default
          line join (0), default line cap (0), default miter limit (10),
          and a solid line as a default for stroking (|fix_dash () 0|).

COMMANDS  fix_fill_cmyk fix_draw_cmyk
USAGE     fix_fill_cmyk <four numbers separated by commas>;
          fix_draw_cmyk <four numbers separated by commas>;
REMARKS   These commands define the colours of the interiors of graphic
          objects (|fix_fill_cmyk|) and colours of outlines (|fix_draw_cmyk|)
          using cyan-magenta-yellow-black model (basic model). They should
          be used after |write_preamble| (because |write_preamble| defines
          the black colour as a default for both macros) and prior to invoking
          the corresponding |fill_C| and |draw_C| commands, respectively.
          There are also (just in case) macros |fix_fill_rgb| and
          |fix_draw_rgb| using red-green-blue model; the argument to both
          macros is a triple of numbers. (The user can control the process
          of conversion from RGB to CMYK by the redefinition of macros
          |under_color_removal| and |black_generation|.) The numbers
          forming the arguments of the macros are supposed to belong to
          the interval [0..1].

ADDITIONAL FUNCTIONS pos_turn neg_turn
USAGE     pos_turn <primary path expression>
          neg_turn <primary path expression>
REMARKS   Each function returns the path passed as the argument,
          except that the orientation of the path is changed, if
          necessary: |pos_turn| returns paths oriented anti-clockwise,
          |neg_turn|---oriented clockwise. This may be
          usefull for creation pictures which are to be processed
          further by Adobe Illustrator, because this program is
          sensitive to the orientation of paths.

CONTROL VARIABLES yeseps yesEPS YESEPS
REMARKS   No EPS file will be generated unless one variable among
          |yeseps| or |yesEPS| or |YESEPS| is assigned a definite value.
          It is advisable to set this variable in a command line
          (see M2E.BAT and M2E-ALT.BAT in the PROGS directory).
          In fact, using |yeseps| is reccomended. Aliases |yesEPS|
          and |YESEPS| were introduced for ``historical'' reasons.

CONTROL VARIABLE testing
REMARKS   If the variable |testing| is assigned a definite value, the whole
          PostScript code is flushed to the terminal, thus slowing
          down significantly the process of generation of an EPS file
          (cf. the description of the |write_preamble| command).

-----------------------------------------------------------------------------

ENCOURAGEMENT

The inspection of the source code of the MFTOEPS.MF program may reveal
a few more useful macros.

-----------------------------------------------------------------------------

END OF THE 0MFTOEPS.DOC FILE