Previous Up Next

3  First steps

Let’s now see how to create a first document: for this you’ll need to type some text in the editor window of TEXworks. (LA)TEX is not aWYSIWIG software,5 so you’ll have to type the text and the instructions for formatting it and you’ll see the result only after “typesetting” the text. This looks a little bit dry, but one very quickly gets used to it and this is worth the effort.

3.1  Interface summary

When one opens the editor, it shows a very sparse interface: a title bar, a menu bar, two small tool-bars, a large typing zone (white) and, at the bottom, a status bar. We are in the source/editor window. If you already typeset the document, the resulting .pdf will be shown on the right in the preview window.

The first tool-bar has a button to typeset and an drop-down menu to choose the format for typesetting (we'll choose pdfLaTeX). Knowing that the keyboard short-cut for typesetting is [Ctrl+T] (Mac OS X: [Cmd+T]) and that we almost never change the format, we could even not show this tool-bar. The selection of a format for compiling can also be changed through the Typeset menu.

The second toolbar provides the standard functions: New document, Open, Save | Undo, Redo | Cut, Copy, Paste | Search, Replace.

3.2  Creating a document

3.2.1  Writing the document

As an example of the use of TEXworks we will work with LATEX, but any other TEX system is possible. In particular, if you need to use some special fonts – mandatory font for an official template, non latin alphabets – the XeTeX system is very powerful. 6

Let’s create now our first document: enter the following text exactly as shown. To show some of the features of TEXworks/LATEX, it is intentionally in French.7


\documentclass{article}

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{geometry}
\geometry{a4paper}

\usepackage[francais]{babel}

\title{Premier document}
\author{Un TeXnicien}
\date{}

\begin{document}
\maketitle

Voici un texte accentué en français!

\end{document}

Save the file in a folder for test documents (for example: <home> TeXworks_tests); call the file first.tex, note that it should have a .tex extension.

3.2.2  Typesetting the document and viewing it

Next we start typesetting8 by clicking the green button or by [Ctrl+T] (Mac OS X [Cmd+T]).

A new panel opens between the typing area and the status bar: the output panel, labelled Log; everything LATEX is doing when it works is displayed here 9. When LATEX finishes (if there is no error) this panel disappears and a new window will appear; in this new window, the Preview window, you can see a page with a title “Premier document” followed by the name of the author “Un TeXnicien”, both centred, the text frenchb“Voici un texte accentué en français!” and at the bottom centre a page number.

Notice that the mouse cursor is like a magnifier in the new window. If you push the left button of the mouse you can see the text under the magnifier much bigger (it is a magnifier, isn’t it!); you can move the magnifier and so inspect the text in detail.

To go back to the source, you can just click in its window or better do [Ctrl+'] (Mac OS X [Cmd+']). This short-cut is a toggle between the two windows.10 See also section 5.1 to automatically move at a specified location of the view from the source or the inverse.

3.2.3  The work of LATEX

Let’s now shortly analyse the result to understand what LATEX did and why. Introductions and full tutorials can be found on internet: see for example lshort which should be installed as part of your TEX distribution, and is also available from CTAN.11

We ask to create a document of the article class: this defines the global layout of the document.

Next we say that the input document (the source) is saved with the Unicode encoding utf-8 and that it will then contain characters which are not present in the standard ASCII without accents. We also want to use an output encoding T1 (the modern TEX encoding); we also want an A4 document and not the default US letter size. Finally we make it clear that the typography should follow the French rules using the babel package. Those general instructions for the work are done by packages called with options.

Lastly, we finish the declaration part of the document, the preamble, giving the title, the author and the date of the document; here we specify no date.

Next comes the body of the document, between the lines \begin{document} and \end{document} (commands). It is here where everything which will appear in the document will be.

Let’s do some experiments to show the effect of these instructions. For this we put a % in front of the instructions; the % and everything after it will be considered as a comment, which will be ignored by LATEX.12

Comment out the line \usepackage[utf8]{inputenc}, and typeset the file. You should see that the accented characters are now incorrect in the preview window. If you now comment out the line \usepackage[francais]{babel}, LATEX will give an error. Just hit [Enter] to continue the typesetting.

After these experiments, let’s modify the text as follows:


\begin{document}
\maketitle
\tableofcontents

\section{Petite démonstration}

Voici un texte accentué en français!
Suite du texte entré après avoir fait un retour chariot. Dans l'éditeur 
on peut demander un passage automatique à la ligne du texte saisi; mais
le numéro de ligne n'est incrémenté que par un retour chariot.

Nouvelle ligne en passant une ligne dans la source: c'est la manière 
d'indiquer un changement de paragraphe.

\end{document}

Redo the previous experiments and observe the changes which appear.

Note that entering only one carriage return doesn’t create a new paragraph. In LATEX one has to have an empty line for that. In TEXworks the line number of the source (on the right in the status bar) numbers the lines created with carriage return, not the wrapped lines.

3.3  And when errors occur!

When you create a document for typesetting with LATEX, you cannot avoid making mistakes: forgetting a closing brace or an \end{} command to close an environment, using mathematical commands without switching to mathematical mode, etc. When you compile and there is an error, LATEX stops, this is shown by scrolling actions in the output panel stopping, and an error message is displayed with LATEX waiting for an instruction to know what it should do: one sees the typing cursor in the line between the output panel and the status bar: the console bar.

The error message is on many lines, for example like this:


! Undefined control sequence.
l.168 ... fermante ou d'une commande \veb
                                         +\end{}+ de fermeture d'un...
? 

LATEX says that it doesn’t recognize the command name, sometimes suggests to see the manual or to type h (plus [Return]) for help, points to the line number (here 168) and shows the place of the error at the cut of the line (here at \veb) and finally with the question mark shows that it waits for an action from us.

There are different possible actions:

  • Type [Return] and ask to continue as if nothing happened; sometimes this allows to finish compiling, but there will be an error in the result.
  • Type h[Return] to ask for help; this help in not always clearer than the error message, but often this gives a clue.
  • Type i[Return] to tell LATEX that we will propose a replacement text. Enter the text followed by [Return]; it will be used, beginning at the start of the error, but you should correct the source afterwards. There is no correction in the source during compilation.
  • Type x[Return] to stop compilation. This is the traditional (LA)TEX way to kill a typesetting process.

    We can also kill the typesetting by repeating the action used to start it: the green typesetting button will have changed to a red one with a white cross . By clicking on that button or with [Ctrl+T] (Mac OS X [Cmd+T]), the LATEX process is terminated. The output panel is still visible and so one can still see the error message.

You should note that sometimes an error appears far from its actual position. For example, when opening an environment but not closing it, LATEX doesn’t see the error before it encounters another end of environment without closing of the first one. The error is often only picked up at the \end{document} command, which shows that another environment was not closed!

3.4  Changing TEXworks parameters for convenience

If the default font of the editor doesn’t suit you, it is possible to change it from Format / Font… by selecting a new one in the dialogue box which appears. This change will apply only until TEXworks is restarted.

From the Typeset menu or from the drop-down on the Typesetting tool bar, you can change the compilation format. Again this change will only be temporary.

To have permanent changes, you need to change the Preferences through the Edit/ Preferences… menu, using the Editor tab for the font and Typesetting tab for the compilation format: the default format is at the bottom of the tab (let’s choose pdfLaTex for this one).


Previous Up Next