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:
Its beautiful typeset output is second to none.
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} Input stdclass.inc
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.