# [tex-live] windows doc modifications?

Karl Berry karl at freefriends.org
Wed Jun 11 10:49:58 CEST 2003

This is what the person who volunteered sent me, a few days ago.

Since it's regarding the Windows part of the documentation -- Fabrice and
Staszek, maybe you'd like to look at it?  I have not checked to see what
changes he's actually suggesting.

If it's good, we should at least send him a free cd :).

Thanks,
karl

Date: Fri, 06 Jun 2003 09:58:26 +0200
From: Christer Gustafsson <gustaf at powertech.no>
To: Karl Berry <karl at freefriends.org>
Subject: Re: [tex-live] Volunteer.

Karl,

I have read the section Installation and use under Windows' and used it
for the first time.

Attached you will find a suggested modification of the text. Some
English errors have been corrected (new ones introduced?). I have tried
to make the speak more direct and even removed some small things.

Since the file could not run (no figures, no \acro and other macros,
fonts missing) I first stripped it , modified, TeXed, and finally
restored by hand to what I think is correct.

Hopefully something could be of use.

Best regards/   Christer Gustafsson

Christer Gustafsson  Phone : +47 3282 0728
Grevlingvn. 49       Fax   : None
N-3029 Drammen       E-Mail: mailto:gustaf at powertech.no

% change history (started May 13th 2002)
% 2002/05/13: added tex-langafrican to list of collections
% 2002/05/14: corrected example files, other small errors noted by Volker
% 2002/05/18: win32 updates, by Fabrice
% 2002/05/25: remove mention of sizes, and bsr-interpolated; add Gutenberg
\documentclass{article}
\newsavebox{\warnbox}
\def\Q#1{\par\vskip6pt\leftline{#1}\par}
\setcounter{tocdepth}{2}
\pretolerance=1000
\tolerance=1500
\hyphenpenalty=400
\renewcommand{\topfraction}{0.85}
\renewcommand{\floatpagefraction}{0.86}
\renewcommand{\textfraction}{0.1}
\setcounter{topnumber}{5}
\setcounter{totalnumber}{5}
\def\eTeX{$\varepsilon$-\TeX}
\def\Dash{---}
\def\hyph{-}
\def\OMEGA{$\Omega$}
\def\bs{{\protect\normalfont\ttfamily\char'134}}
\DeclareRobustCommand{\cs}[1]{{\normalfont\ttfamily\char\\#1}}
\def\La{La}
\let\textsl\textit
\let\sl\it
\let\slfamily\itfamily
\def\ttdefault{cmtt}
\usepackage{tex-live}
\begin{document}
\section{Installation and use under Windows}
\label{sec:wintex}
The Win32 \TeX{} system applies to computers that
run Windows 9x,  ,  \acro{ME},
\acro{NT},  \acro{2K} or  \acro{XP}.
It includes the \textsf{Windvi} previewer, whose
documentation is found in \OnCD{texmf/doc/html/windvi/windvi.html}.

You use the  Win32 \TeX{} system either from your harddisk
or from the \CD{} as a ready-to-run system. In the former case you first
install it onto your harddisk and this is done by means of the
\texttt{TeXLive.exe} program.

In order to use it ready-to-run, your Windows system must be so set up,
that it uses the
Microsoft Joliet extensions for reading \CD s; simply look at the
\CD{} in Explorer and see whether it shows long, mixed-case, file
names. If it does not then you have to install the system onto your hard
disk.

\subsection[The TeXLive.exe program]{The \texttt{TeXLive.exe} program}

The \texttt{TeXLive.exe} program offers an integrated environment from
which you can perform various tasks such as to install
the Win32 \TeX{} system onto your hard disk or run the system directly
from the \CD{}. The program either auto-runs, when the \CD{} is inserted
into the reader, or you have to start it by double clicking on
\path|bin/win32/TeXLive.exe|
on the \CD{} from
the Explorer window. From the tool-bar of \texttt{TeXLive.exe} you
select:%

\begin{itemize}
\item Install \TeX{} on your hard disk,
\item Install TeX-oriented editors on your hard disk,
\item Install support packages on your hard disk (Ghostscript, NetPBM,
\ldots)
\item Do some maintenance on you \TeX{} system,
\item Remove the \TeX{} system,
\item Use \TeX{} off the CD{},
\item Cleanup the temporary files created on your hard disk when using
\TeX{} off the CD{},
\item Update some of the DLLs on your system,
\item Browse some documentation: TeXLive{} documentation, TUG web
pages, fpTeX web pages,
\item Run the cmdname{TeXdocTK} application to find specific documentation.
\end{itemize}

\subsection[Running \protect\TeXLive{} from the CD-ROM]{Running from
the \protect\CD{}}

You can run all the \TeX{} programs directly off the \CD.
This gives you
access to all macros and fonts immediately, but the \TeX{} system runs
slower than if you first install it onto the hard disk.
In order to work effectively, the system  needs to modify
environment variables and to create some small auxiliary directories
onto your hard disk.  These directories will contain necessary
configuration files which
allow you to modify program settings and to generate a necessary
format file'. Automatically generated font files
will be stored in these directories as well.

When you run \TeX{} from the \CD, then you do as follows:

\begin{enumerate}
\item from the menu, chose \verb|Explore CD-Rom|, then
\verb|Select a text editor|, a dialog box will open to select some
path|.exe|
program.

This program needs to be a \TeX{}-oriented editor. It must be able
to run the \TeX{} compiler, previewer and any other needed tool. If
you don't have one already installed on your system, you can install
one from the \CD{}; for  details see section~{\ref{sec:texlive-install}}.

\emph{There is no way  we can guess if the program you will
select is actually a text editor, so please be careful}.

Here is a list of frequently used \TeX{} editors:
\begin{center}
\begin{tabular}[ht]{ll}
GNU Emacs & path|c:/Program Files/NTEmacs/bin/runemacs.exe| \\
XEmacs & path|c:/Program Files/XEmacs/XEmacs-21.2/i586-pc-win32/xemacs.exe| \\
WinShell & path|c:/Program Files/WinShell/WinShell.exe| \\
WinEdt & path|c:/Program Files/WinEdt Team/WinEdt/WinEdt.exe|\\
TeXnicCenter & path|c:/Program Files/TeXnicCenter/TEXCNTR.exe|
\end{tabular}
\end{center}
The editor
selected will be memorized and used in future runs.

\item from the menu, chose \verb|Explore CD-Rom|, then
\verb|Run TeX off CD-Rom|. The environment will be modified, a small
temporary directory created and some configuration files copied
there. Thereafter the selected editor starts, and you
will be able to type in some text, let \TeX{} typeset it and finally

If Ghostscript is not detected on your machine, then
you will be warned
that the system might fail to render your DVI files.
Notice that you can install Ghostscript from
the path|Install|, path|Support| menu item. Refer to
section~\ref{sec:texlive-install} for details.

\item you can select a different text editor any time you want.

\item if you chose \verb|Cleanup CD-Rom setup|, everything \TeX{}
installed on your disk will be removed; even
editor.  However, any one of the extra packages that you may have
installed, e.g. \cmdname{WinShell} or \cmdname{NTEmacs},
will not be removed.
\end{enumerate}

\smallskip {\small\noindent \textbf{[For advanced users:]} You can
also use the small batch file \path|mkloctex.bat| which is called from
\path|setupw32| of the \CD.  From the Start menu select
Run', then browse the \CD drive and select \path|mkloctex.bat|. The
batch procedure requires two command-line parameters : the
letter of your \CD drive and the letter of the hard disk where you
want to install the \TeX\ directory, e.g. \verb+d:\setupw32\mkloctex.bat d c+.
When the installation is
run Windows 9x/\acro{ME}, then you will have to restart Windows in order
to complete.

\chgbigx{Readers comment: It is not explained for what the procedure {\tt mkloctex} is good
} }

\smallskip {\small\noindent \textbf{[For very advanced users:]}
The editor runs inside a modified environment. A temporary
TDS-compliant
texmf-tree is built in the temporary area created on your disk.
Here files that may be built on the fly, like pk font
files or format files, are stored.
Configuration files are copied from the \CD{}
to this texmf tree, so that you can edit them should need be.
The \path|ls-R| database for this texmf-tree is computed .
Then  the \texttt{PATH} and \texttt{TEXMFCNF} environment
variables are set locally, and the  editor is run in
this local environment. From within your editor\footnote{Actually, you can
state any other program than a text editor, and select your command
processor for example. You will then get a console with the right
settings to use \TeX{} from the \CD{}.}, you have access to a full
\TeXLive{} environment so that all files that are referenced will be
found on the \CD{}.}

\subsection{Installing editors or support packages to your hard disk}
\label{sec:texlive-install}

You may use the \path|TeXSetup.exe| program to install a
non-\TeX{} package. This may be an editor
such as \cmdname{WinShell} or \cmdname{NTEmacs},
or a support package like \cmdname{NetPBM}
(graphics formats conversion) or \cmdname{Ghostscript}.

Some of the packages are not free, or not with the
same meaning {\bf  What does this mean?} as for
the rest of the \CD{}. These packages can be installed through
the Internet. You need to enable an Internet connection in order to
install them. If you choose the \path|Enable Internet access| then
your system will be searched for an active Internet connection,
or start one if if none is found.
\emph{If your computer is not connected to the Internet,
then the timeout might be long, 30s or more}.

Do not request this option unless you know that your Internet access works.

At present only the most important
auxiliary
packages are available from the \CD{}.  These are
the editors \cmdname{NTEmacs} and \cmdname{WinShell}
and the general support programs \cmdname{Ghostscript} and
\cmdname{NetPBM}. It is \TeX{}4ht that requires \cmdname{NetPBM}.

\cmdname{XEmacs} is 50Mb, so be warned that it can take a lot of time

When you install these packages, \path|TeXSetup| works in
unattended mode. However, programs that have their own installer,
e.g. WinEdt or Ghostscript, will require your interaction.

Packages without an installer will be unpacked and configured
for your system. You will be required to specify the directory where
they will be installed. This directory must be the root
directory of the whole installation. {\bf Here I cannot understand
what is meant by the whole installation'} Assume that you wish to install
\cmdname{NTEmacs} into the directory \path/c:/Local/,
then that is the directory
that you shall specify.

\subsection{Installing the Win32 \TeX{}to your hard disk}

Insert the \TeXLive{} \CD, and wait for it to autostart. Then select
\verb|Install| from the menu that appears, then the subitem
\verb|TeXLive|. This invokes the
\path/TeXSetup.exe/\footnote{If the \CD{} does not autostart,
then run \path/TeXSetup.exe/ from the \OnCD{path/bin/win32/} directory.}
which
is a Windows wizard that will display several pages while running.

\begin{description}
\item[Welcome Page]
You can choose a \emph{quick} installation from
here.  In this case, the installation will run without any human
assistance from beginning to end, with all the default settings.
(Figure~\ref{graph:setup-src},
\ifnum \Status = 1
on the left%
\else\ifnum \Status=2
at the top%
\else
on the left%
\fi\fi
)
However, if you choose to install any support program that has its
own installer like \cmdname{WinEdt} or \cmdname{Ghostscript}, your intervention might be required.
If you have enough privileges  then you can decide
to install the \TeXLive{} for all users or for yourself only by
checking the appropriate box.

\begin{figure*}[!htb]
The \cmdname{TeXSetup} Wizard\hfill
Source directories for the TeXLive{} files

\begin{center}
\ifnum \Status=1
\includegraphics[width=.48\textwidth]{../pictures/setup-wizard.jpg}\hfill%
\includegraphics[width=.48\textwidth]{../pictures/source-for-texlive.jpg}
\else
\ifnum \Status=2
\includegraphics[bb=0 0 506 403]{../pictures/setup-wizard.gif}
\includegraphics[bb=0 0 506 403]{../pictures/source-for-texlive.gif}
\else
\includegraphics[width=.48\textwidth]{../pictures/setup-wizard}%
\hfill%
\includegraphics[width=.48\textwidth]{../pictures/source-for-texlive}
\fi
\fi
\caption{The \TeXLive{} setup wizard}\label{graph:setup-src}
\end{center}
\end{figure*}

\item[Source Page]
This page is a bit complex. It allows you to select two source
(Figure~\ref{graph:setup-src},
\ifnum \Status = 1
on the right%
\else\ifnum \Status=2
at the bottom%
\else
on the right%
\fi\fi
).
You will need a \emph{local source directory} and
possibly a \emph{remote source directory}.

Why do we need both these directories? All files of the
\TeXLive{} system are on the \CD{}, but some other  useful packages
are not. The reason for that is
either because space is too small or
their license is not compatible with the \TeXLive{}'s one.
other packages.

However, don't panic: the default parameters of the setup will allow
you to install a full system using the \CD{} only. Simply, you won't
have \file{WinEdt} for example, but you will be able to install it
later.

This leaves you with the following sources of files:
\begin{itemize}
\item the \CD{} or any similar flat tree of files, available through
some standard directory (this means the \CD{} can be mounted on
some remote machine and be made available through network    sharing),
\item a set of  \file{.zip} files (this is the case when you are
installing the
\fpTeX{} distribution),
\item the Internet, in which case the program \texttt{TeXLive.exe}
\end{itemize}
This option is available only if you enable Internet file
configure this Internet access by selecting to connect either using
Internet Explorer~5 \file{wininet.dll}, or using a direct connection (\texttt{ftp},
\texttt{http}).
% or using a proxy server.
%   Last, you can be assisted in defining the \emph{local source
%     directory} and \emph{remote source directory} which will be used
%   to copy the files onto your hard disk. The \texttt{browse} buttons
%   allow to select a directory for the former, and an url among a list
%   of mirrors for the latter.
\item[Root Page]
On this page, you will tell where you want the files to be
installed (Figure~\ref{graph:root-schm},
\ifnum \Status = 1
on the left%
\else\ifnum \Status=2
at the top%
\else
on the left%
\fi\fi
) .  Only the root directory really matters; the other ones
are set according to the root one. You may want to make
\path|$TEXMFEXTRA| point to some TDS compliant directory with other \TeX}{} files or assign a different value to \path|$HOMETEXMF|, which is set by default to whatever Windows think
is your HOME' location.
\begin{figure*}[!htb]
Root and directories\hfill%
Scheme selection
\begin{center}
\ifnum \Status=1
\includegraphics[width=.46\textwidth]{../pictures/root-of-installation.jpg}\hfill%
\includegraphics[width=.46\textwidth]{../pictures/scheme-selection.jpg}
\else
\ifnum \Status=2
\includegraphics[bb=0 0 506 403]{../pictures/root-of-installation.gif}
\includegraphics[bb=0 0 506 403]{../pictures/scheme-selection.gif}
\else
\includegraphics[width=.46\textwidth]{../pictures/root-of-installation}%
\hfill%
\includegraphics[width=.46\textwidth]{../pictures/scheme-selection}
\fi
\fi
\caption{\TeXLive-Setup: Root and directories / Schemes}\label{graph:root-schm}
\end{center}
\end{figure*}
\item[Get TPM Page]
files which describe collections and packages are retrieved
(possibly from the Internet), unzipped if needed and parsed.
\item[Schemes Page]
installation (Figure~\ref{graph:root-schm},
\ifnum \Status = 1
on the right%
\else\ifnum \Status=2
at the bottom%
\else
on the right%
\fi\fi
).  A scheme' is a large set of files targeted at some kind
of usage. There are 3 generic schemes for basic, recommended and
full installation. The other ones are devoted to LUGs (what GUST or
GUTenberg propose for their members) or applications (XML and
\TeX{}).
When a scheme is selected, it is still possible to refine the
selection by checking the appropriate box. If doing so, you will be
presented the packages-page to change your selection, else you will
\item[Packages Page]
Collections and packages are presented in a tree form
(Figure~\ref{graph:win32-support},
\ifnum \Status = 1
on the left%
\else\ifnum \Status=2
at the top%
\else
on the left%
\fi\fi
in the tree are dependency links. Collections \emph{depend on}
packages and maybe other collections, and it is the same for each
package. You can select any package or collection individually, but
your request will be granted only if the object is not requested by
another one which is selected. For example, you can't deselect
\texttt{tex-basic} without deselecting all the collections that
request it.

The \texttt{win32-support} collection displayed on the picture is Win32 specific. It
holds a number of bonus packages (Figure~\ref{graph:win32-support},
\ifnum \Status = 1
on the right%
\else\ifnum \Status=2
at the bottom%
\else
on the right%
\fi\fi
)   which can be installed
automatically and individually: \cmdname{Ghostscript}, the
\cmdname{PostScript}
interpreter, \TeX{} oriented editors, tools like \cmdname{Perl},
\LaTeX{}2HTML, etc. \emph{None of these packages are selected by
default}. Some of them have an Internet Explorer icon on their
right, which means that they are not on the \CD{} and that they will be
available only if you previously enabled  Internet
once: you need to select the packages individually}. This is to

needed: for each object, and for the set of those who are selected,
and also the disk space available on the partition selected for the
installation. Last, you can choose to install or not the
documentation files and source files associated with each package.
\item[Review Page]
You will find there a summary of your choices
(Figure~\ref{graph:review},
\ifnum \Status = 1
on the left%
\else\ifnum \Status=2
at the top%
\else
on the left%
\fi\fi
). It is still time to
go back to change them.
\begin{figure*}[!htb]
Packages Page\hfill%
Win32 Support
\begin{center}
\ifnum \Status=1
\includegraphics[width=.48\textwidth]{../pictures/package-selection}\hfill%
\includegraphics[width=.48\textwidth]{../pictures/win32-support}
\else
\ifnum \Status=2
\includegraphics[bb=0 0 506 403]{../pictures/package-selection.gif}\hfill%
\includegraphics[bb=0 0 506 403]{../pictures/win32-support.gif}
\else
\includegraphics[width=.48\textwidth]{../pictures/package-selection}%
\hfill%
\includegraphics[width=.48\textwidth]{../pictures/win32-support}
\fi
\fi
\end{center}
\caption{Packages Page / Win32 goodies}
\label{graph:win32-support}
\end{figure*}
\item[Files Copy Page]
The selected files are copied on your hard disk   (Figure~\ref{graph:file-copy},
\ifnum \Status = 1
on the right%
\else\ifnum \Status=2
at the bottom%
\else
on the right%
\fi\fi
). All the files not
remote source directory on the Internet. Then every package is
unpacked (if \path|.zip| files), or copied from the \CD{}.
\item[Configuration Page]  Several  packages  need some  configuration
step to  make them usable (Figure~\ref{graph:configuration},
\ifnum \Status = 1
on the left%
\else\ifnum \Status=2
at the top%
\else
on the left%
\fi\fi
). Also the  \TeXLive{} system  needs some post-processing  step
(format  files generation,  ls-R   databases generation, environment
variables, etc.). All these operations are  done there,
and some of them   can be lengthy.
\begin{figure*}[!htb]
\textbf{Review Page}\hfill%
\textbf{File Copy Page}
\begin{center}
\ifnum \Status=1
\includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill%
\includegraphics[width=.48\textwidth]{../pictures/file-copy}
\else
\ifnum \Status=2
\includegraphics[bb=0 0 506 403]{../pictures/review-settings.gif}\hfill%
\includegraphics[bb=0 0 506 403]{../pictures/file-copy.gif}
\else
\includegraphics[width=.48\textwidth]{../pictures/review-settings}\hfill%
\includegraphics[width=.48\textwidth]{../pictures/file-copy}%
\fi
\fi
\end{center}
\caption{Review Page / File Copy Page}
\label{graph:review}\label{graph:file-copy}
\end{figure*}
\item[Final Page] The installation being over, you may want to display
the Windows specific documentation (HTML format) and / or the log
file of the setup process (Figure~\ref{graph:final}
\ifnum \Status = 1
on the right%
\else\ifnum \Status=2
at the bottom%
\else
on the right%
\fi\fi
).  If it is needed (Win9x/WinME), then you will
\end{description}

\begin{figure*}[!htb]
\textbf{Configuration Page}\hfill%
\textbf{Final Page}
\begin{center}
\ifnum \Status=1
\includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill%
\includegraphics[width=.48\textwidth]{../pictures/congratulations}
\else
\ifnum \Status=2
\includegraphics[bb=0 0 506 403]{../pictures/configuration.gif}\hfill%
\includegraphics[bb=0 0 506 403]{../pictures/congratulations.gif}
\else
\includegraphics[width=.48\textwidth]{../pictures/configuration}\hfill%
\includegraphics[width=.48\textwidth]{../pictures/congratulations}%
\fi
\fi
\end{center}
\caption{Configuration Page / Final page}
\label{graph:configuration}\label{graph:final}
\end{figure*}

Please be aware that the choice of cluster size on DOS disk