diff options
Diffstat (limited to 'macros/latex/contrib/hvextern/doc/hvextern.tex')
-rw-r--r-- | macros/latex/contrib/hvextern/doc/hvextern.tex | 122 |
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} |