summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/mfpic/mfpic.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/generic/mfpic/mfpic.dtx')
-rw-r--r--Master/texmf-dist/source/generic/mfpic/mfpic.dtx220
1 files changed, 154 insertions, 66 deletions
diff --git a/Master/texmf-dist/source/generic/mfpic/mfpic.dtx b/Master/texmf-dist/source/generic/mfpic/mfpic.dtx
index cc427bbf7f2..5da4b773a74 100644
--- a/Master/texmf-dist/source/generic/mfpic/mfpic.dtx
+++ b/Master/texmf-dist/source/generic/mfpic/mfpic.dtx
@@ -1,17 +1,17 @@
% \iffalse
-%%% File: mfpic.dtx
-%%% A part of mfpic 1.05 2010/06/10
-%%%
+% File: mfpic.dtx
+% A part of mfpic 1.06 2011/03/08
+%
% -------------------------------------------------------------------
%
-% Copyright 2002--2010, Daniel H. Luecking
+% Copyright 2002--2011, Daniel H. Luecking
%
% Mfpic may be distributed and/or modified under the conditions of the
-% LaTeX Project Public License, either version 1.3b of this license or (at
+% LaTeX Project Public License, either version 1.3c of this license or (at
% your option) any later version. The latest version of this license is in
% <http://www.latex-project.org/lppl.txt>
-% and version 1.3b or later is part of all distributions of LaTeX version
-% 2003/12/01 or later.
+% and version 1.3c or later is part of all distributions of LaTeX version
+% 2008/12/01 or later.
%
% Mfpic has maintenance status "author-maintained". The Current Maintainer
% is Daniel H. Luecking. There are several Base Interpreters: plain TeX, LaTeX,
@@ -22,7 +22,7 @@
%</driver>
%<sty>\ProvidesPackage{mfpic}
%<*sty>
- [2010/06/10 v1.05. Macros for drawing with Metafont/MetaPost.]%
+ [2011/03/08 v1.06. Macros for drawing with Metafont/MetaPost.]%
%</sty>
%<*driver>
\documentclass{ltxdoc}
@@ -106,7 +106,7 @@
\end{document}
%</driver>
%\fi
-% \CheckSum{5119}
+% \CheckSum{5145}
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
@@ -134,9 +134,9 @@
% produce the picture. The picture is then included on a second pass
% through \TeX.
%
-% This file documents the source code. See \file{mfpic-doc.pdf} (source
-% \file{mfpic.doc.tex} for the user documentation or \file{mfpguide.pdf}
-% (source \file{mfpguide.tex}) for an introductory guide.
+% This file documents the source code. See \file{mfpic-doc.pdf}/\file{tex}
+% for the user documentation, or \file{mfpguide.pdf}/\file{tex}) for an
+% introductory guide.
% \end{abstract}
%
% \StopEventually{\PrintIndex}
@@ -170,9 +170,9 @@
\ifx\mfpfileversion\UndEfInEd\else\expandafter\endinput\fi%
{%
\catcode\lq\.12 \catcode\lq\/12%
- \gdef\mfpfileversion{1.05}%
- \gdef\mfpfiledate{2010/06/10}%
- \gdef\mfpicversion{105}%
+ \gdef\mfpfileversion{1.06}%
+ \gdef\mfpfiledate{2011/02/25}%
+ \gdef\mfpicversion{106}%
}%
% \end{macrocode}
%
@@ -335,18 +335,20 @@
% The following might be useful in patching things or adding to
% \cs{mfp@additions}.
% \begin{macrocode}
-\mfp@ifdefined\g@addto@macro{}{%
+\mfp@ifundefined\g@addto@macro
\long\def\g@addto@macro#1#2{%
\begingroup
\toks@\@xp{#1#2}%
\xdef#1{\the\toks@}%
- \endgroup}}%
-\mfp@ifdefined\g@prependto@macro{}{%
+ \endgroup}%
+\mfp@enddef
+\mfp@ifundefined\g@prependto@macro
\long\def\g@prependto@macro#1#2{%
\begingroup
\toks@{#2}\toks2\@xp{#1}%
\xdef#1{\the\toks@\the\toks2}%
- \endgroup}}%
+ \endgroup}%
+\mfp@enddef
% \end{macrocode}
%
% We test for LaTeX. We assume plain\TeX{}, or something compatible,
@@ -527,7 +529,7 @@
\newdef\mfp@justify@error{%
\mfp@errmsg{Invalid justification parameter for text label}%
{The optional argument for an mfpic text label must be^^J%
- one of B, b, c or t, followed by^^J
+ one of B, b, c or t, followed by^^J%
one of l, r or c, optionally followed by an angle.}}%
% \end{macrocode}
%
@@ -722,7 +724,7 @@
\ifmfp@latex
\ifmfp@centcapt \centering \else \raggedright \fi
\else
- \rightskip 0pt plus 1fil
+ \rightskip 0pt plus 1fil\relax
\ifmfp@centcapt
\leftskip 0pt plus 1fil
\parfillskip 0pt plus 1fil\relax
@@ -1065,6 +1067,11 @@
\let\Gread@parse@bb\mfp@parse@bb}%
\global\let\setmfpicgraphic\includegraphics
\gdef\getmfpicoffset##1{}}%
+% \end{macrocode}
+%
+% The \LaTeX{} wrapper ends by inputing \file{mfpic.tex}.
+% \begin{macrocode}
+\input mfpic.tex\relax
%</sty>
% \end{macrocode}
%
@@ -1214,11 +1221,16 @@
% executed. When neither follows, nothing is removed and \arg3 is
% executed. Normally, this last is the main command being applied to each
% element of the list.
+%
+% We also define \LaTeX's \cs{@ifstar} for the few cases that require it.
% \begin{macrocode}
\def\mfp@iftoken#1#2{\@ifnextchar#1{\@firstoftwo{#2}}}%
\def\mfp@ifstar#1#2#3{\mfp@iftoken*{#1{#2}}{#1{#3}}}%
\def\mfp@ifend{\mfp@iftoken\mfp@end}%
\def\mfp@ifendorcomma#1#2#3{\mfp@ifend{#1}{\mfp@iftoken,{#2}{#3}}}%
+\mfp@ifundefined\@ifstar
+ \def\@ifstar#1{\@ifnextchar*{\@firstoftwo{#1}}}%
+\mfp@enddef
% \end{macrocode}
%
% I've taken to making an empty optional argument the default for a lot
@@ -1390,6 +1402,19 @@
\newdef\mfp@wlist#1{\mfp@src\mflist{(#1);}}%
% \end{macrocode}
%
+% If \prog{babel} is loaded with some options, certain punctuation will
+% be made active. These will then be expanded when written to the graph
+% file. \prog{Babel} provides a way to turn this off, but it would be an
+% error to run those commands if \prog{babel} is not loaded. Rather than
+% try to detect \prog{babel}, we run these commands only if they are
+% defined.
+% \begin{macrocode}
+\def\mfp@safe@activestrue{%
+ \mfp@ifdefined\@safe@activestrue\@safe@activestrue{}}%
+\def\mfp@safe@activesfalse{%
+ \mfp@ifdefined\@safe@activesfalse\@safe@activesfalse{}}%
+% \end{macrocode}
+%
% \subsection{Initializing the output file}\label{output}
%
% Category 12 characters percent, sharp and backslash signs for the
@@ -1501,7 +1526,7 @@
% \grafbase{} macros to be loaded.
% \begin{macrocode}
\newdef\mfp@versioninfo{%
- \mfp@p\space\mfp@filename.m\mfp@ifmpost{p}{f},
+ \mfp@p\space\mfp@filename.m\mfp@ifmpost{p}{f}, %
generated by Mfpic, v\mfpfileversion\space\mfpfiledate,\@nl
\mfp@p\space from TeX source "\jobname" on \mfp@now\@nl
numeric mfpicversion; mfpicversion := \mfpicversion;\@nl}%
@@ -1654,7 +1679,7 @@
% \begin{macrocode}
\mfp@ifopengraphsfile%
{\Mfpic@warn
- {\@nl An attempt has been made to open a graph file,
+ {\@nl An attempt has been made to open a graph file, %
\mfp@sanitized\mfp@tempa\@msgbreak
while another, \mfp@filename, is still open. \@msgbreak
Closing \mfp@filename.}\mfp@closegraphsfile}%
@@ -1758,8 +1783,8 @@
#1\edef#2{%
\@ifundefined{\mfp@cmdname#2}{???}{\@nameuse{\mfp@cmdname#2}}}%
\@ifundefined{\mfp@cmdname#2}%
- {\mfp@msg{}\Mfpic@msg{No value for \string#2\ifin@mfpicenv\space in
- mfpic figure \number\mfp@count\fi.\@nl}}%
+ {\mfp@msg{}\Mfpic@msg{No value for \string#2\ifin@mfpicenv\space
+ in mfpic figure \number\mfp@count\fi.\@nl}}%
{}%
\mfsrc{\@ifmplabels{\@nl verbatimtex #1\def\string#2{#2} etex;\@nl}{}%
message "\string\mfpicvalue";\@nl
@@ -2674,7 +2699,7 @@
\mfp@local\edef\tl@rot{#2}%
\@ifmplabels{}%
{\mfp@ifexist{#2}%
- {\Mfpic@warn{Rotation of labels is not supported without the
+ {\Mfpic@warn{Rotation of labels is not supported without the %
mplabels\@msgbreak option. Rotation setting\on@line\space
may be ignored.}}%
}}%
@@ -2888,7 +2913,7 @@
\mfp@ifmpost
{\mfp@local\mfp@linetype0
\mfp@def\mfp@setstyle{\draw[getcolor \number\mfp@linetype]}}%
- {\Mfpic@warn{You can't use \mfp@b coloredlines in
+ {\Mfpic@warn{You can't use \mfp@b coloredlines in %
Metafont.\@msgbreak Using \dashedlines instead}%
\dashedlines}}%
% \end{macrocode}
@@ -3669,6 +3694,68 @@
\def\levelcurve{\mfp@fcn{levelset}p}%
% \end{macrocode}
%
+% We now define two macros for depicting the solution of an
+% ordinary differential equation. THe first of these, \cs{DEgraph},
+% produces the graph of solutions of equations of the form
+% $$
+% \frac{dy}{dx} = f(x,y),\quad y(x_0) = y_0.
+% $$
+% The data required are the \emph{initial values} (the two numbers $x_0$
+% and $y_0$), the formula $f(x,y)$ (an explicit \MF{} numerical expression
+% with literal variables \mfc{x} and \mfc{y} as the only unknowns. Since
+% the \MF{} and only handle paths connecting discrete points, also
+% required is a step size which, roughly speaking, is the distance between
+% points in graph coordinates, and the number of steps $N$ to use. The \MF{}
+% macros then calculate $N$ additional points (the first is $(x_0,y_0)$) and join
+% them together to produce the graph.
+%
+% The second macro, \cs{DEtrajectory}, draws the trajectory of a
+% two-dimentional differential equation of the form
+% $$
+% \left( \frac{dx}{dt}, \frac{dy}{dt}\right) = (f(x,y,t),g(x,y,t)\,,
+% \quad (x(0),y(0)) = (x\sb0,y\sb0)
+% $$
+% This is not, strictly speaking, a \emph{graph} since that would
+% require three dimensions to indicate the relation between $x$, $y$, and
+% $t$. Mathematicians call it a trajectory, and it only shows the
+% two-dimensional path followed by the moving object. The required data
+% are an initial point $(x_0,y_0)$, the formula for the right-hand side
+% (an explicit \MF{} pair-valued expression or a pair of numerical
+% expressions in parentheses, with literal variables \mfc{x}, \mfc{y} and
+% \mfc{t} as the only unknowns. Also required are a step size and the
+% number of steps, as in \cs{DEgraph}.
+%
+% The method used to calculate the points to connect is a modified version
+% of the four-step Runge-Kutta method. The modifications are intended to
+% avoid numerical overflow. That is, infinite blow-up in finite time. An
+% example is the simple equation
+% $$
+% \frac{dy}{dx} = y^2 \quad y(0) = 1,
+% $$
+% whose solution is $y = 1/(1-x)$. The usual definition of
+% Runge-Kutta-IV would have one process equally spaced $x$-values. If a
+% user had no idea of the character of the solution, and asked for $N$
+% $x$-values with separation $h$ to get a graph on $0\le x \le Nh$, and if
+% $Nh > 1$, then the result would be either quite different from the actual
+% solution (especially around $x=1$), or would reach a point of numerical
+% overflow.
+%
+% Thus our macros require the user to supply a parameter that will be
+% interpreted as a distance step: if $h$ is this parameter, instead of
+% finding values of $y$ at $x_0$, $x_0+h$, $x_0+2h$, etc., it finds points
+% $(x_n,y_n)$ on the graph so that the two-dimensional distance from $(x_0,y_0)$
+% to $(x_1,y_1)$ is $h$, then the distance from $(x_1,y_1)$ to $(x_2,y_2)$
+% is also $h$, etc. The resulting graph therefore simply follow the graph
+% of $y = 1/(1-x)$ a distance roughly $Nh$ and numerical overflow is
+% impossible unless the value of $Nh$ exceeds \MF{}'s size limits.
+%
+% There is an optional smoothness parameter as in \cs{function}.
+% \begin{macrocode}
+ \newdef\DEgraph{\mfp@fcn{odeRKIV}s}%
+ \newdef\DEtrajectory{\mfp@fcn{xyRKIV}s}%
+% \end{macrocode}
+%
+%
% \subsection{Plotting data from files}\label{datafiles}
%
% \DescribeMacro{\plotdata}
@@ -3944,7 +4031,7 @@
% the tension value (empty if there is no tension option).
%
% \DescribeMacro{\sclosed}
-% The first, \cs{sclosed} closes smoothly in the same manner that
+% The first, \cs{sclosed}, closes smoothly in the same manner that
% \cs{curve} creates a smooth path.
% \DescribeMacro{\bclosed}
% The second, \cs{bclosed}, uses an ordinary \MF{} B\'ezier. These two
@@ -4781,15 +4868,16 @@
\mfp@listmac{\mfp@ifempty{#1}{fcncurve}{functioncurve (#1)}}}%
% \end{macrocode}
%
-% \cs{mfp@fcn} is called by six commands: \cs{levelcurve},
-% \cs{plrregion}, \cs{belowfcn}, \cs{function}, \cs{plrfcn} and,
-% \cs{parafcn}. They have a common argument structure for both
-% the \mfpic{} and \grafbase{} command. \cs{mfp@fcn} calls
-% \cs{mfp@dotension} to parse the optional tension argument (the second
-% argument) leaving the results in the macros \cs{mfp@t} (a \texttt{t}
-% for command name if a tension value was present) and \cs{mfp@sval}
-% (\texttt{true} or \texttt{false} and the tension value if it was
-% present). The first argument is the base name of a \grafbase{} command.
+% \cs{mfp@fcn} is called by eight commands: \cs{levelcurve},
+% \cs{plrregion}, \cs{belowfcn}, \cs{function}, \cs{plrfcn},
+% \cs{parafcn}, \cs{DEgraph} and \cs{DEtrajectory}. They have a common
+% argument structure for both the \mfpic{} and \grafbase{} command.
+% \cs{mfp@fcn} calls \cs{mfp@dotension} to parse the optional tension
+% argument (the second argument) leaving the results in the macros
+% \cs{mfp@t} (a \texttt{t} for command name if a tension value was
+% present) and \cs{mfp@sval} (\texttt{true} or \texttt{false} and the
+% tension value if it was present). The first argument is the base name of
+% a \grafbase{} command.
%
% Ultimately, \cs{mfp@@fcn} is called, and only then the two mandatory
% arguments of the calling command are read.
@@ -5035,15 +5123,15 @@
\mfp@ifexist{#1}{\mfp@@arropt#1\mfp@end}\mfp@@arr}%
\newdef\mfp@@arropt#1#2\mfp@end{%
\mfp@ifempty{#2}%
- {\Mfpic@warn{Arrow option #1 has no value\on@line;
+ {\Mfpic@warn{Arrow option #1 has no value\on@line; %
it will be ignored.}}%
{\@ifundefined{mfp@arr@#1}%
- {\Mfpic@warn{Arrow option #1 invalid \on@line;
+ {\Mfpic@warn{Arrow option #1 invalid \on@line; %
it will be ignored}}%
{\@nameuse{mfp@arr@#1}{#2}}%
}}%
\newdef\mfp@doarrow{%
- \mfp@addmac{\mfp@clropt{\mfp@hcolour}{\mfp@hcommand} (\mfp@hlength,
+ \mfp@addmac{\mfp@clropt{\mfp@hcolour}{\mfp@hcommand} (\mfp@hlength, %
\mfp@hrotate, \mfp@hlocate)}}%
% \end{macrocode}
%
@@ -5209,7 +5297,7 @@
\save@mfpicdimens
\begingroup % ended near end of \endmfpic
\@mfpicunit\mfpicunit
- \@nameuse{@safe@activestrue}%
+ \mfp@safe@activestrue
\mfp@ifopengraphsfile{}%
{\ifmfp@nowrite\else \mfp@nooutput@error\mfpic
\def\mfp@src##1##2{\endgroup}%
@@ -5234,14 +5322,23 @@
% We also define the coordinate conversion macros \cs{@xconv} and
% \cs{@yconv} via \cs{mfp@setconv}. These are used to calculate the
% nominal dimensions of the picture and to position \TeX{} labels.
+%
+% We make all the arguments of \cs{@mfpic} available to the user. Macro
+% \cs{mfp@setconv} now also makes use of them.
+% \begin{itemize}
+% \item the x-scaling factor.
% \DescribeMacro{\xfactor}
+% \item the y-scaling factor.
% \DescribeMacro{\yfactor}
+% \item the leftmost x-coordinate.
% \DescribeMacro{\xmin}
+% \item the rightmost x-coordinate.
% \DescribeMacro{\xmax}
+% \item the leftmost y-coordinate.
% \DescribeMacro{\ymin}
+% \item the rightmost y-coordinate.
% \DescribeMacro{\ymax}
-% We make all the arguments of \cs{@mfpic} available to the user. Macro
-% \cs{mfp@setconv} now also makes use of them.
+% \end{itemize}
%
% We are going to add all text labels to a box \cs{@alltlabels} and put
% that whole box on top of the graph during \cs{endmfpic}.
@@ -5626,7 +5723,7 @@
% \begin{macrocode}
\newdef\set@textbox#1{%
\setbox\@textbox\vbox{\def\\{\cr}\mfp@restorepar
- \@tcurr\@nameuse{@safe@activesfalse}\every@tlabel
+ \mfp@safe@activesfalse\@tcurr\every@tlabel
\halign{##\hfil\cr#1\crcr}}}%
% \end{macrocode}
%
@@ -5795,7 +5892,7 @@
\newdef\tlabelpath@{\@ifmplabels{}{\measure@textbox{\the\mfp@toks}}%
\mfp@setMPpos
\mfcmd{text\mfp@name x (\mfp@MPpos)\@nl
- (\@ifmplabels{origin, \mfp@btex{\the\mfp@toks}}{\tb@ll, \tb@ur},
+ (\@ifmplabels{origin, \mfp@btex{\the\mfp@toks}}{\tb@ll, \tb@ur}, %
\mfp@param) (\tl@points)}%
\ifmfp@switch\else \mfp@thelabel\fi \endgroup}%
% \end{macrocode}
@@ -5908,7 +6005,7 @@
\def\mfp@docaption{%
\setbox\@textbox
\hbox{\def\\{\hskip\@M\p@\let\\\relax}\mfp@restorepar
- \@nameuse{@safe@activesfalse}\@tcurr#3}%
+ \mfp@safe@activesfalse\@tcurr#3}%
% \end{macrocode}
%
% If the above \cs{hbox} is too wide, we re-assign \cs{@textbox} to a
@@ -5922,10 +6019,10 @@
\hbox{%
\vbox{%
\hsize#2\mfp@scratch \mfp@restorepar
- \leftskip0pt
- \rightskip0pt
+ \leftskip0pt \rightskip0pt\relax
\mfp@capsettings
- \@nameuse{@safe@activesfalse}\noindent\@tcurr #3%
+ \mfp@safe@activesfalse
+ \noindent\@tcurr #3%
}% End vbox.
}% End hbox.
\fi
@@ -5974,7 +6071,8 @@
% \begin{macrocode}
\mfp@DBlog{Definition of closure of mfpic environment.}%
\newdef\endmfpic{\every@endmfpic
- \mfsrc{\mfp@ifmpost{\@nl verbatimtex \relax\egroup\space etex;}{}\@nl
+ \mfsrc{%
+ \mfp@ifmpost{\@nl verbatimtex \relax\egroup\space etex;}{}\@nl
endmfpic; \mfp@p\space(\number\mfp@count) \mfp@lineno.\@nl
\mfp@p\mfp@d\mfp@d\mfp@d\@nl}%
\ifmfpicdebug\wlog{}\wlog{Mfpic: ENTERED endmfpic.}\wlog{}\fi
@@ -6056,7 +6154,7 @@
{\@graphright\wd\@wholegraph
\@graphtop\ht\@wholegraph}{}%
\ifmfpicdebug
- \wlog{Mfpic debug: Dimensions of wholegraph before labels
+ \wlog{Mfpic debug: Dimensions of wholegraph before labels %
are added, and before truebbox adjustments:}%
\wlog{Mfpic: graphleft = \the\@graphleft}%
\wlog{Mfpic: graphright = \the\@graphright}%
@@ -6081,7 +6179,7 @@
% (or both) that is nonempty, so one of the box resets may be redundant.
% \begin{macrocode}
\ifmfpicdebug
- \wlog{Mfpic debug: Dimensions of alltlabels, before
+ \wlog{Mfpic debug: Dimensions of alltlabels, before %
truebbox adjustments:}%
\mfp@scratch\mfpicllx bp\relax
\wlog{Mfpic: mfpicllx = \the\mfp@scratch}%
@@ -6126,7 +6224,7 @@
% detected by \TeX.
% \begin{macrocode}
\ifmfpicdebug
- \wlog{Mfpic debug: Dimensions of alltlabels after
+ \wlog{Mfpic debug: Dimensions of alltlabels after %
truebbox adjustments:}%
\wlog{Mfpic: tlabelsleft = \the\@tlabelsleft}%
\wlog{Mfpic: tlabelstop = \the\@tlabelstop}%
@@ -6147,7 +6245,7 @@
% graphht${}={}$graphtop${}-{}$graphbot, and graphdp${}= 0$.
% \begin{macrocode}
\ifmfpicdebug
- \wlog{Mfpic debug: Dimensions of wholegraph after
+ \wlog{Mfpic debug: Dimensions of wholegraph after %
labels are added:}%
\wlog{Mfpic: graphleft = \the\@graphleft}%
\wlog{Mfpic: graphright = \the\@graphright}%
@@ -6391,12 +6489,6 @@
\mfpicnumber{1}%
% \end{macrocode}
%
-% Create a system for adding patches in the file \file{mfppatch.tex},
-% and for user defaults in a file \file{mfpic.usr}.
-% \begin{macrocode}
-\InputIfFileExists{mfppatch.tex}{}{}%
-% \end{macrocode}
-%
% Set the font for missing or draft mode figures (for the file name or
% figure number). This will already have been defined if \file{mfpic.sty}
% was used, so here we can probably assume \LaTeX{} wasn't used, and
@@ -6406,7 +6498,8 @@
% \end{macrocode}
%
% Restore the meaning of \cs{+}, and execute the command that restores all
-% the saved category codes and \cs{newlinechar}.
+% the saved category codes and \cs{newlinechar}. Input user defaults in
+% the file \file{mfpic.usr}.
% \begin{macrocode}
\mfp@DBlog{Punctuation, etc., will revert to old catcodes now.}%
\let\+\mfpsaveplus
@@ -6415,10 +6508,5 @@
%</tex>
% \end{macrocode}
%
-% The \LaTeX{} wrapper inputs \file{mfpic.tex}.
-% \begin{macrocode}
-%<sty>\input mfpic.tex\relax
-% \end{macrocode}
-%
%\clearpage
%\Finale