From Source Code to Typeset

Chapter 3 From Source Code to Typeset

Output

Every time you want to create or edit a L A TEX document, there are three basic steps you will always need to follow:

1. Write or edit the source code .

2. Pass the source code to the latex or pdflatex application (“L A TEX the documentž).

• If there are any error messages, return to Step 1 . • If there are no error messages, a PDF file is created.

3. View the PDF file to check the result. If you need to modify your document, go back to Step 1 .

You will therefore need:

1. A text editor (to perform Step 1 ). For example Vim , Emacs or Gedit .

2. The TEX software (to perform Step 2 ). If you don’t already have TEX [FAQ: (La)TeX on your machine, you will need to install it. The most convenient way for different

to do this is to install from the TEX Collection DVD ROM, which is machines ] distributed to all

TEX User Group 3.1 (TUG) members, but you can also download and install free TEX distributions, such as TeX Live, MiKTeX

or MacTeX, from the Internet (see on the following page). There is also proTeXt , an enhancement of MiKTeX that aims to be an easy-to-install

TEX Distribution. For more information including up-to-date links, go to http://www.ctan.org/starter.html .

3. A PDF viewer (to perform Step 3 ). For example Adobe Reader , Sumatra , Evince or Okular .

This can be rather complicated for a beginner, especially for those with no experience writing computer code. Fortunately, there are some all-in- one applications (often called a front-end) that provide a text editor (for Step 1 ), buttons or menu items to run the latex or pdflatex command-line application (for Step 2 ) and, in some cases, a viewer to perform Step 3 .

3.1 http://tug.org/

Section 3.1 describes one such front-end called TeXWorks . I have chosen to describe TeXWorks because it is a free, cross-platform application. Bina- ries are available for Microsoft Windows, Mac OS X and GNU/Linux. The screen shots of TeXWorks in this book were taken from the Linux version running under Fedora. If you run TeXWorks on other operating systems, it may have a slightly different look, but it has the same functionality.

New versions of TeX Live and MiKTeX include TeXWorks for MS Win- dows, and new versions of MacTeX include TeXWorks for Mac OS X users. GNU/Linux users can use their Add/Remove Software utility to install TeX- Works. Alternatively, you can download TeXWorks by following the links provided at http://www.tug.org/texworks/ .

If you’re confused by all the options, let’s keep things as simple as pos- sible:

• MS Windows: You have a choice between MiKTeX (or proTeXt) and TeX Live. MiKTeX

provides a smaller and quicker installation, but the downside is that you may not have the classes or packages you want to use. MiKTeX can

install these whenever you try to L A TEX a document that uses them, but you need an Internet connection while it does this. TeX Live installs everything, so it takes longer and needs more space, but you should have the majority of packages and classes that you need.

TeX Live:

1. Fetch and unpack http://mirror.ctan.org/systems/ texlive/tlnet/install-tl.zip

2. Run install-tl and follow the instructions. This can take an hour or more.

proTeXt:

1. Go to http://tug.org/protext/

2. Click on the “download the self-extract protext.exež link to download and run the executable.

MiKTeX:

1. Go to http://www.miktex.org/

2. In the left-hand panel, there is a link to the down- load page for the latest version. At time of writing, it is MiKTeX 2.9. Click on that link.

3. Scroll down to the section “Installing a basic MiKTeX systemž.

4. If you’re happy with the selected mirror location, click on the “Downloadž button.

5. Run the executable. • Mac OS X:

1. Go to http://tug.org/mactex/

2. Follow the instructions on that page. • GNU/Linux:

1. Fetch and unpack http://mirror.ctan.org/systems/ texlive/tlnet/install-tl-unx.tar.gz

2. Follow the instructions at http://tug.org/texlive/quickinstall. html

3. Once TeX Live has finished installing, run your sys- tem’s “Add/Remove Softwarež tool.

4. Find “texworksž, select the newest version and install. If you run into problems, there are mailing lists at http://tug.org/

mailman/listinfo/tex-live and http://docs.miktex.org/manual/lists. html for TeX Live and MiKTeX, and MacTeX help at http://www.tug.org/ mactex/help/ . There is also a list of places where you can ask for help in Appendix C (Need More Help?).

3.1 TeXWorks

Hopefully you’ve managed to successfully install TEX and TeXWorks as de- scribed above, so let’s test it out.

First run TeXWorks. On Windows, you can access it via the Start menu. On GNU/Linux, it’s probably located in ApplicationsÏOffice, or you can type texworks in a terminal . You should now see the TeXWorks window. The button marked with a grey triangle in a green circle is the build or typeset function. It runs the application in the drop-down list next to it. This is set to pdfLaTeX, which is what we want for now.

It’s a good idea to switch on the syntax highlighting, if it isn’t already on. This is done via the FormatÏSyntax Coloring sub-menu. Make sure the LaTeX item is selected.

Next, type in the following sample source code, as shown in Figure 3.1 (the commands used here will be described in more detail in Chapter 4 (Creating a Simple Document)):

↑ Input

\documentclass{scrartcl} \begin{document} This is an example document. \end{document}

↓ Input

Pay close attention to the backslashes at the start of each command

name. If you find the font is a bit too small for you, you can make it larger name. If you find the font is a bit too small for you, you can make it larger

dialog box. Set the font size as appropriate. Then save the document, using the FileÏSave As menu item. I called my document example1.tex (remember the .tex extension and stick to file names that only consist of alphabetical characters, digits and hyphens Ð don’t uses spaces or underscores).

Now that you have saved the file, you can run pdfLaTeX. Make sure the drop-down list next to the build button has “pdfLaTeXž selected and click on the build button. If all goes well, a new window should open displaying the typeset document ( Figure 3.2 ).

Now let’s see what happens if there is an error in the source code. In Figure 3.3

I have misspelt the \documentclass command. This time, when

I click on the build button, I get the error message: ! Undefined control sequence.

l.1 \documentclas

{scrartcl}

? (Shown in Figure 3.4 .)

Here “Undefined control sequencež means an unrecognised command, and below that message, “l.1ž means the error was encountered on line 1. An input line at the bottom of the window has appeared with a cursor.

L A TEX is in interactive mode and is awaiting a response. There are several responses, but I’m only going to mention two of them:

1. Type h and press the Return/Enter key . This displays a short help message and awaits a new response (see Figure 3.5 ).

2. Type x and press Return/Enter. This aborts the L A TEX run. Notice that the green circle button with the grey triangle has turned into

a red stop button. This button can be used to abort the process instead of typing x. Now, there is a second tab at the bottom of the TeXWork’s window ( Fig- ure 3.6 ). This lists the error message and provides a link to the line where the error occurred. Clicking on this link highlights line 1. Next I need to fix the error by correcting the spelling of the command. Once it’s fixed,

I can click on the build button. Here’s another error you might encounter: I’m now going to misspell

the class name. It should be scrartcl, but in Figure 3.7 it has been misspelt. This time, when I click on the build button, I get the error:

! LaTeX Error: File ‘scrartc.cls’ not found.

I have two choices: type in the correct name on the line below “Enter file name:ž or I can abort the process using the red abort button. In either case

I need to go back and fix the error in my code.

Figure 3.1 Source Code for an Example Document. (Syntax highlighting switched on.)

Figure 3.2 The Typeset Document

Figure 3.3 The Source Code Has a Misspelt Command

Abort

Error Message

Line Number

Input Line Figure 3.4 An Error Message is Displayed

Figure 3.5 A Short Help Message

Figure 3.6 Error Tab

Figure 3.7 Misspelt Class File

Chapter 4