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

%% $Id: runtexfile-doc.tex 4 2025-08-13 14:58:56Z 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[makeidx]{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[location=remote]{https://www.ctan.org/tex-archive/biblio/ctan-bibdata/ctan.bib}

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

\usepackage{minted-code}
\usepackage{fancyref}

\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{runtexfile}\xspace}

\title{Script \texttt{runtexfile} \\--\\ \normalsize v. 0.05 (\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: \\
Rolf Niepraschk
\end{noteblock}
\clearpage

\section{Introduction}
The \Index{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. If there is no such line,
it runs the document by default with \Lprog{lualatex}.


\subsection{Syntax}

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

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

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

All \LaTeX\ commands are startet with the option\index{nonstopmode|texttt}

\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. It is only valid for 
any run depending to a \AllTeX-program.
The optional \Index{filename} \verb|<file>| must always be used if the current command expects
another filename (see example for multiple index files). See also section~\vref{mainfile}
for \Index{online-compiler}s where you often do not know the main filename.



\subsection{\TeX studio}

For \TeX studio use as default compiler \Lfile{latexmk} and simply replace the
name by \Lfile{runtexfile} (see last line in the second image):

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


\begin{center}
\includegraphics[width=\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 xindex
%! HV lualatex
%! HV lualatex

%% $Id: runtexfile-doc.tex 4 2025-08-13 14:58:56Z 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|runtexfile runtexfile-doc|
is sufficiant. More complex is the header of example \verb|test2|:


\subsection{Document test}
This document uses package \Lpack{imakeidx} which itself
runs the index commands.~\parencite{ctan-imakeidx}

\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 \Lfile{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 \Lprog{lualatex} and options with
another filename for two of the three \Lprog{xindex} runs.~\parencite{ctan-xindex}

\subsection{Document test3 -- for Online-Compiler}\label{mainfile}

Most applications do not need the original filename, but in an extended
version, like \LaTeX\ together with \Lprog{asymptote} it is 
different.~\parencite{ctan-asymptote} Sometimes you do not know the original
filename, for example when working with an \Index{online-compiler}.
In such a case one can use
the \Index{placeholder} \verb|!!file!!| which will be later replaced
by  the original \TeX-filename which is used by the first command line..

\begin{codeblock}[language=latex,title=Example \texttt{test3} (Asymptote)]
%! HV lualatex --shell-escape
%! HV asy <!!file!!-*asy>
%! HV lualatex --shell-escape
\end{codeblock}

Remember that this makes no real sense here, because you know the main file
name.

\printbibliography

\printindex

\end{document}
