diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/tlaunch/tlaunch.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/tlaunch/tlaunch.tex | 1066 |
1 files changed, 1066 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/tlaunch/tlaunch.tex b/Master/texmf-dist/doc/support/tlaunch/tlaunch.tex new file mode 100644 index 00000000000..a984e57a2eb --- /dev/null +++ b/Master/texmf-dist/doc/support/tlaunch/tlaunch.tex @@ -0,0 +1,1066 @@ +\documentclass[11pt,a4paper,oneside]{report} +% 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}} +\newcommand\vspc{\vspace{6pt}} +\newenvironment{ttdesc}{% + \def\descriptionlabel##1{\hspace\labelsep\ttfamily\selectfont ##1}% + \description}{\enddescription} +\hyphenation{head-ache} + +\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.1. + +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 document is about the \TL{} launcher. The first chapter +describes the launcher in general. + +The second chapter describes the launcher-based installation at the +\RUG, or Rijksuniversiteit Groningen, as an example of what can be +done with a launcher-based installation. + +Finally, since many \TeX{} developers spend as little time as they +can help in a Windows environment, I 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 all 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. + +Although at the moment the launcher contains no 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 the +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 +uses: +\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 Generating or updating the \XeTeX{} font cache, assuming + that the font cache directory is user-writable + \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 define scripts for doing +additional configuration and cleanup. + +\subsection{Location} +\label{sec:loc} + +One option is to place both the binary and the ini file in the +root of the \TL{} installation. Another is to place the binary in +\TL{} binary directory, \texttt{\emph{tlroot}/bin/win32}, and the +ini file where \texttt{kpsewhich} can find it, \emph{e.g.} in +\texttt{\emph{tlroot}/texmf-config/web2c}. + +The binary and the ini file should have the same first name. + +\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 the +filetype registry key is created but remains empty. + +The ini file can contain the following sections: + +\subsection{The Strings section} +\label{sec:strings} + +\begin{table}[tb] + \small\centering +\extrarowheight3pt\sffamily\noindent +\begin{tabular}{|>{\ttfamily}llP{2.3in}|} + \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{} 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 & 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. + +\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 strings 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, and should +not be tampered with; they may be required, or they are allowed to +stay empty. + +At least \texttt{TLCONFIG} 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 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, then 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: +\begin{verbatim} +[SC:XeTeX-fontcache] +command=fc-cache -v +splash=Creating or updating XeTeX font cache +\end{verbatim} +This item is included in the default ini file, although it may not +work out of the box on a multi-user installation. Section +\ref{sec:xecache} describes how to get it to work, and the +\texttt{tlaunchmode} script, see section \ref{sec:tlaunchmode}, will +take care of this automatically. + +\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} below +\item [FU:default\_editor] See section \ref{sec:edsel} below +\item [FU:about] An About box +\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 (see section +\ref{sec:utscripts} for the \texttt{SC:XeTeX-fontcache} entry): +\begin{verbatim} +[MN:Tools] +Editor choice=FU:editor_select +TeX Live Command Prompt=%comspec% /T "TeX Live" /e:on += +Generate/Refresh xetex font database=SC:XeTeX-fontcache + +[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} + +Here, three keywords are allowed: +\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 the process + searchpath.\par} +\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} +Since these are all default settings, one may as well omit this section. + +\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 the previous 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. + +Installation and uninstallation are triggered by command-line +parameters: + +\begin{ttdesc} +\item[user\_inst] Install the launcher for a single user +\item[admin\_inst] Install the launcher for all users +\item[uninst] Undo installation but leave the \TL{} + directory tree alone +\item[uninst\_all] Undo installation and remove the \TL{} directory + tree. This is the only option of these four which touches the \TL{} + installation itself. +\end{ttdesc} + +If there is a forgetter for the current user, both uninst options +will run it. A command-line option \texttt{silent} will ensure +that the forgetter will run without user interaction. + +Within the launcher, there are corresponding 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. + +\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 aborts if admin permissions are required but missing. + +It can be installed in the usual way: put it under the scripts +subdirectory of some texmf tree, run \texttt{mktexlsr} on that tree, +and copy in the \texttt{\emph{tlroot}\bslb bin\bslb win32} directory +\texttt{runscript.exe} to \texttt{tlaunchmode.exe}. + +Although at the moment there is no mechanism to make the path- and +file association settings in the ini file conform to those set +during a classic installation, those orginal settings are restored +when converting back to classic mode. + +\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 is about 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 the start menu, and anybody on the university +network can click the launcher shortcut and start using \TeX{}. + +The files in the \texttt{tlrug.zip} zipfile are tidied up versions +of those of the \RUG{} installation: compared to the files actually +in use, they benefit from hindsight and omit ugly workarounds for +specific local problems. + +\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. + +However, some people got confused that the generated \TL{} menu was +in one place, \emph{viz.} in the conventional Start / Programs menu, +and the initializer script in the centrally maintained `RUG menu'. + +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. 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 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. But this +is not the place to expand on my trials and tribulations with RES. + +\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 generating or updating a \XeTeX{} font cache; see Section + \ref{sec:xecache} +\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 did not put anything into the existing subdirectories of the \TL{} +installation, and put both the binary and the ini file in the root +of the installation. + +\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 are only vaguely aware of directories beyond their home +directory, I wrote a vbscript which emulates the MiKTeX +autoconfiguration for \TL{} and avoids 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. +\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 solution for the second problem is described in Appendix +\ref{sec:appreg}.\footnote{In the current \RUG{} installation, \TS{} + is started instead via a small wrapper program.} + +Note that TeXworks, Dviout and PSV[iew] are invoked via the \TL{} +runscript wrapper, which takes care of the searchpath, among other +things. + +\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. Its developers informed me what registry setting +would convince SumatraPDF otherwise, so that it would 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} + +{\sloppy At the time of writing, 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 was a + problem, a line +\begin{verbatim} +FC_CACHEDIR = $TEXMFVAR/fonts/cache +\end{verbatim} +in the file \texttt{\emph{tlroot}/\dbr texmf.cnf} moved the cache to a +user-writable location.\par} + +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 a less +error-prone solution is to leave this file alone and move the font +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. Any +non-null value would have had the same effect. + +\section{Fixing non-roaming filetype associations} +\label{sec:fixroam} + +Before RES (see Section \ref{sec:res}), and before the launcher, the +\TL-related filetype associations would not follow the user from +desktop to desktop; see also Appendix \ref{sec:wftas}. This was +solved with a batchfile which restored missing file associations. By +placing a shortcut to this batchfile in the Start / All Programs / +Startup menu, this batchfile would automatically run at +logon. However, RES made this workaround unnecessary. + +For situations where non-roaming file associations are still a +problem, I intend to add a `reassoc' mode to the forgetter. The +forgetter is already in place and knows how to parse the ini +file. With the reassoc option, the forgetter will silently recreate +missing filetypes. If \TL{} or the launcher is missing it will do +nothing. There will be an option in the ini file to enable or +disable creation of such a shortcut to the forgetter, in its role as +rememberer. + +\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 logon and logoff. 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. + +Unfortunately, these user-level filetype associations do not roam. +With the RES desktop management system, this is no longer a problem +for us. But a future version of the launcher will contain a +workaround for other environments; see section \ref{sec:fixroam}. + +\subsection{UserChoice} +\label{sec:userchoice} + +Apart from this scheme, 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. + +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/texlive2016/texmf-var +TEXMFCONFIG = $APPDATA/texlive2016/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} |