summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hvextern/doc/hvextern.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/hvextern/doc/hvextern.tex')
-rw-r--r--macros/latex/contrib/hvextern/doc/hvextern.tex1403
1 files changed, 1403 insertions, 0 deletions
diff --git a/macros/latex/contrib/hvextern/doc/hvextern.tex b/macros/latex/contrib/hvextern/doc/hvextern.tex
new file mode 100644
index 0000000000..8acd4e841c
--- /dev/null
+++ b/macros/latex/contrib/hvextern/doc/hvextern.tex
@@ -0,0 +1,1403 @@
+\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}
+\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 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..
+
+\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]{Roemer1}
+\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]{Roemer1}
+\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}
+\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]{Senger3}
+\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 in an own
+ config file, e.g. \texttt{hv-extern-py.cfg}:
+
+\begin{verbatim}
+\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}
+\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}
+
+\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]{Senger3}
+\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 config file which
+defines the keywords for the linerange which should be printed for the preamble and
+the body. For example the \texttt{latex} config file \texttt{hvextern-latex,cfg}:
+
+\begin{verbatim}
+\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}}
+\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}
+
+
+
+
+
+
+
+\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,
+ 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}
+%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=1pt,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}
+
+