CONTENTS

Editor's Desk We Stand On Their Shoulders LyX Overview Understanding LyX Through Contrasts LyX Facts and Myths LyX Hello World Writing a Letter Installing or Upgrading LyX LyX Documentation Resources Making a Book Adding to Your Document Simulating Character Styles With Color Pseudostyles

Making Your Own Layout LyX Code vs. LaTeX Code Expanding Your .layout File Making a Note Environment Changing Vertical Spacing Learning by Reverse Engineering Headers and Footers Odds and Ends Life After Windows: You Get What You Pay For Letters to the Editor How to Submit an Article Trademarks URLs Mentioned in this Issue

Editor's Desk

By Steve Litt

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!

Steve Litt is the author of "Troubleshooting Techniques of the Successful Technologist".  Steve can be reached at Steve Litt's email address .

We Stand On Their Shoulders

By Steve Litt

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.

Steve Litt is the author of the Universal Troubleshooting Process courseware.   Steve can be reached at Steve Litt's email address.

LyX Overview

By Steve Litt

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.
 

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

Author==>LyX front end==>LyX language==>LaTeX==>TeX==>DVI==>Postscript

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.

Steve Litt is the author of the Universal Troubleshooting Process courseware.   Steve can be reached at Steve Litt's email address.

Understanding LyX Through Contrasts

By Steve Litt

• 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

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

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

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

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

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

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

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

• 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

Steve Litt is the author of the Universal Troubleshooting Process courseware.   Steve can be reached at Steve Litt's email address.

LyX Facts and Myths

By Steve Litt

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

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 easy

LyX is impossibly difficult

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

Steve Litt is the author of Rapid Learning: Secret Weapon of the Successful Technologist . He can be reached at Steve Litt's email address .

LyX Hello World

By Steve Litt

lyx

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.
 

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

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

Steve Litt is the author of " Troubleshooting Techniques of the Successful Technologist".  Steve can be reached at Steve Litt's email address .

Writing a Letter

By Steve Litt

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}

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

Steve Litt is the author of " Troubleshooting Techniques of the Successful Technologist".  Steve can be reached at Steve Litt's email address .

Installing or Upgrading LyX

By Steve Litt

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

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]#

ln -s /usr/lib/libstdc++-libc6.2-2.so.3 /usr/lib/libstdc++-libc6.1-2.so.3

rpm -Uvh --nodeps lyx-1.2.1-1.i386.rpm

Lessons Learned

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

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.

Steve Litt is the author of Rapid Learning: Secret Weapon of the Successful Technologist . He can be reached at Steve Litt's email address .

LyX Documentation Resources

By Steve Litt

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:
 
 
 

Reference	Location	LyX	LaTeX	Details
Intro.lyx (Help->Introduction)	/usr/share/lyx/doc/Intro.lyx	Newbie	n/a	Broad and shallow overview of LyX
Tutorial.lyx (Help->Tutorial)	/usr/share/lyx/doc/Tutorial.lyx	Newbie	n/a	2 hour tutorial will answer many of your questions. Best 2 hours you can spend.
UserGuide.lyx (Help->User's Guide)	/usr/share/lyx/doc/UserGuide.lyx	Newbie Apprentice	n/a	Detailed overview of LyX, its environment, its capabilities
Extended.lyx (Help->Extended Features)	/usr/share/lyx/doc/Extended.lyx	Apprentice	n/a	Lesser used LyX features, tips and tricks. Reading this doc early can save a fortune in headscratching time later.
Customization.lyx (Help->Customizations)	/usr/share/lyx/doc/Customization.lyx	Apprentice	n/a	How to customize your LyX environment, as well as incorporating third party improvements such as New Document Classes, Layouts, and Templates.
Reference.lyx (Help->Reference Manual)	/usr/share/lyx/doc/Reference.lyx	Apprentice	n/a	Complete list of LyX functions, and how to bind them to menus, buttonbars, etc.
FAQ.lyx (Help->FAQ)	/usr/share/lyx/doc/FAQ.lyx	Newbie	n/a	Easy FAQ answers many newbie questions
BUGS.lyx (Help->Known Bugs)	/usr/share/lyx/doc/BUGS.lyx	Apprentice	n/a	List of known bugs.
LyX Quickstart	http://www.troubleshooters.com/lpm/200210/200210.htm	Newbie Apprentice Accomplished	Apprentice Accomplished	Soup to nuts LyX familiarization tool
Writing Self-Published Books with Lyx	http://www.troubleshooters.com/linux/lyx/index.htm	Newbie Apprentice Accomplished	Apprentice Accomplished	Newbie to expert LyX book writing tutorial
KatSpace: Using LyX For DTP	http://katspace.net/lyx/lyxhow.shtml	Apprentice Accomplished	Apprentice Accomplished	Kathryn Andersen's excellent solutions to real life LyX problems, including .cls files and lots of problem-solving LaTeX
latex2e.dvi	/usr/share/texmf/doc/latex/general/latex2e.dvi	n/a	Apprentice Accomplished	This is your best general purpose LaTeX reference. 60 pages of details on LaTeX commands, but not much explanation. This is a reference for experts, not a learning tool. But if you're patient in your experimentation, you can learn from it. Be aware that the table of contents is at the end, so to look up a command go to the table of contents at the end.
essential.dvi	/usr/share/texmf/doc/latex/general/essential.dvi	n/a	Apprentice	This is a must read LaTeX explanation suitable for an apprentice level user. If you find yourself having misunderstandings about LaTeX, reread this document.
guide.dvi	/usr/share/texmf/doc/latex/general/guide.dvi	n/a	Apprentice Accomplished	Billed as "A LaTeX survival guide for UNIX systems", this doc is mostly redundant.
lshort.dvi	/usr/share/texmf/doc/latex/general/lshort.dvi	n/a	Apprentice Accomplished	The title is "The Not So Short Introduction to LaTeX2e or LaTeX2e in 87 minutes". This is a sort of advanced LaTeX textbook that's best read on a rainy Sunday afternoon. Read it when you get to the point where you're making your own environments and you don't really understand what you're doing. Reread this doc from time to time. The more expert you become, the more valuable you'll find this document.
fancyhdr.dvi	/usr/share/texmf/doc/latex/fancyhdr/fancyhdr.dvi	n/a	Apprentice Accomplished	Almost everything you could ever want to know about customizing headers and footers, well explained and well organized. A must read!
Class/package documentation	/usr/share/texmf/doc/latex/*	n/a	Apprentice Accomplished	This tree contains documentation for most document classes and packages. It's a wishing well. Want to make slides? See the pdfslide and seminar subdirectories. Want to print a booklet stapled in the middle? See the booklet subdirectory. Want to typeset computer programs? See the program subdirectory. Be sure to look in the styles subdirectory for information on floats, fancybox, lastpage, soul (better underlining), and much, much more.
LyX Tricks and Tips	http://www.lyx.org/help/index.php3	Advanced	Advanced	Tons of tricks and sample code from Herbert Voss, one of the premier authorities on LyX. Contains answers for many or most of the questions you might have. But it's not as organized as one would hope, and it's mostly LaTeX with little info on how to integrate with LyX. I treat this site as a reference for experts.
LyX Mailing List	Sign up at http://www.lyx.org/internet/mailing.php3	Newbie	Advanced	Great resource for newbie questions and advanced questions, but sometimes misses the mark with intermediate questions.

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)

Your Documentation Strategy

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

dvips myfile.dvi

dvips -P printername myfile.dvi

xdvi myfile.dvi

or

dvips -o ~/junk.ps latex2e.dvi; gv ~/junk.ps

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.

Steve Litt is the author of " Troubleshooting Techniques of the Successful Technologist".  Steve can be reached at Steve Litt's email address .

Making a Book

By Steve Litt

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

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

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

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

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

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

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

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}

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

The Extra Tab

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

Making 2 Column Output

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
6. View->Postscript and notice how much more readable your book is.

Layout->Document Preamble

Insert the following line:

\setlength{\columnsep}{1in}

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

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.

This article detailed document formatting. The next article details a few tasks that all writers perform.

Steve Litt is the author of " Troubleshooting Techniques of the Successful Technologist".  Steve can be reached at Steve Litt's email address .

Adding to Your Document

By Steve Litt

Adding a Table of Contents

In your LyX document, place the cursor at the very front of the first Part environment ("Using this File"). Insert->Lists & TOC->Table of Contents. A gray button labeled "Table of Contents" appears just above the first Part environment.

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.

Adding a Graphic

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.
 

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.

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.
8. Click the browse button, and navigate to the gimp Screenshot .eps you downloaded from this page.
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".

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.

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

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

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".

Adding a Cross 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.

Inserting and Modifying a Table

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:

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.

6. File->Save, View->Postscript, and note that the table walked right off the edge of the page. That's no good!

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

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

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.
 

Steve Litt is the author of " Troubleshooting Techniques of the Successful Technologist".  Steve can be reached at Steve Litt's email address.

Simulating Character Styles With Color Pseudostyles

By Steve Litt

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.

First start with a fresh, clean document. Right click HERE to download it, and save it to your home directory. That will be the file you use for this article's exercises, and will be called "your LyX document" for the rest of this article.

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

Steve Litt is the author of the Universal Troubleshooting Process courseware.   Steve can be reached at Steve Litt's email address.

Making Your Own Layout

By Steve Litt

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

Layout File Hello World

#% 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

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

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}

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.

Symlinking the .layout File

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

ln -s /books/mybook/mybook.layout $HOME/.lyx/layout/whatever.layout

\textclass whatever

LyX Code vs. LaTeX Code

By Steve Litt

• Generally, anything appearing in the .layout file between Preamble and EndPreamble lines is LaTeX, and anything in the .layout file not in a Preamble EndPreamble pair is LyX.
• The Preamble and EndPreamble statements themselves are LyX code.
• You could theoretically place LyX statements between Preamble and EndPreamble, but it's seldom done.
• Anything appearing in the document body (in the LyX front end) that is ERT (Evil Red Text, TeX mode) is LaTeX.
• Anything appearing in Layout->Document preamble is LaTeX.

The following code shows all LyX code in red, and all LaTeX code in green:
 

#% Do not delete the line below; configure depends on this #  \DeclareLaTeXClass[book]{hellobook} Input stdclass.inc Preamble % %%% Scratchpad variable for later use \newlength{\scratchLength}%  scratch variable used later % %%% Pseudo character styles indexed by color %%% \usepackage{ifthen} \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 } EndPreamble # %%% Story Environment Style Story   LatexType             Environment   LatexName             story_l   PARSEP                0.7   Font     Shape               Italic   EndFont   Preamble         \newenvironment{story_l}                 {                 %comment                 \itshape                 }                 {                 \par                 }   EndPreamble End

If you want a nice, easy life in LyX, it's essential that you understand the similarities and differences between LyX code and LaTeX code, and know when to use each.
 

Expanding Your .layout File

#% Do not delete the line below; configure depends on this
#  \DeclareLaTeXClass[book]{hellobook}
Input stdclass.inc

Preamble
% %%% Scratchpad variable for later use
\newlength{\scratchLength}%  scratch variable used later

% %%% Pseudo character styles indexed by color %%%
\usepackage{ifthen}
\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
}
EndPreamble

# %%% Story Environment
Style Story
  LatexType             Environment
  LatexName             story_l
  PARSEP                0.7

  Font
    Shape               Italic
  EndFont
  Preamble
        \newenvironment{story_l}
                {
                %comment
                \itshape
                }
                {
                \par
                }
  EndPreamble
End

The preceding layout code starts with the obligatory Latex Class declaration and the importation of the stdclass.inc file. It then begins a preamble, declares a length variable for future use, and implements the color pseudostyles discussed earlier. Now that these pseudostyles are in the .layout file there's no necessity to place the code in the LyX LaTeX preamble. In fact, doing so would likely cause an error. Also, please remember that once you implement color pseudostyles, your document must have at least one instance of one of the declared colors.

Making a Note Environment

Shading and boxing are a little too complex for this article, so instead we'll create the styles using horizontal lines top and bottom. It should be indented about an inch on either side, and just for fun, let's make it sans serif and ragged on the right (not justified to a constant right margin). The code for the environment should be added to the bottom of your existing .layout file created in previous exercises:
 

# %%% Note Environment Style Note   LatexType             Environment   LatexName             note_l   LabelType             Centered_Top_Environment   LabelString           "NOTE"   LeftMargin            MMMMM   RightMargin           MMMMM   ParIndent             MM   TopSep                0.7   ItemSep               0.7   ParSep                0.7   BottomSep             0.7   Align                 Block   AlignPossible         Block   Font     Family               Sans    Shape                Upright    Series               Medium    Size                 Normal   EndFont   LabelFont    Family               Sans    Shape                Upright    Series               Bold    Size                 Largest   EndFont   Preamble         \newenvironment{note_l}                 {                 \begin{list}{}                         {                         \setlength{\leftmargin}{1in}                         \setlength{\rightmargin}{\leftmargin}                         \setlength{\parindent}{0in}                         \setlength{\parsep}{0.2in}                         \itshape                         }                 \item[]                 \hrulefill\\[-.4in]                 \center{NOTE}\\[.1in]                 \flushleft                 \raggedright                 }                 {                 \\                 \hrulefill                 \par                 \end{list}                 }   EndPreamble End

As mentioned earlier, creating such an environment requires a LyX environment definition and a LaTeX environment definition, and a LatexName LyX statement to link the two. The LaTeX environment definition resides between the Preamble and EndPreamble LyX statements. We'll go through each section line by line.

The LyX Section

The following table explains each line of the LyX section of the NOTE environment definition:
  <

LatexType Environment	Specifies that this is an environment, not a command or any other LaTeX entity.
LatexName  note_l	This is the reference to the actual LaTeX code.
LabelType  Centered_Top_Environment	Specifies that within the LyX user interface, this environment will have a label, and that label will be centered above the text. In fact, for the Note environment, this label will be the constant string "NOTE".
LabelString "NOTE"	Specifies that within the LyX user interface, the label to be "NOTE".
LeftMargin MMMMM	Specifies that within the LyX user interface, the left margin is indented the width of 5 upper case M characters.
RightMargin MMMMM	Specifies that within the LyX user interface, the right margin is indented the width of 5 upper case M characters.
ParIndent MM	Specifies that within the LyX user interface, the first line of each paragraph is indented the width of 2 upper case M characters.
TopSep    0.7	Specifies that within the LyX user interface, the start of the environment is separated at least 0.7 units from the environment that came before it.
ItemSep   0.7	Specifies that within the LyX user interface, ????.
ParSep    0.7	Specifies that within the LyX user interface, the vertical space between two paragraphs of this layout.
BottomSep 0.7	Specifies that within the LyX user interface,  the end of the environment is separated at least 0.7 units from the environment that comes after it.