Create LaTeX documents graphically with LyX

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

William von Hagen August 16, 2013

LyX is a graphical tool, with a familiar drop-down and content-driven menu system, for writing
and editing LaTeX documents. TeX and its higher-level macro language, LaTeX, are powerful
document markup languages that are the de facto standard for Linux® users. New users can
find them difficult to work with because you must know the available markup tags, the contexts
they can be used in, and how to use a text editor and previewing tool. LyX simplifies the entire
process of working with LaTeX documents — not just on Linux. Learn how to install, use, and
customize LyX on Linux, UNIX®, Windows®, and Mac OS X systems.

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

© Copyright IBM Corporation 2013 Trademarks

Create LaTeX documents graphically with LyX Page 1 of 12
developerWorks® ibm.com/developerWorks/

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.

Building LyX from the source code

As with all open source software, the source code for LyX is freely available if you want to
build it yourself to get the latest fixes and features. If Git is installed on your system, you can
check out the code through the git clone git://git.lyx.org/lyx command.

Some additional packages, such as qt4 and qt4-devel, are required to provide the
platform-independent graphics subsystem that LyX uses. See the README and INSTALL
files in your LyX source code checkout for detailed information about building LyX for your
platform. Building LyX for Linux also requires the standard automake, autoconf, and
gettext packages (and the GNU Compiler Collection).

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:

Create LaTeX documents graphically with LyX Page 2 of 12

ibm.com/developerWorks/ developerWorks®

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:

Create LaTeX documents graphically with LyX Page 3 of 12

developerWorks® ibm.com/developerWorks/

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:

Create LaTeX documents graphically with LyX Page 4 of 12

ibm.com/developerWorks/ developerWorks®

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 file Use

aa.lyx Articles for the journal Astronomy & Astrophysics

ACM-siggraph.lyx Articles for the journals of the Association for Computing Machinery
(ACM) Special Interest Group on Computer Graphics and Interactive
Techniques (SIGGRAPH)

ACM-sigplan.lyx Articles for the journals of the ACM Special Interest Group on
Programming Languages

agutex.lyx Articles for the journals of the American Geophysical Union

ectaart.lyx Articles for the journal Econometrica

elsarticle.lyx Articles in journals that are published by Elsevier

IEEEtran.lyx Articles in the journals of the Institute of Electrical and Electronics

Engineers (IEEE)

Create LaTeX documents graphically with LyX Page 5 of 12

developerWorks® ibm.com/developerWorks/

svjour3.lyx, svmono_book.lyx, svmult_author.lyx, svmult_editor.lyx, and
svmult_appendix.lyx
Books 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):

Create LaTeX documents graphically with LyX Page 6 of 12

ibm.com/developerWorks/ developerWorks®

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.

Create LaTeX documents graphically with LyX Page 7 of 12

developerWorks® ibm.com/developerWorks/

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.

Create LaTeX documents graphically with LyX Page 8 of 12

ibm.com/developerWorks/ developerWorks®

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:

Create LaTeX documents graphically with LyX Page 9 of 12

developerWorks® ibm.com/developerWorks/

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:

1. Download acmsiggraph.zip, which contains the ACM SIGGRAPH LaTeX styles.

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.

Create LaTeX documents graphically with LyX Page 10 of 12

ibm.com/developerWorks/ developerWorks®

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.

Create LaTeX documents graphically with LyX Page 11 of 12

developerWorks® ibm.com/developerWorks/

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.
• LyX: Download the LyX version for your platform.
• TeX Live: Find information and downloads for TeX Live, a recommended TeX and LaTeX
implementation for Linux systems. TeX Live is available through a central repository for your
Linux distribution.
• MacTeX: Find information and downloads for a recommended TeX and LaTeX implementation
for Mac OS X.

© Copyright IBM Corporation 2013

(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)

Create LaTeX documents graphically with LyX Page 12 of 12