# Create LaTeX documents graphically with LyX

Take the pain out LaTeX formatting; preview as you write, on your platform of choice

TeX, released in 1978, is the markup language that Donald Knuth created for typesetting his Art of Computer Programming book series. TeX was soon widely adopted in science and academia, but using TeX markup directly can be somewhat cryptic. The LaTeX macro language, created by computer scientist Leslie Lamport a few years later, lifts TeX markup into the realm of structured documentation by simplifying the identification of document types and their logical components, such as sections, paragraphs, lists, figures, and headings.

Markup languages such as LaTeX are popular in academic and scientific circles because they make it easy to merge documents from multiple authors into a single publication with a consistent structure. However, their use typically requires an iterative write/markup/preview sequence. The preview stage of that sequence enables authors to verify their markup and to see what the formatted document will look like. Marking up and previewing LaTeX documents are typically done using separate, external applications — a process that can interrupt an author's concentration (or provide opportunities for procrastination).

The LyX document processor came into being at the turn of the century. LyX simplifies writing and editing in LaTeX because you see what the formatted document looks like as you write, rather than as a separate preview stage. LyX introduces the WYSIWYM (What You See Is What You Mean) concept to differentiate between graphically creating structured documents and graphically creating documents with no mandatory structure (classic WYSIWYG — What You See Is What You Get). LyX also provides publication-specific templates for many scientific and academic publications. With the templates, you can use any LaTeX macros and styles that a publication provides; they also help ensure that you don't use LaTeX macros that are invalid in submissions to that publication.

This article gives you a comprehensive introduction to LyX. You'll see how to install, use, and customize it on your operating system of choice, and how to take advantage of LyX templates.

## Installing LyX on your system

LyX is supported on Linux, Windows, Cygwin, Mac OS X, IBM® OS/2®, and Haiku (a BeOS-inspired operating system). Executable installers are available for them all. Also, most Linux distributions provide installable versions of LyX in a centralized repository for that distribution, so you can install LyX without separately downloading an installable package in that distribution's package format.

After you download the installer for your platform, install LyX like any other software package. LyX packages for Windows include a bundled version of TeX/LaTeX called MiKTeX. The Linux and Mac OS X LyX installers require that you separately install a version of TeX/LaTeX for that platform. (See Related topics for links to downloads and related information.) Some Linux platforms require that you install other packages to access specific LaTeX macro packages, such as the `AMS TeX` macro package that publications from the American Mathematical Society use.

## Creating and editing documents in LyX

To start LyX, click the LyX menu entry or execute the `lyx` command from the command line. The first time that you start LyX, it displays an introductory document (/usr/share/lyx/examples/splash.lyx on Linux systems) that provides links to various portions of the LyX documentation and the LyX home page. Each subsequent time that you start LyX, it displays a generic splash screen with the LyX logo and version information.

### Create and edit standard LaTeX documents in LyX

To create a new LaTeX document, click File > New. Figure 1 shows the new but empty document that results:

##### Figure 1. A new document in LyX

You can either enter text or add structural LaTeX commands. To add a structural LaTeX command:

1. Click the formatting drop-down menu at the upper left, directly below the File menu.

A list of available structural units opens.

2. Select the LaTeX markup element that you want to insert.

The selected markup element is inserted into the document at the current cursor position. The cursor position changes to reflect any formatting that is associated with the inserted element.

After you insert a LaTeX element, enter the text that is associated with that element, and press the Return (or Enter) key to terminate the content for that element. Figure 2 shows a sample document after the addition of standard LaTeX elements for a `title`, an `author`, a `section`, and some standard text:

##### Figure 2. Sample in-progress document in LyX

From the Insert menu, you can add many different LaTeX elements in the context of the current document or structural element. The items in the Insert menu are especially helpful for adding formatting characters (such as nonbreaking spaces, line breaks, and page breaks), special characters, special types of lists (such as a table of contents or list of tables), and much more.

To see both the WYSIWYM version of the document that you're creating and the LaTeX markup for that document, click View > View Source. The document window splits into two sections: The top portion displays the WYSIWYG version of the document, while the lower portion displays the LaTeX markup for the current portion of the document. Figure 3 shows an example:

##### Figure 3. In-progress document and LaTeX source in LyX

By default, viewing the LaTeX source for a LyX document displays the LaTeX source only for the current structural LaTeX element. How you view the LaTeX source for an entire document depends on your platform. On Linux, select the Complete source check box. On Windows and Mac OS X, click the drop-down menu that initially displays Current paragraph, and then click Complete source.

### Create publication-specific documents in LyX

LyX provides templates that simplify document creation for various academic and scientific publications. To create a new document from one of these templates, click File > New from Template. Then, select the appropriate template for the document you are creating. Table 1 lists some of the templates that are provided with LyX:

##### Table 1. Popular document templates that are provided with LyX
Template fileUse
aa.lyxArticles for the journal Astronomy & Astrophysics
ACM-siggraph.lyxArticles for the journals of the Association for Computing Machinery (ACM) Special Interest Group on Computer Graphics and Interactive Techniques (SIGGRAPH)
ACM-sigplan.lyxArticles for the journals of the ACM Special Interest Group on Programming Languages
agutex.lyxArticles for the journals of the American Geophysical Union
ectaart.lyxArticles for the journal Econometrica
IEEEtran.lyxArticles in the journals of the Institute of Electrical and Electronics Engineers (IEEE)
svjour3.lyx, svmono_book.lyx, svmult_author.lyx, svmult_editor.lyx, and svmult_appendix.lyxBooks and articles that are published by Springer:
• svjour3.lyx is for journal articles.
• svmono_book.lyx is for books by a single author.
• svmult_author.lyx, svmult_editor.lyx, and svmult_appendix.lyx templates are for the appropriate portions of multiauthor books.
A related template, kluwer.lyx, was used for publications from Kluwer Academic Publishers, which merged with Springer-Verlag to form Springer.

Many of the templates that LyX provides rely on the presence of publication-specific TeX and LaTeX packages that you must manually install on your system. See Add prerequisites for a LyX template later in the article for an example of using a template that requires customizing both your LyX and LaTeX installations.

### Edit existing LaTeX documents in LyX

If you are already working on a LaTeX document and want to take advantage of LyX's ease of use, import the existing document into LyX by clicking File > Import > LaTeX (plain). LyX then displays a standard browse window in which you can navigate to and select the existing document you want to work with in LyX.

### Save LaTeX documents in LyX

To maximize performance, LyX documents that you save by clicking File > Save are stored in a custom TeX/LaTeX-like format that LyX can process quickly, without invoking an external formatter. These files have a .lyx file extension.

To generate a standard LaTeX file from the document you are working on in LyX, click File > Export > LaTeX (plain). This command displays a standard browse window in which you can navigate to the location where you want to save the exported LaTeX file. If you export a standard LaTeX document and then edit it outside of LyX, you must reimport it into LyX (File > Import > LaTeX (plain)) to ensure that LyX is aware of the changes you made to the LaTeX file.

## Printing and publishing documents in LyX

After you work on a document for a while, the WYSIWYM preview of that document that LyX provides might not be sufficient. To see a more accurate rendering of how the final, formatted document will look, click View > PDF. This command (or the View PDF icon in the View/Update toolbar) generates a PDF version of your document and displays it in your system's default viewer for PDF documents. Figure 4 shows the sample document from Figure 3 in Evince (the default PDF previewer on GNOME-based Linux systems):

##### Figure 4. PDF preview of an in-progress LyX document

PDF previews of LyX documents look slightly different from the WYSIWYM preview that displays in LyX itself. To see this difference, compare Figure 3 to Figure 4. PDF previews (and other printable output formats) take advantage of the custom formatting that is provided for portions of the text — such as the word LyX in Figure 4— that map to custom LaTeX macros.

The easiest way to print a LyX document is to use the default PDF preview application for your platform because such applications provide access to a standard system Print dialog. You can specify a target printer with the default LyX File > Print command. But that command can be difficult to use on Windows and Mac OS X because printer names on those platforms can contain spaces. Enqueuing to such printers uses system-specific resources that are more complex than the resources that the Linux/UNIX `lp` and `lpr` commands use.

The preview that is shown in Figure 4 displays the date on which the PDF version of that document was generated. The date is part of the standard title page for LaTeX articles. As you'll see in Add custom LaTeX commands in LyX later in this article, you can add custom LaTeX code to your document to suppress or modify default items such as the date.

Previewing a LyX document creates a temporary PDF file that's not easy to find or use. To create a preview PDF in the same directory as the LyX document that you are working on, click File > Export > PDF. On Linux, LyX also provides two PDF export commands:

• `PDF (pdflatex)` (the simpler and faster of the two), creates a PDF file from the standard .dvi file that LaTeX produces.
• `PDF (ps2pdf)`:
1. Generates a .dvi file.
2. Generates an Adobe® PostScript® file from the .dvi file.
3. Generates a PDF file from the PostScript file.

## Customizing LyX

Like LaTeX itself, LyX is customizable. This section gives you examples of common types of customizations that you might want or need to perform.

### Add custom LaTeX commands in LyX

Some LaTeX elements automatically add other elements to your documents. An example is the LaTeX `title` element, which automatically inserts the current date below the title and other, related elements, such as the `author` element. You can't directly edit or remove these elements in either your LyX document (where they aren't visible) or in the document's LaTeX preview pane. Instead, you must override the default behavior of such auto-inserted commands by adding appropriate LaTeX commands to a standard LaTeX preamble that LyX adds to the current LaTeX document.

For example, you can suppress display of the date by adding the `\date{}` command to the preamble. Or you can set the date to a specific date value by adding the `\date{CUSTOM DATE}` command to the preamble.

To add custom commands to LyX's LaTeX preamble for the current document:

1. Click Document > Settings to display the Settings window.
2. Click LaTeX Preamble in the navigation bar and enter the LaTeX commands that you want to put in the preamble in the text area to the right.

Figure 5 shows an empty `\date{}` LaTeX command being added to the preamble:

##### Figure 5. Adding a LaTeX command to a document's preamble
3. Click Apply at any time to save your changes to the preamble, or click OK to save your changes and close the Settings window.

Figure 6 shows a PDF preview of the same document that is shown in Figure 4, with the date removed through addition of the `\date{}` LaTeX command to that document's LaTeX preamble:

##### Figure 6. PDF preview of a LyX document with no date

Document preamble settings are associated with individual documents. They do not apply to all new documents that are of the same type.

### Add prerequisites for a LyX template

Table 1 lists many of the templates that LyX includes so that you can create articles for various publications. Many of these template documents rely on custom TeX and LaTeX macros that you must obtain from the associated publisher. Some also require that you create a custom layout file for that template type, which LyX then uses when you preview articles of that type.

If you try to create a new document with the `ACM-siggraph.lyx` template, for example, LyX displays an error message. The message states that the layout file for the `ACM-siggraph` document type is missing and that LyX cannot preview documents of this type as it's currently configured. When you click OK to close the error window, LyX displays a LyX document like the one shown in Figure 7:

##### Figure 7. Using a template with missing LaTeX definitions

The document in Figure 7 includes various informational messages that are highlighted in yellow, known in LyX as insets. The first inset provides a link to a page on the LyX website that explains how to install the missing `ACM-siggraph` LaTeX styles. To summarize the contents of that page:

2. Extract the contents of that archive file to the appropriate location for your LaTeX installation.

On Linux systems that use the TeX Live TeX/LaTeX implementation, this location is /usr/share/texmf/tex/latex. (See Related topics for a link to the LyX wiki page with information about the `ACM-siggraph.lyx` template and where to install these styles on Windows and Mac OS X.)

3. After you install the LaTeX macros that this template requires, execute the `texhash` command as the root user to generate the files that the TeX Live distribution uses to locate document-specific styles.
4. Create the layout file — /usr/share/lyx/layouts/acmsiggraph.layout — that LyX uses to preview documents that are associated with this template. Add the following contents to the file:

```#\DeclareLaTeXClass[acmsiggraph]{ACM SigGraph}
Input article.layout```

This layout definition uses the existing layout definition for LaTeX articles.

5. To update your LyX configuration. select Tools > Reconfigure. When this command finishes executing, exit and restart LyX to ensure that it is using the new configuration data.

After you make these changes, you no longer see an initial error message when you create documents with the `ACM-siggraph.lyx` template.

## Conclusion

LyX is a powerful, free graphical editor for documents that use LaTeX, a common markup language for academic and scientific publications and Linux fans everywhere. This article gives you a firm foundation for getting started with LyX but merely scratched the surface of LyX's capabilities. LyX provides access to sophisticated and complex LaTeX features that would otherwise require you to perform multiple web searches, scan the LaTeX documentation, and enter the associated LaTeX incantations manually. LyX is worth installing on any system that you want to use for creating LaTeX documents.

#### Related topics

• LyX: Visit the central location for LyX information and documentation.
• Donald Knuth and Leslie Lamport: Learn more about the creator of TeX and the creator of LaTeX.
• LaTeX: Visit the LaTeX project website for information about the LaTeX macro package for the TeX markup language and document-preparation system.
• TeX Users Group: TUG is a great organization for fans of the TeX markup language and macro packages such as LaTeX. The group's for-members-only "TUGboat" publication is always interesting. TUG's TeX Resources on the Web page has useful links to other TeX-related sites.
• LyX for Linux: This LyX wiki page links to detailed, distribution-specific information about installing and using LyX (and appropriate versions of LaTeX) on various Linux distributions.
• LyX `AcmSiggraph` template: See this page in the LyX wiki for information about where to install ACM-specific styles on Windows and Mac OS X platforms.