summaryrefslogtreecommitdiff
path: root/support/tlaunch/tlaunch.tex
blob: bda23690631ff25679a48adce6c95d21fffa796f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
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}