exteps.tex (4aug10)

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

1 files changed, 410 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/metapost/exteps/exteps.tex b/Master/texmf-dist/doc/metapost/exteps/exteps.tex
new file mode 100644
index 00000000000..a2314a15e2f
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/exteps/exteps.tex
@@ -0,0 +1,410 @@
+\documentclass[a4paper,11pt,british,DIVcalc]{scrartcl}
+\usepackage[T1]{fontenc,url}
+\usepackage[latin1]{inputenc}
+\usepackage{soul,babel,mflogo,xspace,tabularx,fancyref,booktabs,textcomp,ifpdf}
+\usepackage[dvips]{graphicx}
+\usepackage[final]{listings}
+\usepackage[sc]{mathpazo}
+%\usepackage{luximono}
+
+
+\newcommand{\exteps}{\texttt{\upshape exteps}\xspace}
+\newcommand{\delfin}{\texttt{\upshape delfin}\xspace}
+%\let\delfin\relax
+
+\usepackage{hyperref}
+\addto\itemize{\def\labelitemi{-\kern-.15em-}}
+\hypersetup{ps2pdf,a4paper,pdfauthor=Palle Jørgensen, pdftitle={exteps
+    documentation}, pdfsubject={Inclusion of external EPS graphics in
+    MetaPost figures},pdfkeywords={MetaPost,EPS,external,exteps}}
+\author{Palle Jørgensen} 
+
+\title{\so{Using external EPS graphics in} \MP\\\LARGE \so{The}
+  \exteps \so{module}\\\so{Version} \oldstylenums{0.41}}
+
+\lstset{basicstyle=\small,breaklines=true,columns=fullflexible}
+\renewcommand{\thesection}{\oldstylenums{\arabic{section}}}
+\renewcommand{\thesubsection}{\oldstylenums{\arabic{subsection}}}
+\renewcommand{\thefigure}{\oldstylenums{\arabic{figure}}}
+\renewcommand{\thepage}{\oldstylenums{\arabic{page}}}
+
+\makeatletter
+\let\vref@space\space
+\let\old@section\section
+\def\section{%
+  \@ifstar{%
+    \old@section*%
+  }{%
+    \so@section}%
+}
+\def\so@@@section#1{\old@section[#1]{\so{#1}}}
+\def\so@@section[#1]#2{\old@section[#1]{\so{#2}}}
+\def\so@section{%
+  \@ifnextchar[%]
+  {%
+    \so@@section
+  }{%
+    \so@@@section
+  }%
+}
+
+\let\old@subsection\subsection
+\def\subsection{%
+  \@ifstar{%
+    \old@subsection*%
+  }{%
+    \so@subsection}%
+}
+\def\so@@subsection[#1]#2{\old@subsection[#1]{\so{#2}}}
+\def\so@@@subsection#1{\old@subsection[#1]{\so{#1}}}
+\def\so@subsection{%
+  \@ifnextchar[%]
+  {%
+    \so@@subsection
+  }{%
+    \so@@@subsection
+  }%
+}
+\def\trr{\rightskip\@flushglue}
+
+\makeatother
+\renewcommand{\textfraction}{0}
+\addtokomafont{sectioning}{\normalfont\scshape}
+\lstset{language=metapost}
+
+\begin{document}
+\def\contentsname{\so{Contents}}
+\maketitle
+\tableofcontents
+
+\clearpage
+\section{Introduction}
+\label{sec:introduction}
+
+This document describes the use of the \exteps module for inclusion of
+external EPS figures in \MP\ figures. Unlike the previous attempt
+(epsincl) it make no use external programs\footnote{This is only
+  partly true, as \MP\ is unable to handle large files; a workaround
+  is described in appendix~\vref{sec:large-eps-files}}; it is
+entirely written in \MP.
+
+The EPS graphics is included using the \emph{special} command in \MP.
+\clearpage
+
+\section{Using \exteps}
+\label{sec:using-exteps}
+
+To illustrate the use of the \exteps module an example is given below.
+Between the \texttt{begineps} and \texttt{endeps} commands both
+settings can be set, as well as special drawing commands can be added.
+The output of the example and the original picture can be seen in
+\fref{fig:orig-and-mod}.
+
+\lstinputlisting[lastline=15]{example.mp}
+\begin{figure}[!h]
+  \includegraphics[bb = 0 -50 150 200,clip,scale=.71]{pallej}\hfill
+  \includegraphics[bb= -25 -25 180 225,scale=.71,clip=true]{example.1}\hfill
+  \includegraphics[bb = 10 -25 175 225,scale=.71,clip=false]{example.5}
+  \caption{The original (left) and the with \exteps modified picture
+    (middle). To the right there is one without the grid and the dot at the
+    origin.}
+  \label{fig:orig-and-mod}
+\end{figure}
+
+\clearpage
+\subsection{Settings}
+\label{sec:settings}
+
+The parameters of the settings and their defaults can be seen the
+table below\bigskip.
+
+\noindent\begin{tabularx}{\linewidth}{llp{2cm}<\trr X}
+  \toprule
+  Parameter & Type & Default & Description\\
+  \midrule
+  angle & numeric & 0 & The counterclockwise rotation of the EPS figure.\\
+  clipping\footnotemark & boolean & false & If true, the EPS figure is
+  clipped to its bounding box.\\
+  clippath & path & Bounding box of the EPS file & Path to which the
+  EPS picture is clipped, if the \emph{clipping} switch is \emph{true.}\\
+  base & pair & (0,0) & The offset of the lower left corner of the EPS
+  picture.\\
+  scale & pair & (1,1) & The scaling of the picture.\\
+  width & numeric & No default & Specify the width of the picture;
+  overrules the scale setting.\\
+  height & numeric & No default & Specify the height of the picture;
+  overrules the scale setting.\\
+  grid & boolean & false & If true a grid is draw on top of the
+  picture; mostly (only?) meant to help when drawing on top of the EPS
+  figure.\\
+  gridstep & numeric & 10 & The distance in percent between the lines
+  of the grid.\\
+  gridllx & numeric & 0 & The x-part of the lower left corner of the grid; in pct \\
+  gridlly & numeric & 0 & The y-part\\
+  gridurx & numeric & \emph{full width} & The x-part of the upper rightt corner of the grid\\
+  gridury & numeric & \emph{full height} & The y-part\\
+  \bottomrule
+\end{tabularx}
+\footnotetext{In version \oldstylenums{0.1} named \emph{clip}}
+
+\subsection{Special values}
+\label{sec:special-values}
+
+\texttt{begineps} saves the original bounding box of the EPS picture
+in the values \texttt{llx}, \texttt{lly}, \texttt{urx} and
+\texttt{urx}. These values can be used in the settings, and for
+drawing commands. Furthermore a numeric value \texttt{pct} is set.
+This is a length that is one percent of the width of the picture.
+
+If for instance one wants the picture to be placed at the same place on
+the page as the original picture it is simply typing
+\begin{lstlisting}
+  base:=(llx,lly);
+\end{lstlisting}
+between \texttt{begineps} and \texttt{endeps}.
+
+\subsection{Drawing commands}
+\label{sec:drawing-commands}
+
+When \texttt{begineps} is called a special picture,
+\texttt{epspicture}, is created. To draw on this picture, and whence
+drawing on the EPS picture the special commands \texttt{epsdraw},
+\texttt{epsfill}, \texttt{epsfilldraw}, \texttt{epsdrawdot} and
+\texttt{epslabel} are defined. They work as the normal drawing
+commands, but now adds to the \texttt{epspicture}. 
+
+At \texttt{endeps} the \texttt{epspicture} is scaled, rotated and
+translated in the same way as the included EPS figure.
+
+\subsection{Clipping the EPS picture}
+\label{sec:clipping-eps-picture}
+
+From version \oldstylenums{0.2} it is possible to do advanced clipping of the EPS
+picture.
+
+This is done by specifying the path \emph{clippath} along which the
+EPS picture is to be clipped, and setting \emph{clipping} to
+\emph{true}.
+
+A minor example and the result in \fref{fig:clipped}:
+\lstinputlisting[firstline=37,lastline=44]{example.mp}
+
+\begin{figure}[tb]
+  \includegraphics[scale=.71]{example.3}\hfill
+  \includegraphics[bb = 30 -2 175 225,,scale=.71]{example.2}\hfill
+  \includegraphics[bb = 30 -2 175 225,,scale=.71]{example.4}
+  \caption{The clipped picture to the right, and the original with a
+    grid to the left. The clippath is marked with blue. The picture in
+    the midlle is created by keeping the blue line on top of the
+    clipped picture.}
+  \label{fig:clipped}
+\end{figure}
+
+Please note that this does not clip the \texttt{epspicture}.
+You can do this manually by specifying
+\begin{lstlisting}
+  clip epspicture to clippath;
+\end{lstlisting}
+or
+\begin{lstlisting}
+  setbounds epspicture to clippath;
+\end{lstlisting}
+
+The section about the grid~\vpageref{sec:grid} also provides an
+example of the clipping commands.
+
+\newpage
+\subsection{The grid}
+\label{sec:grid}
+It is possible to finetune the settings og the grid, for instance when
+clipping the picture. The example below shows the impact of setting
+the values of \texttt{gridstep}, \texttt{gridllx}, \texttt{gridlly},
+\texttt{gridurx}, and \texttt{gridury}. The result can be seen in
+\fref{fig:grid}.
+
+\lstinputlisting[firstline=55,lastline=69]{example.mp}
+
+\begin{figure}[tbp]
+  \includegraphics[scale=.71]{example.6}
+  \caption{The picture with the finetuned grid, and some clipping.}
+  \label{fig:grid}
+\end{figure}
+
+\section{Limitations of \exteps}
+\label{sec:limitations}
+\begin{itemize}
+\item \exteps only looks at the first line in the document
+  that says \\\verb|%%BoundingBox:|~\dots 
+  
+  Thus it will cause trouble if this line does not provide the
+  bounding box; some PostScript drivers may write
+  \verb|%%BoundingBox: (atend)|. This is not supported.
+  
+\item As all of the graphics inclusion is done with \MP, it is limited
+  by \MP's memory capacity. More specific on the string pool size.
+  
+  Read more about this problem, and about the \emph{delfin} workaround
+  perl script in \appendixname~\vref{sec:large-eps-files}
+
+\item As the module makes it possible to include external EPS pictures
+  it may not be possible to use the output with \textsc{pdf}\TeX.
+
+  A way to get around this is to use the program epstopdf.
+
+  epstopdf is  located on CTAN at\\
+  \url{http://tug.ctan.org/tex-archive/support/epstopdf/}.
+  
+  Another possible work-around for this is to use the program
+  purifyeps to ``clean up'' the PostScript picture.
+  
+  purifyeps is located on CTAN at\\
+  \url{http://tug.ctan.org/tex-archive/support/purifyeps/}.
+  
+  Yet another work-around is to use the program pstoedit to generate
+  \MP\ code form EPS files and include this into your \MP\ file.
+
+  See \url{http://www.pstoedit.net/pstoedit/}.
+\end{itemize}
+
+
+\section{Changes}
+\label{sec:changes}
+
+\addtocontents{toc}{\setcounter{tocdepth}{1}}
+\subsection{From version \mbox{\oldstylenums{0.1}} to \mbox{\oldstylenums{0.2}}}
+\label{sec:from-version-0.1-to-0.2}
+
+\begin{itemize}
+\item Adding advanced clipping, see \fref{sec:clipping-eps-picture}.
+\item Renaming the \emph{clip} switch to \emph{clipping}.
+\item Eliminating the \verb|showpage| ``problem'' in version \oldstylenums{0.1}.
+\end{itemize}
+
+\subsection{From version \mbox{\oldstylenums{0.2}} to \mbox{\oldstylenums{0.3}}}
+\label{sec:from-version-0.2-to-0.3}
+
+\begin{itemize}
+\item Improvement of the grid drawing commands. The grid is now drawn
+  \emph{after} the scaling of the picture.
+\item Introducing a workaround for large files. This includes a Perl
+  script.
+\end{itemize}
+
+\section{Comments and Bug Reports}
+\label{sec:comments-bug-reports}
+
+All comments, questions and bug reports, both on the module itself as
+well as this document may be sent to Palle Jørgensen,
+\href{mailto:hamselv@pallej.dk}{hamselv@pallej.dk}.
+
+\section{This document}
+\label{sec:this-document}
+
+\textcopyright\ \the\year\ by Palle Jørgensen.\\  The license of this
+document is GNU General Public License. Source of this document and the
+used example can be found at \url{http://pallej.dk/exteps/}.
+
+\clearpage
+\appendix
+\section{Source code of \exteps}
+\label{sec:source-code-exteps}
+
+\lstinputlisting[firstline=22,extendedchars=true]{exteps.mp}
+
+\clearpage
+\section{Large EPS files}
+\label{sec:large-eps-files}
+
+In case of a too large EPS file, the \exteps module causes an error
+message from \MP, due to the limited memory capacity of \MP.
+
+The error message looks somewhat like this:
+
+\begin{verbatim}
+camel25:~/tmp% mpost et.mp
+This is MetaPost, Version 0.641 (Web2C 7.5.2)
+(/usr/local/TeX/texmf/web2c/cp8bit.tcx)
+(et.mp (/users/pallej/texmf/metapost/exteps.mp)
+Inserting sk.eps into et.1
+! MetaPost capacity exceeded, sorry [pool size=476396].
+<read>
+
+<forever> __eps__currentline:=readfrom.file;
+                                            exitunless.__eps__currentline<>E...
+
+endeps->...<>EOF;special.__eps__currentline;endfor
+                                                  .fi.special"%%EndDocument:...
+l.14      endeps
+\end{verbatim}
+A workaround for this problem is to set the value \texttt{largefile}
+to \texttt{true}:
+\begin{lstlisting}
+  largefile:=true;
+\end{lstlisting}
+
+\exteps now writes 
+\begin{lstlisting}
+  %% MetaPost exteps large file->file.eps
+\end{lstlisting}
+into the \MP\ output file. Afterwards one must run the Perl script
+\delfin onto the \MP\ output file.
+
+First run \MP:
+\begin{verbatim}
+This is MetaPost, Version 0.641 (Web2C 7.5.2)
+(/usr/local/TeX/texmf/web2c/cp8bit.tcx)
+(et.mp (/users/pallej/texmf/metapost/exteps.mp)
+exteps notification:  File sk.eps not inserted into et.1
+                      Run 'delfin et.1' to insert sk.eps
+                      This is caused by setting 'largefile:=true'
+[1] )
+1 output file written: et.1
+Transcript written on et.log.
+camel25:~/tmp%
+\end{verbatim}
+
+and then \delfin
+\begin{verbatim}
+camel25:~/tmp% delfin et.1
+This is delfin version 0.1
+Delfin, the Exteps Large File INserter
+Inserting sk.eps into et.1
+camel25:~/tmp%
+\end{verbatim}
+
+It is possible to turn off the \exteps notification; just set the
+(global) value \texttt{extepsverbose} to false
+\begin{lstlisting}
+  extepsverbose = false;
+\end{lstlisting}
+
+If you are unable to use the \delfin program, it is still possible
+to do the finishing. Just open the \MP\ output file in your favourite
+editor, and replace the line mentioned above with the entire EPS file.
+
+\subsection{Using \delfin}
+\label{sec:delfin-program}
+Usage of the \delfin program:
+\begin{verbatim}
+delfin [options] file.n [file.m [file.l ... ]]
+Options:
+    -h  Print this message end exit
+    -q  Be quiet
+    -v  Display version and license and exit
+    -V  Display version number and exit
+
+\end{verbatim}
+
+\subsection{Source of \delfin}
+\label{sec:source-delfin}
+
+\lstinputlisting[lastline=1,extendedchars=true,language=perl]{delfin}
+[license stuff etc.]%\vskip-\baselineskip
+\lstinputlisting[firstline=31,extendedchars=true,language=perl]{delfin}
+
+\end{document}
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: t
+%%% End: