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.tex226
1 files changed, 140 insertions, 86 deletions
diff --git a/macros/latex/contrib/hvextern/doc/hvextern.tex b/macros/latex/contrib/hvextern/doc/hvextern.tex
index ecc62a121f..a170457a7d 100644
--- a/macros/latex/contrib/hvextern/doc/hvextern.tex
+++ b/macros/latex/contrib/hvextern/doc/hvextern.tex
@@ -23,12 +23,12 @@
\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}}
+from within a main\newline \LaTeX\ document~--v. \hvexternFileversion}
+\author{Herbert Voß \url{herbert@dante.de}}
\maketitle
\tableofcontents
-\newpage
+%\newpage
\setkeys{hv}{moveToExampleDir,ExampleDir=Examples,showFilename,verbose}
\section{Syntax}
@@ -37,6 +37,9 @@ from within a main \LaTeX\ document~--v. \hvexternFileversion}
\usepackage{hvextern}
\end{verbatim}
+\addtocontents{toc}{\protect\enlargethispage{2ex}}
+
+
\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
@@ -144,7 +147,6 @@ The \ttIndex{png} image is created on the fly with the following arguments of \
\begin{Verbatim}
\begin{externalDocument}[
compiler=python3,
- showFilename,
code,
ext=py,
docType=py,
@@ -171,7 +173,6 @@ catagory, which is done internally by the package. The complete definition of th
\begin{Verbatim}
\begin{externalDocument}[
compiler=python3,
- showFilename,
code,
ext=py,
force=false,
@@ -225,7 +226,6 @@ line in the above code shows how it can be done with Python.
compiler=python3,
progpath=/usr/local/bin/,
force=false,
- showFilename,
runs=1,
code,
ext=py,
@@ -269,11 +269,9 @@ image.save(imageName+".png", "PNG")
-
-
\begin{externalDocument}[grfOptions={width=0.95\linewidth},
compiler=xelatex,code,mpwidth=0.6\linewidth,
- crop,cleanup,force=false,usefancyvrb=false,ext=tex]{voss}
+ crop,cleanup,force=false,usefancyvrb=false,ext=tex,showFilename=false]{voss}
\documentclass{article}
%StartVisiblePreamble
\usepackage{tikz}
@@ -298,6 +296,7 @@ image.save(imageName+".png", "PNG")
\end{externalDocument}
+
\section{Setting marker in the source}
The marker for the code ranges which should be listed depend to the used programming language:
@@ -379,9 +378,10 @@ runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex}
\begin{externalDocument}[
grfOptions={width=0.30\linewidth},
pages={1,3,5},
+ pagesep=2pt,
frame,
runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex},
- showFilename,
+ ,
verbose,
force=false,
cleanup={log,aux,toc,bbl,blg},
@@ -412,6 +412,9 @@ Sort with xindex \verb|-l DE --config AU|
\end{externalDocument}
+
+
+
The following \Java-program creates the Mandelbrot set as png image. The valid setting for
the environment \Lenv{externalDocument} is:
@@ -489,6 +492,8 @@ public class Main {
%$
+
+
\subsection{Grafik options}
\begin{verbatim}
\define@key{hv}{grfOptions}[]{\def\hv@extern@grfOptions{#1}}
@@ -524,6 +529,10 @@ the follwing example.
\end{externalDocument}
+
+\newpage%%%%%%%%%%%
+
+
\subsection{Listings options}
\begin{verbatim}
@@ -563,6 +572,8 @@ to \Lcs{VerbatimInput}. The following example uses
\end{document}
\end{externalDocument}
+
+
\subsection{Background color}
There are different colors for the preamble and body listing: the backgrund and frame color.
@@ -644,78 +655,24 @@ If a source needs more than running the defined compiler, it must be defined by
The type of the source code can be different to the compiler, e.g. source \Lkeyval{latex},
but compiler \Lkeyval{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 \Lkeyword{float}, a caption and a label are optional. The float type is always
-\Lenv{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=false,
- 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@key{hv}{pagesep}[1em]{\hv@extern@pagesep=#1}
\define@boolkey{hv}[hv@extern@]{frame}[true]{}
\end{verbatim}
With \Lkeyword{frame} the pages can be framed (internally by \Lcs{fbox}).
It is leaved to the user to choose the correct image width for the pages.
+The separation between the pages is defined by the length \Lkeyword{pagesep}.
The following example uses:
\begin{verbatim}
pages={1,2,3},
+ pagesep=2pt,
grfOptions={width=0.3\linewidth},
compiler=lualatex, runs=2, % for the TOC
frame,
@@ -723,6 +680,7 @@ The following example uses:
\begin{externalDocument}[
pages={1,2,3},
+ pagesep=2pt,
grfOptions={width=0.3\linewidth},
% lstOptions={fontsize=\small,fontfamily=tt},
compiler=lualatex, runs=2,
@@ -732,7 +690,7 @@ The following example uses:
% mpwidth=0.6\linewidth,
% crop,
cleanup,
- force=false,
+ force=true,
frame,
% usefancyvrb,
% float,
@@ -757,6 +715,61 @@ The following example uses:
+
+\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 \Lkeyword{float}, a caption and a label are optional. The float type is always
+\Lenv{figure}.
+
+\begin{verbatim}
+\define@boolkey{hv}[hv@extern@]{float}[true]{}
+\define@key{hv}{floatsetting}[]{\def\hv@extern@floatsetting{#1}}
+\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 floating object, which uses the floatsetting \verb|!htb|,
+which is the default. Using a caption and a label are optional.
+
+\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=true,
+ usefancyvrb,
+ float,
+ floatsetting=!ht,
+ 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}
+\end{document}
+\end{externalDocument}
+
+
+
+%\clearpage%%%%%%%%%%%%%%%%%
+
+
\subsection{Cropping the PDF}
Instead of using the \Index{documentclass} \Lclass{standalone}, which already crops the created PDF,
one can use the optional argument \Lkeyword{crop}.
@@ -774,6 +787,7 @@ The follwoing example was created with
\begin{verbatim}
pages={1,2,3},
+ pagesep=2pt,
grfOptions={width=0.3\linewidth},
compiler=lualatex, runs=2, % for the TOC
frame,
@@ -782,6 +796,7 @@ The follwoing example was created with
\begin{externalDocument}[
pages={1,2,3},
+ pagesep=2pt,
grfOptions={width=0.3\linewidth},
% lstOptions={fontsize=\small,fontfamily=tt},
compiler=lualatex, runs=2,
@@ -838,17 +853,18 @@ or \Lkeyval{b}.
%\define@key{hv}{align}[\centering]{\def\hv@extern@align{#1}}
%\end{verbatim}
-\subsubsection{the default}
-
+%\textbf{the default}
+%
\begin{verbatim}
- align=\centering,
+ align=\centering, % default
\end{verbatim}
-
+%
\begin{externalDocument}[
compiler=lualatex, runs=2,
BGpreamble=red!10, BOpreamble=red,
BGbody=blue!8, BObody=blue,
code,
+ showFilename=false,
crop,
cleanup,
force=false,
@@ -860,7 +876,7 @@ or \Lkeyval{b}.
\end{document}
\end{externalDocument}
-\subsubsection{Left aligned}
+%\textbf{Left aligned}
\begin{verbatim}
align=\raggedright,
@@ -871,6 +887,7 @@ or \Lkeyval{b}.
compiler=lualatex, runs=2,
BGpreamble=red!10, BOpreamble=red,
BGbody=blue!8, BObody=blue,
+ showFilename=false,
code,
crop,
cleanup,
@@ -883,7 +900,7 @@ or \Lkeyval{b}.
\end{document}
\end{externalDocument}
-\subsubsection{Right aligned}
+%\textbf{Right aligned}
\begin{verbatim}
align=\raggedleft,
@@ -896,6 +913,7 @@ or \Lkeyval{b}.
BGpreamble=red!10, BOpreamble=red,
BGbody=blue!8, BObody=blue,
code,
+ showFilename=false,
crop,
cleanup,
force=false,
@@ -910,9 +928,9 @@ or \Lkeyval{b}.
%Now the same for side by side output.
-\subsubsection{the default -- side by side}
+%\textbf{the default -- side by side}
\begin{verbatim}
- align=\centering, mpwidth=0.5\linewidth,
+ align=\centering, mpwidth=0.5\linewidth, % default for side by side
\end{verbatim}
\begin{externalDocument}[
@@ -921,6 +939,7 @@ or \Lkeyval{b}.
BGbody=blue!8, BObody=blue,
code,
crop,
+ showFilename=false,
cleanup,
force=false,
mpwidth=0.5\linewidth,
@@ -932,7 +951,7 @@ or \Lkeyval{b}.
\end{document}
\end{externalDocument}
-\subsubsection{Left aligned -- side by side}
+%\textbf{Left aligned -- side by side}
\begin{verbatim}
align=\raggedright, mpwidth=0.5\linewidth,
@@ -944,6 +963,7 @@ or \Lkeyval{b}.
BGpreamble=red!10, BOpreamble=red,
BGbody=blue!8, BObody=blue,
code,
+ showFilename=false,
crop,
cleanup,
force=false,
@@ -956,7 +976,7 @@ or \Lkeyval{b}.
\end{document}
\end{externalDocument}
-\subsubsection{Right aligned -- side by side}
+%\textbf{Right aligned -- side by side}
\begin{verbatim}
align=\raggedleft, mpwidth=0.5\linewidth,
@@ -969,6 +989,7 @@ or \Lkeyval{b}.
BGpreamble=red!10, BOpreamble=red,
BGbody=blue!8, BObody=blue,
code,
+ showFilename=false,
crop,
cleanup,
force=false,
@@ -981,20 +1002,27 @@ or \Lkeyval{b}.
\end{document}
\end{externalDocument}
+
+
+
\subsection{Inline images}
By default code and image are own paragraphs. With the optional argument \Lkeyword{inline} the created
image can be part of the \Index{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}
+\define@boolkey{hv}[hv@extern@]{inline}[true]{%
+ \hv@extern@codefalse
+ \hv@extern@showFilenamefalse}
\end{verbatim}
-With the setting \LKeyset{inline=true} the optional keyword \Lkeyword{code} is automatically set to false. The
+With the setting \LKeyset{inline=true} the optional keyword \Lkeyword{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=false, docType=latex]{voss}%
+ crop, cropmargin=0,
+ cleanup, force=false, docType=latex]{voss}%
\documentclass{ctexart}
\pagestyle{empty}
\begin{document}
@@ -1006,8 +1034,8 @@ are inserted as \Index{inline image} without showing the code. The complete code
\begin{Verbatim}
-With \Lkeyset{inline} the optional argument \Lkeyword{code} is automatically set to false. The
-next Chinese characters
+With \Lkeyset{inline} the optional argument \Lkeyword{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=false, docType=latex]{voss}
@@ -1017,7 +1045,8 @@ next Chinese characters
美好的一天
\end{document}
\end{externalDocument}
-are inserted as inline image without showing the code. The complete code looks like:
+are inserted as inline image without showing the code. The complete
+code looks like:
\end{Verbatim}
@@ -1049,7 +1078,7 @@ sorted digits of the number $A$: $495=954-459$.
\begin{externalDocument}[
compiler=perl, force=false, docType=pl, ext=pl, includegraphic=false,
- code, mpwidth=0.6\linewidth]{voss}
+ code, mpwidth=0.6\linewidth, showFilename=false]{voss}
#!/usr/bin/perl
#
# Herbert Voss 2005-05-31
@@ -1103,7 +1132,8 @@ outFile = io.open(shortFN..".txt","w+") -- open external file
\begin{externalDocument}[
- compiler=lua, force=false, docType=lua, ext=lua, includegraphic=false, code, usefancyvrb=false]{voss}
+ compiler=lua, force=false, docType=lua, ext=lua, includegraphic=false,
+ code, usefancyvrb=false,textOptions={basicstyle=\ttfamily\footnotesize}]{voss}
#!/usr/bin/env lua
local filename = arg[0]
local shortFN = filename:match("(.+)%..+")
@@ -1181,6 +1211,7 @@ The following examples uses
xindexOptions={-l DE --config AU},
mpwidth=0.6\linewidth,
usefancyvrb=false,
+ showFilename=false,
docType=latex]{voss}
\documentclass[paper=a6,DIV=18,parskip=half-]{screxa}
\pagestyle{empty}
@@ -1228,6 +1259,7 @@ runsequence={lualatex,biber,{xindex -l de -c AU},lualatex,lualatex}
\begin{externalDocument}[
grfOptions={width=0.30\linewidth},
pages={1,3,5},
+ pagesep=2pt,
frame,
runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex},
showFilename,
@@ -1382,6 +1414,26 @@ it makes no difference using the optional argument \Lkeyword{usefancyvrb} or not
\end{externalDocument}
+%\clearpage
+
+
+\subsection{Vertical space}
+
+\begin{verbatim}
+\define@key{hv}{aboveskip}[\medskipamount]{\setlength\hv@extern@aboveskip{#1}}
+\define@key{hv}{belowpreambleskip}[\smallskipamount]{\setlength\hv@extern@belowpreambleskip{#1}}
+\define@key{hv}{belowbodyskip}[\smallskipamount]{\setlength\hv@extern@belowbodyskip{#1}}
+\define@key{hv}{belowskip}[\medskipamount]{\setlength\hv@extern@belowskip{#1}}
+\end{verbatim}
+
+\begin{description}
+\item[\Lkeyword{aboveskip}] Vertical space \emph{before} the environment \Lenv{externalDocument} or
+ the command \Lcs{runExtCmd} (default \Lcs{medskipamount})
+\item[\Lkeyword{belowpreambleskip}] Vertical space between preamble and body (default \Lcs{smallskipamount})
+\item[\Lkeyword{belowbodyskip}] Vertical space between body and output (default \Lcs{smallskipamount})
+\item[\Lkeyword{belowskip}] Vertical space \emph{after} the environment \Lenv{externalDocument} or
+ the command \Lcs{runExtCmd} (default \Lcs{medskipamount})
+\end{description}
\section{Supported engines}
\subsection{\MP\ example}
@@ -1525,6 +1577,7 @@ This is the start of the introduction.
\begin{externalDocument}[
grfOptions={width=0.3\linewidth},
pages={1,2,3},
+ pagesep=2pt,
frame,
verbose=false,
compiler=context,
@@ -1596,6 +1649,7 @@ already exists, there is no need to create it with the next run again and again.
\item[\Lkeyword{ExamplesDir}] move all examples into a directory
\item[\Lkeyset{tclbox=false}] Can be used if there are some negative interactions between package \Lpack{listings}
and package \Lpack{tcolorbox}.
+\item[\Lkeyword{framesep}] Value for \Lcs{fbox} if keyword \texttt{frame} is used.
\item[\Lkeyword{mpsep}] Distance between code and output (default 1\,em).
\item[\Lkeyword{pagesep}] Distance between pages for multipage output (default 1\,em).
\item[\Lkeyword{eps}] create an eps from the pdf (historical).