\chapter{Getting started}\label{sec: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  pdf
files.  For this introduction we use the \TS{} editor, which is free,
and is available for Windows, Mac OS X 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 it is important to edit them in an editor which adds
nothing binary. You can use a general programmers editor or even
Notepad, but an editor which understands \LaTeX{} 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.\enlargethispage*{26bp}

\subsection{More advice}

My a website \url{http://tex.aanhet.net/rugtex/} contains a page
which goes into more detail about putting together your own \TeX{}
system. There are also 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{fig:launcher}
\end{figure}

The ready-to-run \LaTeX{}
installation at the Rijksuniversiteit Groningen is based on \TL{} and
contains several editors and 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{yyyy}}. This invokes the RuG \TL{} Launcher, see
Figure~\ref{fig:launcher}. The RuG \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 my website mentioned earlier.

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}

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

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}. If you want to tell such files apart, you
need to configure your computer to display file extensions. For
Windows, you need the Folder Options dialog, or File Explorer
Options in Windows 10.

This dialog can be accessed via the Control Panel, in the
`Appearance and Personalization' category.\footnote{The Control
  Panel is slated to disappear from Windows 10 eventually. Other
  ways to open this dialog are via Search, or via File Explorer,
  clicking first the View tab of the ribbon, then the Options
  button.}

Go to the View tab of the dialog, see figure~\ref{fig:extensions},
uncheck `Hide extensions for known file types' and click `OK'.
\clearpage % bug workaround for misplaced footnote

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

\begin{figure}[tb]
\centering
\includegraphics[width=.8\linewidth]{../screenshots/tsd}
\caption{\TS, a \LaTeX{} editor. Left: structure; center top:
editing area; center bottom: message area; right: pdf
preview}\label{fig:tsd}
\end{figure}

Figure~\ref{fig:tsd} shows the \TS{} edit screen. The editing area
is surrounded by various toolbars, a structure view on the left and,
after a successful compilation, the built-in pdf viewer.

Optionally, there is also a tabbed message pane below the
editing pane.  This 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}
As you get to know \LaTeX{} better, you may prefer to type \LaTeX{}
macros by hand.

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

Now we are going to do the entire cycle: text entry, compilation and
previewing in the \LaTeX{} editor \TS. Create a new document by
clicking on \menupath{File / New} and type the following code:
\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 pane should
appear; see figure~\ref{fig:tsd}.

Also have a look at the message pane below the editing pane
(figure~\ref{fig:tsd}). If there are problems then \TS{} tries
to identify and flag the cause, see figure~\ref{fig:error}.
\begin{figure}[tb]
  \centering
  \includegraphics[scale=.3]{../screenshots/tsd_error_cropped}
  \caption{\TS{} flagging errors}
  \label{fig:error}
\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 \LaTeX{} reference in html format.

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 \TL{} version of the above \LaTeX{} reference,
also in pdf format and also fully bookmarked and hyperlinked.

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 visit 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.\enlargethispage*{13bp}

\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 introduction comes with a zipfile \path{practice.zip} with some
example \path{.tex} files, a subdirectory \path{figures} of graphic
files for chapter~\ref{sec:grap} and a second subdirectory
\path{bibtex} relating to bibliography management in
appendix~\ref{sec:bib}\footnote{This last topic is no longer part of
the introduction. Nevertheless, the \LaTeX{} bibliography system is
highly recommended.}.

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

\subsection{RUG \TeX{} installation}
\vspace{-12bp}
{\intextsep=-24pt
\begin{wrapfigure}[6]{r}{0pt}%
  {\includegraphics[scale=.4]{../screenshots/practice7zip}}%
\end{wrapfigure}%
The practice zipfile is the Practice files item in the Documentation menu of the
launcher. If you click the item, you get to see a folder named
\texttt{practice} in a 7zip window. Drag-and-drop this folder to your
X:-drive. A destination on your desktop is probably ok too.\par}

\subsection{Home \TeX{} installation}
{\intextsep=-12pt
\begin{wrapfigure}[5]{r}{0pt}%
  {\includegraphics[scale=.4]{../screenshots/zip_open}}%
\end{wrapfigure}%
The practice zipfile is available from \citetitle{ctan} in the
\url{info/latexcourse-rug} subdirectory. Right-click the zip file
after downloading, select `Extract All...'. Take care to pick some
reasonable location, \emph{e.g.} under \path{Documents} or on the
desktop. The default may well be some directory for temporary files,
which is probably not what you want.\par}
