% language=us runpath=texruns:manuals/metafun

\startcomponent metafun-introduction

\environment metafun-environment

\starttitle[title={Introduction}]

This document is about \METAPOST\ and \TEX. The former is a graphic programming
language, the latter a typographic programming language. However, in this
document we will not focus on real programming, but more on how we can interface
between those two languages. We will do so by using \CONTEXT, a macro package
written in \TEX, in which support for \METAPOST\ is integrated in the core. The
\TEX\ macros are integrated in \CONTEXT, and the \METAPOST\ macros are bundled in
\METAFUN.

When Donald Knuth wrote his typographical programming language \TEX\ he was in
need for fonts, especially mathematical fonts. So, as a side track, he started
writing \METAFONT, a graphical language. When you read between the lines in the
\METAFONT\ book and the source code, the name John Hobby is mentioned alongside
complicated formulas. It will be no surprise then, that, since he was tightly
involved in the development of \METAFONT, after a few years his \METAPOST\ showed
up.

While its ancestor \METAFONT\ was originally targeted at designing fonts,
\METAPOST\ is more oriented to drawing graphics as used in scientific
publications. Since \METAFONT\ produced bitmap output, some of its operators make
use of this fact. \METAPOST\ on the other hand produces \POSTSCRIPT\ code, which
means that it has some features not present in \METAFONT\ and vice versa.

With \METAFUN\ I will demonstrate that \METAPOST\ can also be used, or misused,
for less technical drawing purposes. We will see that \METAPOST\ can fill in some
gaps in \TEX, especially its lack of graphic capabilities. We will demonstrate
that graphics can make a document more attractive, even if it is processed in a
batch processing system like \TEX. Most of all, we will see that embedding
\METAPOST\ definitions in the \TEX\ source enables a smooth communication between
both programs.

The best starting point for using \METAPOST\ is the manual written by its author
John Hobby. You can find this manual at every main \TEX\ repository. Also, a copy
of the \METAFONT\ book from Donald Knuth is worth every cent, if only because it
will give you the feeling that many years of graphical fun lays ahead.

In this \METAFUN\ manual we will demonstrate how you can embed graphics in a
\TEX\ document, but we will also introduce most of the features of \METAPOST. For
this reason you will see a lot of \METAPOST\ code. For sure there are better
methods to solve problems, but I have tried to demonstrate different methods and
techniques as much as possible.

I started using \METAPOST\ long after I started using \TEX, and I never regret
it. Although I like \TEX\ very much, I must admit that sometimes using \METAPOST\
is even more fun. Therefore, before we start exploring both in depth, I want to
thank their creators, Donald Knuth and John Hobby, for providing me these
fabulous tools. Of course I also need to thank \THANH, for giving the \TEX\
community \PDFTEX, as well as providing me the hooks I considered necessary for
implementing some of the features presented here. In the meantime Taco Hoekwater
has created the \METAPOST\ library so that it can be an integral component of
\LUATEX. After that happened, the program was extended to deal with more than one
number implementation: in addition to scaled integers we now can switch to floats
and arbitrary precision decimal or binary calculations. I myself prototyped a
simple but efficient \LUA\ script interface. With Luigi Scarso, who is now the
maintainer of \METAPOST, we keep improving the system, so who knows what will
show up next.

I also want to thank David Arnold and Ton Otten for their fast proofreading, for
providing me useful input, and for testing the examples. Without David's patience
and help, this document would be far from perfect English and less complete.
Without Ton's help, many small typos would have gone unnoticed.

In the second version of this manual the content was been adapted to \CONTEXT\
\MKIV\ that uses \LUATEX\ and the built in \METAPOST\ library. In the meantime
some \LUA\ has been brought into the game, not only to help construct graphics,
but also as a communication channel. In the process some extra features have been
added and some interfacing has been upgraded. The third version of this document
deals with that too. It makes no sense to maintain compatibility with \CONTEXT\
\MKII, but many examples can be used there as well. In the meantime most
\CONTEXT\ users have switched to \MKIV, so this is no real issue. In the fourth
update some new features are presented and the discussion of obsolete ones have
been removed.

The fifth update describes the \MPIV\ version of \METAFUN\ which brings some more
and improved functionality. Some examples are inspired from questions by users and
examples that Alan Braslau, Luigi Scarso and I made when testing new features and
macros. Some examples can be rewritten in a more efficient way but are kept as
they are. Therefore this manual presents different ways to solve problems.
Hopefully this is not too confusing. Numerous examples can be found in the other
manuals and test suite.

The first version of \METAFUN\ evolved in \CONTEXT\ \MKII, and when we moved to
\MKIV\ some interfaces (especially the extensions) could be made better. We now
have \LMTX\ so we can make even those better (and often easier). The downside is
that some features discussed here won't work in \MKII\ and \MKIV. If you run into
that, just consider updating to \LMTX. The current version should process okay
with the latest version; thanks to Otared Kavian for keeping an eye on that and
posting me possible issues. The real new features are part of what is to become
\LUAMETAFUN, but for that we have a separate manual.

In 2022 Mikael Sundqvist and I spent a lot of time on improving math in both
\LUAMETATEX\ and \CONTEXT\ \LMTX, which is now the main version. Because we're both
\METAPOST\ fans we let ourselves being sidetracked to also explore new possibilities
in the library. Some of the macros that evolved from that made it into \METAFUN\
which is why we also discuss some here. Be aware of the fact that we do some things
different in \LMTX\ than in \MKIV, for instance we moved to colors being specified
as strings (references to colors defined in \CONTEXT). There are also some new
features that are unique to the library in \LUAMETATEX, like \type {&&}, \type
{&&&}, \type {&&&&} and \type {nocycle}. THis means that not everything discussed
here works in \MKIV\ too.

\blank[big,samepage]

\startlines
Hans Hagen
Hasselt NL
\currentdate[month,year]
\stoplines

\stoptitle

\stopcomponent