\documentclass[numbers=noenddot, pagesize=auto]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{etoolbox}
\usepackage{xspace}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[svgnames]{xcolor}
\usepackage{listings}
\usepackage{microtype}
\usepackage[unicode=true]{hyperref}

\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\opt}[1]{\texttt{#1}}
\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}

\renewcommand*{\thesubsection}{\thesection\,\alph{subsection}}
\renewcommand*{\theenumi}{\alph{enumi}}
\renewcommand*{\labelenumi}{\theenumi)}
\addtokomafont{title}{\rmfamily}

% fix bug in listings package, see http://groups.google.de/group/comp.text.tex/browse_thread/thread/b004ec97fd72613a
\makeatletter
\preto\lstlisting{\global\@noskipsectrue}
\makeatother

\lstset{%
  language=[LaTeX]TeX,%
  columns=fullflexible,%
  upquote=true,%
  numbers=left,%
  basicstyle=\small\ttfamily,%
  keywordstyle=\color{Navy},%
  commentstyle=\color{DimGray},%
  stringstyle=\color{SeaGreen},%
  numberstyle=\scriptsize\color{SlateGray}%
}


\title{The \pkg{grfpaste} package\thanks{This manual corresponds to \pkg{grfpaste}~v0.2, dated~1997/07/18.}}
\subtitle{\LaTeX\ support for \TeX plorators / M. Spivak \texttt{dvipaste} program}
\author{David Carlisle}
\date{1997/07/18}


\begin{document}

\maketitle

\tableofcontents

\begin{quote}
  \footnotesize
  This package can redistributed and/or modified under the terms
  of the \LaTeX\ Project Public License Distributed from CTAN
  archives in directory \texttt{macros/latex/base/lppl.txt}; either
  version~1 of the License, or (at your option) any later version.
\end{quote}

\noindent
\texttt{Dvipaste} comes with a plain~\TeX\ based set of macros in a file
\texttt{dvipaste.tex} that provide an interface to the \texttt{dvipaste} program. That
file works perfectly well in \LaTeX\ with only minor modifications
(specifically using \cmd{\@@line} instead of \cmd{\line}, and \cmd{\c@page} instead of
\cmd{\pageno}). A \texttt{dvipaste.sty} constructed by just such modifications may be
found distributed with Jean-Pierre Drucbert's `\pkg{export'} package on \textsc{ctan}.
However I thought that it would be more in the `\LaTeX\ spirit'
to provide an interface via the existing \LaTeX\ graphics package.

The files produced by this \pkg{grfpaste} package should be fully compatible
with \texttt{dvi\-paste.tex} or \texttt{dvipaste.sty}. That is, if \textsc{dvi} fragments are
created using the plain~\TeX\ interface they may be included using
\cmd{\includegraphics} via this package, and conversely if this package is
used with the \opt{[write]} or \opt{[writepages]} options to produce a file of \textsc{dvi}
fragments for including in another file, then the \textsc{dvi} file (and it's
accompanying `\texttt{.dat}' file of size information) may be included either
with this package, or via the original \texttt{dvipaste.tex} interface.

Currently the \LaTeX\ interface uses the \pkg{graphicx} package, it would be
possible to also provide an interface to the more basic \pkg{graphics}
package, but that is not done here.

The package is used in one of two forms.



\section{Producing DVI Fragments}

\subsection{Writing out boxes.}

\begin{lstlisting}
\documentclass{article}

\usepackage[write]{grfpaste}

\begin{document}

\sendout{\parbox[b]{2cm}{one \sf two three \tt four \it five}}

\sendout[abc]{hello}

\sendout{\parbox[t]{2cm}{one \sf two three \tt four \it five}}

\end{document}
\end{lstlisting}
%
If the package is used with the \opt{[write]} option then the document should
just consist of \cmd{\sendout} commands, the argument of each will be marked
as a `fragment' that may be pasted into another DVI file by the \texttt{dvipaste}
program. An auxiliary file with extension \texttt{.dat} will be created which
contains the size of each of these fragments. Normally the fragments
will be accessed by their number, starting from~1, but you may
optionally supply a label, as in `\texttt{abc}' above which allows fragments to
be referenced more easily. The above example forms the example
document \texttt{grfp1.tex} in this distribution.


\subsection{Writing out whole pages.}

\begin{lstlisting}
\documentclass{article}

\usepackage[writepages]{grfpaste}

\begin{document}
...
\end{document}
\end{lstlisting}
%
If the package is used with the \opt{[writepages]} option then each
indivdual page will be marked as a `fragment' for later processing by
\texttt{dvipaste}. The fragments will be numbered consecutively, starting from~%
1, whatever the value of the page counter.  See the example document
\texttt{grfp2.tex}.



\section{Using DVI Fragments}

\begin{lstlisting}
\documentclass{article}

\usepackage{grfpaste}

\begin{document}

aaa\fbox{\includegraphics
        [num=1,natheight=19,natdepth=2pt,natwidth=57]{grfp1.dvi}}bbb

xxx\fbox{\includegraphics[num=2]{grfp1.dvi}}yyy

xxx\fbox{\includegraphics[ref=abc]{grfp1.dvi}}yyy

Page 3 of grfp2.dvi:
aaa\fbox{\includegraphics[num=3]{grfp2}}bbb

\end{document}
\end{lstlisting}
%
To use the fragments then load the package with no option (or
equivalently with the \opt{[include]} option). You may also use any options
understood by the \pkg{graphicx} package, these will be passed on to \pkg{graphicx}
which is loaded by this package.

To load the first fragment of a given \textsc{dvi} file you just need
\cmd{\include\-graphics}\marg{file\-name} or \cmd{\include\-graphics}\texttt{\{}\meta{file\-name}\texttt{.dvi\}}
(\texttt{.dvi} is added as one of the default extensions by this package)

To access later fragments then you use the new \texttt{num=}\meta{??} key to specify
the fragment number, as demonstrated above. If there are a lot of
fragments maintaining the correct number may be inconvenient so you
may instead use the \texttt{ref=} key to refer to a label previously supplied
by the \cmd{\sendout} command. Note this label information is added to the
\texttt{.dat} file in the form of a comment (after \texttt{\%}) and so the \texttt{.dat} file is
still compatible with  \texttt{dvipaste.tex}, but if that is used, then the
numeric form must be used. Thus the two examples above with \texttt{num=2}
and \texttt{ref=abc} include the same fragment from the file \texttt{grfp1.dvi}.

Normally the size of the graphic is read from the `\texttt{.dat}' file which is
the `read file' for the \textsc{dvi} graphic type, in the terminoligy of the
\pkg{graphics} package documentation.  If you have lost the \texttt{.dat} file, or
wish to override it with altered sizes, you may specify the natural
size using the \texttt{natheight}, \texttt{natwidth} and \texttt{natdepth} keys. As usual these
take a dimension but the units may be omitted in which case \texttt{bp} are
assumed.  \texttt{natheight} and \texttt{natwidth} are standard \pkg{graphicx} keys, but
\texttt{natdepth} is new, as these fragments are \TeX\ boxes, so have height and
depth, unlike most other graphic formats that may be included, which
always have zero depth.

The \cmd{\sendout} command defined by the \opt{[write]} option matches that used
in the plain~\TeX\ support, but the plain~\TeX\ version does not use
\cmd{\includegraphics} to include the fragment. It defines a command \cmd{\paste}
to achieve this. In order to help move documents between the two
versions, a \opt{[defpaste]} option is provided for this package which
specifies that a compatible \cmd{\paste} command should be defined. It is
defined to be the equivalent call to \cmd{\includegraphics},
\verb+\includegraphics[num=#2]{#1}+.

See the example file \texttt{grfp3.tex} to see examples of including \textsc{dvi}
fragments.



\section{Putting it all together}

\begin{enumerate}
\item Produce one or more files of fragments using
  \LaTeX\ and this package with the \opt{[write]} or \opt{[writepages]} options.
  (or plain~\TeX\ using \texttt{dvipaste.tex}).
  
\item \LaTeX\ your master document, including this package and using
  \cmd{\includegraphics} to include the fragments at the appropriate points.
  
  At this stage the file will have blank spaces (but if the correct
  size) at the points where the \textsc{dvi} fragments should appear
  
\item  Run \texttt{dvipaste} on the master \textsc{dvi} file. It will incorporate the
  fragments and re-write the file.
  
\item  Preview or print the modified \textsc{dvi} file in your usual manner.
\end{enumerate}



\section{Running the examples}

\lstset{language=bash}

\begin{itemize}
\item \texttt{grfp1.tex} is an example of using the \opt{[write]} option
\item \texttt{grfp2.tex} is an example of using the \opt{[writepages]} option
\item \texttt{grfp3.tex} is an example of using the \opt{[include]} option
\end{itemize}
%
To process the final document (\texttt{grfp3.dvi}) the following steps need be
taken.
%
\begin{lstlisting}
latex grfp1
latex grfp2
latex grfp2
latex grfp3
dvipaste grfp3
\end{lstlisting}
%
Note that \texttt{grfp2} needs to be processed twice to generate a full table of
contents. After \texttt{grfp3.tex} is processed by \LaTeX\ the \textsc{dvi} file will show
blank spaces at the points that the fragments are to be included. These
will be filled in by running \texttt{dvipaste}, after which the \texttt{grfp3.dvi} may be
processed by your driver in the normal way.



\section{Compiling \texttt{dvipaste.c}}

\lstset{language=C}

\begin{lstlisting}
/* config.h for LINUX machines for dvipaste.c (DPC) */


#define ANSI
#undef MICROSOFTC
#define LITTLENDIAN

/* I guess this is what was meant. */
/* (dvipaste.c defines strcmp to itself */
/* leaving stricmp undefined) .*/
#ifndef MICROSOFTC
#define strnicmp strncmp
#define stricmp strcmp
#endif

#ifdef ANSI
/* Other things in ANSI C are good, but this is a crock */
#define READ_BINARY "rb"
#define WRITE_BINARY "wb"
#else
/* The good old simple and logical K&R I/O */
#define READ_BINARY "r"
#define WRITE_BINARY "w"
#endif
\end{lstlisting}
%
When I tried compiling \texttt{dvipaste.c} I got error due to the function
\texttt{stricmp} being undefined. The file has a circular definition of \texttt{strcmp}
to itself which looks like a typo, so I corrected that by making 
\texttt{stricmp} an alias for \texttt{strcmp} by altering \texttt{config.h} as above (which also
sets \texttt{LITTLENDIAN} for Linux. It seems to work for me, but no promises.

The above suggested \texttt{config.h} leaves \texttt{stricmp} meaning the same thing as
\texttt{strcmp} (string comparison). Jean-Pierre Drucbert points out that
\texttt{stricmp} is (on systems that it is defined) a case-insensitive
comparison function, and that rather than the crude substitution above
one may define it as follows.
%
\begin{quote}
  \texttt{str\{n\}icmp} is not available on all systems. So I got the
  following code in \texttt{ci.c}~:
  %
\begin{lstlisting}
#include <ctype.h>
#include "config.h"
/*
* str{n}icmp - case-insensitive flavors of strcmp(), strncmp()
*/
#ifdef PROTOS
int stricmp(register char *s1,
register char *s2)
#else
int stricmp(s1, s2)
register char *s1, *s2;
#endif
{
  register char c1, c2;
  
  for ( ; (c1 = TOLOWER(*s1)) == (c2 = TOLOWER(*s2)); s1++, s2++)
  if (c1 == '\0')
  return 0;
  
  return c1 - c2;
}


#ifdef PROTOS
int strnicmp(register char *s1,
register char *s2,
int n)
#else
int strnicmp(s1, s2, n)
register char *s1, *s2;
int n;
#endif
{
  register char c1, c2;
  
  for ( ; --n >= 0 &&
  (c1 = TOLOWER(*s1)) == (c2 = TOLOWER(*s2)); s1++, s2++)
  if (c1 == '\0')
  return 0;
  
  return n < 0 ? 0 : c1 - c2;
}
\end{lstlisting}
\end{quote}

By default \texttt{dvipaste.c} has
%
\begin{lstlisting}
#define STRINGSIZE (5124)       /* maximum string size */
\end{lstlisting}
%
Jean-Pierre Drucbert commented:
%
\begin{quote}
  it is necessary to increase \texttt{STRINGSIZE} if you paste a lot of \textsc{dvi}
  pieces (I~increased it from 40592 to 2597888)\@. In practice, do
  not export more than~\textasciitilde 100 pieces from one file. You can import a
  lot more into one file. So it is preferable to import from
  several files if you have more than 100 pieces to import.
\end{quote}

\end{document}
























