summaryrefslogtreecommitdiff
path: root/support/tlaunch/tlaunch.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/tlaunch/tlaunch.tex')
-rw-r--r--support/tlaunch/tlaunch.tex1110
1 files changed, 1110 insertions, 0 deletions
diff --git a/support/tlaunch/tlaunch.tex b/support/tlaunch/tlaunch.tex
new file mode 100644
index 0000000000..bda2369063
--- /dev/null
+++ b/support/tlaunch/tlaunch.tex
@@ -0,0 +1,1110 @@
+\documentclass[11pt,a4paper,oneside]{report}
+
+% narrow margins, otherwise same layout as default
+\AtBeginDocument{%
+ \paperwidth\textwidth
+ \advance\paperwidth48bp
+ \oddsidemargin-48bp
+ \paperheight\textheight
+ \advance\paperheight48bp
+ \advance\paperheight\headheight
+ \advance\paperheight\headsep
+ \advance\paperheight\footskip
+ \topmargin=-48bp
+ \pdfpagewidth=\paperwidth
+ \pdfpageheight=\paperheight
+}
+
+\makeatletter
+\long\def\@makecaption#1#2{%
+ \vskip\abovecaptionskip
+ \sbox\@tempboxa{\small \textbf{#1:} #2}%
+ \ifdim \wd\@tempboxa >\hsize
+ {\small \textbf{#1:} #2\par}
+ \else
+ \global \@minipagefalse
+ \hb@xt@\hsize{\hfil\box\@tempboxa\hfil}%
+ \fi
+ \vskip\belowcaptionskip}
+\makeatother
+
+% fonts
+\usepackage{tgpagella}
+\let\slshape\itshape
+\usepackage[TS1,T1]{fontenc}
+
+\usepackage{array,textcomp,graphicx}
+\setcounter{secnumdepth}{2}
+\setcounter{tocdepth}{2}
+\usepackage[%
+ raiselinks=false,%
+ colorlinks=true,%
+ bookmarksnumbered=true,%
+ bookmarksopen=true,%
+ bookmarksopenlevel=1%
+]{hyperref}
+\pagestyle{headings}
+
+\newcolumntype{P}[1]{%
+ >{\raggedright\hspace{0pt}\arraybackslash}p{#1}}
+\def\TL{\TeX~Live}
+\def\fta{filetype association}
+\def\FTA{Filetype association}
+% if bold small caps available:
+\def\mysc#1{{\rmfamily\textsc{#1}}}
+% if bold small caps unavailable:
+%\def\mysc#1{\textsc{\textmd{#1}}}
+\def\GUI{\mysc{gui}}
+\def\RUG{\mysc{rug}}
+\def\UWP{\mysc{uwp}}
+
+\def\TNC{TeXnicCenter}
+\def\TS{TeXstudio}
+
+\def\XeTeX{Xe\TeX}
+\def\dbr{\discretionary{}{}{}}
+\let\bsl\textbackslash
+\def\bslb{\bsl\discretionary{}{}{}}
+%\def\hkcu{HKEY\_\dbr CURRENT\_\dbr USER}
+\def\hkcu{\textsc{hkcu}}
+%\def\hklm{HKEY\_\dbr LOCAL\_\dbr MACHINE}
+\def\hklm{\textsc{hklm}}
+%\def\hkcr{HKEY\_\dbr CLASSES\_\dbr ROOT}
+\def\hkcr{\textsc{hkcr}}
+\newenvironment{ttdesc}{%
+ \def\descriptionlabel##1{\hspace\labelsep\ttfamily\selectfont ##1}%
+ \description}{\enddescription}
+\hyphenation{head-ache work-space}
+
+\title{TLaunch: a launcher for a \TL{} system}
+\author{Siep Kroonenberg}
+\begin{document}
+\maketitle
+\clearpage
+\thispagestyle{empty}
+\null\vfill
+{\small\parindent=0pt
+This manual is for tlaunch, the \TL{} Launcher, version 0.5.3.
+
+Copyright \textcopyright{} 2017 Siep Kroonenberg.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved. This file is offered as-is,
+without any warranty.\par}
+\clearpage
+\thispagestyle{empty}
+% let physical pages match logical ones
+\setcounter{page}{3}
+\tableofcontents
+
+\chapter{The launcher}
+\label{chap:launcher}
+
+\begin{figure}
+ \centering
+ \includegraphics[width=.7\linewidth]{figures/tlaunch_window}
+ \caption{A possible Launcher window}
+ \label{fig:launcher}
+\end{figure}
+
+\section*{About this document}
+
+This manual documents the \TL{} Launcher. The first chapter
+describes the launcher in general, its facilities, its ini file and
+its command-line parameters.
+
+The second chapter describes the launcher-based installation at the
+\RUG, or Rijksuniversiteit Groningen, as an example
+launcher-based installation.
+
+Since many \TeX{} developers spend as little time as they can help
+in a Windows environment, I also added an appendix with Windows
+background information.
+
+\section{Introduction}
+\label{sec:intro}
+
+I designed the \TL{} launcher for the Windows \TL{} installation on
+our university network, which contains \TL{} itself plus several
+other \TeX-related applications. The launcher provides a single
+access point to all this software, and to related local and online
+resources.
+
+The launcher also takes care of configuration: at first run, \TL{}
+is added to the searchpath, and relevant filetype associations are
+set up.
+
+This means that the launcher rather than the classic \TL{} installer
+takes care of Windows-specific configuration. Which is a good
+thing if the \TL{} directory tree is on a shared network drive, or
+if a \TL{} installation has to be copied to many workstations.
+
+Filetypes, menus and buttons and pre- and post configuration scripts
+are defined in a standard Windows ini file. The format of this file
+is described in section \ref{sec:config} of this chapter. The
+supplied ini file provides something more or less equivalent to a
+classic Windows \TL{} installation.
+
+\subsection{Localization}
+\label{sec:localize}
+
+Although at the moment the launcher lacks proper support for
+localization, most of the user interface strings are defined in the
+ini file and can be replaced with strings in other languages.
+
+\section{Modes}
+\label{sec:modes}
+
+\subsection{Normal mode}
+\label{sec:normal}
+
+In a normal run, the launcher displays a window with a menu or a
+series of buttons or both, see figure \ref{fig:launcher}. For
+anything launched via these controls, \TL{} is prepended to its
+process searchpath irrespective of the system- or user
+searchpath; see Appendix \ref{sec:env} on Windows searchpath
+handling.
+
+\subsection{Initializing}
+\label{sec:init}
+
+On first run, tlaunch creates file associations and prepends \TL{} to
+the user searchpath, see appendix~\ref{sec:env}. Such configuration
+allows users to start up their \LaTeX{} editor by double-clicking a
+\LaTeX{} file in their file manager, bypassing the launcher
+altogether.
+
+On first run, the launcher also creates a renamed copy of itself and
+a renamed modified copy of the configuration file to a directory
+inside the user's profile. This pair of copies serves as
+\emph{forgetter}, see below. tlaunch registers this forgetter as an
+uninstaller under Windows.
+
+\subsection{Forgetting}
+\label{sec:forget}
+
+Since a network- or multi-user \TL{} installation can be uninstalled
+by others, it is desirable that the configuration done on first run
+can be reversed without the presence of the original \TL{}. The
+forgetter takes care of this.
+
+The launcher detects from its location whether it should run normally
+or as forgetter.
+
+It is also possible to undo configuration from within a normal run
+if the ini file defines a button- or menu control for it.
+
+\section{Using scripts}
+\label{sec:scripts}
+
+External scripts may run on demand, as the action associated with a
+button or a menu control; see section \ref{sec:utscripts}. Scripts
+may also run automatically, as supplemental initialization or
+cleanup; see the \texttt{pre\_config}, \texttt{post\_config} and
+\texttt{pre\_forget} variables in table \ref{tab:strings}. Examples:
+\begin{itemize}
+\item Forgetting a previous release of \TL{} before configuring the
+ current one. This only makes sense for a centrally-managed \TeX{}
+ installation, where it is known what \TeX{} installation came
+ before.
+ \item Giving \TeX works some spelling dictionaries
+ \item Writing configuration data for non-\TL{} components
+ \item Adjusting \XeTeX{} font configuration, see Section
+ \ref{sec:xecache}
+\end{itemize}
+
+\section{The ini file}
+\label{sec:config}
+
+The ini file defines the menu items and buttons of the graphical
+interface. These controls can start up \GUI{} programs or run
+utility scripts, or run some predefined functions. The ini file also
+defines filetype associations, and may specify scripts for doing
+additional configuration and cleanup.
+
+\subsection{Location}
+\label{sec:loc}
+
+In \TL, the binary is in the \TL{} binary directory,
+\texttt{\emph{tlroot}/bin/win32}, and the ini file is in
+\texttt{\emph{tlroot}/texmf-dist/web2c}. The installer may have
+created a modified higher-priority copy in
+\texttt{\emph{tlroot}/texmf-var/web2c}. A custom
+\texttt{tlaunch.ini} in \texttt{\emph{tlroot}/texmf-config/web2c}
+will override either. In this case, the filename database should be
+updated.
+
+Another option is to place both the binary and the ini file in the
+root of the \TL{} installation.
+
+\subsection{Encoding}
+\label{sec:enc}
+
+The launcher tries to guess the encoding used, and accepts
+ASCII, UTF-8 and Windows' UTF-16, with or without BOM. If all else
+fails, it tries ANSI with the system default code page.
+
+\subsection{Syntax}
+\label{sec:synt}
+
+The ini file is a regular Windows ini file with sections,
+definitions and comment lines.
+\begin{itemize}
+\item A section starts with a line containing the section name
+ enclosed in square brackets `\texttt{[}' and `\texttt{]}'. It ends
+ at the start of the next section or at the end of the file.
+\item A definition line consists of a line
+ \texttt{\emph{key}=\emph{value}}.
+\item A comment line starts with `\texttt{;}'.
+\end{itemize}
+
+The ini file is processed in one go, which means that everything
+must be defined before it is used. The ordering of the list below of
+possible sections satisfies this requirement.
+
+However, it is not necessary that everything that is referred to
+actually exists; if a menu- or button control refers to a
+non-existent file, the control is quietly left out, and if the
+\texttt{COMMAND} of a filetype refers to a non-existent file then
+neither the filetype registry entry nor any control for it will be
+created.
+
+The ini file can contain the following sections:
+
+\subsection{The Strings section}
+\label{sec:strings}
+
+\begin{table}[tb]
+ \centering
+{\small
+\extrarowheight3pt\sffamily\noindent
+\begin{tabular}{|>{\ttfamily}llP{2in}|}
+ \hline
+ & DEFAULT & MEANING \\
+ tlroot & predefined & root of the \TL{} installation \\
+ version & predefined & release year \\
+ tlperl & predefined & path of the built-in Perl binary \\
+ tlwperl & predefined & same for the \GUI{} Perl binary \\
+ java & predefined & Java binary, if found \\
+ tlconfig & required & directory for the launcher's user data, see \emph{e.g.}
+ sections \ref{sec:strings} and Appendix \ref{sec:known_configs} \\
+ tlname & \texttt{TeX Live \%version\%} & used for \emph{e.g.}
+ window title and uninstaller `DisplayName' \\
+ customed\_progid & \texttt{TL.customed} & Filetype
+ for external, user-selected editor, see section \ref{sec:fta} \\
+ pre\_config & empty & optional program or script to be run before
+ first-time initialization \\
+ post\_config & empty & optional program or script to be run after
+ first-time initialization \\
+ pre\_forget & empty & optional program or script to be run before
+ undoing initialization \\
+ announce & empty & optional text to display \\[3pt]
+ \hline
+\end{tabular} \\[3pt]
+Note. All process environment variables, \emph{e.g.}
+\texttt{\%appdata\%}, are accessible while the
+launcher parses the ini file. Variable names are case-insensitive.\par}
+
+\caption{Strings with a special meaning in the ini file}
+\label{tab:strings}
+\end{table}
+
+In this section arbitrary strings can be defined to be used later
+during parsing. The names of the string variables are
+case-insensitive, their values are not. Various strings have a
+special meaning, see Table \ref{tab:strings}. Their values may be
+predefined, \emph{i.e.} they are set by the launcher before
+processing the ini file; they may be required, or they are allowed
+to stay empty.
+
+At a minimum, the \texttt{TLCONFIG} string should be defined in the
+ini file. This is the directory for launcher user files such as the
+forgetter. A few suggestions:
+ \begin{itemize}
+ \item \texttt{\%UserProfile\%\bsl.texlive\%version\%\bslb tlaunch},
+ \emph{i.e.} under the common root of \texttt{\%TEXMFVAR\%} and
+ \texttt{\%TEXMFCONFIG\%}
+ \item \texttt{\%appdata\%\bslb tlaunch\bslb\%version\%}; see Appendix
+ \ref{sec:known_configs}
+ \item or maybe \texttt{\%localappdata\%\bslb tlaunch\bslb\%version\%} if
+ \TL{} is installed on the local system
+ \end{itemize}
+
+\subsection{Sections for filetype associations (FTAs)}
+\label{sec:fta}
+
+In Windows, an extension is associated with a filetype and a
+filetype is associated with a program. An extension can also have
+alternate filetypes associated with it, which may show up if you
+right-click a file and select `Open with\textellipsis'. More on
+filetypes in appendix \ref{sec:wftas}.
+
+A filetype section has as name the string `\texttt{FT:}' followed by
+the filetype name. An example of a filetype section:
+
+\begin{verbatim}
+[FT:TL.TeXworks.edit.%VERSION%]
+COMMAND="%tlroot%\bin\win32\TeXworks.exe"
+;SHELL_CMD="%tlroot%\bin\win32\TeXworks.exe" "%1"
+;ICON="%tlroot%\bin\win32\TeXworks.exe,0"
+;NAME=TeXworks
+EXTENSIONS=.tex .cls .sty
+;PRIMARY=1
+;PATH_PREFIX=0
+\end{verbatim}
+
+The commented lines are optional and represent default values.
+
+\begin{ttdesc}
+\item [COMMAND] is the command to start the program.
+\item [SHELL\_CMD] is the command to open a file. The default is
+ \texttt{COMMAND} with `\texttt{~"\%1"}' appended.
+\item[ICON] is the icon to be used in GUI file managers. The default
+ is \texttt{COMMAND} with `\texttt{,0}' appended, without a
+ space. If there is no such icon then a fall-back icon will be
+ used; see \emph{e.g.} the right-most icon in Figure
+ \ref{fig:launcher}.
+\item[NAME] is only used for \LaTeX{} editors, in the
+ editor-selection window, see section \ref{sec:edsel}. If not
+ specified, it will be derived from the program filename.
+\item[EXTENSIONS] is the list of extensions that should have the
+ filetype as primary or secondary association.
+\item[PRIMARY] is default 1. If set to 0, then the program only
+ shows up in the Open with... dialog. Mainly of interest for the
+ bitmap2eps utility. See appendix \ref{sec:wftas} on primary and
+ secondary filetypes.
+\item[PATH\_PREFIX] is default 0. If set to 1, Windows will
+ prepend \TL{} to the program's searchpath. The launcher will only
+ do this if \texttt{COMMAND} is a bare or quoted filename, without
+ options or parameters; see Appendix \ref{sec:appreg}.
+\end{ttdesc}
+
+\subsection{Sections for utility scripts}
+\label{sec:utscripts}
+
+A batchfile or command-line program can be declared in a
+utility-script section. If a button or menu item invokes such a
+script, standard output is intercepted and displayed in a dialog box
+when the script has completed. Standard error is also captured, but
+shows up only in the log file \texttt{\%TEMP\%\bslb TeXLive\_\dbr
+ Launcher.\dbr log}. A splash text is displayed while the script is
+running. The default value for the splash text is `Working...'. An
+example adapted from the \RUG{} installation:
+\begin{verbatim}
+[SC:TNC_config]
+command=cscript "%TLROOT%\rugscripts\tnc_config.vbs" "%tlroot%"
+;splash=Reconfiguring TeXnicCenter...
+\end{verbatim}
+In this example, the script takes just a moment, so there is no
+point in defining a splash text.
+
+\subsection{The built-in functions}
+\label{sec:fun}
+
+The following functions are available:
+\begin{ttdesc}
+\item [FU:quit] Terminate the launcher
+\item [FU:clear] Undo all configuration and terminate
+\item [FU:initialize] Undo all configuration, terminate and
+ restart. This forces re-initialization.
+\item [FU:editor\_select] See section \ref{sec:edsel}
+\item [FU:default\_editor] See section \ref{sec:edsel}
+\item [FU:about] An About box
+\item [FU:uninst\_all] See section \ref{sec:lbased}
+\item [FU:uninst] See section \ref{sec:lbased}
+\end{ttdesc}
+
+\subsection{Menus and buttons}
+\label{sec:controls}
+
+The visible interface of the launcher consists of an optional menu
+with dropdown submenus and an optional row of buttons. There should be
+at least one button or one submenu with one entry.
+
+A submenu is defined in a section with name `\texttt{MN:}' followed
+by the submenu name, and the row of buttons is defined in a section
+named `\texttt{BUTTONS}'. A button- or a menu item has as key the
+string to be displayed and as value one of the following:
+\begin{itemize}
+\item A filetype. This invokes its \texttt{COMMAND}.
+\item A utility script. This also invokes its \texttt{COMMAND}.
+\item `\texttt{SO:}' (Shell Open) followed by a document or
+ \textsc{url}. The document or url will be opened in its default
+ program.
+\item A predefined function, see section \ref{sec:fun}.
+\item An arbitrary command.
+\end{itemize}
+In a submenu section, a sole `\texttt{=}' will produce a separator
+line. In the button section, it will do nothing.
+
+{\sloppy
+Example buttons- and submenu sections:
+\begin{verbatim}
+[MN:Tools]
+Editor choice=FU:editor_select
+TeX Live Command Prompt=%comspec% /T "TeX Live" /e:on
+=
+(Re)configure TeXnicCenter=SC:TNC_config
+
+[MN:Documentation]
+All TeX Live documentation by package=SO:%tlroot%\doc.html
+TeX and LaTeX Q & A=SO:http://tex.stackexchange.com/
+
+[BUTTONS]
+LaTeX Editor=FU:default_editor
+PostScript Viewer=FT:TL.PSView.view.%VERSION%
+Quit=FU:quit
+\end{verbatim}
+\par}
+
+\subsection{The General section}
+\label{sec:gen}
+
+This section is optional. Four keywords are allowed, of which the
+first two correspond to \TL{} installer options:
+\begin{ttdesc}
+\item[Filetypes] Allowed values are
+ \begin{itemize}
+ \item \texttt{none}: do not set or change filetype associations
+ \item \texttt{new}: create filetype associations only if they do
+ not override existing ones; default
+ \item \texttt{overwrite}: create filetype associations regardless
+ of existing ones
+ \end{itemize}
+\item[searchpath] {\sloppy Allowed values are 0 (leave searchpath
+ alone) and 1 (add \TL{} to the searchpath; default). See
+ appendix \ref{sec:env}. In any case, when a program is started
+ from the launcher it will have \TL{} prepended to its process
+ searchpath.\par}
+\item[remember] Allowed values are 0 (do nothing) and 1 (arrange
+ that \TeX-related filetype associations are restored on
+ login). This may be desirable in a Roaming Profiles setup, see
+ sections \ref{sec:roam} and \ref{sec:noroam}.
+\item[keeptemps] Allowed values are 0 (delete temporary files;
+ default) and 1 (keep them). This is a debug option for running
+ external scripts. In most cases however, the contents of the
+ temporary files are copied to the log file \texttt{\%TEMP\%\bslb
+ TeXLive\_\dbr Launcher.log} anyway.
+\end{ttdesc}
+
+An example general section:
+\begin{verbatim}
+[General]
+FILETYPES=new
+SEARCHPATH=1
+KEEPTEMPS=0
+\end{verbatim}
+The above values are the defaults.
+
+\section{Editor choice}
+\label{sec:edsel}
+
+\begin{figure}
+ \centering
+ \includegraphics[width=.8\linewidth]{figures/custom_ed}
+ \caption{Editor selection with a file browser for a custom editor}
+ \label{fig:ed_sel}
+\end{figure}
+If a filetype has \texttt{.tex} among its supported extensions, the
+launcher considers it an editor. On initialization, the first one
+becomes the default, unless \texttt{PRIMARY} is set to 0 and there
+is another candidate with \texttt{PRIMARY} 1. If in the
+\texttt{General} section \texttt{FILETYPES} is set to \texttt{none}
+or \texttt{new}, then an existing file association for \texttt{.tex}
+files will not be overwritten.
+
+The function \texttt{FU:default\_editor} invokes the default editor
+if there is one. The function \texttt{FU:editor\_select} invokes a
+dialog for selecting a default editor; the options are the ones
+defined in the ini file, the current default and selecting one via a
+file browser dialog, see figure \ref{fig:ed_sel}.
+
+If the new editor is selected via the file browser, it will be
+assigned to the filetype \texttt{TL.customed} and this filetype will
+become the default for \texttt{.tex} files. It is possible to
+configure another filetype string in the ini file, \emph{e.g.} one
+which includes the \texttt{\%VERSION\%} string.
+
+Appendix \ref{sec:userchoice} explains why a \texttt{.tex} file
+might still get opened in another editor.
+
+\section{Launcher-based installations}
+\label{sec:lbased}
+
+It seems possible to do away with much of the Windows-specific code
+of the current installer. To this end, I added install and uninstall
+options to the launcher. Installation merely means creating a Start
+menu entry for itself and to register itself as uninstaller.
+
+In installation mode, it is assumed that the launcher and its ini
+file are already in place as part of the regular \TL{}
+installation.
+
+The launcher can be invoked with the following command-line
+parameters:
+
+\begin{ttdesc}
+\item[user\_inst] Install the launcher for a single user. This
+ includes doing the first-time initialization as in a regular
+ invocation.
+\item[admin\_inst] Install the launcher for all users
+\item[uninst] Undo installation but leave the \TL{}
+ directory tree alone. Also runs the forgetter for the current
+ user silently, if it exists.
+\item[uninst\_all] Undo installation and remove the \TL{} directory
+ tree. Also runs the forgetter for the current user silently, if it
+ exists. This is the only option of these four which touches the
+ \TL{} installation itself.
+\item[remember] Recreate filetype associations, see sections
+ \ref{sec:roam} and \ref{sec:noroam}.
+\item[silent] Do not ask for confirmation and do not pop up
+ messages. Output is still written to the log file, at
+ \texttt{\%TEMP\%\bslb TeXLive\_\dbr Launcher.\dbr log}.
+\end{ttdesc}
+The \texttt{user\_inst\_silent} and \texttt{admin\_inst\_silent} are
+also still available.
+
+The non-silent uninstall options both ask which of the two uninstall
+options is desired. the only difference between them is which button
+is the default.
+
+The new launcher mode option of the 2017 \TL{} installer invokes the
+launcher with one of the silent installer options.
+
+Within the launcher, there are functions \texttt{FU:uninst\_all} and
+\texttt{FU:uninst} which can be assigned to a menu- or button
+control. If necessary, the launcher will pop up a \textsc{uac}
+prompt and restart in elevated mode.
+
+The \TL{} installer may create a higher-priority
+\texttt{tlaunch.ini} if for either the path setting option or the
+file associations option a non-default value was selected. This will
+happen even if launcher mode was not selected.
+
+\subsection{The tlaunchmode script}
+\label{sec:tlaunchmode}
+
+The included Perl script tlaunchmode can convert a local \TL{}
+installation between classic and launcher-based. Run with a
+parameter `on', the script turns launcher mode on; with `off' it
+reverts the installation to classic, and anything else prints a
+brief help message. It is already part of \TL.
+
+It aborts if admin permissions are required but missing.
+
+\subsection{\TeX{} Live Manager}
+
+Nothing special has been done for the \TL{} Manager. It can be
+assigned to a menu- or button control, although this makes little
+sense for a centrally managed network installation. If necessary it
+will automatically pop up a \textsc{uac} prompt.
+
+\chapter[The launcher at the RUG]{The launcher at the
+ Rijksuniversiteit Groningen}
+\label{chap:rug}
+
+\begin{figure}[tb]
+ \centering
+ \includegraphics[width=.7\linewidth]{figures/tlaunch_rug}
+ \caption{The launcher at the Rijksuniversiteit Groningen}
+ \label{fig:launcher_rug}
+\end{figure}
+
+This chapter deals with the launcher-based \TL{} installation at the
+\RUG{} (Rijksuniversiteit Groningen) and the environment in which it
+operates.
+
+Our \TL{} installation resides on the network. The \TL{} Launcher
+is available via a centrally managed start menu. From any Windows
+workstation connected to the network, one can click the launcher
+shortcut in this menu and start using \TeX{}.
+
+The files in the \texttt{tlrug.zip} zipfile are tidied up versions
+of those of the \RUG{} installation; they omit some ugly workarounds
+for specific local problems and also benefit from hindsight.
+
+\section{Historical}
+
+An earlier solution for \TL{} was implemented with a patchwork of
+scripts in various languages. An initialization script created
+filetype associations, Start Menu shortcuts and modified the
+searchpath. It made use of the built-in Perl and its \TL{} modules.
+
+When between 2013 to 2014 the university transitioned to centrally
+managed desktops, using the RES workspace management
+system\footnote{Real Enterprise Solutions,
+ \texttt{https://res.com/}}, I created the launcher. Because
+previously users might run the initializer / installer when they
+really want to run the already initialized / installed \TL, I opted
+this time for a launcher that configures itself automatically,
+without requiring a separate initialization step.
+
+For speed of development, a first version was written in the
+AutoIT\footnote{\texttt{https://\dbr www.\dbr autoitscript.\dbr
+ com/}} scripting language. AutoIT has good access to Windows'
+internals, and comes with a utility which packages a script with a
+AutoIT runtime into a self-contained executable. The AutoIT versions
+did not use an ini file; everything was coded into the script
+itself.
+
+For the 2015 \TL{} release, I finally had a usable C version, in
+which all configuration was read from an ini file.
+
+\section{RES desktops}
+\label{sec:res}
+
+The RES system synthesizes a desktop or workspace for the user on
+logon. Personal settings are selectively captured, stored in a
+database and restored on re-logon; the settings part of RES can be
+considered an alternative implementation of the roaming profiles
+described in Appendix \ref{sec:roam}.
+
+This desktop is also available remotely, which works reasonably well
+most of the time.
+
+For \TL, I submit a wish list of settings to be captured to the
+workspace management people, and they enter everything into the RES
+system. Unfortunately, the RES system has its quirks, and what I
+expect to happen is not always what actually does happen. Some of
+these problems are mentioned later on.
+
+\section{Components of the \RUG{} \TeX{} installation}
+\label{sec:comps}
+
+Various third-party programs are incorporated into our \TL{}
+installation. Below are some details.
+
+Most \TeX-related software does not have deep hooks into the
+system. Even if applications require elevated permissions to
+install, usuallly they can simply be copied to another location and
+work fine from there. This is the case with \emph{e.g.} \TL{}
+itself and with \TS.
+
+The add-ons are:
+\begin{itemize}
+\item Additional editors: \TNC{} and \TS{}
+\item The pdf viewer SumatraPDF
+\item The Java-based bibliography manager JabRef
+\item The epspdf \GUI{} with bundled single-file Tcl/Tk runtime
+\item The pseudo-wysywyg LyX \LaTeX{} editor
+\end{itemize}
+There are also controls for:
+\begin{itemize}
+\item browsing the \TL{} installation
+\item a command-prompt with \TL{} as the first directory on the
+ searchpath
+\item some manuals from the \TL{} installation
+\item links to \TeX-related websites
+\end{itemize}
+Such menu items are simply created by single lines in the
+ini file.
+
+There are no controls for the \TL{} manager or for uninstalling.
+
+Figure \ref{fig:launcher_rug} shows buttons for some of the
+additional software. Along the bottom of the window is an
+announcement text, which is an optional string item in the ini
+file. The Help menu item opens a help text in the configured default
+text editor -- probably Notepad.
+
+\section{Directory organization}
+\label{sec:rugdirs}
+
+There is a directory under the \TL{} root containing all the
+extras. There is another subdirectory for the various scripts. All
+paths in both the ini file and the scripts are relative to the root
+of the installation.
+
+I placed both the binary and the ini file in the root of the
+installation, but did not place anything into existing \TL{}
+subdirectories.
+
+\section{Fixes for add-ons}
+\label{sec:fixes}
+
+Some of the add-ons needed a bit more work than just copying the
+installed program directory to its place under the \TL{} root:
+
+\subsection{\TNC}
+\label{sec:tnc}
+The original university installation was based on MikTeX, with
+\TNC{} as editor. In 2008 I replaced MikTeX with \TL, and \TNC{}
+with the more up to date \TS{} editor. Since I did not want to force
+anyone to switch editors, I also kept \TNC{} around.
+
+While \TNC{} can autoconfigure itself nicely for MikTeX, it asks
+\TL{} users a series of questions about what is where. Since many
+users do not know their way around outside their home directory, I
+wrote a vbscript which emulates the MiKTeX autoconfiguration for
+\TL{} and spares the user awkward questions.
+
+\subsection{\TS}
+\label{sec:ts}
+
+\TS{} autoconfigures itself fine, but there were still two problems:
+\begin{enumerate}
+\item By default, it checks whether there is a more recent version,
+ while users are not in a position to do an update themselves.
+\item With our current desktop management software, programs do not
+ get the user searchpath appended to their process searchpath.
+\end{enumerate}
+The first problem is solved during first-time initialization of the
+launcher. If there is no \TS{} configuration file, then one is
+created with just the setting not to check for updates. If there is
+one, the update check option is edited to be off. Either way, there
+is no impact on other settings.
+
+A possible solution for the second problem is described in Appendix
+\ref{sec:appreg}, but I opted instead to start \TS{} via a small
+wrapper program.
+
+Note that the \TL{} runscript wrapper does already take care of the
+searchpath for TeXworks, Dviout and PSV[iew].
+
+\subsection{SumatraPDF}
+\label{sec:sumatra}
+
+In the absence of any registry settings, SumatraPDF assumes that it
+is a portable setup, and tries to write user configuration to its
+own directory. Following advice from its developers, I created a
+registry setting to tell SumatraPDF otherwise, and let it write
+its configuration data to the user's profile.
+
+Checks for updates are disabled in a similar way as for \TS.
+
+\subsection{LyX}
+\label{sec:lyx}
+
+On first start, LyX can take several minutes to take stock of its
+environment and figure out what it can use. During this time, it is not
+even clear that anything is happening.
+
+To prevent this delay, the post-config script copies a pre-generated
+configuration directory to the user's profile.
+
+In the LyX installation itself, in the file
+\texttt{\emph{lyxroot}\bslb Resources\bslb lyxrc.dist}, the setting
+\texttt{\bsl path\_prefix} has been rephrased to only contain paths
+relative to \texttt{\$LyXDir}, which is the root of the LyX
+installation.
+
+\section{Moving the \XeTeX{} font cache}
+\label{sec:xecache}
+
+The default location of the \XeTeX{} font cache in \TL{} is
+\texttt{\$TEXMFYSVAR/\dbr fonts/\dbr cache}, \emph{i.e.}
+\texttt{\emph{tlroot}/\dbr texmf-var/\dbr fonts/\dbr cache}. In a
+multi-user or network install, this location is not
+user-writable. Since this may be a problem,\footnote{\emph{E.g.} if
+ the set of Windows fonts changes, \XeTeX{} will try to update the
+ font cache but will not be able to save the updated cache.} a line
+\begin{verbatim}
+FC_CACHEDIR = $TEXMFVAR/fonts/cache
+\end{verbatim}
+in the file \texttt{\emph{tlroot}/\dbr texmf.cnf} will move the
+cache to a user-writable location. The \texttt{tlaunchmode} script,
+see section \ref{sec:tlaunchmode}, will take care of this
+automatically.
+
+Since I generate the \TL{} installation on a Linux system, the
+configured \TL{} font paths in \texttt{\$TEXMFSYSVAR/\dbr fonts/\dbr
+ conf/\dbr fonts.conf} do not match the target installation. Of
+course this generated file can be hand-edited, but I preferred to
+leave this file alone and move the font cache configuration files
+also to a user-writable location with another line:
+\begin{verbatim}
+FONTCONFIG_PATH = $TEXMFVAR/fonts/conf
+\end{verbatim}
+in \texttt{\emph{tlroot}/texmf.cnf}. A per-user font configuration
+is then created by a line
+\begin{verbatim}
+"%TLROOT%\tlpkg\tlperl\bin\perl.exe"
+ "%TLROOT%\tlpkg\tlpostcode\xetex.pl"
+ install "%TLROOT%" skip_gen 2>NUL
+\end{verbatim}
+(one line) in a post-config script, see section \ref{sec:scripts}.
+
+The last parameter, \emph{viz.} \texttt{skip\_gen}, suppresses
+actual cache generation, since that might take quite some time and
+only benefit \XeTeX{} users. Any non-null value would have had the
+same effect.
+
+\appendix
+
+\chapter{Windows issues}
+
+\section{User and system}
+\label{sec:usersys}
+
+Microsoft has wised up a lot security-wise. When Windows XP
+appeared, the line of Windows 9\emph{x} windowses made place for
+slightly crippled versions of the NT-based professional
+editions. Even for Home editions there is now a separation between
+per-user and system-wide settings and files. Since Windows Vista,
+this separation is much more strictly enforced, and even
+administrators have to take an extra step, such as clicking yes to a
+UAC\footnote{User Account Control} prompt, before they can do
+anything deemed risky.
+
+\section{Roaming}
+\label{sec:roam}
+
+On a Windows domain network, it can be arranged that users have more
+or less the same desktop, whatever computer within the network they
+happen to be working on. This is accomplished by either `folder
+redirection', \emph{i.e.} defining network locations for certain
+dedicated directories (see `Known Folders' in Appendix
+\ref{sec:known}), or by copying user data back and forth between
+workstation and network on logoff and logon. There may also be a
+dedicated network share for user documents which is accessible from
+any computer, and which may do double duty as home to redirected
+folders.
+
+\section{Windows configuration}
+\label{sec:wconfig}
+
+Some Windows configuration can only be stored in the registry, in
+particular file associations, see section \ref{sec:wftas} below, and
+environment variables, including the searchpath.
+
+Other configuration can be stored either in the registry or in
+configuration files, at the discretion of the developer.
+
+\subsection{Registry locations}
+\label{sec:hives}
+
+We have to deal with three locations or hives within the registry:
+\begin{itemize}
+\item \texttt{HKEY\_\dbr
+ CURRENT\_\dbr USER}, or \hkcu{} in short, for user-specific settings
+\item \texttt{HKEY\_\dbr
+ LOCAL\_\dbr MACHINE}, or \hklm{} in short, for system-level settings
+\item A third hive, \texttt{HKEY\_\dbr CLASSES\_\dbr ROOT}, or
+ \hkcr, will be described in the next subsection.
+\end{itemize}
+
+\subsection{Filetype associations}
+\label{sec:wftas}
+
+The basic idea is that an extension has a default filetype or
+ProgID, and this filetype in its turn can define commands such as
+open, edit, view or print. For example, the extension \texttt{.jar}
+has as its filetype or ProgID \texttt{jarfile}, and for the ProgID
+\texttt{jarfile} the open command is defined as \emph{e.g.}\par
+{\footnotesize
+\begin{verbatim}
+"C:\Program Files (x86)\Java\jre1.8.0_45\bin\javaw.exe" -jar "%1" %*
+\end{verbatim}
+}\normalsize
+Extensions can also have secondary file associations. These are
+the ones showing up when right-clicking a file and selecting `Open
+with\textellipsis'.
+
+Filetype associations exist in per-user and system-wide flavors:
+
+{\sloppy
+\begin{itemize}
+\item User-specific filetype associations are stored in
+ \hkcu\texttt{\bslb Software\bslb Classes}
+\item System-level filetype associations are stored in
+ \hklm\texttt{\bslb Software\bslb Classes}
+\item The effective filetype associations are stored in
+ \texttt{HKEY\_\dbr CLASSES\_\dbr ROOT} or \hkcr, which is a
+ runtime merge of the above two branches. Settings in \hkcu{}
+ override corresponding settings in \hklm.
+\end{itemize}}
+
+{\sloppy For example, the link from \texttt{.jar} to
+ \texttt{jarfile} is can be read from the \hkcr\texttt{\bslb.jar}
+ key and the link from \texttt{jarfile} to actual commands from the
+ \hkcr \texttt{\bslb jarfile} key.\footnote{In some situations,
+ reading from \hkcr{} proved not entirely reliable. Therefore, \TL{}
+ always explicitly checks first \hkcu{} and if necessary
+ \hklm.}\par}
+
+Secondary filetype associations can be stored in a subkey of the
+extension subkey, either the \texttt{OpenWithList} (obsolete) or
+the \texttt{OpenWithProgIds} subkey.
+
+\subsection{Non-roaming filetype associations}
+\label{sec:noroam}
+
+{\sloppy
+Unfortunately, these filetype associations do not roam. With the
+RES desktop management system at our university, this is no longer a
+problem for us. For other setups, the launcher contains a workaround
+which is activated by the \texttt{remember} ini file setting, see
+section \ref{sec:gen}.\par}
+
+When this is set to 1, the launcher will during first-time
+initialization place a shortcut to the forgetter in the Start / All
+Programs / Startup menu, with a `remember' parameter added. This
+will cause the forgetter to run automatically at logon with a
+remember parameter. With this parameter, it will just silently
+recreate the filetype associations and then terminate.
+
+\subsection{UserChoice}
+\label{sec:userchoice}
+
+{\sloppy
+Apart from the registry settings under the two \texttt{\bslb
+ Software\bslb Classes} keys, choices made by the user in the `Open
+with\textellipsis' dialog are stored under subkeys of \hkcu
+\texttt{\bslb Software\bslb Microsoft\bslb Windows\bslb
+ CurrentVersion\bslb Explorer\bslb FileExts\bslb \emph{.ext}}, the
+exact subkey(s) depending on the Windows version. Such entries
+should have priority over the ones described above, and do roam.\par}
+
+Windows 8 and later may pop up a dialog asking with what program to
+open a file even if there is already an answer in a
+\texttt{Software\bslb Classes} key. The answer will be a preference
+stored under the \texttt{FileExts} key mentioned above. This should
+alleviate the problem of non-roaming filetype associations.
+
+The launcher will not touch these registry entries.
+
+\subsection{Application registration}
+\label{sec:appreg}
+
+An application which is registered may have a better chance to be listed
+as an alternative in the `Open with...' dialog.
+
+{\sloppy The currently recommended way to register an application is
+ under the \texttt{SOFTWARE\bsl Microsoft\bslb Windows\bslb
+ CurrentVersion\bslb App Paths\bslb \emph{basename}} key
+ (\texttt{basename} including \texttt{.exe} file extension). The
+ default entry of such a key is the full path of the
+ file. Therefore, only one file with a given basename can have such
+ a registration entry.\par}
+
+The other entry of interest under this key is `Path', which is a
+searchpath fragment that should be prepended to the regular
+searchpath, just for this program. This prefixing happens if the
+program is opened by Windows Explorer. The path prefix is ignored
+if the program is started from the command-line or from the
+launcher.
+
+For filetypes defined in the launcher ini file, the launcher creates
+an application registration key for the associated program, but only
+if the \texttt{COMMAND} field is just a filename or -path, with or
+without quotes.
+
+{\sloppy
+Applications can also be registered under \hkcr \texttt{\bslb
+ Applications\bslb \emph{basename}}, but here is no option to set a
+searchpath prefix. Microsoft considers this location obsolete.\par}
+
+\subsection{The searchpath and other environment variables}
+\label{sec:env}
+
+Environment variables are also stored in the registry: per-user
+variables in \hkcu\texttt{\bslb software\bslb environment}, system
+environment variables in \hklm\texttt{\bslb System\bslb
+ CurrentControlSet\bslb Control\bslb Session Manager\bslb
+ Environment}.
+
+For the searchpath, the effective searchpath consists of the system
+\texttt{\%Path\%} variable, with the user \texttt{\%Path\%} variable
+\emph{appended} if it exists, with an intervening `;' of
+course. Therefore, \emph{directories on the system searchpath have
+ priority over the user searchpath}.
+
+Other environment variables from these registry locations behave as
+expected: the user version has priority if both exist. Note that the
+names of environment variables are case-insensitive.
+
+{\sloppy
+Various pieces of system information, such as \texttt{COMPUTERNAME}
+and \texttt{CommonProgramFiles}, are not explicitly stored as
+environment variables, but are nevertheless available as such.\par}
+
+\section{ Windows Known Folders}
+\label{sec:known}
+
+Windows has an elaborate and ever expanding system of `Known
+Folders': \emph{e.g.} Program Files, ProgramData, User Profile
+(HOME directory), Start Menu, Desktop, Documents, Downloads,
+History, SendTo, Templates, Administrative Tools, Pictures, Music,
+Videos, Account Pictures, Cookies, Favorites, and dozens more, many
+of them both in a system- and a user version.
+
+Sometimes a known folder is not a real folder but a virtual one, and
+for some known folders, 64-bits applications and 32-bits
+applications view things differently.
+
+There are APIs which associate known folder identifiers to actual
+directory paths.
+
+With Windows Vista a new API has been introduced, and the old one
+declared obsolete. One change for the better: the directory
+name `Documents and Settings' has been replaced with simply `Users'.
+
+This API also gives access to other properties, such as the
+localized names shown in Windows Explorer, such as `Programme'
+instead of `Program Files', or `Gebruikers' instead of `Users'.
+
+Microsoft recommends to avoid hard-coded paths, and to place
+everything under known folders instead. One benefit is at least that
+files in known folders have a better chance of surviving system
+upgrades.
+
+\subsection{Programs}
+\label{sec:knownprogs}
+
+The directory reserved for programs is normally \texttt{c:\bslb
+ Program Files}. On 64-bit systems, this directory is reserved for
+64-bits programs, and \texttt{c:\bslb Program Files (x86)} for
+32-bits programs. Directories under one of the Program Files folders
+are automatically write-protected.
+
+\subsection{Configuration- and data files}
+\label{sec:known_configs}
+
+There are also preferred locations for per-user- and system-wide
+program data. For Windows Vista and later these are:
+\begin{itemize}
+\item {\sloppy For user-specific settings, typical locations are
+ \texttt{\%appdata\%}, which is usually
+ \texttt{\%userprofile\%\bslb \%appdata\%\bslb roaming}, and
+ \texttt{\%localappdata\%}, which is usually
+ \texttt{\%userprofile\%\bslb \%appdata\%\bslb local}. For a
+ networked workstation, \texttt{\%appdata\%} may be relocated or
+ backed up to a location on the network, and be available to the
+ user on any workstation.\par}
+\item {\sloppy For system-wide settings there is \texttt{\%ProgramData\%},
+ usually \texttt{C:\bsl ProgramData}.\par}
+\end{itemize}
+On Windows Vista and later, these directories normally do \emph{not}
+have spaces in their path. They are by default also hidden.
+
+\subsection{\TL{} choices}
+\label{sec:known_tl}
+
+It is clear that \TL{} does not try very hard to conform to all
+Microsoft's recommendations, and I do not think that it should. A
+couple of obvious advantages of the existing default path
+\texttt{C:\bslb texlive\bslb \emph{yyyy}}\footnote{Regular users can
+ create directories in the root directory of the C:-drive, even
+ though they cannot create regular files there.} are the absence of
+spaces, and the locale-independence of the path seen in Windows
+Explorer.
+
+In this default location, \TL{} will not be write-protected
+automatically. For a system-wide installation, the \TL{} installer
+itself will take care of this.
+
+{\sloppy
+As to user files, it should be ok to put \texttt{\$TEXMFCONFIG},
+\texttt{\$TEXMFVAR} and tlaunch's \texttt{\%TLCONFIG\%} under
+\texttt{\%appdata\%} or \texttt{\%localappdata\%}. For the first
+two, this could also be done after the fact with a couple of lines
+in \texttt{\emph{tlroot}/texmf.cnf}, \emph{e.g.}:
+\begin{verbatim}
+TEXMFVAR = $APPDATA/texlive2017/texmf-var
+TEXMFCONFIG = $APPDATA/texlive2017/texmf-config
+\end{verbatim}
+There they will be hidden, but most users will never interact
+directly with files in these directories anyway.\par}
+
+\end{document}