%! HV lualatex
%! HV biber
%! HV lualatex
%! HV lualatex

%% $Id: runDoc-doc.tex 1140 2025-07-18 10:39:09Z herbert $
%
\listfiles\setcounter{errorcontextlines}{100}
\documentclass[paper=a4,fontsize=11pt,DIV=14,parskip=half-,
               captions=tableabove,twoside=on]{scrartcl}
\usepackage{fontspec}
%\usepackage{libertinus-otf}
\setmainfont{AccanthisADFStdNo3}[
  UprightFont   =*-Regular,
  BoldFont      =*-Bold,
  ItalicFont    =*-Italic,
  BoldItalicFont=*-BoldItalic,
  RawFeature    = -rlig,
]
\setsansfont{GilliusADF}[
  UprightFont   =*-Regular,
  BoldFont      =*-Bold,
  ItalicFont    =*-Italic,
  BoldItalicFont=*-BoldItalic,
  RawFeature    = -rlig,
]

\usepackage{juliamono}
\usepackage[english]{babel}
\usepackage{scrlayer-scrpage}
\automark[section]{section}
\automark*[subsection]{}
\pagestyle{scrheadings}

{\catcode`\%=12 
 \gdef\perCent{%}
 \gdef\DoubleperCent{%%}
}

\usepackage{xcolor,fancyvrb,varioref,awesomebox}
\usepackage{xltabular}
\usepackage{hvlogos} % for Wikipedia W
\usepackage{listings}
\usepackage{hvextern}
\lstset{basicstyle=\ttfamily\small,language=[LaTeX]TeX}
\usepackage{ragged2e}
\usepackage{index}\makeindex
\usepackage{hvindex}
\def\Lfile#1{\texttt{#1}\index{#1 file@\texttt{#1} file}}
\def\Lext#1{\texttt{.#1}\index{#1 file extension@\texttt{.#1} file extension}}
\def\Lcs#1{\texttt{\textbackslash#1}\index{#1@\texttt{\textbackslash#1}}}
\def\Lenv#1{\texttt{#1}\index{#1 environment@\texttt{#1} environment}}
\def\Lpack#1{\texttt{#1}\index{#1 package@\texttt{#1} package}}
\def\Lprog#1{\texttt{#1}\index{#1 program@\texttt{#1} program}}
\def\Loption#1{\texttt{#1}\index{#1@\texttt{#1} package option}}
\def\Largb#1{\emph{\{#1\}}}

\usepackage[style=authoryear]{biblatex}
\addbibresource{ctanbib.bib}

\raggedbottom
\usepackage{url}
\usepackage[colorlinks,linktocpage]{hyperref}

\usepackage{minted-code}

\makeatletter% from: doc.sty
\newcommand*\GetFileInfo[1]{%
  \def\filename{#1}%
  \def\@tempb##1 ##2 ##3\relax##4\relax{%
    \def\filedate{##1}%
    \def\fileversion{##2}%
    \def\fileinfo{##3}}%
  \edef\@tempa{\csname ver@#1\endcsname}%
  \expandafter\@tempb\@tempa\relax? ? \relax\relax}
\makeatother

\usepackage{xspace}

\newcommand\rD{\texttt{runDoc}\xspace}

\title{Script \texttt{runDoc} \\--\\ \normalsize v. 0.02 (\today)}
\author{\shortstack{Herbert Voß\\\small \href{mailto:hvoss@tug.org}{hvoss@tug.org}}}
\date{}
\begin{document}
\maketitle
\thispagestyle{empty}
%\enlargethispage{1cm}
\tableofcontents

\begin{noteblock}
\raggedright
Thanks to: \\
\end{noteblock}
\clearpage

\section{Introduction}
The Lua program \rD  parses an \AllTeX-document for lines
starting with \verb|%! HV |. The «HV» has no meaning, it should only
be a significant marker for the command lines.
Such lines can define commands which will be
executed by \rD.  These lines must be at the beginning of the document.
Only empty lines before will be ignored. \rD will stop parsing for commands
if a line without a preceeding \verb|%! HV | is found.


\subsection{Syntax}

The \Index{syntax} is \verb|runDoc [...] <file>| where \verb|[...]|  are optional \Index{argument}s, either in short or
long form which, of course, can be mixed:

\begin{verbatim}
runDoc [-h,--help] [-v,--verbose] [-V,--version ] filename
\end{verbatim}

Every executed command gets an own logfile \verb|runDoc-?.log| in which
the question mark is the number of the corresponding command lines in
the document. This allows to locate any problem in the several external
runs. 
With the option -v (verbose) a short logfile which lists more or less only the important steps
from within the script is \verb|runDoc.log|.

All \LaTeX\ commands are startet with the option 

\verb|--interaction=nonstopmode|

 The supported \AllTeX-commands
are 

\begin{verbatim}
local commands = {"lualatex", "luatex", "luahbtex", "latex", "pdflatex", 
                  "xelatex", "xetex" }
\end{verbatim}

This is not really of interest, because it is only needed for the decision
to use the option \verb|--interaction=nonstopmode| or not. The optional
filename \verb|<file>| must always be used if the current command expects
another filename (see example for multiple index files).



\subsection{\TeX studio}

For \TeX studio use as compiler \verb|latexmk| and simply replace the
name by \verb|runDoc|:

\includegraphics[width=\linewidth]{images/compiler}

\begin{center}
\includegraphics[width=0.5\linewidth]{images/latexmk}
\end{center}


\section{examples}

\subsection{This document}

The header looks like

\begin{codeblock}[minted language=latex, title=Command lines for this document]
%! HV lualatex
%! HV biber
%! HV lualatex
%! HV lualatex

%% $Id: runDoc-doc.tex 1140 2025-07-18 10:39:09Z herbert $
%
\listfiles\setcounter{errorcontextlines}{100}
\documentclass[paper=a4,fontsize=11pt,DIV=14,parskip=half-,
               captions=tableabove,twoside=on]{scrartcl}
\usepackage{fontspec}
[...]
\end{codeblock}

In this case no extra filename is needed, running \verb|runDoc runDoc-doc|
is sufficiant. More complex is the header of example \verb|test2|:


\subsection{Document test}
This document uses package \texttt{imakeidx} which itself
runs the index commands.

\begin{codeblock}[language=latex,title=Example \texttt{test}]
%! HV lualatex --shell-escape 
%! HV biber <test.aux> 
%! HV lualatex --shell-escape
%! HV lualatex --shell-escape

%% The index files are run by imakeidx
[...]
\end{codeblock}

The filename for biber is not really needed, because it also
works with the main filename.



\subsection{Document test2}

A more complex example:


\begin{codeblock}[language=latex,title=Example \texttt{test2}]
%! HV lualatex --shell-escape
%! HV biber 
%! HV lualatex --shell-escape
%! HV xindex
%! HV xindex  --config DIN2 -l DE -o test2.vwd <test2.vwx>
%! HV xindex  --config DIN2 -l DE -o test2.dbd <test2.dbx>
%! HV lualatex --shell-escape
%! HV lualatex --shell-escape
\end{codeblock}


There is an optional argument for \verb|lualatex| and options with
another filename for two of the three \verb|xindex| runs.


\nocite{ctan-index}
\printbibliography

\printindex

\end{document}
