[tex-live] TL 0206 notes

[Sebastian Rahtz]

here is a (possible) new section on using TL under Windows. would
anyone like to edit it and check it?

sebastian


\section{Installing the TeXLive CD under Windows}

\textbf{Important Note:} Installation needs at least 300MB, and the
cluster size on FAT partitions will make the package appear much
bigger, maybe as much as 500 MB, depending on your install choices.
If your hard drive is partitioned and you don't have enough space in
C:, you can use D: If you do, replace all occurrences of C: with D: in
the instructions below.

\textit{Allow at least an hour for the install.}

Before starting, it is a good idea to be connected to the internet so
you will have the option of installing supplementary programs from the
Web.  It is also a good idea to reboot so your computer is in a stable
state.

When you put the CD in the computer, the install process should start
automatically. If it doesn't, open the CD (from \textbf{My Computer}, right
click on the CD icon, select \textbf{Open}) and run the program
\textbf{TeXsetup.exe}, found in the \textbf{setupw32} folder on the CD. 

\subsection{The Install and Configuration Procedure}

Start by clicking on \textbf{Next}. (Do \textit{not} click ``Quick Install".)
You will be prompted to supply some information. In almost all cases, it is
best to accept the default by just pressing \textbf{Next}.
\begin{itemize}
\item For the Destination Folder (or ``root"), choose the default 
  \verb+C:\Local\TeX\+
  (Be sure never to use any path with an embedded space in its name.)
  The main ``texmf tree" will then be \verb+C:\Local\TeX\texmf+.
\item Choose the ``Recommended" setup. 
  If you have plenty of disk space, choose to install the documentation files,
  but you do not need to install the source files. Click \textbf{Next}. 
\item You will have the opportunity to install some supplementary programs
  from the CD and from the Web. Below are some possibilities;
  those denoted with an asterisk (*) are highly recommended. \\[6pt]
\begin{minipage}[t]{.46\textwidth}
>From the CD:\vspace{-6pt}
  \begin{description}\itemsep -2pt
    \item[\ *Netpbm] (graphics utilities)
    \item[\ *PS Utils] (utilities for PostScript files)
    \item[\ \hphantom{*}Emacs] (if you are already an emacs user) 
    \item[\ *WinShell] (friendly, easy to use editor/shell)
  \end{description}
\end{minipage}\hfill%
\begin{minipage}[t]{.5\textwidth}
>From the Web:\vspace{-6pt}
  \begin{description}\itemsep -2pt
    \item[\ \hphantom{*}WinEdt] (alternative to WinShell, shareware \~\$40)
    \item[\ *ImageMagick] (useful for graphics conversions)
    \item[\ *Ghostscript/GSview$^\dagger$] (view, convert PSfiles)
    \item[\ \hphantom{*}perl] (good for system management, 
      but it's \textit{big})
    \end{description}
\end{minipage}

$^\dagger$% 
Although not required, this (excellent) version of GSView
would like you to register and pay a small fee. If you don't register, each
time you open it, you have to close the registration box before
proceeding. If this is too annoying, you can either register or
install the older version from the CD instead.\par
\end{itemize}

A screen will appear showing your selections. If all looks OK, press
\textbf{Next}.  The install process then begins. The whole process takes
about 15-30 minutes, depending on the options you have selected.  The extra
programs are installed first; some will require you to answer some
questions or press \textbf{Next}.

\begin{itemize}
\item If you've chosen Ghostscript/GSView from the Web, a Ghostscript
window will appear after downloading. Click \textbf{Setup}. In the next
window, click \textbf{Install}.  Next, the GSView program will be
downloaded: click \textbf{Setup}, then \textbf{Next} several times, and
finally \textbf{Finish}. After a wait, the installation will
continue. Finally, in the GSView Install window, click \textbf{Exit}.

\item For the WinShell install, keep pressing \textbf{Next} and 
finally \textbf{Install} and then \textbf{Finish}.

\item Press \textbf{Next} when the installation process is finished.
\end{itemize}

After all the programs and files have finally been installed, it takes a few
minutes more for the configuration process. Be patient. (If you chose
the older version of Ghostscript/GSView from the CD, a configuration window
may start automatically. When asked, accept all the defaults;
when finished, click \textbf{Exit}.)

In the final window: 
\begin{itemize}
\item Do not check the box to read the documentation at this time.
\item Do not check the box to view the log file (unless you think something has
  gone wrong).
\item Do check the box to restart your computer.
\item Click the Reboot button to restart your computer. 
\end{itemize}
IT IS IMPORTANT TO REBOOT AT THIS POINT!
  
\subsection{Personal Configurations}
\subsubsection{WinShell}
Start this program from the Start menu or from the Desktop shortcut.
Go to \textbf{Options} \verb+->+ \textbf{Program Calls}.

\begin{itemize}\itemsep 0pt  
\item In the DVIWin tab, if the filename is \textbf{yap}, replace it with \textbf{windvi.exe}.
\item In Ghostview tab, make sure it gives the correct path for gsview32.exe:\\
\hspace*{1em} \verb+C:\ghostgum\gsview\gsview32.exe+ (for 6.0, the current
version)\\
  or \\
\hspace*{1em} \verb+C:\gstools\gsview\gsview32.exe+  (for the older version)
\end{itemize}\vspace{-12pt}
Click \textbf{OK}.

Note that the install process set all files with the \texttt{.tex}
extension to open with WinShell. Unless you plan to use another editor
(such as WinEdt or Emacs), this is appropriate.

Unfortunately, WinShell does not have a spell-checking feature.  However,
your installation included \textbf{Ispell}
(a spell checking program found on most \textsc{unix} systems). The
executable is in your path so \verb+ispell.exe+ will be found if you
invoke it from a DOS window. \textit{Ispell needs a folder called}
\verb+C:\tmp+; \textit{if it doesn't exist, you must create it.}  
If you installed documentation, look at 
\verb+C:\Local\TeX\texmf\doc\html\manpages\ispell.html+  for 
information on Ispell. (Otherwise, you
can find \verb+ispell.html+ on the CD.) 
If you rely on spell checking, you may want to
add an Ispell icon to WinShell. See Appendix B of this document for how to
do that.\\ For an excellent commercial (but inexpensive) spelling checker,
see \url{http:\\www.microspell.com}.

Appendix B also contains other information about using WinShell, such as:

\begin{itemize}
\item How to apply a bug fix you probably need 
\item How to print directly from WinShell 
\item How to use the Project feature for multiple-file documents  
\end{itemize}

WinShell also has on-line help, which you can access via the
$\bm{\underbar{?}}$ on the menu bar.

\subsubsection*{Dvips}
You need to change dvips so it uses PostScript Type 1 fonts for printing
rather than bitmap fonts and to use US letter as the paper size.

Open the file \verb+C:\Local\TeX\texmf-var\dvips\config\config.ps+
with any editor (WinShell will do fine).

\begin{itemize}
\item First scroll to where it says, ``To use the CM Type 1 fonts."\\
Uncomment (remove the \%) the following two lines, making sure the ``p'' is 
in column 1:\\
\hspace*{1em}    p +bsr.map\\
\hspace*{1em}    p +bakomaextra.map
\item Next, you need to change the paper size from European (A4) to US letter
  by making the US letter the first paper size mentioned in the file.
  Scroll to the group of lines beginning with ``@". Move 
  the appropriate lines so that this section begins with the lines:\\
\hspace*{1em}    @ letterSize 8.5in 11in\\
\hspace*{1em}    @ letter 8.5in 11in\\
\hspace*{1em}    @+ \%\%BeginPaperSize: Letter\\
\hspace*{1em}    @+ letter\\
\hspace*{1em}    @+ \%\%EndPaperSize
\item Save the file.
\end{itemize}


\subsubsection{Pdftex}
If you think you will use the program pdflatex to convert directly to
pdf format, edit the file\\
 \verb+C:\Local\TeX\texmf-var\pdftex\config\pdftex.cfg+
and change ``page\_width'' and ``page\_height'' to specify letter-size paper.
These entries should read:\\
\hspace*{1em}   page\_width 8.5 true in\\
\hspace*{1em}   page\_height 11 true in\\[6pt]
Save the file and exit the editor.   

\subsubsection{GSView}
You may need to change the papersize to US letter size. If so,
open GSView from the Start menu. (If you are asked to select the
Ghostscript version, select 6.01 if you have installed the newer version
from the Web, and 5.50 if you have installed the older version.) \\
>From the \textbf{Media} menu, select \textbf{Letter}.

Also, there are  menu settings that are supposed to give you the
most readable screen image:\\[4pt]
 From \textbf{Media} \verb+->+ \textbf{Display Settings}, 
set \textbf{Text Alpha} 
and \textbf{Graphics Alpha} both to 4 bits.

Note that the installation process has set all .ps and .eps files 
to automatically open with GSView.

For printing instructions, see section~\ref{printing} below.

\subsubsection{WinDvi}
Open it from the Start menu (Programs \verb+->+ TeXLive \verb+->+ DVI Viewer).  
Set it for US letter paper by going to \textbf{View} \verb+->+ \textbf{Options}
and next to \textbf{Papertype},
selecting US (8.5\verb+"+ x 11\verb+"+). 
Click \textbf{OK}. Also, the first time you 
view any .dvi file, you may find the magnification too large. Zoom out
until you get an appropriate size.
Exit Windvi.

To make .dvi files automatically open with Windvi, find a .dvi file, open
it, and when it asks what program to open with, scroll down the list and
look for Windvi. If it isn't in the list, click \textbf{Other} and browse
to find the location of windvi.exe
(\verb+C:\Local\TeX\bin\win32\windvi.exe+).  Click \textbf{Open}, then
click the box ``Always use this program to open file" and click
\textbf{OK}.

\subsection{Testing}
You can test WinShell by opening the file \verb+sample2e.tex+, found in
\verb+C:\Local\TeX\texmf\tex\latex\base\+. The LaTeX source should appear
on the screen. Process it by clicking on the LaTeX icon on the toolbar,
then view it by clicking on the Preview (Windvi) icon. 
At first, when you preview files with Windvi, it will create fonts because
screen fonts were not installed. After a while, you will have created most
of the fonts you use, and you will rarely see the font-creation window.
Return to WinShell and try dvips, then GSView.

\textbf{Hint for the future:} If a \LaTeX\ run stops because \LaTeX\ 
cannot find a file, you can press \textbf{Ctrl-z} to quit. 

\subsection{Printing}\label{printing}a
It is possible to print from Windvi, but there are some problems with
placement on the page that reportedly will be corrected in the next
version. Printing is faster and more reliable if you run dvips to make a
.ps file and then print from GSView. To print from GSView, first select
\textbf{Print...} from the \textbf{File} menu. A Print window will appear.

If you will be using a PostScript printer (such as any of the networked
campus printers), \textit{be sure to select \textbf{PostScript Printer}}.
In the newer version this is done in the ``Print Method" box at the
bottom left of the Print window. You can then select any of the printers
that you have previously intalled on your PC.  If you fail to check the
box for PostScript Printer, printing will not work.
  
If you will be using your own non-PostScript printer, select
\textbf{Ghostscript device} in the ``Print Method'' box, then click on the
button to the right labelled \textbf{djet500} and select your printer type
from the list that pops up. (In the older version of GSView, make sure
PostScript Printer is \textit{not} selected, then select your printer type
from the ``Device'' list.)
  
If you use WinShell and a PostScript printer, probably the most convenient
way to print is to add an icon to the WinShell toolbar that invokes dvips
in a way that sends the output directly to a default printer.  For detailed
instructions on how to do this, see Appendix B, \textit{More About WinShell}.

\section{Installing Additional \LaTeX\ Packages}
If you find you want additional \LaTeX\ packages that were not installed as
part of the ``recommended" install, you can get almost everything from the CD.

To add a package, open the \textbf{Start menu} and go to \textbf{Programs}
\verb+->+ \textbf{TeX Live} \verb+->+ \textbf{Maintenance} and select the
``Add TeX Package" option. The Installation window will come up, and after
clicking \textbf{Next}, select \textbf{Latex} from the list. Then you can
choose the package(s) you want to install and continue with the process.
Documentation for the packages (if you chose to install the documentation)
is in \verb+C:\Local\TeX\texmf\doc\latex\+.

When you add packages or fonts yourself, it's a good idea to put these
extra packages in your \mbox{texmf-local} tree. The texmf-local folder is
initially empty--- you will have to create the appropriate sub-folders for the
packages you add, mirroring the tree under the texmf folder. For example,
put the maple files in the folder\\
\verb+C:\Local\TeX\texmf-local\tex\latex\maple\+ and the thesis.cls file in the
folder\\ \verb+C:\Local\TeX\texmf-local\tex\latex\thesis\+.

\textbf{IMPORTANT NOTE:}
After you add more \verb+.cls+ or \verb+.sty+ files (or fonts), be sure to
rebuild the ls-R database (Start \verb+->+ Programs \verb+->+ TeXLive \verb+->+ Maintenance).
If you forget, your new thing won't be found.


\section{More About WinShell}}}
\subsection{Installing the Bug Fix}
Some versions of WinShell have a bug that results in \LaTeX\ not finding a
newly-created file until you close the file and then reopen it.
To check if you have this bug, look at the date on the file
\verb+winshell.exe+ (found in the folder \verb+c:\program files\winshell+). 
If it is older than 6/8/00 you need to install the bug fix. 

You can copy the bug fix from the CD
(\verb+D:\setup32\WinShellBugFix.zip+) and put it in your WinShell folder
(\verb+C:\Program Files\WinShell+). Next, check to see if you have an unzip
program such as \verb+unzip+ or \verb+winzip+. If you do, you can double
click on \verb+WinShellBugFix.zip+, and when it asks you whether to
overwrite winshell.exe, answer yes.

If you don't aleady have \verb+unzip+ or \verb+winzip+, you can copy unzip
from the CD (\verb+D:\support\unzip.exe+) to your directory
\verb+C:\Local+.  (To avoid getting just a shortcut instead of the program
itself, do not drag the file---use the copy/paste options from the 
right-click menu instead.)  After copying the \verb+unzip.exe+ file, open a DOS
window (Start \verb+->+ Programs \verb+->+ MSDOS Prompt), and enter the
following two commands to install the bug fix.
(Note that case doesn't matter in DOS commands.)\\[2pt]
\hphantom{M}\verb+cd  c:\"program files"\winshell+\\
\hphantom{M}\verb+c:\local\unzip.exe  winshellbugfix.zip+\\[2pt]
When it asks you whether to overwrite winshell.exe, answer yes.



\subsection{Using the Project Feature}
If your document is split into several files
(for example a thesis), look into WinShell's ``Project" feature. From the
\textbf{Project} menu, you give the project a name (e.g., Thesis), 
supply the name of the main (or root) file, and then ``add'' other
files. These filenames display on the left of the screen where you can
double click the names to view and switch between them. Clicking
the \textbf{\LaTeX} icon always processes the main file.

Note the icons on the toolbar for toggling the project space (on the left)
and the log space (at the bottom). If you are not using the Project
feature, you may want to toggle off the space on the left, using the full
screen width to display your file.

\subsection{Printing from WinShell to a PostScript Printer}

The Dvips icon on the WinShell toolbar puts the PostScript output in a file,
which you can then view with GSView and print from there if you choose.
However, it's convenient to add a WinShell ``program call'' to dvips which
sends the output directly to a designated PostScript printer. The steps
below show how to do this for the printer \textbf{vclw}; you should
substitute the name of your most frequently-used printer for \textbf{vclw}.
\begin{itemize}
\item Open WinShell, go to \textbf{Options} \verb+->+ 
\textbf{Program Calls} \verb+->+ \textbf{User defined}.
\item Click on \textbf{Tool 1} in the list on the right and fill in the 
fields to the left as follows:\vspace{-6pt}

\begin{quote}
Name: \verb+Print+\\
exe file: \verb+dvips+\\
cmd-line: \verb+ -D600 %m -o \\sambasrv\vclw+\\
Uncheck the box for ``DVIPS first''
\end{quote}%\vspace{-12pt}
\item Click \textbf{OK}
\end{itemize}\vspace{-10pt}

2. Add Print to the toolbar:\vspace{-14pt}
\begin{itemize}\itemsep 0pt
\item Go to  \textbf{Options} \verb+->+ \textbf{View} \verb+->+ \textbf{Customize}.
\item In the Category box, select \textbf{User-Programs}.
\item Select \textbf{Print} and drag it to the toolbar, placing it just to
  the right of the GSView icon.
\item You then have a choice of ``Image only'', ``Text only'', or ``Image and
Text''. The easiest is to select ``Text only'' and click \textbf{OK}.
You should then see \textbf{Print} on the toolbar. (If you prefer, you can
select ``Image only'', then ``Edit'', and edit the displayed picture to your
satisfaction.)
\end{itemize}
Now, to print a \LaTeX\ document, just click on the \textbf{Print} icon to
send to your selected printer. To use a different printer, you will need to
click on the \textbf{Dvips} icon to print to a file. Then click on the
GSView icon and use GSView to send to any printer you have installed on
your PC.

\subsection{Adding Ispell to WinShell}
1. Add Ispell to User Tools:
\begin{itemize}
\item Open WinShell, go to \textbf{Options} \verb+->+ 
\textbf{Program Calls} \verb+->+ \textbf{User defined}.
\item In the list on the right, click on \textbf{Tool 1} (or \textbf{Tool
    2} if you have already used \textbf{Tool 1}) and fill in the 
fields to the left as follows:\vspace{-6pt}
\begin{quote}
Name: \verb+Ispell+\\
exe file: \verb+ispell+\\
cmd-line: \verb+ -t -d american %c.tex+\\
Uncheck the boxes for ``LaTeX first'' and ``DVIPS first''
\end{quote}%\vspace{-12pt}
\item Click \textbf{OK}
\end{itemize}\vspace{-10pt}

2. Add Ispell to the toolbar:\vspace{-14pt}
\begin{itemize}\itemsep 0pt
\item Go to  \textbf{Options} \verb+->+ \textbf{View} \verb+->+ \textbf{Customize}.
\item In the Category box, select \textbf{User-Programs}.
\item Select \textbf{Ispell} and drag it to the toolbar, placing it just to
  the right of the GSView icon (or the last icon you added).
\item You then have a choice of ``Image only'', ``Text only'', or ``Image and
Text''. The easiest is to select ``Text only'' and click \textbf{OK}.
You should then see \textbf{Ispell} on the toolbar. (If you prefer, you can
select ``Image only'', then ``Edit'', and edit the displayed picture to your
satisfaction.)
\end{itemize}

Now, when you have a \LaTeX\ document open, you can click on
\textbf{Ispell} to perform spell checking. Ispell will open another window
and display the first misspelled word on the left with the filename on the
right. Below that you will see the context in which the misspelling appears;
often several suggestions for replacements are also displayed. To replace
the word, enter the number corresponding to the desired replacement. Other
possible responses are listed below; for example, you can press the space
bar to ignore the misspelled word. For more information on Ispell, read the
man page: \verb+C:\Local\TeX\texmf\doc\html\manpages\ispell.html+.

Note that when you replace a word, you will not see the correction in your
WinShell window until you close the file (click the X in the upper right
corner) and then open it again (use the File menu).