Troubleshooters.Com, T.C Linux Library and Litt's LyX Library Present

LyX Gotchas

Copyright (C) 2005 by Steve Litt, All rights reserved. Material provided as-is, use at your own risk.


This document must be used in conjunction with the LyX Quickstart.

LaTeX is a typesetting language considered by many to create the most beautiful and readable documentation. Authoring with LaTeX makes your document printable and readable on a huge variety of paper, paper sizes, operating systems, and digital formats.

LyX is a front end to LaTeX. Using LyX, you can author your paper without distracting LaTeX codes. Book authoring, at least the typing part of it, becomes a secretarial task. After completing the LyX rendition of your book, it will print out as a professionally typeset document.

But there's trouble in paradise. The LaTeX language is huge and complex. The native format of LyX looks confusingly like LaTeX, but is different enough that knowing one doesn't imply knowing the other. When compiling LyX into postscript or PDF format, error messages can be unfathomable or even buffoonishly misleading.

Newly crafted or changed LyX layout files confront the user with a debugging phase reminiscent of self-modifying assembler code. Error messages are of minimal help, so you often need non-obvious diagnostic tests to find a problem. A simple style that would be a 5 minute effort in OpenOffice could be a 2 day affair in LyX.

If you require the spectacular output of LyX, you must take the bad with the good. This document helps you stay clear of some of the worst LyX landmines, so you can produce spectacular printed output with less effort.

A Word to My Critics

In many circles this document will be greeted with indignant accusations claiming ignorance on my part. Some will say that I'm crazy -- LyX is trivially easy. Yes, it's trivially easy if you use only the default settings for whatever document class you're using. Or if a LaTeX/LyX guru creates a layout file to your specifications. But if you need to add styles, such as a note style or a story style, to your document, it can take hours or even days, complete with excruciating debugging.

Many will say my only problem is a lack of LaTeX knowledge. They will tell you I never bothered to read Frank Mittelbach's 1152 page classic, "The LaTeX Companion" (2nd Edition), nor LaTeX creator Leslie Lamport's "LaTeX: A Document Preparation System". They will say I haven't done my homework -- my due diligence. They're absolutely right, I haven't, and I think that's the whole point. I'm a guy who writes books about Troubleshooting. To do so, I shouldn't be required to learn a language that is in some ways more complex than Python, Perl and C++ put together. Don't forget, a Note or Story style can be created within 5 minutes using OpenOffice.

Other critics will state that if I like OpenOffice so much, I should use it, but it is a WYSIWYG (what you see is what you get) wordprocessor instead of the WYGIWYM (what you get is what you mean) typesetter called LyX/LaTeX. This is a strawman argument. It's true you can misuse OpenOffice, MS Word and WordPerfect 5.1, but it's equally true that if you consistently use styles to implement appearance, OpenOffice, MS Word, WordPerfect 5.1, and most other wordprocessors become every bit as WYGIWYM as LyX. It could be further argued that OpenOffice, MS Word and the 15 year old WordPerfect 5.1 are even more WYGIWYM than LyX because, unlike the current LyX 1.3.6, they implement character styles natively, instead of requiring you to use a cumbersome color workaround.

Yes, the critics will howl and call me names. I think a better outlet for their energy would be to help improve LyX and its documentation.

Why I use LyX

After reading the preceding article, you might wonder why I use LyX. The answer is simple enough -- it's better than the alternatives, at least for writing books. Specifically:
  1. Its beautiful typeset output is second to none.
  2. Its native format is human readable and easily parsed by programs a mere mortal can write.
Books I've written in WordPerfect 5.1 and MS Word look like they were written in WordPerfect 5.1 and MS Word. In a subtle way, they don't look like something you'd get from a publisher. My books written in LyX look professionally published.

Then there's the native format. MS Word's secret and proprietary binary format is by definition unfathomable. OpenOffice has a zipped XML format, but it's so complex that for practical purposes a mere mortal cannot parse and change it. A LyX file is easily read and changed with a text editor or a simple computer program.

The old saying is: "If you're not part of the solution, you're part of the problem.". This document is my effot to become part of the solution for LyX gotchas.

Gotcha: LyX Code vs. LaTeX Code

This can lead to extreme problems with understanding and debugging.

There's a detailed article on LyX code vs. LaTeX code here.

Basically, LaTeX code is anything between a Preamble and EndPreamble. Anything else is LyX except for the first few lines:

#% Do not delete the line below; configure depends on this
# \DeclareLaTeXClass[memoir]{storybook}

Gotcha: LyX Styles must end with End

LyX styles begin with the keyphrase Style StyleName, and end with the word End. If you forget the word End you'll get really bizarre errors that might look intermittent, or might look like an error message with the wrong line number, or might even reference material you've since deleted or commented out (go figure).

If your LyX styles don't show up in LyX's environment dropdown, look for a style not ending with End.

Gotcha: Keep Your LaTeX Together

I highly suggest you keep all your LaTeX code at the beginning of your .layout file, and your LyX code at the end, and that you do not intersperse them. Note that this goes against what I advised in the LyX Quickstart.

By keeping LyX and LaTeX in their own sections, you minimize the likelihood of confusing them, or of accidentally coding the syntax of one in the other. LyX styles can either forward or backward reference their LatexName component, so it's easy to do and prevents the wierd errors when you make a mistake interspersing them.

Gotcha: Use Units on All Lengths and Margins

A very common error is forgetting the units on margins and other LyX lengths. Doing so does not produce an error message, but instead the OK and Apply buttons are grayed out until all lengths have units. We all assumed this was a LyX bug the first time we used LyX.

So if your OK and Apply button are grayed out, check that all lengths have units.

Units are also necessary when hand-coding LaTeX, and forgetting the units will produce an error.

Back to Troubleshooters.Com * Back to Linux Library * Litt's LyX Library