\chapter{Getting started}\label{chap:start}

\section{Getting (La)\TeX}\label{sec:get}

\subsection{Editor}

An obvious component of a (La)\TeX{} installation is the editor in
which you enter your documents, and which compiles them into a pdf
file.  For this course we use the \TS{} editor, which is free,
and is available for both Windows and Linux. It offers extensive
assistance for entering \LaTeX{} code and math.

Since \LaTeX{} files are plain text files, you can view them in any
editor, but you should edit them in an editor which adds no binary
stuff. You can use a general programmers editor or even Notepad, but
a dedicated \LaTeX{} editor can give you a lot more help.

\subsection{\TeX{} system}

The editor is actually the least important part; it delegates all
the hard work to the \TeX{} system in the background.

A \TeX{} system is a complex ensemble of command-line programs,
macros, fonts and data files. The two major alternatives are \TL{}
and \MK{}, both free.  The RuG installation uses \TL{}, which is
available for Windows, Mac OS and Unix/Linux, and is included in
most Linux distributions. The other one, \MK{}, is
Windows-only. Both contain all the bits and pieces that you are
likely to need, although \TL{} is a bit more comprehensive.  They
both include the \TW{} editor.

\subsection{More advice}

My web page \url{http://tex.aanhet.net/rugtex/home_inst.html} gives
more detail about collecting your own \TeX{} system and download
links. Another useful beginners resource is
\url{http://www.tug.org/begin.html}.

Two important points:
\begin{itemize}
\item Make sure \TL{} or \MK{} is installed before you run the
  editor for the first time. This enables the editor to configure
  itself automatically for your \TeX{} system.
\item A full \LaTeX{} install takes a long time; do not attempt
  this, \emph{e.g.}, while in class.
\end{itemize}

\section{The RuG \TL{} launcher}\label{sec:launcher}

\begin{figure}[tb]
\centering
\scalegrap{../screenshots/launcher}
\caption{The \TL{} launcher}\label{scr:launcher}
\end{figure}

The Rijksuniversiteit Groningen has a ready-to-run \LaTeX{}
installation, complete with \TL{} and several editors. It also
includes various additional utilities, some of which will be
mentioned later in this book.

For a standard university UWP computer, you should have a menu item
\menupath{Start / Programs / Text Processing / TeX Live RuG
  \textit{nnnn}}. This invokes the \TL{} Launcher, see
Figure~\ref{scr:launcher}. The \TL{} launcher is also available in a
remote session.  From this launcher you can start up your favorite
\LaTeX{} editor, consult documentation and do some configuration and
maintenance. Take a moment to browse the launcher menus.

The `RuG TeX Live website' item in the \menupath{Online} menu points
to the web pages for our \TeX{} installation, one of which explains
how to install \LaTeX{} at home.

The button at the left, labeled `(La)TeX editor', invokes your
selected default editor. The launcher offers you a couple of
additional choices besides \TS{}; plus the option to select an
editor of your own.

\section{Next: let the system display file extensions}

If you work on a file \texttt{somefile.tex}, then \TeX{} is going to
generate various auxiliary files such as \texttt{somefile.aux} and
\texttt{somefile.log}. For Windows, the following steps ensure that
file extensions are visible, so you can tell all these files apart:

\begin{itemize}
\item Windows XP/$7$
\begin{itemize}
\item Click on `My Computer'
\item Click on Tools / Folder Options. Windows $7$: if you do not see
  Tools, hit the left Alt key first.
\end{itemize}
\item Windows 8 (\button{winkey} indicates the Windows- or logo key)
  \begin{itemize}
  \item Type \button{winkey} -D for desktop mode
  \item Type \button{winkey} -E for File Explorer
  \item Click on the Options logo
  \end{itemize}
\item Select the View tab
\item Uncheck `Hide extensions for known filetypes'
\item Click `Apply to All Folders'
\item Click OK
\end{itemize}

\begin{figure}[tbh]
  \centering
  \includegraphics[width=2.5in]{../screenshots/unhide_extensions}
  \caption{Letting Windows display file extensions}
  \label{fig:extensions}
\end{figure}

\section{\TS{}}\label{sec:texstudio}

\begin{figure}[b]
\centering
\includegraphics[width=.8\linewidth]{../screenshots/tsd}
\caption{\TS, a \LaTeX{} editor}\label{scr:tsd}
\end{figure}

Figure~\ref{scr:tsd} shows the \TS{} edit screen. The editing area
is surrounded by various toolbars, a structure view on the left and
optionally a tabbed information area at the bottom.

This latter item is rather useful. If you do not see it, you can
make it visible by clicking on the second-left item
\button{toggle_mess} at the lower left corner of the editor window.

While you are at it, you can also right-click on an empty area of
the toolbar or menu bar to get rid of some of the toolbar clutter;
everything is already available via the menus.

Also look through the \TS{} menus, in particular:
\begin{itemize}
\item The Tools menu and its Commands submenu for running \LaTeX{}
  and various utilities; see section~\ref{sec:first}
\item The LaTeX menu for inserting various \LaTeX{} macros
\item The Math menu for inserting \LaTeX{} macros for math
\end{itemize}
You can also type \LaTeX{} macros by hand once you know them.

\section{First document}\label{sec:first}

Now we are going to do the entire cycle: text entry, compilation and
previewing from the \LaTeX{} editor \TS. Create a new document by
clicking on \menupath{File / New} and type the following code:
\enlargethispage*{-20bp}
\begin{verbatim}
\documentclass{article}
\begin{document}
Hello, world!
\end{document}
\end{verbatim}
{\sloppy 
This is a complete \LaTeX{} document. Setup is done in the
\emph{preamble}, \emph{i.e.} the \cmd{documentclass} line and
anything else before \benv{document}. In this case, we just
specified that we wanted an article rather than, \emph{e.g.}, a book
or a letter. Actual content goes between \benv{document} and
\eenv{document}.\par}

\subsection{Compiling} Save the document as, \emph{e.g.},
\path{X:\latexdocs\hello.tex}. Then click the Build button
(\button{button_build}). If all is well a pdf-preview window should
pop up; see figure~\ref{fig:preview}.


Also have a look at the message area below the editing area
(figure~\ref{fig:messages}). If there are problems or you are not
getting the output you expect then you can inspect the Errors tab.
\begin{figure}[tbh]
  %\centering
  \includegraphics[width=\linewidth]{../screenshots/tsd_view}
  \caption{The built-in previewer of \TS}
  \label{fig:preview}
\end{figure}
\begin{figure}[tbh]
  %\centering
  \includegraphics[width=\linewidth]{../screenshots/tsd_messages}
  \caption{Messages tab after a successful compilation}
  \label{fig:messages}
\end{figure}

You can read more about compiling in Section~3 of the online help:
\menupath{Help / User Manual...}. It also explains what to do in case
of errors.


\section{Documentation}\label{sec:documentation}

\textbf{Built-in help.}  The Help menu of \TS{} provides both help
for \TS{} itself and a brief \LaTeX{} reference.

The launcher Documentation- and Online menus contain shortcuts to
several other useful manuals and online resources.

The \emph{LaTeX Introduction} menu entry points to a book-length
introduction which covers all the basics. It is also a nice
demonstration of the bookmarking and hyperlinking that you get
virtually for free with \LaTeX, and which makes the pdf very
convenient to consult on-screen. The next menu item, \emph{LaTeX
Reference}, is the full version of the built-in \LaTeX{} reference.

The [UK \TeX] \menupath{FAQ} is another useful resource.

\subsection{The documentation list}\label{sec:doclist}

You can gain access to documentation about packages in one of the
following ways:
\begin{description}
\item[RUG Launcher] In the Documentation menu, a menu item
  \menupath{All TeX Live documentation by package} invokes an html
  file \path{doc.html} which contains links to virtually all package
  manuals.
\item[Standard TeX Live] The menu item \menupath{Start / Programs /
    TeX Live \emph{nnnn} / TeX Live Documentation} invokes an html
  page which includes a link \emph{Available package documentation},
  which is this same file.
\item[MiKTeX] lacks such a file, but you can still browse to the
  \citetitle{ctancat}, \citeurl{ctancat} and consult package
  documentation there.
\end{description}
We shall refer to this list, however accessed, as `the documentation
list.'

But you can also use the \package{texdoc} (\TL) or \package{mthelp}
(\MK) command-line utility.

\subsection{Tip: view pdfs with narrow margins}

For better use of your screen pixels, you may wish that your pdf
viewer zoomed in on the printed part of the page.  Several pdf
viewers can do this automatically. In Adobe Reader, select
\menupath{View / Zoom / Fit Visible}. In SumatraPDF, part of our
\TeX{} installation, select \menupath{Zoom / Fit Content}.

\section{Practice files}\label{sec:zipfile}

This course comes with a zipfile \path{practice.zip} with some
example \path{.tex} files, a subdirectory \path{figures} of graphic
files for later in the course and a second subdirectory \path{bibtex}
relating to bibliography management\footnote{This last topic is no
  longer part of the course, but when you start using \LaTeX{} for
  real, it is highly advisable to learn the \LaTeX{} bibliography
  system.}. Is is available from \citetitle{ctan} in the
\url{info/latexcourse-rug} subdirectory.
%\hfill\llap{\includegraphics[height=1in]{../screenshots/zip_open}}%

{\intextsep=-12pt
\begin{wrapfigure}[5]{r}{0pt}%
  {\includegraphics[height=1in]{../screenshots/zip_open}}%
\end{wrapfigure}
Right-click the zip file after downloading, select `Extract
All...' and pick a suitable directory for unpacking, \emph{not} some
obscure directory for temporary files.

Several chapters conclude with suggestions for practicing, which
usually refer to files from this zipfile.\par}
