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.tex134
1 files changed, 76 insertions, 58 deletions
diff --git a/macros/latex/contrib/hvextern/doc/hvextern.tex b/macros/latex/contrib/hvextern/doc/hvextern.tex
index 0ad4419627..c26ac017a0 100644
--- a/macros/latex/contrib/hvextern/doc/hvextern.tex
+++ b/macros/latex/contrib/hvextern/doc/hvextern.tex
@@ -8,21 +8,29 @@
\usepackage{hvlogos}
\usepackage{hvextern}
+\usepackage{hvindex}
+\usepackage{hvdoctools}
\usepackage{listings}
\lstset{basicstyle=\ttfamily\small,language=[LaTeX]TeX,breaklines}
-\usepackage{xcolor}
+\usepackage{xcolor,xspace}
\usepackage{hyperref}
+
+\def\Python{\textsf{Python}\xspace}
+\def\Perl{\textsf{Perl}\xspace}
+\def\Lua{\textsf{Lua}\xspace}
+\def\Java{\textsf{Java}\xspace}
+
+
\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}
+\setkeys{hv}{moveToExampleDir,ExampleDir=Examples,showFilename}
\section{Syntax}
\begin{verbatim}
@@ -46,10 +54,10 @@ 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.:
+The main document \emph{must} be run with the \Loption{-shell-escape} option, otherwise it won't work, e.g.:
\begin{verbatim}
-laulatex --shell-escape <file>
+lualatex --shell-escape <file>
\end{verbatim}
@@ -75,8 +83,8 @@ This document was run with \LuaLaTeX. Suppose you want to insert the output of a
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}.
+with \pdfLaTeX\ and the output is insert as pdf image. The \Index{source} code itself is not
+shown by the environment \Lenv{externalDocument}.
\begin{minipage}{.59\linewidth}
@@ -129,7 +137,7 @@ shown by the environment \texttt{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|:
+The \ttIndex{png} image is created on the fly with the following arguments of \Lenv{externalDocument}:
\begin{Verbatim}
\begin{externalDocument}[
@@ -154,7 +162,7 @@ The code which is declared as header and main can be marked by:
{\NumChar StopVisiblePreamble}
\end{Verbatim}
-\verb|\NumChar| is the default Python comment character \# and needs to be saved with a different
+\Lcs{NumChar} is the default Python comment character \#\index{\#} and needs to be saved with a different
catagory, which is done internally by the package. The complete definition of the code is:
@@ -206,7 +214,7 @@ image.save(imageName, "PNG")
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,
+internally extended by a consecutive number which isn't known to the \Index{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.
@@ -302,9 +310,9 @@ The marker for the code ranges which should be listed depend to the used program
\end{document}
\end{verbatim}
-everything between \verb|%StartVisiblePreamble| and \verb|%StopVisiblePreamble| will be listed as
+everything between \ttIndex{\%StartVisiblePreamble} and \ttIndex{\%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 with an own
+ \Lcs{begin\{document\}} and \Lcs{end\{document\}} as body. The marker must be defined with an own
macro, e.g.:
\begin{verbatim}
@@ -315,11 +323,14 @@ macro, e.g.:
{\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
+\Lcs{NumChar} is the comment character \#, which needs a special handling. This version of \Lpack{hvextern}
+supports the following programming languages (option \Lkeyword{compiler}):
+\Lkeyval{mpost}, \Lkeyval{tex}, \Lkeyval{latex}, \Lkeyval{luatex},
+\Lkeyval{python3}, \Lkeyval{perl}, \Lkeyval{lua}, \Lkeyval{xetex},
+\Lkeyval{pdflatex}, \Lkeyval{lualatex}, \Lkeyval{xelatex}, and \Lkeyval{context}. The default
+is \Lkeyval{pdflatex}. The option \Lkeyword{docType} selects the config file, which must be one of
+\Lkeyval{context}, \Lkeyval{lua}, \Lkeyval{pl}, \Lkeyval{tex}, \Lkeyval{latex},
+\Lkeyval{mp}, and \Lkeyval{py}. For Lua it is
\begin{verbatim}
\hv@extern@exampleType{lua}
@@ -330,7 +341,8 @@ context, lua, pl, tex, latex, mp, and py. For Lua it is
\end{verbatim}
-It defines the marker strings for the listed code sequences. In some cases you have to use multiple times the same value
+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}
@@ -339,12 +351,12 @@ ext=lua, compiler=lua, docType=lua, ...
\section{Optional arguments}
-The deafault setting is always shown in brackets.
+The default 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.
+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/}
\begin{verbatim}
\define@key{hv}{progpath}[]{\def\hv@extern@progpath{#1}}
@@ -354,9 +366,9 @@ must be end with a slash, e.g. \texttt{./bin/} %The option \texttt{runsequence}
\end{verbatim}
Instead of the optional arguments
- \texttt{compiler}, \texttt{biber}, and \texttt{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
- \texttt{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}
@@ -398,8 +410,8 @@ 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 \texttt{externalDocument} is:
+The following \Java-program creates the Mandelbrot set as png image. The valid setting for
+the environment \Lenv{externalDocument} is:
\begin{verbatim}
compiler=java,ext=java,docType=java,
@@ -480,7 +492,7 @@ public class Main {
\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 option is passed to \Lcs{includegraphics}, e.g. \verb|angle=90,width=\linewidth| for
the follwing example.
\begin{externalDocument}[grfOptions={angle=90,width=\linewidth},
@@ -516,8 +528,8 @@ the follwing example.
\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
+The option is passed either to \Lcs{lstinputlisting}, or, if \Lkeyword{usefancyvrb} is active,
+to \Lcs{VerbatimInput}. The following example uses
\begin{verbatim}
lstOptions={basicstyle=\sffamily\itshape\scriptsize},
@@ -559,7 +571,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 \verb|tcolorbox| and preset to \texttt{black12} and \texttt{black!8}.
+The options are passed to \Lpack{tcolorbox} and preset to \Lcolor{black12} and \Lcolor{black!8}.
The color of the frame is set to the same values, hence not seen. The following example uses
\begin{verbatim}
@@ -598,7 +610,7 @@ The color of the frame is set to the same values, hence not seen. The following
\subsection{Type of the source code}
-The current version of \texttt{hvextern} supports code written as
+The current version of \Lpack{hvextern} supports code written as
\MP, \plainTeX, \LaTeX, \ConTeXt, and Python. Every type has its own keywords for the
linerange which should be printed for the preamble and
the body. For example the \texttt{latex} config is:
@@ -627,15 +639,15 @@ If a source needs more than running the defined compiler, it must be defined by
...}
\end{verbatim}
-The type of the source code can be different to the compiler, e.g. source \texttt{latex},
-but compiler \texttt{lualatex}.
+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 \texttt{float}, a caption and a label are optional. The float type is always
-\texttt{figure}.
+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]{}
@@ -696,7 +708,7 @@ The pages which should be printed can be defined by
\define@boolkey{hv}[hv@extern@]{frame}[true]{}
\end{verbatim}
-With \texttt{frame} the pages can be framed (internally by \verb|\fbox|).
+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 following example uses:
@@ -744,8 +756,8 @@ The following example uses:
\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}.
+Instead of using the \Index{documentclass} \Lcs{standalone}, which already crops the created PDF,
+one can use the optional argument \Lkeyword{crop}.
\begin{verbatim}
\define@boolkey{hv}[hv@extern@]{crop}[true]{}
@@ -755,7 +767,8 @@ one can use the optional argument \texttt{crop}.
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
+will have different heights after \Index{cropping} (see next image).
+The follwoing example was created with
\begin{verbatim}
pages={1,2,3},
@@ -802,20 +815,22 @@ will have different heights after cropping (see next image). The follwoing examp
\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.
+width of a minipage with \Lkeyword{mpwidth} greater than 0\,pt the output will be side by side.
\begin{verbatim}
\define@key{hv}{mpwidth}[0pt]{\setlength\hv@extern@mpwidth{#1}}
+\define@key{hv}{mpvalign}[0pt]{\def\hv@extern@mpvalign{#1}}
\end{verbatim}
-\texttt{mpwidth} is the width of the code. The rest of the line, minus 1em for the space between
+\Lkeyword{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.
+width for the output and will be calculated automatically. The two \Index{minipages} are
+aligned by defaults to its top. This can be changed by setting \Lkeyword{mpvalign} to \Lkeyval{c}
+or \Lkeyval{b}.
-\subsection{Align of the output}
+\subsection{Horizontal alignment of the output}
%\begin{verbatim}
%\define@key{hv}{align}[\centering]{\def\hv@extern@align{#1}}
@@ -965,7 +980,7 @@ aligned by its top.
\end{externalDocument}
\subsection{Inline images}
-By default code and image are own paragraphs. With the optional argument \texttt{inline} the created
+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
not part of your current font.
@@ -984,12 +999,12 @@ next Chinese characters
美好的一天
\end{document}
\end{externalDocument}
-are inserted as inline image without showing the code. The complete code looks like:
+are inserted as \Index{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
+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},
@@ -1015,9 +1030,9 @@ output as verbatim text by setting \verb|includegraphic=false|.
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
+\Lext{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
+\Index{Kaprekar} constants uses
\begin{verbatim}
my $filename = $0; # the current filename
@@ -1025,7 +1040,8 @@ $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
+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$.
@@ -1074,7 +1090,7 @@ close $fh;
%$
-Another example with running Lua to calculate and print the Pascal's triangle. The internal filename
+Another example with running \Lua to calculate and print the \Index{Pascal's triangle}. The internal filename
is available with
\begin{verbatim}
@@ -1133,7 +1149,7 @@ For a \LaTeX\ additional programs for bibliography, index, a.s.o. maybe needed.
\define@key{hv}{runsequence}[]{\def\hv@extern@runsequence{#1}}
\end{verbatim}
-The \texttt{biber} run needs no additional options, but for \texttt{xindex} it maybe useful.
+The \Lkeyword{biber} run needs no additional options, but for \Lkeyword{xindex} it maybe useful.
The following examples uses
\begin{verbatim}
@@ -1200,8 +1216,8 @@ Sort with xindex \verb|-l DE --config AU|
\end{externalDocument}
-Instad of using the options \texttt{compiler}, \texttt{biber}, and \texttt{xindex}
-one can also use only the optional argument \texttt{runsequence} to define an individuell
+Instad of using the options \Lkeyword{compiler}, \Lkeyword{biber}, and \Lkeyword{xindex}
+one can also use only the optional argument \Lkeyword{runsequence} to define an individuell
sequence of commands, e.g.:
\begin{verbatim}
runsequence={lualatex,biber,{xindex -l de -c AU},lualatex,lualatex}
@@ -1258,7 +1274,7 @@ The default is using \verb|\lstinputlisting| for the printed code sequences.
% crop,
force,runs=2,code,docType=latex,
frame,
- lstOptions={columns=fixed}]{Schubert-A}
+ lstOptions={columns=fixed}]{voss}
%StartVisiblePreamble
\documentclass[chapterprefix=on,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
\DeclareNewSectionCommand[
@@ -1307,7 +1323,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 makes no difference using the optional argument \texttt{usefancyvrb} or not.
+it makes no difference using the optional argument \Lkeyword{usefancyvrb} or not.
\begin{externalDocument}[
@@ -1317,7 +1333,7 @@ it makes no difference using the optional argument \texttt{usefancyvrb} or not.
showFilename,
% crop,
force,runs=2,code,docType=latex,
- frame,usefancyvrb]{Schubert-A}
+ frame,usefancyvrb]{voss}
%StartVisiblePreamble
\documentclass[chapterprefix=on,parskip=half-,DIV=12,fontsize=12pt]{scrbook}
\DeclareNewSectionCommand[
@@ -1562,11 +1578,13 @@ already exists, there is no need to create it with the next run again and again.
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)
\end{description}
-
+\printindex
\end{document}