%!TEX TS-program = xelatex 
%!TEX encoding = UTF-8 Unicode samples, and choose one of the font names 


\documentclass[12pt, oneside]{amsart}
\usepackage{geometry}                % See geometry.pdf to learn the layout options. There are lots.
\geometry{letterpaper}                   % ... or a4paper or a5paper or ... 
%\geometry{landscape}                % Activate for for rotated page geometry
\usepackage[parfill]{parskip}    % Activate to begin paragraphs with an empty line rather than an indent
\usepackage{graphicx}
\usepackage{amssymb}
\usepackage{epstopdf}
\DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `dirname #1`/`basename #1 .tif`.png}
\usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue, 
            citecolor=blue, urlcolor=blue]{hyperref}
            
\usepackage{fontspec,xltxtra,xunicode} 
\defaultfontfeatures{Mapping=tex-text} 
%\setromanfont{Hoefler Text} 
%\setromanfont{Optima}
\setromanfont{Baskerville}
\setsansfont[Scale=MatchLowercase] {Gill Sans} 
\setmonofont[Scale=MatchLowercase] {Andale Mono} 

            
\title{The \TeX{} Live Manager}
%\author{The Author}
%\date{}                                           % Activate to display a given date or no date

\begin{document}
%\twocolumn[\maketitle]
 \maketitle
%\section{}
%\subsection{}



\TeX{} Live Manager is an exciting new addition in \TeX{} Live 2008. It allows users to update installed packages in \TeX{} Live over the web, to install new packages, and to configure \TeX{} Live. The software is primarily the work of Norbert Preining, who is also the main implementor of the infrastructure in \TeX\ Live which makes these capabilities possible. 

The hard work in \TeX{} Live Manager is done by Unix command line programs which are part of \TeX{} Live. These programs can be accessed in three independent ways: through a fully native Macintosh application named \TeX{} Live Utility, through the command line program tlmgr which is essentially \TeX{} Live Manager itself, or through an X11 GUI application accessed using tlmgr.
You can think of \TeX{} Live Utility in the context of Safari, Apple's Web Browser. Apple provided a refined and useful front end, but the hard work is actually done by open source code, Konqueror's KHTML engine to render web pages,  and  KDE's JavaScript engine to run JavaScript.

Similarly, \TeX{} Live Utility by Adam Maxwell provides a native Macintosh interface to the  \TeX{} Live Manager routines; most users will administer TeX Live using Maxwell's program.  \TeX{} Live Utility requires Mac OS X 10.5, Leopard, and provides access to a subset of the commands available via tlmgr; it is described in the first section below. Users who are running an earlier system can read the remaining sections and interact with \TeX{} Live Manager via tlmgr or the X11 GUI application. 

\section{\TeX{} Live Utility}

%The program \TeX{} Live Utility is the most recent addition to this suite. It was written by Adam Maxwell and is under active development; in its current state the program is stable and recommended for most users. \TeX{} Live Utility requires system 10.5, Leopard, so users running earlier systems should skip this section and use the command line tool or X11 GUI interface. \TeX{} Live Utility only accesses selected features of \TeX{} Live Manager, but the tasks required by most users are most easily performed with the utility; advanced users will want to consult the tlmgr documentation.

Like all good Macintosh programs, \TeX{} Live Utility is mostly self explanatory. When the program starts, it will consult a \TeX{} Archive CTAN server to determine whether updates are available for the currently active \TeX{} distribution. If so, these updates will be listed. Click the button ``Update All'' at the top of the window to install these updates. 

The \TeX{} User Group provides two Macintosh \TeX{} distributions based on \TeX{} Live --- the full \TeX{} Live 2008 in MacTeX-2008 and the much smaller BasicTeX-2008 for users with slow download connections. The ``Update All'' action will only update packages contained in a particular distribution, so users of BasicTeX-2008 will not suddenly discover that a large number of new packages have been added to their installation. A separate \TeX{} Live Utility command can be used to add packages to a distribution.

Sometimes the program will discover that the command line programs in  \TeX{} Live Manager themselves need updating. Theoretically tlmgr can update itself, but some users have reported problems with these updates, so \TeX{} Live Utility updates tlmgr in a special manner guaranteed to avoid these problems.  If tlmgr needs updating, a dialog pane will appear when \TeX{} Live Utility starts with the title ``Critical updates available'' followed by some text ending with the words  ``... the TeX Live installer packages listed here must be updated first.'' Click the ``Update'' button in this pane to install the tlmgr updates. After installing these critical updates, the program will list the remaining available updates; click ``Update All'' to install them.

\TeX{} Live Utility provides extensive output from tlmgr during updating. One error message reads ``tlmgr does not support --machine-readable yet; ad-hoc parsing will be used''. This message is harmless and can be ignored.

Note that the ``Action'' menu for \TeX{} Live Utility has an item named ``Change Paper Size...'' Use this command to reconfigure paper size in \TeX.

At the top of the \TeX{} Live Utility window, a tab switches between ``Manage Updates'' and ``Manage Packages''. Change this tab to ``Manage Packages'' to see a list of all \TeX{} Live Packages. Use the ``Show Info'' command to read information about particular packages. Use the search field to search for a particular class, tex, or style file and discover the package containing it. Select a package and click ``Install'' to install a new package.

Recall that CTAN is the TeX archive, available through a large number of servers across the world. By default, \TeX{} Live Utility obtains updates from  \url{http://mirror.ctan.org/}. This is actually a multiplexer, which distributes requests to various mirror servers so no one server is overloaded. The actual server being used is shown at the bottom of the \TeX{} Live Utility window. Sometimes a particular mirror may be unavailable or not up to date. Running \TeX{} Live Utility again will usually reach a different mirror and succeed.





\section{The Command Line Tool: tlmgr}

The command line tool is a script included in \TeX{} Live 2008 called the ``\TeX{} Live Manager'', but following Unix traditions these words are condensed to ``tlmgr''. To see a list of commands, open Apple's Terminal in \path{/Applications/Utilities} and type
\begin{verbatim}
     tlmgr --help
\end{verbatim}

When tlmgr wants to modify files in \path{/usr/local/texlive/2008}, it must have root permission. In these cases it must be called using
\begin{verbatim}
     sudo tlmgr ...
\end{verbatim}
rather than simply
\begin{verbatim}
     tlmgr ...
\end{verbatim}
Here ``$\ldots$'' indicates extra parameters for whatever action is to be performed.

For example, typing ``tlmgr arch list'' is fine, but you must type ``sudo tlmgr arch add sparc-solaris''. The first command consults the server's database to discover what kind of binaries are supported: i386-linux, sprac-solaris, i386-openbsd, etc., and to indicate which binaries have been installed on your Mac, usually universal-darwin. But the second command must be used if you want to download and install the Sun Solaris binaries as well.  (Most ordinary users would never want to do that.)


When tlmgr runs, it needs to know a location where updates for \TeX{} Live are available. The default location is stored in your local copy of \TeX{} Live. This location might be a svn copy of \TeX{} Live on the local machine, or a DVD disk inserted into the drive, but usually it will be the location of a web server for updates. The current server address is \url{http://mirror.ctan.org/systems/texlive/tlnet/tldev}, so that is the default option installed by beta copies of Mac\TeX{}-2008. 

You can inspect the current default with the command
\begin{verbatim}
     tlmgr option location
\end{verbatim}
You can change the default location using the command
\begin{verbatim}
     sudo tlmgr option location new-location
\end{verbatim}
For example, when \TeX{} Live 2008 is finalized, the last ``.tldev'' in the server address mentioned earlier is expected to become ``2008.'' You can change the default to this location with the command
\begin{verbatim}
     sudo tlmgr option location \\ 
          http://mirror.ctan.org/systems/texlive/tlnet/2008
\end{verbatim}


\section{Important tlmgr Commands for Updating}

We now come to the central commands you'll use. The command
\begin{verbatim}
     tlmgr list
\end{verbatim}
lists all packages available on the server, and adds an initial ``i'' to packages already installed. This will produce a very long list of output. An example output line selected at random reads
\begin{verbatim}
     i crossreference: Crossreferences within documents.
\end{verbatim}
Here the ``i'' says that this package is already installed, the name of the package is ``crossreference"'' and a short description follows. You can get more information by typing
\begin{verbatim}
     tlmgr show crossreference
\end{verbatim}
This produces the following output:
\begin{verbatim}
     Package:   crossreference
     Category:  Package
     ShortDesc: Crossreferences within documents.
     LongDesc:  The package defines cross-references (essentially `grand' 
         label references),  which may be listed in a table of 
         cross- references.
     Installed: Yes
\end{verbatim}
To see which installed packages are out of date and could be updated, type
\begin{verbatim}
     tlmgr update --list
\end{verbatim}
To update a particular package, say crossreference, type
\begin{verbatim}
     sudo tlmgr update crossreference
\end{verbatim}
To update several packages, say crossreference, xmlplay, and york-thesis, type
\begin{verbatim}
     sudo tlmgr update crossreference xmlplay york-thesis
\end{verbatim}
To make a dry run, so that tlmgr will tell you what it is going to do without actually doing it, type
\begin{verbatim}
     tlmgr update --dry-run crossreference xmlplay york-thesis
\end{verbatim}
To update all packages which are out of date, type
\begin{verbatim}
     sudo tlmgr update --all
\end{verbatim}
and to check what will happen first, type
\begin{verbatim}
     tlmgr update --dry-run --all
\end{verbatim}
This updating mechanism in tlmgr is very intelligent; it understands dependencies and updates additional files if necessary. It also understands situations where configuration scripts must be run after the update process. For example, if you install a new version of pdftex then new format files will be made after updating occurs, and if you install a new font then the mapfile database will be updated.

In \TeX{} Live, several different style files are often packaged together. To find relevant packages, several search commands are provided. For instance, suppose you want packages which deal with paragraph formatting. The command
\begin{verbatim}
     tlmgr search paragraph
\end{verbatim}
gives
\begin{verbatim}
     bigfoot - Footnotes for critical editions.
     edmargin - Multiple series of endnotes for critical editions.
     footmisc - A range of footnote options.
     genmpage - Generalization of LaTeX's minipages.
     hanging - Hanging paragraphs.
     ibycus-babel - Use the Ibycus 4 Greek font with Babel
     insbox - A TeX macro for inserting pictures/boxes into paragraphs.
     layouts - Display various elements of a document's layout.
     lettrine - Typeset dropped capitals.
     lineno - Line numbers on paragraphs.
     lipsum - Easy access to the Lorem Ipsum dummy text.
     moresize - Allows font sizes up to 35.83pt.
     ncctools - A collection of general packages for LaTeX
     paralist - Enumerate and itemize within paragraphs.
     picinpar - Insert pictures into paragraphs.
     plari - Typesetting stageplay scripts.
     seqsplit - Split long sequences of characters in a neutral way.
     shapepar - A macro to typeset paragraphs in specific shapes.
\end{verbatim}
and then the command ``tlmgr show bigfoot'' gives more information about that particular package.

Often you'll want to find a known style file. Suppose you are interested in parskip.sty. The command
\begin{verbatim}
     tlmgr search --file parskip
\end{verbatim}
gives
\begin{verbatim}
     AkkTeX:
        texmf-dist/tex/latex/AkkTeX/akkparskip.sty
     FAQ-en:
        texmf-doc/doc/english/FAQ-en/html/FAQ-parskip.html
     ltxmisc:
        texmf-dist/tex/latex/ltxmisc/parskip.sty
     ncctools:
        texmf-dist/doc/latex/ncctools/nccparskip.pdf
        texmf-dist/tex/latex/ncctools/nccparskip.sty
        texmf-dist/source/latex/ncctools/nccparskip.dtx
     FAQ-en:
        texmf-doc/doc/english/FAQ-en/html/FAQ-parskip.html
     ltxmisc:
        texmf-dist/tex/latex/ltxmisc/parskip.sty
     ncctools:
        texmf-dist/doc/latex/ncctools/nccparskip.pdf
        texmf-dist/tex/latex/ncctools/nccparskip.sty
        texmf-dist/source/latex/ncctools/nccparskip.dtx
\end{verbatim}
Both search commands described above search the local \TeX{} Live distribution. To search the ``location'' from which updates are obtained, include the option ``-{}-global''. Thus
\begin{verbatim}
     tlmgr search --global --file parskip
\end{verbatim}
Incidentally, this command shows the general syntax of a tlmgr command. The first command is ``tlmgr''. Next comes the action which tlmgr should perform --- in our case, ``search''. After that come flags which modify that command, like ``-{}-global'' and ``-{}-file''. Finally the ``operand'' lists what we want to update, search for, or describe --- in our case ``parskip''. As one more syntax note, you can use \verb|-| and \verb|--| interchangeably to introduce option names.


\section{Important tlmgr Commands for Paper Size}

Of course tlmgr can configure the default paper size. To configure for letter size paper, type
\begin{verbatim}
     sudo tlmgr paper letter
\end{verbatim}
and to configure for a4 size paper, type
\begin{verbatim}
     sudo tlmgr paper a4
\end{verbatim}

\section{Using tlmgr to Install \TeX{} Live over the Web; Don't Do It!}

It is possible to use tlmgr in conjunction with other scripts to install \TeX{} Live directly over the web, much as Mik\TeX\ and other distributions download and install \TeX\ at the same time. The reason this is a bad idea on the Mac is that you will only get \TeX{} Live, but you will not get the \TeX\ Distribution data structure.  So your PATH and MANPATH variables will not be properly configured, you will have to reconfigure all of your GUI front ends and utilities directly, and you will have to repeat the process any time you want to switch to another \TeX\ distribution, even briefly to fix a temporary error in \TeX{} Live. In short, you will bypass all of the hard work by Gerben Wierda, J\'{e}r\^{o}me Laurens, and others to make \TeX\ magically work immediately without any configuration.


\section{If Download Times are Slow, Do This Instead}

Shortly after the release of Mac\TeX{}-2008, we will put three packages on the web linked from \url{www.tug.org/mactex/morepackages.html}. The first is called Mac\TeX{}-Additions; it installs everything in Mac\TeX{} except the \TeX{} Live distribution. This is a way to get the various GUI front ends and utilities, Ghostscript, and ``convert'' from ImageMagick. However many users will not need this package; they have their own favorite editors and pdf previewers or can download them from the web, and they don't need Ghostscript or ``convert'' or already have them from MacPorts, Fink, and elsewhere. This package's size is about 136 MB.

The second package is \TeX Live-2008, for users who just need \TeX\ itself. This package does contain the \TeX\ Distribution data structure, but it is very large, about 925 MB.

The third package is Basic\TeX -2008. It is a much smaller subset of \TeX{} Live 2008, only about 40 MB, and yet it is surprisingly capable, able to typeset most standard \TeX\ documents. It includes \TeX, \LaTeX, pdf\TeX, AMS-\LaTeX, Metafont, dvips, Con\TeX t, MetaPost, and \XeTeX. It contains the \TeX\ Distribution data structure, so everything is configured and ready to go.

Moreover, Basic\TeX -2008 includes the tlmgr utility, so if packages are missing they can be obtained over the web. This is the best of both worlds. To obtain additional packages, use the updating commands listed earlier, but replace ``update'' with ``install''. Thus
\begin{verbatim}
     sudo tlmgr install  crossreference xmlplay york-thesis
\end{verbatim}
installs three additional packages, and
\begin{verbatim}
     tlmgr --dry-run install crossreference xmlplay york-thesis
\end{verbatim}
shows what will happen if these packages are installed.


\section{Using the X11 GUI for tlmgr}

In case you haven't heard of it, X11 is an alternate graphics windowing system often used in GNU/Linux and other Unix based architectures. It is roughly the equivalent of the Aqua user interface on the Macintosh. OS X comes with code which allows X11 programs to run on the Macintosh. These programs have a different look and feel than typical Macintosh programs, but the differences are easily mastered. 

The code is also called X11; it was an optional install on OS X 10.3 and 10.4, but is part of the default install on 10.5 Leopard. If you didn't install X11 earlier, you can obtain it from your OS X Install Disk by clicking on the Optional Installs package. 

The tlmgr GUI program requires Perl/Tk, an optional package for Perl. While the Macintosh has Perl, it does not have this optional package. We have provided an install package for Perl/Tk in the \TeX{} Live Manager subfolder of the \path{/Applications/TeX/Utilities} directory; this package requires at least OS X 10.4, but installs automatically with no work.

If you prefer obtaining Perl/Tk yourself, the package can be obtained at \url{http://www.lehigh.edu/~sol0/Macintosh/X/ptk/}, which has instructions for installing for both OS X 10.3 and 10.4; the 10.4 instructions also work on 10.5. These instructions send you to \url{http://search.cpan.org/~ni-s/Tk-804.027/} for the actual source code.  Installing this code requires compiling it first using Apple's developer tools, so it is a mildly nerdy operation.

(The reason some users prefer to install themselves is that they don't know what they are getting when they use an Install package. To partly reassure such users, we provide below the files and folders installed by our Perl/Tk package Tk-804.028.pkg:
\begin{itemize}
\item     Five executable files in \path{/usr/local/bin}: gedi, ptked, ptksh, tkjpeg, and widget. All are short scripts.
\item     The files \path{Tk.pm}, \path{Tk.pod}, and \path{fix_4_os2.pl-temp} and the folders \path{Tie}, and \path{Tk} in \path{/Library/Perl/5.8.8/darwin-thread-multi-2level}. 
\item     The folder \path{Tk} in \path{/Library/Perl/5.8.8/darwin-thread-multi-2level/auto}
\end{itemize}
Here 5.8.8 corresponds to the version number of Perl, and will be different on your machine if you have a different version of Perl.)


After installing X11 and Perl/Tk, you are ready to run the GUI interface to tlmgr. Simply issue one of the following commands in Terminal:
\begin{verbatim}
     tlmgr --gui
\end{verbatim}
or
\begin{verbatim}
     sudo tlmgr --gui
\end{verbatim}
You must use the second form if you want to install packages, because the GUI application will need root permission to install. On Leopard, X11 will start automatically, but on Tiger you will need to start X11 before issuing this command.

Like any good GUI app, the program which appears is mostly self explanatory. Here are a few tips:
\begin{itemize}
\item The ``location'' shown at top left should be the \url{http://mirror.ctan.org/systems/texlive/tlnet/tldev} mirror site for updates. If not, navigate to that site using the ``Change'' button.

\item Package lists will appear in ``Installation'', ``Update'', and ``Remove'' modes. If they do not, push ``Load''.

\item When selecting packages, hold down the control key to add additional selections, which need not be contiguous. As on the Mac, hold down the shift key to select all packages between the original selection and the new click.
\end{itemize}

\section{Further Information}

For further information, see the \TeX{} Live web page about tlmgr, \url{http://tug.org/texlive/tlmgr.html}.
\end{document} 
 