1 files changed, 22 insertions, 13 deletions
diff --git a/macros/latex/contrib/hvextern/doc/hvextern.tex b/macros/latex/contrib/hvextern/doc/hvextern.tex
index b05f01e14a..84b2df5183 100644
--- a/macros/latex/contrib/hvextern/doc/hvextern.tex
+++ b/macros/latex/contrib/hvextern/doc/hvextern.tex
@@ -1,7 +1,7 @@
-%% $Id: hvextern.tex 748 2023-08-22 18:03:42Z herbert $
+%% $Id: hvextern.tex 749 2023-08-24 19:10:17Z herbert $
 \RequirePackage{pdfmanagement-testphase}
 \DeclareDocumentMetadata{}
-\documentclass[ngerman,a4paper,twoside]{article}
+\documentclass[english,a4paper,twoside]{article}
 \usepackage{babel}
 \usepackage{libertinus}
 \setmonofont[Scale=MatchLowercase,FakeStretch=0.88]{AnonymousPro}
@@ -10,13 +10,12 @@
 \usepackage{fancyhdr}
 \pagestyle{fancy}
 \usepackage{hvlogos}
-\usepackage%[checkCode]
-{hvextern}
+\usepackage[checkCode]{hvextern}
 \usepackage{hvindex}
 \usepackage{hvdoctools}
 \usepackage{listings}
 \lstset{basicstyle=\ttfamily\small,language=[LaTeX]TeX,breaklines}  
-\usepackage{xcolor,xspace}
+\usepackage{xcolor,xspace,varioref}
 \usepackage{hyperref}
 
 \def\Python{\textsf{Python}\xspace}
@@ -28,14 +27,14 @@
 \begin{document}
 \title{Writing, running and including the output of external documents 
 from within a main\newline \LaTeX\ document~--v. \hvexternFileversion}
-\author{Herbert Voß \url{herbert@dante.de}\thanks{Thanks to Karl Berry; 
+\author{Herbert Voß \url{hvoss@tug.org}\thanks{Thanks to Karl Berry; 
 Werner Lemberg; Rolf Niepraschk}}
 \maketitle
 \tableofcontents
 
 %\newpage
 
-\setkeys{hv}{%moveToExampleDir,ExampleDir=Exa,
+\setkeys{hv}{moveToExampleDir,ExampleDir=Exa,
 showFilename,verbose}
 
 
@@ -78,7 +77,12 @@ source code
     {<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.:
+The very first compilation run of the main document must be done
+  with the \Loption{-shell-escape} command-line option, otherwise it won't
+  work.  Follow-up runs, for example, to resolve references, should
+  usually be done without \Loption{-shell-escape}.
+
+The currently used filename for the example is saved in the macro \Lcs{hvExternFilename}.
 
 \begin{verbatim}
 lualatex --shell-escape <file>
@@ -107,10 +111,10 @@ This document was run with \LuaLaTeX. Suppose you want to insert the output of a
 which needs for several reasons a \XeLaTeX\ 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 \XeLaTeX\ and the output is insert as pdf image: 
+with \XeLaTeX\ and the output is insert as pdf image:\label{inline-exa}
 \begin{externalDocument}[%
   compiler=xelatex, inline, force=true, runs=2, grfOptions={height=8pt},%
-  crop, cropmargin=0, cleanup, docType=latex]{voss}
+  crop, cropmargin=0, cleanup, docType=latex,vshift=-1pt]{voss}
 \documentclass{ctexart}
 \pagestyle{empty}
 \begin{document} 
@@ -118,7 +122,9 @@ with \XeLaTeX\ and the output is insert as pdf image:
 \end{document}
 \end{externalDocument}
 
-Another example which needs a \pdfLaTeX\ run.  The \Index{source} code itself is also not
+The current filename of the above example is \hvExternFilename.
+
+Let's show another example which needs a \pdfLaTeX\ run.  The \Index{source} code itself is also not
 shown by the environment \Lenv{externalDocument}.
 
 
@@ -1867,8 +1873,8 @@ to get the directory listed:
 \section{Other options}
 
 \begin{description}
-%\item[\Lkeyword{showFilename}] Prints the filename in the outer margin (right for oneside) or in twocolumn mode for
-%    the first column in the left and the second column in the right margin.
+\item[\Lkeyword{vshift}] A length for a vertical shift of the object, only valid for the inline mode.
+See document source of example~\vpageref{inline-exa}.
 %\item[\Lkeyword{outerFN}] Only valid for the twocolumn mode with onecolumn floats (environment \texttt{figure*}),
 %    to get the filename on the right or left of the whole page.
 %\item[\Lkeyword{shiftFN}] A length to move the printed filename up or down.
@@ -1889,6 +1895,9 @@ if the package option \Loption{checkCode} exists.
 \end{description}
 
 
+
+
+
 \printindex