TeX Compilation: step-by-step guide

In this section we show WinEdt in action with step-by-step illustration of the Edit-Compile-Preview cycle. Note that WinEdt's documentation does not deal with the syntax of LaTeX. The fastest way to learn [La]TeX is to base your work on the examples of similar nature. Extensive documentation and literature about the art of typesetting in TeX is also widely available. You'll find downloads, links and references on TeX Users Group (TUG) home page:

http://www.tug.org

Here we focus on WinEdt's role in TeX-ing! Not all TeX Systems include PDF TeX accessories and not all previewers have a support for src specials and DVI Search. Our example works with fully featured MiKTeX 2.1 which supports many extras (beyond basic TeX-ing)...

An "empty" copy of WinEdt is running:

Most of the Menu Items and associated tool bar buttons are disabled. In particular, all TeX Icons are currently disabled. This does not mean that WinEdt cannot find your TeX. It simply indicates that currently there is no TeX document loaded. As soon as you'll open or create a TeX document the compilation commands will become enabled. For our purpose let's open a Sample Thesis that comes with WinEdt:

That's more like it:

The compilation commands such as [PDF] TeXify, LaTeX and TeX are now enabled indicating that we can compile the current TeX Project with the compiler of our choice (since this is a LaTeX document we have to use LaTeX version of the TeX compiler). MiKTeX's TeXify accessory can be used to perform a full compile (run the compiler, BibTeX and MakeIndex as many times as necessary to update the references, bibliography and index). This would be the fastest way to compile the document but for educational purposes we'll take care of things manually. Note that certain commands are still disabled. There is good reason for that: DVI Preview or dvi2ps require the dvi file (which will be created by the TeX Compiler) and currently this file doesn't exists. Let's make it! Ready? Press the LaTeX button...

By default (depending on your choice of the TeX Execution Mode) the Console Window (with black background) appears and LaTeX is doing its thing: complaining about some undefined references and citations and displaying the page numbers as it progresses through the text. When there are no Errors the Windows disappears quite fast and you are not expected to process the feedback from the console Window. In WinEdt you can Press the Ctrl+E (Errors... command in the Search Menu) shortcut to display the LOG file at the bottom of the screen. This file contains all the information produced by TeX. Furthermore, subsequent command search the LOG file for errors and warnings and display the corresponding line in WinEdt. Although the warnings in the current LOG file are not serious (they will disappear once we compile the bibliography and re-compile the source) let's try it (you can either keep on pressing Ctrl+E to "walk" through the errors or else use the GUI in the Error Form). To close the Errors dialog click on the X in the left top corner of the form.

By the way, the location of the Error Form can be changed in the Appearance Dialog. By default the from is docked at the bottom of the Client Window but this can be changed if you don't like it there.

You have noticed that BibTeX and DVI Search and Preview and dvi2ps commands are now enabled: the file Thesis.dvi exists and the commands now make sense. Let us first get rid of all the Warnings by properly compiling the bibliography. Press the Button BibTeX and then LaTeX two more times to get all the cross-references right (TeXify does all that in one step)... There are no more Warnings or Errors. Close the LOG file (X in the top left corner of the Error Form). Now press the DVI Preview Button. The previewer starts (in MiKTeX it is called YAP, fpTeX comes with WinDvi and YandY TeX has DVIWindo). Move a few pages down and see how the compiled document looks.

Note that your actual position was in the Introduction Chapter (T0.tex). So, how did WinEdt know to compile the main file Thesis.tes rather than the current chapter (which would fail to compile without a proper preamble present in the main file). This is because Thesis.tex is set as the main file. To remove or set the current file as the main document use the commands in the Project Menu or the "+/-" buttons in the toolbar. For your Convenience the name of the currently set main file is displayed in the last panel of WinEdt's Status Line. When you'll start working on your projects you should (re)set the main file to your main document or else remove it if you are working on a simple one source file TeX document.

WinEdt's Status Line displays a panel "--src" (it can be toggled between empty and "--src" by clicking on it. The "--src" command qualifier instructs TeX to insert "SRC Specials" in the resulting dvi file. These specials allow the previewer to link the compiled document with the actual position in the source file (+/- a few lines). This makes the Forward and Inverse DVI Search possible. Go back to WinEdt: you are currently at the position of previously undefined citation. Press the Button DVI Search. YAP now starts displaying the position roughly corresponding to your current position in WinEdt. Note a circle in YAP marking the current line:

Even more useful is the Inverse DVI Search which can be initiated from the previewer (by double-clicking on a preview) and as a result the editor displays the corresponding source line (again there is margin of error since the exact position may not be available from the inserted src specials). For example, in YAP go to Page 50 (see the Go Menu in YAP) and double-click on the displayed equation (at the and of the Definition 3.3.3):

WinEdt gets in the foreground, Opens Chapter 3 and highlights the corresponding line:

DVI Search is an extremely useful feature since it allows you to quickly correct errors spotted while you are examining the compiled document. However, for this to work as indicated above you have to define the command that should be used by YAP to initiate the Inverse Search. By default, YAP may be configured so as to call some other editor (eg. Windows Notepad).

In YAP's View Menu start the Options Dialog and click on the Inverse Search Tab:

Enter

        WinEdt.exe "[Open(|%f|);SelPar(%l,8)]"

as a command line and leave the drop-down (Program) list empty. Your version of YAP may be configured differently. You should consult YAP's documentation for detailed instructions (WinEdt is irrelevant to this YAP's configuration issue). Based on the information provided by YAP (or your previewer) you should find the way to specify the editor and enter the command line as indicated above.

You have seen enough to be able to do the same procedure with PDF LaTeX and create a pdf file which can be previewed in Acrobat Reader. Note that there is no "--src" support for this format. Alternatively, dvi2pdf converter yields a very similar result.

By default (it can be changed in the TeX Configuration Wizard: Execution Modes) WinEdt calls the dvi2ps converter through a special interface that allows you to specify additional qualifiers. For the meaning of such switches you have to read the documentation on dvips in MiKTeX's Manual or the help for dvips:

The default -P pdf switch causes dvips to use type 1 fonts. You should use this fonts if you plan to distil the ps file to pdf (either with Adobes Distiller or Ghostscript gswin32c.exe to which WinEdt provides an interface). However, this switch may cause problems with certain code pages (eg. strange characters in the middle of some words). If you are experiencing such problems you'll have to remove the above switch and use dvips without any qualifiers. Note that you don't have to specify the pages: for all pages just leave the fields empty and press enter. Note that WinEdt is irrelevant to any problems with the dvi to ps conversion: it is up to dvips to perform the task and process all the switches...

The resulting "ps" (postscript) file can be previewed and printed with GSView (you'll find a link on TeX Users Group home page).

By now you are probably eager to start working on your own projects. However, let us use this opportunity to illustrate some advanced WinEdt features which will make your work easier...

When you setup your project it is important that you set the main file and build the project tree. The items in the Project Menu (or the associated tool bar buttons) can be used to accomplish the task. Even if you don't want tree visible (in your left panel, you should let WinEdt build it for the purpose of automatic referencing):

WinEdt builds the project tree based on the Input Directives as specified in the Preferences Dialog:

In the Main Document sample you'll see a line like:

        %GATHER{xBib.bib}   % For Gather Purpose Only

This "dummy" input directive is seen by TeX as a comment. However, WinEdt uses it to include your bibliography file(s) to the project tree. This makes it possible to collect bibliography items for easy citations. If you type \cite{} you activate an "Active String" which displays a list of sorted citations in a special. Double-clicking any of the items inserts the citation between curly brackets: try it!

If you press any Fx (eg. F1..F24) key in the interface the appropriate record in the .bib file gets selected. Pressing Enter inserts the selected citation while ESC closes the interface without taking any further action. The Macro response is defined in the script cite.edt in WinEdt's Macros\Active Strings folder. If you take a look at the macro source you'll see that the parameters can be modified so that the bibliography record is automatically selected when you select an item in the list. If this is your preferred behavior you can change the original macro.

You can place bibliography files in the same folder as the main file. However, since such data is usually shared between your projects you may create a global bibliography and place it in your BibTeX folder in the local texmf tree. Your TeX's Manual explains how to do this and describes any other actions that should be undertaken (eg. MiKTeX's Users have to use MiKTeX's Options Interface to refresh the filename database). Note that WinEdt is not aware of the folders where your TeX accessories look for input od data files. If you decide to use the global Bibliography Data base you should specify the fill path in the "dummy" Gather Directive. For example:

        %GATHER{C:\texmf\bibtex\myBib.bib}   % For Gather Purpose Only

Since TeX treats this line as a comment this does not reduce portability of your documents. Once again: if TeX or BibTeX cannot find any of your input files this is not a WinEdt-related problem. Consult the Manual that comes with your TeX System!

If you organize your TeX project in subfolders relative to the main file you have to use UNIX-style folder specification in "proper" include directives. For example:

        \include{chapter1/section1.tex}

        \include{chapter1\section1.tex}

WinEdt understands both but TeX does not "like" backslashes "\" in filenames: you must use forward slashes instead!

Responses such as the "\cite{}" are defined in WinEdt as Active Strings: typing any such string triggers the execution of the associated macro. Such responses are defined in the Settings Dialog:

There are plenty of such strings defined but not necessary enabled in the default settings. Depending on your style of editing you may want to enable more such responses (eg. automatic insertion of closing brackets). For example if you type:

         \begin{proof}}

in a TeX document the active string "\begin{?}}" kicks in and automatically completes your environment by inserting a properly indented "\end{proof}" and placing the cursor in the middle... Similarly, "\begin{?}>" allows you to change the name of the current environment (you are prompted for a new name and both \begin and \end are properly updated...). You don't have to be an expert in WinEdt's Macro language to enable or disable such responses or even add your custom ones based on the existing examples.

WinEdt can also collect certain items in your project files and display them in a special "Gather" form at the bottom of your screen. Such data can be used for navigating and cross referencing:

Gather Interface is initialized in WinEdt.gdi (on-line help provides the details should you want to customize it)...

If you press the "Sigma" button in the default Toolbar WinEdt displays a special GUI consisting of over 500 LaTeX symbols (organized in a few pages). Pressing the button again hides the control:

Important: if you want to use all the symbols in your LaTeX Document you should load the amsmath package in your preamble:

        \usepackage{amsmath}

The file "_Gui Source.tex" in WinEdt's Bitmaps\GUI folder describes how the images were generated (it is time-consuming but it can be customized)...