From 826a444ee70419487a4dabcec775fb1a45472300 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 20 May 2022 21:38:39 +0000 Subject: hvextern (20may22) git-svn-id: svn://tug.org/texlive/trunk@63346 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/hvextern/Changes | 4 + Master/texmf-dist/doc/latex/hvextern/hvextern.pdf | Bin 1203772 -> 1203306 bytes Master/texmf-dist/doc/latex/hvextern/hvextern.tex | 226 ++++++++++++++-------- 3 files changed, 144 insertions(+), 86 deletions(-) (limited to 'Master/texmf-dist/doc/latex') diff --git a/Master/texmf-dist/doc/latex/hvextern/Changes b/Master/texmf-dist/doc/latex/hvextern/Changes index 964577b7fad..c83eea6c1fe 100644 --- a/Master/texmf-dist/doc/latex/hvextern/Changes +++ b/Master/texmf-dist/doc/latex/hvextern/Changes @@ -1,5 +1,9 @@ hvextern.sty ---------------- +v 0.25 2022-05-19 - added framesep keyword + - added keywords for vertical space + - added keyword textOptions for reading text output + - use \hv@marginpar instead of \marginpar/\marginnote v 0.24 2022-05-11 - fix introduced bug for \hv@rm - added tcolorbox support for \runExtCmd . added keywords pagesep and mpsep diff --git a/Master/texmf-dist/doc/latex/hvextern/hvextern.pdf b/Master/texmf-dist/doc/latex/hvextern/hvextern.pdf index 60f1d776455..b472862835d 100644 Binary files a/Master/texmf-dist/doc/latex/hvextern/hvextern.pdf and b/Master/texmf-dist/doc/latex/hvextern/hvextern.pdf differ diff --git a/Master/texmf-dist/doc/latex/hvextern/hvextern.tex b/Master/texmf-dist/doc/latex/hvextern/hvextern.tex index ecc62a121f0..a170457a7d6 100644 --- a/Master/texmf-dist/doc/latex/hvextern/hvextern.tex +++ b/Master/texmf-dist/doc/latex/hvextern/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). -- cgit v1.2.3