Troubleshooters.Com Presents

 Linux Productivity Magazine Volume 1 Issue 3, October 2002 LyX Quickstart

Copyright (C) 2002 by Steve Litt. All rights reserved. Materials from guest authors copyrighted by them and licensed for perpetual use to Linux Productivity Magazine. All rights reserved to the copyright holder, except for items specifically marked otherwise (certain free software source code, GNU/GPL, etc.). All material herein provided "As-Is". User assumes all risk and responsibility for any outcome.

 Everything that is really great and inspiring is created by the individual who can labor in freedom. -- Albert Einstein

# Editor's Desk

##### By Steve Litt
When converting from Windows to Linux in March 2001, I was troubled by what I perceived as a lack of book writing software for Linux, so my assumption was that I'd continue writing books in MS Word. This decision wasn't arrived at lightly. The Abiword and Kword software available back then seemed useless for long documents. StarOffice had major cut and paste problems, and various other quirks rendering it a suboptimal book authoring package. LyX looked very promising, but it seemingly could not export to any format in which styles were preserved, so I worried that if my documents were in LyX, I couldn't transition to another tool if so desired. This worry turned out to be false, but I didn't know it at the time.

Docbook XML looked like a great alternative. Standard. Up and coming. Exportable to just about anything via scripts, with content totally separate from appearance. But alas, Docbook XML front ends were few and far between. LyX can be used as a front end for Docbook SGML, but not Docbook XML. There were a few other front ends in their infancy, but nothing that could really write a book. The only mature front end was EMACS, and that's a problem because EMACS and I don't get along.

So I settled on retaining MS Word. I'd VNC to my Windows box in the corner, and MS Word would Samba back to my book's file on my Linux desktop box. Perfectly workable.

Except that as time goes on, you really start noticing what a pain Windows and even MS Word are. I started looking around again. The turning point came while examining a LyX document in VI. It was text, human readable, and obviously very parsable. My one objection to LyX had been lack of styles-based export. But a look at the native LyX document proved it was one of the most exportable, because one could write a Perl program to turn LyX data into anything, including XML.

It took another 2 weeks to thoroughly evaluate LyX, making sure there were no dead ends that could stop my book in the middle. There weren't. In August 2001 I stopped my evaluation and began to write.

Today I have a beautifully typeset 309 page book, "Troubleshooting Techniques of the Successful Technologist". It has a stylistic consistency I've never achieved with MS Word or WordPerfect. It has an accurate table of contents, unlike most of my previous books, whose software (Word or WordPerfect) goofed up page numbers so that hand editing was required for the table of contents. My book has a very nice index -- a feature I'd never included in previous books because it seemed too difficult with Word or WordPerfect.

One might assume that life was easy with LyX. It wasn't. Unbelievably, LyX doesn't support character styles. Creating  paragraph styles can take hours or even days instead of the minutes you'd expect from using MS Word or WordPerfect. LyX doesn't have MS Word's outline view. Although LyX made most work trivial, every once in a while you run into a seemingly trivial task, such as adding extra lines to the title page, that require much research and experimentation. LyX can be daunting!

Which is exactly why I'm writing this quickstart. This issue of Linux Productivity Magazine gives you the tips and secrets necessary to avoid the time consuming blind alleys I was forced to travel. Using this LPM issue, your use of LyX will be relatively straightforward. When you've read this magazine, you'll be able to write books in LyX.

And remember, if you use Linux or other free software, this is your magazine. Enjoy!

# We Stand On Their Shoulders

##### By Steve Litt
LyX is a miraculously productive way to write books, articles, reports, slideshows, and other long documents. The LyX project development team has done a superb job. There are few bugs, and every version brings ever more wonderful features.

LyX is more than a great product. It's backed by a vibrant, knowledgeable and helpful community. Their mailing list is a fountain of information. Their main list has many tens of experts on LyX and LaTeX, and every time I think I'm a really smart LyX guy I read their posts and realize I'm still a raw newbie. Almost everything you read in this Linux Productivity Magazine issue came directly or indirectly from the LyX list.

The LyX website has a huge subsite devoted to various LyX solutions. It's a little hard to search and navigate, but it's worth it, because solutions to most common and not-so-common problems are there. This subsite was put together by LyX expert extraordinaire Herbert Voss.

A special shout-out goes out to LyX Guru Dekel Tsur, who answered my question about how to make character styles. It was Dekel who showed me the how to code Color Pseudostyles as a substitute for character styles. Color pseudostyles allowed me to proceed with the writing of my book, and indeed to adopt LyX as Troubleshooters.Com's official book authoring software.

No recognition is complete without thanking Richard Stallman, creator of the GNU GPL, which made all free software and Open Source possible. And certainly Linus Torvalds must be thanked for founding the operating system that moves us from what was our comfort zone, enabling the masses to discover LyX. Beyond that, thanks to everyone who works on free software -- we stand on your shoulders.

# LyX Overview

##### By Steve Litt
LyX defies categorization. It's not a word processor, because it doesn't facilitate appearance editing the way word processors do. It's not a desktop publisher, because you don't lay out pages -- you type content. It's not a typesetting program, because it does much, much more than typeset.

LyX is a styles-based, write once, publish everywhere authoring tool. A LyX document can be exported to postscript, pdf, paper (of any size -- it's simple to change the paper size, and everything falls where you'd expect), HTML, and probably soon other formats. For each format, LyX "does the right thing". And if your idea of the right thing isn't the same as LyX's, you can fix it with a few style changes.

On a more technical level, LyX is a GUI front end to the LaTeX publishing language. The fact that LyX is GUI means that styles can be represented in the LyX environment with a somewhat similar appearance to how they'll appear on paper. In other words, you can construct your style so that if it appears large and italic on paper, it will appear large and italic on in the LyX window.

The other cool thing about LyX is that even though LaTeX is a markup language, LyX hides most markup, so as an author you don't need to break your train of thought to insert codes. You simply choose paragraph styles, or, as you'll learn later in this magazine, color-based pseudo character styles. Nevertheless, for that rare case where you need to "fine tune" a piece of text, you can go into TeX mode, which is markup. TeX mode is often called Evil Red Text (ERT for short), because in older LyX versions it appears in red on the LyX screen, and it's LaTeX markup which can be extremely complex for the uninitiated. But ERT guarantees that with enough drive and knowledge, you'll be able to accomplish just about anything in LyX.

 NOTE In versions 1.2.x and later, ERT is no longer red, but instead appears as a button which, when clicked, expends to show the LaTeX code.

Fine tuning is best done seldom, because excessive fine tuning ruins the document's consistency. LyX is made for documents that should be consistent. You would never use LyX for a flyer or a short advertisement where layout is everything. You'd use it for a long article, book, slideshow, or website, in which consistency is key.

So try not to fine tune your document, but instead fine tune its styles. How to fine tune your styles is covered later in this magazine.

As previously mentioned, LyX is a front end to LaTeX. LaTeX is a macro language used to produce the TeX language. TeX is a typesetting language, invented by Donald Knuth, the eminent computer scientist. So the conversion goes like this:

LyX==>LaTeX==>TeX==>DVI==>Postscript
Besides being a front end, LyX is also a language. A LyX document is not entirely valid LaTeX, although much of a LyX document might be valid LaTeX. So a more complete description of the process would look like this:
Author==>LyX front end==>LyX language==>LaTeX==>TeX==>DVI==>Postscript
This is somewhat problematic, because the LyX language is very similar to LaTeX, but not the same. As a new LyX user, one of your greatest challenges will be to know the differences between LyX language and LaTeX, and when to use each. If you read this magazine completely you'll understand.

Last but not least, here is a screenshot of a LyX session (editing my book, as a matter of fact):

Starting at the top is the titlebar, and then comes the menubar, with all the usual menu categories. Then comes the buttonbar, whose leftmost element is a selector for the paragraph style. Paragraph styles are known as "Environments" in LyX. Below the buttonbar is the editing area where you type in your content. The red text is ERT (TeX mode), and the black text is pure content. The reason there's so much ERT is that this is my title page, which needed quite a bit of fine tuning. If you're using a browser that can't properly render .png files, the colors of the preceding screenshot are as follows:

 Titlebar Dark green Titlebar text Yellow Menubar Gray Menubar text Black Buttonbar Gray Buttonbar text Black Edit area background Bright but low saturation yellow Normal text in edit area Black

And here are the uses of some of the buttonbar buttons:

 Environment chooser Lets you choose an environment, which is the LyX word for paragraph style. Emph (emphasis) button For emphasized text, translates directly to italics. Noun button For proper names and first use of new words, translates directly to small caps Code button For computer code within text, converts directly to monospaced. This button probably won't appear in your setup -- I installed the button myself using techniques from /usr/share/lyx/doc/Customization.lyx. Tex (ERT) button To enter LaTeX directly into the document, press this button. Note it's pressed in the screenshot. In versions before 1.2.x, the text you enter will be red, hence the name Evil Red Text. Version 1.2.x and later show this inline LaTeX as an expandable button. Math button Press this button to enter math mode, where you can enter equations that print out like they would in a math book.

Note that the Emph, Noun and Code buttons do not insert a character style, but instead insert a typeface. Unfortunately, LyX has no built in character styles. Later in this magazine you'll see how to create color based pseudo character styles to accomplish what you want.

# Understanding LyX Through Contrasts

##### By Steve Litt
One of the most effective routes to understanding is the exploration of contrasts. In this article we'll examine the following contrasts:
• Fine Tuning vs. Consistency
• Graphical Layout Specification vs. Numeric Layout Specification
• Word Processors vs. Content Authoring Tools
• Using Styles vs. Creating Styles
• Default vs Created Styles
• Character Styles vs. Paragraph Styles
• LyX the Language vs. LyX the Front End
• LyX Code vs. LaTeX Code

## Fine Tuning vs. Consistency

Fine tuning is the word LyX folks use for micromanaging the appearance of each page of your document. Such micromanaging almost guarantees that your document, if long, will not have a consistent appearance throughout.

Some content is best micromanaged. Certainly flyers, advertisements and glossy brochures are most effective when each individual element is placed and sized just so. But anything over 10,000 words (15-30 typewritten pages or longer), and certainly any book, must feature consistent styles throughout.

Fine tuning is done by assigning attributes to individual text, pictures, or whatever. Consistency is achieved by assigning attributes to styles, and then assigning those styles to text and other elements of your document.

Sometimes the requirement for consistency is not within the document, but instead between documents of the same type. For instance, you might need all your letters to appear the same. In such a case, you'd start with a template consisting of elements with the right styles. Other business documents such as legal documents, order forms and the like are also candidates for consistency.

LyX does an outstanding job at producing fine looking, consistent documents based on styles. LyX can do fine tuning, but doing so is difficult enough that you'll probably want to use other software (KWord, Gimp, etc) for brochures, flyers, advertisements, and other content whose look must be artistically managed at the page and element level.

## Graphical Layout Specification vs. Numeric Layout Specification

Products like Microsoft Word and OpenOffice offer the easy to use and intuitive feature of graphical layout specification. You can highlight text and set it 3 points bigger, bold and italic, with a couple mouse clicks. You can even drag paragraph margins to make paragraphs fatter or skinnier. This type of work can be thought of as graphical layout specification.

There's also numeric layout specification. You generally need to insert tags. Creating the right spacing requires trial and error -- changes to numbers describing the layout, followed by viewing the final output, to determine how close you got to your ideal layout.

Obviously graphical layout specification is faster, so why would anyone want a product with numeric layout specification? The simple answer is accuracy and adaptability. My oldest book, "Troubleshooting: Tools Tips and Techniques" was written in WordPerfect 5.1, which used numeric layout specification. Using styles, I created chapter pages with beautiful page borders and outline boxes. A few years later I tried to convert this document to MS Word, and failed miserably. The chapter pages were flawed, and nothing I could do in MS Word could fix them. MS Word uses graphical layout specification, and when it comes to exacting layout, there's no substitute for numeric layout.

Graphical layout is easier, numeric layout more precise. LyX uses numeric layout. Fortunately, the numeric layout need be done only once for each style, and the style can be used throughout the document, or even across multiple documents.

## Word Processors vs. Content Authoring Tools

The tools commonly called word processors are optimized for easy use by untrained people. They excel at that.

Most other content authoring tools are designed so that the author can work entirely within a predefined set of styles. The styles relate to the content, not to any desired appearance. This usage of styles frees the author from the need to consider appearance.

When the document is complete, if the appearance isn't as desired, the styles can be modified to create the desired appearance throughout the book, without the need to search for specific text.

LyX is a content authoring tool, not a word processor.

## Using Styles vs. Creating Styles

When writing Samba Unleashed, I was given an MS Word template with relevant styles, and the Macmillan style guide specifying when to use each style. It was trivial to follow the style guide instructions, and the document turned out exactly how Macmillan's editors, indexers and layout people needed it.

Somebody had to create those styles, and that was fairly difficult. However, it was not as difficult as it could have been, because word processors such as MS Word, OpenOffice and WordPerfect make it fairly easy to create styles.

Unfortunately, creating styles in LyX is downright difficult, because LyX uses numeric layout specification and for other reasons that will be discussed later in this magazine. And yet there is a small body of knowledge, revealed later in this magazine, that removes most of the complexity associated with creating styles in LyX. By the time you've finished this magazine you won't consider it difficult to create styles in LyX.

## Default vs Created Styles

LyX comes with several sets of predefined styles called "Document Types" . Ready made document types include "Book", "Article", "Report", "Letter", and many, many more. If you're willing to accept the default look and behavior of the document type you select, LyX authoring is trivial -- probably easier than using MS Word, OpenOffice or WordPerfect.

But the minute you're dissatisfied with the look of any of the predefined styles, or if you find yourself in need of a new style to be applied to a type of content not anticipated by the person who created the document type, you must modify or create the style yourself. And that, my friends, is difficult -- much more difficult than style creation or modification in Word, OpenOffice or WordPerfect.

The dichotomy between default and created styles explains the discrepancy between those who say LyX is "trivially easy" and those who say it has an "immense learning curve". The person who accepts the defaults operates LyX intuitively, while the person wanting to extend the defaults can find LyX extremely difficult.

The articles in this magazine give you the information to modify and create styles without strain, thereby getting the best of both worlds.

## Character Styles vs. Paragraph Styles

Character styles apply an appearance to arbitrary pieces of text. They typically identify attributes of letters and words -- size, typeface, weight, slant, small caps, character and word spacing and the like.

Paragraph styles apply to entire paragraphs, and include not only the text attributes mentioned in the preceding paragraph, but also specify paragraph attributes: Line spacing, interparagraph spacing, indentation, and justification.

In LyX, paragraph styles are called "environments", and are implemented with a richness that leaves other tools in the dust. However, LyX inexplicably has no character styles. This, in my opinion, is by far LyX's worst flaw -- in fact it would be a fatal flaw if not for a workaround associating a color with a set of text attributes.

The LyX mailing list has recently featured discussions on the best way to implement character styles, so I'm confident a future version of LyX will add this desperately needed feature.

Until genuine character styles are added to LyX, the color workaround gives most of the benefits of character styles, and when character styles are implemented, conversion of the color workaround to genuine character styles will be accomplished by simple scripts.  The color workaround is completely documented in a later article in this magazine.

## LyX the Language vs. LyX the Front End

The intent of LyX is to be a front end to the LaTeX macro language, which itself is a macro front end to the TeX typesetting language. LyX has a GUI user interface into which you can type your content, selecting environments (paragraph styles) and occasionally fine tuning individual paragraphs and/or text phrases.

The information typed into the GUI user interface is stored in a single file, usually with a .lyx extension. That file contains LyX language format. This LyX language is very simple, readable and parsable, and yet it captures all the information needed to create almost any publishing/formatting task.

To create the final output, the LyX user interface first converts the LyX language markup to LaTeX, and then the latex2e program converts the LaTeX to DVI (Device Independent) language. From there, other programs can convert the DVI to other formats. For instance, the dvips program converts it to Postscript.

So, to summarize, LyX is both a GUI user interface, and a language produced by that user interface.

## LyX Code vs. LaTeX Code

If you understand LaTeX language, and you look at a .lyx file, you'll see that much of the .lyx file is really LaTeX language. In fact, the main purpose of the LyX specific language is to specify the look and behavior of environments in the LyX GUI user interface, rather than the look and behavior of the final output, which is specified by LaTeX language.

Understanding the differences between LyX language and LaTeX language is THE single most important distinction necessary to use LyX to create documents conforming to your requirements or the requirements of those who commissioned your work. An entire article in this magazine is devoted to the various distinctions between these two languages. You'll learn how to recognize each, and when to use each.

## Summary

One way to understand LyX is by understanding the contrasts surrounding it:
• Fine Tuning vs. Consistency
• Graphical Layout Specification vs. Numeric Layout Specification
• Word Processors vs. Content Authoring Tools
• Using Styles vs. Creating Styles
• Default vs Created Styles
• Character Styles vs. Paragraph Styles
• Default vs Created Styles
• LyX the Language vs. LyX the Front End
• LyX Code vs. LaTeX Code

# LyX Facts and Myths

##### By Steve Litt
LyX is a splendid tool for creating long documents professionally, as well as producing single source, multi use (paper, slides, html, pdf, etc) documents. It's licensed under the GNU GPL license, meaning you have every right to give copies to a hundred or a thousand of your friends or customers, and you have every right to access and modify LyX's source code.

Until recently, the LyX user interface was based exclusively on a library tool called Xforms. Xforms is somewhat quirky, and it's often hard to incorporate into a working Linux system. As a result, it's often easiest to use the LyX version that shipped with your Linux distribution, rather than trying to install a newer version with rpm, apt-get or compiling. Interestingly, LyX is also available for Windows, so you can use it at your Windows-only client sites.

From what I understand, recent versions of LyX can work with the QT GUI environment, but I'm not sure.

## LyX Myths

Some of the LyX myths that pop up often include:
• LyX is a word processor
• LyX is easy
• LyX is impossibly difficult
• You should use LyX for everything
• ### LyX is a word processor

LyX is NOT a word processor, and shouldn't be used as such. It's overkill for a 5 page school paper. It makes fine tuning of pages very difficult, which is not what you want on a flyer or short paper. LyX is not as obvious (i.e. user friendly) as a word processor.

### LyX is easy

When you hear this statement, it's either pro-Lyx or pro-Linux propaganda, or it's spoken by someone who has never needed to modify LyX defaults. Usually it's both propaganda and spoken by a newbie. LyX isn't easy precisely because it is used to do difficult things, like lay out entire books in a consistent manner.

### LyX is impossibly difficult

This statement is either pro-Windows propaganda (the usual line of "reasoning" is that users are too stupid to use challenging programs -- we want something "grandma" can use), or else it's voiced by someone who did a LyX evaluation and found dead ends. LyX isn't impossibly difficult -- thousands use it worldwide, and they're not all geniuses. I'm sure not.

LyX is not difficult, but it can appear that way to new LyX users. Although LyX handles extremely difficult tasks with aplomb, occasionally trivial tasks involve an almost insane level of knowledge, research, work and debugging. Further complicating the matter is the lack of good LyX howto type documentation. There is adequate newbie documentation, and voluminous reference material for the LyX expert, but there's a hole in the middle. That's the purpose of this Linux Productivity Magazine -- to help fill that hole.

The LyX culture is one of expertise. Ask a howto question on the LyX mailing list, and you're likely to get a dozen lines of LaTeX code without context. The heavy hitter inhabitants of the LyX list learned English as a second language -- their first was LaTeX. Many don't remember what it's like not to have a clear understanding of the difference between LyX code and LaTeX code, when you use each, and where.

But if you know what documents to read, and how to read them, and make notes for yourself, and read articles like those contained in this magazine, LyX will be very much within your grasp. And the end product is worth the extra work.

### You should use LyX for everything

Once again, this myth is LyX propaganda. Using LyX to write a simple note is like taking a commercial airplane to go 50 miles. You can do it, but there are easier ways. Use LyX for documents where content is king, and consistency is a must.

# LyX Hello World

##### By Steve Litt
This article will get you started in the world of LyX. Your first step is to run LyX. If LyX is not installed on your system, or if the wrong version is installed, please refer to the Installing or Upgrading LyX article later in this magazine. If LyX is installed properly on your system, you can run it simply by typing
lyx
at a command prompt. LyX will load, and your edit area will be gray and empty because you have not loaded a document. The screen should look something like this:

For the first 8 seconds after loading you'll see a splash screen, and that splash screen will get in the way of your work. If you can't work around it, wait 8 seconds and it will go away.

 NOTE: An astute Linux Productivity Magazine reader pointed out that you can configure LyX not to display the splash screen at all. Given the inconvenience of the splash screen, I think this is an excellent idea. Here's how you do it: Edit->Preferences->Look_&_Feel_tab->Misc_subtab->Show_banner_button: Off

Your next step is to create a new document, which you do by selecting file->new, of course:

And then you'll be brought to an empty document that looks like this:

Type the words "Hello world" in the edit area as follows:

Now save as hello.lyx in your home directory, and then from the menu choose View->Postscript, and your machine's default postscript file viewer will show the page. On my system it looks like this:

You can print that file from the postscript viewer program. But you often get better output having LyX produce a .ps file. To create a .ps file, do the following:

1. From the menu system, File->Export->Postscript
2. Notice that on the status bar, it tells you the name of the file exported -- in this case ~/hello.ps.
3. lpr ~/hello.ps
4. Note that the paper is a clone of what you saw in the postscript viewer.

## Conclusion

When you've completed the exercises in this article, you've run LyX, made the simplest possible LyX document, viewed it as postscript, and output it as a postscript file which you then printed. You have a working LyX installation, and you're able to manipulate it in a minimal way.

The next article will walk you through creating a letter, which is a very simple LyX document created with a template.

# Writing a Letter

##### By Steve Litt
Perhaps the easiest LyX task is to write a letter. LyX has a pre-made letter template enabling you to simply fill in the blanks (really what you do is replace the prompts). Follow these steps:
1. From your home directory, run this command: lyx &
2. Notice that LyX loads with no document
3. File->New_from_Template
4. A list of .lyx files from /usr/share/lyx/templates/ appears
5. Choose letter.lyx
6. A blank letter template appears, as shown below:

Now replace each part surrounded by angle brackets with the info requested. Your return address goes in the upper right, the send to address goes below it on the left side. Your name replaces the <Your signature> prompt. If you click the note in that prompt, it will tell you that yes, that's right, you need to place your signature above the body of the letter. Replace the <Dear...> prompt with your salutation (such as Dear Mr. President: or Dear Jim,). Be sure to include the trailing punctuation (comma informally, or colon in a formal letter). Replace the <Text of Your Letter etc> prompt with what you want to write. Replace <Yours sincerely> with your closing.

If you have carbon copies, replace <cc> with them. Otherwise, delete the <cc>. If you do, when you move the cursor to a different line, the entire line disappears. Similarly, replace <encl> with your list of enclosures, or else delete it.

Save the file, then View->Postscript, and notice how you have a nicely formatted letter.

But wait a minute! The postscript file shows a date, and yet you never input one. LyX has deduced the date as today's date. This is great if you intend to save the postscript file and not the LyX file. But if you save the LyX file, and you print it a month later, the date of printing will show up. That's no good at all.

Salvage the situation with some ERT (Evil Red Text -- TeX mode).

At the start of the top line -- the one containing your name, prepend the following string:

\date{2/14/2002}
That date corresponds to Valentines day 2002. Now highlight the text you just typed, and click the TeX button (). The text just turned red. You've created a LaTeX date command that will determine the date printed in the letter. View the letter with View->Postscript again, and notice that the letter's date is now Valentines day 2002. If it is not, refresh your postscript viewer.

 NOTE I've read that some 1.2.x versions don't allow highlighting and marking, and instead you must click the TeX button and copy text into the resulting field.

The prompts you replaced are really environments, which, as mentioned previously, are LyXese for paragraph styles.

It's instructive to click the down arrow on the environment selector (the leftmost thing on the buttonbar), and view the list of environments for this document. It looks something like this:

 REMINDER: In the LyX world, "Environment" means "Paragraph Style".

Look at the environments, and notice how some, such as My Address, Send To Address, Opening, Signature, Closing, cc, and encl correspond to parts of the letter. Notice that environments Location and Telephone are things that are likely to go in a letter, although this template doesn't prompt for them. Environments Standard, Itemize, Enumerate, Description, List, LyX-Code, and Comment are general environments useful in most document types:

 Standard Normal paragraph body text Itemize A bulleted list Enumerate A numbered list Description A word/definition list List LyX-Code Show multiple lines of source code in this environment Comment

If you've gone straight through this magazine, you've performed two exercises -- the "Hello World" and the letter. There are plenty more exercises, but before you do them you should know about installing and upgrading LyX, and LyX documentation resources. Read on...

##### By Steve Litt
Thankfully, most Linux distributions come with a working LyX. If LyX isn't installed on your system, you probably can install it by installing the xforms rpm off your install CD's, and installing the LyX rpm off your install CD. However, if those rpm's don't exist, or if you want to install a later version, things get more complicated.

I won't discuss Debian, because I don't have it. From what I understand, Debian's handling of dependencies is so good that upgrading isn't a challenge. It's much more challenging in Mandrake. My Mandrake 8.2 installation shipped with LyX version 1.1.6fix4. I downloaded  version 1.2.1 via the file lyx-1.2.1-1.i386.rpm. An installation attempt:

rpm -Uvh lyx-1.2.1-1.i386
griped about needing xforms and needing libstdc++-libc6.1-2.so.3. I started with xforms. Installing a much newer version (0.99) didn't work, so I went to ftp://ftp.lyx.org/pub/lyx/contrib/ and downloaded xforms 0.88. I think version 0.89 would have worked too, but I had read on the LyX mailing list that LyX is more stable with xforms 0.88. So I did an rpm -Uvh on the rpm, and it said I had a newer version, so it was necessary to uninstall version 0.99 with an rpm -e xforms command. Of course that required me to issue an rpm -e lyx command to get rid of 1.1.6fix4. Then I was able to install xforms 0.88.

From there I tried another LyX 1.2.1 installation, and it once again griped about the lack of libstdc++-libc6.1-2.so.3.

A quick file search with a packaging manager located several similar (but not identical) files in the /usr/lib directory.  A directory listing revealed the following:

[root@litttest lyxinst]# ls -l /usr/lib/libstdc++*
-rw-r--r--    1 root     root       452342 Feb 21  2002 /usr/lib/libstdc++-3-libc6.2-2-2.10.0.a
-r-xr-xr-x    1 root     root       299756 Feb 21  2002 /usr/lib/libstdc++-3-libc6.2-2-2.10.0.so*
lrwxrwxrwx    1 root     root           24 May 14 10:49 /usr/lib/libstdc++-libc6.1-1.so.2 -> libstdc++-libc6.2-2.so.3*
lrwxrwxrwx    1 root     root           30 May 14 10:57 /usr/lib/libstdc++-libc6.2-2.a.3 -> libstdc++-3-libc6.2-2-2.10.0.a
lrwxrwxrwx    1 root     root           31 May 14 10:49 /usr/lib/libstdc++-libc6.2-2.so.3 -> libstdc++-3-libc6.2-2-2.10.0.so*
[root@litttest lyxinst]#
As you can see, many of these are links. Not knowing what the heck I was doing :-), I made the following link:
ln -s /usr/lib/libstdc++-libc6.2-2.so.3 /usr/lib/libstdc++-libc6.1-2.so.3
The preceding command just assigned the correct name to the existing version 6.2.2 file. Smart idea, but it didn't work -- still griped about the lack of libstdc++-libc6.1-2.so.3. So I finally just strongarmed it with a --nodeps option:
rpm -Uvh --nodeps lyx-1.2.1-1.i386.rpm
That did it. It installed.

## Lessons Learned

Procedures will vary from distro to distro, LyX version to LyX version, so the preceding procedure means nothing to you unless you're trying to install LyX 1.2.1 on a Mandrake 8.2 box. What you should take from my experience instead is the process.

I read the LyX mailing list, gleaning information from various list members' installation adventures. I read all the info on the LyX download page, noting that because LyX uses an outdated xforms, they make the outdated xforms available in the contrib section of their ftp site. Their contrib section also contains other components that may or may not be necessary for your particular installation.

Beyond that, you slowly, deliberately and intelligently use trial and error. Try binary packages. Try rebuilding RPM packages with commands like the following:

rpm --rebuild lyx-1.2.1-1.src.rpm
You might find it easier to recompile. Remember to find the right versions of dependencies. Look in the LyX website's contrib directory, and look at the documentation on the website's download page.

One more thing. Perusing the mailing lists, I've noticed that often early adopters of LyX versions found either instability or minor missing features. I installed 1.2.1 on my experimental machine. My daily driver will stay with 1.1.6fix4 until I've verified that 1.2.1 works well and can work with my "Troubleshooting Techniques of the Successful Technologist" book.

# LyX Documentation Resources

##### By Steve Litt
Microsoft made a name for themselves with menu driven software that could be used without a manual. They traded flexibility for obviousness, which works just fine for easy to moderate tasks. But LyX is made for heavy tasks, like writing a book, and gives you unimaginable flexibility. LyX is no MS Word -- you must read the documentation. LyX usage is a commitment, not a dabble.

With LyX, if you want to have control over the look of your documents, you must be accomplished at LyX. That means you must quickly pass through the Newbie and Apprentice stages. Quickly passing through those stages is the entire purpose of this Linux Productivity Magazine issue.

This article lists and describes the documentation resources you'll need in order to use LyX to write books, articles, papers and slideshows in environments where the LyX defaults are not good enough.

The following is a list of the major LyX documentation resources:

The following is a list of resources categorized by LaTeX vs. LyX, and Newbie vs. Apprentice vs. Accomplished.

 LyX LaTeX Newbie The LyX mailing list Intro.lyx (Help->Introduction) Tutorial.lyx (Help->Tutorial) FAQ.lyx (Help->FAQ) None! Apprentice The LyX mailing list Reference.lyx (Help->Customizations) LyX Quickstart (http://www.troubleshooters.com/lpm/200210/200210.htm) Writing Self-Published Books with Lyx (http://www.troubleshooters.com/linux/lyx/index.htm) KatSpace Using LyX For DTP (http://katspace.net/lyx/lyxhow.shtml) Extended.lyx (Help->Extended Features) BUGS.lyx(Help->Known Bugs) LyX Quickstart (http://www.troubleshooters.com/lpm/200210/200210.htm) Writing Self-Published Books with LyX (http://www.troubleshooters.com/linux/lyx/index.htm) KatSpace Using LyX For DTP (http://katspace.net/lyx/lyxhow.shtml) /usr/share/texmf/doc/latex/general/essential.dvi The LyX mailing list Accomplished The LyX mailing list Extended.lyx (Help->Extended Features) /usr/share/texmf/doc/latex/general/latex2e.dvi /usr/share/texmf/doc/latex/general/guide.dvi /usr/share/texmf/doc/latex/general/lshort.dvi /usr/share/texmf/doc/latex/fancyhdr/fancyhdr.dvi /usr/share/texmf/doc/latex/ subdirectories The LyX mailing list LyX Tricks and Tips  (http://www.lyx.org/help/index.php3)

Whether you're committed to LyX, or just evaluating, you must spend some time learning. I'd recommend 1 or 2 work days. This isn't MS Word -- it's a publishing tool that can turn out professional work ready for the printer. The time you spend with introductory documentation and tutorials will more than pay for itself by eliminating dead ends, which saves time if you're committed, and helps you make the right decision if you're evaluating.

First, take 10 minutes to read the Introduction (Help->Introduction at the LyX menu). That will give you a high level view -- almost an executive summary.

Next, take the 2 hours necessary to complete the LyX tutorial (Help->Tutorial at the LyX menu). Of course you'll be tempted to quit the tutorial and try those features you "really need". Don't do that. Those needed features are almost certainly doable with LyX, but if you skip the tutorial you almost certainly won't see how to accomplish them, and won't even be in a position to implement them if guided by someone on the LyX mailing list.

If you haven't yet, now sign up for the LyX mailing list. At least scan every email, and make a note of what info is available. You'll probably be using that info soon enough.

Now start dabbling with LyX, while at the same time going through this document (the LyX Quickstart, http://www.troubleshooters.com/lpm/200210/200210.htm). Go through all the articles and exercises. Soon you'll be confused with the LaTeX code (or even worse, similarities and differences between LaTeX and LyX code). When you start having LaTeX questions, prepare for some serious reading.

There' s no use reading LaTeX documentation until you've seen LaTeX in action and understand where it fits in the big picture. After performing some of the exercises in this magazine, it's time for some heavy reading. If you have a printer, I'd suggest you print the following four files:

1. /usr/share/texmf/doc/latex/general/essential.dvi
2. /usr/share/texmf/doc/latex/general/latex2e.dvi
3. /usr/share/texmf/doc/latex/general/lshort.dvi
4. /usr/share/texmf/doc/latex/fancyhdr/fancyhdr.dvi
Print dvi files with the following command:
dvips myfile.dvi
or
dvips -P printername myfile.dvi
You might wonder why you should print these files instead of looking at them on the computer. The answer is these are substantial documents, and it's easier to read them, and mark them up, on paper. Later, you'll want to view these files online for reference purposes. Here are two commands with which to view a .dvi file:
xdvi myfile.dvi
or
dvips -o ~/junk.ps latex2e.dvi; gv ~/junk.ps
The former command is easy, but you might not like the xdvi user interface. If not, the latter command converts the .dvi to postscript and then views it in the gv viewer. For easier printing and viewing, you might want to convert all the files in directory /usr/share/texmf/doc/latex/general/ to postscript with dvips -o. You'll need to do it as root because no other user has write rights to this directory.

First read essential.dvi, then latex2e.dvi. Go back to your experimentation and your work with the LyX Quickstart (this file, http://www.troubleshooters.com/lpm/200210/200210.htm). Refer back to  essential.dvi, then latex2e.dvi as necessary. Ask questions on the LyX mailing list as necessary. If referred to the LyX Tricks and Tips site (http://www.lyx.org/help/index.php3), then go there, and while there, look around. It's a huge resource.

Once you've done some serious LyX, LaTeX, and LyX/LaTeX integration, read lshort.dvi and fancyhdr.dvi, and really think about what you're reading. As you read, you'll have many "eureka" breakthroughs, and you'll start to understand the finer points.

Now go out and practice some more. You're fast becoming an accomplished LyX user, and maybe even an expert.

# Making a Book

##### By Steve Litt
In this exercise you'll learn to choose a document class. You'll learn about the relationship between your document class and the available environments (remember, that's LyXese for paragraph styles). You'll make a tiny book and view it in Postscript. You'll manipulate the margins, and the interparagraph spacing. You'll go beyond the defaults by indenting paragraphs AND giving them a large skip. You'll change the book's default font size and typeface. You'll customize the headers and footers. You'll use a little ERT to customize the title page. And you'll structure your document into Parts, Chapters, Sections, and Subsections.

Run LyX, and from the menu choose File->New to get a blank document. LyX can create different types of documents, including books, articles, reports, letters, resumes and many other document types. The default for a new document is an article, or more specifically, the Article document class. A document class is similar to a template in MS Word in that it determines the available styles, and what they'll look like.

So the document on your screen is from the Article document class, and you want to make a book. Do the following:

1. Layout->Document to access the Document Layout screen with the Document tab active.
2. Notice that the radio buttons, labeled "Sides", on the right side of the Document Layout screen, have "One", rather than "Two" checked. Remember this.
3. Click the arrow next to the Class input box to access a list of document classes
4. Pick book from the list, and notice that a confirmation window appears, but it's buried under the list.
5. Drag the confirmation window from beneath the list and note that it looks like the following:
6. Click the Yes button
What you've just done is chosen the book document class, so you now have additional Environments such as Part, Chapter, and several others. When you said "yes" to the question "Should I set some parameters to the defaults of this document class?", what you did is allow LyX to change several defaults to conform with a typical book. Look at the radio buttons called "Sides" on the right side of the Document Layout screen now have "Two" checked. This is one of the defaults changed by using the book document class.

Finally, click the OK button on the Document Layout screen so that you return to LyX itself, and save your document. Now it's time to write your book.

## Writing the Book

Copy the text from booktext.htm to the edit area of LyX. Then search for every paragraph beginning with an environment name followed by a colon, and for each such paragraph, select the named environment from the environment list (leftmost component on the buttonbar) to change the environment. The finished document explains the process more completely. Read its pdf file. You might also like to see the raw LyX file.

Save the file frequently. When you're done, from the menu choose View->Postscript, and note that you have a 13 page book with one part and four chapters. Note that every chapter starts on an odd number page. This is configurable.

Notice also that odd number pages print more to the left than the even number pages. This is exactly opposite of what you want, because in a bound book, you need extra room, for the book's binding, on the left side of odd pages and the right side of even pages. We'll fix that right now!

## Setting the Margins

Layout->Document, click the Document tab and make sure that the right side radio buttons are set for a 2 sided document. The fact that it's 2 sided is what enables odd and even pages to have different margins.

Next click the Paper tab. It should look like the following:

No margins are set. The document printed with default margins. We're going to change that. The first thing you want to do is click the "Use Geometry Package" radio button right below the Papersize list button. Margins can be set ONLY if you use the Geometry package. Fill in the following margins:

• Top: 1.5in
• Bottom: 1.5in
• Left: 4in
• Right: 1.5in
Notice that in each field, we appended a unit (in, which stands for "inches"). Valid units include in, cm, ex, pt (points). These margins are shorter from top to bottom, narrower from side to side, and hugely skewed away from the book's binding. From the menu, choose View->Postscript and notice the huge binding margin, and the fact that the document has expanded to 14 pages.

 WARNING! 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.

Looking at the Paper tab, you see that you can modify the header and footer margins or the paper size. The paper size can either be chosen from the papersize list at the upper left, or by putting in custom measurements in the width and height fields in the "Custom Papersize" section.

Now let's make the dimensions more realistic:

• Top: 1in
• Bottom: 1in
• Left: 3in
• Right: 1.5in
• Click OK, then File-Save, View->Postscript, and notice that the document has gotten shorter (should now be 13 pages), and it looks more normal.

 NOTE: When viewing postscript with View->Postscript, you might see the same document as last time. If so, your postscript viewer should have a "Redisplay" button or some other means of refreshing. Refresh it. Note also that View->Postscript opens a new postscript viewer each time. If you want to see your changes in the same postscript viewer, use View->Update->Postscript, and your changes will be in the same viewer as previously. However, you'll almost certainly need to refresh the viewer.  On some installations View->Update->Postscript fails. If so, use View->Postscript and close old postscript viewers.

That's it. You've just set the margins. Make a note of how many pages your postscript view takes, and where the text ends on the last page, because you're about to change the font and notice the changes.

## Changing the Font

You're going to change two aspects of the document's font -- the typeface and the size. Start by noticing the size and "look" of your current font, and also how long the document is to the nearest 1/4 page. Now you'll change it.

Layout->Document, click the Document tab, then click the Fonts list area, and choose "newcent". This is the New Century Schoolbook font, one of the most readable.

NowFile->Save and then View->Postscript (refresh if necessary). The print should appear darker and clearer, and probably the document will have become longer. The "newcent" typeface is an ideal one for books.

Now you'll experiment with font size. Click the Font Size list area, and choose 12, which means 12 point. NowFile->Save and then View->Postscript (refresh if necessary). Notice that the print has become larger, and the document has become longer.

## Changing the Paragraph Spacing and Indentation

If you look at the first page of chapter 1, you'll see that the first line of each paragraph is indented, and there is no extra space between paragraphs. We're going to change that to make a large space between paragraphs and make the indentation even larger.

Layout->Document->Document tab. At the right toward the bottom you'll see two mutually exclusive radio buttons called "Indent" and "Skip", with the "Indent" button enabled. Click the "Skip" button, then click OK. File->Save then View->Postscript and observe that now there's a space between paragraphs, but the paragraphs are no longer indented. This happened because the Document Layout screen incorporates skip and indentation as mutually exclusive, although nothing in LaTeX makes them mutually exclusive. Later we'll enable indent.

But first, let's increase the space between paragraphs. Look at the postscript viewer and  observe the space between paragraphs on the first page of the first chapter. Now Layout->Document->Document tab->Default Skip, and pick Bigskip. Click OK, File->Save, and then View->Postscript. You'll see that the space between paragraphs has gotten bigger.

As mentioned, Skip and Indent are mutually exclusive on the Document Layout screen, but nothing in LaTeX makes them mutually exclusive. So we'll set the skip with a LaTeX command in the global part of the document. In LaTeX (and LyX), the global part of the document is called the "Document Preamble", so that's where we'll put the LaTeX command.

Layout->LaTeX Preamble, then type in the following LaTeX command:

\setlength{\parindent}{1in}
The preceding sets the length of document variable \parindent to one inch. Now click the OK button, and File->Save, then View->Postscript, and notice that your paragraphs are not only spaced widely, but also indented.

You might wonder how I knew the command \setlength{\parindent}{1in}. I read about it in the lshort.dvi document. This is why I say you should read the documents. This solution would have been difficult to find without reading the documentation. There's no "point and click" way to find it.

## Other Document Layout Tabs

Before moving on to other things, let's examine the last three tabs on the Document Layout screen. Layout->Document->Language tab, and note that you can define the language (mostly for spellcheck reasons), the encoding, and the quote style.

### The Extra Tab

Click the Extra tab and you can define the float placement. This is a string of letters that determine the the order in which you try to place a float (floats contain images, tables or other entities).

The Section number depth sets how deep section numbers go. For instance, the default is 2 for books, which means environments Section and Subsection are numbered, but starting with Subsubsection, they are not. Setting it to 1 would mean Section is numbered by Subsection is not. Setting it to 0 means Section is not numbered, but Chapter is. Setting it to -1 means Chapter is not numbered.

Table of contents depth determines how deep the table of contents goes. The book default setting of 2 lists all parts, chapters, sections and subsections. This is a good level of detail, but it can go very long. Technical books typically go this deep, but classic books go just to the chapter level in the table of contents, which would be a contents depth of 0. Some technical books have two tables of contents: One going very deep and the other shallow for quick chapter lookup. While this is probably possible in LyX, it is very inobvious, and beyond the scope of this document. This is the type of question you'd ask on the LyX mailing list.

The PS driver list lets you choose from programs to render postscript. If it works, don't change it. The "Use AMS Math" radio button determines whether or not to use AMS Math in your math content. I'm not a math content expert, so this is beyond the scope of this article.

### The Bullets Tab

You use the Bullets tab to define which bullet types you want to show at which levels for which purposes.

## Making 2 Column Output

Humans read best when lines are less than 70 characters. At a 10 point font and 8.5x11 paper, you'd need to set the margins very narrow -- to maybe half the paper width, to do that. The classic way to make optimal length lines without wasting paper is to use two columns.

Layout->Document->Document tab, and click the "Two" radio button in the Page Cols area in the middle right of the Document Layout screen, and then click OK. File->Save then View->Postscript, and observe you now have two very skinny columns.

To optimize your document for two columns, you need to shrink the font and widen the margins.

1. Layout->Document->Document tab->Font Size 10.
2. Layout->Paper, and then set your left margin to 1.5in and your right margin to 0.8in.
3. Click OK to leave the Document Layout screen, then File->Save.
4. Layout->LaTeX Preamble, then change the 1in argument to 0.25in.
5. Click OK, then File->Save
If you're like me, you'd like to see those columns a little farther apart. Once again, this calls for LaTeX in the document preamble.

Layout->Document Preamble

Insert the following line:

\setlength{\columnsep}{1in}
Click OK, File->Save, View->Postscript, and note that the columns are 1 inch apart. Naturally, you'd want to reduce that number to maybe .3in, but the 1 inch makes it obvious that it worked.

You might wonder how I found the right latex command. I'd like to tell you that I found it in the documentation this magazine has mentioned, but it's not (a grep command proves that). Speaking of grep, I'd like to tell you that I found it with a grep command, but although a grep for the word column led to "\twocolumn", further research led nowhere.

I guessed. Figuring there was a length variable that controlled column separation, and knowing that many such lengths ended in the word "sep", I tried the command and sure enough, it worked. Keep in mind this wasn't the first thing I tried. It followed 1/2 hour of trial and error.

You would probably choose to ask this question on the LyX mailing list, and you'd probably get the correct answer within a couple hours to a couple days.

## Summary

In a matter of minutes, you've created a new book, formatted it with the correct environments, set the margins, changed the fontface and the font size, changed paragraph spacing to skip instead of indent, and then restored the indent with a LaTeX command in the document preamble. You reviewed some of the other options on the Document Layout screen. You made your document a two column document, and then widened the separation between the column with a LaTeX command in the document preamble.

Hopefully you've observed that LyX can do almost anything, if you know how to do it. And you've observed that some of the simplest things, such as widening the column separation, can be obscure given the current state of documentation. You've learned that a combination of knowing how to find the right documentation, experimentation, and asking on the LyX mailing list, usually yields the feature you want to incorporate.

##### By Steve Litt

Open your LyX document in LyX. View->Postscript and view the documents structure -- its chapters, sections, subsections, etc. Notice that there is no table of contents.

Now View->Postscript, go to page 3, and you should see the table of contents. But you might not. I've observed what appears to be an intermittent anomoly in LyX 1.1.6Fix4 in which only the word "Contents" appears on page 3. I believe this is caused by the fact that you need two compiles -- one to create an intermediate file and one to incorporate that intermediate file into the contents. If this happens to you, simply make a small change (add or delete a space at the end of a line) and once again View->Postscript. You should now see the table of contents.

Because the procedure described in the preceding paragraph is a hassle and can also lead to an inaccurate TOC if not checked carefully, the following is a script that produces an accurate TOC every time:

 #!/bin/bash rm -f $1.aux rm -f$1.dvi rm -f $1.log rm -f$1.ps rm -f $1.tex rm -f$1.toc lyx --export latex $1.lyx latex$1.tex latex $1.tex dvips -o$1.ps $1.dvi gv$1.ps

The preceding script can be run from the command prompt, at any time after saving the .lyx file, to produce an accurate postscript document with an acccurate table of contents.

A book with no graphics is pitiful indeed. Graphics are necessary for a good book.

At least as late as LyX 1.1.6Fix4, it was bothersome to use graphics other than .eps or .ps with LyX documents. Yes, it could be done, I did it, but it was ugly. I've heard later versions are better with non-postscript graphics, but this exercise uses a .eps graphic. Right click THIS LINK to download a grayscale encapsulated postscript screenshot of the Gimp main window, and save it in your home directory. If you want to see the image, left click the link.

Now insert the graphic before the first paragraph of section 4.2. Cursor to the start of first paragraph in section 4.2, and Insert->Figure, and make sure "Encapsulated Postscript" is checked (not Inline EPS), and then click the OK button. LyX will present the Figure dialog box. Leave everything in the dialog box at its default. Click the Browse button, and browse to the graphic you just downloaded. Now click the OK button, and watch the figure appear in your LyX document.

 NOTE: The figure might not appear in your document. You might get just a box, possibly containing some text saying the figure can't be rendered. This is an intermittent anomoly in some versions of LyX, and it's not important, because the output renders beautifully. Even if it does render in LyX, the image will be grainy. Once again, that's OK, because the final output will be a work of art.

Now File->Save and View->Postscript, and observe that the monochrome Gimp screenshot appears between the first and second paragraphs of chapter 1. This is the simplest way to insert a graphic, and with tiny graphics, especially tiny graphics that must remain fixed in the text, this is often the best way.

Unfortunately, if you insert a graphic this way (without benefit of a float), the graphic cannot have a caption.

If you want to delete the graphic you just inserted, cursor to one side of it, press the shift key, then use the cursor key to move across the graphic. Now the graphic is highlighted. Now just delete it.

### Adding a Graphic Inside a Float

The trouble with the figure insertion method in the preceding section is that as graphics get bigger, placing them at an exact point in the text might create large holes at the beginning or end of a page. It's often more pleasing to place the graphic at the top or bottom of the page, or even on an adjacent page. You can do this using floats.

When you use floats, the exact location of the graphic relative to the paragraph explaining it is unknown. That means that text like "the preceding figure" or "the following figure" is meaningless. You need a figure number. Floats enable you to assign figure numbers.

 WARNING! According to some documentation, when crossreferencing a label of any kind, you need to run latex2e before you can reference the label. My experience has been that as long as I save the document, the new label is available on cross reference lists. But if a label does not appear on the reference list, try View->Postscript after saving the document. That will probably cure the problem.

Perform the following steps to implement a figure inside a float between the first and second paragraphs of chapter 1:

1. Cursor to the start of the second paragraph of Chapter 1.
2. Insert->Floats->Figure Float Notice a figure float opens up, complete with caption.
3. Insert->Label, and then type Gimp Screenshot and click OK. Notice that a button with the words "Gimp Screenshot" appears.
4. To the immediate right of the new button, type "A screenshot of Gimp". This will be the caption.
5. Cursor left so the cursor is before the button.
6. Press the Enter key once to open a new line above the caption.
7. Insert->Figure->Encapsulated Postscript to open the Figure dialog box.
9. Click the OK button actuate your choice and dismiss the Figure dialog box.
10. Notice that the screenshot appears above the caption.
11. File->Save
12. View->Postscript and verify that the figure appears over a caption labeling it as "Figure 1.1: A screenshot of Gimp".
Notice that the graphic does not appear between paragraphs 1 and 2, but instead appears after paragraph 4, on the next page. So the question then becomes, how does one refer to it in the text? Certainly the words "following"  and "preceding" are misleading when the graphic's location is decided by LyX, not by you. The answer is you use a cross reference. Here's how:
1. Cursor to the end of the first paragraph in Chapter 1.
2. Press Enter, type the word "Figure" and then a space.
3. Insert->Cross reference
4. Pick "Gimp Screenshot" from the reference list. If you've followed the directions exactly, it will be the only one.
5. In the "Reference type" list, pick TextRef
6. Click OK to record your choice and dismiss the Reference dialog box. Notice there's now a button labeled "TextRef: Gimp Screenshot".
7. Type a space and the phrase "shows a screenshot of Gimp." to the right of the the button.
8. File->Save, View->Postscript.
Notice that in the Postscript file the sentence now reads "Figure 1.1 on the following page shows a screenshot of Gimp.". LyX figured out that the graphic was on the next page.

Now, in LyX, copy that sentence to the beginning of Chapter 2 and also to the very end of the document. File->Save, View->Postscript, and observe the phrasing of the three  sentences. Depending on the spacing of the document, the Chapter 2 sentence will refer to the graphic as "on the facing page" or "on the previous page", or something similar. The sentence at the end of the document will simply refer to it by page number.

It's magic!

## Changing the Float's Heuristic

Perhaps you didn't want the graphic on its own page following the page of its insertion. Perhaps you want it at the top of the page of insertion, or at the bottom of the page of insertion, or exactly where you inserted it. You can ask LyX to try to accommodate you. Typically, LyX won't accommodate you if it looks terrible.

You specify the heuristic by specifying a sequence of up to four of the following letters: h, t, b, p. The sequence is optionally preceded by an exclamation point, which means "try very hard to put it at my first choice". The default heuristic is "tbp", which means try to put it at the page's top, then try to put it at the page's bottom, and if neither works, put it on a page of its own. Using "p" would put every graphic on its own page. If you use h (here), it might as well be in front, because h always takes precedence. To try very hard to put it inline with the text, use "!hb", which says "try very hard to put it inline with the text, and if not, try to put it at the bottom of the next page.

Let's try to make the graphic show up inline. Do the following:

1. Layout->Document->Extra tab
2. Type !hb in the Float Placement input area
3. Click OK to record your change and dismiss the Document Layout screen.
4. File->Save, View->Postscript
You'll notice that it makes no difference -- the graphic still goes on the next page. But now try a smaller graphic. Download smallgraphic.eps, click the Gimp screenshot, and switch the filename to smallgraphic.eps. Now you get a small graphic that's easier for LyX to place. Now change the Float Placement to tb, and it goes to the bottom. LyX couldn't place it at the top. But I found that if I changed it to !tb so it would try really hard to place it at the top, the graphic would go to the top.

Note that this Heuristic is global and can't easily be changed throughout the document. Note also that this setting controls both figure floats and table floats, which may not be what you want.

I sure wish they'd have an H letter, which would mean "put it here no matter how awful it looks".

Cross references allow one part of the text to reference another part of the text by page number or by heading number. Typically you hard code the name of the section, or the subject of the section, and then cross reference to get the page and/or the section number. That way, when somebody moves the text, the page numbering and section numbering are updated and stay accurate in the reference.

Adding a cross reference is very similar to the figure float references previously discussed. Try this exercise:

1. At the front of section 2.2 (Pasting Text), Insert->Label.
2. On the label input form, type "Pasting Text".
3. File->Save
4. Go to the end of the first paragraph of chapter 4, and press Enter to create a new paragraph.
5. Type "As we discussed in section ".
6. Insert->Cross reference
7. On the reference screen, choose "Pasting Text", and choose "Ref" from the Reference type list
8. Click OK to assert your choice and dismiss the Reference screen.
9. Type ": Pasting Text, "
10. Insert->Cross reference
11. On the reference screen, choose "Pasting Text", and choose "TextRef" from the Reference type list
12. Click OK to assert your choice and dismiss the Reference screen.
13. Type ", text can be pasted."
14. File->Save, View->Postscript.
You'll see that the finished document says "As we discussed in section 2.2: Pasting Text, on page 9, text can be pasted". If your pagination is different from mine, the page number will be different, but it will be accurate in your document.

## Inserting and Modifying a Table

Tables are tricky in LyX (at least up to and including 1.1.6Fix4). But once you know the tricks of the trade, they're easy.

Start by inserting a table before the first paragraph of Chapter 1:

1. Cursor to the beginning of the first paragraph of Chapter 1
2. Insert->Tabular brings you to the Insert Tabular dialog box
3. Set the slides to 8 rows and 3 columns.
4. Click OK. You'll see an empty table appear at the start of the first paragraph.
5. Fill in the first two rows as follows. Copy and paste the long line so it goes in as one line:
6.  Software OS's Details LyX Linux, UNIX, BSD, Windows Styles based, complete layout and typesetting. All features except character styles are fully supported, though the support mechanisms might not be obvious.
7. File->Save, View->Postscript, and note that the table walked right off the edge of the page. That's no good!
LyX tables won't wordwrap unless you set the column widths. So we'll set the column widths at 0.8in, 1.2in, and 3in for a total width of 5 inches. Do the following:
1. Cursor to the top cell of the leftmost table column
2. Right click, click the column/row tab, and click inside the Width field
3. Type 0.8in
4. USER INTERFACE RARITY!!! Notice there is no OK button. You MUST press the Enter key to record your choice. If you click the Close button before pressing the Enter key, your change will not be saved!
5. Notice that when you press the Enter key, the leftmost column wordwraps.
6. Without closing the Tabular Layout dialog box, switch focus back to LyX, and click in the top cell of the middle column
7. Switch focus back to the Tabular Layout dialog box, enter 1.2in in the Width field, press the Enter key, and notice that the middle column wordwraps.
8. Without closing the Tabular Layout dialog box, switch focus back to LyX, and click in the top cell of the rightmost column
9. Switch focus back to the Tabular Layout dialog box, enter 3in in the Width field, press the Enter key, and notice that the right column wordwraps.
10. Click the Close button.
11. File->Save, View->Postscript
Notice how beautifully the table now renders. The one remaining glitch is that the table is on the same line as the first paragraph of text. To fix that cursor to the beginning of the first word of the first paragraph, and press the Enter key. Now the first paragraph renders completely below the table.

Go ahead and experiment by right clicking inside the table, and peruse all the tabs of the Tabular Layout dialog box. You can set borders, append and delete rows and columns, rotate the table 90 degrees or make it a special "Longtable", and make cells multi-column.

Tables can be inserted inside Floats in the same way that graphics can. Table floats have captions, and can be the basis of crossreferences, and just like figure floats, their location in the rendered document is determined by LyX, with the author setting the heuristics in the same way as with a figure float.

## Summary

In this article you inserted a graphic bare into the text, at which time it was anchored to the text. Then you placed the graphic inside a figure float, at which time the figure received a caption and a label which could be crossreferenced. You learned how to adjust the heuristic that controls the placement of the float. You learned how to use crossreferences, and how to insert and modify a table.

At this point you're capable of writing a substantial LyX document, as long as you're satisfied with the look and capabilities of the document class you use.

# Simulating Character Styles With Color Pseudostyles

##### By Steve Litt
By far the most glaring omission in LyX is the lack of character styles. Character styles are named styles that work on text within a paragraph, instead of on a whole paragraph. For instance, you might have a special appearance for names of baseball players, and a different special appearance for the names of computer gurus, and no special appearance for other names. So in Wordperfect or MS Word, you'd create a new style, declare it to be a character style, and place the proper format codes within it. Then, every time you write a baseball player's name, you'd choose the baseball style, and the baseball player's name would be correctly formatted in the final output. Once you've used this style, if you decided you wanted to change the appearance of ALL baseball player's names, you would simply revise the character style itself. WordPerfect has had this feature since 1988. It's still missing in LyX.

This would be a showstopper if there weren't a workaround. This article shows you the workaround, which is based on mapping colors to appearances. If you use color based pseudostyles, when the LyX developers include this badly needed feature, you can write scripts to convert colors to corresponding genuine character styles, and thus maintain the structural integrity of your book.

Remember 1981's war cry, "I want my MTV"? If you like LyX and want to use it into the future, I'd suggest you get on the LyX list and yell "I want my character styles". But in the meantime, here's the color pseudostyle workaround.

Layout->LaTeX Preamble, and insert the following code:

 % %%% Pseudo character styles indexed by color %%% \usepackage{ifthen} \providecommand{\textcolor}[2]{#2} \renewcommand{\textcolor}[2]{% \ifthenelse{\equal{#1}{blue}}{{\textsl{\textsf{#2}}}}{}%      Baseball name \ifthenelse{\equal{#1}{magenta}}{{\large{\texttt{#2}}}}{}%    Computer guru name \ifthenelse{\equal{#1}{magenta}\or\equal{#1}{blue}}{}{#2}%    fallthrough }

The preceding formats any blue text as slanted sans serif, and any magenta text as large teletype.

Now place the following paragraph at the very end of the document. Be sure to include the magenta and blue text:

 Barry Bonds and Sammy Sosa are carrying on the slugging tradition of Babe Ruth, Roger Maris and Mark McGwire. But who is carrying on the tradition of Linus Torvalds, Richard Stallman and Larry Wall? Keep coding, and one day you might carry the eternal flame of free software.

Remember, you change text color by highlighting the text to change, and then Layout->Character.

File->Save, View-Postscript, and notice that the baseball players are slanted sans serif, while the computer gurus are large teletype.

Obviously color pseudostyles aren't what one has in mind when one imagines character styles, but they allow us to use LyX until real character styles become part of LyX. In the words of the Rolling Stones, "You can't always get what you want, but if you try real hard, you just might find that ... you get what you need!".

##### By Steve Litt
If you've gotten this far, you can use LyX to accomplish pretty much whatever your chosen document class offers you. Sometimes that's enough. But if you're self-publishing, or if you're writing an academic paper that is required to be formatted "just so", or for whatever reason your format is constrained by others, you'll need to change and/or add to what your document class gives you. Basically, you'll need to build a new document class based on the closest existing document class. Unfortunately, documentation to accomplish this feat is rare, and most such documentation is inadequate. That's one reason LyX has a reputation for difficulty.

This article describes how to build your own document class with minimal pain. The hope is also to give you enough theory along the way that it doesn't seem like arcane magic.

This article is for those wanting to improve on an existing document class -- not build one for scratch. It's also not intended for those who build a document class for distribution -- such a class would be delivered as a style file, not a layout file. This article is for a real life LyX user.

## The Role of Layout Files

A layout file is one way to create a new document class. When you Edit->Reconfigure, LyX scans certain directories for files ending in .layout, and if it finds them, it incorporates the document classes of the .layout files into the list of available document classes. The directories searched for .layout files are typically /usr/share/lyx/layouts, the system-wide layout repository, and $HOME/.lyx/layouts, the user's repository for his own layouts. This article assembles the new .layout file in$HOME/.lyx/layouts.

You will now create a layout file which specifies a hellobook document class that inherits all properties and behavior from the book class, and in fact performs identically to the book class. Create the following $HOME/.lyx/layouts/hello.layout file:  #% Do not delete the line below; configure depends on this # \DeclareLaTeXClass[book]{hellobook} Input stdclass.inc Line 1 is a pound sign followed by a comment. Remember, in LaTeX, anything after a percent sign is a comment, including leading whitespace on the next line. Line 2 creates a new document class, called hellobook, that is based on existing document class book. Line 3 imports all the standard properties and behaviors needed by LyX. Save the file. Now start LyX, File->New, Layout->Document->Document tab->Class list. Scroll down the class list, and note that even though you already saved your new .layout file, document class helloclass does not show up in the list. That's as it should be. Now Edit->Reconfigure. LyX tells you to quit LyX and start it again. Do so. LyX, File->New, Layout->Document->Document tab->Class list. Scroll down the class list, and you should see hellobook. Choose it, and when you're asked whether to set defaults, say yes. Click the Environment list box, and you'll see all the same environments as in the book class. You've created a duplicate of the book class, and will do all your experimentation in that duplicate. Read on... ## A Layout Debugging Script Unfortunately, LyX loads layout files when it starts up, and never again checks to see whether the layout file has changed. That means that in order to test a change to the layout file, you must exit LyX, start it again, and View->Postscript. What a hassle! So instead, make yourself a script that loops through closing LyX, opening a new one, creating and viewing a postscript file. In this case, our script never even starts the LyX user interface, but simply runs LyX with the --export option to create a postscript file. Here's the debug script:  echo q to quit, e to edit in LyX, anything else to regenerate Postscript read var until test "$var" = "q"; do         cd         rm -f hello.ps         echo; echo; echo; echo;         if test "$var" = "e"; then lyx hello.lyx else lyx --export ps hello.lyx gv hello.ps fi echo q to quit, e to edit in LyX, anything else to regenerate Postscript read var done Run the preceding script, and it repeatedly creates a new Postscript file with a new LyX session, and shows you the results. Each time, after you close the Postscript viewer, the script gives you a chance to edit the file and continue the loop, continue to loop without editing, or quit. ## Making a New Environment It's now time to make a new Environment. We'll call the new environment Story, and it will be just like the Standard environment except it will be italic. When making a new Environment, you make two different components. The first is a 100% LaTeX description of the desired output, enclosed between a LyX Preamble line and a LyX EndPreamble line. Once again, this LaTeX code has NO EFFECT on how the environment looks in LyX, and has TOTAL EFFECT on how it looks when rendered to DVI, Postscript or PDF. The other component is LyX code that defines how the environment looks in LyX, and also contains a pointer to the LaTeX component. The LyX component begins with a Style statement, and ends with an End statement. The LaTeX component can be nested inside the LyX component, or it can be separate. Generally speaking, if only one Environment uses the LaTeX component, it's more readable to keep them nested. Remember, you can nest the LaTeX inside the LyX, but not vice versa. LyX is a front end to LaTeX, but LaTeX knows absolutely nothing about LyX. The following is the code, which must be placed in$HOME/.lyx/layouts/hello.layout, implements the Story environment:

 Style Story   LatexType             Environment   LatexName             story_l   ParSep                0.7   Font     Shape               Italic   EndFont   Preamble         \newenvironment{story_l}                 {                 \itshape                 }                 {                 \par                 }   EndPreamble End

Here the LaTeX component, which is delimited by the Preamble and EndPreamble LyX statements, is nested inside the LyX component. Let's start with the logic of the LaTeX component.

The syntax for a LaTeX new environment statement is as follows:

\newenvironment{environment_name}{start_code}{end_code}
So at the start we tell the text to be italic, and at the end we tell it to start a new paragraph (or else the next paragraph would be tacked on to this one).

Now let's discuss the LyX code. It starts by declaring a style called Story. The next line says this style is an environment. It could also be a command, or other types of styles. The next line is a pointer to the LaTeX environment to be implemented. You can think of this line as a pointer.

The next line declares that paragraphs of this type shall be separated by 0.7. Without this line, successive Story paragraphs would be too close. Note this affects the appearance in LyX only -- it does NOT affect the final output.

The information between the Font and EndFont lines define how the font looks in LyX, and should roughly match the final output.

Once again, remember that the preceding must be put in the .layout file.

For LyX to find it, the .layout file must be located in either /usr/share/lyx/layouts or $HOME/.lyx/layouts. These are a great place to put layouts that relate to a large number of files in different projects, but not for a layout specific to a single document. I try to keep a 1 to 1 relationship between documents and layouts for the simple reason that I'd prefer documents don't change their appearance unless I consciously change them. If I find a better appearance in a new book, I don't necessarily want my older book to change its number of pages. In cases where you want a layout to stick with the document, it's best to put the layout file in the same directory as the document, and then place a symlink from a strategically named .layout file in$HOME/.lyx/layouts to the actual layout file in your document's directory. That way the layout file is safely grouped with its document, but LyX finds it.

So for instance, if I have a mybook.layout and a mybook.lyx in the /books/mybook directory, I can symlink it as follows:

ln -s /books/mybook/mybook.layout $HOME/.lyx/layout/mybook.layout You'll notice that the symlink name in the$HOME/.lyx/layout directory is the same as the actual filename in the /books/mybook directory. That is not absolutely necessary. You could have called the symlink whatever.layout:
9a10,11
> \usepackage{setspace}
> \setstretch{0.8}

"But wait", says the Windows advocate. "I can buy a respectable computer for $500.00 too! Where's the Linux saving?". The Windows advocate is right. Microsoft's OEM Windows license is so cheap that it's more than offset by the economies of scale of Dell, Gateway, Compaq, HP, and the big and medium whitebox vendors. The Windows advocate might mention that "you get what you pay for". And the Windows advocate would be absolutely right. You get what you pay for. More on that later. To compete with Linux, especially in these days of the quality$400.00 box, Microsoft has had to cut the OEM license price to the bone. This is a problem for Microsoft, because they need to make their profit somewhere. If not the OEM Windows license, then where?

I wonder how much Microsoft makes on their new "anti-piracy" measures? How many people get so fed up trying to fix their computer with the "recovery disk" packaged with an OEM system that they simply buy a fully licensed copy for what, $200.00? Will Microsoft later use their mandatory registration as a profit center? "I'm sorry sir, our records show more than 3 reinstalls on your computer, so you'll need to buy our reinstallation 5 pack". Don't think it can happen? Five years ago, did you ever dream you could buy a piece of software and have the vendor control your installation? Another profit center for Microsoft is the apps they don't include:  On Linux Install Disk Windows Substitutes OpenOffice (free)** MS Office (hundreds) LyX (free) Desktop publisher software (hundreds) * GCC (free) MS Visual C++ (hundreds) Gimp (free) Photoshop (hundreds) * Vim (free) or Emacs (free) MultiEdit(hundreds)*, others (varying prices)* * Not a Microsoft Product ** Not on all Linux distributions, but freely downloadable Microsoft's site lists the price of the full version of Office XP Suite, Standard Edition as$479 US. So if you need an office suite, your $500 box just skyrocketed to$979. Of course, many folks say "I'll just copy it". That's efficient if you get away with it, but if the software police audit you it could boost your $500 box to$150500 (one hundred fifty thousand, five hundred dollars).

The only C++ I could find on Microsoft's website is Visual C++ .NET. The cheapest edition is the Professional Edition, which sells for \$1,079 US full version. Ouch!

Meanwhile, when you obtain a Linux distro, you get literally hundreds of pieces of software -- desktop, server, development, scientific, financial, games, and tons of others. Naturally you won't use all of them, but almost anything you want to do is doable by software packaged with your Linux installation CD set. And if you can't find it there, you'll almost certainly be able to download it. Considering the costs for alternatives to this free software (free both as beer and as speech), that Windows box starts looking expensive indeed.

Now of course you and I know that almost all the Open Source tools have been ported to Windows, so it's not necessary to pay these prices. But somehow, doesn't it seem like when people use Windows, they end up buying the commercial software?

The Windows advocates are right -- you get what you pay for. The OEM Windows license is artificially low to compete with Linux. And if you buy it, you get what you pay for. You live with huge software costs, uncertain ability to reinstall, increased virus risk, the need to buy an antivirus program, and vendor lockin.

So when buying a computer, don't just look at Windows' cheap purchase price. Look at the total cost of ownership. After all, you get what you pay for.

# How to Submit an Article

We anticipate two to five articles per issue, with issues coming out monthly. We look for articles that pertain to the Linux or Open Source. This can be done as an essay, with humor, with a case study, or some other literary device. A Troubleshooting poem would be nice. Submissions may mention a specific product, but must be useful without the purchase of that product. Content must greatly overpower advertising. Submissions should be between 250 and 2000 words long.

Any article submitted to Linux Productivity Magazine must be licensed with the Open Publication License, which you can view at http://opencontent.org/openpub/. At your option you may elect the option to prohibit substantive modifications. However, in order to publish your article in Linux Productivity Magazine, you must decline the option to prohibit commercial use, because Linux Productivity Magazine is a commercial publication.

Obviously, you must be the copyright holder and must be legally able to so license the article. We do not currently pay for articles.

Troubleshooters.Com reserves the right to edit any submission for clarity or brevity, within the scope of the Open Publication License. If you elect to prohibit substantive modifications, we may elect to place editors notes outside of your material, or reject the submission, or send it back for modification. Any published article will include a two sentence description of the author, a hypertext link to his or her email, and a phone number if desired. Upon request, we will include a hypertext link, at the end of the magazine issue, to the author's website, providing that website meets the Troubleshooters.Com criteria for links and that the author's website first links to Troubleshooters.Com. Authors: please understand we can't place hyperlinks inside articles. If we did, only the first article would be read, and we can't place every article first.

Submissions should be emailed to Steve Litt's email address, with subject line Article Submission. The first paragraph of your message should read as follows (unless other arrangements are previously made in writing):

Copyright (c) 2001 by <your name>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, version  Draft v1.0, 8 June 1999 (Available at http://www.troubleshooters.com/openpub04.txt/ (wordwrapped for readability at http://www.troubleshooters.com/openpub04_wrapped.txt). The latest version is presently available at  http://www.opencontent.org/openpub/).

Open Publication License Option A [ is | is not] elected, so this document [may | may not] be modified. Option B is not elected, so this material may be published for commercial purposes.

After that paragraph, write the title, text of the article, and a two sentence description of the author.

## Why not Draft v1.0, 8 June 1999 OR LATER

The Open Publication License recommends using the word "or later" to describe the version of the license. That is unacceptable for Troubleshooting Professional Magazine because we do not know the provisions of that newer version, so it makes no sense to commit to it. We all hope later versions will be better, but there's always a chance that leadership will change. We cannot take the chance that the disclaimer of warranty will be dropped in a later version.