% $Id: faq-getit.tex,v 1.4 2010/01/19 22:44:39 rf10 Exp rf10 $

\section{Acquiring the Software}

\Question[Q-archives]{Repositories of \TeX{} material}

To aid the archiving and retrieval of of \TeX{}-related files, a
\acro{TUG} working group developed the Comprehensive \TeX{} Archive
Network (\acro{CTAN}).  Each \acro{CTAN} site has identical material,
and maintains authoritative versions of its material.  These
collections are extensive; in particular, almost everything mentioned
in this \acro{FAQ}
is archived at the \acro{CTAN} sites (see the lists of software at the
end of each answer).

\begin{narrowversion} % non-hyper
  The \acro{CTAN} sites are in Germany, the UK and the USA; the
  directory layout is the same on each of the sites, starting from a
  tree root of \path{tex-archive/} The sites are
  \texttt{dante.ctan.org} (Dante, Germany), \texttt{cam.ctan.org}
  (Cambridge, UK) and \texttt{tug.ctan.org} (TUG, USA).
\end{narrowversion}
\begin{wideversion} % hyper
  The \acro{CTAN} sites are
  \href{ftp://dante.ctan.org/tex-archive}{Dante (Germany)},
  \href{ftp://cam.ctan.org/tex-archive}{Cambridge (UK)} and
  \href{ftp://tug.ctan.org/tex-archive}{TUG (USA)}; the links are to
  the root of the \acro{CTAN} tree, above which the layout is
  identical at each site.
\end{wideversion}

The \TeX{} files at each \acro{CTAN} node may also be accessed via
the Web at \acro{URL}s \URL{http://www.dante.de/tex-archive},
\URL{http://www.tex.ac.uk/tex-archive} and
\URL{http://www.ctan.org/tex-archive} respectively, but not all
\acro{CTAN} mirrors are Web-accessible.

As a matter of course, to reduce network load,
please use the \acro{CTAN} site
or mirror closest to you.  A complete and current list of \acro{CTAN} sites
and known mirrors is available as file \CTANref{CTAN-sites} on the
archives themselves.

Better still, the script behind \URL{http://mirror.ctan.org/} will
cunningly choose a ``nearby'' mirror for you, using information from
the database `behind' \CTANref{CTAN-sites}; at present it uses
\texttt{ftp} protocol for transfers, but the intention is to convert
it to using \texttt{http} (web) protocol in the near future.

To access a particular thing through the \texttt{mirror.ctan.org}
mechanism, simply place the \acro{CTAN} path after the base
\acro{URL}; so
\URL{http://mirror.ctan.org/macros/latex/contrib/footmisc/} will
connect you to the \Package{footmisc} directory at some \acro{CTAN}
site (or a mirror)~--- note that the \File{tex-archive} part of the
\acro{CTAN} path isn't needed.

For details of how to find files at \acro{CTAN} sites, see
``\Qref*{finding \AllTeX{} files}{Q-findfiles}''.

The \TeX{} user who has no access to any sort of
network may buy a copy of the archive as part of the
\Qref*{\texlive{} distribution}{Q-CD}.

\Question[Q-tds-zip]{Ready-built installation files on the archive}

The \Qref*{\acro{TDS}}{Q-tds} is a simple structure, and almost all
files can be installed simply by putting them in the ``right'' place,
and updating a single index.  (Note, this simple idea typically
doesn't work for fonts, unless they're distributed as \MF{} source.)

The CTAN network is therefore acquiring ``\acro{TDS}-\acro{ZIP}'' files,
which have a built-in directory structure that matches the \acro{TDS}.
These files have to be built, and the \acro{CTAN} team has asked that
package authors supply them (the team will advise, of course, if the
author has trouble).  The \acro{CTAN} team hopes that the extra work
involved will contribute to happier lives for package users, which in
turn must surely help keep the TeX community lively and active.

At the time of writing, there are rather few \extension{tds.zip}
files (by comparison with the huge number of packages that are
available).  As packages are updated, the number of files is
steadily increasing, but it will be a long time before the whole set
is covered.

Use of the files is discussed in % ! line break
``\Qref*{installing using ready-built \acro{ZIP} files}{Q-inst-tds-zip}''.

\Question[Q-nonfree]{What was the \acro{CTAN} \texttt{nonfree} tree?}

When \acro{CTAN} was founded, in the 1990s, it was unusual to publish
the terms under which a \TeX{}-related package was distributed (or, at
any rate, to publish those terms formally).

With the advent of the \TeX{} \emph{distributions}, however, people
started to realise the need for such information, to protect those who
create, distribute or sell the discs that hold the packages, etc.
With the licence information available, the distributors can decide
which packages may be distributed.

The \acro{CTAN} team decided that it would be useful for users (and
distributors, not to say package authors) to separate packages that
were candidates for distribution, and those that were in some sense
``not free''.  Thus was the \texttt{nonfree} tree born.

From the start, the \texttt{nonfree} tree was controversial: the terms
under which a package would be placed on the tree were hotly
contested, and the \acro{CTAN} team were only able slowly to populate
the tree.  It became obvious to the team that the project would never
have been completed.

The \acro{CTAN} catalogue now records the nature of the licences of a
good proportion of the packages it describes (though there remain
several for which the licence is unknown, which is as good, for the
distributors, as a licence forbidding distribution).  Since the
catalogue's coverage of \acro{CTAN} is good (and slowly improving),
the general rule for distributors has become
\begin{quote}
``if the package is listed in the catalogue, check there to see
whether you should distribute; if the package is not listed in the
catalogue, don't think of distributing it''.
\end{quote}
(The catalogue only has a modest % ! line break
\CTANhref{cat-licences}{list of licences}, but it covers the set used
by packages on \acro{CTAN}, with a wild-card ``\texttt{other-free}''
which covers packages that the \acro{CTAN} administrators believe to
be free even though the authors haven't used a standard licence.)

There is a corollary to the `general rule': if you notice something
that ought to be in the distributions, for which there is no catalogue
entry, please let the \acro{CTAN} team (\mailto{ctan@dante.de}) know.
It may well be that the package has simply been missed, but some aren't
catalogued because there's no documentation and the team just doesn't
understand the package.

In the light of the above, the \texttt{nonfree} tree is being
dismantled, and its contents moved (or moved \emph{back}) to the main
\acro{CTAN} tree.  So the answer to the question is, now, ``the
nonfree tree was a part of \acro{CTAN}, whose contents are now in
the main tree''.

\Question[Q-uploads]{Contributing a file to the archives}

You have something to submit to the archive~--- great!  Before we even
start, here's a check-list of things to sort out:
\begin{enumerate}
\item Licence: in the spirit of \TeX{}, we hope for free software; in
  the spirit of today's lawyer-enthralled society, \acro{CTAN}
  provides a % ! line break
  \href{http://mirrors.ctan.org/help/Catalogue/licenses.html}{list of ``standard'' licence statements}.
\item Documentation: it's good for users to be able to browse
  documentation before downloading a package.  You need at least a
  plain text \File{README} file (exactly that name); in addition a
  \acro{PDF} file of the package documentation, prepared for screen
  reading, is highly desirable.
\item Name: endless confusion is caused by name clashes.  If your
  package has the same name as one already on \acro{CTAN}, or if your
  package installation generates files of the same name as something
  in a ``normal'' distribution, the \acro{CTAN} team will delay
  installation while they check that you're doing the right thing:
  they may nag you to change the name, or to negotiate a take-over
  with the author of the original package. % beware line break
  \Qref*{Browse the archive}{Q-findfiles} to ensure uniqueness.
  
  The name you choose should also (as far as possible) be somewhat
  descriptive of what your submission actually \emph{does}; while
  ``descriptiveness'' is to some extent in the eye of the beholder,
  it's clear that names such as \File{mypackage} or \File{jiffy}
  aren't suitable.
\end{enumerate}

If you are able to use anonymous \ProgName{ftp}, you can upload that
way.  The file \File{README.uploads} on \acro{CTAN} tells you
where to upload, what to upload, and how to notify the \acro{CTAN}
management about what you want doing with your upload.

You may also upload via the Web: each of the principal \acro{CTAN}
sites offers an upload page~--- choose from
\URL{http://www.ctan.org/upload.html},
\URL{http://www.dante.de/CTAN/upload.html} or
\URL{http://www.tex.ac.uk/upload.html}; the pages lead you through the
process, showing you the information you need to supply.  This method
enforces one file per upload: if you had intended to upload lots of
files, you need to bundle them into an `archive' file of some sort;
acceptable formats are \extension{zip} and \extension{tar.gz} (or
\extension{tar.bz2}).

If you can use neither of these methods, or if you find something
confusing, ask advice of the
\begin{narrowversion} % really non-hyper version
  \acro{CTAN} management (\mailto{ctan@dante.de}):
\end{narrowversion}
\begin{wideversion}
  \href{mailto:ctan@dante.de}{\acro{CTAN} management}:
\end{wideversion}
if the worst comes to the worst, it may be possible to mail a
contribution.  This really is a last-resort route: none of the
\acro{CTAN} sites is anyone's regular workstation, so if you mail to
one of the maintainers, that maintainer then has to upload to
\acro{CTAN}.
  
If it's appropriate (if your package is large, or regularly updated),
the \acro{CTAN} management can arrange to \ProgName{mirror} your
contribution direct into the archive.  At present this may only be
done if your contribution is available via \ProgName{ftp}, and of
course the directory structure on your repository must `fit'.
\begin{ctanrefs}
\item[README.uploads]\CTANref{CTAN-uploads}
\end{ctanrefs}

\Question[Q-findfiles]{Finding \AllTeX{} files}

Modern \TeX{} distributions contain a huge array of support files of
various sorts, but sooner or later most people need to find something
that's not in their present system (if nothing else, because they've
heard that something has been updated).

But how to find the files?

Some sources, such as these \acro{FAQ} answers, provide links to
files: so if you've learnt about a package here, you should be able to
retrieve it without too much fuss.

Otherwise, the \acro{CTAN} sites provide searching facilities, via the web.
The simplest search, locating files by name, is to be found on the
Dante \acro{CTAN}
at \URL{http://dante.ctan.org/search.html}; the script scans a
list of files (\File{FILES.byname}~--- see below) and returns a list
of matches, arranged very neatly as a series of links to directories
and to individual files.

The \href{http://www.tex.ac.uk/search}{\acro{UK}} and
\href{http://www.ctan.org/search.html}{\acro{USA}} \acro{CTAN}s offer a
search page that provides
\begin{itemize}
\item a file-name search similar to the Dante machine's (above);
\item a keyword search of the archive catalogue (see below): this is a
  pretty powerful tool: the results include links to the catalogue
  ``short descriptions'', so you can assure yourself that the package
  you've found is the one you want; and
\item a search form that allows you to use \ProgName{Google} to search
  \acro{CTAN}.
\end{itemize}

An alternative way to scan the catalogue is to use the catalogue's
% ! line break
\href{http://mirrors.ctan.org/help/Catalogue/bytopic.html}{``by topic'' index};
this lists a series of topics, and \AllTeX{} projects that are worth
considering if you're working on matters related to the topic.  

In fact, \ProgName{Google}, and other search engines, can be useful
tools.  Enter your search keywords, and you may pick up a package that
the author hasn't bothered to submit to \acro{CTAN}.  If you're using
\ProgName{Google}, you can restrict your search to \acro{CTAN} by
entering
\begin{quote}
  \texttt{site:ctan.org tex-archive \meta{search term(s)}}
\end{quote}
in \ProgName{Google}'s ``search box''.  You can also enforce the
restriction using \ProgName{Google}'s ``advanced search'' mechanism;
other search engines (presumably) have similar facilities.

Many people avoid the need to go over the network at all, for their
searches, by downloading the file list that the archives' web
file searches use.  This file, \File{FILES.byname},
presents a unified listing of the archive (omitting directory names and
cross-links).  Its companion \File{FILES.last07days} is also useful, to
keep an eye on the changes on the archive.  Since these files are
updated only once a day, a nightly automatic download (perhaps using
\ProgName{rsync}) makes good sense.
\begin{ctanrefs}
\item[FILES.byname]\CTANref{f-byname}
\item[FILES.last07days]\CTANref{f-last7}
\end{ctanrefs}

\Question[Q-findfont]{Finding new fonts}

A comprehensive list of \MF{} fonts used to be posted to
\Newsgroup{comp.fonts} and to \Newsgroup{comp.text.tex}, roughly
every six weeks, by Lee Quin.
Nowadays, authors of new material in \MF{} are few and far between
(and mostly designing highly specialised things with limited appeal to
ordinary users); as a result, no-one has taken over maintenance of the
list of fonts.  If you need a font for some esoteric purpose, it may
be worth \Qref*{searching \acro{CTAN}}{Q-findfiles} using your purpose
as a search keyword.

Most new fonts that appear are prepared in some scalable outline form
or other, and a large proportion is distributed under commercial
terms.  However, once you have acquired such a font, converting it to
a form usable by your \AllTeX{} distribution is not (in principle) a
serious problem.

The answer ``\Qref*{choice of scalable fonts}{Q-psfchoice}'' discusses
fonts that are configured for general (both textual and mathematical)
use with \AllTeX{}.  The list of such fonts is sufficiently short that
they \emph{can} all be discussed in one answer here.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}\MF{} font list]\CTANref{mf-list}
\end{ctanrefs}

\Question[Q-CD]{The \TeX{} collection}

If you don't have access to the Internet, there are obvious
attractions to \TeX{} collections on a disc.  Even those with net
access will find large quantities of \TeX{}-related files to hand a
great convenience.

The \TeX{} collection provides this, together with
ready-to-run \TeX{} systems for various architectures.  The collection
is distributed on \acro{DVD}, and contains:
\begin{itemize}
\item The \texlive{} for a variety of architectures; \texlive{} may be
  run from the \acro{DVD} or installed on hard disc.
\item Mac\TeX{}: an easy to install \TeX{} system for MacOS/X, based
  on \texlive{}; this distribution includes a native Mac installer,
  % ! line break
  \href{http://www.uoregon.edu/~koch/texshop/}{the \TeX{}Shop front-end}
  and other Mac-specific tools;
\item Pro\TeX{}t: an easy to install \TeX{} system for Windows, based
  on \miktex{}, and including an `active' document to guide
  installation; and
\item A snapshot of \acro{CTAN}.
\end{itemize}
A fair number of national \TeX{} User Groups, as well as \acro{TUG},
distribute copies to their members at no extra charge.  Some user
groups are also able to sell additional copies:
contact your local user group or \Qref*{\acro{TUG}}{Q-TUG*}.

You may also download disc images from \acro{CTAN}; the installation
disc, Pro\TeX{}t and Mac\TeX{} are all separately available.  Beware:
they are all pretty large downloads.  \texlive{}, once installed, may
be updated online

More details of the collection are available from its own
\begin{wideversion} % this really ought to be "hyperversion" or summat
  \href{http://www.tug.org/texcollection/}{web page}
  on the \acro{TUG} site.
\end{wideversion}
\begin{narrowversion} % and non-hyperversion?
  web page on the
  \acro{TUG} site \URL{http://www.tug.org/texcollection/}
\end{narrowversion}
\begin{ctanrefs}
\item[Mac\TeX{}]\CTANref{mactex}
\item[Pro\TeX{}t]\CTANref{protext}
\item[\TeX{}live install image]\CTANref{texlive}
\end{ctanrefs}