diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/mfpic/mfpic.dtx')
| -rw-r--r-- | Master/texmf-dist/source/generic/mfpic/mfpic.dtx | 5045 |
1 files changed, 5045 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/mfpic/mfpic.dtx b/Master/texmf-dist/source/generic/mfpic/mfpic.dtx new file mode 100644 index 00000000000..1789f6e9146 --- /dev/null +++ b/Master/texmf-dist/source/generic/mfpic/mfpic.dtx @@ -0,0 +1,5045 @@ +% \iffalse +% Copyright 2002--2003, Daniel H. Luecking +% +% Mfpic consists of the 3 files mfpic.dtx, grafbase.dtx and mfpic.ins +% and the 5 files they generate: mfpic.tex, mfpic.sty, grafbase.mf, +% grafbase.mp, and dvipsnam.mp. +% +% Mfpic may be distributed and/or modified under the conditions of the +% LaTeX Project Public License, either version 1.2 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.2 or later is part of all distributions of LaTeX version +% 1999/12/01 or later. +% +% Documentation, examples, and ancillary files are separate and not +% covered by this license. See readme.1st for a complete list. See +% individual files for any copyright and license restrictions. +% +% With respect to the proposed draft LPPL-1.3: mfpic has maintenance +% status "maintained". The Current Maintainer is Daniel H. Luecking. There +% are several Base Interpreters: TeX, LaTeX, MetaPost and Metafont. +% +%<*driver> +\documentclass[draft]{ltxdoc} + +\def\fileversion{0.7a beta} +\def\filedate{2004/04/16} + +\addtolength{\textwidth}{.5878pt} + +\def\mytt{\mdseries\ttfamily} +\renewcommand\marg[1]{{\mytt \{#1\}}} +\renewcommand\oarg[1]{{\mytt [#1]}} +\renewcommand\parg[1]{{\mytt (#1)}} +\renewcommand{\meta}[1]{{$\langle$\rmfamily\itshape#1$\rangle$}} +\DeclareRobustCommand\cs[1]{{\mytt\char`\\#1}} +\def\prog#1{{\mdseries\scshape #1}} +\def\grafbase{\prog{grafbase}} +\def\mfpic{\prog{mfpic}} +\def\Mfpic{\prog{Mfpic}} +\def\MF{\prog{meta\-font}} +\def\MP{\prog{meta\-post}} +\def\CMF{\prog{Meta\-font}} +\def\CMP{\prog{Meta\-post}} +\def\opt#1{{\sffamily\upshape#1}} +\def\mfc#1{{\mytt#1}} +\let\env\mfc +\let\file\mfc +\let\gbc\mfc +\renewcommand\{{\char`\{} +\renewcommand\}{\char`\}} +\renewcommand\|{${}\mathrel{|}{}$} + +\makeatletter +\newcommand\bsl{{\mytt\@backslashchar}} +% Stupid lists! +\def\@listi{\leftmargin\leftmargini + \parsep \z@ \@plus\p@ \@minus\z@ + \topsep 4\p@ \@plus\p@ \@minus2\p@ + \itemsep\parsep} +\let\@listI\@listi \@listi +\renewcommand\labelitemi{\normalfont\bfseries \textendash} +\renewcommand\labelitemii{\textasteriskcentered} +\renewcommand\labelitemiii{\textperiodcentered} +\leftmargini\parindent +% Stupid index! +\def\IndexParms{% + \parindent \z@ \columnsep 15pt + \parskip 0pt plus 1pt + \rightskip 5pt plus2em \mathsurround \z@ + \parfillskip=-5pt \small + % less hanging: + \def\@idxitem{\par\hangindent 20pt}% + \def\subitem{\@idxitem\hspace*{15pt}}% + \def\subsubitem{\@idxitem\hspace*{25pt}}% + \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}} +\makeatother + +\def\pdfTeX{\textrm{pdf\kern.04em\TeX}} +\def\pdfLaTeX{\textrm{pdf\kern.06em\LaTeX}} +\def\ConTeXt{\textrm{Con\kern-.16em\TeX\kern-0.06em t}} +\def\PiCTeX{\textrm{P\kern-.13em\lower.3ex\hbox{I}C\TeX}} + +\title{The \mfpic{} package\thanks{This file has version number + \fileversion, last revised \filedate. The code described here + was developed by several people, notably Thomas Leathrum, + Geoffrey Tobin and Dan Luecking. Dan wrote this documentation.}} +\author{Dan Luecking} +\date{\filedate} +\DisableCrossrefs +\CodelineIndex +\AlsoImplementation + +\begin{document} + \DeleteShortVerb{\|} + \DocInput{mfpic.dtx} +\end{document} +%</driver> +%\fi +% +% \CheckSum{4392} +% \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 +% Digits \0\1\2\3\4\5\6\7\8\9 +% Exclamation \! Double quote \" Hash (number) \# +% Dollar \$ Percent \% Ampersand \& +% Acute accent \' Left paren \( Right paren \) +% Asterisk \* Plus \+ Comma \, +% Minus \- Point \. Solidus \/ +% Colon \: Semicolon \; Less than \< +% Equals \= Greater than \> Question mark \? +% Commercial at \@ Left bracket \[ Backslash \\ +% Right bracket \] Circumflex \^ Underscore \_ +% Grave accent \` Left brace \{ Vertical bar \| +% Right brace \} Tilde \~} +% +% \catcode`\_=12 +% \maketitle +% +% \begin{abstract} +% An environment, \env{mfpic}, is defined, within which commands can +% be used for drawing pictures, especially graphs of mathematical +% functions. These commands actually write code to an external file +% which can be processed through \MF{} or \MP{} (depending on package +% options) to produce the picture. The picture is then included on a +% second pass through \TeX. +% +% This file documents the source code. See \file{mfpicdoc.tex} for the +% user documentation. +% \end{abstract} +% +% \StopEventually{\PrintIndex} +% \tableofcontents +% +% +% \section{Introductory setup}\label{intro} +% +% \Mfpic{} is designed to work with plain \TeX, \LaTeX, \pdfTeX, and +% \pdfLaTeX. +% +% \subsection{Versions numbers, category codes, etc.}\label{category} +% +% Almost all the various category code settings we do were prompted by +% an \mfpic{} user who had sent a bug report and had to send along his +% modified version of \file{mfpic.tex}. It had been modified so that +% \cs{message}\,s and \cs{write}\,s would do the right thing in latex +% files where various punctuation were made active (e.g., with +% \file{french.sty}). +% +% \DescribeMacro{\mfpfileversion} +% \DescribeMacro{\mfpfiledate} +% \DescribeMacro{\mfpicversion} +% We keep track of version numbers here. We use \cs{mfpfileversion} +% because \cs{fileversion} is used by very many \LaTeX{} packages. +% This is important, because later we write the version information to the +% output file, The \cs{mfpicversion} is 100 times the numeric part of the +% version. The output file can compare this number with the corresponding +% value in \file{grafbase} and detect installations where there is a +% mismatch. +% \begin{macrocode} +%<*tex> +{\catcode\lq\.12 \catcode\lq\/12% +\gdef\mfpfileversion{0.7a beta}% +\gdef\mfpfiledate{2004/04/16}% +\gdef\mfpicversion{70}}% +\ifx\MFPicpackagE\UndEfInEd\else\expandafter\endinput\fi% +% \end{macrocode} +% +% A bug in older versions of some support files is triggered by the macro +% \cs{+}, which is an \cs{outer} macro in plain \TeX. Here we save the +% current definition and then give it a nonouter meaning. +% \begin{macrocode} +\let\mfpsaveplus\+% +\let\+\tabalign% +% \end{macrocode} +% +% \DescribeMacro{\MFPrestorecode} +% We now get rid of unusually catcoded punctuation, space and EOL. +% We save all the current category codes in the macro \cs{MFPicpackagE} +% and restore them at the end by executing this command. +% We try to assume only: that letters, numbers, +% `\texttt\bsl', `\texttt\{', `\texttt\}', `\texttt\#' and +% `\texttt\%' have the usual categories. Styles (e.g., \prog{french}) +% that make punctuation active foul up \cs{write}\,s of MF/MP code. This can +% still occur in user-generated \cs{write}\,s, so maybe some code should be +% added in \cs{mfpic} or \cs{mfsrc} command too. +% \begin{macrocode} +\edef\MFPrestoreequal{\catcode61\space\the\catcode61\relax}% +\catcode61 12\relax% +\edef\MFPrestorespace{\catcode32=\the\catcode32\relax}% +\catcode32=10\relax% +\edef\MFPrestoreEOL{\catcode13=\the\catcode13\relax}% +\catcode13=5\relax +\edef\MFPrestorelq{\catcode96=\the\catcode96\relax}% +\catcode96=12 +\def\MFPrestorecode#1{\catcode`\string#1=\the\catcode`#1\relax}% +% \end{macrocode} +% +% \DescribeMacro{\MFPicpackagE} +% This will be invoked at the end of the file to restore all the catcodes. +% This will fail if some of these characters have really bad codes +% (comment or escape, for example) but that would likely be the case only +% if {\tt\bsl} or {\tt\%} have some different codes and then everything +% above here would fail. +% \begin{macrocode} +\edef\MFPicpackagE{% + \MFPrestorecode{@}\MFPrestorecode{-}% + \MFPrestorecode{:}\MFPrestorecode{;}% + \MFPrestorecode{.}\MFPrestorecode{,}% + \MFPrestorecode{!}\MFPrestorecode{?}% + \MFPrestorecode{(}\MFPrestorecode{)}% + \MFPrestorecode{[}\MFPrestorecode{]}% + \MFPrestorecode{'}\MFPrestorecode{/}% + \MFPrestorecode{"}\MFPrestorecode{*}% + \MFPrestorecode{$}\MFPrestorecode{+}% + \MFPrestorecode{_}\MFPrestorecode{>}% + \MFPrestorecode{<}\MFPrestorecode{~}% + \MFPrestorelq\MFPrestoreEOL\MFPrestorespace + \MFPrestoreequal\catcode 10=\number\catcode10}% +% \end{macrocode} +% +% Set everything to normal except \texttt @=letter, \mfc{_}=other, and +% \texttt \textasciitilde=other. Do this by putting the settings in a +% macro and invoking the macro. That makes it possibly to redo the +% settings inside some other macro, should that ever become necessary. +% Characters 10 and 13 are \verb|^^J| and \verb|^^M|, control-J and +% control-M. +% +% \begin{macrocode} +\catcode`\@=11 +\ifx\@makeother\UndEfInEd \def\@makeother#1{\catcode`#1=12\relax}\fi +\def\mfp@sanitize{% +\catcode10=12\catcode13=5\catcode`\$=3\catcode`\ =10 +\@makeother\:\@makeother\;\@makeother\.\@makeother\,% +\@makeother\!\@makeother\?\@makeother\(\@makeother\)% +\@makeother\[\@makeother\]% +\@makeother\'\@makeother\/\@makeother\"\@makeother\*% +\@makeother\_\@makeother\`\@makeother\+\@makeother\=% +\@makeother\>\@makeother\<\@makeother\~\@makeother\-}% +\mfp@sanitize +\edef\restorenewlinechar{\newlinechar=\number\newlinechar\relax}% +\chardef\mfp@ctrlJ10 \chardef\mfp@ctrlM13 +\newlinechar\mfp@ctrlJ\def\@nl{^^J}% +% \end{macrocode} +% +% \subsection{Debugging and messages}\label{debug} +% +% \DescribeMacro{\ifmfpicdebug} +% \DescribeMacro{\mfpicdebug} +% To turn on debugging before option processing, the user must make sure +% \cs{mfpicdebug} is defined. \cs{mfp@DBlog} writes it contents to the +% log file only if debugging is on. +% \begin{macrocode} +\newif\ifmfpicdebug +\ifx\mfpicdebug\UndEfInEd \mfpicdebugfalse +\else \mfpicdebugtrue +\fi +\def\mfp@DBlog#1{% + \ifmfpicdebug{\let\@msgbreak\mfp@errbrk\wlog{Mfpic debug: #1}}\fi}% +% \end{macrocode} +% Various kinds of messages to the screen and log file. \cs{mfp@msg} is only +% used in the definition of the others and to write a blank line. We +% always use the second, which identifies the source of the message, or +% the third, which adds the word `warning'. The fourth is for errors +% and provides for help if a user presses `\texttt h' in response to the +% message. The bit with the spaces is to get a hanging indentation with +% text properly aligned on screen. +% \begin{macrocode} +\def\mfp@msg#1{{\newlinechar\mfp@ctrlJ\immediate\write16{#1}}}% +\def\@msgbreak{^^J}% +\def\mfp@spaces{\space\space\space\space\space\space}% +% +\def\mfp@msgbrk{^^J\mfp@spaces\space}% +\def\mfp@errbrk{\mfp@msgbrk\mfp@spaces}% +\def\mfp@warnbrk{\mfp@errbrk\space\space}% +% +\def\Mfpic@msg#1{{\let\@msgbreak=\mfp@msgbrk + \mfp@msg{Mfpic: #1 }}}% +\def\Mfpic@warn#1{{\let\@msgbreak=\mfp@warnbrk + \mfp@msg{^^JMfpic warning: #1}}}% +\def\mfp@errmsg#1#2{{\newlinechar\mfp@ctrlJ + \let\@msgbreak\mfp@errbrk + \errhelp{#2}\errmessage{Mfpic error: #1}}}% +% \end{macrocode} +% +% In \TeX{} 3.x we can identify the line being processed when a message is +% issued. We do not support \TeX{} 2.x. The command \cs{@mfplineno} is +% for information written into the output file. +% \begin{macrocode} +\def\@online{ on line \number\inputlineno}% +\def\@mfplineno{line \number\inputlineno\space in TeX source}% +% \end{macrocode} +% +% \subsection{Detecting the format}\label{format} +% +% To detect its environment, \mfpic{} needs to test whether certain +% commands are defined. The \cs{@xp} is usually used to `expand away' +% the rest of a conditional. \cs{@XP} does this from two levels deep in +% a conditional. (We use \cs{@xp}\cs{@XP}\cs{@xp} later to expand +% away from three levels.) Since it uses \cs{@firstoftwo} and +% \cs{@secondoftwo}, we cannot use it to check their existence. +% \begin{macrocode} +\ifx\@firstoftwo\UndEfInEd \long\def\@firstoftwo#1#2{#1}\fi +\ifx\@secondoftwo\UndEfInEd \long\def\@secondoftwo#1#2{#2}\fi +\let\@xp\expandafter +\def\@XP{\@xp\@xp\@xp}% +\def\mfp@ifdefined#1{% + \ifx#1\UndEfInEd \@xp\@secondoftwo + \else\ifx#1\relax \@XP\@secondoftwo + \else \@XP\@firstoftwo + \fi\fi}% +\mfp@ifdefined\@firstofone{}{\long\def\@firstofone#1{#1}}% +% \end{macrocode} +% +% We test for the format. If all tests fail we assume plain\TeX{} or +% something compatible. Mainly this is needed to support \LaTeX. I've done +% a few things to work around \ConTeXt, but its been a moving target and +% \mfpic{} didn't work in \ConTeXt{} the last time I tried. +% +% Here we see if \cs{documentstyle} is defined, and then make sure +% we are not in \AmSTeX{}. Probably there is a better command to test, +% and perhaps we should just test whether the functionality required is +% present, but I'm not really sure how best to do either of those. +% \begin{macrocode} +\newif\if@mfp@latex \@mfp@latexfalse +\mfp@ifdefined\documentstyle + {{\def\x{AmS-TeX}% + \ifx \fmtname\x \mfp@DBlog{AmS-TeX detected.}% + \else + \global\@mfp@latextrue \mfp@DBlog{LaTeX detected.}% + \fi}}% + {\mfp@DBlog{Neither LaTeX2e nor LaTeX209 nor AmS-TeX.}}% +% \end{macrocode} +% +% We are in \LaTeXe{}, as opposed to \LaTeX2.09, if \cs{documentclass} +% is defined. +% \begin{macrocode} +\newif\if@mfp@latexe \@mfp@latexefalse +\mfp@ifdefined\documentclass + {\@mfp@latexetrue \mfp@DBlog{LaTeX2e detected.}}% + {\mfp@DBlog{Not LaTeX2e.}}% +% \end{macrocode} +% +% We now test \cs{pdfoutput} to see if pdf support is needed. +% \begin{macrocode} +\newif\if@mfp@pdf \@mfp@pdffalse +\mfp@ifdefined\pdfoutput + {\mfp@DBlog{PdfTeX detected...}% + \ifcase\pdfoutput + \mfp@DBlog{...with dvi output.}% + \else + \@mfp@pdftrue \mfp@DBlog{...with PDF output.}% + \fi}% + {\mfp@DBlog{Not pdfTeX.}}% +% \end{macrocode} +% +% \subsection{Blank line and spacing hacks}\label{spacing} +% +% In order for commands to always read their arguments correctly, +% we need EOLs to have their normal category codes, but then a +% blank line will end a paragraph, and we would like blank lines to be +% ignored inside an \env{mfpic} environment. Therefore we turn off +% \cs{par} inside that environment, and then need(?) to turn it back on +% inside \cs{tlabel} and \cs{tcaption}. \cs{@@par} (in \LaTeX) and +% \cs{endgraf} (in plain \TeX) should equal the primitive \cs{par}. +% \begin{macrocode} +\if@mfp@latex \else \let\@@par\endgraf \fi +\def\mfp@restorepar{\let\par\@@par}% +% \end{macrocode} +% +% Some \mfpic{} commands end with \cs{ignorespaces}. For some others a +% better choice is the \LaTeX{} strategy of conditionally ignoring spaces. +% \begin{macrocode} +\if@mfp@latex\else + \def\@namedef#1{\@xp\def\csname #1\endcsname}% + \def\@nameuse#1{\csname #1\endcsname}% +\fi +\mfp@ifdefined\@bsphack{}% + {\@nameuse{newskip}\@savsk + \@nameuse{newcount}\@savsf + \def\@bsphack{\relax + \ifhmode \@savsk\lastskip \@savsf\spacefactor \fi}% + \def\@esphack{\relax + \ifhmode \spacefactor\@savsf + \ifdim\@savsk>\z@ \ignorespaces + \fi\fi}}% +% \end{macrocode} +% +% We sometimes (either by accident or by choice) redefine things defined +% in some formats. For the accidental redefinitions we want to be told, +% and since we cannot assume \LaTeX{} with its \cs{newcommand}, we define +% a simple check and print a warning when it happens. +% \begin{macrocode} +\mfp@DBlog{Defining test for previous definitions of macros.}% +\mfp@ifdefined\mfp@testdef + {\Mfpic@warn{% + Hey! How can \string\mfp@testdef\space already be defined? % + \@msgbreak I'll redefine it anyway!}}% + {}% +\def\mfp@testdef#1{% + \ifx#1\UndEfInEd + \else\ifx#1\relax + \Mfpic@warn{\string #1 was previouly defined to be \string\relax.}% + \else + \Mfpic@warn{\string #1 is already defined!}% + \fi\fi}% +% \end{macrocode} +% +% \DescribeMacro{\newdef} +% \DescribeMacro{\newlet} +% Is the proposed definer of new definitions itself not new? Well, +% we'd like a warning, but go ahead and define it anyway. All +% \cs{newdef} does is check whether the macro being defined is already +% defined, raise a warning (but \emph{not} an error) and define it +% anyway. We do something similar with \cs{let}. +% \begin{macrocode} +\mfp@testdef\newdef +\mfp@testdef\newlet +\def\newdef#1{\mfp@testdef#1\def#1}% +\newdef\newlet#1{\mfp@testdef#1\let#1}% +% \end{macrocode} +% +% +% \section{Configuring \mfpic{} behavior}\label{configuring} +% +% \subsection{Options}\label{options} +% +% \DescribeMacro{ifmfpmpost} +% I have decided to make this a user-level macro so that a user can +% write code that behaves one way for \MP{} and another for \MF. However +% the commands to change the setting are private. +% +% Our switch to turn \MP{} support on or off needs to be global, so it +% can't be a normal \cs{newif}. +% \begin{macrocode} +\global\let\ifmfpmpost\iffalse +\newdef\mfp@mposttrue {\global\let\ifmfpmpost\iftrue}% +\newdef\mfp@mpostfalse{\global\let\ifmfpmpost\iffalse}% +\newdef\mfp@ifmpost{% + \ifmfpmpost\@xp\@firstoftwo\else\@xp\@secondoftwo\fi}% +% \end{macrocode} +% +% \DescribeMacro{\usemetafont} +% We make a user-level commands for switching to the appropriate drawing +% program. This is necessary for plain\TeX, but also used internally by +% \mfpic. \CMF{} is the default. This command needs to not only clear the +% boolean \cs{ifmfpmpost}, but also restore the default graphics inclusion +% commands. Actually, it doesn't \emph{need} to unless \cs{usemetapost} +% was previously issued to change the default. This would normally not +% happen unless the user wanted to close the current graph file and open a +% new one for \MF. +% +% \MP{} support requires macros for including EPS graphics. What works +% best depends on the format, so we delay the definition of +% \cs{usemetapost} until the \LaTeX{} options section, but we define the +% error message here. +% \begin{macrocode} +\newdef\usemetafont{\mfp@mpostfalse + \def\preparemfpicgraphic##1{}% + \def\setmfpicgraphic##1{\@graphfont\char\mfp@count}% + \def\getmfpicoffset##1{}}% +\newdef\MPtoolate@error{% + \mfp@errmsg {Command \string\usemetapost\space too late.}% + {It is too late to select the metapost option.^^J% + It must be selected before the \opengraphsfile command.^^J% + If you proceed, the metafont option will be assumed.}}% +% \end{macrocode} +% +% Some options need an open \file{.mf} or \file{.mp} file before they +% can do anything. This means the \cs{opengraphsfile} command must have +% been issued but not \cs{closegraphsfile}. Since those commands define and +% undefine \cs{mfp@filename}, we use that as our test. +% \begin{macrocode} +\newdef\@ifmfpfileisopen{\mfp@ifdefined\mfp@filename}% +% \end{macrocode} +% +% \DescribeMacro{\setmfvariable} +% \DescribeMacro{\setmpvariable} +% A useful abbreviation for a common requirement: declaring and setting +% a \MF{} variable. I have decided to change it to a user level macro for +% power users. \cs{setmpvariable} is another name for it. It takes three +% arguments: the type of variable, the variable itself, and its value. +% Example: \cs{setmfvariable}\marg{numeric}\marg{shadewd}\marg{.7pt}. +% Since it \mfc{save}\,s the variable, it must not have a suffix. This is +% not a big problem since mostly it is for internal use. We document +% that fact for power users and advise ordinary users on the naming of +% \MF{} variables. +% +% \DescribeMacro{\setmfboolean} +% \DescribeMacro{\setmfnumeric} +% \DescribeMacro{\setmfcolor} +% Abbreviations for the most common internal uses. In the case of \MF, +% color is the same numeric, but in \MP{} it is a separate variable type. +% \begin{macrocode} +\newdef\setmfvariable#1#2#3{% + \@ifmfpfileisopen{\mfcmd{setvariable (#1) (#2) (#3)}}{}}% +\newlet\setmpvariable\setmfvariable +\newdef\setmfboolean#1#2{\setmfvariable{boolean}{#1}{#2}}% +\newdef\setmfnumeric#1#2{\setmfvariable{numeric}{#1}{#2}}% +\newdef\setmfcolor#1#2{\setmfvariable{color}{#1}{#2}}% +% \end{macrocode} +% +% The command \cs{setmfvariable} arranges for the value of +% that variable to be localized to each figure if set inside one, but +% it is global otherwise. We have to be careful that \TeX{} and \MF{} +% stay in sync, as they have different understandings as to what is +% global and what is not. So we define a switch that will be set at the +% start of an \env{mfpic} environment to test if a command is issued +% inside one. +% +% We also define here \texttt{true} and \texttt{false} as macros. These +% are strings we need to write to the output frequently. +% \begin{macrocode} +\let\ifin@mfpicenv\iffalse +\newdef\mfp@local{\relax\ifin@mfpicenv\else\global\fi}% +\newdef\mf@T{true}% +\newdef\mf@F{false}% +\newdef\mfp@let{\mfp@local\let}% +\newdef\mfp@def{\mfp@local\def}% +% \end{macrocode} +% +% \DescribeMacro{\usecenteredcaptions} +% \DescribeMacro{\nocenteredcaptions} +% This (\opt{centeredcaptions}) is the simplest option. Other options +% follow a similar pattern: user-level commands are defined for +% turning on (and sometimes turning off) the option. Selection of +% centered captions can be turned on or off at will throughout a +% document. +% \begin{macrocode} +\newdef\usecenteredcaptions{\mfp@let\if@mfp@centcapt\iftrue}% +\newdef\nocenteredcaptions {\mfp@let\if@mfp@centcapt\iffalse}% +\nocenteredcaptions +% \end{macrocode} +% +% This common code is repeated almost verbatim four times, so we define +% the following abbreviation. The first two arguments are the commands +% to turn the option on and off. The third and fourth are the \TeX{} and +% \MF{} booleans to switch. In all cases, the default for the option is +% \emph{off}, so we run \texttt{\#2} at the end. +% \begin{macrocode} +\newdef\mfp@makeoption#1#2#3#4{% + \newdef#1{\mfp@let#3\iftrue\setmfboolean{#4}\mf@T}% + \newdef#2{\mfp@let#3\iffalse\setmfboolean{#4}\mf@F} + #2}% +% \end{macrocode} +% +% \DescribeMacro{\clipmfpic} +% \DescribeMacro{\noclipmfpic} +% The \opt{clip} option shows only what's inside the rectangle +% given in the \cs{mfpic} command. It can be turned on or off for +% each figure independently. The default is the old behavior: no +% clipping. +% +% If the output file has not been opened, \cs{setmfboolean} does nothing. +% But the \cs{opengraphsfile} code checks the boolean and writes the +% appropriate code. +% \begin{macrocode} +\mfp@makeoption\clipmfpic\noclipmfpic\if@mfp@clip{clipall}% +% \end{macrocode} +% +% \DescribeMacro{\usetruebbox} +% \DescribeMacro{\notruebbox} +% The \opt{truebbox} option lets \MP{} set the true bounding box (which +% may differ from the numbers defined through \cs{mfpic}). +% +% We don't need to be too careful with the scope of truebbox. As +% currently written, \TeX{} never needs to know the setting except to pass +% the information on to \cs{opengraphsfile} if the option is set before +% then. However, we treat it like most other settings, turning on or off +% an appropriate \TeX{} boolean, in case it ever becomes necessary to know +% the setting. It is local to any \env{mfpic}, global otherwise. The +% default is to have \opt{truebbox} turned off. +% \begin{macrocode} +\mfp@makeoption\usetruebbox\notruebbox\if@mfp@truebbox{truebbox}% +% \end{macrocode} +% +% Some options and commands require the \opt{metapost} option be in +% effect. We define a generic error message for such cases. If a command +% or option requires \MP, but the \opt{metapost} option is not set, the +% option is ignored, or the command aborted. +% \begin{macrocode} +\newdef\noMP@error#1{% + \mfp@errmsg {Metafont does not support #1, use MetaPost.}% + {Metafont doesn't support #1. Perhaps you forgot to turn on^^J% + MetaPost support by using the metapost option or issuing the^^J% + command \usemetapost. For now, I will ignore it.}}% +% \end{macrocode} +% +% \DescribeMacro{\usemplabels} +% \DescribeMacro{\nomplabels} +% An option to let \MP{} create labels, \opt{mplabels} mostly just +% switches between two versions of \cs{tlabel} so no \MP{} booleans +% are set and so syncronization of scope is not an issue. The default +% is the old behavior: labels are placed by \TeX. The actual setting is +% delayed until \cs{opengraphsfile} so the order of these commands and +% \cs{usemetapost} is not significant (before \cs{opengraphsfile}). +% +% Because of the frequent need to check this setting, we define +% \cs{@ifmplabels} to execute one of two alternatives based on it. +% \begin{macrocode} +\newdef\usemplabels{\mfp@let\if@mfp@mplabels\iftrue + \@ifmfpfileisopen + {\mfp@ifmpost{}% + {\noMP@error{mplabels}\global\let\if@mfp@mplabels\iffalse}}{}}% +\newdef\nomplabels{\mfp@let\if@mfp@mplabels\iffalse}% +\newdef\@ifmplabels{% + \if@mfp@mplabels\@xp\@firstoftwo\else\@xp\@secondoftwo\fi}% +\nomplabels +% \end{macrocode} +% +% \DescribeMacro{\overlaylabels} +% \DescribeMacro{\nooverlaylabels} +% These control an option to defer adding labels (in \MP) until the end +% of the picture. That means they don't get clipped or covered up by any +% drawing elements. Neither of these commands affect \MF, but they write +% to the output file anyway if issued after \cs{opengraphsfile}. +% \begin{macrocode} +\mfp@makeoption% + \overlaylabels\nooverlaylabels\if@mfp@overlabels{overlaylabels}% +% \end{macrocode} +% +% \DescribeMacro{\clearsymbols} +% \DescribeMacro{\noclearsymbols} +% These determine whether the symbols drawn by \cs{plotsymbol} and +% \cs{plotnodes} should have their interiors erased before being drawn. +% \begin{macrocode} +\mfp@makeoption% + \clearsymbols\noclearsymbols\if@mfp@clearsym{clearsymbols}% +% \end{macrocode} +% +% \subsection{Graphic inclusion}\label{graphic} +% +% \DescribeMacro{\mfpicllx} +% \DescribeMacro{\mfpiclly} +% The code to include a figure has been divided into three parts. Under +% \opt{metapost} we need to both include the figure and save the +% bounding box coordinates of the lower left corner. Here we initialize +% the macros that hold these coordinates. +% \begin{macrocode} +\def\mfpicllx{0}% +\def\mfpiclly{0}% +% \end{macrocode} +% +% \DescribeMacro{\preparemfpicgraphic} +% Most EPS inclusion macros make the bounding box information available, +% and so after the inclusion command we just save it in the above two +% macros. However, \LaTeX's \cs{includegraphics} does not, so we have to +% issue a command before the inclusion to force it to become available. +% That command is \cs{preparemfpicgraphic}. Usually it does nothing, +% but in the \LaTeXe{} case it locally redefines one of the graphics +% packages internal macros. +% +% \DescribeMacro{\setmfpicgraphic} +% This command includes the graphic. The \mfpic{} default (for the +% \opt{metafont} option) is set by running \cs{usemetafont}. +% +% \DescribeMacro{\getmfpicoffset} +% This one saves the lower left corner in the macros \cs{mfpicllx} and +% \cs{mfpiclly}. In the case described above, that is accomplished by +% the redefined internal command, so this command does nothing. +% +% The command \cs{@setmfpicgraphic} is a wrapper around the inclusion +% code. It takes the name of the graphic file and passes it along to the +% above three commands. Those three commands can be redefined by the +% user for special circumstances. The user is then responsible to make +% sure \cs{mfpicllx} and \cs{mfpiclly} are properly set when necessary. +% Redefining one may necessitate redefining one or both of the others. +% +% The definition of these three is delayed to the option processing +% section, except under the \MF{} default: \cs{usemetafont} defines them. +% \begin{macrocode} +\newdef\@setmfpicgraphic#1{% + \preparemfpicgraphic{#1}\setmfpicgraphic{#1}\getmfpicoffset{#1}}% +\usemetafont +% \end{macrocode} +% +% \DescribeMacro{\setfilename} +% The user can also change \cs{setfilename} to modify the assumed +% filenames of the graphics output by \MP. The default is to concatenate +% the output file's basename with the picture number. +% \begin{macrocode} +\newdef\setfilename#1#2{#1.#2}% +% \end{macrocode} +% +% \DescribeMacro{\ifmfpicdraft} +% \DescribeMacro{\mfpicdraft} +% \DescribeMacro{\mfpicfinal} +% \DescribeMacro{\mfpicnowrite} +% The \opt{draft}, \opt{final} and \opt{nowrite} options override +% \mfpic's attempts to automatically detect whether the eps +% files should be included. The \opt{final} option can also be used to +% override a global draft option. Each of these sets the user level +% if-command \cs{ifmfpicdraft}, which is retained for backward +% compatibility. These settings are global since they are intended to +% be set for the whole document. The four commands +% \cs{@mfp@draft/finaltrue/false} are used to communicate with the +% \cs{opengraphsfile} command, in case the user-level commands occur before +% then. +% \begin{macrocode} +\newif\ifmfpicdraft +\newif\if@mfp@draft +\newif\if@mfp@final +\newif\if@mfp@nowrite +\newdef\mfpicdraft{% + \@ifmfpfileisopen{\global\mfpicdrafttrue}% + {\global\@mfp@drafttrue}}% +\newdef\mfpicfinal{% + \@ifmfpfileisopen{\global\mfpicdraftfalse}% + {\global\@mfp@finaltrue}}% +\newdef\mfpicnowrite{% + \@ifmfpfileisopen + {\mfp@errmsg + {Improper use of command \string\mfpicnowrite\@online.}% + {You must issue the command \mfpicnowrite prior to + \opengraphsfile. It will be ignored now.}}% + {\global\@mfp@nowritetrue}}% +% \end{macrocode} +% +% \subsection{\CMP{} graphics and \LaTeX{} options}\label{latex} +% +% Code dependent on \LaTeXe. Mostly this is the option processing +% facilities. +% \begin{macrocode} +\if@mfp@latexe + \ProvidesPackage{mfpic}[2004/04/16 v0.7a beta.]% + \DeclareOption{draft}{\mfpicdraft}% + \DeclareOption{final}{\mfpicfinal}% + \DeclareOption{nowrite}{\mfpicnowrite}% + \DeclareOption{metapost}{\mfp@mposttrue}% + \DeclareOption{metafont}{\usemetafont}% + \DeclareOption{centeredcaptions}{\usecenteredcaptions}% + \DeclareOption{clip}{\clipmfpic}% + \DeclareOption{truebbox}{\usetruebbox}% + \DeclareOption{mplabels}{\usemplabels}% + \DeclareOption{overlaylabels}{\overlaylabels}% + \DeclareOption{clearsymbols}{\clearsymbols}% + \DeclareOption{debug}{\mfpicdebugtrue}% + \DeclareOption*{% + \@ifpackageloaded{graphics}% + {\Mfpic@warn{Unrecognized option \CurrentOption.}}% + {\Mfpic@msg{Passing option \CurrentOption\space to % + graphics package.}% + \PassOptionsToPackage{\CurrentOption}{graphics}}}% +% \end{macrocode} +% If \file{mfpic.cfg} exists, it will be input at this point. Then, +% we \cs{ProcessOptions}, using the *-form because it allows package +% options to take precedence over global options. Thus \mfpic's +% \opt{final} option can counteract the \mfpic-specific side effects of a +% global \opt{draft} option. +% \begin{macrocode} + \InputIfFileExists{mfpic.cfg}{}{}% + \ProcessOptions*\relax +% \end{macrocode} +% +% \DescribeMacro{\usemetapost} +% Finally, one of the definitions of \cs{usemetapost}. The other is +% for use outside \LaTeXe, when the \prog{graphics} package cannot be +% assumed to be available. +% \begin{macrocode} + \def\usemetapost{% + \@ifmfpfileisopen{\mfp@mpostfalse\MPtoolate@error}% + {\mfp@mposttrue \RequirePackage{graphics}% +% \end{macrocode} +% +% Unlike all the other eps inclusion macros, \cs{includegraphics} does +% not make the bounding box coordinates available: \cs{Gin@llx} and the +% others are defined, but are local to a group surrounding the internals +% of \cs{includegraphics}. We locally modify one graphics package internal +% macro to globally save the information we need. Here we save the +% original definition and define our replacement. This definitely needs +% to come after the above \cs{RequirePackage} command. +% \begin{macrocode} + \global\let\mfp@save@parse@bb\Gread@parse@bb + \gdef\mfp@parse@bb##1 ##2 ##3 ##4 ##5\\{% + \mfp@save@parse@bb##1 ##2 ##3 ##4 ##5\\% + \xdef\mfpicllx{\Gin@llx}\xdef\mfpiclly{\Gin@lly}}% +% \end{macrocode} +% +% The \prog{graphics} package (as opposed to the \prog{graphicx} package) +% is far too dependent on actual extensions. Since we don't want to +% force our users to rename all the graphics output by \MP, we have to +% force \cs{includegraphics} to treat the current extension (some number) +% as if it were `{\tt eps}' or `{\tt mps}' according to the context. We +% decide which at this point. +% \begin{macrocode} + \if@mfp@pdf \gdef\mfp@Gtype{mps}% + \else \gdef\mfp@Gtype{eps}% + \fi +% \end{macrocode} +% +% The code we add to \cs{setmfpicgraphic} replaces \cs{Gread@parse@bb} with +% our own version. +% \begin{macrocode} + \gdef\preparemfpicgraphic##1{% + \let\Gread@parse@bb\mfp@parse@bb}% + \gdef\getmfpicoffset##1{}% + \gdef\setmfpicgraphic##1{\includegraphics{##1}}}}% +% \end{macrocode} +% +% \cs{ProcessOptions} doesn't allow \cs{RequirePackage}\marg{graphics}, +% so the above and the following were not simply put inside +% \cs{DeclareOption}\marg{metapost}. The \cs{AtEndDocument} command will +% close the output file if the user forgot. +% \begin{macrocode} + \mfp@ifmpost{\usemetapost}{}% + \AtEndDocument{\@closegraphsfile}% +% \end{macrocode} +% +% Now those cases outside \LaTeXe{} that we try to support. +% \begin{macrocode} +\else + \Mfpic@msg{\mfpfiledate\space v\mfpfileversion.}% +% \end{macrocode} +% +% \DescribeMacro{\usemetapost} +% The definition of \cs{usemetapost} depends on the setting of +% \cs{if@mfp@pdf}: \file{epsf.tex} is used for regular \TeX{} and +% \file{supp-pdf.tex} for \pdfTeX. +% \begin{macrocode} + \if@mfp@pdf + \def\usemetapost{% + \@ifmfpfileisopen{\mfp@mpostfalse\MPtoolate@error}% + {\mfp@mposttrue + \mfp@ifdefined\convertMPtoPDF{}{\input supp-pdf\relax}% +% \end{macrocode} +% The command \cs{convertMPtoPDF} takes the filename and and two +% scaling factors. It parses the files PS contents to PDF code. It leaves +% the bounding box info in macros \cs{MPllx}, etc. +% \begin{macrocode} + \gdef\setmfpicgraphic##1{\convertMPtoPDF{##1}{1}{1}}% + \gdef\getmfpicoffset##1{% + \xdef\mfpicllx{\MPllx}\xdef\mfpiclly{\MPlly}}}}% + \else +% \end{macrocode} +% The final case is the generic plain\TeX, \AmSTeX, or \LaTeX2.09. Our +% code uses the macros from \file{epsf.tex}, which should be present in +% every installation that includes \prog{dvips}. The command +% \cs{epsfbox} takes the filename, writes a \cs{special} for +% \prog{dvips} (and other programs) and saves the bounding box +% coordinates in \cs{epsfllx}, etc. +% \begin{macrocode} + \def\usemetapost{% + \@ifmfpfileisopen{\mfp@mpostfalse\MPtoolate@error}% + {\mfp@mposttrue + \mfp@ifdefined\epsfbox {}{\input epsf\relax}% + \gdef\setmfpicgraphic##1{\epsfbox{##1}}% + \gdef\getmfpicoffset##1{% + \xdef\mfpicllx{\epsfllx}\xdef\mfpiclly{\epsflly}}}}% + \fi +\fi +% \end{macrocode} +% +% +% \section{Optional parameter handling}\label{optional} +% +% We borrow \LaTeX's \cs{@ifnextchar} to have the advantage of +% skipping spaces and EOLs, but we skip \cs{relax} as well. The reason for +% this last is that an EOL will be set equal to \cs{relax} in certain +% contexts and we want option handling to work the same there as +% elsewhere. This could be a mistake, since \cs{relax} is a common method +% to halt such things. However, there should be no occasion in an +% \env{mfpic} environment where one would want a `\texttt[' to follow a +% command and \emph{not} be an optional argument. In text label commands +% we restore the meaning of blank lines, and EOLs ought to be normal. +% +% The first argument of \cs{mfp@ifnextchar} is the token being checked. It +% doesn't have to be a character and we sometimes use \cs{mfp@ifnextchar} +% to check whether a certain command follows. However, it is usually +% `\texttt['. The next argument is the code to run if that character is +% present, the last is code to use if the character is not present. The +% first argument must end with code that handles the character. +% +% The reason for the \cs{long} in the code when the next token is +% \cs{relax} is that it may be \cs{par} which has been \cs{let} equal to +% \cs{relax} in \env{mfpic} environments. +% \begin{macrocode} +\mfp@DBlog{Handlers for optional parameters.}% +\long\def\mfp@ifnextchar#1#2#3{% + \let\mfptmp@d=#1\def\mfptmp@a{#2}% + \def\mfptmp@b{#3}\mfp@checknext}% +\def\mfp@checknext{\futurelet\@let@token\mfp@ifnch}% +\def\mfp@ifnch{% + \ifx\@let@token\@sptoken + \let\mfptmp@c\eatspace@checknext + \else\ifx\@let@token\relax + \long\def\mfptmp@c##1{\mfp@checknext}% + \else\ifx\@let@token\mfptmp@d + \let\mfptmp@c\mfptmp@a + \else + \let\mfptmp@c\mfptmp@b + \fi\fi\fi\mfptmp@c}% +\begingroup + \def\:{\global\let\@sptoken= }\: % + \def\:{\eatspace@checknext}\@xp\gdef\: {\mfp@checknext}% +\endgroup +% \end{macrocode} +% +% I've taken to making an empty optional argument the default for a lot +% of commands. I wanted to make it possible to have the same result for +% empty brackets (i.e., \texttt{[]}) as for omitted brackets. +% The following helps check for emptyness. It uses a simple \cs{if} so +% that \texttt{\#1} will be expanded. I use a non-active +% \texttt{\textasciitilde} to test for emptyness because, even if a tilde +% should accidentally occur in \texttt{\#1}, it will most likely be active +% and expand to something else. In fact, in plain \TeX, +% \cs{mfp@ifempty}\marg{\textasciitilde} will compare +% \texttt{\textasciitilde} to \cs{penalty} and in \LaTeX{} to +% \cs{unhbox}. +% +% The \cs{@ifmtarg} macro is borrowed from \file{ifmtarg.sty}. +% It is used when a space should count as empty, but expansion isn't +% wanted. +% \begin{macrocode} +\newdef\mfp@ifempty#1{% + \if~#1~\@xp\@firstoftwo\else\@xp\@secondoftwo\fi}% +\begingroup +\catcode`Q=3 +\long\gdef\@ifmtarg#1{\@xifmtarg#1QQ\@secondoftwo\@firstoftwo\@nil}% +\long\gdef\@xifmtarg#1#2Q#3#4#5\@nil{#4}% +\endgroup +\newdef\@ifmtsub#1#2{\@ifmtarg{#1}{#2}{#1}}% +\newdef\mfp@mtsub#1#2{\mfp@ifempty{#1}{#2}{#1}}% +% \end{macrocode} +% +% The following is a historical holdover. Originally all optional arguments +% were handled through \cs{do@ptparam}. Then there arose cases that did not +% fit its assumptions and I wrote \cs{alt@ptparam}. Then, it became more +% efficient to have \cs{mfp@ifnextchar} (defined above) and now +% this command is defined in terms of it. +% +% The first argument of \cs{do@ptparam} is the command to use and the +% second is a default value of the optional argument. The command must be +% defined, and it must be a command whose first argument is delimited by +% `{\tt[}' and `{\tt]}'. Currently this is no longer used: all commands +% use one of the variants below. +% \begin{macrocode} +\newdef\do@ptparam#1#2{\mfp@ifnextchar[{#1}{#1[#2]}}% +% \end{macrocode} +% +% These are variations on the above. In \cs{simple@opt}, if an optional +% argument is present, we check to see if it is empty and substitute the +% default if it is. This was so named because I intended that it be used +% only if the optional argument required no further parsing (because it +% turned the argument into a nondelimited one). But now we use it even +% then and the few commands that require further parsing handle it more or +% less ad hoc. +% +% \cs{null@opt} is a convenient abbreviation for a common case: the +% default option is null. +% \begin{macrocode} +\newdef\simple@opt#1#2{% + \mfp@ifnextchar[{\process@opt{#1}{#2}}{#1{#2}}}% +\newdef\process@opt#1#2[#3]{% + \mfp@ifempty{#3}{#1{#2}}{#1{#3}}}% +\newdef\null@opt#1{\mfp@ifnextchar[{#1}{#1[]}}% +% \end{macrocode} +% +% Quite a few \mfpic{} commands stuff several parameters into a +% single optional argument. Generally, these commands can be coded to +% proceed gracefully if the last parameter is missing (substituting a +% default). However, if more than that are missing, \TeX{} gobbles the +% closing bracket and produces pretty inscrutable error mesages. This +% (adding extra information in one optional argument) was, in retrospect, +% a bad design decision that was made for backward compatibility and +% (originally) to minimize the changes in existing commands. +% Unfortunately we are stuck with it for at least the near future. +% +% We use the following utility to check for empty optional parameters. +% \begin{itemize} +% \item {\tt\#1} is the parameter to test (passed by some other macro) +% \item {\tt\#2} is what to use if {\tt\#1} is empty. +% \item {\tt\#3} is the command being passed the optional argument +% \end{itemize} +% We use a \cs{mfp@ifempty} so \texttt{\#1} will get expanded (often we +% pass arguments as macros). After the above revamping of optional +% argument handling, we ended up needing this code only once. +% \begin{macrocode} +\newdef\do@mtparam#1#2#3{\mfp@ifempty{#1}{#3[#2]}{#3[#1]}}% +% \end{macrocode} +% +% +% \section{Writing to the \file{.mf} or \file{.mp} file}\label{writing} +% +% \subsection{Preserving linebreaks}\label{linebreaks} +% +% Some macros can take quite long arguments (we call them +% \cs{@listmac}\,s), especially if they are automatically generated by +% some program. While the output file need not ever be looked at, there +% can be a problem with lines too long for the \MF{} executable's line +% buffer. Plus, for debugging, we might want to examine the file \mfpic{} +% writes. We therefore try to get at least the list macros to preserve +% linebreaks on output. +% +% \DescribeMacro{\mfpicobeylines} +% We make use of the \TeX{} property that expandable commands are +% expanded inside \cs{write} commands, but unexpandable commands and +% characters are written verbatim (almost). If this were the only +% consideration, nothing would need to be done. But characters with +% catagory code 5 (end-of-line) are converted to spaces upon reading, so +% we have to change the category of the \cs{endlinechar}, or we have +% change the \cs{endlinechar} to a character in a different category. +% We do the former, because the line a macro starts on will already have +% the end-of-line character added, but its category will not yet be +% established. We need a category that \TeX{} will not \emph{ignore}, +% but that nevertheless has no (or minimal) side effects if encountered in +% a \TeX{} file. We therefore make it active, but \cs{let} it equal to +% \cs{relax}. This makes the end-line-character unexpandable. +% \begin{macrocode} +\mfp@DBlog{Direct output to Metafont/Post file.}% +\begingroup + \catcode\mfp@ctrlM\active% + \gdef\@activectrlM{^^M}% + \gdef\mfpicobeylines{\catcode\mfp@ctrlM\active\let^^M\relax}% +\endgroup +% \end{macrocode} +% +% The choice \cs{relax} seems to be actually a slightly better choice +% than \cs{endgraf} (which we used to use, and which equals the +% unexpandable primative \cs{par}) because \cs{relax} is permitted before +% the opening brace in the syntax of \meta{general text} (for token +% variable assignments, \cs{write}, \cs{message}, and the like) as well as +% being skipped in mfpic's version of \cs{@ifnextchar}. +% +% \DescribeMacro{\preservelines} +% The character assigned to \cs{endlinechar} is added to the end of all +% lines read in by \TeX. The character assigned to \cs{newlinechar} +% will produce a newline when it occurs in a \cs{write}. Our +% \cs{preservelines} ensures these are the same and makes the above +% changes in category. +% \begin{macrocode} +\newdef\preservelines{\newlinechar\mfp@ctrlM + \endlinechar\newlinechar \mfpicobeylines}% +% \end{macrocode} +% +% \DescribeMacro{\unpreservelines} +% This is no longer used and may some day be removed. Grouping is +% enough to isolate effects of \cs{preservelines}. The command +% \cs{unpreservelines} simply restores the catcode of control-M to the +% control-M to the usual in formats consistent with plain \TeX. If we +% really wanted to reverse the effects of \cs{preservelines}, we'd have to +% save and restore the four items changed: the values of \cs{newlinchar} +% and \cs{endlinechar}, the category of control-M, and the definition of +% an active control-M. +% \begin{macrocode} +\newdef\unpreservelines{\catcode\mfp@ctrlM=5 }% +% \end{macrocode} +% +% \DescribeMacro{\mfsrc} +% \DescribeMacro{\mfcmd} +% \DescribeMacro{\mflist} +% We want these to issue \cs{preservelines} before the text is read +% (and category codes assigned). Also we often want to add a few items to +% the argument (figure macros append a semi-colon, list macros surround +% with parentheses), so we isolate the common starting code in +% \cs{@mfwrite}, and then invoke the appropriate continuation command. +% The ending code is in \cs{@mfsrc}. The \cs{begingroup} in +% \cs{@mfwrite} matches the \cs{endgroup} in \cs{@mfsrc}. The group +% isolates the changes to EOLs. We also equate \cs{@nl} to an active +% control-M so that it can be used for line breaks in cases where it is +% inconvenient to make EOLs active (in the replacement text of +% \cs{opengraphsfile} and \cs{@mfpic}, for example). +% \begin{macrocode} +\newdef\mfsrc {\@mfwrite\@mfsrc\mfsrc}% +\newdef\mfcmd {\@mfwrite\@mfcmd}% +\newdef\mflist{\@mfwrite\@mflist}% +\newdef\@mfwrite{\begingroup + \preservelines \let\@nl\@activectrlM}% +% \end{macrocode} +% +% The macro \cs{@mfsrc} does the job of writing to files. The output +% stream \cs{mfp@out} is declared later. The other two commands invoke +% \cs{@mfsrc} on a slightly modified argument. The first argument to +% \cs{@mfsrc} is the command that called it (for the error message), the +% second is the code to write. +% \begin{macrocode} +\newdef\@mfsrc#1#2{% + \@ifmfpfileisopen{\immediate\write\mfp@out{#2}}% + {\nooutputfileerror{#1}}\endgroup}% +\newdef\@mfcmd#1{\@mfsrc\mfcmd{#1;}}% +\newdef\@mflist#1{\@mfsrc\mflist{(#1);}}% +% \end{macrocode} +% +% \subsection{Initializing the output file}\label{output} +% +% Category 12 characters percent, sharp and backslash signs for the +% \file{.mf} file. The command \cs{mf@d} is used to write a line of +% dashes above and below each figure to make them stand out when debugging +% the file. This might be removed in the final distribution. +% \begin{macrocode} +\newdef\mfp@gobble#1{}% +\edef\mf@p{\@xp\mfp@gobble\string\%}% percent (%) +\edef\mf@s{\@xp\mfp@gobble\string\#}% sharp (#) +\edef\mf@b{\@xp\mfp@gobble\string\\}% backslash (\) +\newdef\mf@d{--------------}% +% \end{macrocode} +% +% Used to mark ends of things, \cs{mfp@delim} should never be expanded, +% but we give it a definition for debugging purposes: +% \begin{macrocode} +\newdef\mfp@delim{% + \mfp@errmsg {Misplaced \string\mfp@delim.}% + {If you get this message but did not (mis)use the command^^J% + \mfp@delim, please report this to the mfpic maintainer.}}% +% \end{macrocode} +% +% The current date and time stamp will be written to the \file{.mf} file. +% We calculate it here and store the result in these macros. The commands +% \cs{normalyear} and \cs{normalmonth} are part of \ConTeXt, where they +% have been equated to the primitive commands \cs{year} and \cs{month} +% (which are then redefined). +% \begin{macrocode} +{\mfp@ifdefined\normalmonth + {\let\month\normalmonth\let\year\normalyear}{}% + \xdef\mfp@today{\number\year/\ifnum\month<10 0\fi\number\month/% + \ifnum\day<10 0\fi\number\day}% + \count2=\time \divide\count2 by 60 + \xdef\mfp@now{\ifnum\count2<10 0\fi\number\count2:}% + \multiply\count2 by -60 \advance\count2 \time + \xdef\mfp@now{\mfp@now\ifnum\count2<10 0\fi\number\count2 }}% +% \end{macrocode} +% +% These registers are allocated: +% \begin{itemize} +% \item \cs{mfp@out} Write stream for the \file{.mf} or \file{.mp} file. +% \item \cs{mfp@graph} Read stream used to test existence of files and +% for reading datafiles. +% \item \cs{mfp@count} Number for next \env{mfpic} environment. +% \item \cs{mfp@linetype} Current line style in multi-curve data plots. +% \item \cs{mfp@n} Scratch counter, so far used only in writing data to +% the \file{.mf} file. +% \item \cs{mfp@sequence} Counter incremented with every datapoint written +% from a file to implement the feature that a list of numeric data can be +% plotted against its sequence position. +% \item \cs{mfp@toks} Temporary token register. +% \item \cs{every@tlabel} Tokens inserted at every \cs{tlabel}. +% \item \cs{mfp@verbtex} A temporary token list used by \cs{mfpverbtex}. +% \item \cs{mfp@commonverbatimtex} Tokens written at the start of every +% output file inside a \mfc{verbatimtex} group. +% \end{itemize} +% \begin{macrocode} +\mfp@DBlog{Declarations used with data and graphs files.}% +\newwrite\mfp@out +\newread\mfp@graph +\newlet\mfp@data\mfp@graph +\newcount\mfp@count +\newcount\mfp@linetype +\newcount\mfp@n +\newcount\mfp@sequence +\newtoks\mfp@toks +\newtoks\every@tlabel +\newtoks\mfp@verbtex +\newtoks\mfp@commonverbatimtex +\every@tlabel{}% +% \end{macrocode} +% +% We store most of the \mfc{verbatimtex} block that \mfpic{} relies on in +% the token register \cs{mfp@commonverbatimtex}. We do that because it +% relies on a couple of catcode changes and we want to be in a situation +% where we have that under control. Each line will end with an active +% ctrl-M, which is transformed by \cs{mfsrc} into a newline. +% \begin{macrocode} +\begingroup + \let\newtoks\relax + \@makeother\%\@makeother\#\preservelines + \global\mfp@commonverbatimtex= + {\def\MFPtext#1{% + \vbox{\def\\{\cr}\MFPcfont\everylabel + \halign{##\hfil\cr#1\crcr}}}% + }\endgroup +% \end{macrocode} +% +% \DescribeMacro{\opengraphsfile} +% This is the main command to set up the output file. It also aims to +% check whether \MF{} or \MP{} has already been run on the output file, +% thereby determining whether the graphics can be included. It does this +% by checking for the existence of one of the products of these programs. +% In the case of \MF{} it looks for a \file{.tfm} file; in the case of +% \MP{} it looks for the first output graphic. +% +% The name of the output file is its only parameter, and it appends +% the extension \file{.mf} or \file{.mp} depending on the whether option +% \opt{metafont} or \opt{metapost} was chosen. +% \begin{macrocode} +\mfp@DBlog{Macros to open and close graphs files.}% +\newdef\opengraphsfile#1{\@bsphack +% \end{macrocode} +% A command can determine if it occurs after \cs{opengraphsfile} but +% before \cs{closegraphsfile} by testing whether \cs{mfp@filename} is defined. +% \begin{macrocode} + \@ifmfpfileisopen% + {\Mfpic@warn + {An attempt has been made to open a graph file, #1, + \@msgbreak while another, \mfp@filename, is still open. + \@msgbreak Closing \mfp@filename.}% + \@closegraphsfile}% + {}% + \xdef\mfp@filename{#1}% +% \end{macrocode} +% The value of \cs{mfp@count} should be the number of the first figure. +% We use the existence of that figure as a signal that there are graphics +% to be included. +% \begin{macrocode} + \mfp@ifmpost{% + \openin\mfp@graph=\setfilename{\mfp@filename}{\number\mfp@count}% + \relax + \ifeof\mfp@graph \mfp@msg{}% + \Mfpic@msg + {No file \setfilename{\mfp@filename}{\number\mfp@count}.^^J}% + \global\mfpicdrafttrue + \else + \global\mfpicdraftfalse + \fi +% \end{macrocode} +% Type out the \MP-specific portion of a reminder to process the +% output. Then on to the \MF{} case. +% \begin{macrocode} + \if@mfp@nowrite \else + \immediate\openout\mfp@out=\mfp@filename.mp\relax + \Mfpic@msg{Don't forget to process \mfp@filename.mp! % + \@msgbreak (Apply metapost to \mfp@filename.mp.)}% + \fi + }{% metafont +% \end{macrocode} +% Under the \opt{metafont} option, we check for the \file{.tfm} file. +% We do not simply try to load the font because that might trigger +% some \prog{maketfm} script which could be disastrous at this point, +% when the \file{.mf} file is in an uncertain state. We open the +% \file{.tfm} for input, and check \cs{ifeof}, as we did in the +% \MP{} graphic case. +% \begin{macrocode} + \openin\mfp@graph=\mfp@filename.tfm\relax + \ifeof\mfp@graph \mfp@msg{}% + \Mfpic@msg{No file \mfp@filename.tfm .^^J}% + \global\let\@graphfont=\mfp@dummy + \global\mfpicdrafttrue +% \end{macrocode} +% If it does exist, we load the font and in either case type out the +% \MF{} specific portion of our reminder. +% \begin{macrocode} + \else + \global\font\@graphfont=\mfp@filename\relax + \global\mfpicdraftfalse + \fi + \if@mfp@nowrite \else + \immediate\openout\mfp@out=\mfp@filename.mf\relax + \Mfpic@msg{Don't forget to process \mfp@filename.mf! % + \@msgbreak (Apply metafont to \mfp@filename.mf, % + then gftopk to the resulting gf file.)}% + \fi + }% +% \end{macrocode} +% The input stream used for testing is closed and the +% unspecific portion of the reminder is typed out, then +% the above settings of \cs{ifmfpicdraft} are overridden if the user has +% explicitly chosen the \opt{draft} or \opt{final} option. The +% \opt{nowrite} option merely disables the \cs{@mfsrc} command. +% \begin{macrocode} + \closein\mfp@graph + \if@mfp@nowrite\else + \Mfpic@msg{Then reprocess this file (\jobname).^^J}% + \fi + \if@mfp@draft\global\mfpicdrafttrue\fi + \if@mfp@final\global\mfpicdraftfalse\fi + \if@mfp@nowrite\gdef\@mfsrc##1##2{}\fi +% \end{macrocode} +% The first two lines of the output file are comments identifying the +% file, the \mfpic{} version, the tex source file, and the date. +% Then we let \grafbase{} know the \mfpic{} version creating the file. +% After that we set the \mfc{mode}, the \mfc{mag} (both ignored by \MP), +% and arrange for \grafbase{} macros to be loaded. The current +% \grafbase{} checks the \gbc{mfpicversion}: if it is unknown, or not +% equal to the value of \gbc{grafbaseversion}, a diagnostic message is +% printed. +% \begin{macrocode} + \mfsrc{% + \mf@p\space\mfp@filename.m\mfp@ifmpost{p}{f}, % + generated by Mfpic, v\mfpfileversion\space\mfpfiledate,\@nl + \mf@p\space from TeX source "\jobname" % + on \mfp@today\space at \mfp@now\@nl + numeric mfpicversion; mfpicversion:=\mfpicversion;\@nl + if unknown mode: mode := localfont; fi\@nl + if unknown mag: mag := \number\mag/1000; fi\@nl + if unknown grafbase: input grafbase; fi\@nl\@nl +% \end{macrocode} +% Then a comparison of the version of this file, stored in +% \cs{mfpicversion} with the version stored in the \grafbase{} variable +% \mfc{grafbaseversion}. This should catch mismatches the previous test +% would miss. +% \begin{macrocode} + if unknown grafbaseversion: grafbaseversion := 0; fi\@nl + if grafbaseversion <> mfpicversion :\@nl + GBmsg "Bad mfpic installation: mfpic and grafbase % + versions do not match.";\@nl + fi\@nl}% +% \end{macrocode} +% For \opt{metapost} we need to load some color macros also, and write +% some setup for text labels (even if \cs{nomplabels}, because +% \cs{usemplabels could be turned on later}). \MF{} now can also handle +% the definitions in \file{dvipsnam.mp} but it seems a waste to load all +% those definitions just to get a few more grayscales (even given \MF{} +% can find that file). +% \begin{macrocode} + \mfp@ifmpost + {\mfsrc{% + if unknown Apricot: input dvipsnam.mp; fi\@nl + verbatimtex\@nl + \the\mfp@commonverbatimtex\@nl + \def\noexpand\everylabel{\the\every@tlabel}\@nl + \if@mfp@verbtex \the\mfp@verbtex\@nl \fi + etex;\@nl}% + \global\@mfp@verbtexfalse\mfp@verbtex{}% +% \end{macrocode} +% Finally, we write information to the output file, and/or set switches +% based on the options as they are currently known. The \cs{usemplabels} +% was delayed until now so that the order of it and \cs{usemetapost} +% before now would not matter. The other five are issued now because they +% might require a write to the output file. +% \begin{macrocode} + \@ifmplabels{\usemplabels}{}% + \if@mfp@truebbox \usetruebbox \fi + \if@mfp@overlabels \overlaylabels \fi}{}% + \if@mfp@clip \clipmfpic \fi + \if@mfp@clearsym \clearsymbols \fi + \if@shipping\else\stopshipping\fi + \@esphack}% +% \end{macrocode} +% +% \DescribeMacro{\closegraphsfile} +% This finishes off the output files and undefines \cs{mfp@filename}. +% We define an error message free version \cs{@closegraphsfile} for +% internal use. We unconditionally undefine \cs{mfp@filename} just in +% case. +% \begin{macrocode} +\newdef\closegraphsfile{% + \@ifmfpfileisopen{}{\nooutputfileerror\closegraphsfile}% + \@closegraphsfile \global\let\mfp@filename\UndEfInEd}% +\newdef\@closegraphsfile{% + \@ifmfpfileisopen + {\if@mfp@nowrite \else + \mfsrc{\@nl end.}\immediate\closeout\mfp@out + \fi}{}}% +% \end{macrocode} +% +% \DescribeMacro{\nooutputfileerror} +% We define a generic error message for macros that need an output file +% to write to. \cs{mfsrc} uses it, as does \cs{closegraphsfile}. +% \cs{mfpic} also uses it even though all its writes take place through +% \cs{mfsrc}. This avoids potentially hundreds of error messages. +% \begin{macrocode} +\def\nooutputfileerror#1{% + \mfp@errmsg {No output file has been opened.}% + {You have tried to used a command, #1, that requires an output^^J% + file to be opened with the \opengraphsfile command, which^^J% + was either not issued or was not successful.}}% +% \end{macrocode} +% +% +% \section{\Mfpic{} dimensions}\label{dimensions} +% +% A number of packages, especially figure drawing packages, allocate a +% great many dimension registers. The most familiar example is \PiCTeX{} +% which is at least partially responsible for most ``No room for a new +% \cs{dimen}'' error messages. \Mfpic{} also needs many dimension +% values, but some are set by macros that simply write the value to the +% \file{.mf} file and do not use any registers. A few are stored in +% \TeX{} registers, but most are stored using a trick with font +% dimensions. +% \begin{macrocode} +\mfp@DBlog{Using dummy font's dimensions, to spare TeX registers.}% +% \end{macrocode} +% While most fonts have relatively few font dimensions (twenty-two is a +% common number), it turns out that if one loads a font and immediately +% assigns a value to \cs{fontdimen}~$n$, Then \TeX{} acts as if the font +% has \cs{fontdimen}\,s 0 through $n$ available. They can be assigned +% dimension values just like \TeX{} dimension registers. +% +% Virtually all \TeX{} systems have a \file{dummy.tfm}, which contains +% no characters (it is used for syntax checking by some packages and +% classes). Since this trick will only work if we are the first to +% load the font (the \AmSTeX{} document style \file{amsppt.sty} loads +% the dummy font), we use another trick, which is to load it scaled to +% some unlikely value, which \TeX{} treats as a new font. +% \begin{macrocode} +\font\mfp@dummy=dummy scaled 1042 +\fontdimen100\mfp@dummy=0pt +% \end{macrocode} +% +% Some versions of \file{dummy.tfm} have values already assigned to font +% dimensions 0 through 22. It would probably not hurt to use those, but +% we'll be cautious and use only font dimensions 23 and up, making 78 +% available. +% +% We use an auxiliary count register to keep track of new font dimens. +% \begin{macrocode} +\newcount\mfp@fdc +\mfp@fdc=22 +% \end{macrocode} +% \DescribeMacro{\newfdim} +% We define a macros that mimics the behavior of \cs{newdimen}, for +% allocating font dimension numbers. It increments \cs{mfp@fdc} and +% defines its argument \texttt{\#1} to expand to an assignment of the +% current \cs{fontdimen}. +% \begin{macrocode} +\newdef\newfdim#1{% + \global\advance\mfp@fdc 1 + \xdef#1{\fontdimen\number\mfp@fdc\mfp@dummy}% + \wlog{\string#1=\string\fontdimen\number\mfp@fdc\mfp@dummy}}% +% \end{macrocode} +% The definition (\cs{xdef}) is global since font dimension +% assignments are always global anyway. \TeX{} will not accept font +% dimensions in its syntax for the dimension arithmetic commands +% \cs{advance}, \cs{multiply} and \cs{divide}. In the rare cases where we +% need to do this we assign the value to a temporary register and +% calculate with it. It is, however OK to use them with a numeric factor. +% +% We allocate a couple of boxes. At the end of an \mfpic{} +% environment, \cs{@wholegraph} is loaded with the picture (possibly +% null) as it exists then. Inside the environment, when text labels are +% processed, \cs{@textbox} holds this text temporarily so it can be +% measured, moved about, etc. We also define abbreviations for the +% frequent commands that specify the dimensions of \cs{@textbox} +% \begin{macrocode} +\mfp@DBlog{A box register for whole labeled graph, % + and a temporary one.}% +\newbox\@wholegraph +\newbox\@textbox +\newdef\tb@ht{\ht\@textbox}% height, +\newdef\tb@dp{\dp\@textbox}% depth and +\newdef\tb@wd{\wd\@textbox}% width of the text label. +% \end{macrocode} +% +% When labels are processed, they are accumulated in the box +% \cs{@alltlabels}. We allocate it, and four \cs{newfdim}\,s for the +% location of the four sides. +% \begin{macrocode} +\newbox\@alltlabels +\newfdim\@tlabelstop +\newfdim\@tlabelsbot +\newfdim\@tlabelsleft +\newfdim\@tlabelsright +% \end{macrocode} +% +% It can be argued that dimensions not needed by \TeX{} should be stored +% in the output file rather than allocating (font) dimensions. These are +% everything below from \cs{pointsize} through \cs{symbolspace}, +% inclusive. This would make syncronictity between \TeX{} and \MF{} easier +% to maintain. Those that are needed by \TeX{} are then few enough to be +% regular \cs{dimen} registers, making them automatically local to each +% \env{mfpic} environment. Unfortunately, changing to such a scheme could +% break some past \mfpic{} files. It would also require recoding every +% command that now writes one of these dimensions to the output. +% +% One of these (\cs{@graphright}) is unused, except for debugging. +% We could also code around \cs{@graphwd} because it is always +% \cs{wd}\cs{@wholegraph}. ^^A Is this true? Check it out. +% \begin{macrocode} +\mfp@DBlog{Internal dimension parameters for graph dimensions...}% +\newfdim\@graphwd +\newfdim\@graphright +\newfdim\@graphleft +\newfdim\@graphtop +\newfdim\@graphbot +\mfp@DBlog{...and dimension parameters for tlabel positioning.}% +\newfdim\tb@raise +\newfdim\tb@moveright +\newfdim\tb@totalht +% \end{macrocode} +% +% The following are for label adjustments. The first two are used to +% implement the feature that all labels can be simultaneously shifted an +% equal amount. The last is for the feature that the label can be a +% certain distance separated from the point where it is placed. +% \begin{macrocode} +\newfdim\tlabel@hadj +\newfdim\tlabel@vadj +\newfdim\tlabel@sep +\tlabel@hadj=0pt +\tlabel@vadj=0pt +\tlabel@sep=0pt +% \end{macrocode} +% +% The following are default parameters for various graphics commands that +% take an optional argument for the size of something. We allocate them, +% and then initialize them. +% \begin{macrocode} +\mfp@DBlog{User level dimension parameters, with default settings.}% +\newfdim\mfpicunit % unit of length +\newfdim\pointsize % diameter of circle +\newfdim\shadespace % spacing of shade dots +\newfdim\polkadotspace % spacing of polkadots +\newfdim\hatchspace % spacing of lines +\newfdim\headlen % size of arrowhead (\arrow) +\newfdim\axisheadlen % size of arrowhead (x, y axes) +\newfdim\sideheadlen % size of arrowhead (border axes) +\newfdim\hashlen % length of marks on axes +\newfdim\dashlen % length of dashes (\dashed) +\newfdim\dashspace % space between dashes +\newfdim\dotsize % size of dots (\dotted) +\newfdim\dotspace % space between dots +\newfdim\symbolspace % space between symbols (\plot) +% +\mfpicunit=1pt +\pointsize=2pt +\shadespace=1pt +\polkadotspace=10pt +\hatchspace=3pt +\headlen=3pt +\axisheadlen=5pt +\sideheadlen=0pt +\hashlen=4pt +\dashlen=4pt +\dashspace=4pt +\dotsize=0.5pt +\dotspace=3pt +\symbolspace=5pt +% \end{macrocode} +% +% Font dimensions are global, and so not restricted to an \env{mfpic} +% environment even when assigned inside one. This would require the +% user to restore a value every time one picture needed a different +% value from the rest. To avoid requiring this, the following macro is +% used to save all values of these dimensions at the start of a picture, +% and to restore the saved values at the end. (Some internal dimensions +% (\cs{@graph...}, for example) don't need saving since they are reset +% with each picture.) +% \begin{macrocode} +\newdef\save@mfpicdimens{% + \edef\restore@mfpicdimens{% + \mfpicunit =\the\mfpicunit + \pointsize =\the\pointsize + \shadespace =\the\shadespace +\polkadotspace =\the\polkadotspace + \hatchspace =\the\hatchspace + \headlen =\the\headlen + \axisheadlen =\the\axisheadlen + \sideheadlen =\the\sideheadlen + \hashlen =\the\hashlen + \dashlen =\the\dashlen + \dashspace =\the\dashspace + \dotsize =\the\dotsize + \dotspace =\the\dotspace + \symbolspace =\the\symbolspace + \tlabel@hadj =\the\tlabel@hadj + \tlabel@vadj =\the\tlabel@vadj + \tlabel@sep =\the\tlabel@sep}}% +% \end{macrocode} +% +% \DescribeMacro{\mfpframesep} +% \DescribeMacro{\mfpframethickness} +% \DescribeMacro{\mfpicheight} +% \DescribeMacro{\mfpicwidth} +% \DescribeMacro{\mfpiccaptionskip} +% Here are the few dimension registers we do allocate. The first two are +% scratch registers, the next two govern frames, and the last two are set +% after each picture to that pictures size. A \cs{vskip} of +% \cs{mfpiccaptionskip} is placed between figure and caption by +% \cs{tcaption}. +% \begin{macrocode} +\newdimen\mfp@scratch +\newdimen\mfp@scratchB +\newdimen\mfpframesep +\newdimen\mfpframethickness +\newdimen\mfpicheight +\newdimen\mfpicwidth +\newskip\mfpiccaptionskip +\mfpframethickness0.4pt +\mfpframesep2pt +\mfpiccaptionskip=\medskipamount +% \end{macrocode} +% +% +% \section{Helper macros}\label{helper} +% +% \DescribeMacro{\mfpicnumber} +% We make a user-level macro for setting the number of the next graph. +% The purpose of this is so that the output file can be used as a font, +% setting the figure numbers to the ascii codes of printable characters. +% Then creating a composite figure is as easy as changing fonts: +% \marg{\cs{pic} ABABAAB}. The motivation came from a discussion on +% \texttt{comp.text.tex} started by someone who wanted to input a sequence +% of 0's and 1's and get a corresponding sequence of black and white +% squares. +% \begin{macrocode} +\def\mfpicnumber#1{\global\mfp@count=#1\relax}% +% \end{macrocode} +% +% \DescribeMacro{\mfpaddto} +% When placing text at intervals on an axis, we need to automatically +% calculate coordinates to feed to the \cs{tlabel} command. The +% following is a utility macro to add two real numbers. It is currently +% used only in the \cs{axislabels} command, so it needn't be globally +% defined, but it might be handy in the future. +% \begin{itemize} +% \item[] \texttt{\#1} is a \emph{macro} that expands to some number. +% \item[] \texttt{\#2} is a number to add to it. +% \end{itemize} +% The result is stored again in \texttt{\#1}, overwriting the old value. +% +% \DescribeMacro{\mfpmultiply} +% For my personal use (or for power users), this is the multiplicative +% version, with the same syntax and behavior. +% \begin{macrocode} +\newdef\mfpaddto#1#2{\mfp@scratch=#1pt\advance\mfp@scratch#2pt + \edef#1{\mfp@strippt\mfp@scratch}}% +\newdef\mfpmultiply#1#2{\mfp@scratch=#1pt \mfp@scratch#2\mfp@scratch + \edef#1{\mfp@strippt\mfp@scratch}}% +\begingroup + \@makeother P\@makeother T\lowercase{\gdef\mfp@factor#1PT{#1}}% +\endgroup +\newdef\mfp@strippt{\@xp\mfp@factor\the}% +% \end{macrocode} +% +% A few user-level utilities. +% +% \DescribeMacro{\pointdef} +% A point defining macro, suggested by a user. +% \begin{itemize} +% \item[] \texttt{\#1} is a symbolic name for a point, only letters. +% \item[] \texttt{\#2} and \texttt{\#3} are the coordinates. +% \item[] Usage: \cs{pointdef}\marg{A}\parg{2,5} makes \cs{A} expand +% to \texttt{(2,5)}, \cs{Ax} to \texttt{2}, and \cs{Ay} to +% \texttt{5}. +% \end{itemize} +% \begin{macrocode} +\newdef\pointdef#1(#2,#3){% + \@namedef{#1}{(#2,#3)}\@namedef{#1x}{#2}\@namedef{#1y}{#3}}% +% \end{macrocode} +% +% \DescribeMacro{\pairarray} +% \DescribeMacro{\numericarray} +% The first enables the simultaneous definition of \MF{} pair variables +% \mfc{A1}, \mfc{A2}, etc, \mfc{A[n]} by writing, +% \cs{pairarray}\marg{A}\marg{\meta{list}}, the list being a list of +% $n$ ordred pairs. Numeric variables can be created similarly with the +% second command. +% \begin{macrocode} +\newdef\pairarray#1{% + \mfcmd{save #1}\mfsrc{textpairs (#1)}\mfp@writedata}% +\newdef\numericarray#1{\mfcmd{save #1; numeric #1; numeric #1[]}% + \mfsrc{list (#1)}\mfp@writedata}% +% \end{macrocode} +% +% \DescribeMacro{\lightershade} +% \DescribeMacro{\darkershade} +% Shade adjustment macros. They just multiply or divide \cs{shadespace} +% by 1.2. +% \begin{macrocode} +\newdef\lightershade{\shadespace=1.2\shadespace}% +\newdef\darkershade{\shadespace=.833333\shadespace}% +% \end{macrocode} +% +% \DescribeMacro{\dashlineset} +% \DescribeMacro{\dotlineset} +% The following arrange for contrastive dashed lines. \cs{dashlineset} +% just resets the default parameters that the \cs{dashed} macro uses, +% \cs{dotlineset} sets these parameters so that \cs{dashed} produces +% something almost dotted. +% \begin{macrocode} +\newdef\dashlineset{\dashlen=4pt \dashspace=4pt}% +\newdef\dotlineset{\dashlen=1pt \dashspace=2pt}% +% \end{macrocode} +% +% \DescribeMacro{\ifpointfill} +% With the commands \cs{pointfilltrue} or \cs{pointfillfalse} the user +% can specify points drawn with the \cs{point} command to be either +% filled in or not. +% \begin{macrocode} +\let\ifpointfill\iftrue +\newdef\pointfilltrue{\mfp@let\ifpointfill\iftrue}% +\newdef\pointfillfalse{\mfp@let\ifpointfill\iffalse}% +% \end{macrocode} +% +% +% \section{Macros to implement prefix commands}\label{prefix} +% +% \Mfpic{} prefix macros change the behavior of the figure macros. +% Normally we want \cs{circle}\marg{...} to draw the solid outline of a +% circle. So normally \cs{circle}\marg{...} will write a drawing command +% followed by a path expression giving the circle to draw. But +% \cs{dashed}\cs{circle}\marg{...} should write a \emph{dashing} command +% and \emph{omit} the drawing command. Thus, \emph{rendering} macros +% like \cs{dashed} need to set a switch, and figure macros like +% \cs{circle} need to test that switch. +% +% Similar considerations hold for prefix macros that transform the +% figure. The logic is that, at the \MF{} level, every figure macro +% is syntactically a path expression. Every prefix accepts a path +% expression as input and has a path as its return value, so a +% combination prefix + path expression is again a path expression. +% Prefixes may also have side effects, such as adding some ink to the +% current picture. Such prefixes are called \emph{rendering} macros. +% Rendering macros normally return the same path as their argument, but +% there are macros that modify the path. Some applying a linear +% transform, some close an open path, some return a subpath. These we call +% \emph{modification} macros. +% +% This scheme is quite simple, but unfortunately too simple. To avoid +% having to explicitly type a rendering prefix every time, we need +% the above mentioned ability to pass information to the figure macros. +% Moreover, \MF{} abhors an `isolated expression', so the first prefix +% has to write something with a different syntax, and pass the info that +% it has already done so on to later prefixes, who need to test that +% info. +% \begin{macrocode} +\mfp@DBlog{Tests to control multiple prefix commands.}% +% \end{macrocode} +% +% Every prefix macro needs to know if it is the first or a later one. +% They test this \cs{if} command and also set it to false. The +% figure macros, which are last in the chain, close by resetting it true. +% \begin{macrocode} +\newif\if@startfig\@startfigtrue +% \end{macrocode} +% +% If a prefix is a rendering prefix, it writes the rendering code +% and sets the following switch to false, letting the figure macro know +% it needn't invoke the default rendering, +% Figure macros close by resetting it true. Some modification macros don't +% touch it at all (the \cs{@modmac}\,s) others just test it +% (\cs{@closmac}\,s). +% \begin{macrocode} +\newif\if@imrend\@imrendtrue +% \end{macrocode} +% +% The following macro is always (and only) invoked by the first prefix +% macro. It writes the code that prevents an isolated expression. It +% stores the following path expression in the variable \gbc{curpath}. Thus +% every combination of prefixes followed by a figure macro is +% syntactically a \MF{} variable assignment command. +% \begin{macrocode} +\newdef\store@path{\mfsrc{\@nl store (curpath)}}% +% \end{macrocode} +% +% Every prefix and figure macro has to invoke \cs{@firststage}, since +% each is potentially the first in the sequence. If +% \cs{if@startfig} is true, it writes the storing command, sets +% \cs{@startfigfalse}, and says that rendering is needed. (The +% rendering macros immediately cancel that switch.) +% \begin{macrocode} +\newdef\@firststage{\relax + \if@startfig \store@path \@imrendtrue \@startfigfalse\fi}% +% \end{macrocode} +% +% \DescribeMacro{\@rendmac} +% Every rendering macro invokes this command. After the first-stage code +% it writes its rendering command (via \cs{mfsrc}) and passes on the info +% that rendering is no longer required of the figure macro. +% \begin{macrocode} +\newdef\@rendmac{\@firststage \@imrendfalse \mfsrc}% +% \end{macrocode} +% +% \DescribeMacro{\@modmac} +% It is possible we should call this something else, as only \cs{arrow} +% and \cs{reverse} use \cs{@modmac}. Other modifications cause the +% modified path to be drawn as if (modifier+figure) were a solitary figure +% macro. This would be pointless for a reversed path or a path with +% arrowhead added, as presumably the original path would already be drawn. +% Moreover, it can be argued (for \MP{} at least) that the arrowhead +% should be drawn on top of the shaft. This is the only significant effect of +% coding \cs{arrow} and \cs{reverse} as \cs{@modmac}\,s. +% +% It simply invokes the common first-stage code and writes its \MF{} code. +% \begin{macrocode} +\newdef\@modmac{\@firststage \mfsrc}% +% \end{macrocode} +% +% \DescribeMacro{\@closmac} +% Other modification macros were added later, and it turned out that +% they needed the same treatment as the closure macros that already +% existed. Therefore, most modification macros invoke \cs{@closmac}. The +% \emph{figure} macros proceed as follows: they invoke the \cs{@firststage} +% code, then write a rendering macro if necessary, then make +% \cs{@starfigtrue} (for the next figure), then write \MF{} code that +% defines the path. These modification macros do only the first two, +% counting on the figure macro to follow to invoke the last two. The idea +% is that {closure + figure} should act the same as if the path it defines +% were encoded as a single figure command. +% +% The \cs{@modmac} and \cs{@closmac} macros differ only when there are +% no preceeding rendering macros. In that case it is as if \cs{draw} (or +% more generally \cs{@render}) precedes the \cs{@closmac} macro. That +% drawing happens \emph{in addition to} any rendering macros that follow. +% This implicitly added \cs{draw} is not present for \cs{@modmac} macros, +% unless it is added by the following figure macro itself. +% \begin{macrocode} +\newdef\@closmac{\@firststage \if@imrend\@xp\@render\fi \mfsrc}% +% \end{macrocode} +% +% \DescribeMacro{\setrender} +% As mentioned above, when a figure macro is invoked without a +% rendering prefix, it will invoke some default. That default is stored +% in the macro \cs{@render}, which can be changed for special effects. +% Initially we define it as \cs{draw} to draw solid paths, but provide a +% command for the user to change it. +% \begin{macrocode} +\newdef\@render{\draw[]}% +\newdef\setrender#1{\mfp@def\@render{#1}}% +% \end{macrocode} +% +% \DescribeMacro{\@figmac} +% A figure macro will invoke the common first-stage code, then check +% if rendering is needed. If so, it issues the \cs{@render} command. +% It also resets the startfig switche. Since a figure macro completes +% an assignment command in \MF, we use \cs{mfcmd}, which places a +% semicolon at the end of the code it writes. We define the first part +% (all but the writing) as a separate command because there are a few cases +% where we need to delay that writing. +% \begin{macrocode} +\newdef\@figmacstart{% + \@firststage \if@imrend\@xp\@render\fi \@startfigtrue}% +\newdef\@figmac{\@figmacstart\mfcmd}% +% \end{macrocode} +% +% \DescribeMacro{\@listmac} +% The list macros take as their last argument a list of $(x,y)$ pairs. +% That list can either be typed directly into +% the \TeX{} source file (inside braces, separated by commas) or be +% present in an external datafile. Either way, the data is written +% as a list of \MF{} pairs within an enclosing pair of +% parentheses. Since these are all figure macros, \cs{@listmac} starts out +% just like \cs{@figmac}, but it writes only part of its arguments, the +% last one being handled by \cs{mfp@writedata}. +% +% \cs{mfp@writedata} looks ahead to see if the token \cs{datafile} +% follows, if it does \cs{mfp@writefile} is invoked, which gobbles +% the \cs{datafile} token and processes the filename that should follow it. +% Otherwise, \cs{mflist} is invoked to write the list in braces +% that should follow. +% +% \cs{mfp@writedata} is also used by non-figure macros such as the axis +% marks macros, plus \cs{piechart} and \cs{barchart}. +% \begin{macrocode} +\newdef\@listmac#1{\@figmacstart\mfsrc{#1}\mfp@writedata}% +\newdef\mfp@writedata{% + \mfp@ifnextchar\datafile{\mfp@writefile}{\mflist}}% +\newdef\mfp@writefile\datafile#1{\@processdatafile{#1}{\mfp@rwdata}}% +% \end{macrocode} +% +% \DescribeMacro{\mftitle} +% \DescribeMacro{\tmtitle} +% These go here because they didn't seem to go anywhere else. The are +% mainly for debugging the example files. \cs{getmfp@toks} assigns the +% following group to a token register and then invokes its argument. +% \cs{mftitle} and \cs{tmtitle} use this to write the code into +% the string argument of the \grafbase{} command \gbc{mftitle}. +% \cs{mftitle} does only that, while \cs{tmtitle} also writes the argument +% to the \file{.log} file and typesets it in the document. +% +% We write the argument as a token list because that is the the easiest +% verbatim-like way to do it. +% \begin{macrocode} +\newif\if@mfpswitch +\newdef\mftitle{\@bsphack\@mfpswitchtrue\mfp@gettoks\mf@title}% +\newdef\tmtitle{\mfp@gettoks\tm@title}% +\newdef\mfp@gettoks#1{\afterassignment#1\mfp@toks=}% +\newdef\tm@title{\@mfpswitchfalse\mf@title + \wlog{\the\mfp@toks}{\the\mfp@toks}}% +\newdef\mf@title{\mfsrc{}% + \immediate\write\mfp@out{mftitle "\the\mfp@toks";}% + \if@mfpswitch\@esphack\fi}% +% \end{macrocode} +% +% \DescribeMacro{\noship} +% \DescribeMacro{\stopshipping} +% \DescribeMacro{\resumeshipping} +% To turn off character shipping for duration of innermost enclosing +% group (eg, \env{mfpic} environment). As far as I know it has never been +% tested with \MP. (It hasn't been tested recently even in \MF.) The \MF{} +% code prevents the figure from being added to the font, the \TeX{} switch +% \texttt{shipping} is checked before \cs{endmfpic} attempts to add the +% (nonexistent) figure to the document. +% \begin{macrocode} +\newdef\stopshipping{\mfp@let\if@shipping\iffalse + \@ifmfpfileisopen{\mfcmd{save shipit;def shipit = relax enddef}}{}}% +\newdef\resumeshipping{\mfp@let\if@shipping\iftrue + \@ifmfpfileisopen{\mfcmd{save shipit;def shipit = shipit_ enddef}}{}}% +\newlet\noship\stopshipping +\resumeshipping +% \end{macrocode} +% +% +% \section{Macros for getting data from files}\label{rwdata} +% +% The following command contains the common code to open a data file for +% reading. The first parameter is the filename, the second is what to do +% if it exists and is nonempty. We first try to \cs{openin} the file and +% issue an error message if that fails. Then we skip any initial blank +% lines and comments and complain if that takes us to the end of the +% file. Otherwise we execute the command specified. Afterwards, since +% each \cs{plotdata} command in a given \env{mfpic} environment +% starts with the linetype at which the previous one ended, we allow the +% value of \cs{mfp@linetype} to survive the group. If \texttt{\#2} is +% not \cs{plotdata}, this is harmless (I hope). +% \begin{macrocode} +\newdef\@processdatafile#1#2{% + \openin\mfp@data=#1\relax + \ifeof\mfp@data \nodatafileerror{#1}% + \else + \begingroup + \mfp@resetwhitespace \mfp@setcomment + \skipBlanksandComments + \ifeof\mfp@data \emptydatafileerror{#1}\else #2\fi + \global\mfp@n=\mfp@linetype + \endgroup + \mfp@linetype=\mfp@n + \fi + \closein\mfp@data}% +% \end{macrocode} +% +% \DescribeMacro{\nodatafileerror} +% \DescribeMacro{\emptydatafileerror} +% These are error messages for missing or empty data files: +% \begin{macrocode} +\newdef\nodatafileerror#1{% + \mfp@errmsg{No data file: #1 .}% + {The data file you tried to plot can't be found.}}% +\newdef\emptydatafileerror#1{% + \mfp@errmsg{Empty data file: #1 .}% + {The file you tried to plot contains only empty lines and comments.}}% +% \end{macrocode} +% +% When reading files it is important that white space in the files +% always have the same meaning for \TeX{}. This utility resets spaces, +% tabs and EOLs to the standard categories. +% \begin{macrocode} +\newdef\mfp@resetwhitespace{% + \catcode`\^^M=5 \catcode`\ =10 \catcode`\^^I=10 }% +% \end{macrocode} +% +% \DescribeMacro{\skipcomments} +% This does what it says, skipping comments in a data file. It reads a +% line from a previously opened file (input stream \cs{mfp@data}) and +% compares it to \cs{@empty}. It calls itself when they are equal (a +% comment line). When this macro finishes, \cs{mfp@temp} contains either +% \cs{par} (blank line or EOF) or real data. +% \begin{macrocode} +\mfp@ifdefined\@empty{}{\def\@empty{}}% +\newdef\skipcomments{\read\mfp@data to \mfp@temp + \ifx\mfp@temp\@empty \@xp\skipcomments\fi}% +% \end{macrocode} +% +% \DescribeMacro{\skipBlanksandComments} +% This command first skips comments. After that \cs{mfp@temp} can contain +% \cs{par}, indicating either EOF or a blank line, or something else. +% In the first case (EOF) the macro terminates, in the second case (blank) +% it calls itself again, in the third case it also terminates, having +% presumably found real data. +% +% When this is called, a file should already be open (by +% \cs{@processdatafile}) using the handle \cs{mfp@data}. +% +% The macro \cs{@XP} causes two macros after the next token to be +% expanded, removing the two \cs{fi}\,s (and so avoiding deep nesting). +% \begin{macrocode} +\newdef\skipBlanksandComments{\skipcomments + \ifeof\mfp@data + \else\ifx\mfp@temp\mfp@par \@XP\skipBlanksandComments + \fi\fi}% +% \end{macrocode} +% +% The following two commands, \cs{mfp@rwdata} and \cs{mfp@rwdataloop} +% perform the work of writing the file (read stream \cs{mfp@data} opened +% by \cs{@processdatafile}). +% +% The counter \cs{mfp@n} is used to keep track of how many lines of the +% data file have been written to one line of the output. The token +% \cs{sequence} in a \cs{using} specification will expand to the value of +% the counter \cs{mfp@sequence}. +% +% When this first macro is called, a non-blank line has been read to the +% macro \cs{mfp@temp}, to which we now add a space. The macro +% \cs{mfp@buffer} is what will be written to the output file as soon as it +% is long enough. We initialize it by defining it to be an open +% parenthesis followed by the result of applying \cs{parse@data} to the +% contents of \cs{mfp@temp}. Then we call \cs{mfp@rwdataloop}, which does +% the actual reading and writing. +% \begin{macrocode} + \def\mfp@rwdata{\mfp@n=1 \mfp@sequence=1 + \def\sequence{\number\mfp@sequence}% + \edef\mfp@temp{\mfp@temp\space}% + \edef\mfp@buffer{(\@xp\parse@data\mfp@temp\mfp@delim}% + \mfp@rwdataloop}% +% \end{macrocode} +% +% At this point, the buffer has been started with the first datum, so we +% read another line. If that is blank, we write the buffer (and the closing +% parenthesis and a semicolon) and terminate the loop. Otherwise we go +% through a loop: +% \begin{enumerate} +% \item Increment the sequence counter, +% \item add a comma to the buffer, +% \item test whether the buffer is `full', and +% \item add the datum to the buffer. If the buffer is full in step~3, it is +% written to the output and cleared before going to step~4. +% \end{enumerate} +% \cs{mfp@rwdataloop} loops by calling itself at the end. Whenever +% \cs{mfp@temp} is empty (comment line read), (1)--(4) are skipped and +% another line read. +% \begin{macrocode} + \def\mfp@rwdataloop{% + \read\mfp@data to \mfp@temp + \ifx\mfp@temp\mfp@par + \mfcmd{\mfp@buffer)}% + \else + \ifx\mfp@temp\@empty % comment line, read another + \else + \edef\mfp@temp{\mfp@temp\space}% + \advance\mfp@sequence1 + \edef\mfp@buffer{\mfp@buffer\mfp@join}% + \ifnum\mfp@n<\mfpdataperline\relax + \advance\mfp@n1 + \else + \mfsrc{\mfp@buffer}% + \mfp@n=1 + \def\mfp@buffer{}% + \fi + \edef\mfp@buffer{\mfp@buffer + \@xp\parse@data\mfp@temp\mfp@delim}% + \fi + \@xp\mfp@rwdataloop + \fi}% +% \end{macrocode} +% +% +% \section{Various \CMF{} Settings.}\label{MFsettings} +% +% \DescribeMacro{\drawpen} +% \DescribeMacro{\pen} +% \DescribeMacro{\penwd} +% Macros that write changes in default \grafbase{} variables now use the +% construct ``\gbc{save x; <type> x; x := <value>;}'' (via a call to +% \cs{setmfvariable}). This makes changes local if inside a given \env{mfpic} +% environment, global if outside. An exception is \gbc{penwd} which, as an +% internal variable uses `\gbc{interim}' instead (via the \grafbase{} +% command \gbc{resizedrawpen}). Both \cs{drawpen} and \cs{pen} have been +% used in the past, while \cs{penwd} is more consistent with other +% commands, so we keep all three. +% \begin{macrocode} +\newdef\drawpen#1{\mfcmd{\@nl resizedrawpen (#1)}}% +\newlet\pen=\drawpen \newlet\penwd=\drawpen +% \end{macrocode} +% +% \DescribeMacro{\shadewd} +% The \cs{shade} macro works in \MF{} by adding many copies of the small +% picture \gbc{shadedot} to the figure, in \MP{} the parameters +% \gbc{shadewd} and \cs{shadespace} are simply used to calculate a level +% of gray and a color fill is used. +% +% \DescribeMacro{\polkadotwd} +% However, both \MF{} and \MP{} handle polkadots the same. The only +% difference is \MF's need for fitting to a pixel grid. But that is +% handled in \grafbase. +% \begin{macrocode} +\newdef\shadewd#1{\setmfnumeric{shadewd}{#1}}% +\newdef\polkadotwd#1{\setmfnumeric{polkadotwd}{#1}}% +% \end{macrocode} +% +% \DescribeMacro{\hatchwd} +% The thickness of lines in the hatching fill. +% \begin{macrocode} +\newdef\hatchwd#1{\setmfnumeric{hatchwd}{#1}% + \setmfvariable{pen}{hatchpen}{pencircle scaled hatchwd}}% +% \end{macrocode} +% +% \DescribeMacro{\dashpattern} +% A dash pattern consists (internal to \MF) of three arrays. The +% \grafbase{} command \gbc{dashpat} accepts a name, and a sequence of +% numbers representing the sizes of dashes and spaces, and builds these +% arrays. +% \begin{macrocode} +\newdef\dashpattern#1#2{\mfcmd{save #1; dashpat (#1) (#2)}}% +% \end{macrocode} +% +% \DescribeMacro{\settension} +% This sets the default tension for \cs{curve} commands, as well as for +% any command that takes an optional argument of the form +% \oarg{s\meta{tens}}. This includes \cs{function}, \cs{plrfcn}, +% \cs{fcncurve}, \cs{datafile}, \cs{plotdata} and others. It also sets the +% default tension for \cs{sclosed} and \cs{bclosed}. The value should be +% at least $3/4$. +% \begin{macrocode} +\newdef\settension#1{\setmfnumeric{default_tension}{#1}}% +% \end{macrocode} +% +% +% \section{Settings for text label placement in +% figures}\label{labelsettings} +% +% \cs{tlabel}\,s are `justified' by placing a particular point of the +% text at the location specified. The \cs{tlabel} command accepts an +% optional argument containing two letters. There are 4 possibilities +% for the first and three for the second. It turns out to be easier to +% process these if we have a command that converts these to numbers, and +% then \cs{ifcase} can be used. There is a third part of the optional +% argument usable only in \MP{}: a number indicating degrees of rotation. +% +% \DescribeMacro{\tlabeljustify} +% The multi-part definition of \cs{tlabeljustify} is to guard +% against confusing error messages if some part of this optional argument +% is empty. The code assumes that if there are only 2, 1 or no parts, then +% later parts should be left unchanged. The rotation part is empty by +% default (rather than 0), because some commands will emit a warning if +% a nonempty rotation exists without \opt{mlabels}. +% +% The result of \cs{tlabeljustify} is that \cs{tl@vpos} is set equal to +% $-1$ if the first letter is (default) \texttt{B} (for Baseline), and +% 0--2 if it is \texttt{b} (bottom), \texttt{c} (center) or \texttt{t} +% (top). Similarly, \cs{tl@hpos} is set equal to $-1$ if the second +% letter is (default) \texttt{l} (for left), and 0 or 1 if it is +% \texttt{c} (center) or \texttt{r} (right). +% +% The rotation part is just saved in \cs{tlabel@rot}. This is now true +% even without \opt{mplabels} in case it is turned on later. It is +% ignored by \cs{tlabel} without \opt{mplabels}, but a warning is issued +% here anyway. +% \begin{macrocode} +\newcount\tl@vpos \newcount\tl@hpos +\tl@vpos=-1 \tl@hpos=-1 +\newdef\tlabel@rot{}% +% +\newdef\tlabeljustify#1{% + \mfp@ifempty{#1}{}{\mfp@justify#1\mfp@delim}}% +\def\mfp@justify#1#2\mfp@delim{\mfp@local\mfp@vconv{#1}% + \mfp@ifempty{#2}{}{\@mfp@justify#2\mfp@delim}}% +\newdef\@mfp@justify#1#2\mfp@delim{% + \mfp@local\mfp@hconv{#1}\mfp@local\edef\tlabel@rot{#2} + \@ifmplabels{}% + {\mfp@ifempty{#2}{}% + {\Mfpic@warn{Rotation of labels is not supported without the + mplabels\@msgbreak option. Rotation may be ignored\@online .}}}}% +\newdef\mfp@vconv#1{% + \if B#1\tl@vpos=-1 \else + \if b#1\tl@vpos= 0 \else + \if c#1\tl@vpos= 1 \else + \if t#1\tl@vpos= 2 \else + \tl@vpos=-1 \mfp@justifyerror + \fi\fi\fi\fi}% +\newdef\mfp@hconv#1{% + \if l#1\tl@hpos=-1 \else + \if c#1\tl@hpos= 0 \else + \if r#1\tl@hpos= 1 \else + \tl@hpos=-1 \mfp@justifyerror + \fi\fi\fi}% +\newdef\mfp@justifyerror{% + \mfp@errmsg{Invalid justification parameter for text label.}% + {The optional argument for a text label must be^^J% + one of B, b, c or t^^J + followed by l or r or c,^^J% + followed by an angle (optionally).}}% +% \end{macrocode} +% +% \DescribeMacro{\tlpathjustify} +% This acts just like \cs{tlabeljustify} from the user's point of view. +% Since it is only for users, and not used internally, it merely defines +% three macros that \cs{@@@tlpath} passes on to \cs{tlabeljustify} when no +% justification parameter is present. +% \begin{macrocode} +\newdef\tlpathjustify#1{% + \mfp@ifempty{#1}{}{\tlp@justify#1\mfp@delim}}% +\newdef\tlp@justify#1#2\mfp@delim{\mfp@def\tlpath@v{#1}% + \mfp@ifempty{#2}{}{\tlp@@justify#2\mfp@delim}}% +\newdef\tlp@@justify#1#2\mfp@delim{% + \mfp@def\tlpath@h{#1}\mfp@def\tlpath@r{#2}}% +\tlpathjustify{cc}% +% \end{macrocode} +% +% \DescribeMacro{\tlabelsep} +% \DescribeMacro{\tlabeloffset} +% \cs{tlabelsep} takes an absolute length as its argument and sets +% parameters that determine by how much a label is separated from the +% point it is placed at. This is in case something is drawn at that point, +% such as a dot or a hash mark on an axis. +% +% \cs{tlabeloffset}, on the other hand, takes a pair of dimensions, +% representing offsets. This is mainly so that, if labels seem to be off, +% they can all be shifted with one command. +% +% Both these values are written to the \MF{} file for the sake of the +% commands that draw rectangles or ovals around labels. +% \begin{macrocode} +\newdef\tlabelsep#1{\mfp@local\tlabel@sep=#1\relax + \setmfnumeric{label_sep}{\the\tlabel@sep}}% +\newdef\tlabeloffset#1#2{% + \mfp@local\tlabel@hadj=#1\relax \mfp@local\tlabel@vadj=#2\relax + \setmfvariable{pair}{label_adjust}% + {(\the\tlabel@hadj,\the\tlabel@vadj)}}% +% \end{macrocode} +% +% \DescribeMacro{\everytlabel} +% Every line of a multiline label is written inside a group, so +% adjustments to baselineskip and other things are difficult or impossible. +% Therefore, \cs{everytlabel} is provided to define tokens to be inserted +% before the label code, outside these groups. It is not itself a token +% variable, so that that it can write the tokens to the \MP{} file once, +% instead of at every label. +% \begin{macrocode} +\newdef\everytlabel{\afterassignment\@everytlabel + \mfp@local\every@tlabel}% +\newdef\@everytlabel{% + \mfp@ifmpost + {\@ifmfpfileisopen + {\mfcmd{verbatimtex\@nl + \def\noexpand\everylabel{\the\every@tlabel} etex}}% + {}}% + {}}% +% \end{macrocode} +% +% +% \section{Other settings}\label{othersettings} +% +% \DescribeMacro{\headshape} +% This sets the arrowhead shape. The parameters are: the ratio of width +% to length, the tension (see \file{grafbase.dtx}) and a boolean +% (\gbc{true} or \gbc{false}) to say whether the the head is filled, or +% only the barbs are drawn. (In retrospect, it would have been more +% consistent with other commands to have one \TeX{} parameter with commas +% separating the components.) +% \begin{macrocode} +\newdef\headshape#1#2#3{\mfcmd{\@nl headshape (#1, #2, #3)}}% +% \end{macrocode} +% +% \DescribeMacro{\mfpdefinecolor} +% \prog{Mfpic} supports color under \MP{} by writing all color +% definitions to the output \file{.mp} file. In order to support a +% \LaTeX-like color syntax, all the color models allowed by the color +% package correspond to a \grafbase{} function that returns a \MP{} +% color value. For example, \gbc{cmyk(.3,.3,0,.7)} returns \gbc{(0,0,.3)}, +% a very dark blue. This can be set by +% \cs{mfpdefinecolor}\marg{vdblue}\marg{cmyk}\marg{.3,.3,0,.7}. +% +% \DescribeMacro{\fillcolor} +% \DescribeMacro{\drawcolor} +% \DescribeMacro{\headcolor} +% \DescribeMacro{\hatchcolor} +% \DescribeMacro{\pointcolor} +% \DescribeMacro{\tlabelcolor} +% \DescribeMacro{\backgroundcolor} +% To support the syntax +% \cs{fillcolor}\oarg{\meta{model}}\marg{\meta{parameters}}, we just +% call \cs{@mfpcolor} with the \grafbase{} color variable name +% \gbc{fillcolor}. +% \begin{macrocode} +\newdef\mfpdefinecolor#1#2#3{\setmfcolor{#1}{#2(#3)}}% +\newdef\fillcolor{\@mfpcolor{fillcolor}}% +\newdef\drawcolor{\@mfpcolor{drawcolor}}% +\newdef\headcolor{\@mfpcolor{headcolor}}% +\newdef\hatchcolor{\@mfpcolor{hatchcolor}}% +\newdef\pointcolor{\@mfpcolor{pointcolor}}% +\newdef\tlabelcolor{\@mfpcolor{tlabelcolor}}% +\newdef\backgroundcolor{\@mfpcolor{background}}% +\newdef\@mfpcolor#1{% + \mfp@ifnextchar[{\mfp@color{#1}}{\setmfcolor{#1}}}% +\newdef\mfp@color#1[#2]#3{\setmfcolor{#1}{#2(#3)}}% +% \end{macrocode} +% +% When \cs{plotdata} is used to draw several graphs from one file, each +% sequence of non-blank lines corresponds to a different curve with a +% different style of rendering. The user has the option to cycle through +% different dashing patterns, different colors, or different symbols. +% +% Internally, \cs{plotdata} issues the command \cs{mfp@setstyle} (which +% can be defined to be any rendering macro), followed by a path defining +% command such as \cs{curve} or \cs{polyline}, followed by a command +% that reads the data and writes it in a suitable format. The following +% commands essentially allow the user to select the rendering macro. +% They start by resetting \cs{mfp@linetype}, the count register that keeps +% track of how many curves have been drawn, then they define +% \cs{mfp@setstyle}. +% +% \DescribeMacro{\dashedlines} +% \cs{dashedlines} uses the rendering prefix \cs{gendashed} with 6 +% different dashing patterns \gbc{dashtype0} through \gbc{dashtype5}. +% These are actually selected in \MF{} through the command +% \gbc{getdashpat}. This takes care of cycling back to +% \gbc{dashtype0} when the number of available dash patterns is exceeded. +% Dashed lines is the default. +% \begin{macrocode} +\newdef\dashedlines{\mfp@local\mfp@linetype0 + \mfp@def\mfp@setstyle{\gendashed{getdashpat\number\mfp@linetype}}}% +\dashedlines +% \end{macrocode} +% +% \DescribeMacro{\coloredlines} +% This uses \cs{draw} with an optional color parameter set +% to \gbc{colortype0} through (by default) \gbc{colortype 7}. These are +% color variables defined by \grafbase{}. It also issues a warning if +% \MF{} is being used. As with \cs{dashedlines}, a \MP{} command +% \gbc{getcolor} selects these colors. +% \begin{macrocode} +\newdef\coloredlines{% + \mfp@ifmpost + {\mfp@local\mfp@linetype0 + \mfp@def\mfp@setstyle{\draw [getcolor\number\mfp@linetype]}}% + {\Mfpic@warn{You can't use \string\coloredlines\space in + Metafont.\@msgbreak Using \dashedlines instead}% + \dashedlines}}% +% \end{macrocode} +% +% \DescribeMacro{\pointedlines} +% This makes a sort of dotted line, except the dots are actually different +% symbols. It uses the rendering macro \cs{plot} with a parameter cycling +% through 9 different symbols. +% \begin{macrocode} +\newdef\pointedlines{\mfp@local\mfp@linetype0 + \mfp@def\mfp@setstyle{\plot{getsymbol\number\mfp@linetype}}}% +% \end{macrocode} +% +% \DescribeMacro{\datapointsonly} +% \cs{datapointsonly} uses symbols like \cs{pointedlines}, but places +% them only at the data points from the file. It uses the rendering macro +% \cs{plotnodes} with a parameter cycling through the same 9 symbols. +% \begin{macrocode} +\newdef\datapointsonly{\mfp@local\mfp@linetype0 + \mfp@def\mfp@setstyle{\relax + \plotnodes{getsymbol \number\mfp@linetype}}}% +% \end{macrocode} +% +% \DescribeMacro{\reconfigureplot} +% This command allows the user to set the dashes, colors and symbols used +% by the \cs{plotdata} command. The first argument is the plotting method +% to be changed (\texttt{dashes}, \texttt{colors}, or \texttt{symbols}) +% and the second argument is a comma separated list of appropriate type +% variables for \cs{plotdata} to cycle through. For example, +% \cs{reconfigureplot}\marg{dashes} takes a list of dashing patterns +% (previously defined by the \cs{dashpattern} command) separated by +% commas. It writes a command instructing \MF{} to redefine the arrays +% \mfc{dashtype0}, \mfc{dashtype1}, etc., used with \cs{gendashed} when +% \cs{dashedlines} is in effect. The number of patterns is counted by \MF, +% which also handles the mod-ing operation now. +% +% \cs{reconfigureplot}\marg{colors} takes a list of colors (expressions or +% color names previously defined) separated by commas. It redefines +% \gbc{colortype0}, etc., used with \cs{plotdata} when \cs{coloredlines} +% is in effect. +% +% \cs{reconfigureplot}\marg{symbols} takes a list of symbols (\MF{} path +% expressions, one of the symbols available to \cs{plotsymbol}, or path +% names defined by \cs{store}) separated by commas. It redefines +% \gbc{pointtype0}, etc., used by \cs{plotdata} when \cs{pointedlines} or +% \cs{datapointsonly} is in effect. +% +% \DescribeMacro{\defaultplot} +% This restores \mfpic's predefined defaults for dash patterns, colors and +% symbols in \cs{plotdata}. The one argument is one of the words +% \texttt{dashes}, \texttt{colors}, or \texttt{symbols}, indicating which +% plotting method is to be restored. +% \begin{macrocode} +\newdef\reconfigureplot#1{\mfsrc{setdata#1}\mfp@writedata}% +\newdef\defaultplot#1{\mfcmd{default#1}}% +% \end{macrocode} +% +% \DescribeMacro{\mfplinetype} +% \DescribeMacro{\mfplinestyle} +% The user-level commands \cs{mfplinetype} and \cs{mfplinestyle} allow the +% user to set the starting value of \cs{mfp@linetype}. The default is to +% start at $0$. The names ``linestyle'' and ``linetype'' come from +% an analogous system of changing rendering in \prog{gnuplot}. +% \begin{macrocode} +\newdef\mfplinetype#1{\mfp@local\mfp@linetype=#1}% +\newlet\mfplinestyle\mfplinetype +\mfplinetype{0}% +% \end{macrocode} +% +% \prog{Mfpic} has 6 possible axes, the x- and y-axes pass through the +% origin, $(0,0)$, the four border axes are at the edges of the graph +% space, possibly offset from it by some amount. These four commands hold +% the amount of that offset in graph units, the default being 0. +% \begin{macrocode} +\newdef\mfp@lshift{0}% +\newdef\mfp@bshift{0}% +\newdef\mfp@rshift{0}% +\newdef\mfp@tshift{0}% +% \end{macrocode} +% +% \DescribeMacro{\axismargin} +% \DescribeMacro{\setaxismargins} +% \DescribeMacro{\setallaxismargins} +% These are the user-level command for setting the above offsets. The +% first argument to \cs{axismargin} is one of the letters l, b, r, or t to +% select the axis and the second is the offset in graph units. A positive +% offset represents an inward shift, which is why we call them +% \emph{margins}. The arguments of \cs{setaxismargins} are four offsets +% for the axes (in the above order, which is anticlockwise, starting +% with the left). \cs{setallaxismargins} takes one offset and applies it +% to all axes. +% +% The values are passed on to \MF{} in the variables \gbc{laxis}, +% \gbc{baxis}, \gbc{raxis}, and \gbc{taxis}. They are also needed by the +% \cs{axislabels} command so they are saved in macros. +% \begin{macrocode} +\newdef\axismargin#1#2{\setmfnumeric{#1axis}{#2}% + \mfp@local\@namedef{mfp@#1shift}{#2}}% +\newdef\setaxismargins#1#2#3#4{\axismargin l{#1}\axismargin b{#2}% + \axismargin r{#3}\axismargin t{#4}}% +\newdef\setallaxismargins#1{\setaxismargins{#1}{#1}{#1}{#1}}% +% \end{macrocode} +% +% The following converts axis letters to a numeric, making conditionals for +% axes simpler to code (\cs{ifcase} versus the six nested \cs{if}\,s we +% see here.) Plus we get to define the error message only once. The +% first argument is the letter and the second argument is the calling +% command (for the error message). +% \begin{macrocode} +\newcount\mfp@axisnum +\def\get@axisnum#1#2{% + \if x#1\relax \mfp@axisnum0 + \else\if y#1\relax \mfp@axisnum1 + \else\if l#1\relax \mfp@axisnum2 + \else\if b#1\relax \mfp@axisnum3 + \else\if r#1\relax \mfp@axisnum4 + \else\if t#1\relax \mfp@axisnum5 + \else + \mfp@errmsg {Invalid axis letter "#1".}% + {The command #2 requires an axis to be designated by one of^^J% + the following letters: x, y, l, b, r, or t. If you proceed, ^^J% + x will be assumed.}% + \fi\fi\fi\fi\fi\fi}% +% \end{macrocode} +% +% \DescribeMacro{\setaxismarks} +% \DescribeMacro{\setxmarks} +% \DescribeMacro{\setymarks} +% \DescribeMacro{\setbordermarks} +% \DescribeMacro{\setallbordermarks} +% The tick marks (or hash marks) on the axes can be in three possible +% positions: centered on the axes, all on one side, or all on the other +% side. The default for the x- and y-axes is centered, for the border axes +% it is inside. For changing this we provide the \cs{setaxismarks} command, +% whose first argument is the axis letter, and whose second argument is +% one of the words \texttt{inside}, \texttt{outside}, \texttt{centered}, +% \texttt{ontop}, \texttt{onbottom}, \texttt{onleft}, or \texttt{onright}. +% \begin{macrocode} +\newdef\setaxismarks#1#2{\setmfnumeric{#1tick}{#2}}% +\newdef\setxmarks#1{\setaxismarks x{#1}}% +\newdef\setymarks#1{\setaxismarks y{#1}}% +\newdef\setbordermarks#1#2#3#4{\setaxismarks l{#1}\setaxismarks b{#2}% + \setaxismarks r{#3}\setaxismarks t{#4}}% +\newdef\setallbordermarks#1{\setbordermarks{#1}{#1}{#1}{#1}}% +% \end{macrocode} +% +% \DescribeMacro{\smoothdata} +% \DescribeMacro{\unsmoothdata} +% The \cs{datafile} and \cs{plotdata} commands originally just created +% polygonal paths, but users requested the ability to draw smooth ones. +% Originally only the commands below (\cs{smoothdata} and +% \cs{unsmoothdata}) were written to do this. Later, these file +% manipulation commands were given optional arguments to achieve the same +% effect, so now the commands below just set the defaults for the optional +% parameter, storing them in the macros \cs{mfp@smoothness} and +% \cs{mfp@tension}. The latter can be used to adjust the tension of the +% \MF{} path if smoothness is `s'. Default tension is now empty rather +% than 1 so we can implement a scheme to change the actual default used. +% \begin{macrocode} +\newdef\smoothdata{\null@opt\@smoothdata}% +\newdef\@smoothdata[#1]{\mfp@def\mfp@smoothness{s}% + \mfp@def\mfp@tension{#1}}% +\newdef\unsmoothdata{\mfp@def\mfp@smoothness{p}% + \mfp@def\mfp@tension{}}% +\unsmoothdata% default +% \end{macrocode} +% +% \DescribeMacro{\using} +% \DescribeMacro{\usingpairdefault} +% \DescribeMacro{\usingnumericdefault} +% These commands control how we interpret data in a file. +% The command \cs{using} is named after a keyword in \prog{gnuplot}. It +% controls which datum is plotted against which by \cs{plotdata} and +% \cs{datafile}. The default is to read the first two space separated +% words on a line as the x- and y-coordinate of a point. To allow that +% there might be more data on a line, it is also assumed that the second +% word is followed by a space and the rest of the line is read as a third +% parameter that is not used. In case there are only two words, +% \mfpic{} will always add a space on the end and then the third +% parameter will be empty. +% +% The \cs{parse@data} command reads its argument as delimited +% parameters, and the \cs{using} command tells what those delimiters are. +% For example, in the first part of +% \cs{using}\marg{\#1 \#2 \#3}\marg{(\#1,\#2)}, we are telling +% \cs{parse@data} that everything on a line up to the first space is the +% first parameter, and everything up to the second space is the second +% parameter and the rest of the line is the third parameter. In the second +% part we are telling it that what we write to the output is a pair in +% parentheses with the first two parameters separated by a comma. This +% example is the default as we see here in \cs{usingpairdefault}. This +% command can be issued by a user to return to that default. The user can +% also issue \cs{usingnumericdefault} to write the first space separated +% word as a single numeric. This is for commands like \cs{piechart}. +% +% \DescribeMacro{\mfpdataperline} +% \cs{mfpdataperline} is a user level macro that controls the maximum +% number of points that will be written to a single line in the output. +% \begin{macrocode} +\newdef\using#1#2{\mfp@def\parse@data#1\mfp@delim{#2}}% +\newdef\usingpairdefault{\using{##1 ##2 ##3}{(##1,##2)}}% +\newdef\usingnumericdefault{\using{##1 ##2}{##1}}% +\usingpairdefault +\newdef\mfpdataperline{5}% +% \end{macrocode} +% +% The following macros are used internally by \cs{datafile} and \cs{plotdata}. +% A comment line is read by \TeX{} as empty so we need an empty macro to +% test against, and a blank line is read as \cs{par} (not the primitive +% \cs{par}, but the literal token \cs{par}, so it tests as equal to +% \cs{mfp@par}. Early versions of \cs{plotdata} wrote a literal \MF{} path +% expression to the output file and \cs{mfp@join} created the \mfc{--} +% between points. Now we write one of the \grafbase{} list-to-path +% commands followed by a comma separated list of points, so \cs{mfp@join} +% has morphed into a comma. +% \begin{macrocode} +\newdef\mfp@par{\par}% +\newdef\mfp@join{,}% +% \end{macrocode} +% +% \DescribeMacro{\makepercentother} +% \DescribeMacro{\makepercentcomment} +% \DescribeMacro{\mfpdatacomment} +% The user can change the comment character for data files with +% something like \cs{mfpdatacomment}\marg{\cs{\#}}. This also changes the +% percent character to category `other'. We can also use the percent sign +% as part of the numeric data by sandwiching the \cs{using} command +% between \cs{makepercentother} and \cs{makepercentcomment}. Every file +% reading command issues \cs{mfp@setcomment} before reading. The count +% register \cs{@datacomment} hold the ASCII code of the current comment +% character, the default being the percent sign. +% \begin{macrocode} +\newcount\@datacommentchar \@datacommentchar`\% +\newdef\makepercentother{\@makeother\%}% +\newdef\makepercentcomment{\catcode`\%=14 }% +\newdef\mfpdatacomment#1{\mfp@local\@datacommentchar`#1}% +\newdef\mfp@setcomment{\makepercentother\catcode\@datacommentchar14 }% +% \end{macrocode} +% +% \DescribeMacro{\fdef} +% The following is for defining functions to be used in \cs{function} +% through \cs{plrregion}. The first argument is the name of the function, +% the second is its variable, the last is the \MF{} code. Obviously its +% use requires a knowledge of the \MF{} language. The function produced is +% a \mfc{vardef}, and can contain almost arbitrary \MF{} code, but must +% end with an expression. Normally it must be a numerical expression, to +% be use in \cs{function}, or a pair expression so it can be used alone in +% the last argument of \cs{parafcn}. +% +% We apply \cs{@makeother} to \texttt{\#} so it doesn't get doubled. The +% \texttt{\#} is frequent in vardefs among the \MF{} gurus. +% \begin{macrocode} +\newdef\fdef{\begingroup\@makeother\#\preservelines\@fdef}% +\newdef\@fdef#1#2#3{\mfcmd{\@nl save #1;\@nl + vardef #1 (expr #2) = \@nl #3\@nl enddef}\endgroup}% +% \end{macrocode} +% +% The following is executed last inside \cs{@mfpic@graf@macs}. It is a +% hook for adding new definitions. It is initialized to empty, and add-on +% packages can add to it. +% \begin{macrocode} +\newdef\mfp@additions{}% +% \end{macrocode} +% +% +% \section{The main graphics macros}\label{main} +% +% In order to avoid redefining commands of other packages and in order +% to avoid having other packages redefine \mfpic{} commands, all mfpic +% commands that cannot be used outside the \env{mfpic} environment are +% defined anew with every such environment. This is accomplished by having +% the \cs{mfpic} command execute \cs{@mfpic@graf@macs}, which expands to +% all those definitions. Grouping localizes the definitions, so outside +% \env{mfpic} environments, these commands revert to being undefined, or +% to there original definitions if they had any. As might be expected it +% is quite long, over 300 lines of code at last count. +% \begin{macrocode} +\newdef\@mfpic@graf@macs{% +% \end{macrocode} +% +% \subsection{Plotting data from files}\label{datafiles} +% +% \DescribeMacro{\plotdata} +% Most of the \mfpic{} graphic commands take optional arguments. Most of +% them follow the scheme below: \cs{@plotdata} takes a mandatory argument +% enclosed in brackets, and does the work. \cs{plotdata} is simply defined +% to test for an optional argument and pass it or a default to +% \cs{@plotdata}. In this case, the default option is signaled by +% passing empty brackets via \cs{null@opt}. +% +% \cs{@plotdata} follows the scheme of most of the data file processing +% commands: it calls \cs{@processdatafile} with the name of the file (the +% second parameter of \cs{@plotdata}) and another command, \cs{mfp@doplots}, +% which really does the work. The argument of \cs{mfp@doplots} is the +% original optional parameter of \cs{plotdata}. This optional parameter is +% the smoothness, which may be \oarg{s\meta{tension}} for a smooth path +% or \oarg{p} for a polygonal path, or empty to select whatever default +% was created by \cs{smoothdata}. +% \begin{macrocode} + \newdef\plotdata{\null@opt\@plotdata}% + \newdef\@plotdata[##1]##2{\@processdatafile{##2}{\mfp@doplots{##1}}}% +% \end{macrocode} +% +% \cs{mfp@doplots} is a self-looping macro. It issues the rendering +% prefix (in \cs{mfp@setstyle}), increments the linetype, and writes the +% path expression defined by the first set of data in the file (via +% \cs{do@datafile}, which \emph{really} does the work and which stops at a +% blank line). That part, when prefixed by \cs{@figmacstart}, functions +% as a \cs{@figmac}. When finished with one figure, \cs{@if@enddata} +% checks if there is another set of data in the file. If so, +% \cs{mfp@doplots} calls itself again. +% +% The argument is the smoothness parameter(s), which it merely passes on. +% There is no filename argument: since \cs{@processdatafile} has already +% opened the input stream \cs{mfp@data} and subsequent macros will read +% from it. +% \begin{macrocode} + \def\mfp@doplots##1{\mfp@setstyle + \advance\mfp@linetype1 \@figmacstart + \do@datafile{##1}% + \@if@enddata{}{\mfp@doplots{##1}}}% +% \end{macrocode} +% +% When two blank lines occur in succession, \cs{plotdata} is suppose to +% stop. \cs{@ifenddata} is called when \cs{do@datafile} ends (one blank +% line was found), it checks for another blank line (or end-of-file) +% and, if it finds one, selects the first of the two alternatives that +% follow. +% \begin{macrocode} + \newdef\@if@enddata{% check for another blank line + \ifeof\mfp@data \@xp\@firstoftwo + \else + \skipcomments + \ifx\mfp@temp\mfp@par \@XP\@firstoftwo + \else \@XP\@secondoftwo + \fi + \fi}% +% \end{macrocode} +% +% \DescribeMacro{\datafile} +% \cs{datafile} defines a path connecting the points in a datafile. The +% optional parameter is the smoothness, as in \cs{plotdata}. The other +% parameter is the filename. \cs{@datafile} does the figure macro stuff, +% opens the data file, and calls \cs{do@datafile} which does all the work. +% \begin{macrocode} + \newdef\datafile{\null@opt\@datafile}% + \newdef\@datafile[##1]##2{\@figmacstart + \@processdatafile{##2}{\do@datafile{##1}}}% +% \end{macrocode} +% +% I lied. Actually all \cs{do@datafile} does is handle any empty +% optional parameter and call \cs{@do@datafile} to do the work. +% \begin{macrocode} + \newdef\do@datafile##1{% + \do@mtparam{##1}{\mfp@smoothness\mfp@tension}\@do@datafile}% +% \end{macrocode} +% +% And \cs{@do@datafile} is mainly just a wrapper, processing the optional +% parameter (passed by either \cs{plotdata} or \cs{datafile}) which +% selects what figure making code should be written. For +% \oarg{s\meta{tension}} a \gbc{curve} command is used. For \oarg{p}, a +% \gbc{polyline}. (The `\cs{mf@F}' means the curve is not closed). +% +% After that, \cs{mfp@rwdata} is called, which reads and writes the +% data. +% \begin{macrocode} + \newdef\@do@datafile[##1##2]{% + \mfsrc{% + \if s##1 \mfp@ifempty{##2}{curve }{tcurve (##2) }% + \else polyline + \fi (\mf@F)}\mfp@rwdata}% +% \end{macrocode} +% +% \subsection{The prefix commands}\label{prefixcommands} +% +% \subsubsection{Storing and reusing a figure}\label{storing} +% +% \DescribeMacro{\store} +% This stores an \mfpic{} path in a \MF{} path variable. The argument is +% the variable name. It should be followed by an \mfpic{} figure macro +% (such as \cs{rect}\marg{...}). The stored path can be reused via the +% \cs{mfobj} command. This command is written as a \cs{@rendmac} even +% though it does no rendering. This is so (1)~it will turn off implicit +% rendering (any rendering must be explicitly written) and (2) it can be +% placed anywhere within the prefix area. This is new behavior with +% version 0.7. Prior to this it was required to place the path to be +% stored as a second argument. Though that argument could contain other +% prefixes in addition to the path, it was required that no other prefixes +% precede \cs{store}. Note that \cs{store} takes a second argument but +% it merely puts it back. This is so that the old syntax (with the figure +% macro in braces) will continue to work. +% \begin{macrocode} + \newdef\store##1##2{\@rendmac{stored (##1)}##2}% +% \end{macrocode} +% +% \DescribeMacro{\mfobj} +% \DescribeMacro{\mpobj} +% This is the interface to use a \cs{store}-d object. +% \cs{mfobj}\marg{\meta{name}} is a figure macro, and should act pretty +% much exactly the same as if the figure macro that had been stored in the +% variable were typed in its place. Its one argument, the variable name, +% is read by \cs{@figmac}, which operates as described previously, either +% implicitly rendering the path, or allowing it to be picked up by +% preceding prefix macros. +% \begin{macrocode} + \newlet\mfobj\@figmac + \newlet\mpobj\@figmac +% \end{macrocode} +% +% \subsubsection{Subpaths} +% +% \DescribeMacro{\cutoffbefore} +% This macro take one mandatory argument which is an object stored with +% \cs{store}. It modifies the path it is prefixed to so that it starts +% at its first point of intersection with the object, cutting off any +% earlier part of the path. +% +% \DescribeMacro{\cutoffafter} +% This is similar, except the modified path ends at the last point of +% intersection between the following path and the object, cutting off +% any later part of the path. It is internally the same as applying +% \cs{cutoffbefore} to the reversed path and reversing the result. +% +% \DescribeMacro{\trimpath} +% This trims off the specified amounts from the start and end of the +% path. The amounts are two absolute dimensions, separated by commas. +% They may be \TeX{} dimensions. If the first dimension is absent, it is +% set to \texttt{0pt}, if the second is absent, it is set equal to the +% first. (So if both are absent, nothing is trimmed.) +% \begin{macrocode} + \newdef\cutoffafter##1{\@closmac{cutoffafter (##1)}}% + \newdef\cutoffbefore##1{\@closmac{cutoffbefore (##1)}}% + \newdef\trimpath##1{\@getdimens##1,,\mfp@delim + \@closmac{trimmedpath (\the\mfp@scratch, \the\mfp@scratchB)}}% + \newdef\@getdimens##1,##2,##3\mfp@delim{% + \mfp@scratch \@ifmtsub{##1}{\z@}\relax + \mfp@scratchB\@ifmtsub{##2}{\mfp@scratch}\relax}% +% \end{macrocode} +% +% \DescribeMacro{\partpath} +% \DescribeMacro{\subpath} +% These produce a subpath of the following path. Each takes a mandatory +% parameter containing two numbers separated by a comma. In +% \cs{partpath}, these should be between 0 and 1 and produce a fraction +% of the following path. In \cs{subpath}, these are absolute numbers between +% 0 and the number of segments in the path, and it produces the equivalent of +% \MF's \mfc{subpath} primitive. +% \begin{macrocode} + \newdef\partpath##1{\@closmac{partialpath (##1)}}% + \newdef\subpath##1{\@closmac{gsubpath (##1)}}% +% \end{macrocode} +% +% \subsubsection{Drawing a curve}\label{drawing} +% +% These are rendering macros that draw the curve in some fashion: solid, +% dashed, colored, etc. +% +% \DescribeMacro{\draw} +% \cs{draw} is the initial definition of \cs{@render}. It takes one +% optional argument, a color. In \MF{}, where color are just numerics, if +% it is ${}\ge 1$ (representing white) the path is subtracted from the +% picture, otherwise it is drawn in black. +% +% \begin{macrocode} + \newdef\draw{\null@opt\@draw}% + \newdef\@draw[##1]{% + \@rendmac{\mfp@ifempty{##1}{drawn}{colordrawn (##1)}}}% +% \end{macrocode} +% +% \DescribeMacro{\dashed} +% \cs{dashed} (as well as \cs{dotted}) takes one optional argument, +% which should contain the length of the dashes (diameter of dots) and +% the length of the spaces between, separated by a comma. The defaults +% can be seen in the code below. +% \begin{macrocode} + \newdef\dashed{\simple@opt\@dashed{\the\dashlen,\the\dashspace}}% + \newdef\@dashed##1{\@rendmac{DASHED (##1)}}% + \newdef\dotted{\simple@opt\@dotted{\the\dotsize,\the\dotspace}}% + \newdef\@dotted##1{\@rendmac{dotted (##1)}}% +% \end{macrocode} +% +% \cs{gendashed} takes one mandatory argument, the name of a dash pattern +% previously defined by \cs{dashpattern} +% \begin{macrocode} + \newdef\gendashed##1{\@rendmac{gendashed (##1)}}% +% \end{macrocode} +% +% \cs{plot} is like \cs{dotted}, except the dots are variously shaped +% symbols. It takes one optional argument containing the size of the +% symbol and the spacing, separated by a comma, and one mandatory +% argument, the name of the symbol. This can in principal be any +% expression of type \mfc{picture} or \mfc{path}. (In \MP, type +% \mfc{string} is also permitted). For the size parameter to work +% correctly, the symbol should be a path, and it should have 1 as it's +% natural size. \Mfpic{} provides the predefined paths +% \texttt{Triangle}, \texttt{Square}, \texttt{Circle}, \texttt{Star}, +% \texttt{Diamond}, \texttt{Plus}, \texttt{Cross} and \texttt{Asterisk}. +% The first 5 have filled-in versions: \texttt{SolidTriangle}, etc. +% \begin{macrocode} + \newdef\plot{\simple@opt\@plot{\the\pointsize, \the\symbolspace}}% + \newdef\@plot##1##2{\@rendmac{doplot (##2, ##1)}}% +% \end{macrocode} +% +% Sometimes, rather than equally spaced dots or symbols, we would rather +% have a symbol at each `node' of the following path. If the path is +% created by a list macro, then usually each point in the list is a node +% (but the spline paths are exceptions). For other figures, the nodes +% can seem pretty random. For example, a \cs{circle} command without optional +% argument produces a curve with 8 equally spaced nodes, but with optional +% argument the nodes depend on how it is drawn and the size of any angle +% parameter. +% +% \cs{plotnodes} has almost the same syntax as \cs{plot}, but since it +% places the symbols only at the nodes of the path, there is no spacing +% parameter in the optional argument. +% \begin{macrocode} + \newdef\plotnodes{\simple@opt\@plotnodes{\the\pointsize}}% + \newdef\@plotnodes##1##2{\@rendmac{plotnodes (##2, ##1)}}% +% \end{macrocode} +% +% \subsubsection{Closing a curve}\label{closing} +% +% \DescribeMacro{\sclosed} +% \DescribeMacro{\bclosed} +% \DescribeMacro{\lclosed} +% \DescribeMacro{\cbclosed} +% \DescribeMacro{\qbclosed} +% \DescribeMacro{\uclosed} +% These close a path defined by whatever figure macro follows it. The +% first closes smoothly in the same manner that \cs{curve} creates a +% smooth path, the second uses an ordinary \MF{} B\'ezier. These two have +% an optional argument: the amount of tension to put in the connecting +% link. Higher tension produces a linking segment with sharper turns near +% the endpoints and a flatter path in between. This makes no sense with +% \cs{lclosed}, \cs{qbclosed} or \cs{cbclosed}. The first always draws a +% straight line and the other two requires a link explicitly determined by +% the beginning and ending segments of the path: a cubic B-spline for +% \cs{cbclosed} and a quadratic B-spline for \cs{qbclosed}. See +% \cs{closedcspline} and \cs{closedqspline} described later. +% +% Due to a misunderstanding on my part, \cs{uclosed} was defined in a more +% complicated manner than necessary, and actually produced exactly the +% same path as \cs{bclosed}. So now they are just made to be equal. +% \begin{macrocode} + \newdef\@closed##1##2{% + \@closmac{##1closed\mfp@ifempty{##2}{}{t (##2)}}}% + \newdef\bclosed{\null@opt\@bclosed}% + \newdef\@bclosed[##1]{\@closed b{##1}}% + \newdef\sclosed{\null@opt\@sclosed}% + \newdef\@sclosed[##1]{\@closed s{##1}}% + \newdef\lclosed{\@closed l{}}% + \newdef\cbclosed{\@closed{cb}{}}% + \newdef\qbclosed{\@closed{qb}{}}% + \newlet\uclosed\bclosed +% \end{macrocode} +% +% \subsubsection{Filling a closed curve}\label{filling} +% +% The next few prefix macros fill the interior of the closed path that +% follows with some sort of pattern. The path must be either already +% closed (like that produced by \cs{rect} or \cs{circle}) or explicitly +% closed with a closing prefix. A non-closed path will simply be drawn +% with a solid line. +% +% \DescribeMacro{\tess} +% \cs{tess} takes one mandatory argument, the name of a previously defined +% tile, and fills with shifted copies of the tile. +% \begin{macrocode} + \newdef\tess##1{\@rendmac{tess (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\shade} +% \DescribeMacro{\polkadot} +% \cs{shade} and \cs{polkadot} take one optional parameter, the separation +% between dots, defaulting to \cs{shadespace} (resp., \cs{polkadotspace}). +% The size of the dots is set by issuing the command \cs{shadewd} (resp., +% \cs{polkadotwd}). +% \begin{macrocode} + \newdef\shade{\simple@opt\@shade{\the\shadespace}}% + \newdef\@shade##1{\@rendmac{shade (##1)}}% + \newdef\polkadot{\simple@opt\@polkadot{\the\polkadotspace}}% + \newdef\@polkadot##1{\@rendmac{polkadot (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\thatch} +% \DescribeMacro{\lhatch} +% \DescribeMacro{\rhatch} +% \DescribeMacro{\xhatch} +% The hatching macros mostly take two optional parameters, the +% separation of the hatching lines (default \cs{hatchspace}) and their +% color. One slight exception is \cs{thatch}, which is called by all the +% others. Its first optional argument is the separation \emph{and} the +% angle (default $0$) of the lines, separated by a comma. The other +% hatching macros have a fixed angle. \cs{lhatch} has lines at a $-45$ +% degree angle (upper left to lower right), \cs{rhatch} produces the opposite +% diagonal, and \cs{xhatch} does both sets of lines (cross hatching). +% \begin{macrocode} + \newdef\thatch{\simple@opt\@thatch{\the\hatchspace,0}}% + \newdef\@thatch##1{\null@opt{\@@thatch{##1}}}% + \newdef\@@thatch##1[##2]{\@rendmac{% + \mfp@ifempty{##2}{thatch}{colorthatch (##2)} (##1)}}% + \newdef\lhatch{\simple@opt\@lhatch{\the\hatchspace}}% + \newdef\@lhatch##1{\@thatch{##1,-45}}% + \newdef\rhatch{\simple@opt\@rhatch{\the\hatchspace}}% + \newdef\@rhatch##1{\@thatch{##1,45}}% + \newdef\xhatch{\simple@opt\@xhatch{\the\hatchspace}}% + \newdef\@xhatch##1{\null@opt{\@@xhatch{##1}}}% + \newdef\@@xhatch##1[##2]{\@rendmac{% + \mfp@ifempty{##2}{xhatch}{colorxhatch (##2)} (##1)}}% + \newlet\hatch=\xhatch +% \end{macrocode} +% +% Commands that might conceivably interfere with small bits of \TeX{} +% code in labels have been renamed. Thus, instead of \cs{fill}, which is a +% \LaTeX{} text mode command, we have \cs{gfill}. We also have \cs{gclear} +% and \cs{gclip}. The `g' is for `graphic'. Later, commands that deal +% with text (labels and captions), have `t' prepended to their more +% natural name, thus \cs{tlabel} and \cs{tcaption}. +% +% \DescribeMacro{\gfill} +% \DescribeMacro{\gclear} +% \DescribeMacro{\gclip} +% \cs{gfill} take one optional argument, the color with which to fill. +% Under \MF{} the color must be a numeric (representing a level of gray) +% or one of the color functions, which are defined in \file{grafbase.mf} +% to return numeric values. +% +% \cs{gclear} will actually fill with the color \texttt{background} in \MP. +% \cs{gclip} might seem to be the inverse of \cs{gclear} (clearing the +% outside of a region), but in \MP{} the mechanism is completely +% different. One wishes \MP{} had an `inverse clip' command to use +% instead of filling with \gbc{background}. The figure macro following +% these commands must be a closed path. +% \begin{macrocode} + \newdef\gfill{\null@opt\@gfill}% + \newdef\@gfill[##1]{% + \@rendmac{\mfp@ifempty{##1}{filled}{colorfilled (##1)}}}% + \newdef\gclear{\@rendmac{unfilled}}% + \newdef\gclip{\@rendmac{Clip}}% +% \end{macrocode} +% +% \subsubsection{Transforming a curve}\label{transforming} +% +% The following are transformation prefixes. They are all but one +% implemented with \cs{@closmac} for reasons covered earlier. Most have a +% mandatory argument, the parameters of the transformation. Because of the +% implementation, one can insert rendering macros between a transformation +% macro and the path being transformed, and they will apply to the +% untransformed path. +% +% If the \env{mfpic} environment has different x and y scales, the +% \cs{rotatepath} and \cs{reflectpath} compensates so that the result is +% congruent to the original. The others do not because this is what users +% seem to expect. +% \begin{itemize} +% \item \cs{reverse} and \cs{xyswappath} have no argument. +% \item \cs{rotatepath} takes \marg{\meta{point},\meta{angle}}. +% \item \cs{shiftpath} takes \marg{\meta{pair}}. +% \item \cs{scalepath} takes \marg{\meta{center of scaling},\meta{factor}}. +% \item \cs{xscalepath} takes \marg{\meta{x-center},\meta{factor}}. +% \item \cs{yscalepath} takes \marg{\meta{y-center},\meta{factor}}. +% \item \cs{slantpath} takes \marg{\meta{y-pivot},\meta{factor}}. +% \item \cs{xslantpath} = \cs{slantpath}. +% \item \cs{yslantpath} takes \marg{\meta{x-pivot},\meta{factor}}. +% \item \cs{reflectpath} takes \marg{\meta{point1},\meta{point2}}, the +% endpoints of a `mirror'. +% \item \cs{transformpath} takes \marg{\meta{transformer}}, a \MF{} +% `transformer' (see ``The \MF book'', page~212). +% \end{itemize} +% +% All of them simply write the \grafbase{} command of nearly the same +% name. +% \begin{macrocode} + \newdef\reverse{\@modmac{reverse}}% + \newdef\xyswappath{\@closmac{xyswappedpath}}% + \newdef\rotatepath##1{\@closmac{rotatedpath (##1)}}% + \newdef\shiftpath##1{\@closmac{shiftedpath (##1)}}% + \newdef\scalepath##1{\@closmac{scaledpath (##1)}}% + \newdef\xscalepath##1{\@closmac{xscaledpath (##1)}}% + \newdef\yscalepath##1{\@closmac{yscaledpath (##1)}}% + \newdef\slantpath##1{\@closmac{xslantedpath (##1)}}% + \newlet\xslantpath\slantpath + \newdef\yslantpath##1{\@closmac{yslantedpath (##1)}}% + \newdef\reflectpath##1{\@closmac{reflectedpath (##1)}}% + \newdef\transformpath##1{\@closmac{transformedpath (##1)}}% +% \end{macrocode} +% +% \subsubsection{Appending an arrowhead}\label{arrowhead} +% +% \DescribeMacro{\arrow} +% The four macros beginning \cs{@h} are assigned default values at the +% start and changed only if an option calls for it. +% Each option starts with a letter (The initial letters of +% `backset', `color', `length', or `rotate'), followed by a value +% to assign to the corresponding variable (defaulting to \mfc{0pt}, +% \meta{empty}, \cs{the}\cs{headlen} and \gbc{0 deg}). Then \cs{arrow} +% finishes with the invokation of \cs{@arrow}. +% \begin{macrocode} + \def\arrow{\def\@hbackset{0}\def\@hcolour{}% + \edef\@hlength{\the\headlen}\def\@hrotate{0}% + \@arrow}% +% \end{macrocode} +% +% \cs{@arrow} calls \cs{@arrowoption} if it finds an optional parameter. +% After processing the parameter, \cs{@arrowoption} calls \cs{@arrow} +% again. This loop will end when optional arguments run out. Then +% \cs{@@arrow} finishes with the actual \MF{} code. +% \begin{macrocode} + \newdef\@arrow{\mfp@ifnextchar[{\@arrowoption}{\@@arrow}}% + \newdef\@@arrow{% + \@modmac{% + \mfp@ifempty{\@hcolour}{headpath}{colorheadpath (\@hcolour)}% + \space(\@hlength, \@hrotate, \@hbackset)}}% +% \end{macrocode} +% +% Since the \cs{arrow} command takes up to 4 optional arguments in any +% order, we have this utility \cs{@arrowoption} which examines an option's +% contents and assigns a value to an appropriate macro. Since rather nasty +% error messages will result if the contents are empty, we test for this +% and do nothing when there is nothing to process. \cs{@@arrowoption} +% makes the appropriated definitions, then \cs{@arrow} is iterated to +% catch another optional parameter. +% \begin{macrocode} + \newdef\@arrowoption[##1]{% + \mfp@ifempty{##1}{}{\@@arrowoption##1\mfp@delim}\@arrow}% + \newdef\@@arrowoption##1##2\mfp@delim{% + \if l##1\relax \mfp@ifempty{##2}{}{\def\@hlength{##2}}% + \else\if r##1\relax \mfp@ifempty{##2}{}{\def\@hrotate{##2}}% + \else\if b##1\relax \mfp@ifempty{##2}{}{\def\@hbackset{##2}}% + \else\if c##1\relax \mfp@ifempty{##2}{}{\def\@hcolour{##2}}% + \else + \Mfpic@warn{Improper option to \string\arrow\@online .}% + \fi\fi\fi\fi}% +% \end{macrocode} +% +% This ends the prefix macros. +% +% \subsection{Transforming the coordinate system}\label{coordinate} +% +% \DescribeMacro{\coords} +% \DescribeMacro{\endcoords} +% The following apply transforms to the \MF{} coordinate system, and +% these can be localized with \cs{coords} $\ldots$ \cs{endcoords}. The +% transforms apply when the curve is \emph{rendered} and have no effect +% on paths merely stored with \cs{store} and \cs{patharr}. Moreover, if a +% path is created with \cs{connect}, it is transformed as a whole. +% +% \DescribeMacro{\applyT} +% These are implemented by \cs{applyT} which takes as its argument a \MF{} +% `transformer'. +% +% These commands (except \cs{turn}, kept for backward compatibility) have +% at most one argument, the parameters of the transformation. \cs{rotate} +% rotates around the origin, \cs{rotatearound} rotates around a given +% point, \cs{turn} takes the point as an optional argument. +% +% Transformations are applied in reverse of the order they appear in the +% file (i.e., the most recent first). +% \begin{macrocode} + \newdef\coords{\mfsrc{\@nl bcoords\@nl}}% + \newdef\endcoords{\mfsrc{\@nl ecoords\@nl}}% + \newdef\applyT##1{\mfsrc{\@nl hide(apply_t (##1))}}% + \def\rotate##1{\applyT{rotated ##1}}% + \newdef\rotatearound##1##2{% + \applyT{rotatedaround (##1, ##2)}}% + \newdef\turn{\simple@opt\@turn{(0,0)}}% + \newdef\@turn##1##2{\rotatearound{##1}{##2}}% + \newdef\reflectabout##1##2{% + \applyT{reflectedabout (##1, ##2)}}% line ##1--##2. + \let\mirror=\reflectabout + \newdef\shift##1{\applyT{shifted ##1}}% pair. + \def\scale##1{\applyT{scaled ##1}}% same scaling + \newdef\xscale##1{\applyT{xscaled ##1}}% + \newdef\yscale##1{\applyT{yscaled ##1}}% + \newdef\zscale##1{\applyT{zscaled ##1}}% + \newdef\xslant##1{\applyT{xslant ##1}}% + \newdef\yslant##1{\applyT{yslant ##1}}% + \newdef\zslant##1{\applyT{zslant ##1}}% + \newdef\boost##1{\applyT{boost ##1}}% + \newdef\xyswap{\applyT{xyswap}}% +% \end{macrocode} +% +% \subsection{Axes and grids}\label{axes} +% +% \DescribeMacro{\axes} +% \DescribeMacro{\xaxis} +% \DescribeMacro{\yaxis} +% An axis would normally not be thought of as a figure macro, because one +% would not want to position them arbitrarily nor transform them. One +% would also not want the hassle of having always to specify the origin, +% etc. However, one would want to occasionally make them dotted or dashed +% or colored. +% +% The original \cs{axes} was therefore not a figure macro. It always drew +% both axes with solid lines. Later \cs{xaxis} and \cs{yaxis} were +% introduced, which mimicked the behavior of \cs{axes}. For backward +% compatibility, the old behavior is supported with the old commands. The +% optional argument to \cs{axes}, \cs{xaxis} and \cs{yaxis} is the length +% of the arrowhead, defaulting to \cs{the}\cs{axisheadlength}. +% \begin{macrocode} + \newdef\xaxis{\simple@opt\@xaxis{\the\axisheadlen}}% + \newdef\yaxis{\simple@opt\@yaxis{\the\axisheadlen}}% + \newdef\axes{\simple@opt\@axes{\the\axisheadlen}}% + \newdef\@axes##1{\mfcmd{\@nl axes (##1)}}% + \newdef\@xaxis##1{\mfcmd{\@nl xaxis (##1)}}% + \newdef\@yaxis##1{\mfcmd{\@nl yaxis (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\axis} +% When border axes were added, all the code was revamped, and now we +% create axes as figure macros. It also became clear there was so +% much common code that it would be better to implement the syntax +% \cs{axis}\marg{l}, etc., rather than have separate commands \cs{laxis}, +% etc. for all six possible axes. Therefore, only the x- and y-axes have +% their own commands. The \cs{axis} command has one optional argument +% (the arrowhead length) and one mandatory argument, a single letter +% designating the axis to draw. +% +% The only complication is that the x- and y-axis have one default head +% length, \cs{axisheadlength} (initially \texttt{5pt}), while the side +% axes have a different default, \cs{sideheadlength} (initially \texttt{0pt}). +% Therefore we don't know which default to use until the mandatory argument +% is read. In \cs{@@axis}, we use \cs{get@axisnum} to check this +% mandatory argument and convert it to a number \cs{mfp@axisnum}, which is +% used to select the head length. +% \begin{macrocode} + \newdef\axis{\null@opt\@axis}% + \newdef\@axis[##1]##2{\get@axisnum{##2}\axis + \mfp@ifempty{##1}% + {\edef\mfp@param{% + \ifnum\mfp@axisnum<2 \the\axisheadlen + \else \the\sideheadlen + \fi}\@@axis{\mfp@param}}{\@@axis{##1}}{##2}}% + \newdef\@@axis##1##2{\arrow[l##1]\@figmac{axisline.##2}}% +% \end{macrocode} +% +% \DescribeMacro{\doaxes} +% \cs{doaxes} takes one optional argument, the arrowhead length, and one +% mandatory argument, all the axes to draw. These should be just letters +% with nothing separating them except optional spaces. \cs{doaxes} is +% implemented via the self-looping macro \cs{do@axis}, which applies +% one of two commands to the letter, depending on whether the optional +% parameter was present (\cs{@axis}) or not (\cs{@@axis}). +% \begin{macrocode} + \newdef\doaxes{\null@opt\@doaxes}% + \newdef\@doaxes[##1]##2{\def\mfp@axis{\@axis[##1]}% + \do@axis##2\mfp@delim}% + \newdef\do@axis##1{% + \ifx\mfp@delim##1\relax\else\mfp@axis{##1}\@xp\do@axis\fi}% +% \end{macrocode} +% +% \DescribeMacro{\axismarks} +% \DescribeMacro{\xmarks} +% \DescribeMacro{\ymarks} +% \DescribeMacro{\lmarks} +% \DescribeMacro{\bmarks} +% \DescribeMacro{\rmarks} +% \DescribeMacro{\tmarks} +% Hash marks (or tick marks) on the axes are provided by the +% \cs{axismarks} command (\cs{marks} was the original choice, but that +% turned out to conflict with a primative of e\TeX). For brevity, therefore, +% we also have separate commands \cs{xmarks}, etc. \cs{axismarks} has two +% mandatory arguments: the letter for the axis, and a comma separated +% list of numbers giving the positions on the axis. It functions as a list +% macro (see previous discussion of types of macros) and so the list of +% numbers can be prescribed by an external file +% \cs{datafile}\marg{\meta{file}}. One must be sure to issue an +% appropriate \cs{using} command to produce a numeric list in the output. +% This is the main reason for the \cs{usingnumericdefault} command. +% +% I had a change of heart after the \cs{axis} command, and I made things +% simpler to code here by putting the optional argument of \cs{axismarks} +% after the first mandatory argument. I could justify this because I +% expect most users will use the shorter versions that don't require the +% first argument (that is, the expectation that optional arguments come +% first is still satisfied). The optional argument is the length of the +% marks. The position of the marks is controlled separately by the +% \cs{setaxismarks} command, described previously. +% \begin{macrocode} + \newdef\axismarks##1{\simple@opt{\@marks{##1}}{\the\hashlen}}% + \newdef\@marks##1##2{\mfsrc{\@nl ##1marks (##2)}\mfp@writedata}% + \newdef\xmarks{\axismarks x}% + \newdef\ymarks{\axismarks y}% + \newdef\lmarks{\axismarks l}% + \newdef\bmarks{\axismarks b}% + \newdef\rmarks{\axismarks r}% + \newdef\tmarks{\axismarks t}% +% \end{macrocode} +% +% \DescribeMacro{\grid} +% \DescribeMacro{\gridpoints} +% \DescribeMacro{\lattice} +% The first one is, I think, inaccurately named: the word `grid' calls +% to mind a set of lines. It functions in a similar way: allowing a +% visualization of the coordinates, but it actually produces dots. The +% dots are located at the points whose coordinates are integer multiples +% of two numbers, which are given in the single mandatory argument +% separated by commas. The optional first argument is the diameter of the +% dots this defaults to \texttt{0.5bp} (hard coded in \file{grafbase}). +% Because of the name, I have provided two aliases: \cs{gridpoints} +% (for consistency with \cs{gridlines}, below) and \cs{lattice}. +% +% \DescribeMacro{\gridlines} +% Macro \cs{gridlines} takes the same mandatory argument and draws +% horizontal and vertical lines intersecting at all the dots that +% \cs{grid} would draw. Some packages (and \ConTeXt) define a \cs{grid} +% command so we use \cs{def} here instead of \cs{newdef} or \cs{redef}. +% +% \DescribeMacro{\hgridlines} +% \DescribeMacro{\vgridlines} +% These two draw only the horizontal or vertical lines, and their +% argument is the separation (in graph units) between successive lines. +% \begin{macrocode} + \def\grid{\null@opt\@grid}% + \newdef\@grid[##1]##2{% + \mfcmd{\mfp@ifempty{##1}{grid}{vgrid (##1)} (##2)}}% + \newlet\gridpoints=\grid \newlet\lattice=\grid + \newdef\gridlines##1{\mfcmd{\@nl gridlines (##1)}}% + \newdef\vgridlines##1{\mfcmd{\@nl vgridlines (##1)}}% + \newdef\hgridlines##1{\mfcmd{\@nl hgridlines (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\plrgrid} +% \DescribeMacro{\plrgridpoints} +% \DescribeMacro{\gridarcs} +% \DescribeMacro{\gridrays} +% \DescribeMacro{\plrpatch} +% The command \cs{plrgrid} takes one mandatory argument which contains two +% numbers separated by a comma. The first is a radius and the second an +% angle. It draws circular arcs at integer multiples of the radius, and +% radial lines at integer multiples of the angle. It fills the +% picture rectangle and is clipped to that rectangle. \cs{plrgridpoints} +% is similar but places only dots at the intersections of these arcs and +% rays. It takes an optional argument for the size of the dots, normally +% \cs{dotsize}. \cs{gridarcs} draws only the arcs, \cs{gridrays} only the +% rays. These last two take only one parameter each: the radius separating +% the arcs, and the angle separating the rays. +% +% \cs{plrpatch} draws: a circular arc at a starting +% radius, then increments that radius by a step size and draws another +% arc, etc., and finally draws an arc at the ending radius. It does a similar +% thing for radial lines and angles. It takes one mandatory argument, +% which contains 6 numbers separated by commas: starting radius, ending +% radius, step size, starting angle, ending angle, step size. +% \begin{macrocode} + \newdef\plrgrid##1{\mfcmd{\@nl polargrid (##1)}}% + \newdef\plrgridpoints{\simple@opt\@plrgp{\the\dotsize}}% + \newdef\@plrgp##1##2{\mfcmd{\@nl polargridpoints (##1, ##2)}}% + \newdef\gridarcs##1{\mfcmd{\@nl gridarcs (##1)}}% + \newdef\gridrays##1{\mfcmd{\@nl gridrays (##1)}}% + \newdef\plrpatch##1{\mfcmd{\@nl polarpatch (##1)}}% +% \end{macrocode} +% +% \subsection{Visualizing points}\label{points} +% +% \DescribeMacro{\point} +% \DescribeMacro{\plotsymbol} +% \cs{point} draws a dot or a small circle. It takes one optional +% argument, the diameter of the dot, and one mandatory argument, the ordered +% pair (or comma separated list of them) at which to draw a dot. After +% \cs{pointfillfalse}, the dots will be unfilled (i.e., small circles), +% after \cs{pointfilltrue} (the default), they will be solid. Like the +% grid macros, it is not a figure macro, but merely does its drawing and +% is not subject to any prefix macros. +% +% In order to mark points with other than circles, we have the +% \cs{plotsymbol} command, so-called because it uses the same symbols as +% the \cs{plot} command (previously discussed). There is an optional +% argument that gives the size of the symbol, a mandatory argument with +% the name of the symbol, and a second mandatory argument which +% is a comma separated list of ordered pairs for the locations. +% +% For both these commands, the default optional argument is +% \cs{the}\cs{pointsize}. +% \begin{macrocode} + \newdef\point{\simple@opt\@point{\the\pointsize}}% + \newdef\@point##1{% + \mfsrc{\@nl pointd (##1, \ifpointfill\mf@T\else\mf@F\fi)}% + \mfp@writedata}% + \newdef\plotsymbol{\simple@opt\@plotsymbol{\the\pointsize}}% + \newdef\@plotsymbol##1##2{% + \mfsrc{\@nl plotsymbol (##2, ##1)}\mfp@writedata}% +% \end{macrocode} +% +% \DescribeMacro{\plottext} +% In \MP{}, \TeX{} labels can be used in place of the symbols in +% \cs{plotsymbol}. Moreover, multiple copies of text can be placed with +% the \cs{tlabel} command (under \opt{mplabels}), as it supports a list of +% points for the location parameter. For \MF{} we supply an alternative, +% \cs{plottext}, which loops through the list of coordinates and issues +% \cs{tlabel} commands. The text can be anything that works in \cs{tlabel}. +% +% It takes one optional argument, the justification of the text (as in the +% \cs{tlabel command}, below---see also \cs{tlabeljustify}, above), +% defaulting to \oarg{cc}. There are two mandatory arguments: the text, +% and a comma separated list of ordered pairs. For consistency with +% \cs{plotsymbol} (and because it works better), we now require the same +% syntax for the points (i.e., no braces around individual points in the +% list as are allowed in \cs{tlabel} commands). +% +% We start by handling the justification, resetting whitespace, +% and loading the text into a token register. Then we read the list of +% points with \cs{@@plottext}. Under \opt{mplabels} we process the whole +% list with a single \cs{tlabel} command. Otherwise we prepare to loop +% through the list of points. The \cs{begingroup} in \cs{@plottext} is +% ended by the command called in \cs{@@plottext}. +% \begin{macrocode} + \newdef\plottext{\simple@opt\@plottext{cc}}% + \newdef\@plottext##1{% + \begingroup + \mfp@resetwhitespace \tlabeljustify{##1}% + \@ifmplabels{\@makeother\#}{}% + \mfp@gettoks\@@plottext}% + \newdef\@@plottext##1{% + \@ifmplabels + {\mfp@setMPpos \def\mfp@points{##1}\@@@tlabel}% + {\@@@plottext##1,\mfp@delim}}% +% \end{macrocode} +% After reading the list of points and appending ending tokens, we +% loop through them. The ending condition is that the next token is +% \cs{mfp@delim}. Otherwise we read the coordinates as delimited macros, +% and call \cs{@tlabel}, feeding it the coordinates and the text to +% plot there (the \cs{begingroup} in \cs{x@plottext} matches the +% \cs{endgroup} in \cs{@tlabel}). Then we recall \cs{@@@plottext} for +% another loop. Since we have used two internal commands of \cs{tlabel} +% code, we have to remember to check this if ever we rewrite \cs{tlabel}. +% \begin{macrocode} + \newdef\@@@plottext{% + \mfp@ifnextchar\mfp@delim{\@firstoftwo\endgroup}{\x@plottext}}% + \newdef\x@plottext(##1,##2),{\begingroup + \@tlabel{##1}{##2}{\the\mfp@toks}\@@@plottext}% +% \end{macrocode} +% +% \subsection{Figure macros}\label{figure} +% +% \subsubsection{Common geometric objects}\label{geometric} +% +% Finally we get to the real figure macros. These are implemented as +% \MF{} paths that can be variously rendered, transformed, etc., with the +% prefix macros. +% +% The first few (\cs{rect} through \cs{makesector}) are closed paths and +% need not be prefixed with a closing macro before filling, etc. +% +% \DescribeMacro{\rect} +% This takes one mandatory argument, the two diagonally opposite +% corners of the rectangle separated by a comma, and draws the rectangle +% with horizontal and vertical sides having these as two corners. The +% direction of the path (which seldom makes a difference) is such that it +% starts at the first specified point and moves horizontally first. +% \begin{macrocode} + \newdef\rect##1{\@figmac{rect (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\regpolygon} +% There are four arguments. The first is the number of sides. The second +% is the name of a variable to represent the vertices. The other +% two should be equations locating two vertices or the center and one +% vertex. If the name used is \gbc{Ver}, then the vertices will be +% \gbc{Ver1}, \gbc{Ver2}, etc., numbering anticlockwise. The center is +% \gbc{Ver0}. Case is significant. After the command, the points can be +% referred to in other \mfpic{} commands (except text label commands +% when \opt{mplabels} is not in effect). +% \begin{macrocode} +\newdef\regpolygon##1##2##3##4{% + \@figmac{regularpolygon(##1)(##2)(##3;##4;)}}% +% \end{macrocode} +% +% \DescribeMacro{\circle} +% This has one optional argument containing one of the letters +% \texttt{t}, \texttt{p} (the default), \texttt{c}, or \texttt{s}. Its +% purpose is to specify what kind of data is in the single mandatory +% argument. These are a subset of the optional arguments that the \cs{arc} +% commad (below) takes, and have almost the same meaning: +% \begin{itemize} +% \item \oarg{t}, the three point form needs three points (of course). +% \item \oarg{p}, the polar form needs the center point and the radius. +% This is the default when the optional argument is absent. +% \item \oarg{c}, the center/point form needs the center and one point on +% the circle. +% \item \oarg{s}, the point-sweep form requires two points and the angle of +% arc between them. The angle may be positive or negative. A +% positive angle indicates the number of degrees anticlockwise from +% the first point to the second. Negative means clockwise. +% \end{itemize} +% +% Supplying \cs{arc} with the same parameters, or the appropriate superset +% in the case of \oarg{p} and \oarg{c}, would produce a sub-arc of the +% circle that \cs{circle} produces. This is the reason for giving +% \cs{circle} these options: to make diagrams which show a circle and an +% arc on it. (This can also be done with an ellipse by using a +% transform on a circle and its arc. +% +% We use \cs{def} instead of \cs{newdef} or \cs{redef} because we know +% \LaTeX{} has already defined a \cs{circle} command, but plain \TeX{} has +% not. Instead of passing the default \texttt{p}, we pass a null +% argument, causing the code to compare various letters to \cs{relax} +% (always false) and then execute the default code. +% \begin{macrocode} + \def\circle{\null@opt\circl@}% + \newdef\circl@[##1]##2{% + \if t##1\relax \@figmac{circleppp (##2)}% + \else\if c##1\relax \@figmac{circlecp (##2)}% + \else\if s##1\relax \@figmac{circlepps (##2)}% + \else \@figmac{circle (##2)}% + \fi\fi\fi}% +% \end{macrocode} +% +% \DescribeMacro{\ellipse} +% \cs{ellipse} has one optional argument, an angle of rotation and one +% mandatory argument, containing the center, the horizontal radius (before +% rotation) and the vertical radius, separated by commas. +% \begin{macrocode} + \newdef\ellipse{\simple@opt\@ellipse{0}}% + \newdef\@ellipse##1##2{\@figmac{ellipse (##2, ##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\sector} +% This is the closed curve starting at the center of a circle, out +% along a radius to the circumference of the circle, along an arc of the +% circle, then back to the center. It has one mandatory argument +% containing the center, the radius, and the two angles, separated by +% commas. +% +% \DescribeMacro{\makesector} +% Takes a following arc and draws the sector (even if the center point +% is not known). It is really a prefix macro (closing an arc with two +% straight lines), but the combination \cs{makesector}\cs{arc} acts like a +% figure. +% \begin{macrocode} + \newdef\sector##1{\@figmac{sector (##1)}}% + \newdef\makesector{\@closmac{makesector}}% +% \end{macrocode} +% +% \DescribeMacro{\arc} +% A circular arc can be specified in several ways and we support most of +% them. \cs{arc} takes an optional argument: a letter to indicate which +% specification. It has one mandatory argument containing the data for +% that specification, separated by commas. +% +% The available letters and the corresponding required data are: +% \begin{itemize} +% \item \oarg{t}, the three point form needs three ordered pairs. +% \item \oarg{p}, the polar form needs the center point, two angles and +% the radius. +% \item \oarg{a}, the alternative polar form needs the center, the radius +% and two angles. +% \item \oarg{c}, the center-point-sweep form needs the center, the +% starting point, and the angle. +% \item \oarg{s}, the point-sweep form requires the starting point, the +% ending point and the angle. +% \end{itemize} +% +% The default optional argument is \oarg{s}. (I don't know why. It +% certainly doesn't seem the most natural. I would have picked \oarg{a}.) +% Like \cs{circle}, an empty argument is passed by default. +% \begin{macrocode} + \newdef\arc{\null@opt\@arc}% + \newdef\@arc[##1]##2{% + \if t##1\relax \@figmac{arcppp (##2)}% + \else\if p##1\relax \@figmac{arcplr (##2)}% + \else\if a##1\relax \@figmac{arcalt (##2)}% + \else\if c##1\relax \@figmac{arccps (##2)}% + \else \@figmac{arcpps (##2)}% + \fi\fi\fi\fi}% +% \end{macrocode} +% +% \DescribeMacro{\plr} +% \DescribeMacro{\midpoint} +% A little utility to convert a list of pairs into another list of +% pairs, where the given list are assumed to be polar coordinates and the +% results are their Cartesian counterparts. And one to calculate the +% midpoint, given two points separated by a comma. +% \begin{macrocode} + \newdef\plr##1{map (polar) (##1)}% + \newdef\midpoint##1{(0.5[##1])}% +% \end{macrocode} +% +% \subsubsection{List macros}\label{list} +% +% The next several figure macros are all list macros. They draw a path +% determined by a list of points. The list can be explicitly given as a +% mandatory argument containing a comma-separated list of ordered pairs, +% or it can be taken from an external datafile. This is true for +% \cs{polyline} through \cs{turtle}. These macros differ only in +% how the points determine the path. (The splines don't actually connect +% the points given, but rather use the points in a different way to +% determine a curve.) The list of points is not an argument of any of +% these. It should follow, and is picked up and written to output by the +% ending code of \cs{@listmac}. This is basic to list macros, and will not +% be repeated for each one. +% +% \DescribeMacro{\polyline} +% \DescribeMacro{\polygon} +% The most basic, a polyline or polygonal path, \cs{polyline} +% draws line segments from each point to the next. \cs{lines} is an +% alias. \cs{polygon} does the same, except it closes the path by +% connecting the last point to the first. +% +% In \cs{@polyline}, the argument is \mfc{true} or \mfc{false}, +% indicating whether the path is to be closed. +% \begin{macrocode} + \newdef\polyline{\@polyline\mf@F}% + \newlet\lines=\polyline + \newdef\polygon{\@polyline\mf@T}% + \newdef\@polyline##1{\@listmac{polyline (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\curve} +% \DescribeMacro{\cyclic} +% \cs{curve} draws a smooth curve connecting a list of points. it arranges +% for the curve, at point $p\sb n$ to be traveling parallel to the direction +% from $p\sb {n-1}$ to $p\sb {n+1}$ (except at the first and last point). +% +% \cs{cyclic} is similar, except the curve is closed, and at the first +% point it also travels parallel to the direction from the previous point +% (the last one listed) to the next. +% +% There is an optional argument, which is the tension. This is a number +% greater than .75. The larger it is, the closer to a polyline one gets. +% The default is 1 (set in \file{grafbase}) or more generally, the value +% set by \cs{settension}. +% \begin{macrocode} + \newdef\curve {\null@opt{\@curve\mf@F}}% + \newdef\cyclic{\null@opt{\@curve\mf@T}}% + \newdef\@curve##1[##2]{% + \@listmac{\mfp@ifempty{##2}{curve}{tcurve (##2)} (##1)}}% +% \end{macrocode} +% +% \DescribeMacro{\fcncurve} +% A `function curve' is the graph of a function of $x$. It should always +% travel left to right. This is not guaranteed by the \cs{curve} macro, +% above, even if the x-coordinates are listed in order. \cs{fcncurve} is +% guaranteed to do this if the list of points has the x-coordinates so +% ordered. +% +% The optional argument is called tension. Internally, it is not quite the +% same as the tension argument to \cs{curve}, but it also governs how +% closely the curve stays to the corresponding polyline. If the optional +% argument is missing, this command uses $1.2$ (more precisely, it uses +% $1.2$ times the value set with \cs{settension}). The above guarantee is +% voided if the value used is less than $1$. However, most curves will +% satisfy the guarantee with some lower values. +% \begin{macrocode} + \newdef\fcncurve{\null@opt\@fcncurve}% + \newdef\@fcncurve[##1]{% + \@listmac{\mfp@ifempty{##1}{fcncurve}{functioncurve (##1)}}}% +% \end{macrocode} +% +% \DescribeMacro{\qspline} +% \DescribeMacro{\closedqspline} +% \DescribeMacro{\cspline} +% \DescribeMacro{\closedcspline} +% These are supposed to be types of splines, about which I know only a +% little. The list or datafile that should follow each command should +% contain not the points passed through, but instead the control data. +% For quadratic B-splines the points create the path as follows: for +% successive points $p\sb i, p\sb {i+1}$ in the list, the path passes through +% the midpoint of the line segment connecting $p\sb i$ and $p\sb {i+1}$, tangent +% to that line segment. +% +% Cubic splines determine the curve as follows: for successive points +% $p\sb i, p\sb {i+1}$ in the list, the line segment connecting them is divided +% into thirds with two points $q\sb i$ and $q\sb i'$. The curve then passes +% through the midpoint of the segment from $q\sb {i-1}'$ to $q\sb i$ and tangent +% to that segment. +% +% `Control' is obtained as follows: the farther apart the points $p\sb i$ +% and $p\sb {i+1}$ (quadratic) or $q\sb {i-1}'$ and $q\sb i$ (cubic) the +% less the curvature of the curve at the midpoint. +% +% The `\texttt{q}' versions produce quadratic splines, the `\texttt{c}' +% versions produce cubic splines. +% \begin{macrocode} + \newdef\qspline{\@listmac{openqbs}}% + \newdef\closedqspline{\@listmac{closedqbs}}% + \newdef\cspline{\@listmac{opencbs}}% + \newdef\closedcspline{\@listmac{closedcbs}}% +% \end{macrocode} +% +% \DescribeMacro{\mfbezier} +% \DescribeMacro{\closedmfbezier} +% These produce the standard \MF{} cubic B\'ezier (the connection is +% \mfc{..} unless the optional argument is used) with tension given by +% an optional argument. A mandatory argument (not shown) contains the +% list of points. +% +% \DescribeMacro{qbeziers} +% \DescribeMacro{closedqbeziers} +% These produce the equivalent of a sequence of \LaTeX{} \cs{qbezier} +% commands. The mandatory argument will be a list of points alternating +% between nodes and control points. Note that quadratic B\'eziers need +% not be smooth at the nodes unless the control points line up. Our +% plural name distinguishes it from the \LaTeX{} command. +% \begin{macrocode} + \newdef\mfbezier{\null@opt{\@mfbezier\mf@F}}% + \newdef\closedmfbezier{\null@opt{\@mfbezier\mf@T}}% + \newdef\@mfbezier##1[##2]{% + \@listmac{\mfp@ifempty{##2}{bezier}{tbezier (##2)} (##1)}}% + \newdef\qbeziers{\@listmac{qbezier (\mf@F)}}% + \newdef\closedqbeziers{\@listmac{qbezier (\mf@T)}}% +% \end{macrocode} +% +% \DescribeMacro{\turtle} +% Many years ago there was a tool for teaching programming concepts to +% young children. They could draw a figure on a screen by programming a +% `turtle' with a sequence of turns and distances. The following is +% similar. It has a mandatory argument containing a list of ordered pairs. +% The first is the coordinates of the starting point, and each of the rest +% is interpreted as a displacement from the current position, along which +% a line segment is to be drawn. The terminal point of that segment is the +% new current position +% \begin{macrocode} + \newdef\turtle{\@listmac{turtle}}% +% \end{macrocode} +% +% \subsubsection{Graphing functions}\label{functions} +% +% \DescribeMacro{\function} +% \prog{Mfpic} provides the ability to plot the graph of any function that +% can be defined in \MF. This is done with the \cs{function} command, a +% figure macro which takes one optional parameter that selects +% the smoothness of the \MF{} path produced. It can be \oarg{p}, which +% draws a polyline path through selected points (much like \cs{polyline}), +% or \oarg{s\meta{tension}} which selects a smooth path (much like +% \cs{curve}\oarg{\meta{tension}}). The tension may be omitted and then +% defaults to 1 (set in \file{grafbase}). The default is \oarg{s}. +% +% There are two mandatory arguments. The second is the function, which +% must be written as a formula (strictly speaking, a \MF{} numerical +% expression) containing only one variable, \texttt{x}. The first +% mandatory argument contains three numbers separated by commas. They are, +% in order, the starting value of \texttt{x}, the ending value, and the +% step size. +% +% \DescribeMacro{\parafcn} +% \cs{parafcn} is similar, except its formula must be an ordered pair of +% formulas (strictly speaking, a \MF{} pair expression) in which +% \texttt{t} is the only variable. +% +% \DescribeMacro{\plrfcn} +% \cs{plrfcn} is similar, except its argument is a formula (a \MF{} +% numeric expression) representing the radius, in which \texttt{t} is the +% only variable, interpreted as the angle coordinate, $\theta$, in degrees. +% +% These three commands are so alike that all they do is set the name to +% be written to the output and call the common code. +% \begin{macrocode} + \newdef\function{\def\mfp@name{function}\mfp@fcn}% + \newdef\parafcn{\def\mfp@name{parafcn}\mfp@fcn}% + \newdef\plrfcn{\def\mfp@name{plrfcn}\mfp@fcn}% + \newdef\mfp@fcn{\simple@opt\@mfp@fcn{s}}% + \newdef\@mfp@fcn##1{\@@mfp@fcn##1\mfp@delim}% + \newdef\@@mfp@fcn##1##2\mfp@delim##3##4{% + \@figmac{\mfp@ifempty{##2}{}{t}\mfp@name\space + (\if p##1\mf@F\else\mf@T\fi \mfp@ifempty{##2}{}{, ##2}) + (##3) (##4)}}% +% \end{macrocode} +% +% \DescribeMacro{\btwnfcn} +% The region between two functions \cs{btwnfcn} is a figure macro. It is +% mostly intended for shading or other filling operations so it is already +% closed and, by default, it is not `smooth'. Its parameters are the +% same as those of \cs{function} (above), with two exceptions: the default +% optional argument is \oarg{p} and it has an additional mandatory +% argument, the other function. The resulting \MF{} path travels along one +% the graph of the first function from the starting $x$ to the ending $x$, +% thence vertically to the graph of the second function, along it (in +% reverse) to the starting $x$ and finally, vertically to the start of the +% first function's graph. +% +% \DescribeMacro{\plrregion} +% The figure macro \cs{plrregion} also produces a closed \MF{} path. It +% has the same parameters as \cs{plrfcn}, and the path produced begins at +% the origin, travels along a straight line in the direction of the +% starting angle to the beginning of the graph of the expression, along +% that graph to the ending angle and then straight back to the origin. Its +% default option is also \oarg{p}. +% \begin{macrocode} + \newdef\btwnfcn{\simple@opt\@btwnfcn{p}}% + \newdef\@btwnfcn##1{\@@btwnfcn##1\mfp@delim}% + \newdef\@@btwnfcn##1##2\mfp@delim##3##4##5{\btwn@params{##1}{##2}% + \@figmac{\t@pref btwnfcn (\s@vals) (##3) (##4) (##5)}}% + \newdef\btwn@params##1##2{% + \edef\s@vals{\if s##1\mf@T\else\mf@F\fi}% + \mfp@ifempty{##2}{\def\t@pref{}}% + {\def\t@pref{t}\edef\s@vals{\s@vals, ##2}}}% + \newdef\plrregion{\simple@opt\@plrregion{p}}% + \newdef\@plrregion##1{\@@plrregion##1\mfp@delim}% + \newdef\@@plrregion##1##2\mfp@delim##3##4{\btwn@params{##1}{##2}% + \@figmac{((0,0)--(\t@pref plrfcn (\s@vals) (##3) (##4))% + --cycle)}}% +% \end{macrocode} +% +% \subsection{Some composite objects}\label{composite} +% +% \DescribeMacro{\tile} +% A tile is syntactically a \MF{} picture variable. The commands between +% \cs{tile} (or \cs{begin}\marg{tile}) and \cs{endtile} (or +% \cs{end}\marg{tile}) should be any sequence of \mfpic{} figure macros +% with possible prefix macros. They will be drawn not on the main picture +% (\gbc{currentpicture}), but on the picture given by the name in the +% \cs{tile} command's argument. +% +% The argument has five parts separated by commas, the first is the +% name, the second is the unit of length (some absolute dimension like +% \mfc{1pt}), the next two are the width and height (pure numbers, the +% actual dimensions being these numbers times the unit of length), the +% last is one of the words \mfc{true} or \mfc{false}, indicating whether +% tile should be clipped to these dimensions (true) or allowed to extend +% beyond them (false). +% \begin{macrocode} + \newdef\tile##1{\mfcmd{\@nl tile (##1)}}% + \newdef\endtile{\mfsrc{endtile;\@nl}}% +% \end{macrocode} +% +% \DescribeMacro{\patharr} +% A path array is a set of \MF{} path variables each having the same name +% followed by a different numeric suffix. This command turns off rendering +% and simply assigns these variables in order to the path expressions +% written by the figure macros between \cs{patharr} and \cs{endpatharr}. +% It works by redefining \cs{store@path}, issued by all the figure +% macros. These variables can be accessed in \mfpic{} by using the +% \cs{mfobj} command. +% +% \emph{Explicit} rendering commands will work in the sense that the +% affected path will be rendered in addition to being assigned to the +% variable. The only parameter is the common name of the variables. +% \begin{macrocode} + \newdef\patharr##1{\begingroup + \mfsrc{hide(numeric ##1; path ##1[]; ##1 = 0)}% + \def\store@path{\mfsrc{\@nl store (##1[incr ##1])}}% + \setrender{}}% + \newdef\endpatharr{\endgroup}% +% \end{macrocode} +% +% \DescribeMacro{\connect} +% \DescribeMacro{\endconnect} +% These define an environment that can contain any sequence of figure +% macros. It functions as a single large \cs{@figmac}, the figure being +% the path obtained by connecting all the paths within by straight lines +% from the end of one to the beginning of the next. It is implemented via +% a path array, so the individual figures within the environment have +% implicit rendering turned off. Explicit rendering commands within the +% environment will have the expected effect. +% +% The \cs{if@mfp@latex} stuff at the end allows \cs{connect} to be used as +% a \LaTeX{} environment. +% \begin{macrocode} + \newdef\connect{\@figmac{begingroup; save nexus}% + \patharr{nexus}}% + \newdef\endconnect{\endpatharr + \mfcmd{\@nl mkpoly (\mf@F, nexus)\@nl endgroup}% + \if@mfp@latex \def\mfptmp@a{connect}% + \ifx\mfptmp@a\@currenvir + \aftergroup\@startfigtrue %\aftergroup\@imrendtrue + \fi + \fi}% +% \end{macrocode} +% +% \subsection{Other graphical features}\label{otherfeatures} +% +% And now for something completely different: pie charts and bar charts +% (or bar graphs, or histograms). +% +% \DescribeMacro{\piechart} +% The \cs{piechart} command takes one optional argument containing a +% letter and an angle, and one mandatory argument containing the data. The +% letter can be `\texttt{c}' for clockwise or `\texttt{a}' for anticlockwise +% and determines the direction around the pie the different wedges will be +% drawn. The angle determines the angle of the first edge (in the given +% direction) of the first wedge. The default is \oarg{c90} which starts +% the first wedge at 12 o'clock and proceeds clockwise from there. The +% data in the mandatory argument are numbers separated by commas. The size +% of a wedge is proportional to the size of the corresponding number. +% \cs{piechart} is a list macro and can take the data from an external +% file. +% +% \DescribeMacro{\piewedge} +% Actually, nothing is drawn, it only defines a path array and a few +% other internal variables. Each individual wedge (elements of the just +% mentioned array) may be drawn using the \cs{piewedge} command, which is +% a figure macro. That command takes one optional argument that determines +% how the wedge is drawn, as described below, and one mandatory argument, +% the number of the wedge. Without the optional argument, +% \cs{piewedge}\marg{1} draws the first wedge in the position given by the +% arguments of the \cs{piechart} command. +% +% The optional arguments can be: +% \begin{itemize} +% \item \oarg{x\meta{distance}}, the wedge is exploded, drawn +% shifted outward from its position by \meta{distance} (in graph +% units). +% \item \oarg{s(\meta{dx},\meta{dy})}, the wedge is shifted from its +% position by \meta{dx} horizontally and \meta{dy} vertically (in +% graph units). +% \item \oarg{m(\meta{x},\meta{y})}, the wedge is moved so that its +% point is at coordinates \parg{\meta{x},\meta{y}}. +% \end{itemize} +% \begin{macrocode} + \newdef\piechart{\simple@opt\@piechart{c}}% + \newdef\@piechart##1{\@@piechart##1\mfp@delim}% + \newdef\@@piechart##1##2\mfp@delim##3{% + \mfsrc{\@nl piechart(\if a##1 \else-\fi1, % + \mfp@mtsub{##2}{90}, ##3)}\mfp@writedata}% + \newdef\piewedge{\simple@opt\@piewedge{d}}% + \newdef\@piewedge##1{\@@piewedge##1\mfp@delim}% + \newdef\@@piewedge##1##2\mfp@delim##3{% + \@figmac{(piewedge[##3]% + \if x##1 shifted (##2*piedirection[##3])% + \else\if s##1 shifted (##2)% + \else\if m##1 shifted (##2 - piecenter)% + \else + \fi\fi\fi)}}% +% \end{macrocode} +% +% \DescribeMacro{\barchart} +% \DescribeMacro{\bargraph} +% \DescribeMacro{\gantt} +% \DescribeMacro{\histogram} +% The \cs{barchart} command takes one optional and two mandatory +% arguments. The last mandatory argument contains the data, separated by +% commas and these determine the length of the bars in graph units. This +% is also a list macro and instead of the list, an external file can hold +% the data. +% +% The optional argument determines the position and width of the bars and +% the first mandatory argument determines the orientation. The mandatory +% argument can be \marg{v} for vertical bars with base on the x-axis, or +% \marg{h} for horizontal bars with base on the y-axis. +% The optional argument contains three numbers separated by commas. The +% first is the coordinate of the leading edge of the first bar, the second +% is the distance (in graph coordinates) between the leading edge of one +% bar and that of the next, and the third is the fraction of that distance +% that is occupied by the bar. The default is \oarg{0,1,1}. +% +% We provide the aliases \cs{bargraph} and \cs{histogram}. +% +% \DescribeMacro{\chartbar} +% \DescribeMacro{\ganttbar} +% \DescribeMacro{\graphbar} +% \DescribeMacro{\histobar} +% The \cs{barchart} command does not actually draw anything, but defines a +% path array. The \cs{chartbar} command can then be used to draw a bar +% (one of the members of the just mentioned array). It is a figure macro +% and take the number of the bar as its mandatory argument. Aliases +% \cs{graphbar} and \cs{histobar} are provided. We avoid \cs{bar} because +% it is a math accent command. +% \begin{macrocode} + \newdef\barchart{\simple@opt\@barchart{0,1,1}}% + \newdef\@barchart##1##2{% + \mfsrc{\@nl barchart (##1, \if h##2\mf@F\else\mf@T\fi)}% + \mfp@writedata}% + \newlet\bargraph=\barchart + \newlet\histogram=\barchart + \newlet\gantt\barchart + \newdef\chartbar##1{\@figmac{chartbar[##1]}}% + \newlet\graphbar=\chartbar + \newlet\histobar=\chartbar + \newlet\ganttbar=\chartbar +% \end{macrocode} +% +% One can add to \cs{mfp@additions} to extend \mfpic. Currently it +% is empty. This ends \cs{@mfpic@graf@macs}. +% \begin{macrocode} + \newdef\pinumber{3.14159}% + \mfp@additions +}% +% \end{macrocode} +% +% +% \section{The \env{mfpic} environment}\label{mfpicenv} +% +% \subsection{Initializations}\label{mfpicinitializations} +% +% \DescribeMacro{\mfpic} +% This command (or the \LaTeX{} environment \cs{begin}\marg{mfpic}) takes +% two optional arguments: the xscale and the yscale. When both are +% omitted, they are both set to 1, if the yscale is omitted, it is set +% equal to the xscale. +% +% There are also 4 mandatory arguments: the first two give the minimum and +% maximum extent of the x coordinates and the last two do the same for the +% y coordinates. The coordinates used in the figure commands within an +% mfpic environment are multiplied by the corresponding scales, and that +% is the multiple of \cs{mfpicunit} used in positioning, drawing, etc. +% +% The optional arguments are converted by the option handling code to +% mandatory arguments for \cs{@mfpic}, which contains the actual +% definition. +% \begin{macrocode} +\newdef\mfpic{\simple@opt\@mfpicA{1}}% +\newdef\@mfpicA#1{\simple@opt{\@mfpic{#1}}{#1}}% +\newdef\@mfpic#1#2#3#4#5#6{% +% \end{macrocode} +% +% We start by saving \mfpic{} extra fontdimen values. They will be +% restored by \cs{endmfpic}. This makes the values local (font dimensions +% are normally always global). Then we begin a group to localize ordinary +% \TeX{} definitions and assignments, disable writes to the output if +% \cs{opengraphsfile} hasn't occurred yet. save the current font in +% \cs{@tcurr} for restoration inside text labels and captions, set the +% switch that says we are in an \cs{mfpic} environment, disable \cs{par} +% so that blank lines have (little or) no effect, and switch to +% \cs{nullfont} so that stray characters (always an error) and spaces (not +% an error), have no effect. I wonder if \cs{@empty} is a better +% disabling definition for \cs{par} than \cs{relax}. +% \begin{macrocode} + \save@mfpicdimens + \begingroup % ended near end of \endmfpic + \@ifmfpfileisopen{}% + {\if@mfp@nowrite\else \nooutputfileerror{\mfpic}% + \def\@mfsrc##1##2{}% + \fi}% + \mfp@DBlog{Starting mfpic \number\mfp@count \@online.}% + \font\@tcurr=\fontname\font\relax + \let\ifin@mfpicenv\iftrue +% \let\par\relax + \let\par\@empty + \nullfont +% \end{macrocode} +% +% The graphics macros are undefined outside the \env{mfpic} environment. +% They are defined now by invoking \cs{@mfpic@graf@macs}. +% \begin{macrocode} + \@mfpic@graf@macs +% \end{macrocode} +% +% Then we define two utility macros used to convert graph coordinates into +% actual dimensions relative to the lower left corner of the picture. The +% first argument is a dimension, but it is normally obtained by first +% multiplying a coordinate value by \cs{mfpicunit}. Since font dimensions +% may be involved, we assign \texttt{\#\#1} to a scratch dimension +% register first, since \TeX{} won't \cs{advance} font dimensions. We make +% the final assignment global for consistency. +% \begin{macrocode} + \newdef\@xconv##1{% + {\mfp@scratch = ##1\relax + \advance\mfp@scratch by -#3\mfpicunit + \mfp@scratch = #1\mfp@scratch + \global ##1 = \mfp@scratch}}% + \newdef\@yconv##1{% + {\mfp@scratch=##1\relax + \advance\mfp@scratch by -#5\mfpicunit + \mfp@scratch = #2\mfp@scratch + \global ##1 = \mfp@scratch}}% +% \end{macrocode} +% +% 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}. +% We initialize the box here. The dimensions \cs{@tlabelsbot}, etc., +% are also initialized. Each will be changed as labels are added, so a +% `non-maxdimen' value at \cs{endmfpic} means there are labels to add. +% \begin{macrocode} +\setbox\@alltlabels\vbox{\hbox{}}% +\@tlabelsbot \maxdimen +\@tlabelstop -\maxdimen +\@tlabelsleft \maxdimen +\@tlabelsright-\maxdimen +% \end{macrocode} +% +% The graph is loaded into a box register at the end of the mfpic +% environment. The size of that box register may have to correspond to the +% arguments of the \cs{mfpic} command. Since \cs{endmfpic} doesn't receive +% these arguments we process them now. +% +% Dimensions \cs{@graphright}, etc., represent the extent of the graph +% box. We increase them when the text is added if it extends beyond the +% edges of the graph. These are all font dimensions, so they are global +% assignments. +% \begin{macrocode} + \@graphright=#4\mfpicunit \@xconv\@graphright + \@graphtop=#6\mfpicunit \@yconv\@graphtop + \@graphleft=0pt + \@graphbot=0pt + \@graphwd=\@graphright +% \end{macrocode} +% +% \subsection{Initialization code for the current +% picture}\label{current} +% +% Each \env{mfpic} environment produces a \gbc{beginmfpic...endmfpic} +% environment in the output file. Here we initialize the variables that +% correspond there to the 6 arguments and \cs{mfpicunit}, then begin the +% \MF{} environment. \gbc{beginmfpic} takes the number of the current +% figure as its only argument. For debugging purposes we write a \MF{} +% comment the contains the line number in the \TeX{} source file where the +% \cs{mfpic} command occurred. We also write a line of dashes +% (\cs{mf@d}) to make it easier to find the start of the environment. This +% will be removed in the public release. +% +% When \opt{mplabels} is in effect we need to set the font for the labels +% to the saved \cs{@tcurr} by writing some \mfc{verbatimtex} code. Since +% \opt{mplabels} can be turned on at any time, we write this whenever the +% \opt{metapost} option is in effect. It is a common misconception that +% \mfc{verbatimtex} can be used only once at the start of a \MP{} file. In +% fact it can be used any number of times. It's purpose is to be at an +% outer level, while \mfc{btex} is localized inside a box +% \begin{macrocode} + \mfsrc{\@nl \mf@p\mf@d\mf@d\mf@d\@nl + unitlen := \the\mfpicunit\mf@s;\@nl + xscale := #1; yscale := #2;\@nl + bounds (#3, #4, #5, #6);\@nl + \@nl + beginmfpic(\number\mfp@count); \mf@p\space\@mfplineno. + \mfp@ifmpost + {\@nl verbatimtex \@nl + \begingroup\space\font\noexpand\MFPcfont=\fontname\@tcurr\@nl + etex;}{}}% +% \end{macrocode} +% +% \subsection{Placing text labels}\label{textlabels} +% +% All the rest of \cs{@mfpic} defines commands that in some way or another +% produce labels. The easiest part is defining \cs{tlabel} under +% \opt{mplabels} where most of the work takes place in \file{grafbase.mp}. +% The most involved is the definition of \cs{tlabel} without +% \opt{mplabels}. All the rest (except \cs{tcaption}) add labels by +% calling \cs{tlabel}. Some of those could be simpler under \opt{mplabels} +% but then we'd need two versions of each. +% +% \DescribeMacro{\tlabel} +% This is the common code, processing optional arguments, etc. for +% \cs{tlabel}. It ultimately calls one of \cs{@tlabel} (no +% \opt{mplabels}) or \cs{@@tlabel} (\opt{mplabels}). It takes an optional +% argument describing the justification and rotation, followed by a +% location in one of two syntaxes (which adds to the complication, but we +% want to be backward compatible), followed by the text of the label +% (\TeX{} code). +% +% The location can be in the form \parg{\meta{x},\meta{y}}, but if \MP{} +% is processing labels we would like to be able to use \MP{} expressions, +% which can contain parentheses and commas. This would mess up \TeX's +% token matching for reading the two coordinates. Therefore we allow the +% whole point to be enclosed in braces. Under \opt{mplabels} the contents +% of the braces will be written to the output file without any further +% parsing. Without \opt{mplabels}, there should be either no braces, or +% inside the braces is the previously described syntax. +% +% We start with \cs{begingroup} to hide changes, then reset whitespace to +% its normal catcodes. Without \opt{mplabels} we reset \cs{tlabel@rot} to +% empty. Finally, we check for an optional parameter and run \cs{@tlabel@}, +% feeding it an empty optional argument if there is none. +% \begin{macrocode} + \newdef\tlabel{% + \begingroup % ended in \@(@@)tlabel + \mfp@resetwhitespace + \@ifmplabels{}{\def\tlabel@rot{}}% + \null@opt\@tlabel@}% +% \end{macrocode} +% +% We run \cs{tlabeljustify} on the optional parameter. This keeps the +% default values of \cs{tl@vpos}, \cs{tl@hpos} and \cs{tlabel@rot} if +% the parameter is empty, otherwise it modifies them inside the current +% group. +% +% We then check for a left parenthesis and assume the +% \parg{\meta{x},\meta{y}} syntax in that case, calling \cs{@@tlabel@} +% to process it. Under \opt{mplabels} it stuffs the whole point into +% braces and call the main code \cs{@@tlabel} with that argument, +% otherwise it pulls out the two coordinates and feeds them as the first +% two arguments of the main code \cs{@tlabel}. +% \begin{macrocode} + \newdef\@tlabel@[##1]{\tlabeljustify{##1}% + \mfp@ifnextchar({\@@tlabel@}{\@@tlabel@@}}% + \newdef\@@tlabel@(##1,##2){% + \@ifmplabels + {\@@tlabel{(##1,##2)}}{\@tlabel{##1}{##2}}}% +% \end{macrocode} +% +% If no parenthesis, we assume braces surround the point. Under +% \opt{mplabels} we call the main code (\cs{@@tlabel}) with that argument. +% Otherwise, we re-call the above \cs{@@tlabel@} on the contents of the +% braces, assuming (without checking) that the contents are coordinates in +% parentheses. +% \begin{macrocode} + \newdef\@@tlabel@@##1{% + \@ifmplabels {\@@tlabel{##1}}{\@@tlabel@##1}}% +% \end{macrocode} +% +% \DescribeMacro{\extraendtlabel} +% We now come to the main code under \opt{mplabels}, which should just +% arrange to write the correct commands to the output file. All labels are +% passed as \mfc{btex ... etex} structures. The definition of \cs{MFPtext} +% will have been written earlier by \cs{opengraphsfile}. +% \cs{extraendtlabel} is a hook currently only used by the \cs{tlabels} +% command to force a loop. +% \begin{macrocode} + \newdef\mfp@btex##1{btex \noexpand\MFPtext{##1} etex}% + \newdef\extraendtlabel{}% +% \end{macrocode} +% +% The command \gbc{newgblabel}, defined in \file{graphbase.mp} for placing +% labels, uses three parameters to justify the text. If we didn't have to +% support the \texttt{B} vertical placement option, there would be only +% two. All the other options involve placement \emph{relative} to the +% bounding box. But the baseline is absolute: \MP{} always puts it at +% y-coordinate 0 in the picture returned by \gbc{btex}. The first two +% parameters are numerical and the third is boolean. The +% first represents the fraction of the text that lies left of given +% point. The second is the fraction of the text below the point. If the +% third parameter is \mfc{true}, this fraction ignores the depth of the +% text (so $0$ indicates baseline placement); if it is false, the depth +% is accounted for (so $0$ indicates the very bottom of the text). +% +% By this point the letters of the optional parameter have been converted +% to integer values for \cs{tl@hpos} and \cs{tl@vpos} by +% \cs{tlabeljustify}. The following converts these integers to comma +% separated parameters as described above using \cs{ifcase}. +% +% The fourth parameter of \gbc{newgblabel} is the angle of rotation. Empty +% rotation is converted to the angle 0, otherwise it is written as is. +% All four parameters are stored in \cs{mfp@MPpos}. +% \begin{macrocode} + \newdef\mfp@setMPpos{% + \edef\mfp@MPpos{% + \ifcase\tl@hpos .5\or 1\else 0\fi, % horizontal + \ifcase\tl@vpos 0\or .5\or 1\else 0\fi, % vertical + \ifnum \tl@vpos < 0 \mf@T\else\mf@F\fi, % true=Baseline + \mfp@mtsub{\tlabel@rot}{0}}}% +% \end{macrocode} +% +% \cs{@@tlabel} is the code called by \cs{tlabel} when \opt{mplabels} is +% in effect. The argument is a \MP{} pair expression, or comma separated +% list of them. It should be followed by the \TeX{} code for the label. +% We will load the label into a token register afterwards. First +% we restore the meaning of blank lines and then make sure any +% \texttt{\#}'s in the \TeX{} code are not doubled by changing their +% category. +% +% We load the label in a token register because writing that is (almost) +% verbatim (blank lines become \cs{par}, \texttt{\#} symbols are +% doubled if we're not careful, and control names have a space appended). +% One day maybe we'll try to obtain a true verbatim writing mode. +% \begin{macrocode} + \newdef\@@tlabel##1{\def\mfp@points{##1}\mfp@restorepar + \mfp@setMPpos \@makeother\#\mfp@gettoks\@@@tlabel}% +% \end{macrocode} +% Then the \gbc{newgblabel} command is written with the justification +% parameters, and two more: the label tokens, and the point (or list of +% points). The group (begun by \cs{tlabel}) is ended, and the +% \cs{extraendtlabel} command invoked. +% \begin{macrocode} + \newdef\@@@tlabel{% + \mfcmd{\@nl + newgblabel(\mfp@MPpos)(\mfp@btex{\the\mfp@toks})(\mfp@points)}% + \endgroup \extraendtlabel}% +% \end{macrocode} +% +% When \opt{mplabels} is not in effect, we use \TeX{} to position the +% label. By this point, the optional justification parameter to +% \cs{tlabel} has been converted to integer values of \cs{tl@vpos} and +% \cs{tl@hpos}, and the coordinates of the location are passed as the +% first two arguments of \cs{@tlabel}. The third argument is the \TeX{} +% code for the label. +% +% We put the label in a box (\cs{@textbox}) so we can measure and position +% it. It is a \cs{vbox} so we can have multiline labels. This is effected +% by wrapping it in a simple, left-aligned, one column \cs{halign}, +% defining \cs{\bsl} to be \cs{cr}. We make this procedure a separate +% macro, since we need to do the identical thing in the \cs{tlabelpath} +% code. +% \begin{macrocode} + \newdef\set@textbox##1{% + \setbox\@textbox=\vbox{\def\\{\cr}\mfp@restorepar + \@tcurr\the\every@tlabel\halign{####\hfil\cr##1\crcr}}}% +% \end{macrocode} +% +% We then compute its total height to simplify later code. +% \begin{macrocode} + \newdef\@tlabel##1##2##3{% + \set@textbox{##3}% + \mfp@scratch\tb@ht \advance\mfp@scratch\tb@dp + \tb@totalht\mfp@scratch +% \end{macrocode} +% +% The following computes whether the rightmost extent of the picture will +% be increased by the addition of the label. We convert the x-coordinate +% of the label's location to a distance from the left edge of the picture. +% We then add to that the amount of the label extending to the right of +% this location. Then we add or subtract the separation of the label +% from its location. Finally, we simply add the horizontal adjustment +% defined by the user with \cs{tlabeloffset}. The value of +% \cs{@tlabelsright} is set equal to this if it was less. We could omit +% this group: we never use \cs{@tlabelsright} except in debugging. +% +% The macro \cs{tb@wd} expands to \cs{wd}\cs{@textbox}. +% \begin{macrocode} + \mfp@scratch=##1\mfpicunit + \@xconv\mfp@scratch + \begingroup + \ifcase\tl@hpos \advance\mfp@scratch 0.5\tb@wd % center + \or \advance\mfp@scratch -\tlabel@sep % right + \else \advance\mfp@scratch \tb@wd % left + \advance\mfp@scratch \tlabel@sep + \fi + \advance\mfp@scratch \tlabel@hadj + \ifdim \mfp@scratch>\@tlabelsright + \@tlabelsright=\mfp@scratch + \fi + \endgroup +% \end{macrocode} +% +% The following is the same as the previous calculations, but with respect +% to the leftmost extension of picture and label. Here, however, we save +% the calculated value in \cs{tb@moveright}, because it is exactly the +% amount we'll need to \cs{kern} later to position the label. +% \begin{macrocode} + \begingroup + \ifcase\tl@hpos \advance\mfp@scratch -0.5\tb@wd % center + \or \advance\mfp@scratch -\tb@wd % right + \advance\mfp@scratch -\tlabel@sep + \else \advance\mfp@scratch \tlabel@sep % left + \fi + \advance\mfp@scratch \tlabel@hadj + \tb@moveright=\mfp@scratch + \ifdim \mfp@scratch<\@tlabelsleft + \@tlabelsleft=\mfp@scratch + \fi + \endgroup +% \end{macrocode} +% +% Now we base the calculations on the vertical extent of picture and +% label. Otherwise the idea is the same, and we may increase +% \cs{@graphtop}. The macro \cs{tb@ht} means \cs{ht}\cs{@textbox} and +% \cs{tb@dp} means \cs{dp}\cs{@textbox}. Again we save the calculated +% result (in \cs{tb@raise}) for later positioning of the label. +% \begin{macrocode} + \mfp@scratch=##2\mfpicunit + \@yconv\mfp@scratch + \begingroup + \ifcase\tl@vpos \advance\mfp@scratch \tb@totalht % bottom + \advance\mfp@scratch \tlabel@sep + \or \advance\mfp@scratch 0.5\tb@totalht % center + \or \advance\mfp@scratch -\tlabel@sep % top + \else \advance\mfp@scratch \tb@ht % baseline + \fi + \advance\mfp@scratch \tlabel@vadj + \tb@raise=\mfp@scratch + \ifdim \mfp@scratch>\@tlabelstop + \@tlabelstop=\mfp@scratch + \fi + \endgroup +% \end{macrocode} +% +% Finally we compute the bottom-most extent. +% \begin{macrocode} + \begingroup + \ifcase\tl@vpos \advance\mfp@scratch \tlabel@sep % bottom + \or \advance\mfp@scratch -0.5\tb@totalht % center + \or \advance\mfp@scratch -\tb@totalht % top + \advance\mfp@scratch -\tlabel@sep + \else \advance\mfp@scratch -\tb@dp % baseline + \fi + \advance\mfp@scratch \tlabel@vadj + \ifdim \mfp@scratch<\@tlabelsbot + \@tlabelsbot=\mfp@scratch + \fi + \endgroup +% \end{macrocode} +% +% Now we've computed the new size of \cs{@alltlabels} and we put the +% new label on top of it with the above calculated kerns. +% \begin{macrocode} + \global \setbox\@alltlabels=% + \vtop{\unvbox\@alltlabels + \vbox to 0pt{\kern-\tb@raise + \hbox{\kern\tb@moveright\box\@textbox}\vss}}% + \endgroup % group begun in \tlabel + \extraendtlabel}% End \@tlabel +% \end{macrocode} +% +% \subsection{Surrounding the label with a path}\label{surrounding} +% +% These next macros place labels, but also define a path surrounding the +% label This allows one to clear a space for the label, create a +% background, draw a box around it, etc. They take two optional arguments. +% The first optional argument depends on the type of path being created. +% It is described below. The second one is the justification as in the +% \cs{tlabel} command. There are two mandatory arguments, the location +% (same syntax as for \cs{tlabel}) and the text. They also have +% star-forms, which create the path but doesn't place the label. +% +% All the curves are sized to just contain what I will call the +% \emph{label strip}. Imagine a rectangle that just fits around the text. +% Now extend it on all sides by the value defined with \cs{tlabelsep}. +% This rectangle is the label strip. +% +% \DescribeMacro{\tlabelrect} +% \cs{tlabelrect} creates the rectangular boundaries of the label strip by +% default. With the optional argument a rectangle with rounded corners is +% produced; the optional argument is the radius of the quarter circles used. +% These quarter circles pass through the corners of the label strip and are +% joined together with straight lines to create the rest of the rectangle. +% As a special case, the optional argument can contain the keyword +% `\texttt{roundends}' to produce a rectangle with the short sides +% replaced by a semicircle. +% +% \DescribeMacro{\tlabeloval} +% \cs{tlabeloval} produces an ellipse which, by default has the same +% aspect ratio as the label strip. It is sized to just include that label strip, +% passing through its four corners. The optional argument contains a +% numerical factor $m$ that, if greater than 1, increases the width and +% decreases the height to maintain this relationship with the label strip, +% while multiplying the width to height ratio by $m$. The default value of +% $m$ is 1. +% +% \DescribeMacro{\tlabelellipse} +% \cs{tlabelellipse} produces an ellipse, where the optional argument $a$ +% is the ratio of its width to its height. The default for $a$ is 1, which +% produces a circle. +% +% \DescribeMacro{\tlabelcircle} +% To get a circle the user can \cs{tlabelellipse} without the optional +% argument, or with argument \oarg{1}. However, it makes for a more +% readable source if the command reflects the shape. \cs{tlabelcircle} is +% defined to be essentially \cs{tlabelellipse}\oarg{1}, but it first +% checks for the \texttt{*} and passes it along in front of the \oarg{1}. +% +% We implement the other three by calling \cs{tlpath} with the name of the +% curve (\texttt{rect}, \texttt{oval}, or \texttt{ellipse}) and the +% default value of the optional argument (\texttt{0}, \texttt{1}, and +% \texttt{1}, respectively) as arguments. +% \begin{macrocode} + \newdef\tlabelrect{\tlpath{rect}{0}}% + \newdef\tlabeloval{\tlpath{oval}{1}}% + \newdef\tlabelellipse{\tlpath{ellipse}{1}}% + \newdef\tlabelcircle{% + \mfp@ifnextchar*{\@firstoftwo{\tlabelellipse*[1]}}% + {\tlabelellipse[1]}}% +% \end{macrocode} +% +% We store the name of the path in \cs{mfp@name} and the default argument +% in \cs{mfp@param}, then check for a \texttt{*} and set a switch based +% on it before calling \cs{@tlpath}. The \cs{@figmacstart} must be outside +% the group so the switches it sets will survive for later commands to +% detect. +% \begin{macrocode} + \newdef\tlpath##1##2{\@figmacstart + \begingroup % ended in \tlabelpath@ + \def\mfp@name{##1}\def\mfp@param{##2}% + \mfp@ifnextchar*% + {\@mfpswitchtrue\@firstoftwo{\@tlpath}}% gobbles the star + {\@mfpswitchfalse\@tlpath}}% +% \end{macrocode} +% Process first optional argument. First one has value of \cs{mfp@param} +% as default. The second one has a default justification set by the user +% with \cs{tlpathjustify} or the initial \texttt{[cc]} setting. Once these +% are processed, we check whether a parentheses follows, calling one of +% two different handlers for the location parameter(s). +% \begin{macrocode} + \newdef\@tlpath{\null@opt\@@tlpath}% + \newdef\@@tlpath[##1]{% + \edef\mfp@param{\mfp@mtsub{##1}{\mfp@param}}% + \mfp@resetwhitespace + \simple@opt\@@@tlpath{\tlpath@v\tlpath@h\tlpath@r}}% + \newdef\@@@tlpath##1{\tlabeljustify{##1}% + \mfp@setMPpos \mfp@ifnextchar({\@tlabelpath}{\@@tlabelpath}}% +% \end{macrocode} +% +% These handlers just stuff the point into a macro and call the command +% that reads the label code. The name \cs{mfp@points} is plural (even +% though only one point is supported) because the internal command that +% places the label expects this macro. We use \cs{@firstofone} so +% that the braces will not be written to the output, but they will +% function as braces for \TeX's parameter matching. +% \begin{macrocode} + \newdef\@tlabelpath (##1,##2){% + \def\mfp@points{(\@firstofone{##1},\@firstofone{##2})}% + \@@@tlabelpath}% + \newdef\@@tlabelpath##1{\def\mfp@points{##1}\@@@tlabelpath}% + \newdef\@@@tlabelpath{\mfp@restorepar + \@ifmplabels{\@makeother\#}{}\mfp@gettoks\tlabelpath@}% +% \end{macrocode} +% +% Under \opt{mplabels} we just call on \MP{} to do everything (including +% measuring the text). Otherwise we measure the text in \TeX{} and feed +% the bounding box corners to \MF{} for making the path. Then we optionally +% place the text based on the switch previously set. All the data needed +% have already been stored in macros by previous commands in the chain. +% \begin{macrocode} + \newdef\tlabelpath@{% + \@ifmplabels + {\mfcmd{text\mfp@name x (\mfp@MPpos)\@nl(origin, % dummy parameter + \mfp@btex{\the\mfp@toks}, \mfp@param, \mfp@points)}}% + {\measure@textbox{\the\mfp@toks}% + \mfcmd{text\mfp@name x (\mfp@MPpos)\@nl(\tb@ll, \tb@ur, % text bbox + \mfp@param, \mfp@points)}}% + \if@mfpswitch \endgroup % *-form, no label placed + \else % tlabel commands contain \endgroup + \@ifmplabels{\@@@tlabel}% + {\@xp\@@tlabel@\mfp@points{\the\mfp@toks}}% + \fi}% +% \end{macrocode} +% +% Here we define the command that measures the text. It is almost a clone +% of a similar code sequence in \cs{@tlabel}, but it produces the \gbc{ll} +% and \gbc{ur} (corners of the boundingbox) that the \grafbase{} code +% needs. +% \begin{macrocode} + \newdef\measure@textbox##1{% + \set@textbox{##1}% + \edef\tb@ll{(0, -(\the\tb@dp))}% + \edef\tb@ur{(\the\tb@wd, \the\tb@ht)}}% +% \end{macrocode} +% +% \subsection{Placing multiple text labels}\label{multiple} +% +% \DescribeMacro{\tlabels} +% One of the more onerous things about labels in \env{mfpic} environments +% was the shear number of them. The following was intended to reduce the +% amount of typing by having to repeat only the arguments. \cs{tlabels} +% takes only one argument: any sequence of valid arguments for a \cs{tlabel} +% command, optionally separated by whitespace (but not blank lines). +% +% We begin a group, reset whitespace to normal, and call the command that +% reads the argument. That command arranges to make the main code +% self-looping by defining \cs{extraendtlabel} to call the beginning of the +% loop, then it feeds its argument to \cs{do@tlabels} followed by a +% delimiter to signal the end of the loop. +% \begin{macrocode} + \newdef\tlabels{% + \begingroup % ended in \do@tlabels + \mfp@resetwhitespace \@tlabels}% + \newdef\@tlabels##1{\def\extraendtlabel{\do@tlabels}% + \do@tlabels##1\mfp@delim}% +% \end{macrocode} +% +% If \cs{do@tlabels} sees the end-of-loop delimiter it ends the group and +% gobbles the delimiter. Otherwise it calls \cs{tlabel}, which sees the +% next set of arguments, and repeats the loop. +% \begin{macrocode} + \newdef\do@tlabels{% + \mfp@ifnextchar\mfp@delim{\@firstoftwo\endgroup}{\tlabel}}% +% \end{macrocode} +% +% Labelling axes generates a lot of \cs{tlabel} commands or a single +% \cs{tlabels} command with a lot of arguments. Given that such labels +% have much in common (e.g., for the x-axis the y-coordinate and the +% justification are usually the same for all the labels) we can do still +% better at abbreviating this task. +% +% \DescribeMacro{\axislabels} +% The \cs{axislabels} command takes a mandatory argument (the axis) +% followed by an optional argument (the justification, as in the +% \cs{tlabel} command), followed by another mandatory argument, a comma +% separated list of items of the form +% \marg{\meta{label}}\meta{coordinate}. The label is placed at that +% coordinate on the given axis. This command is complicated by the fact +% that the default justification should be different for each axis (for +% example, for the y-axis it is \oarg{cr} but for the x-axis it is +% \oarg{tc}). For all of them, one of the parts is \texttt{c}, so after +% resetting whitespace we initialize them both to this and later change +% only the one that needs it. +% +% Also, one of the coordinates of a label will be given by the argument, +% while the other is the location of the axis. However, which coordinate +% is which is different for different axes. What we do is feed the +% argument to \cs{mfp@xcoord} and \cs{mfp@ycoord}. Both are initialized to +% the identity macro, but one is changed to expand to just the axis +% position. +% +% The axis position for x- and y-axis is 0. For border axes it is +% calculated by adding the border axis shift to the border coordinate. +% \begin{macrocode} + \newdef\axislabels##1{% + \begingroup % ended in \do@axislabel + \mfp@resetwhitespace \tlabeljustify{cc}% + \let\mfp@xcoord=\@firstofone \let\mfp@ycoord=\@firstofone + \get@axisnum{##1}\axislabels + \ifcase\mfp@axisnum \tl@vpos=2 % x-axis -->[tc] + \def\mfp@ycoord{0}% + \or \tl@hpos=1 % y-axis-->[cr] + \def\mfp@xcoord{0} + \or \tl@hpos=1 % left -->[cr] + \edef\mfp@xcoord{\mfp@lshift}\mfpaddto\mfp@xcoord{#3}% + \or \tl@vpos=2 % bottom-->[tc] + \edef\mfp@ycoord{\mfp@bshift}\mfpaddto\mfp@ycoord{#5}% + \or \tl@hpos=-1 % right -->[cl] + \edef\mfp@xcoord{-\mfp@rshift}\mfpaddto\mfp@xcoord{#4}% + \or \tl@vpos=0 % top -->[bc] + \edef\mfp@ycoord{-\mfp@tshift}\mfpaddto\mfp@ycoord{#6}% + \fi +% \end{macrocode} +% +% Now one of \cs{mfp@xcoord} or \cs{mfp@ycoord} expands to the axis +% position. We change it so that it does this while gobbling a parameter. +% And then call \cs{@axislabels}, feeding it an empty argument as the +% default optional argument. +% \begin{macrocode} + \ifx\@firstofone\mfp@xcoord + \edef\mfp@ycoord####1{\mfp@ycoord}% + \else + \edef\mfp@xcoord####1{\mfp@xcoord}% + \fi \null@opt\@axislabels}% +% \end{macrocode} +% +% \cs{@axislabels} processes the contents of the optional parameter and +% calls \cs{do@axislabel} on the list in the argument. An additional item +% is added that signals the end of the loop. +% \begin{macrocode} + \newdef\@axislabels[##1]##2{% + \tlabeljustify{##1}% + \do@axislabel~ ##2,\mfp@delim}% +% \end{macrocode} +% +% We add some code that traps the most common typos: a comma between the +% label and the coordinate, or a missing coordinate, or a doubled comma. +% It seems impossible to detect which of the first two has happened, and +% assuming the first case produces really awful results if the second is +% true. Therefore when a coordinate seems to be missing, we just lose the +% text (as we have no place to put it) and resume the loop. If the first +% case is true, the next iteration will see only the number, read one +% digit or decimal as the text and the rest as the coordinate. The output +% will be wrong, but at least \TeX{} can proceed. +% +% Above we prepended a `\verb*+~ +' so that if the coordinate is missing, +% the braces around the argument won't be lost; the space will be +% consumed in the argument processing of \cs{do@@axislabel}. +% +% The first argument should be the label, and everything from that to the +% comma is the location. In the above error cases, the second argument +% is empty +% \begin{macrocode} + \newdef\do@axislabel~##1,{% + \@ifmtarg{##1}{\x@axislabel}{\do@@axislabel##1\@nil}}% + \newdef\do@@axislabel##1##2\@nil{% + \@ifmtarg{##2}% + {\Mfpic@warn{Possible extra comma, missing coordinate, or + missing\@msgbreak braces in \string\axislabels\@online. + Skipping this label.}}% + {\tlabel(\mfp@xcoord{##2},\mfp@ycoord{##2}){##1}}% + \x@axislabel}% + \newdef\x@axislabel{% check for end of list + \mfp@ifnextchar\mfp@delim{\@firstoftwo\endgroup}{\do@axislabel~ }}% +% \end{macrocode} +% +% \subsection{Captions}\label{captions} +% +% Captions are not added immediately by the \cs{tcaption} command. That +% command redefines \cs{@docaption} to add it, and \cs{endmfpic} executes +% \cs{@docaption}. For now, \cs{@docaption} does nothing. +% \begin{macrocode} + \newdef\@docaption{}% +% \end{macrocode} +% +% \DescribeMacro{\tcaption} +% \cs{tcaption} takes an optional argument that holds two numbers, +% separated by a comma. The first number determines the maximum width of a +% one line caption. Captions larger than that multiple of the width of the +% graphic will be reset as a paragraph, whose lines have length the second +% number times the width of the graph. The defaults are \oarg{1.2,1}. +% +% \cs{@tcaption} has one mandatory argument, the caption's text. In it, the +% \cs{\bsl} command forces line breaks. This works by forcing the width to +% be greater than any reasonable setting of the maximum line width. When +% this happens, the caption is reset in a \cs{vbox} and \cs{\bsl} is +% redefined like a normal line break. +% \begin{macrocode} + \newdef\tcaption{\simple@opt\tcaption@{1.2, 1.0}}% + \newdef\tcaption@##1{\@tcaption##1\mfp@delim}% + \long\def\@tcaption##1,##2\mfp@delim##3{% + \def\@docaption{% + \setbox\@textbox=% + \hbox{\def\\{\hskip\@M\p@}\mfp@restorepar + \@tcurr##3}% +% \end{macrocode} +% +% If the above \cs{hbox} is too wide, we re-assign \cs{@textbox} to a +% \cs{vbox} with \cs{hsize} determined by the second part of the optional +% argument, and with \cs{leftskip} and \cs{rightskip} defined according +% to the setting of \opt{centeredcaptions}. +% \begin{macrocode} + \@graphwd=\wd\@wholegraph + \ifdim\tb@wd>##1\@graphwd + \setbox\@textbox=% + \hbox{% + \vbox{% + \if@mfp@latex % keep LaTeX's `\\' + \else + \def\\{\unskip\hbox{}\hfil\penalty-\@M\ignorespaces}% + \fi + \if@mfp@centcapt + \leftskip=0pt plus 0.5fil + \rightskip=0pt plus -0.5fil + \parfillskip=0pt plus 1fil + \else + \leftskip=0pt + \rightskip=0pt + \fi + \hsize=##2\@graphwd \mfp@restorepar + \noindent\@tcurr ##3% + }% End vbox. + }% End hbox. + \fi +% \end{macrocode} +% +% Here we determine the wider of the graph or the caption, then put the +% graph and caption together by centering them in \cs{hbox}es with this +% width, stacked one atop the other with \cs{mfpiccaptionskip} (default: +% \cs{medskipamount}) in between. +% \begin{macrocode} + \mfp@scratch=\wd\@wholegraph + \ifdim \mfp@scratch<\tb@wd \mfp@scratch=\tb@wd \fi + \global\setbox\@wholegraph=% + \vbox{\hbox to \mfp@scratch{\hss\box\@wholegraph\hss}% + \nointerlineskip \vskip\mfpiccaptionskip + \hbox to \mfp@scratch{\hss\box\@textbox\hss}}% End vbox. + }% End \@docaption. +% \ignorespaces + }% End \@tcaption. +% \ignorespaces +}% End of \@mfpic +% \end{macrocode} +% +% +% \section{Placing the picture: \cs{endmfpic}}\label{endmfpic} +% +% By the time \cs{endmfpic} is reached, the \MF{} code for the figure has +% all been written to the output file. The labels have all been +% accumulated and arrangements have been made to add the caption. +% +% \DescribeMacro{\endmfpic} +% Under \opt{metapost}, write \cs{endgroup} to match beginning written +% by \cs{mfpic} Then write the \cs{grafbase} command \gbc{endmfpic}, +% followed by a comment telling which figure number it is, and the line +% number in the \TeX{} source where the \cs{endmfpic} occurred. +% \begin{macrocode} +\mfp@DBlog{Definition of closure of mfpic environment.}% +\newdef\endmfpic{% + \mfsrc{\mfp@ifmpost{\@nl verbatimtex \endgroup\space etex;}{}\@nl + endmfpic;\mf@p (\number\mfp@count) \space\@mfplineno.\@nl + \mf@p\mf@d\mf@d\mf@d\@nl}% + \ifmfpicdebug\wlog{}\wlog{Mfpic: ENTERED endmfpic.}\wlog{}\fi +% \end{macrocode} +% The code to load and place the box is skipped if figure shipping was +% turned off. +% \begin{macrocode} + \if@shipping % +% \end{macrocode} +% +% \subsection{Loading and measuring the graphic}\label{loading} +% +% Now we load the graphic. It would be at this point that we could add a +% \cs{write18} to process the figure on-the-fly. Of course that would +% require re-initializing the output file with each graphic (i.e., the +% equivalent of issuing \cs{opengraphsfile} at every \cs{mfpic} and +% \cs{closegraphsfile} at every \cs{endmfpic}.) +% \begin{macrocode} + \global\setbox\@wholegraph=% + \vbox{% +% \end{macrocode} +% +% If draft mode has been detected or set by the user, we just make a box +% of the size specified with the figure number inside it. +% \begin{macrocode} + \ifmfpicdraft + \vbox to \@graphtop{\vss + \hbox to \@graphwd{\kern2pt\tt\#\number\mfp@count\hss}% + \kern2pt}% + \else +% \end{macrocode} +% +% The \opt{truebbox} option works at the \MP{} level. Without it the +% height of the EPS bounding box will actually be the calculated value +% of \cs{@graphtop} (but increased by up to \texttt{2bp} due to rounding). +% With it, the box will be its natural height. In either case, the actual +% height is what we use in the \MP{} case. For \MF{} we use the nominal +% height calculated in \cs{mfpic}. +% \begin{macrocode} + \mfp@ifmpost{\vbox}{\vbox to \@graphtop}% + {\vss +% \end{macrocode} +% +% \cs{@graphfilename} holds the name of the \MP{} output figure. (It will be +% ignored by the \opt{metafont} option.) We test if the file exists before +% doing the graphic inclusion because of the large number of confusing error +% messages many graphic inclusion packages generate otherwise. When absent +% we substitute the figure number for \cs{@setmfpicgraphic}. When present, +% and if in \LaTeXe, we arrange for the current numerical extension to be +% accepted as an EPS or MPS file by the \cs{includegraphics} command of the +% graphics package. +% \begin{macrocode} + \edef\@graphfilename{\setfilename{\mfp@filename}% + {\number\mfp@count}}% + \mfp@ifmpost + {\openin\mfp@graph=\@graphfilename\relax + \ifeof\mfp@graph + \Mfpic@msg{No graph file: \@graphfilename\space.}% + \def\@setmfpicgraphic##1{\raise2pt\hbox{\kern2pt\tt ##1}}% + \closein\mfp@graph + \else\if@mfp@latexe + \@namedef{Gin@rule@.\number\mfp@count}##1{% + {\mfp@Gtype}{.\number\mfp@count}{##1}}% + \fi\fi}{}% +% \end{macrocode} +% +% We put the graphic in an \cs{hbox} of the required width and close off +% the boxes. +% \begin{macrocode} + \mfp@ifmpost{\hbox}{\hbox to \@graphwd}% + {\@xp\@setmfpicgraphic\@xp{\@graphfilename}\hss}% End hbox. + \kern0pt + }% End vbox + \fi + }%% End vbox (\setbox\@wholegraph) +% \end{macrocode} +% +% We change the horizontal and vertical dimensions under \opt{metapost} in +% case \opt{truebbox} was in effect, but also because they are almost always +% rounded up to whole numbers of \texttt{bp} and therefore, even without +% \opt{truebbox} the calculated values needn't be correct. +% \begin{macrocode} + \mfp@ifmpost + {\@graphright=\wd\@wholegraph + \@graphtop=\ht\@wholegraph + \@graphwd=\@graphright}{}% + \ifmfpicdebug + \wlog{Mfpic: graphleft = \the\@graphleft}% + \wlog{Mfpic: graphright = \the\@graphright}% + \wlog{Mfpic: graphtop = \the\@graphtop}% + \wlog{Mfpic: graphbot = \the\@graphbot}% + \wlog{Mfpic: graphwd = \the\wd\@wholegraph}% + \wlog{Mfpic: graphht = \the\ht\@wholegraph}% + \wlog{Mfpic: graphdp = \the\dp\@wholegraph}% + \wlog{}% + \fi +% \end{macrocode} +% +% \subsection{Adding labels and caption}\label{addlabel} +% +% We now add the box \cs{@alltlabels} onto the graph box. The box should +% still have 0pt height and depth, so we can just stick it under the graph +% box. But first we have to adjust for \cs{mfpicllx} and \cs{mfpiclly} +% which can only be known after the graphics inclusion. We reset the box +% \cs{@alltlabels} so its contents are shifted by these values. We only +% need to do this if labels have have actually been added. The signal that +% this has happened is that the label dimensions are no longer +% $\pm$\cs{maxdimen}. +% \begin{macrocode} + \ifmfpicdebug + \wlog{Mfpic: tlabelsleft = \the\@tlabelsleft}% + \wlog{Mfpic: tlabelsright = \the\@tlabelsright}% + \wlog{Mfpic: tlabelstop = \the\@tlabelstop}% + \wlog{Mfpic: tlabelsbot = \the\@tlabelsbot}% + \wlog{}% + \fi + \ifdim\@tlabelsleft < \maxdimen + \setbox\@alltlabels\vtop to 0pt{% + \kern \mfpiclly bp + \moveleft \mfpicllx bp \box\@alltlabels + \vss}% +% \end{macrocode} +% Then we adjust \cs{@tlabelsleft}, etc. for the boundingbox offset. +% \begin{macrocode} + \mfp@scratch\@tlabelsleft + \advance\mfp@scratch-\mfpicllx bp + \ifdim\mfp@scratch<\@graphleft + \@graphleft\mfp@scratch + \fi + \mfp@scratch\@tlabelsright + \advance\mfp@scratch-\mfpicllx bp + \ifdim\mfp@scratch>\@graphright + \@graphright\mfp@scratch + \fi + \mfp@scratch\@tlabelstop + \advance\mfp@scratch-\mfpiclly bp + \ifdim\mfp@scratch>\@graphtop + \@graphtop\mfp@scratch + \fi + \mfp@scratch\@tlabelsbot + \advance\mfp@scratch-\mfpiclly bp + \ifdim\mfp@scratch<\@graphbot + \@graphbot\mfp@scratch + \fi + \setbox\@wholegraph=\vtop{% + \unvbox\@wholegraph\box\@alltlabels}% + \fi +% \end{macrocode} +% +% The method for putting labels in \cs{@alltlabels} does not add any width +% on the left, nor any height to the top or depth to the bottom of that box +% (that \TeX{} can detect), but we have saved their values and now we can +% use them. For example, if \cs{@graphleft} is negative after the above, +% then a label sticks out to the left, but \TeX{} thinks it has no width. +% Therefore put \cs{kern}\texttt{-}\cs{@graphleft} to move the graph +% rightward. The height and depth are taken care of by putting it in +% \cs{vbox} with the calculated total height and moving the graph upward +% with \cs{kern}\texttt{-}\cs{@graphbot}. The rightward extensions do get +% detected by \TeX. +% \begin{macrocode} + \ifmfpicdebug + \wlog{Mfpic: tlabelsleft = \the\@tlabelsleft}% + \wlog{Mfpic: tlabelsright = \the\@tlabelsright}% + \wlog{Mfpic: tlabelstop = \the\@tlabelstop}% + \wlog{Mfpic: tlabelsbot = \the\@tlabelsbot}% + \wlog{}% + \fi + \mfp@scratch=\@graphtop + \advance\mfp@scratch by -\@graphbot + \global \setbox\@wholegraph=% + \vbox to \mfp@scratch{\vss + \hbox{\kern-\@graphleft\box\@wholegraph}% + \kern-\@graphbot}% End vbox. +% \end{macrocode} +% +% Now add the caption, then set the parameters \cs{mfpicheight} and +% \cs{mfpicwidth} for user to examine. The debug info now should show +% graphwd${}={}$graphright${}-{}$graphleft, +% graphht${}={}$graphtop${}-{}$graphbot, and graphdp${}= 0$. +% \begin{macrocode} + \ifmfpicdebug + \wlog{Mfpic: graphleft = \the\@graphleft}% + \wlog{Mfpic: graphright = \the\@graphright}% + \wlog{Mfpic: graphtop = \the\@graphtop}% + \wlog{Mfpic: graphbot = \the\@graphbot}% + \wlog{Mfpic: graphwd = \the\wd\@wholegraph}% + \wlog{Mfpic: graphht = \the\ht\@wholegraph}% + \wlog{Mfpic: graphdp = \the\dp\@wholegraph}% + \wlog{}% + \fi + \@docaption + \global\mfpicheight\ht\@wholegraph + \global\mfpicwidth\wd\@wholegraph + \ifmfpicdebug + \wlog{Mfpic: graphleft = \the\@graphleft}% + \wlog{Mfpic: graphright = \the\@graphright}% + \wlog{Mfpic: graphtop = \the\@graphtop}% + \wlog{Mfpic: graphbot = \the\@graphbot}% + \wlog{Mfpic: graphwd = \the\wd\@wholegraph}% + \wlog{Mfpic: graphht = \the\ht\@wholegraph}% + \wlog{Mfpic: graphdp = \the\dp\@wholegraph}% + \wlog{}% + \fi +% \end{macrocode} +% +% \subsection{Placing the graphic}\label{placing} +% +% Add a frame around the box \cs{@wholegraph} in draft mode (so its size +% can be seen) since there is practically nothing in it except the picture +% number +% \begin{macrocode} + \ifmfpicdraft + \setbox\@wholegraph=% + \hbox{\@mfpframed{-\mfpframethickness}{\box\@wholegraph}}% + \fi +% \end{macrocode} +% +% If the \cs{savepic} command occurred prior to this, then \cs{s@vemfpic} +% is defined and we save this picture in the box named in that +% \cs{savepic} command and stored in the macro \cs{s@vemfpic}. Otherwise, +% \cs{s@vemfpic} is undefined, and we place the picture (\cs{@wholegraph}) +% in the document. Afterward, we undefine \cs{s@vemfpic}. +% \begin{macrocode} + \mfp@ifdefined\s@vemfpic + {\global\setbox\s@vemfpic=\box\@wholegraph}% + {\leavevmode\box\@wholegraph}% + \global\let\s@vemfpic\UndEfInEd +% \end{macrocode} +% +% Now we advance the figure count, end the group started by the \cs{mfpic} +% command, restore the values of extra font dimensions that were saved, +% then arrange for spaces to be ignored in case the syntax +% \cs{begin}\marg{mfpic}$\ldots$\cs{end}\marg{mfpic} was used. +% \begin{macrocode} + \global \advance\mfp@count1 + \fi % end of \if@shipping + \endgroup % Begun near start of \@mfpic + \restore@mfpicdimens + \if@mfp@latex + \def\mfptmp@a{mfpic}% + \ifx\mfptmp@a\@currenvir + \@ignoretrue% so \endmfpic and \end{mfpic} have the same effect. + \fi + \fi + \ignorespaces +}% +% \end{macrocode} +% +% +% \section{Additional features}\label{additional} +% +% \subsection{Saving a copy of the picture}\label{saving} +% +% \DescribeMacro{\newsavepic} +% One saves a picture by first allocating a save box with +% \cs{newsavepic}\marg{\cs{mypic}}, then saying +% \cs{savepic}\marg{\cs{mypic}} beforehand. The \cs{endmfpic} code +% detects that this has been done and saves the picture in \cs{mypic}. +% It can be placed with \cs{usepic}{\cs{mypic}}. +% +% \cs{newsavepic} is just a clone of \LaTeX's \cs{newsavebox}. The one +% argument is a control sequence. +% \begin{macrocode} +\newdef\newsavepic#1{% + \if@mfp@latex \newsavebox{#1}% + \else + \mfp@ifdefined{#1}% + {\mfp@errmsg + {Command \string #1 already defined.}% + {You have used \newsavepic with an already defined or an^^J% + improper control sequence. Replace #1 with another name.^^J% + If you proceed, \newsavepic will be ignored.}}% + {\csname newbox\endcsname#1}% + \fi}% +\newlet\newpic=\newsavepic % compatibility +% \end{macrocode} +% +% \DescribeMacro{\savepic} +% All \cs{savepic} really does is define \cs{s@vepic} to its argument, +% which should be a control sequence defined by \cs{newsavepic} (or +% \cs{newbox}). +% \begin{macrocode} +\newdef\savepic#1{\relax + \mfp@ifdefined{#1}{\gdef\s@vemfpic{#1}}% + {\mfp@errmsg{Box \string#1 undefined.}% + {You tried to save a picture in a box which had not been^^J% + previously allocated. Use \newsavepic to allocate a box.}}}% +% \end{macrocode} +% +% \DescribeMacro{\usepic} +% \cs{usepic} takes one argument, a control sequence that should have +% been previously used in a \cs{savepic} comamnd. It just places the box +% with the primitive \cs{copy} command. +% \begin{macrocode} +\newdef\usepic#1{\leavevmode \copy#1\relax}% +% \end{macrocode} +% +% \subsection{Putting a frame around it}\label{frame} +% +% This is essentially code I wrote years ago to have a framing command +% that had two properties not enjoyed by come example `\cs{boxit}' commands +% for plain\TeX: It should have a baseline the same as the baseline of the +% contents, and it should work as an environment, not by reading an +% argument (so verbatim material could be included). +% +% \DescribeMacro{\mfpframed} +% \DescribeMacro{\mfpframe} +% \cs{mfpframed} takes an optional argument (the separation) and a +% mandatory argument, the contents. \cs{mfpframe}$\ldots$\cs{endmfpframe} +% is an environment and \cs{mfpframe} also takes the separation as an +% optional argument. +% +% \DescribeMacro{\framed} +% \cs{framed} is a common command (\ConTeXt{} has one, a few packages also +% define it), therefore we only define it if it is not already defined. +% \begin{macrocode} +\newdef\mfpframed{\simple@opt\@mfpframed\mfpframesep}% +\newdef\mfpframe{\simple@opt\@mfpframe\mfpframesep}% +\newdef\@mfpframed#1#2{\@mfpframe{#1}#2\endmfpframe}% +\newdef\@mfpframe#1{% + \leavevmode\hbox\bgroup + \mfpframesep#1\relax + \vrule width\mfpframethickness + \vtop\bgroup + \vbox\bgroup + \hrule height\mfpframethickness + \kern\mfpframesep + \hbox\bgroup \kern\mfpframesep \ignorespaces}% +\newdef\endmfpframe{\unskip + \kern\mfpframesep + \egroup % end hbox + \egroup % end vbox + \kern\mfpframesep + \hrule height\mfpframethickness + \egroup % end vtop + \vrule width\mfpframethickness + \egroup}% end hbox +\mfp@ifdefined\framed{}{\newlet\framed=\mfpframed}% +% \end{macrocode} +% +% \subsection{Adding \mfc{verbatimtex} to the \file{.mp} +% file}\label{verbatimtex} +% +% \DescribeMacro{mfpverbtex} +% This is a user level utility for putting some \mfc{verbatimtex} material +% in the output file for \MP. We allow the user to do this even before +% \cs{opengraphsfile} by storing it in a token register and setting a flag +% for that command to test. +% \begin{macrocode} +\newif\if@mfp@verbtex +\def\mfpverbtex{% +% \end{macrocode} +% +% We start a group, make sure lines will be preserved in writing the +% material, make sure that \texttt{\#} characters will not be doubled by +% changing its category, then continue after loading the code into the +% token register \cs{mfp@verbtex}. +% \begin{macrocode} + \begingroup \preservelines \@makeother\#% + \afterassignment\mfp@writetex\global\mfp@verbtex=}% +% \end{macrocode} +% +% We end the group and then either set the switch to tell +% \cs{opengraphsfile} that the material is ready, or we write it to the +% output, between the commands \gbc{verbatimtex} and \cs{etex}. +% \begin{macrocode} +\def\mfp@writetex{% + \endgroup + \@ifmfpfileisopen + {\mfp@ifmpost + {\mfsrc{verbatimtex}\mfsrc{\the\mfp@verbtex}\mfcmd{etex}}% + {\noMP@error{verbatimtex}}% + \global\@mfp@verbtexfalse\mfp@verbtex{}}% + {\global\@mfp@verbtextrue}}% +% \end{macrocode} +% +% +% \section{Finale}\label{finale} +% +% Set the default starting graphic number. +% \begin{macrocode} +\global\mfp@count=1 % 1 because we now advance it in \endmfpic. +% \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} +\newdef\MFPICinput#1{% + \immediate\openin\mfp@graph=#1 + \ifeof\mfp@graph + \immediate\closein\mfp@graph + \else + \immediate\closein\mfp@graph + \input #1 + \fi}% +\MFPICinput{mfppatch.tex}% +% \end{macrocode} +% +% Restore the meaning of \cs{+}, and of the \cs{newlinechar}, and execute +% the command that restores all the saved category codes. +% \begin{macrocode} +\mfp@DBlog{Punctuation, etc., will revert to old catcodes now.}% +\let\+\mfpsaveplus +\restorenewlinechar +\MFPicpackagE% +\MFPICinput{mfpic.usr}% +%</tex> +% \end{macrocode} +% +% Generate a (far too) simple wrapper for \LaTeX. +% \begin{macrocode} +%<*sty> +\input mfpic.tex\relax +%</sty> +% \end{macrocode} +%\clearpage +%\Finale |