% !Mode:: "TeX:DE:UTF-8:Main"
\RequirePackage{luatex85}
\documentclass[parskip=half-,egregdoesnotlikesansseriftitles]{scrartcl}
\usepackage{ydoc-code,ydoc-desc}
\usepackage{fontspec}
\usepackage[english]{babel}
\usepackage{csquotes}
\usepackage{xcolor,listings,enumitem}

\title{The \texttt{fontloader-luaotfload} package}
\author{Ulrike Fischer\thanks{fischer@troubleshooting-tex.de}}
\newcommand\package[1]{\texttt{#1}}


\begin{document}
\maketitle

\section{Requirements}

Use a current tex system! The files has been tried with texlive 2017.

\section{Introduction}
The luatex engine can use open type fonts but -- unlike xetex which has the harfbuzz library built-in  --  it doesn't work with the bare binary but needs additional (lua)-code.

In \LaTeX\ this lua-code is provided by the package \package{luaotfload}. In newer \LaTeX-versions the lua-code of \package{luaotfload} is loaded by the format. So you don't need to load it manually. Even a minimal hello-world-example should show in the log-file

\verb+Lua module: luaotfload-main 2017/01/29 2.80001 OpenType layout system.+




\package{luaotfload} consist of two parts:

\begin{itemize}
\item The core of the package is the \emph{fontloader} -- the current is \texttt{fontloader-2017-02-11.lua}. The fontloader has been created from a subset of the fontloader code of the Con\TeX{}t format.

\item Around this fontloader \package{luaotfload} contains a number of lua-file needed for the creation of the font name database, the font cache, and some adaptions of the fontloader to the needs of \LaTeX.
\end{itemize}

\package{luaotfload} has made quite an effort to separate the two parts and since some time it is possible to replace the core fontloader with another (newer) version with the help of a configuration file. This makes it possible e.\,g. to test new features which have been added to Con\TeX{}t.

This package provides a number of such alternative fontloaders.

\emph{Please read the complete documentation before trying to use the fontloaders -- at least read the section \ref{sec:problem} about incompabilities.}


\section{Installation}

The package contains

\begin{itemize}
\item a number of \texttt{fontloader-XXX.lua} files. This files should be in a texmf-tree in  \texttt{../tex/luatex/fontloader-luaotfload} -- probably your tex system installed them there already.

\item all the other files are either examples or documentation and should go in the \texttt{doc}-folder.
\end{itemize}

\section{Using the fontloader(s)}

To use one of the alternative fontloader you must create a \texttt{luaotfload.conf} file.  This file should be in the normal search path, e.g. in the folder of your document or in some texmf-tree, there at best in  the branch \texttt{tex/luatex}.

Such a \texttt{luaotfload.conf} looks e.\,g. like this:

\lstinputlisting[columns=flexible,basicstyle=\ttfamily]{luaotfload.conf}

\begin{itemize}
\item The fontloader section starts with \texttt[run].
\item The semicolon starts a comment. So in the example \texttt{fontloader-reference-2017-07-28.lua} is the active fontloader. If you comment all fontloaders \package{luaotfload} will use its default loader.
\item The shortcuts \texttt{default} loads the default fontloader of \package{luaotfload} and \texttt{reference} its reference version (see below for an explanation about the reference fontloader).
\item The last active entry wins!
\item It is possible to use absolute pathes, but how exactly is rather system dependant, so you will have to try.
\end{itemize}

\section{General description of the fontloaders}

Fontloaders come in two flavors: I will call them \emph{reference type} and \emph{luaotfload type}.

The \emph{reference type} is a copy from a \texttt{luatex-fonts-merged.lua} from a context installation. This file is -- as the name indicates -- a merge of the generic part of the context fontloader files. It is normally present in a context minimals installation, or can be created by running in the folder which contains \texttt{luatex-fonts.lua} the command:

\begin{lstlisting}
mtxrun --script package --merge ./luatex-fonts.lua
\end{lstlisting}

The \emph{luaotfload type} is created by a script call \texttt{mkimport} which you can find on the github site of \package{luaotfload}. It also uses the context files but ignores some that are present in the lualibs packages and it also does some other adaptions.

The original \package{luaotfload} already contains both types of fontloaders, the reference type is \texttt{fontloader-reference.lua} -- it can be chosen in the configuration file with the keyword \texttt{reference} -- and the luaotfload type is \texttt{fontloader-2017-02-11-lua}.

I have no idea about the pros and cons of both types. On the whole I would have preferred to build  luaotfload type fontloaders as they are nearer to the current default fontloader. But sadly it didn't work: I could adapt the pathes in \texttt{mkimport} to my system and build a fontloader but it wasn't usable.
The \emph{reference type} are perhaps slower and there is the possibility that they contain code which could clash with some lua libraries loaded by other \LaTeX packages. But until now they seemed to work.

For both types there is the danger that fontloaders created with files from a newer context version clash with the older wrapper code of luaotfload -- and actually this already happened, see the following section.



\section{Incompabilities with the \package{luaotfload} \enquote{wrapper} files}\label{sec:problem}

As mentioned in the previous section it is always possible that newer versions of the core fontloader are no longer compatible to the wrapper files from \package{luaotfload}. If you try out \texttt{fontloader-reference-2017-07-28.lua} you will get a lua error:

\begin{verbatim}
luaotfload | load : FATAL ERROR
luaotfload | load : Failed to load module "luaotfload-letterspace.lua".
luaotfload | load : Error message:
luaotfload | load : "...mf-dist/tex/luatex/luaotfload/luaotfload-letterspace.lua:73: 
                   attempt to index local 'nodepool' (a nil value)".
\end{verbatim}

The reason is that \texttt{luaotfload-letterspace.lua} tries to access a table value that no longer exists. Imho it is not possible to solve this problem without changing the original file. This is absolutly not to my liking but as I don't see another way I offer a patched version. If you want to use the newer fontloader versions you will have to do this:

In the documentation folder of this package there is a file \texttt{luaotfload-letterspace.luax}. Change the extension to \texttt{lua} and copy the file to your document folder or in a \emph{local} texmf tree to \texttt{tex/luatex/luaotfload} -- in the second case don't forget to update your file name database (FNDB): in miktex with \texttt{initexmf -u} and in texlive with \texttt{mktexlsr}.

Try out a small lualatex document. If the log-file tells you

\verb+ !!!!! UF: Using CHANGED luaotfload-letterspace 2017-07-14 !!!!!+

then the new \texttt{lua}-file is used. \textbf{Don't forget that this patched file is in your system! When luaotfload is updated you should remove it.}

\section{The list of new fontloaders}

Currently there are only three fontloaders. But I plan to add more if some changes are made to the context files.

Fontloaders with * before their name need the adapted \texttt{luaotfload-letterspace.lua} as described in the last section.

\begin{description}[font=\texttt]
  \item[fontloader-2017-02-11-stix.lua] This fontloader is the original luaotfload-type fontloader where one section  -- from \texttt{font-oto.lua} -- has been replaced to get around a bug in the stix fonts with wrong parenthese sizes. See \texttt{test-fontloader-2017-02-11-stix.tex}.

  \item[*fontloader-reference-2017-07-28.lua] This is a reference-type fontloader which has been created on 2017-07-28. It adds the capability to add ligatures with \enquote{word boundaries}. See \texttt{test-fontloader-2017-07-28.tex}.
  
  \item[*fontloader-reference-2017-08-18.lua] This is a reference-type fontloader which I added when I tried out to color the cow fonts: See \url{https://tex.stackexchange.com/a/387069/2388}  and 
      \texttt{test-fontloader-2017-08-18.tex}.
      
\end{description}


\section{Using newer luatex versions}

As mentioned in the tex.stackexchange answer about the colored cow fonts, the solution needs a newer luatex. While \texttt{fontloader-reference-2017-08-18.lua} in itself seems to work fine with the luatex of TeXlive 2017, trying to use the \texttt{colr} font feature, leads to the error

  \verb+! error:  (vf command): unknown packet command+ 
  
So here a description how I did setup my windows system to allow tests with a newer luatex without disturbing my standard system:

\begin{enumerate}
\item I created a folder \texttt{.../texlive/2017/bin-dev} beside the standard \texttt{bin}-folder. 
\item In this \texttt{bin-dev}-folder I copied the whole \texttt{win32} from the \texttt{bin}-folder.
\item I got \texttt{luatex-dev-w32.tar.xz} from \texttt{http://w32tex.org/} and copied the included \texttt{luatex.dll} and \texttt{lua52.dll} to the \texttt{bin-dev/win32}-folder.
    
\item In the  \texttt{bin-dev/win32}-folder I created a \texttt{texmf.cnf}-file with the line

   \verb+ TEXMFSYSVAR = $TEXMFROOT/texmf-var-dev+
   
\item Then I changed the windows \texttt{PATH}-variable and added the path to \texttt{.../bin-dev/win32;} at the begin.
    
\item As a last step I called on a command \verb+fmtutil-sys --all+. This creates the formats in a new  \texttt{texmf-var-dev} tree beside the standard \texttt{texmf-var}. 
\end{enumerate}   

With this installation it is possible to switch between the normal texlive and the one with the development luatex simply by changing the windows PATH variable. 





\end{document}



