new metapost release (1.803) documentation files

git-svn-id: svn://tug.org/texlive/trunk@30834 c570f23f-e606-0410-a88d-b1316a301751

9 files changed, 639 insertions, 143 deletions

diff --git a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
index 01f96ce402b..d1d0fcccc7d 100644
--- a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
index 019931a2783..8be16292908 100644
--- a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/mpintro.pdf b/Master/texmf-dist/doc/metapost/base/mpintro.pdf
index 97ecbd78560..29b6d37175d 100644
--- a/Master/texmf-dist/doc/metapost/base/mpintro.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpintro.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
index 3be7d5703d2..caabad494c1 100644
--- a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/mpman.pdf b/Master/texmf-dist/doc/metapost/base/mpman.pdf
index a5f889d2b7c..cafe45a9eee 100644
--- a/Master/texmf-dist/doc/metapost/base/mpman.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpman.pdf
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/TODO b/Master/texmf-dist/doc/metapost/base/source-manual/TODO
index 5b1a7aec305..0c99309afbc 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/TODO
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/TODO
@@ -31,18 +31,41 @@ mp-implementors list or alternatively the metapost list.
 ***   Wanted For Release  ***
 *****************************
 
+* Discussion of floating point vs. fixed point numbers:
+
+  + needs complete review of the manual ...
+
+  + description of new command-line option
+
+* Describe PNG backend.
+
+* Describe prescriptpart/postscriptpart.
+
+* Describe envelope primitive/macro.
+
+
+
+
+*****************************
+***   Short term issues   ***
+*****************************
+
 Integrating Text and Graphics:
-* (SH) Fix bad description of prologues in table ivartab.
-* (SH) Move discussion of prologues to sec. workflow2.
+* Fix bad description of prologues in table ivartab.
+* Move discussion of prologues to sec. workflow2.
+
+Advanced Graphics:
+* Describe turningnumber (mention differences in sec. 'MetaPost
+  Versus METAFONT').
 
 Notes on the MetaPost Workflow:
-* (SH) Describe variables jobname, charcode.
+* Describe variables jobname, charcode.
 
 Reference Manual:
 * Describe environment variables and configuration files.
 
 Legacy Information:
-* (SH) Cite original Hobby papers.
+* Cite original Hobby papers.
 
 
 
@@ -59,7 +82,7 @@ Integrating Text and Graphics:
     scattered around mpman.
 * More information and examples on alternatives for calling TeX
     or LaTeX from within MetaPost.
-* (SH) Revise (and add more) flow charts for MetaPost workflow.
+* Revise (and add more) flow charts for MetaPost workflow.
 * Describe whitespace handling of verbatimtex/btex/etex.
 * Why is verbatimtex\end{document}etex "safer", cf. sec. 13.1?
 * Discuss difference between "draw <pic> withpen" and
@@ -67,7 +90,7 @@ Integrating Text and Graphics:
 
 Advanced Graphics:
 * Add a sub-section discussing colours.
-* (SH) Colour cars and change code example in section piccomp.
+* Colour cars and change code example in section piccomp.
 
 Reference Manual:
 * Describe missing variables, constants, and operators.
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex
index a18e5e01fb0..97aa825db1c 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mplibapi.tex
@@ -3,6 +3,9 @@
 \def\MP{MetaPost}
 \def\POSTSCRIPT{PostScript}
 \def\PS{PostScript}
+\def\SVG{SVG}
+\def\PNG{PNG}
+\def\MNG{MNG}
 \def\TFM{{\sc tfm}}
 \def\LUA{Lua}
 
@@ -31,9 +34,11 @@
 
 \nonknuthmode
 
-\def\ctypedef#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}}
+\defineselector[title][max=2,n=2]
+
+\def\ctypedef#1#2#3{\subsubsection[#2]{\select{title}{\type{#2}}{\type{#1#2#3}}}\bookmark{#2}}
 \def\cenumeration#1{\subsubsection{\type{#1}}\bookmark{#1}}
-\def\cfunction#1#2#3{\subsubsection[#2]{\type{#1#2#3}}\bookmark{#2}}
+\def\cfunction#1#2#3{\subsubsection[#2]{\select{title}{\type{#2}}{\type{#1 #2#3}}}\bookmark{#2}}
 
 
 \starttext
@@ -41,15 +46,19 @@
 \StartTitlePage
 \centerline{\definedfont[TitleFont at 50pt]{\MPLIB}}
 \blank[3*line]
-\centerline{\definedfont[SubTitleFont at 24pt]{API documentation}}
+\centerline{\definedfont[SubTitleFont at 24pt]{API documentation, version 1.800}}
 \blank[3*line]
-\centerline{Taco Hoekwater, July 2008}
+\centerline{Taco Hoekwater, September 2012}
 \StopTitlePage
 
 \section{Table of contents}
 
+\setupselector[title][n=1]
+
 \placecontent[criterium=all,level=subsection]
 
+\setupselector[title][n=2]
+
 \page
 
 \section{Introduction}
@@ -82,7 +91,6 @@ Here is a C language example of how to do this:
 
 
 \starttyping
-#include <stdlib.h>
 #include "mplib.h"
 int main (int argc, char **argv) {
   MP mp;
@@ -99,7 +107,8 @@ int main (int argc, char **argv) {
 }
 \stoptyping
 
-This example will run in \quote{inimpost} mode. 
+This example will run in \quote{inimpost} mode. See below for how to
+preload a macro package.
 
 \subsection{Embedded \MPLIB\ use}
 
@@ -127,7 +136,7 @@ if mp then
 end
 \stoptyping
 
-This example loads a previously generated \quote{plain} mem file.
+This example preloads the \quote{plain} macro file.
 
 
 \section{C API for core \MPLIB}
@@ -143,20 +152,12 @@ This is a structure that contains the configurable parameters for a new \MPLIB\
 between \type{-ini} and \type{non-ini} modes, there are three types of settings: Those that apply in both cases, and
 those that apply in only one of those cases.
 
+
 \starttabulate[|l|l|l|p|]
 \NC int            \NC ini_version      \NC 1     \NC set this to zero if you want to load a mem file.\NC \NR  
 \NC int            \NC error_line       \NC 79    \NC maximal length of error message lines\NC \NR
 \NC int            \NC half_error_line  \NC 50    \NC halfway break point for error contexts\NC\NR
 \NC int            \NC max_print_line   \NC 100   \NC maximal length of file output\NC \NR
-\NC unsigned       \NC hash_size        \NC 16384 \NC size of the internal hash (always a multiple of 2).
-                                                      ignored in \type{non-ini} mode, read from mem file\NC \NR
-\NC int            \NC param_size       \NC 150   \NC number of simultaneously active macro parameters.
-                                                      ignored in \type{non-ini} mode, read from mem file\NC \NR
-\NC int            \NC max_in_open      \NC 10    \NC maximum level of \type{input} nesting.
-                                                      ignored in \type{non-ini} mode, read from mem file\NC \NR
-\NC int            \NC main_memory      \NC 5000  \NC size of the main memory array in 8-byte words;
-                                                      in \type{non-ini} mode only used if larger than the 
-                                                      value stored in the mem file\NC\NR
 \NC void *         \NC userdata         \NC NULL  \NC for your personal use only, not used by the library\NC \NR
 \NC char *         \NC banner           \NC NULL  \NC string to use instead of default banner\NC \NR
 \NC int            \NC print_found_names\NC 0     \NC controls whether the asked name or the actual found 
@@ -177,6 +178,8 @@ those that apply in only one of those cases.
 \NC mp_file_finder \NC find_file        \NC NULL  \NC function called for finding files \NC \NR
 \NC mp_editor_cmd  \NC run_editor       \NC NULL  \NC function called after \quote{E} error response\NC \NR
 \NC mp_makempx_cmd \NC run_make_mpx     \NC NULL  \NC function called for the creation of mpx files\NC \NR
+\NC int            \NC math_mode       \NC 0     \NC set this to \type{mp_math_double_mode} to use doubles
+                                                     instead of scaled (\type{mp_math_scaled_mode}) values\NC \NR
 \stoptabulate
 
 To create an \type{MP_options} structure, you have to use the \type{mp_options()} function.
@@ -186,21 +189,22 @@ To create an \type{MP_options} structure, you have to use the \type{mp_options()
 This type is an opaque pointer to a \MPLIB\ instance, it is what you
 have pass along as the first argument to (almost) all the \MPLIB\ 
 functions. The actual C structure it points to has hundreds of fields,
-but you should not use any of those directly. All confuration is done
+but you should not use any of those directly. All configuration is done
 via the \type{MP_options} structure, and there are accessor functions
 for the fields that can be read out.
 
 \ctypedef{}{mp_run_data}{}
 
-When the \MPLIB\ instance is not interactive, any output is redirect
+When the \MPLIB\ instance is not interactive, any output is redirected
 to this structure.  There are a few string output streams, and a
 linked list of output images. 
 
 \starttabulate[|l|l|p|]
-\NC mp_stream \NC term_out    \NC holds the terminal output          \NC \NR
-\NC mp_stream \NC error_out   \NC holds error messages               \NC \NR
-\NC mp_stream \NC log_out     \NC holds the log output               \NC \NR
-\NC mp_edge_object *\NC edges \NC linked list of generated pictures  \NC \NR 
+\NC mp_stream \NC term_out    \NC holds the terminal output            \NC \NR
+\NC mp_stream \NC error_out   \NC holds error messages                 \NC \NR
+\NC mp_stream \NC log_out     \NC holds the log output                 \NC \NR
+\NC mp_stream \NC ship_out    \NC holds the exported EPS, SVG or PNG string \NC \NR
+\NC mp_edge_object *\NC edges \NC linked list of generated pictures    \NC \NR 
 \stoptabulate
 
 \type{term_out} is equivalent to \type{stdout} in interactive use, and
@@ -209,8 +213,9 @@ is currently only used for memory allocation errors, the \MP\ error
 messages are written to \type{term_out} (and are often duplicated to
 \type{log_out} as well).
 
-You need to include \type{mplibps.h} to be able to actually make use this list of images, 
-see the next section for the details on \type{mp_edge_object} lists.
+You need to include at least \type{mplibps.h} to be able to actually
+make use of this list of images, see the next section for the details
+on \type{mp_edge_object} lists.
 
 See next paragraph for \type{mp_stream}.
 
@@ -225,7 +230,8 @@ bookkeeping variables. The fields that are of interest to you are:
 \stoptabulate
 
 There is nothing in the stream unless the \type{size} field is
-nonzero. There will not be embedded zeroes in \type{data}.
+nonzero. There will not be embedded null characters (\type{\0}) 
+in \type{data} except when \type{ship_out} is used for PNG output.
 
 If \type{size} is nonzero, \type{strlen(data)} is guaranteed to be
 less than that, and may be as low as zero (if \MPLIB\ has written an
@@ -234,7 +240,7 @@ empty string).
 \subsection{Function prototype typedefs}
 
 The following three function prototypes define functions that you can
-pass to \MPLIB\ insert the \type{MP_options} structure.
+pass to \MPLIB\ inside the \type{MP_options} structure.
 
 \ctypedef{char * }{(*mp_file_finder)}{ (MP, const char*, const char*, int)}
 
@@ -265,9 +271,9 @@ This function is executed when there is a need to start generating an
 \type{mpx} file because (the first time a \type{btex} command was
 encountered in the current input file).
 
-The first arguments is the input file name. This is the name that was given
-in the \MP\ language, so it may not be the same as name of the actual
-file that is being used, depending on how you your
+The first argument is the input file name. This is the name that was given
+in the \MP\ language, so it may not be the same as the name of the actual
+file that is being used, depending on how your
 \type{mp_file_finder} function behaves.  The second argument is the 
 requested output name for mpx commands.
 
@@ -283,8 +289,8 @@ The \type{mp_file_finder} receives an \type{int} argument that is one of the fol
 \starttabulate[|l|p|]
 \NC mp_filetype_program    \NC Metapost language code (r)\NC \NR
 \NC mp_filetype_log        \NC Log output (w)\NC \NR
-\NC mp_filetype_postscript \NC PostScript output (w)\NC \NR
-\NC mp_filetype_memfile    \NC Mem file (r+w)\NC \NR
+\NC mp_filetype_postscript \NC PostScript or SVG output (w)\NC \NR
+\NC mp_filetype_bitmap     \NC PNG output (w)\NC \NR
 \NC mp_filetype_metrics    \NC \TeX\ font metric file (r+w)\NC \NR
 \NC mp_filetype_fontmap    \NC Font map file (r)\NC \NR
 \NC mp_filetype_font       \NC Font PFB file (r)\NC \NR
@@ -304,6 +310,15 @@ stops and asks the user for input. This initial mode can be overruled by using o
 \NC mp_error_stop_mode  \NC as with \type{errorstopmode} \NC \NR 
 \stoptabulate
 
+\cenumeration{mp_math_mode}
+
+\starttabulate[|l|p|]
+\NC mp_math_scaled_mode      \NC uses scaled point data for numerical values   \NC \NR 
+\NC mp_math_double_mode      \NC uses IEEE double floating point data for numerical values \NC \NR 
+\NC mp_math_binary_mode      \NC not used yet.                                 \NC \NR 
+\NC mp_math_decimal_mode     \NC not used yet.                                 \NC \NR 
+\stoptabulate
+
 \cenumeration{mp_history_state}
 
 These are set depending on the current state of the interpreter.
@@ -330,34 +345,6 @@ Graphical objects always have a color model attached to them.
 \stoptabulate
 
 
-\cenumeration{mp_knot_type}
-
-Knots can have left and right types depending on their current
-status. By the time you see them in the output, they are usually
-either \type{mp_explicit} or \type{mp_endpoint}, but here is the full
-list:
-
-\starttabulate[|l|p|]
-\NC mp_endpoint  \NC \NC \NR
-\NC mp_explicit  \NC \NC \NR
-\NC mp_given     \NC \NC \NR
-\NC mp_curl      \NC \NC \NR
-\NC mp_open      \NC \NC \NR
-\NC mp_end_cycle \NC \NC \NR
-\stoptabulate
-
-\cenumeration{mp_knot_originator}
-
-Knots can originate from two sources: they can be explicitly given by
-the user, or they can be created by the \MPLIB\ program code (for
-example as result of the \type{makepath} operator).
-
-\starttabulate[|l|p|]
-\NC mp_program_code  \NC \NC \NR
-\NC mp_metapost_user \NC \NC \NR
-\stoptabulate
-
-
 \cenumeration{mp_graphical_object_code}
 
 There are eight different graphical object types.
@@ -453,40 +440,457 @@ Returns the current simultaneous macro parameter usage of this instance.
 
 Returns the current \type{input} levels of this instance.
 
-\section{C API for graphical backend functions}
+\section{C API for path and knot manipulation}
 
-These are all defined in \type{mplibps.h}
+\subsection{Enumerations}
 
-Unless otherwise stated, the \type{int} fields that express \MP\ values
-should be interpreted as scaled points: the 32bits are divided into an
-integer part and a fraction part so that the value $65536$ equals
-1~\PS\ point (of which there are exactly 72 in an inch).
+\cenumeration{mp_knot_type}
+
+Knots can have left and right types depending on their current
+status. By the time you see them in the output, they are usually
+either \type{mp_explicit} or \type{mp_endpoint}, but here is the full
+list:
+
+\starttabulate[|l|p|]
+\NC mp_endpoint  \NC \NC \NR
+\NC mp_explicit  \NC \NC \NR
+\NC mp_given     \NC \NC \NR
+\NC mp_curl      \NC \NC \NR
+\NC mp_open      \NC \NC \NR
+\NC mp_end_cycle \NC \NC \NR
+\stoptabulate
+
+\cenumeration{mp_knot_originator}
+
+Knots can originate from two sources: they can be explicitly given by
+the user, or they can be created by the \MPLIB\ program code (for
+example as result of the \type{makepath} operator).
+
+\starttabulate[|l|p|]
+\NC mp_program_code  \NC \NC \NR
+\NC mp_metapost_user \NC \NC \NR
+\stoptabulate
 
 
 \subsection{Structures}
 
-The structures in this section are used by the items in the body of
-the \type{edges} field of an \type{mp_rundata} structure. They are
-presented here in a bottom-up manner.
+\ctypedef {}{mp_number}{}
+
+Numerical values are represented by opaque structure pointers named \type{mp_number}. 
 
 \ctypedef {}{mp_knot}{}
 
 Each \MPLIB\ path (a sequence of \MP\ points) is represented as a linked list
-of structures of the type \type{mp_knot}.
+of structure pointers of the type \type{mp_knot}.
 
 \starttabulate[|l|l|p|]
-\NC struct mp_knot *   \NC next       \NC the next knot, or NULL\NC \NR
-\NC mp_knot_type       \NC left_type  \NC the \type{mp_knot_type} for the left side \NC \NR
-\NC mp_knot_type       \NC right_type \NC the \type{mp_knot_type} for the right side \NC \NR
-\NC signed int         \NC x_coord    \NC $x$\NC \NR
-\NC signed int         \NC y_coord    \NC $y$\NC \NR
-\NC signed int         \NC left_x     \NC $x$ of the left (incoming) control point\NC \NR
-\NC signed int         \NC left_y     \NC $y$ of the left (incoming) control point\NC \NR
-\NC signed int         \NC right_x    \NC $x$ of the right (outgoing) control point\NC \NR
-\NC signed int         \NC right_y    \NC $y$ of the right (outgoing) control point\NC \NR
+\NC mp_knot            \NC next       \NC the next knot, or NULL\NC \NR
+\NC mp_knot_type       \NC data.types.left_type  \NC the \type{mp_knot_type} for the left side \NC \NR
+\NC mp_knot_type       \NC data.types.right_type \NC the \type{mp_knot_type} for the right side \NC \NR
+\NC mp_number          \NC x_coord    \NC $x$\NC \NR
+\NC mp_number          \NC y_coord    \NC $y$\NC \NR
+\NC mp_number          \NC left_x     \NC $x$ of the left (incoming) control point\NC \NR
+\NC mp_number          \NC left_y     \NC $y$ of the left (incoming) control point\NC \NR
+\NC mp_number          \NC right_x    \NC $x$ of the right (outgoing) control point\NC \NR
+\NC mp_number          \NC right_y    \NC $y$ of the right (outgoing) control point\NC \NR
 \NC mp_knot_originator \NC originator \NC the \type{mp_knot_originator} \NC \NR
 \stoptabulate
 
+Paths are always represented as a circular list. The difference between cyclic and
+non-cyclic paths is indicated by their \type{mp_knot_type}.
+
+While the fields of the knot structure are in fact accessible, it is better to use
+the access functions below as the internal structure tends to change.
+
+\subsection{Functions for accessing knot data}
+
+\cfunction{mp_number}{mp_knot_x_coord}{(MP mp,mp_knot p)}
+Access the $x$ coordinate of the knot.
+\cfunction{mp_number}{mp_knot_y_coord}{(MP mp,mp_knot p)}
+Access the $y$ coordinate of the knot.
+\cfunction{mp_number}{mp_knot_left_x}{(MP mp,mp_knot p)}
+Access the $x$ coordinate of the left control point of the knot.
+\cfunction{mp_number}{mp_knot_left_y}{(MP mp,mp_knot p)}
+Access the $y$ coordinate of the left control point of the knot.
+\cfunction{mp_number}{mp_knot_right_x}{(MP mp,mp_knot p)}
+Access the $x$ coordinate of the right control point of the knot.
+\cfunction{mp_number}{mp_knot_right_y}{(MP mp,mp_knot p)}
+Access the $y$ coordinate of the right control point of the knot.
+\cfunction{int}{mp_knot_left_type}{(MP mp,mp_knot p)}
+Access the type of the knot on the left side.
+\cfunction{int}{mp_knot_right_type}{(MP mp,mp_knot p)}
+Access the type of the knot on the right side.
+\cfunction{mp_knot}{mp_knot_next}{(MP mp,mp_knot p)}
+Access the pointer to the next knot.
+\cfunction{mp_number}{mp_knot_left_curl}{(MP mp,mp_knot p)}
+Access the left curl of the knot (applies to unresolved knots, see below).
+\cfunction{mp_number}{mp_knot_left_given}{(MP mp,mp_knot p)}
+Access the left given value of the knot  (applies to unresolved knots, see below).
+\cfunction{mp_number}{mp_knot_left_tension}{(MP mp,mp_knot p)}
+Access the left tension of the knot  (applies to unresolved knots, see below).
+\cfunction{mp_number}{mp_knot_right_curl}{(MP mp,mp_knot p)}
+Access the right curl value of the knot  (applies to unresolved knots, see below).
+\cfunction{mp_number}{mp_knot_right_given}{(MP mp,mp_knot p)}
+Access the right given value of the knot  (applies to unresolved knots, see below).
+\cfunction{mp_number}{mp_knot_right_tension}{(MP mp,mp_knot p)}
+Access the right tension value of the knot  (applies to unresolved knots, see below).
+
+\cfunction{double}{mp_number_as_double}{(MP mp,mp_number n)}
+
+Converts an \type{mp_number} to \type{double}.
+
+\subsection{Functions for creating and modifying knot data}
+
+\cfunction{mp_knot}{mp_create_knot}{(MP mp)}
+
+Allocates and returns a new knot.  Returns \type{NULL} on (malloc) failure. 
+
+\cfunction{int}{mp_set_knot}{(MP mp,mp_knot p,double x,double y)}
+
+Fills in the coordinate of knot \type{p}. \type{x1} and \type{y1} values should be
+within the proper range for the current numerical mode.
+Return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_close_path}{(MP mp,mp_knot p,mp_knot q)}
+
+Connects \type{p} and \type{q} using an \quote{endpoint join}, where \type{p} is the last knot
+of the path, and \type{q} is the first knot. The right tension of \type{p} and the
+left tension of \type{q} are (re)set to the default of 1.0.
+
+Because all knot list data structures are always circular, this is needed to end the path 
+properly even if the path is not intended cyclic (or use \type{mp_close_path_cycle()}, 
+if it is indeed a cycle).
+Return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_close_path_cycle}{(MP mp,mp_knot p,mp_knot q)}
+
+Connects \type{p} and \type{q} using an \quote{open join}, where \type{p} is the last knot
+of the path, and \type{q} is the first knot. The right tension of \type{p} and the
+left tension of \type{q} are (re)set to the default of 1.0.
+
+This is needed to mimic metapost's \type{cycle}.
+return 1 on success, 0 on failure.
+
+\cfunction{mp_knot}{mp_append_knot}{(MP mp,mp_knot p,double x,double y)}
+
+Appends a knot to previous knot \type{q}, and returns the new knot. 
+This is a convenience method combining \type{mp_create_knot()}, \type{mp_set_knot()}, and
+(if \type{q} is not NULL) \type{mp_close_path_cycle()}. 
+Returns NULL on failure. 
+
+\cfunction{int}{mp_set_knot_left_curl}{(MP mp,mp_knot q,double value)}
+
+Sets the left curl value for a knot. 
+\type{fabs(value)} should be less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knot_right_curl}{(MP mp,mp_knot q,double value)}
+
+Sets the right curl value for a knot. 
+\type{fabs(value)} should be less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knot_curl}{(MP mp,mp_knot q,double value)}
+
+Sets the curl value for a knot. 
+\type{fabs(value)} should be less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knotpair_curls}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)}
+
+A convenience method that calls \type{mp_set_knot_curl(mp,p,t1)} and \type{mp_set_knot_curl(mp,q,t2)}
+return 1 if both succeed, 0 otherwise.
+
+\cfunction{int}{mp_set_knot_direction}{(MP mp,mp_knot q,double x,double y)}
+
+Sets the direction \type{{x,y}} value for a knot. 
+\type{fabs(x)} and \type{fabs(y)} should be less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knotpair_directions}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)}
+
+A convenience method that calls 
+\type{mp_set_knot_direction(mp,p,x1,y1)} and \type{mp_set_knot_direction(mp,p,x2,y2)}
+return 1 if both succeed, 0 otherwise.
+
+\cfunction{int}{mp_set_knotpair_tensions}{(MP mp,mp_knot p,mp_knot q,double t1,double t2)}
+
+Sets the tension specifiers for a pair of connected knots.
+\type{fabs(t1)} and \type{fabs(t2)} should be more than 0.75 and less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knot_left_tension}{(MP mp, mp_knot p, double t1)}
+
+Set the left tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knot_right_tension}{(MP mp, mp_knot p, double t1)}
+
+Set the right tension of a knot. \type{fabs(t1)} should be more than 0.75 and less than 4096.0
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knot_left_control}{(MP mp, mp_knot p, double x1, double y1)}
+\cfunction{int}{mp_set_knot_right_control}{(MP mp, mp_knot p, double x1, double y1)}
+
+Sets explicit left or right control for a knot. \type{x1} and \type{y1} values should be
+within the proper range for the current numerical mode.
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_set_knotpair_controls}{(MP mp,mp_knot p,mp_knot q,double x1,double y1,double x2,double y2)}
+
+Sets explicit controls for a knot pair. All four \type{x} and \type{y} values should be
+within the proper range for the current numerical mode.
+return 1 on success, 0 on failure.
+
+\cfunction{int}{mp_solve_path}{(MP mp,mp_knot first)}
+
+Finds explicit controls for the knot list at \type{first}, which
+is changed in-situ. Returns 0 if there was any kind of error, in which
+case \type{first} is unmodified. There can be quite a set of potential errors,
+mostly harmless processing errors.
+However, be aware that it is also possible that there are internal mplib 
+memory allocation errors. A distinction between those can not be made 
+at the moment.
+Return 1 on success, 0 on failure.
+
+\cfunction{void}{mp_free_path}{(MP mp,mp_knot p)}
+
+Frees the memory of a path.
+
+\subsection{Example usage}
+
+Since the above function list is quite dry and not that easy to grasp,
+here are two examples of how to use it. First a simple example
+(\type{mp_dump_path()} code is given below).
+
+
+\starttyping
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "mplib.h"
+
+int main (int argc, char ** argv)  {
+        MP mp ;
+        mp_knot p, first, q; 
+        MP_options * opt = mp_options () ;
+        opt -> command_line = NULL;
+        opt -> noninteractive = 1 ; 
+        mp = mp_initialize ( opt ) ;
+        if ( ! mp ) exit ( EXIT_FAILURE ) ;
+
+        /* Equivalent Metapost code: 
+
+           path p;
+           p := (0,0)..(10,10)..(10,-5)..cycle;
+
+         */
+        first = p = mp_append_knot(mp,NULL,0,0); 
+        if ( ! p ) exit ( EXIT_FAILURE ) ;
+        q = mp_append_knot(mp,p,10,10); 
+        if ( ! q ) exit ( EXIT_FAILURE ) ;
+        p = mp_append_knot(mp,q,10,-5); 
+        if ( ! p ) exit ( EXIT_FAILURE ) ;
+        mp_close_path_cycle(mp, p, first);
+        /* mp_dump_path(mp, first); */
+        if (mp_solve_path(mp, first)) {
+            /* mp_dump_path(mp, first); */
+        }
+        mp_free_path(mp, first);
+        mp_finish ( mp ) ;
+        free(opt);
+        return 0;
+}
+\stoptyping
+
+For some more challenging path input, here is a more elaborate
+example of the path processing code:
+
+\starttyping
+        /* Equivalent Metapost code:
+
+           path p;
+           p := (0,0)..
+                (2,20)--
+                (10, 5)..controls (2,2) and (9,4.5)..
+                (3,10)..tension 3 and atleast 4 .. 
+                (1,14){2,0} .. {0,1}(5,-4);
+         */
+        first = p = mp_append_knot(mp,NULL,0,0); 
+        q = mp_append_knot(mp,p,2,20);  
+        p = mp_append_knot(mp,q,10,5);
+        if (!mp_set_knotpair_curls(mp, q,p, 1.0, 1.0)) 
+          exit ( EXIT_FAILURE ) ; 
+        q = mp_append_knot(mp,p,3,10);
+        if (!mp_set_knotpair_controls(mp, p,q, 2.0, 2.0, 9.0, 4.5)) 
+          exit ( EXIT_FAILURE ) ; 
+        p = mp_append_knot(mp,q,1,14);
+        if (!mp_set_knotpair_tensions(mp,q,p, 3.0, -4.0)) 
+          exit ( EXIT_FAILURE ) ;
+        q = mp_append_knot(mp,p,5,-4);
+        if (!mp_set_knotpair_directions(mp, p,q, 2.0, 0.0, 0.0, 1.0)) 
+          exit ( EXIT_FAILURE ) ;
+        
+        mp_close_path(mp, q, first);
+
+        /* mp_dump_path(mp, first); */
+        if (mp_solve_path(mp, first)) {
+            /* mp_dump_path(mp, first); */
+        }
+        mp_free_path(mp, first);
+\stoptyping
+
+And here is the source code for the \type{mp_dump_path} function,
+which produces path output that is similar to Metapost's 
+\type{tracingchoices} report. 
+
+\starttyping
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "mplib.h"
+
+#define ROUNDED_ZERO(v) (fabs((v))<0.00001 ? 0 : (v))
+#define PI 3.1415926535897932384626433832795028841971 
+#define RADIANS(a) (mp_number_as_double(mp,(a)) / 16.0) * PI/180.0
+
+void mp_dump_path (MP mp, mp_knot h) {
+  mp_knot p, q;
+  if (h == NULL) return;
+  p = h;
+  do {  
+    q=mp_knot_next(mp,p);
+    if ( (p==NULL)||(q==NULL) ) { 
+      printf("\n???"); 
+      return; /* this won't happen */
+    }
+    printf ("(%g,%g)", mp_number_as_double(mp,mp_knot_x_coord(mp,p)), 
+                       mp_number_as_double(mp,mp_knot_y_coord(mp,p)));
+    switch (mp_knot_right_type(mp,p)) {
+    case mp_endpoint: 
+      if ( mp_knot_left_type(mp,p)==mp_open ) printf("{open?}"); 
+      if ( (mp_knot_left_type(mp,q)!=mp_endpoint)||(q!=h) ) 
+        q=NULL; /* force an error */
+      goto DONE;
+      break;
+    case mp_explicit: 
+      printf ("..controls (%g,%g)", 
+              mp_number_as_double(mp,mp_knot_right_x(mp,p)), 
+              mp_number_as_double(mp,mp_knot_right_y(mp,p)));
+      printf(" and ");
+      if ( mp_knot_left_type(mp,q)!=mp_explicit ) { 
+        printf("??");
+      } else {
+        printf ("(%g,%g)",mp_number_as_double(mp,mp_knot_left_x(mp,q)), 
+                          mp_number_as_double(mp,mp_knot_left_y(mp,q)));
+      }
+      goto DONE;
+      break;
+    case mp_open: 
+      if ( (mp_knot_left_type(mp,p)!=mp_explicit)
+           &&
+           (mp_knot_left_type(mp,p)!=mp_open) ) {
+        printf("{open?}");
+      }
+      break;
+    case mp_curl:
+    case mp_given: 
+      if ( mp_knot_left_type(mp,p)==mp_open )  
+        printf("??");
+      if ( mp_knot_right_type(mp,p)==mp_curl ) { 
+        printf("{curl %g}", mp_number_as_double(mp,mp_knot_right_curl(mp,p)));
+      } else { 
+        double rad = RADIANS(mp_knot_right_curl(mp,p));
+        double n_cos = ROUNDED_ZERO(cos(rad)*4096);
+        double n_sin = ROUNDED_ZERO(sin(rad)*4096);
+        printf("{%g,%g}", n_cos, n_sin);
+      }
+      break;
+    }
+    if ( mp_knot_left_type(mp,q)<=mp_explicit ) {
+      printf("..control?"); /* can't happen */
+    } else if ((mp_number_as_double(mp,mp_knot_right_tension(mp,p))!=(1.0))||
+               (mp_number_as_double(mp,mp_knot_left_tension(mp,q)) !=(1.0))) {
+      printf("..tension ");
+      if ( mp_number_as_double(mp,mp_knot_right_tension(mp,p))<0.0 ) 
+        printf("atleast ");
+      printf("%g", fabs(mp_number_as_double(mp,mp_knot_right_tension(mp,p))));
+      if (mp_number_as_double(mp,mp_knot_right_tension(mp,p)) != 
+          mp_number_as_double(mp,mp_knot_left_tension(mp,q))) { 
+        printf(" and ");
+        if (mp_number_as_double(mp,mp_knot_left_tension(mp,q))< 0.0) 
+          printf("atleast ");
+        printf("%g", fabs(mp_number_as_double(mp,mp_knot_left_tension(mp,q))));
+      }
+    }
+   DONE:
+    p=q;
+    if ( p!=h || mp_knot_left_type(mp,h)!=mp_endpoint) {
+      printf ("\n ..");
+      if ( mp_knot_left_type(mp,p) == mp_given ) { 
+        double rad = RADIANS(mp_knot_left_curl(mp,p));
+        double n_cos = ROUNDED_ZERO(cos(rad)*4096);
+        double n_sin = ROUNDED_ZERO(sin(rad)*4096);
+        printf("{%g,%g}", n_cos, n_sin);
+      } else if ( mp_knot_left_type(mp,p) ==mp_curl ){ 
+        printf("{curl %g}", mp_number_as_double(mp,mp_knot_left_curl(mp,p))); 
+      }
+    }
+  } while (p!=h);
+  if ( mp_knot_left_type(mp,h)!=mp_endpoint ) 
+    printf("cycle");
+  printf (";\n");
+}
+\stoptyping
+
+The above function is much complicated because of all the knot type
+cases that can only happen {\it before} \type{mp_solve_path()} is
+called. A version that only prints processed paths and is less
+scared of using direct field access would be much shorter:
+
+\starttyping
+void mp_dump_solved_path (MP mp, mp_knot h) {
+    mp_knot p, q;
+    if (h == NULL) return;
+    p = h;
+    do {  
+        q=mp_knot_next(mp,p);
+        printf ("(%g,%g)..controls (%g,%g) and (%g,%g)", 
+                mp_number_as_double(mp,p->x_coord), 
+                mp_number_as_double(mp,p->y_coord),
+                mp_number_as_double(mp,p->right_x), 
+                mp_number_as_double(mp,p->right_y),
+                mp_number_as_double(mp,q->left_x), 
+                mp_number_as_double(mp,q->left_y));
+        p=q;
+        if ( p!=h || h->data.types.left_type!=mp_endpoint) {
+            printf ("\n ..");
+        }
+    } while (p!=h);
+    if (  h->data.types.left_type!=mp_endpoint ) 
+        printf("cycle");
+    printf (";\n");
+}
+\stoptyping
+
+\page
+\section{C API for graphical backend functions}
+\bookmark{C API for graphical backend functions}
+
+These are all defined in \type{mplibps.h}
+
+\subsection{Structures}
+
+The structures in this section are used by the items in the body of
+the \type{edges} field of an \type{mp_rundata} structure. They are
+presented here in a bottom-up manner.
+
+\ctypedef {}{mp_gr_knot}{}
+
+These are like \type{mp_knot}, except that all \type{mp_number} values 
+have been simplified to \type{double}.
+
 \ctypedef {}{mp_color}{}
 
 The graphical object that can be colored, have two fields to define
@@ -494,10 +898,10 @@ the color: one for the color model and one for the color values. The
 structure for the color values is defined as follows:
 
 \starttabulate[|l|l|p|]
-\NC int \NC a_val \NC see below, values are in scaled points\NC \NR
-\NC int \NC b_val \NC --\NC \NR
-\NC int \NC c_val \NC --\NC \NR
-\NC int \NC d_val \NC --\NC \NR 
+\NC double \NC a_val \NC see below\NC \NR
+\NC double \NC b_val \NC --\NC \NR
+\NC double \NC c_val \NC --\NC \NR
+\NC double \NC d_val \NC --\NC \NR 
 \stoptabulate
 
 All graphical objects that have \type{mp_color} fields also have
@@ -517,9 +921,8 @@ the four data fields:
 Dash lists are represented like this:
 
 \starttabulate[|l|l|p|]
-\NC int * \NC array \NC an array of dash lengths, terminated by $-1$.
-                        the values are in scaled points\NC \NR
-\NC int   \NC offset\NC the dash array offset (as in PostScript) \NC \NR
+\NC double * \NC array \NC an array of dash lengths, terminated by $-1$.\NC \NR
+\NC double   \NC offset\NC the dash array offset (as in PostScript) \NC \NR
 \stoptabulate
 
 \ctypedef {}{mp_graphic_object}{}
@@ -537,7 +940,7 @@ base line of graphical object types. It has only two fields:
 \NC struct mp_graphic_object * \NC next \NC next object or NULL \NC \NR
 \stoptabulate
 
-Because every graphical object has at least these two types, the body
+Because every graphical object has at least these two fields, the body
 of a picture is represented as  a linked list of
 \type{mp_graphic_object} items. Each object in turn can then be
 typecast to the proper type depending on its \type{type}.
@@ -557,10 +960,10 @@ Contains the following fields on top of the ones defined by \type{mp_graphic_obj
 \NC mp_color_model   \NC color_model \NC the color model\NC \NR
 \NC unsigned char    \NC ljoin       \NC the line join style; values have the same meaning 
                as in \PS: 0 for mitered, 1 for round, 2 for beveled.\NC \NR
-\NC mp_knot *        \NC path_p      \NC the (always cyclic) path\NC \NR
-\NC mp_knot *        \NC htap_p      \NC a possible reversed path (see below)\NC \NR
-\NC mp_knot *        \NC pen_p       \NC a possible pen (see below)\NC \NR
-\NC int              \NC miterlim    \NC the miter limit\NC \NR
+\NC mp_gr_knot        \NC path_p      \NC the (always cyclic) path\NC \NR
+\NC mp_gr_knot        \NC htap_p      \NC a possible reversed path (see below)\NC \NR
+\NC mp_gr_knot        \NC pen_p       \NC a possible pen (see below)\NC \NR
+\NC double              \NC miterlim    \NC the miter limit\NC \NR
 \stoptabulate
 
 Even though this object is called an \type{mp_fill_object}, it can be the result of both
@@ -573,7 +976,8 @@ involved as well. The final output should behave as follows:
 and also draw \type{path_p} with the \type{pen_p}. Do not forget to take \type{ljoin} and
 \type{miterlim} into account when drawing with the pen.
 \item If there is a more complex pen (\type{pen_p->next} != \type{pen_p}) then its path 
-has already been preprocessed for you. fill \type{path_p} and \type{htap_p}.
+has already been preprocessed for you: \type{path_p} and \type{htap_p} already incorporate
+its shape.
 \stopitemize
 
 \ctypedef {}{mp_stroked_object}{}
@@ -588,9 +992,9 @@ Contains the following fields on top of the ones defined by \type{mp_graphic_obj
 \NC unsigned char    \NC ljoin       \NC the line join style \NC \NR
 \NC unsigned char    \NC lcap        \NC the line cap style; values have the same meaning 
                as in \PS: 0 for butt ends, 1 for round ends, 2 for projecting ends.\NC \NR
-\NC mp_knot *        \NC path_p      \NC the path \NC \NR
-\NC mp_knot *        \NC pen_p       \NC the pen \NC \NR
-\NC int              \NC miterlim    \NC miter limit \NC \NR
+\NC mp_gr_knot       \NC path_p      \NC the path \NC \NR
+\NC mp_gr_knot       \NC pen_p       \NC the pen \NC \NR
+\NC double           \NC miterlim    \NC miter limit \NC \NR
 \NC mp_dash_object * \NC dash_p      \NC a possible dash list\NC \NR
 \stoptabulate
 
@@ -605,16 +1009,16 @@ Contains the following fields on top of the ones defined by \type{mp_graphic_obj
 \NC mp_color_model \NC color_model\NC color model \NC \NR
 \NC char *         \NC text_p     \NC string to be placed \NC \NR
 \NC char *         \NC font_name  \NC the \MP\ font name\NC \NR
-\NC unsigned int   \NC font_dsize \NC size of the font\NC \NR
-\NC int            \NC width      \NC width of the picture resulting from the string\NC \NR
-\NC int            \NC height     \NC height\NC \NR
-\NC int            \NC depth      \NC depth\NC \NR
-\NC int            \NC tx         \NC transformation component\NC \NR
-\NC int            \NC ty         \NC transformation component\NC \NR
-\NC int            \NC txx        \NC transformation component\NC \NR
-\NC int            \NC tyx        \NC transformation component\NC \NR
-\NC int            \NC txy        \NC transformation component\NC \NR
-\NC int            \NC tyy        \NC transformation component\NC \NR
+\NC double         \NC font_dsize \NC size of the font\NC \NR
+\NC double         \NC width      \NC width of the picture resulting from the string\NC \NR
+\NC double         \NC height     \NC height\NC \NR
+\NC double         \NC depth      \NC depth\NC \NR
+\NC double         \NC tx         \NC transformation component\NC \NR
+\NC double         \NC ty         \NC transformation component\NC \NR
+\NC double         \NC txx        \NC transformation component\NC \NR
+\NC double         \NC tyx        \NC transformation component\NC \NR
+\NC double         \NC txy        \NC transformation component\NC \NR
+\NC double         \NC tyy        \NC transformation component\NC \NR
 \stoptabulate
 
 All fonts are loaded by \MPLIB\ at the design size (but not all fonts have the same design
@@ -625,7 +1029,7 @@ size). If text is to be scaled, this happens via the transformation components.
 Contains the following field on top of the ones defined by \type{mp_graphic_object}:
 
 \starttabulate[|l|l|p|]
-\NC  mp_knot * \NC  path_p \NC defines the clipping path that is in effect until 
+\NC  mp_gr_knot   \NC  path_p \NC defines the clipping path that is in effect until 
          the object with the matching \type{mp_stop_clip_code} is encountered\NC \NR
 \stoptabulate
 
@@ -634,7 +1038,7 @@ Contains the following field on top of the ones defined by \type{mp_graphic_obje
 Contains the following field on top of the ones defined by \type{mp_graphic_object}:
 
 \starttabulate[|l|l|p|]
-\NC  mp_knot * \NC  path_p \NC the path that was used for boundary calculation \NC \NR
+\NC  mp_gr_knot   \NC  path_p \NC the path that was used for boundary calculation \NC \NR
 \stoptabulate
 
 This object can be ignored when output is generated, it only has effect on the boudingbox
@@ -662,15 +1066,15 @@ of that figure.
                                                 would have been generated\NC \NR
 \NC MP                        \NC parent    \NC a pointer to the instance that created 
                                                 this figure\NC \NR
-\NC int                       \NC minx      \NC lower-left $x$ of the bounding box\NC \NR
-\NC int                       \NC miny      \NC lower-left $y$ of the bounding box\NC \NR
-\NC int                       \NC maxx      \NC upper right $x$ of the bounding box\NC \NR
-\NC int                       \NC maxy      \NC upper right $y$ of the bounding box\NC \NR
-\NC int                       \NC width     \NC value of \type{charwd};
+\NC double                       \NC minx      \NC lower-left $x$ of the bounding box\NC \NR
+\NC double                       \NC miny      \NC lower-left $y$ of the bounding box\NC \NR
+\NC double                       \NC maxx      \NC upper right $x$ of the bounding box\NC \NR
+\NC double                       \NC maxy      \NC upper right $y$ of the bounding box\NC \NR
+\NC double                       \NC width     \NC value of \type{charwd};
 this would become the \TFM\ width (but without the potential rounding correction for \TFM\ file format)\NC \NR
-\NC int                       \NC height    \NC similar for height (\type{charht})\NC \NR
-\NC int                       \NC depth     \NC similar for depth (\type{chardp})\NC \NR
-\NC int                       \NC ital_corr \NC similar for italic correction (\type{charic})\NC \NR
+\NC double                       \NC height    \NC similar for height (\type{charht})\NC \NR
+\NC double                       \NC depth     \NC similar for depth (\type{chardp})\NC \NR
+\NC double                       \NC ital_corr \NC similar for italic correction (\type{charic})\NC \NR
 \NC int                       \NC charcode  \NC Value of \type{charcode} (rounded, but not
                                                 modulated for \TFM's 256 values yet)\NC \NR
 \stoptabulate
@@ -681,10 +1085,31 @@ this would become the \TFM\ width (but without the potential rounding correction
 
 If you have an \type{mp_edge_object},  you can call this function. It will 
 generate the \PS\ output for the figure and save it internally. A subsequent call to
-\type{mp_rundata} will find the generated text in the \type{ps_out} field.
+\type{mp_rundata} will find the generated text in the \type{ship_out} field.
+
+Returns zero for success. 
+
+\cfunction{int }{mp_svg_ship_out}{(mp_edge_object*hh,int prologues)}
+
+If you have an \type{mp_edge_object},  you can call this function. It will 
+generate the \SVG\ output for the figure and save it internally. A subsequent call to
+\type{mp_rundata} will find the generated text in the \type{ship_out} field.
+
+Returns zero for success. 
+
+
+\cfunction{int }{mp_png_ship_out}{(mp_edge_object*hh, char *options)}
+
+If you have an \type{mp_edge_object},  you can call this function. It will 
+generate the \PNG\ bitmap for the figure and save it internally. A subsequent call to
+\type{mp_rundata} will find the generated data in the \type{ship_out} field.
+
+Note: the \type{options} structure follows the same syntax as in the Metapost language,
+and can be NULL.
 
 Returns zero for success. 
 
+
 \cfunction{void }{mp_gr_toss_objects}{(mp_edge_object*hh)}
 
 This frees a single \type{mp_edge_object} and its \type{mp_graphic_object} contents.
@@ -783,23 +1208,22 @@ To create a new metapost instance, call
 <mpinstance> mp = mplib.new({...})
 \stoptyping
 
-This creates the \type{mp} instance object. The argument hash can have a number of
-different fields,  as follows:
+This creates the \type{mp} instance object. The \type{mp} instance object
+always starts out in so|-|called \quote{inimp} mode, there is no
+support for preload files.
+
+The argument hash can have a number of different fields,  as follows:
 
 \starttabulate[|lT|l|p|p|]
 \NC \ssbf name  \NC \bf type   \NC \bf description                \NC \bf default \NC\NR
 \NC error_line \NC         number \NC error line width            \NC 79 \NC\NR
 \NC print_line \NC         number \NC line length in ps output    \NC 100\NC\NR
-\NC main_memory \NC        number \NC total memory size           \NC 5000\NC\NR
-\NC hash_size \NC          number \NC hash size                   \NC 16384 \NC\NR
-\NC param_size \NC         number \NC max. active macro parameters\NC 150\NC\NR
-\NC max_in_open \NC        number \NC max. input file nestings    \NC 10\NC\NR
 \NC random_seed \NC        number \NC the initial random seed     \NC variable\NC\NR
-\NC interaction \NC        string \NC the interaction mode, one of
-\type {batch}, \type {nonstop}, \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR
-\NC ini_version \NC        boolean \NC the --ini switch           \NC true \NC\NR
-\NC mem_name \NC           string \NC \type {--mem}               \NC \type {plain} \NC\NR
+\NC interaction \NC        string \NC the interaction mode, one of \type {batch}, \type {nonstop}, 
+                                     \type {scroll}, \type {errorstop} \NC \type {errorstop}\NC\NR
 \NC job_name \NC           string \NC \type {--jobname}           \NC \type {mpout} \NC\NR
+\NC math_mode \NC          string \NC the number system mode, one of \type{scaled} or 
+                                     \type{double} \NC \type {scaled} \NC\NR
 \NC find_file \NC          function \NC a function to find files  \NC only local files\NC\NR
 \stoptabulate
 
@@ -814,7 +1238,7 @@ with:
 \starttabulate[|lT|l|p|]
 \NC name \NC the requested file \NC   \NR
 \NC mode \NC the file mode: \type {r} or \type {w} \NC \NR
-\NC type \NC the kind of file, one of: \type {mp}, \type {mem}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR
+\NC type \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR
 \stoptabulate
 
 Return either the full pathname of the found file, or \type{nil} if
@@ -828,15 +1252,15 @@ You can request statistics with:
 <table> stats = mp:statistics()
 \stoptyping
 
-This function returns the vital statistics for an \MPLIB\ instance. There are four
-fields, giving the maximum number of used items in each of the four
-statically allocated object classes:
+This function returns the allocation statistics for an \MPLIB\
+instance. There are four fields, giving the maximum number of used
+items in each of four object classes:
 
 \starttabulate[|lT|l|p|]
-\NC main_memory \NC number \NC memory size \NC\NR
-\NC hash_size   \NC number \NC hash size\NC\NR
-\NC param_size  \NC number \NC simultaneous macro parameters\NC\NR
-\NC max_in_open \NC number \NC input file nesting levels\NC\NR
+\NC memory  \NC number \NC allocated memory (in bytes)\NC\NR
+\NC hash    \NC number \NC hash size (in entries)\NC\NR
+\NC params  \NC number \NC simultaneous macro parameters\NC\NR
+\NC open    \NC number \NC input file nesting levels\NC\NR
 \stoptabulate
 
 \subsection{\luatex{mp:execute}}
@@ -895,6 +1319,7 @@ object methods you can call:
 \NC boundingbox  \NC function \NC returns the bounding box, as an array of 4 values\NC \NR
 \NC postscript   \NC function \NC return a string that is the ps output of the \type{fig} \NC \NR
 \NC svg          \NC function \NC return a string that is the svg output of the \type{fig} \NC \NR
+\NC png          \NC function \NC return a string that is the png output of the \type{fig} \NC \NR
 \NC objects      \NC function \NC returns the actual array of graphic objects in this \type{fig} \NC \NR
 \NC copy_objects \NC function \NC returns a deep copy of the array of graphic objects in this \type{fig} \NC \NR
 \NC filename     \NC function \NC the filename this \type{fig}'s \POSTSCRIPT\ output
@@ -1091,6 +1516,44 @@ the \type{char} is a glyph id in the range 0 to 255; the returned
 <number> w = mp.char_depth(<string> fontname, <number> char)
 \stoptyping
 
+\subsection{Solving path control points}
+
+\starttyping
+<boolean> success = mp.solve_path(<table> knots, <boolean> cyclic)
+\stoptyping
+
+This modifies the \type{knots} table (which should contain an
+array of points in a path, with the substructure explained below) 
+by filling in the control points. The boolean \type{cyclic} is
+used to determine whether the path should be the equivalent of 
+\type{--cycle}. If the return value is \type{false}, there
+is an extra return argument containing the error string.
+
+On entry, the individual knot tables can contain the values
+mentioned above (but typically the \type{left_{x,y}} and 
+\type{right_{x,y}} will be missing). \type{{x,y}_coord} are 
+both required. Also, some extra values are allowed:
+\starttabulate[|lT|l|p|]
+\NC left_tension	\NC number \NC A tension specifier \NC \NR
+\NC right_tension	\NC number \NC like \type{left_tension}\NC \NR
+\NC left_curl	        \NC number \NC A curl specifier\NC \NR
+\NC right_curl	        \NC number \NC like \type{left_curl}\NC \NR
+\NC direction_x		\NC number \NC $x$ displacement of a direction specifier\NC \NR
+\NC direction_y		\NC number \NC $y$ displacement of a direction specifier\NC \NR
+\stoptabulate
+
+Note the following: 
+\startitemize
+\item A knot has either a direction specifier, or a curl specifier, or a tension specification, 
+      or explicit control points, with the note that tensions, curls and control points are split
+      in a left and a right side (directions apply to both sides equally).
+\item The absolute value of a tension specifier should be more than 0.75 and less than 4096.0,
+      with negative values indicating \quote{\type{atleast}}.
+\item The absolute value of a direction or curl should be less than 4096.0.
+\item If a tension, curl, or direction is specified, then existing control points will be
+      replaced by the newly computed value.
+\item Calling \type{solve_path} does not alter the used mplib instance.
+\stopitemize
 
 \stoptext
 
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex
index baa97fa9009..dd779479d43 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex
@@ -1,4 +1,4 @@
-\svnInfo $Id: mpman-app-optab.tex 1598 2011-04-05 14:14:16Z taco $
+\svnInfo $Id: mpman-app-optab.tex 1438 2010-10-26 20:08:17Z stephanhennig $
 %%% Two notes on column specification:
 %%% (i)  Column widths are manually chosen as small as possible to allow
 %%%      for a wider last X column.
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex
index 274c2982ead..a38cb529578 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex
@@ -1,4 +1,4 @@
-% $Id: mpman.tex 1599 2011-04-05 14:15:45Z taco $
+% $Id: mpman.tex 1920 2013-06-13 14:21:25Z stephanhennig $
 % MetaPost manual, by John Hobby.  License at end.
 \listfiles
 \RequirePackage{ifpdf}
@@ -12,8 +12,8 @@
 \fi
 \documentclass{article} % article is NOT the original style
 \usepackage[nofancy]{svninfo}% Access VCS information.
-\svnInfo $Id: mpman.tex 1599 2011-04-05 14:15:45Z taco $
-\newcommand*{\mpversion}{1.504}
+\svnInfo $Id: mpman.tex 1920 2013-06-13 14:21:25Z stephanhennig $
+\newcommand*{\mpversion}{1.503}
 
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
@@ -91,6 +91,16 @@
 \begin{titlepage}
   \vbox to \textheight {%
     \vskip0pt
+    \raisebox{0pt}[0pt][0pt]{%
+      \begin{minipage}{\linewidth}
+        \emph{The manual currently doesn't cover all recent features of
+          MetaPost, such as the PNG backend or support for calculations
+          in different number systems.  We'll try to keep up.  For more
+          information, please refer to the
+          \href{https://foundry.supelec.fr/scm/viewvc.php/trunk/CHANGES?view=markup&revision=1919&root=metapost}{change
+            log}.  Sorry for the inconvenience!}
+      \end{minipage}%
+    }
     \vfil
     \vfil
     \vfil