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.tex122
1 files changed, 69 insertions, 53 deletions
diff --git a/macros/latex/contrib/hvextern/doc/hvextern.tex b/macros/latex/contrib/hvextern/doc/hvextern.tex
index c26ac017a0..8c104803e6 100644
--- a/macros/latex/contrib/hvextern/doc/hvextern.tex
+++ b/macros/latex/contrib/hvextern/doc/hvextern.tex
@@ -30,7 +30,7 @@ from within a main \LaTeX\ document~--v. \hvexternFileversion}
\newpage
-\setkeys{hv}{moveToExampleDir,ExampleDir=Examples,showFilename}
+\setkeys{hv}{moveToExampleDir,ExampleDir=Examples,showFilename,verbose}
\section{Syntax}
\begin{verbatim}
@@ -44,7 +44,7 @@ it into the main \LaTeX\ document.
\end{sloppypar}
-There is only one environment:
+There is only one environment and one command:
\begin{verbatim}
\begin{externalDocument}[<options>]{<external filename without extension>}
@@ -52,6 +52,8 @@ There is only one environment:
source code
...
\end{externalDocument}
+
+\runExtCmd[<options>]{<command with arguments>}{<external filename without extension>}
\end{verbatim}
The main document \emph{must} be run with the \Loption{-shell-escape} option, otherwise it won't work, e.g.:
@@ -71,7 +73,7 @@ automatically in the main document..
\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.
+with \texttt{lualatex} with the \texttt{-\kern1pt-shell-escape} option.
\end{minipage}}
@@ -114,7 +116,7 @@ shown by the environment \Lenv{externalDocument}.
\end{minipage}
\begin{minipage}{.39\linewidth}
\begin{externalDocument}[
- compiler=pdflatex,force,cleanup={log,aux},verbose]{voss}
+ compiler=pdflatex,force=false,cleanup={log,aux},verbose]{voss}
\documentclass{standalone}
%StartVisiblePreamble
\usepackage{fontenc}
@@ -172,7 +174,7 @@ catagory, which is done internally by the package. The complete definition of th
showFilename,
code,
ext=py,
- force,
+ force=false,
docType=py,
usefancyvrb,
grfOptions={width=\linewidth}]{python}
@@ -222,7 +224,7 @@ line in the above code shows how it can be done with Python.
\begin{externalDocument}[
compiler=python3,
progpath=/usr/local/bin/,
- force,
+ force=false,
showFilename,
runs=1,
code,
@@ -271,7 +273,7 @@ image.save(imageName+".png", "PNG")
\begin{externalDocument}[grfOptions={width=0.95\linewidth},
compiler=xelatex,code,mpwidth=0.6\linewidth,
- crop,cleanup,force,usefancyvrb=false,ext=tex]{voss}
+ crop,cleanup,force=false,usefancyvrb=false,ext=tex]{voss}
\documentclass{article}
%StartVisiblePreamble
\usepackage{tikz}
@@ -354,7 +356,7 @@ ext=lua, compiler=lua, docType=lua, ...
The default setting is always shown in brackets.
\subsection{Programs and runs}
-The \texttt{progpath} should only in some
+The \Lkeyword{progpath} should only in some
rare cases needed. In general all used compilers will be found by the system. A given \Lkeyword{progpath}
must be end with a slash, e.g. \Lkeyval{./bin/}
@@ -366,9 +368,9 @@ must be end with a slash, e.g. \Lkeyval{./bin/}
\end{verbatim}
Instead of the optional arguments
- \\Lkeyword{compiler}, \\Lkeyword{biber}, and \\Lkeyword{xindex} one can define an individual
+ \Lkeyword{compiler}, \Lkeyword{biber}, and \Lkeyword{xindex} one can define an individual
command sequence by using the optional argument
- \\Lkeyword{runsequence}. It must be comma separated list:
+ \Lkeyword{runsequence}. It must be comma separated list:
\begin{verbatim}
runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex}
@@ -381,7 +383,7 @@ runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex}
runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex},
showFilename,
verbose,
- force,
+ force=false,
cleanup={log,aux,toc,bbl,blg},
code,docType=latex,
lstOptions={columns=fixed}]{voss}
@@ -420,7 +422,7 @@ the environment \Lenv{externalDocument} is:
\begin{externalDocument}[
verbose,
compiler=java,ext=java,code,
- force,docType=java,includegraphic,
+ force=false,docType=java,includegraphic,
usefancyvrb,grfOptions={width=0.9\linewidth}]{java}
import java.awt.Color;
import java.awt.Graphics;
@@ -484,7 +486,7 @@ public class Main {
\end{externalDocument}
-
+%$
\subsection{Grafik options}
@@ -545,7 +547,7 @@ to \Lcs{VerbatimInput}. The following example uses
mpwidth=0.6\linewidth,
crop,
cleanup,
- force,
+ force=false,
docType=latex]{voss}
\RequirePackage{pdfmanagement-testphase}
\DeclareDocumentMetadata{}
@@ -571,7 +573,7 @@ There are different colors for the preamble and body listing: the backgrund and
\define@key{hv}{BObody}[black8]{\def\hv@extern@BObody{#1}}
\end{verbatim}
-The options are passed to \Lpack{tcolorbox} and preset to \Lcolor{black12} and \Lcolor{black!8}.
+The options are passed to \Lpack{tcolorbox} and preset to \Lcolor{black"!12} and \Lcolor{black"!8}.
The color of the frame is set to the same values, hence not seen. The following example uses
\begin{verbatim}
@@ -591,7 +593,7 @@ The color of the frame is set to the same values, hence not seen. The following
mpwidth=0.6\linewidth,
crop,
cleanup,
- force,
+ force=false,
usefancyvrb,
docType=latex]{voss}
\RequirePackage{pdfmanagement-testphase}
@@ -668,7 +670,7 @@ The image Figure~\ref{img:cox} shows an example for a floting object.
% mpwidth=0.6\linewidth,
crop,
cleanup,
- force,
+ force=false,
usefancyvrb,
float,
caption={An example for Coxeter images},
@@ -730,7 +732,7 @@ The following example uses:
% mpwidth=0.6\linewidth,
% crop,
cleanup,
- force,
+ force=false,
frame,
% usefancyvrb,
% float,
@@ -756,7 +758,7 @@ The following example uses:
\subsection{Cropping the PDF}
-Instead of using the \Index{documentclass} \Lcs{standalone}, which already crops the created PDF,
+Instead of using the \Index{documentclass} \Lclass{standalone}, which already crops the created PDF,
one can use the optional argument \Lkeyword{crop}.
\begin{verbatim}
@@ -789,7 +791,7 @@ The follwoing example was created with
% mpwidth=0.6\linewidth,
crop, cropmargin=5,
cleanup,
- force,
+ force=false,
frame,
% usefancyvrb,
% float,
@@ -849,7 +851,7 @@ or \Lkeyval{b}.
code,
crop,
cleanup,
- force,
+ force=false,
docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
@@ -872,7 +874,7 @@ or \Lkeyval{b}.
code,
crop,
cleanup,
- force,
+ force=false,
docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
@@ -896,7 +898,7 @@ or \Lkeyval{b}.
code,
crop,
cleanup,
- force,
+ force=false,
docType=latex]{voss}
\documentclass{article}
\pagestyle{empty}
@@ -920,7 +922,7 @@ or \Lkeyval{b}.
code,
crop,
cleanup,
- force,
+ force=false,
mpwidth=0.5\linewidth,
docType=latex]{voss}
\documentclass{article}
@@ -944,7 +946,7 @@ or \Lkeyval{b}.
code,
crop,
cleanup,
- force,
+ force=false,
mpwidth=0.5\linewidth,
docType=latex]{voss}
\documentclass{article}
@@ -969,7 +971,7 @@ or \Lkeyval{b}.
code,
crop,
cleanup,
- force,
+ force=false,
mpwidth=0.5\linewidth,
docType=latex]{voss}
\documentclass{article}
@@ -981,18 +983,18 @@ or \Lkeyval{b}.
\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 current line. This may make sense, if you need characters which are
+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}
\end{verbatim}
-With \texttt{inline=true} the optional argument \texttt{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, docType=latex]{voss}%
+ crop, cropmargin=0, cleanup, force=false, docType=latex]{voss}%
\documentclass{ctexart}
\pagestyle{empty}
\begin{document}
@@ -1008,7 +1010,7 @@ With \Lkeyset{inline} the optional argument \Lkeyword{code} is automatically set
next Chinese characters
\begin{externalDocument}[
compiler=xelatex, inline, runs=2, grfOptions={height=8pt},
- crop, cropmargin=0, cleanup, force, docType=latex]{voss}
+ crop, cropmargin=0, cleanup, force=false, docType=latex]{voss}
\documentclass{ctexart}
\pagestyle{empty}
\begin{document}
@@ -1020,9 +1022,9 @@ are inserted as inline image without showing the code. The complete code looks l
\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|.
+By default the created pdf which can be, of course, only text, will be inserted by \Lcs{includegraphics}.
+If you have only text as output and don't want to create a pdf you can insert this kind of
+output as verbatim text by setting \Lkeyset{includegraphic=false}.
\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{includegraphic}[true]{}
@@ -1046,7 +1048,7 @@ sorted digits of the number $A$: $495=954-459$.
\begin{externalDocument}[
- compiler=perl, force, docType=pl, ext=pl, includegraphic=false,
+ compiler=perl, force=false, docType=pl, ext=pl, includegraphic=false,
code, mpwidth=0.6\linewidth]{voss}
#!/usr/bin/perl
#
@@ -1101,7 +1103,7 @@ outFile = io.open(shortFN..".txt","w+") -- open external file
\begin{externalDocument}[
- compiler=lua, force, docType=lua, ext=lua, includegraphic=false, code, usefancyvrb=false]{voss}
+ compiler=lua, force=false, docType=lua, ext=lua, includegraphic=false, code, usefancyvrb=false]{voss}
#!/usr/bin/env lua
local filename = arg[0]
local shortFN = filename:match("(.+)%..+")
@@ -1140,7 +1142,7 @@ outFile:close()
\subsection{Running additional external programs}
-For a \LaTeX\ additional programs for bibliography, index, a.s.o. maybe needed.
+For a \LaTeX\ additional programs for \Index{bibliography}, \Index{index}, a.s.o. maybe needed.
\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{biber}[true]{}
@@ -1174,7 +1176,7 @@ The following examples uses
pages=2,
crop,
cleanup,
- force,
+ force=false,
xindex,
xindexOptions={-l DE --config AU},
mpwidth=0.6\linewidth,
@@ -1230,7 +1232,7 @@ runsequence={lualatex,biber,{xindex -l de -c AU},lualatex,lualatex}
runsequence={lualatex,biber,xindex -l de -c AU,lualatex,lualatex},
showFilename,
verbose,
- force,
+ force=false,
cleanup={log,aux,toc,bbl,blg},
code,docType=latex,
lstOptions={columns=fixed}]{voss}
@@ -1264,7 +1266,7 @@ Sort with xindex \verb|-l DE --config AU|
\subsection{Using \texttt{listings}}
-The default is using \verb|\lstinputlisting| for the printed code sequences.
+The default is using \Lcs{lstinputlisting} for the printed code sequences.
\begin{externalDocument}[
grfOptions={width=0.45\linewidth},
@@ -1272,7 +1274,7 @@ The default is using \verb|\lstinputlisting| for the printed code sequences.
frame,compiler=pdflatex,
showFilename,
% crop,
- force,runs=2,code,docType=latex,
+ force=false,runs=2,code,docType=latex,
frame,
lstOptions={columns=fixed}]{voss}
%StartVisiblePreamble
@@ -1322,7 +1324,7 @@ The default is using \verb|\lstinputlisting| for the printed code sequences.
-It also possible to use \verb|\VerbatimInput| from package \texttt{fancyvrb}. In general
+It also possible to use \Lcs{VerbatimInput} from package \Lpack{fancyvrb}. In general
it makes no difference using the optional argument \Lkeyword{usefancyvrb} or not.
@@ -1332,7 +1334,7 @@ it makes no difference using the optional argument \Lkeyword{usefancyvrb} or not
frame,compiler=pdflatex,
showFilename,
% crop,
- force,runs=2,code,docType=latex,
+ force=false,runs=2,code,docType=latex,
frame,usefancyvrb]{voss}
%StartVisiblePreamble
\documentclass[chapterprefix=on,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
@@ -1392,7 +1394,7 @@ it makes no difference using the optional argument \Lkeyword{usefancyvrb} or not
compiler=mpost,
showFilename,
% crop,
- force,
+ force=false,
cleanup,
code,
docType=mp,
@@ -1424,7 +1426,7 @@ end;
compiler=tex,
showFilename,
% crop,
- force,
+ force=false,
code,
docType=tex,
ext=tex,]{voss}
@@ -1488,7 +1490,7 @@ This is the start of the introduction.
compiler=lualatex,
showFilename,
crop,
- force,
+ force=false,
code,
docType=latex,
ext=tex,]{voss}
@@ -1528,7 +1530,7 @@ This is the start of the introduction.
compiler=context,
showFilename,
runs=2,
- force,
+ force=false,
code,
docType=context,
ext=tex,]{voss}
@@ -1569,18 +1571,32 @@ foo
\end{externalDocument}
+\section{Running external commands}
+Integrating the current directory of this document we can use the macro \Lcs{runExtCmd} with
+the optional argument \Lkeyword{redirect}
+
+\begin{verbatim}
+\runExtCmd[redirect]{ls -la}{voss}
+\end{verbatim}
+
+to get the directory listed:
+
+\medskip
+\runExtCmd[redirect,verbose]{ls -la}{voss}
+
+
\section{Other options}
\begin{description}
-\item[\texttt{force=false}] can speed up the comiling time for the document. If a created image/output
+\item[\Lkeyset{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}.
+\item[\Lkeyword{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{tclbox=false}] Can be used if there are some negative interactions between package \texttt{listing}
- and package \texttt{tcolorbox}.
-\item[\texttt{eps}] create an eps from the pdf (historical)
+\item[\Lkeyword{copyToExampleDir}] name of a directory for the examples, must first be created by the user himself
+\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{eps}] create an eps from the pdf (historical).
\end{description}