path: root/Master/texmf-dist/doc/latex/hvextern/hvextern.tex

\RequirePackage{pdfmanagement-testphase}
\DeclareDocumentMetadata{}
\documentclass[ngerman,a4paper]{article}
\usepackage{babel}
\usepackage{libertinus}
\setmonofont[Scale=MatchLowercase,FakeStretch=0.88]{AnonymousPro}
\usepackage{iftex}

\usepackage{hvlogos}
\usepackage{hvextern}
\usepackage{listings}
\lstset{basicstyle=\ttfamily\small,language=[LaTeX]TeX,breaklines}
\usepackage{xcolor}
\usepackage{hyperref}
\begin{document}
\title{Writing, running and including the output of external documents 
from within a main \LaTeX\ document~--v. \hvexternFileversion}
\author{Herbert Voß\thanks{herbert@dante.de}}
\maketitle

\tableofcontents

\newpage

\setkeys{hv}{moveToExampleDir,ExampleDir=Examples}
\section{Syntax}

\begin{verbatim}
\usepackage{hvextern}
\end{verbatim}

\begin{sloppypar}
This package allows to write external \MP, \TeX, \ConTeXt, \LaTeX, \LuaTeX, \LuaLaTeX, \XeTeX, \XeLaTeX, Lua, Perl, Java and/or Python
source code, which will then be run via \texttt{shell escape} to create a PDF oder text output to include
it into the main \LaTeX\ document. 
\end{sloppypar}


There is only one environment:

\begin{verbatim}
\begin{externalDocument}[<options>]{<external filename without extension>}
...
source code
...
\end{externalDocument}
\end{verbatim}

The main document \emph{must} be run with the \texttt{-shell-escape} option, otherwise it won't work, e.g.:

\begin{verbatim}
laulatex --shell-escape <file>
\end{verbatim}




The purpose for this package is to show the output of documents which have to be compiled with
a different preamble or a different engine or a complete different system, but integrating the output
automatically in the main document..

\bigskip
\noindent
\fbox{\begin{minipage}{\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax}
\emph{All} examples in this document are created on-the-fly while running this \LaTeX\ document
with \texttt{lualatex} with the  \texttt{-\kern2pt-shell-escape} option.
\end{minipage}}



\section{First examples}
\subsection{Without showing the code}

This document was run with \LuaLaTeX. Suppose you want to insert the output of a document
which needs for several reasons a \pdfLaTeX\ run. Instead of created and running a document 
outside of the main document and then to insert the output
we can do this from within this \LuaLaTeX\ document itself. The external document is compiled
with \pdfLaTeX\ and the output is insert as pdf image. The source code itself is not
shown by the environment \texttt{externalDocument}.


\begin{minipage}{.59\linewidth}
\begin{lstlisting}
\begin{externalDocument}[
  compiler=pdflatex,force,cleanup]{voss}
\documentclass{standalone}
%StartVisiblePreamble
\usepackage{fontenc}
\usepackage{libertinus}
\usepackage[linguistics]{forest}
\forestapplylibrarydefaults{linguistics, edges}
%StopVisiblePreamble
\begin{document}
\begin{forest}
[VP
  [DP]
  [V’
   [V]
  [DP]
  ]
]
\end{forest}
\end{document}
\end{externalDocument}
\end{lstlisting}
\end{minipage}
\begin{minipage}{.39\linewidth}
\begin{externalDocument}[
  compiler=pdflatex,force,cleanup={log,aux},verbose]{voss}
\documentclass{standalone}
%StartVisiblePreamble
\usepackage{fontenc}
\usepackage{libertinus}
\usepackage[linguistics]{forest}
\forestapplylibrarydefaults{linguistics, edges}
%StopVisiblePreamble
\begin{document}
\begin{forest}
[VP
  [DP]
  [V’
   [V]
  [DP]
  ]
]
\end{forest}
\end{document}
\end{externalDocument}
\end{minipage}

\subsection{Showing code and output of a Python example}
The png image  is created on the fly with the following arguments of \verb|externalDocument|:

\begin{Verbatim}
\begin{externalDocument}[
  compiler=python3,
  showFilename,
  code,
  ext=py,
  docType=py,
  usefancyvrb,
  grfOptions={width=\linewidth}]{python}
... Python code ...
\end{externalDocument}
\end{Verbatim}

The code which is declared as header and main can be marked by:

\begin{Verbatim}
\hv@extern@exampleType{py}
  {\NumChar StartVisibleMain}
  {\NumChar StopVisibleMain}
  {\NumChar StartVisiblePreamble}
  {\NumChar StopVisiblePreamble}
\end{Verbatim}

\verb|\NumChar| is the default Python comment character \# and needs to be saved with a different
catagory, which is done internally by the package. The complete definition of the code is:


\begin{Verbatim}
\begin{externalDocument}[
  compiler=python3,
  showFilename,
  code,
  ext=py,
  force,
  docType=py,
  usefancyvrb,
  grfOptions={width=\linewidth}]{python}
import os
#StartVisiblePreamble
from PIL import Image
import subprocess
# drawing area (xa < xb and ya < yb)
xa = -0.1716
xb = -0.1433
ya = 1.022
yb = 1.044
maxIt = 1024  # iterations
imgx = 1000   # image size
imgy = 750
image = Image.new("RGB", (imgx, imgy))
#StopVisiblePreamble

#StartVisibleMain
for y in range(imgy):
    cy = y * (yb - ya) / (imgy - 1)  + ya
    for x in range(imgx):
        cx = x * (xb - xa) / (imgx - 1) + xa
        c = complex(cx, cy)
        z = 0
        for i in range(maxIt):
            if abs(z) > 2.0: break 
            z = z * z + c 
        r = i % 4 * 6
        g = i % 8 * 32
        b = i % 16 * 16
        image.putpixel((x, y), b * 65536 + g * 256 + r)
#StopVisibleMain
# now get the filename created by the latex document
imageName = os.path.basename(os.path.splitext(__file__)[0])+".png" # get filename
image.save(imageName, "PNG")
\end{externalDocument}
\end{Verbatim}

And with using this code we get the image as png inserted. The given filename of the external
document is 
internally extended by a consecutive number which isn't known to the Python code. However,
it is no problem in any programming language to get the name of a running file. The  forlast
line in the above code shows how it can be done with Python.


\begin{externalDocument}[
  compiler=python3,
  progpath=/usr/local/bin/,
  force,
  showFilename,
  runs=1,
  code,
  ext=py,
  docType=py,
  usefancyvrb,
  grfOptions={width=\linewidth}]{python}
import os
#StartVisiblePreamble
from PIL import Image
import subprocess
# drawing area (xa < xb and ya < yb)
xa = -0.1716
xb = -0.1433
ya = 1.022
yb = 1.044
maxIt = 1024  # iterations
imgx = 1000   # image size
imgy = 750
image = Image.new("RGB", (imgx, imgy))
#StopVisiblePreamble

#StartVisibleMain
for y in range(imgy):
    cy = y * (yb - ya) / (imgy - 1)  + ya
    for x in range(imgx):
        cx = x * (xb - xa) / (imgx - 1) + xa
        c = complex(cx, cy)
        z = 0
        for i in range(maxIt):
            if abs(z) > 2.0: break 
            z = z * z + c 
        r = i % 4 * 6
        g = i % 8 * 32
        b = i % 16 * 16
        image.putpixel((x, y), b * 65536 + g * 256 + r)
#StopVisibleMain
# now get the filename created by the latex document
imageName = os.path.basename(os.path.splitext(__file__)[0]) # get filename
image.save(imageName+".png", "PNG")
\end{externalDocument}





\begin{externalDocument}[grfOptions={width=0.95\linewidth},
  compiler=xelatex,code,mpwidth=0.6\linewidth,
  crop,cleanup,force,usefancyvrb=false,ext=tex]{voss}
\documentclass{article}
%StartVisiblePreamble
\usepackage{tikz}
\usepackage[hks,pantone,xcolor]{xespotcolor}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\SetPageColorSpace{HKS}
\definecolor{HYellow}{spotcolor}{HKS05N,0.5}
\definecolor{HRed}{spotcolor}{HKS14N,0.5}
\definecolor{HBlue}{spotcolor}{HKS38N,0.5}
\begin{tikzpicture}[scale=0.7,fill opacity=0.7]
 \fill[HYellow]( 90:1.2) circle (2);
 \fill[HRed]   (210:1.2) circle (2);
 \fill[HBlue]  (330:1.2) circle (2);
 \node at ( 90:2)  {Typography};
 \node at ( 210:2) {Design};
 \node at ( 330:2) {Coding};
 \node {\LaTeX};
\end{tikzpicture}
\end{document}
\end{externalDocument}


\section{Setting marker in the source}
The marker for the code ranges which should be listed depend to the used programming language:

\begin{verbatim}
[...]
%StartVisiblePreamble
[... listed preamble code ]
%StopVisiblePreamble
[...]
\begin{document}
[...]
\end{document}
\end{verbatim}

everything between \verb|%StartVisiblePreamble| and \verb|%StopVisiblePreamble| will be listed as
preamble and in case of a \LaTeX\ source everything between
 \verb|\begin{document}| and \verb|\end{document}| as body. The marker must be defined with an own
macro, e.g.:
 
\begin{verbatim}
\hv@extern@exampleType{py}
  {\NumChar StartVisibleMain}
  {\NumChar StopVisibleMain}
  {\NumChar StartVisiblePreamble}
  {\NumChar StopVisiblePreamble}
\end{verbatim}
 
\verb|\NumChar| is the comment character \#, which needs a special handling. This version of \texttt{hvextern}
supports the following programming languages (option \texttt{compiler}):
mpost, tex, latex, luatex, python3, perl, lua, xetex, pdflatex, lualatex, xelatex, and context. The default
is pdflatex. The option \texttt{docType} selects the config file, which must be one of 
context, lua, pl, tex, latex, mp, and py. For Lua it is

\begin{verbatim}
\hv@extern@exampleType{lua}
  {--StartVisibleMain}
  {--StopVisibleMain}
  {--StartVisiblePreamble}
  {--StopVisiblePreamble}
\end{verbatim}


It defines the marker strings for the listed code sequences.  In some cases you have to use multiple times the same value
for different optional arguments, e.g.

\begin{verbatim}
ext=lua, compiler=lua, docType=lua, ... 
\end{verbatim}


\section{Optional arguments}
The deafault setting is always shown in brackets. 
\subsection{Programs and runs}

The \texttt{progpath} should only in some
rare cases needed. In general all used compilers will be found by the system. A given \texttt{progpath}
must be end with a slash, e.g. \texttt{./bin/} %The option \texttt{runsequence} is currently not used.

\begin{verbatim}
\define@key{hv}{progpath}[]{\def\hv@extern@progpath{#1}}
\define@key{hv}{compiler}[pdflatex]{\def\hv@extern@compiler{#1}}
\define@key{hv}{runsequence}[]{\def\hv@extern@runsequence{#1}}
\define@key{hv}{runs}[1]{\setcounter{hv@extern@runs}{#1}}
\end{verbatim}

Instead of the optional arguments
 \texttt{compiler}, \texttt{biber}, and \texttt{xindex} one can define an individual
 command sequence by using the optional argument
 \texttt{runsequence}. It must be comma separated list:
 
\begin{verbatim}
runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex}
\end{verbatim}

\begin{externalDocument}[
  grfOptions={width=0.30\linewidth},
  pages={1,3,5},
  frame,
  runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex},
  showFilename,
  verbose,
  force,
  cleanup={log,aux,toc,bbl,blg},
  code,docType=latex,
  lstOptions={columns=fixed}]{voss}
\documentclass[paper=a5,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
%StartVisiblePreamble
\usepackage[ngerman]{babel}
\usepackage{libertinus,hvindex}
\usepackage{makeidx}\makeindex
\usepackage{biblatex}\addbibresource{biblatex-examples.bib}
%StopVisiblePreamble
\usepackage{blindtext}
\begin{document}
Sort with xindex \verb|-l DE --config AU|
\blindtext
\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} \Index{Oberin} 
\Index{Österreich} \Index{Öresund} 
\Index{Ödem} \Index{Oligarch} \Index{Oder} 
\Index{Goldmann}
\printindex
\nocite{*}\printbibliography
\blindtext
\blinddocument

\end{document}
\end{externalDocument}


The following Java-program creates the Mandelbrot set as png image. The valid setting for 
the environment \texttt{externalDocument} is:

\begin{verbatim}
  compiler=java,ext=java,docType=java,
\end{verbatim}

\begin{externalDocument}[
  verbose,
  compiler=java,ext=java,code,
  force,docType=java,includegraphic,
  usefancyvrb,grfOptions={width=0.9\linewidth}]{java}
import java.awt.Color;
import java.awt.Graphics;
import java.awt.image.BufferedImage;
import java.awt.image.RenderedImage;
import java.io.File;
import javax.imageio.ImageIO;

public class Main {

//StartVisiblePreamble
  public static int iterZahl(final double cx, final double cy, int maxIt, 
                final double radius) {
  // bestimmt Anzahl der Iterationen
    int zaehler = 0;
    double zx = 0.0, zy = 0.0, tmp;
    do {
      tmp = zx*zx - zy*zy + cx;
      zy = 2*zx*zy + cy; zx = tmp;
      zaehler++;
    } while (zx*zx + zy*zy <= radius && zaehler < maxIt);
    return zaehler;
  }
//StopVisiblePreamble
  public static void main(String[] argv) throws Exception {  
    String f_name = new File ((Main.class.getProtectionDomain().getCodeSource().getLocation().toURI()).getPath()).getName();
    String basename = f_name.replaceAll("\\.[^.]*$", "");
    int imageBreite = 540, imageHoehe = 405;
    BufferedImage bufferedImage = new BufferedImage(imageBreite, imageHoehe, BufferedImage.TYPE_INT_RGB);
    Graphics g = bufferedImage.createGraphics();
//StartVisibleMain
    double xa = -2.5, xe = 0.7, ya = -1.2, ye = 1.2; // Ratio 20:15 
    double dx = (xe-xa)/(imageBreite-1), dy = (ye-ya)/(imageHoehe-1);
    double cx, cy; int R, G, B;
    double radius = 10.0;  int maxIt = 1024;
    cx = xa;
    for (int sp = 0; sp < imageBreite; sp++) {
      cy = ye; // von oben nach unten
      for (int ze = 0; ze < imageHoehe; ze++) {
        int zIter = iterZahl(cx, cy, maxIt, radius);
        if (zIter == maxIt) {
          g.setColor(Color.WHITE);
          g.drawLine(sp, ze, sp, ze);
        } else { 
          R = zIter % 4 * 6 ; G = zIter % 8 * 32; B = zIter % 16 * 16;
          g.setColor(new Color(R,G,B));
          g.drawLine(sp, ze, sp, ze);
        }
        cy = cy - dy;
      } // for ze
      cx = cx + dx;
    } // for sp
//StopVisibleMain
    g.dispose();
    RenderedImage rendImage = bufferedImage;

    File file = new File(basename+".png");
    ImageIO.write(rendImage, "png", file);
  }
}
\end{externalDocument}





\subsection{Grafik options}
\begin{verbatim}
\define@key{hv}{grfOptions}[]{\def\hv@extern@grfOptions{#1}}
\end{verbatim}

The option is passed to \verb|\includegraphics|, e.g. \verb|angle=90,width=\linewidth| for
the follwing example.

\begin{externalDocument}[grfOptions={angle=90,width=\linewidth},
  compiler=xelatex,code,mpwidth=0.6\linewidth,
  crop,cleanup,force]{voss}
\documentclass{article}
%StartVisiblePreamble
\usepackage{tikz}
\usepackage[hks,pantone,xcolor]{xespotcolor}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\SetPageColorSpace{HKS}
\definecolor{HYellow}{spotcolor}{HKS05N,0.5}
\definecolor{HRed}{spotcolor}{HKS14N,0.5}
\definecolor{HBlue}{spotcolor}{HKS38N,0.5}
\begin{tikzpicture}[scale=0.7,fill opacity=0.7]
 \fill[HYellow]   ( 90:1.2) circle (2);
 \fill[HRed] (210:1.2) circle (2);
 \fill[HBlue]  (330:1.2) circle (2);
 \node at ( 90:2) {Typography};
 \node at ( 210:2) {Design};
 \node at ( 330:2) {Coding};
 \node {\LaTeX};
\end{tikzpicture}
\end{document}
\end{externalDocument}


\subsection{Listings options}

\begin{verbatim}
\define@key{hv}{lstOptions}[]{\def\hv@extern@lstOptions{#1}}
\end{verbatim}

The option is passed either to \verb|\lstinputlisting|, or, if \texttt{usefancyvrb} is active, 
to \verb|\VerbatimInput|. The following example uses 

\begin{verbatim}
  lstOptions={basicstyle=\sffamily\itshape\scriptsize},
\end{verbatim}



\begin{externalDocument}[
  grfOptions={width=\linewidth},
  lstOptions={basicstyle=\sffamily\itshape\scriptsize},
  compiler=lualatex,
  code,
  mpwidth=0.6\linewidth,
  crop,
  cleanup,
  force,
  docType=latex]{voss}
\RequirePackage{pdfmanagement-testphase}
\DeclareDocumentMetadata{}
\documentclass{article}
%StartVisiblePreamble
\usepackage{pst-calendar} 
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\psscalebox{0.3}{%
  \psCalDodecaeder[Year=2022,style=april]%
}
\end{document}
\end{externalDocument}

\subsection{Background color}

There are different colors for the preamble and body listing: the backgrund and frame color.
\begin{verbatim}
\define@key{hv}{BGpreamble}[black12]{\def\hv@extern@BGpreamble{#1}}
\define@key{hv}{BGbody}[black8]{\def\hv@extern@BGbody{#1}}
\define@key{hv}{BOpreamble}[black12]{\def\hv@extern@BOpreamble{#1}}
\define@key{hv}{BObody}[black8]{\def\hv@extern@BObody{#1}}
\end{verbatim}

The options are passed to \verb|tcolorbox| and preset to \texttt{black12} and \texttt{black!8}.
The color of the frame is set to the same values, hence not seen. The following example uses

\begin{verbatim}
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
\end{verbatim}

%\clearpage

\begin{externalDocument}[
  grfOptions={width=\linewidth},
  lstOptions={fontsize=\small,fontfamily=tt},
  compiler=lualatex,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  mpwidth=0.6\linewidth,
  crop,
  cleanup,
  force,
  usefancyvrb,
  docType=latex]{voss}
\RequirePackage{pdfmanagement-testphase}
\DeclareDocumentMetadata{}
\documentclass{article}
%StartVisiblePreamble
\usepackage{pst-calendar} 
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\psscalebox{0.3}{%
  \psCalDodecaeder[Year=2022,style=may]%
}
\end{document}
\end{externalDocument}

\subsection{Type of the source code}

The current version of \texttt{hvextern} supports code written as
\MP, \plainTeX, \LaTeX, \ConTeXt, and Python. Every type has its own keywords for the 
linerange which should be printed for the preamble and
the body. For example the \texttt{latex} config is:

\begin{verbatim}
\hv@extern@exampleType{latex}%                   for _all_LaTeX engines   
  {\string\begin\string{document\string}}%       
  {\string\end\string{document\string}}%         
  {\perCent StartVisiblePreamble}%               
  {\perCent StopVisiblePreamble}%                

% only for the sequence latex->dvips->ps2pdf
\def\hv@extern@runLATEX#1#2#3#4{% path compiler file extension  
  \ifhv@extern@verbose \typeout{>>>> running #1#2 #3#4}\fi
  \ShellEscape{#1#2\space #3#4}%
  \ifhv@extern@verbose \typeout{>>>> running #1dvips #3}\fi
  \ShellEscape{#1dvips\space #3.dvi}%
  \ifhv@extern@verbose \typeout{>>>> running ps2pdf #3.ps}\fi
  \ShellEscape{#1ps2pdf\space -dAutoRotatePages=/None\space -dALLOWPSTRANSPARENCY\space  #3.ps}%
}
\end{verbatim}

If a source needs more than running the defined compiler, it must be defined by a macro
\begin{verbatim}
\def\hv@extern@run<NAME>#1#2#3#4{% path compiler file extension
...}
\end{verbatim}

The type of the source code can be different to the compiler, e.g. source \texttt{latex},
but compiler \texttt{lualatex}.


\subsection{Output as floating object with caption and label}

By default the images are not inserted as a float. This can be changed by
the keyword \texttt{float}, a caption and a label are optional. The float type is always
\texttt{figure}.

\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{float}[true]{}
\define@key{hv}{caption}[]{\def\hv@extern@caption{#1}}
\define@key{hv}{label}[]{\def\hv@extern@label{#1}}
\end{verbatim}

The image Figure~\ref{img:cox} shows an example for a floting object.

\begin{externalDocument}[
  grfOptions={width=\linewidth},
  lstOptions={fontsize=\small,fontfamily=tt},
%  lstOptions={basicstyle=\small\ttfamily},
  compiler=lualatex,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
%  mpwidth=0.6\linewidth,
  crop,
  cleanup,
  force,
  usefancyvrb,
  float,
  caption={An example for Coxeter images},
  label=img:cox,
  docType=latex]{voss}
\RequirePackage{pdfmanagement-testphase}
\DeclareDocumentMetadata{}
\documentclass{article}
%StartVisiblePreamble
\usepackage{pst-coxeterp} 
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\begin{pspicture}(-1,-1)(1,1)\Simplex[dimension=2]\end{pspicture}
%
\begin{pspicture}(-1,-1)(1,1)\Simplex[dimension=3]\end{pspicture}
%
\begin{pspicture}(-1,-1)(1,1)\Simplex[dimension=5]\end{pspicture}
%
\begin{pspicture}(-1,-1)(1,1)\Simplex[dimension=7]\end{pspicture}
%
% ------------------------------------
% Only some text to show the pagebreak
% ------------------------------------
\end{document}
\end{externalDocument}




\subsection{Output more than one page}
The pages which should be printed can be defined by


\begin{verbatim}
\define@key{hv}{pages}[1]{\def\hv@extern@pages{#1}}
\define@boolkey{hv}[hv@extern@]{frame}[true]{}
\end{verbatim}

With \texttt{frame} the pages can be framed (internally by \verb|\fbox|).
It is leaved to the user to choose the correct image width for the pages.
The following example uses:

\begin{verbatim}
  pages={1,2,3},
  grfOptions={width=0.3\linewidth},
  compiler=lualatex, runs=2,  % for the TOC
  frame,
\end{verbatim}

\begin{externalDocument}[
  pages={1,2,3},
  grfOptions={width=0.3\linewidth},
%  lstOptions={fontsize=\small,fontfamily=tt},
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
%  mpwidth=0.6\linewidth,
%  crop,
  cleanup,
  force,
  frame,
%  usefancyvrb,
%  float,
%  caption={An example for Coxeter images},
%  label=img:cox,
  docType=latex]{voss}
\documentclass{article}
%StartVisiblePreamble
\usepackage[american]{babel}
\usepackage{libertinus} 
\usepackage{blindtext} 
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\title{A multipage example}
\author{Erasmus von Rotterdam}
\maketitle
\tableofcontents
\blinddocument
\end{document}
\end{externalDocument}



\subsection{Cropping the PDF}
Instead of using the documentclass \texttt{standalone}, which already crops the created PDF,
one can use the optional argument \texttt{crop}.

\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{crop}[true]{}
\define@key{hv}{cropmargin}[2]{\def\hv@extern@cropmargin{#1 }}% length in pt
\end{verbatim}


It is also possible to crop a document with more than one page. In this case the
beginning and end of the pages should be on the same height. Otherwise the pages
will have different heights after cropping (see next image). The follwoing example was created with

\begin{verbatim}
  pages={1,2,3},
  grfOptions={width=0.3\linewidth},
  compiler=lualatex, runs=2,  % for the TOC
  frame,
  crop, cropmargin=5,%    5pt margin
\end{verbatim}

\begin{externalDocument}[
  pages={1,2,3},
  grfOptions={width=0.3\linewidth},
%  lstOptions={fontsize=\small,fontfamily=tt},
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
%  mpwidth=0.6\linewidth,
  crop, cropmargin=5,
  cleanup,
  force,
  frame,
%  usefancyvrb,
%  float,
%  caption={An example for Coxeter images},
%  label=img:cox,
  docType=latex]{voss}
\documentclass{article}
%StartVisiblePreamble
\usepackage[american]{babel}
\usepackage{libertinus} 
\usepackage{blindtext} 
\pagestyle{headings}
%StopVisiblePreamble
\begin{document}
\title{A multipage example}
\author{Erasmus von Rotterdam}
\maketitle
\tableofcontents
\Blinddocument
\end{document}
\end{externalDocument}


\subsection{Code and output side by side}
By default the code and the output is on top of each other. With setting the
width of a minipage with \texttt{mpwidth} greater than 0\,pt  the output will be side by side.

\begin{verbatim}
\define@key{hv}{mpwidth}[0pt]{\setlength\hv@extern@mpwidth{#1}}
\end{verbatim}

\texttt{mpwidth} is  the width of the code. The rest of the line, minus 1em for the space between
the minipages, will be the possible
width for the output and will be calculated automatically. The two minipages are
aligned by its top.



\subsection{Align of the output}

%\begin{verbatim}
%\define@key{hv}{align}[\centering]{\def\hv@extern@align{#1}}
%\end{verbatim}

\subsubsection{the default}

\begin{verbatim}
  align=\centering,
\end{verbatim}

\begin{externalDocument}[
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  crop,
  cleanup,
  force,
  docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
\begin{document}
\rule{0.5\linewidth}{5mm}
\end{document}
\end{externalDocument}

\subsubsection{Left aligned}

\begin{verbatim}
  align=\raggedright,
\end{verbatim}

\begin{externalDocument}[
  align=\raggedright,
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  crop,
  cleanup,
  force,
  docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
\begin{document}
\rule{0.5\linewidth}{5mm}
\end{document}
\end{externalDocument}

\subsubsection{Right aligned}

\begin{verbatim}
  align=\raggedleft,
\end{verbatim}


\begin{externalDocument}[
  align=\raggedleft,
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  crop,
  cleanup,
  force,
  docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
\begin{document}
\rule{0.5\linewidth}{5mm}
\end{document}
\end{externalDocument}


%Now the same for side by side output.

\subsubsection{the default -- side by side}
\begin{verbatim}
  align=\centering,  mpwidth=0.5\linewidth,
\end{verbatim}

\begin{externalDocument}[
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  crop,
  cleanup,
  force,
  mpwidth=0.5\linewidth,
  docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
\begin{document}
\rule{0.25\linewidth}{5mm}
\end{document}
\end{externalDocument}

\subsubsection{Left aligned -- side by side}

\begin{verbatim}
  align=\raggedright,   mpwidth=0.5\linewidth,
\end{verbatim}

\begin{externalDocument}[
  align=\raggedright,
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  crop,
  cleanup,
  force,
  mpwidth=0.5\linewidth,
  docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
\begin{document}
\rule{0.25\linewidth}{5mm}
\end{document}
\end{externalDocument}

\subsubsection{Right aligned -- side by side}

\begin{verbatim}
  align=\raggedleft,  mpwidth=0.5\linewidth,
\end{verbatim}


\begin{externalDocument}[
  align=\raggedleft,
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  crop,
  cleanup,
  force,
  mpwidth=0.5\linewidth,
  docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
\begin{document}
\rule{0.25\linewidth}{5mm}
\end{document}
\end{externalDocument}

\subsection{Inline images}
By default code and image are own paragraphs. With the optional argument \texttt{inline} the created
image can be part of the current line. This may make sense, if you need characters which are
not part of your current font.

\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{inline}[true]{\hv@extern@codefalse}
\end{verbatim}

With \texttt{inline=true} the optional argument \texttt{code} is automatically set to false. The
next  Chinese characters 
\begin{externalDocument}[
  compiler=xelatex, inline, runs=2, grfOptions={height=8pt},
  crop, cropmargin=0, cleanup, force, docType=latex]{voss}%
\documentclass{ctexart}
\pagestyle{empty}
\begin{document}
美好的一天
\end{document}
\end{externalDocument}
are inserted as inline image without showing the code. The complete code looks like:



\begin{Verbatim}
With \texttt{inline=true} the optional argument \texttt{code} is automatically set to false. The
next  Chinese characters 
\begin{externalDocument}[
  compiler=xelatex, inline, runs=2, grfOptions={height=8pt},
  crop, cropmargin=0, cleanup, force, docType=latex]{voss}
\documentclass{ctexart}
\pagestyle{empty}
\begin{document}
美好的一天
\end{document}
\end{externalDocument}
are inserted as inline image without showing the code. The complete code looks like:
\end{Verbatim}


\subsection{Input text instead of an image}
By default the created pdf which can be, of course, only test, wil be insert by \verb|\incudegraphics|.
If you have only text as output and dont want to create a pdf you can insert this kind of
output as verbatim text by setting \verb|includegraphic=false|. 

\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{includegraphic}[true]{}
\end{verbatim}


The textfile must have the same main filename with the extension
\verb|.txt|. As already mentioned, in every programming language you can get the current
used filename from within the code itself. The following Perl example which calculates the
Kaprekar constants uses 

\begin{verbatim}
my $filename = $0;             # the current filename
$filename =~ s/\.pl//;         # without extension .pl
$filename = "${filename}.txt"; # for the output
\end{verbatim}

Only for some completeness: a Kaprekar constant is a number $A$ with $\max(A)-\min(A)=A$. $\max$ and $\min$ are the
sorted digits of the number $A$: $495=954-459$.


\begin{externalDocument}[
  compiler=perl, force, docType=pl, ext=pl, includegraphic=false,
  code, mpwidth=0.6\linewidth]{voss}
#!/usr/bin/perl
#
# Herbert Voss 2005-05-31
#
#StartVisiblePreamble
my $zahl = 1;
my $anfang = 1;
my $ende = 9;
#StopVisiblePreamble
my $filename = $0;             # the current filename
$filename =~ s/\.pl//;         # without extension .pl
$filename = "${filename}.txt"; # for the output
my $found = 0;
open(my $fh, '>', $filename);

#StartVisibleMain
print $fh "Finding Kaprekarconstants ...\n";
while ($zahl < 8) {
  print $fh "${zahl}-stellig: ";
  foreach ($anfang...$ende) { # for every row $_
    @Zeichen = split(//,$_);
    $Min = join("",sort(@Zeichen));
    $Max = reverse($Min);
    $Dif=$Max-$Min;
    if($_ eq $Dif) {
      $found = 1;
      print $fh $_,",  ";
    }
  }
  if (!$found) { print $fh "---\n"; }
  else         { print $fh "\n";    }
  $found = false;
  $zahl = $zahl+1;
  $anfang = $anfang*10;
  $ende = $ende*10;
}
#StopVisibleMain
close $fh;
\end{externalDocument}


%$
Another example with running Lua to calculate and print the Pascal's triangle. The internal filename
is available with

\begin{verbatim}
local filename = arg[0]
local shortFN = str:match("(.+)%..+")   -- delete extension
outFile = io.open(shortFN..".txt","w+") -- open external file
\end{verbatim}


\begin{externalDocument}[
  compiler=lua, force, docType=lua, ext=lua, includegraphic=false, code, usefancyvrb=false]{voss}
#!/usr/bin/env lua
local filename = arg[0]
local shortFN = filename:match("(.+)%..+")
outFile = io.open(shortFN..".txt","w+")

--StartVisiblePreamble
function nextrow(t)
  local ret = {}
  t[0], t[#t+1] = 0, 0
  for i = 1, #t do ret[i] = t[i-1] + t[i] end
  return ret
end

function triangle(n)
  t = {1}
  for i = 1, n do
    m = (n - i)
    for j = 1,m do outFile:write("    ") end
    for k = 1,i do outFile:write(string.format("%8s",t[k])) end
    outFile:write("\n")
    t = nextrow(t)
  end
end
--StopVisiblePreamble

--StartVisibleMain
triangle(10)
--StopVisibleMain
outFile:close()
\end{externalDocument}






\subsection{Running additional external programs}

For a \LaTeX\ additional programs for bibliography, index, a.s.o. maybe needed.

\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{biber}[true]{}
\define@boolkey{hv}[hv@extern@]{xindex}[true]{}
\define@key{hv}{xindexOptions}[]{\def\hv@extern@xindexOptions{#1}}
\define@key{hv}{runsequence}[]{\def\hv@extern@runsequence{#1}}
\end{verbatim}

The \texttt{biber} run needs no additional options, but for \texttt{xindex} it maybe useful.
The following examples uses

\begin{verbatim}
\begin{externalDocument}[
  compiler=lualatex, runs=2, pages=2,crop,
  xindex, xindexOptions={-l DE --config AU},
  mpwidth=0.6\linewidth, usefancyvrb=false,
  docType=latex,
  ...
]{voss}
\end{verbatim}




\begin{externalDocument}[
  grfOptions={scale=0.75},
  compiler=lualatex, runs=2,
  BGpreamble=red!10, BOpreamble=red, 
  BGbody=blue!8, BObody=blue,
  code,
  pages=2,
  crop,
  cleanup,
  force,
  xindex,
  xindexOptions={-l DE --config AU},
  mpwidth=0.6\linewidth,
  usefancyvrb=false,
  docType=latex]{voss}
\documentclass[paper=a6,DIV=18,parskip=half-]{screxa}
\pagestyle{empty}
\usepackage{libertinus}
\setmonofont{DejaVu Sans Mono}[Scale=MatchLowercase,FakeStretch=0.9]
\usepackage[ngerman]{babel}
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\usepackage{hvindex}
%StopVisiblePreamble
\begin{document}
Sort with xindex \verb|-l DE --config AU|
\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} \Index{Oberin} 
\Index{Österreich} \Index{Öresund} 
\Index{Ödem} \Index{Oligarch} \Index{Oder} 
\Index{Ostern} \Index{Ober} \Index{Oberin} 
\Index{Obstler} \Index{Öl} \Index{ölen} 
\Index{Oder|seealso{Fluss}} \Index{Göbel}
\Index{oder} \index{Fluss!Oder}
\Index{Goethe} \Index{Göthe} \Index{Götz}
\Index{Goldmann}
\printindex
\end{document}
\end{externalDocument}


Instad of using the options \texttt{compiler}, \texttt{biber}, and \texttt{xindex} 
one can also use only the optional argument \texttt{runsequence} to define an individuell
sequence of commands, e.g.:
\begin{verbatim}
runsequence={lualatex,biber,{xindex -l de -c AU},lualatex,lualatex}
\end{verbatim}

\begin{externalDocument}[
  grfOptions={width=0.30\linewidth},
  pages={1,3,5},
  frame,
  runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex},
  showFilename,
  verbose,
  force,
  cleanup={log,aux,toc,bbl,blg},
  code,docType=latex,
  lstOptions={columns=fixed}]{voss}
\documentclass[paper=a5,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
%StartVisiblePreamble
\usepackage[ngerman]{babel}
\usepackage{libertinus,hvindex}
\usepackage{makeidx}\makeindex
\usepackage{biblatex}\addbibresource{biblatex-examples.bib}
%StopVisiblePreamble
\usepackage{blindtext}
\begin{document}
Sort with xindex \verb|-l DE --config AU|
\blindtext
\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} \Index{Oberin} 
\Index{Österreich} \Index{Öresund} 
\Index{Ödem} \Index{Oligarch} \Index{Oder} 
\Index{Goldmann}
\printindex
\nocite{*}\printbibliography
\blindtext
\blinddocument

\end{document}
\end{externalDocument}






\subsection{Using \texttt{listings}}
The default is using \verb|\lstinputlisting| for the printed code sequences.

\begin{externalDocument}[
  grfOptions={width=0.45\linewidth},
  pages={1,3},
  frame,compiler=pdflatex,
  showFilename,
%  crop,
  force,runs=2,code,docType=latex,
  frame,
  lstOptions={columns=fixed}]{Schubert-A}
%StartVisiblePreamble
\documentclass[chapterprefix=on,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
\DeclareNewSectionCommand[
  style=section,
  level=4,
  beforeskip=-3.25ex plus -1ex minus -.2ex,
  afterskip=1.5ex plus .2ex,
  font=\normalsize,
  indent=0pt,
  counterwithin=subsubsection
]{subsubsubsection}
\RedeclareSectionCommand[
  level=5,
  toclevel=5,
  tocindent=13em,
  tocnumwidth=5.9em,
  counterwithin=subsubsubsection
]{paragraph}
\RedeclareSectionCommand[
  level=6,
  toclevel=6,
  tocindent=15em,
  tocnumwidth=6.8em
]{subparagraph}
\setcounter{secnumdepth}{\subsubsubsectionnumdepth}
\setcounter{tocdepth}{\subsubsubsectiontocdepth}
%StopVisiblePreamble
\usepackage[ngerman]{babel}
\usepackage{libertinus}
\usepackage{blindtext}
\begin{document}
\tableofcontents
\chapter{Einführung}
\section{Ein Abschnitt}
\subsection{Ein Unterabschnitt}
\subsubsection{Ein Unter-Unterabschnitt}
\subsubsubsection{Ein Unter-Unter-Unterabschnitt}
\paragraph{Der normale Paragraph}
\blindtext
\subparagraph{Der normale Unterparagraph}
\blindtext
\blinddocument
\end{document}
\end{externalDocument}



It also possible to use \verb|\VerbatimInput| from package \texttt{fancyvrb}. In general
it makes no difference using the optional argument \texttt{usefancyvrb} or not.


\begin{externalDocument}[
  grfOptions={width=0.45\linewidth},
  pages={1,3},
  frame,compiler=pdflatex,
  showFilename,
%  crop,
  force,runs=2,code,docType=latex,
  frame,usefancyvrb]{Schubert-A}
%StartVisiblePreamble
\documentclass[chapterprefix=on,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
\DeclareNewSectionCommand[
  style=section,
  level=4,
  beforeskip=-3.25ex plus -1ex minus -.2ex,
  afterskip=1.5ex plus .2ex,
  font=\normalsize,
  indent=0pt,
  counterwithin=subsubsection
]{subsubsubsection}
\RedeclareSectionCommand[
  level=5,
  toclevel=5,
  tocindent=13em,
  tocnumwidth=5.9em,
  counterwithin=subsubsubsection
]{paragraph}
\RedeclareSectionCommand[
  level=6,
  toclevel=6,
  tocindent=15em,
  tocnumwidth=6.8em
]{subparagraph}
\setcounter{secnumdepth}{\subsubsubsectionnumdepth}
\setcounter{tocdepth}{\subsubsubsectiontocdepth}
%StopVisiblePreamble
\usepackage[ngerman]{babel}
\usepackage{libertinus}
\usepackage{blindtext}
\begin{document}
\tableofcontents
\chapter{Einführung}
\section{Ein Abschnitt}
\subsection{Ein Unterabschnitt}
\subsubsection{Ein Unter-Unterabschnitt}
\subsubsubsection{Ein Unter-Unter-Unterabschnitt}
\paragraph{Der normale Paragraph}
\blindtext
\subparagraph{Der normale Unterparagraph}
\blindtext
\blinddocument
\end{document}
\end{externalDocument}



\section{Supported engines}
\subsection{\MP\ example}

\begin{externalDocument}[
%  grfOptions={width=0.45\linewidth},
%  pages={1,3},
  frame,
  verbose=false,
  compiler=mpost,
  showFilename,
%  crop,
  force,
  cleanup,
  code,
  docType=mp,
  ext=mp,]{voss}
%StartVisiblePreamble
defaultfont:="ptmr8r";
warningcheck:=0;
%StopVisiblePreamble
beginfig(1)
draw fullcircle shifted (0.5,0.6) xscaled 8cm yscaled 3.5cm 
  withpen pencircle scaled 5bp withcolor red;
special( " /Times-Roman findfont 150 scalefont setfont " &
  " 0 10 moveto (MPost) false charpath clip stroke gsave 150 70 translate " &
  " 2 4 600 {dup 0 moveto 0 exch 0 exch 0 360 arc stroke} for grestore ");
endfig;
end;
\end{externalDocument}




\subsection{plain\TeX\ example}

\begin{externalDocument}[
  grfOptions={width=0.5\linewidth},
%  pages={1,3},
  frame,
  verbose=false,
  compiler=tex,
  showFilename,
%  crop,
  force,
  code,
  docType=tex,
  ext=tex,]{voss}
\magnification=\magstep1
\baselineskip=12pt
\hsize=6.3truein
\vsize=8.7truein
\font\footsc=cmcsc10 at 8truept
\font\footbf=cmbx10 at 8truept
\font\footrm=cmr10 at 10truept
%StartVisiblePreamble
\footline={\footsc the electronic journal of combinatorics
   {\footbf 16} (2009), \#R00\hfil\footrm\folio}
%StopVisiblePreamble
%StartBody
\font\bigrm=cmr12 at 14pt
\centerline{\bigrm An elementary proof of the reconstruction conjecture}

\bigskip\bigskip
\centerline{D. Remifa\footnote*{Thanks to the editors of this journal!}}
\smallskip
\centerline{Department of Inconsequential Studies}
\centerline{Solatido College, North Kentucky, USA}
\centerline{\tt remifa@dis.solatido.edu}
\bigskip
\centerline{\footrm 
Submitted: Jan 1, 2009; Accepted: Jan 2, 2009; Published: Jan 3, 2009}
\centerline{\footrm Mathematics Subject Classifications: 05C88, 05C89}
\bigskip\bigskip
\centerline{\bf Abstract}
\smallskip
{\narrower\noindent
The reconstruction conjecture states that the multiset of unlabeled
vertex-deleted subgraphs of a graph determines the graph, provided it
has at least 3 vertices.  A version of the problem was first stated
by Stanis\l aw Ulam.  In this paper, we show that the conjecture can
be proved by elementary methods.  It is only necessary to integrate
the Lenkle potential of the Broglington manifold over the quantum
supervacillatory measure in order to reduce the set of possible
counterexamples to a small number (less than a trillion).  A simple
computer program that implements Pipletti's classification theorem
for torsion-free Aramaic groups with simplectic socles can then
finish the remaining cases.}

\bigskip
\beginsection 1. Introduction.

This is the start of the introduction.
\bye
\end{externalDocument}



\subsection{\LaTeX\ example}

\begin{externalDocument}[
  grfOptions={width=0.5\linewidth},
%  pages={1,3},
%  frame,
  verbose=false,
  compiler=lualatex,
  showFilename,
  crop,
  force,
  code,
  docType=latex,
  ext=tex,]{voss}
\documentclass{report}
\pagestyle{empty}
%StartVisiblePreamble
\usepackage{fontenc}\usepackage{libertinus}
\usepackage{pst-all}
%StopVisiblePreamble
\begin{document}
\psset{unit=0.8cm}
\begin{pspicture}(-9,-15)(9,2)
\psaxes(0,0)(-9,-15)(9,2)
\psplot[algebraic,plotstyle=curve,curvature=1 1 0, 
  linewidth=2pt,linecolor=red]{-8}{8}{
  1 - 3876218985722260225*x^2/10892114744073986176 
    + 14975974793271450625*x^4/174273835905183778816 
    - 317095420958296875*x^6/26811359370028273664 
    + 194412970920703125*x^8/214490874960226189312 
    - 2090988251953125*x^10/53622718740056547328 
    + 99480224609375*x^12/107245437480113094656 
    - 7879638671875*x^14/697095343620735115264 
    + 152587890625*x^16/2788381374482940461056}
\end{pspicture}
\end{document}
\end{externalDocument}


\subsection{\ConTeXt\ example}


\begin{externalDocument}[
  grfOptions={width=0.3\linewidth},
  pages={1,2,3},
  frame,
  verbose=false,
  compiler=context,
  showFilename,
  runs=2,
  force,
  code,
  docType=context,
  ext=tex,]{voss}
%StartVisiblePreamble
\definehead
  [myhead]
  [section]
\setuphead
  [myhead]
  [numberstyle=bold,
   textstyle=bold,
   before=\hairline\blank,
   after=\nowhitespace\hairline]
%StopVisiblePreamble
\starttext
\startstandardmakeup
\midaligned{From Hasselt to America}
\midaligned{by}
\midaligned{J. Jonker and C. van Marle}
\stopstandardmakeup
\placecombinedlist[content]
\chapter{Introduction}
\input knuth \input knuth 
\chapter[rensselaer]{The Rensselaer family}
\section{The first born}
\input knuth 
\section{The early years}
... in those days Hasselt was ...
\section{Living and workin in America}
\input knuth
\chapter[lansing]{The Lansing family}
... the Lansing family was also ...
\chapter[cuyler]{The Cuyler family}
... much later Tydeman Cuyler ...
\myhead[headlines]{And the end}
foo
\stoptext
\end{externalDocument}


\section{Other options}

\begin{description}
\item[\texttt{force=false}] can speed up the comiling time for the document. If a created image/output
already exists, there is no need to create it with the next run again and again.
\item[\texttt{cleanup}] the auxiliary files of a \LaTeX-run are deleted, preset to \texttt{.aux}, \texttt{.log}.
   It must be a comma seperated list of the extensions of the main file, s.g. \texttt{cleanup=\{aux,log\}}.
\item[\texttt{copyToExampleDir}] name of a directory for the examples, must first be created by the user himself
\item[\texttt{ExamplesDir}] move all examples into a directory
\item[\texttt{eps}] create an eps from the pdf (historical)
\end{description}





\end{document}