| November 14, 2009 5:00 pm

Imagine for a minute that you’re writing a book or technical manual.  Let’s say it’s a book on technology, maybe the open source tools used for scientific writing (to randomly pick an example).  As you write this book, you realize that you need some way to cue the reader into different parts of the text.

For instance, you might want all definitions to appear in bolded text so that a reader pick out key terms quickly.  Or you might want code examples to appear in a different font than the regular text, again, so they’re easy to find.  What’s the best way to do this?

Sure, you could just bold the definitions, or manually change the font for the code examples.  But that’s painful!  Changing typeface and size every time that you have a section of code will eventually result in a lot of lost time.  Moreover, you might make a mistake, which destroys your consistency and makes your writing look unprofessional.  There must be a better way!

Thankfully, there is.  It’s through the consistent use of styles.

Styles Defined

A style is a collection of formatting commands with a meaningful name.  Examples in Microsoft Word include “Heading 1”, “Body”, and “Figure”.  When you use them consistently, styles allow for “logical markup” of a document.  That is to say, you tell the computer what the section, paragraph or text corresponds to and then it handles the formatting.  For this reason, styles form the basis of the “What You See Is What You Mean (WYSIWYM)” philosophy used by LyX and other “document processors”.

There are three major types of styles: section styles, paragraph styles and character styles.  You are likely familiar with section and paragraph styles, as they populate the main drop down box of LyX’s main toolbar. The most common section styles are: chapter, section, subsection.  Examples of paragraph styles include: standard text, quotations, and code.  But the third main type of style, “a character style” may be a stranger.  It isn’t as common as it’s two older brethren and easier to lose track of; which is a huge shame, because it is just as important.

Character styles, as the name implies, work on individual characters within the text of a paragraph.  To extend the examples given in the introduction, the most efficient way to bold a definition would be to use a pre-defined character style called “definition”.  Ditto for an in-paragraph sample of code.

“Now wait a minute,” you’re probably saying, “I’m not sure that I follow the difference between character styles and other text formatting commands like ‘bold’, ‘italic’, or ‘underline’!”

That is perfectly alright, the distinction can be a bit hazy.  Nonetheless, it is still key in understanding the difference between “logical markup” and formatting.  Let me see if I can clear it up.

As described above, a style is typically used to describe what a part of the document is, rather than how it should look.  Subsequently, you are unlikely to see a style called “bold”, “italic” or “center”.  Those terms describe how the text should appear; which is to say, they are formatting commands.  Bolded text uses a heavier line stroke and centered text appears in the middle of the page.  A style, on the other hand, is used to describe a “definition”.  You then associate that style with how you want “definition” to look.  It could be numbered, bolded and centered; or it might be larger than the surrounding text and italicized.  The appearance is determined by a “style sheet”.

Note: Since the use and customization of section and paragraph styles is well explained in the LyX help documentation, this article will focus on character styles.

Using Character Styles in LyX

LyX provides some common character styles through the use of its “Logical Markup” module.  These include styles for nouns, emphasizing text, and code – which may be useful for highlighting filenames or programming syntax within the body of the paragraph.

The character styles are not loaded by default, however.  Instead, they come as part of an optional module.  You can use them by going to the “Document->Settings->Modules” pane and adding “Logical Markup” to your document.

LyX supports several character styles (including noun, emphasize, strong and code) through the "Logical Markup" module.

Once the “Logical Markup” module has been loaded, you  use of apply a particular character style through the “Edit->Text Styles” menu, or by first highlighting a block of text and selecting “Text Style” from the right click context menu.

Note: The emphasize style is distinct in that it can also be toggled on and off through the “Ctrl+E” keyboard shortcut.

You can add a character style to a document either through the "Edit" menu, or by selecting a block of text and then right clicking on it.

After you’ve formatted a block of text with character style, it will appear differently from the surrounding text.  It will not only use a different font, but will also be surrounded by a set of hash marks.  The example below shows a document with two instances of the “Code” character style.  Optionally, character styles have a label which you be toggled on and off.  The screen shot below shows what this looks like.  The first instance, “TEXMFLOCAL”, has the label toggled off while the instance, “/var/lib/texmf/tex/latex”, shows the same character style with the label visible.

This example shows two blocks of text formatted with the "code" character style.

Customizing Character Styles

But what if you need access to other character styles?  Perhaps you’re writing a novel and would like to have a dedicated style for specifying when a character is talking to himself (called internal dialogue)?  Or you’d finally get back to working on your textbook with bolded definitions.  Such styles aren’t defined by the “Logical Markup” module, or any module at all for that matter.  Nor are they likely to be used so frequently that it is worth trying to modify the built-in modules or create a new one to support them.

Luckily, there is a solution to this problem.  In the first article in this series, I looked at how to create a template for an NIH grant proposal from an existing LaTeX document class.  In that article, the secret to using the “nih.cls” document class lay in its corresponding LyX layout file (“nih.layout”).  Also in that article, I explained how LyX layout files primarily contain information concerned with on-screen presentation.

Note: For more detail, see: Customizing LyX – Part 1, Understanding the Big Picture.

As a first approximation, what I said in that article is mostly true.  But, naturally, the reality is more complex.  LyX layout files can also contain information about character styles.  This includes both information about how they should be presented on-screen and how the underlying LaTeX typesetting language should process them.  Moreover, that information can either live in a global layout file (like nih.layout) or in the .lyx file you are working on (meaning that it can be conveniently added to a template).  In the remainder of this post, I will show how to create custom character styles by modifying the local layout.

Example: Creating a “User Interface” Character Style

As you might have guessed, the example introduced above isn’t so random.  For the past several weeks, I have been working on a book about scientific and technical writing.  The book will cover a number of programs and technologies including LyX, LaTeX, BibTeX, Mendeley, Scribus and Kile.

Since it is geared to a somewhat technical audience, it includes both instructions on how to use program’s UI and code samples.  For my code examples, I can use the internal LyX character style.  But I’ve found that I would also like to highlight references to the UI.  There isn’t a pre-defined UI character style.

Fortunately, I not the first person writing a book with UI references.  If you look at the LyX user manuals, you will see that the LyX documentation team created a character style specifically for highlighting LyX menu commands.  It uses a sans serif font and I think it is rather attractive.  But, how do you go about adding it to another document?

It’s actually pretty straightforward:

  1. Since there isn’t a UI to modify the local layout in LyX, open your document in a text editor
  2. Create a local_layout section
  3. Define how you want your character style to appear (both on screen and in the LaTeX output)

Step 1: Open your document in a text editor

As explained above, custom character styles live in the local_layout section (enclosed with the “\begin_local_layout” and “\end_local_layout”) near the beginning of a LyX document.  Unfortunately, there is not currently a user interface pane within LyX to edit this section.  As a result, open the document in your favorite text editor.  The figure shows what this looks like for a file called “Book Chapter – Technical.lyx”.

Note: There is nothing to be afraid of, LyX’s file format is relatively easy to parse; even for human beings.

A sample LyX document for a technical book chapter.

“Book Chapter – Technical.lyx” has three major sections:

  • Document: enclosed by “\begin_document” and “\end_document” (off-screen)
  • LaTeX Preamble: enclosed by “\begin_preamble” and “\end_preamble”
  • Local Layout: enclosed by “\begin_local_layout” and “end_local_layout” (off-screen)

I have added some text to the LateX preamble in this example.  The command tells LyX to use the “Latin Modern” fonts instead of the LaTeX default fonts, which I find to be rather ugly:

% set fonts for nicer pdf view

Step 2: Create a Local Layout Section

If it doesn’t already exist, insert a local_layout section.  For organizational purposes, I like for it to appear following the preamble.  Below is the full text of the layout section for “Book Chapter – Technical.lyx”:

    Format 7
        InsetLayout    CharStyle:UserInterface
        LyxType               charstyle
        LabelString           userinterface
        LatexType             command
        LatexName             userinterface
            Family              Sans
            \newcommand*{\userinterface}[1]{{\sffamily #1}}

In the example, there is some template code (also known as boilerplate), and values that you can modify in order to better customize the appearance of your character style.  The boilerplate includes “Format 7”, LyXType      charstyle”, and “LatexType    command”.  These values will be constant for all character styles, but everything else can be customized.

Step 3: Define how you want the character style to look

When customizing the appearance of your character style, the first thing to do is to decide what you want to call your style.  This is done by modifying the “InsetLayout” argument.  Since my book project covers many different programs, I’ve decided that I will use this character style for any reference to the ui.  That includes menus, button names, or dialog box text.  As a result, I’ve called it “CharStyle:UserInterface”.  This is what appears when I go to the “Edit->Text Style” menu and in the dialog box that appears when I right click.

Next, you need to decide what you would like the “label” to be.  The label appears when the “show label” option is toggled on.  In this example, it’s “userinterface”.

I also need to associate my character style with a LaTeX name.  Again, I’ve opted to call it “userinterface”.

The next block of options, “Font”, specify how the text will look on screen.  You could be extremely ornate specifying text size, typeface, and  font weight.  In this case, however, I want to go with something simple.  I’m just going to use the “Sans” font family for on-screen to display.  Boring, but functional.

Note: A complete list of available options can be found in the LyX help documentation: “Customizing LyX: Features for the Advanced User”.  See section 5.3.6.

The Preamble block tells LaTeX how it should process the character style.  Again, I don’t want to do anything fancy, so I’m just going to use the “Sans Serif” font family.  This is accomplished by the following LaTeX command:

\newcommand*{\userinterface}[1]{{\\sffamily #1}}

The “\newcommand” syntax tells LaTeX about my custom style, while everything after is specifying the text and the font family. “\ssfamily” refers to the sans serif font family.  Other options I could have used include the roman font family (“\rmfamily”), the typewriter family (“\ttfamily”), medium text (“\mdseries”), italic (“\itshape”), or small caps (“\scshape”).

Note: For a more complete list with sample output, see here (Table 4.5).

When finished, save your document and exit the text editor.  When you load the document back into LyX, your style should appear in the “Edit->Text Style” menu.  The screenshot below shows how the “User Interface” character style looks in use.

Miscellaneous Things and Conclusion

Like the example in the previous article, I like to save documents with custom character styles as templates.  This means that I can create additional documents very easily by going to the “File” menu and choosing the “New from template” option.  The new document will have all of the template’s settings, including the LaTeX preamble and the custom character styles.  It also means that I can keep separate templates for technical documents, scientific articles, book chapters and fiction.  Each has character styles defined that make sense for that type of publication.

Character styles make writing long documents much easier.  It’s so much better to label a piece of text as “code” or “userinterface” than it is to remember the exact formatting specifications.  Moreover, it makes the document more consistent and provides an easy path to change formatting at a later date.  As a first time author, I have no complaints about anything that makes my writing easier, more organized, and flexible.


No Responses to “Customizing LyX: Character Styles and the LyX Local Layout”

Care to comment?