| November 2, 2009 6:21 pm

LyX is a wonderful writing program.  It’s easy to use and produces beautifully typeset output.  More importantly, though, it lets an author focus on the content and structure of his writing; rather than the formatting.

It isn’t so easy to customize, though; and this limits its usefulness in a big way.  What if you need to create a new layout or take advantage of one of the thousands of specialized  LaTeX styles?  How, exactly, do you go about doing that?

That’s why this article was written.  Recently, I was asked to help with a National Institutes of Health (NIH) R21 grant proposal.  After some talk amongst the different investigators, it was decided that we would use LaTeX and LyX to draft it.  Unfortunately, we hit a rather substantial hurdle early in the process:  LyX doesn’t have an NIH grant template.

After additional debate, we decided to proceed with LyX anyway.  But in the process, I found myself saddled with an additional job.  In addition to responsibilities as research flunky and copy editor, I was tasked with creating a LyX and LaTeX template for our NIH grant.  This article will summarize the steps I took and describe how to create a custom template using an available style on CTAN.


Note: All of the files in this tutorial can downloaded here (.zip).

Understanding the Big Picture

Before laying out the procedure, I will start with the theory. That includes understanding how LyX and LaTeX interact, as well as what files they use for their respective jobs.

An Introduction to LyX and LaTeX

As you probably already know, LyX is a document preparation system which supports LaTeX, DocBook, and other typesetting technologies.  Writing with LyX is easier than using regular LaTeX or DocBook because it abstracts away the markup language and most of the associated pain.  Want to insert a citation?  Just hit Insert –> Citation.  There’s no fussing with markup tags or macro commands.  The same goes for inserting figure legends, tags, labels, footnotes or any other relatively complex formatting.  LyX takes care of all the minutiae for you.

When you want to customize LyX, however, all of the ugliness and complexity gets shoved right back into your face.  Instead of just writing and letting the program sort out the details, all of a sudden you are transformed from a user into a collaborating developer.  You need to know how the underlying technologies work.  What’s the difference between a LaTeX class and a style sheet?  What does a LyX layout document do?  How does that differ from a LyX template document?  How do you install them and get the system to recognize that they’re present?

To get a handle on these questions, you need to understand that LyX and LaTeX accomplish two different (though complementary) goals.  LaTeX is largely in the job of creating printed documents (typesetting), whereas LyX is about helping you to write and organize the document (on-screen display).

I like to think of LyX as an editorial assistant while LaTeX is the production staff.  The editorial assistant organizes the various elements into a more logical layout, puts references and other material at your fingertips, and finally helps collate everything into a package that the production people can make sense of.  Once the package has been assembled, the production staff then goes about laying it all out on paper, making sure that references are all numbered and formatted correctly, and otherwise handling the business of making the document beautiful.

LaTeX Classes and Styles

To go about its work, LaTeX uses a couple of important files: document classes (.cls) and styles (.sty).  As mentioned, the entire purpose behind LaTeX is that you should be able to focus on the content of your writing without being distracted by its visual presentation.  Classes and styles are what make this possible.  As you are writing, you tell LyX (and by extension LaTeX) whether a block of text is a chapter, figure legend, table, or footnote.  When ready, you can then transform the markup (which makes sense to a computer) into something that makes sense to a human being.

LaTeX classes are the first step in the transformation.  They contain important information about what the structure of the document should be and where things should go.  You might even say that a class file tells a document “what” it is.  Subsequently, the most common types of document classes are articles, reports, and books.

A LaTeX style, in contrast, tells the file “how” it should look.  If a class says, “You’re a book,” then a style will say, “you should have one inch margins” and “the chapter heading should be in Arial 16 point font with 0.2 inches of space above and below them”.  Any given document will only have a single document class, but may use many different styles.

LyX Layout and Template Files

In contrast, a LyX layout file corresponds to a LaTeX class and tells LyX how to draw things on screen; and this is where things can get a little confusing.  Even though a LyX layout is supposed to look like the printed page, this isn’t always true.  For example, the final document may have two or three columns; but on-screen the LyX document will only have one.  What is true, however, is that a LyX layout file will contain information about what document elements are available.  If you’re writing a book, for example, the LyX layout will have an option called “Chapter”; even though the fonts and spacing used won’t always be exactly the same.

The final fie type that you need to know about is called a template.  Whereas a layout file largely contains information about the on-screen display, the template file has information about typesetting and presentation.  In many ways it inherits both the properties of the LaTeX .cls and .sty files and the LyX layout properties.  This means  that you can add both LaTeX and LyX information to it.

The figure below shows these relationships graphically.

How LyX Works

Creating a Custom LyX Template – NIH Grant Proposal

With the definitions out of the way, here is the procedure for creating a custom document template.  There are four basic steps:

  1. Download the necessary document classes and styles
  2. Install the files into the proper folder of your LaTeX distribution
  3. Create an appropriate layout file corresponding to the document class or style
  4. Create a template file with additional details and information

Step 1: Download the necessary styles and templates

The very first step is to locate the document class that you need to use.  There are many good resources to do this.  The first is CTAN, which is probably the most comprehensive resource available.  (You can also find very good package lists on Wikipedia and through Google.)  Since I already know the name of the document class I need (NIH), I will download it from the associated CTAN page.

Step 2: Install the files into the proper folder for your  LaTeX distribution

Once you have saved the files onto your computer, you need to place them in one of several locations.  If all users of the computer need it, install it to the system wide LaTeX tree.  If, however, you are the only person who will be using the package, you can place it in your own “user” folder.

The location of the system tree varies depending on which version of LaTeX you happen to be running.  It is typically defined by the “TEXMFLOCAL” variable.  For individuals using Ubuntu Linux, you will find it at “/var/lib/texmf/tex/latex”.  For users of other LaTeX distributions or operating systems, you will need to consult the documentation files.  The “user” tree is located in your own user folder.  For users of Linux, this will be “/home/username/texmf/tex/latex”.  Note: Be sure to replace “username” with your appropriate login information.

To install the package, unpack the archive and copy all of the contents to the appropriate location.  After, you will need to update the LaTeX database by running texhash.

sudo texhash

Step 3: Create an appropriate style layout for LyX

Now that the package has been installed, we need to create a layout file so that LyX can make use of it.  This is a two step process:

  1. Edit the document class and style so that it only contains general elements
  2. Generate a new LyX layout file

Step 3.1: Edit the document class and style to only contain general elements

Working with LaTeX classes in LyX is slightly different than how you would work with them in a tool like Kile or TeXMaker.  As already mentioned, LyX abstracts a lot of the technical detail of LaTeX away.  However, when using a tool like Kile, you directly interact with the LaTeX code.  When working this way, it can be convenient to place commonly used elements into the document class or style.  The NIH files that we downloaded and installed in the steps above do this.  (The page headers and footers contain the name of the primary investigator and the reference number for the grant.)

As you might guess, however, this isn’t a good thing if you are trying to create a general template.  The document class and style files should only contain the elements that are going to applied to all of the documents.  This shouldn’t include dates specific to a given revision, the name of a principal investigator, or the title of the grant.  We want to install the LaTeX files and then forget about them, which is simply impossible if they contain such specific information.

As a result, before we go further, we need to redact this information from the nih.cls file.  But even though we are removing it, don’t throw it away! Stick it in a spare text file for the time being.  It is still needed so that the final document will match NIH style conventions.  We will add it back to the template created in Step 4.

In the original files from CTAN, open up nih.layout in your favorite text editor and cut out the following text:

% preamble stuff
\newcommand{\nih@PIname}{Oakes, Robert Stilman}

% constants


In addition to redacting the information above, you will also want to add the following line close to the end of nih.cls.  It will ensures that alphabetic section labels will be used instead of numeric labels:


Note: In the files for this tutorial, I have already redacted the unnecessary text from the nih.cls file and added it to the NIH Grant Proposal template.  I have also added the section label code.

Step 3.2: Generate a new LyX layout file

The easiest way to create a new layout file is to modify one of the existing examples.  If you look closely at the NIH document class (nih.cls), you will notice that it is based on the LaTeX “article” class.  As we try and create an appropriate nih.layout, let’s start by modifying article.layout.

When you first open the file, you will see the following:

# Do not delete the line below; configure depends on this
# \Declare LaTeXClass{article}

Format 11
Input stdclass.inc

SecNumDepth             3
TocDepth                3

NoStyle Chapter
NoStyle Chapter*

Style Part
    Align                 Left
    AlignPossible         Left
    TopSep                2
    BottomSep             1.5
      Size                Larger

As you study the layout, you should start to see a few general sections.  For example, the second line tells LyX that it is using the LaTeX class “article”.  “Input stdclass.inc” tells LyX to import the standard list of document elements.  Whenever you see a line that begins “NoStyle”, that is telling LyX to remove those particular section types from the available list of options since they aren’t supported by the document class.

Pay close attention to the section block that begin with “Style”.  This tells LyX how to display that particular document element on screen.  It includes information about how the text should be aligned (“Align”, “AlignPossible”) and what font should be used (“Font”, “Size”, “EndFont”).

To make article.layout work with nih.cls, we need to make two modifications.  First, we need to change the \DeclareLaTeXClass and then we need to add a new “Style” block.

First, let’s change the \DeclareLaTeXClass.  Add the following:

\DeclareLaTeXClass[nih]{proposal (NIH)}

In this example, nih is the name of the LaTeX document class (nih.cls) and the information in curly brackets is a description which will make it easier to find in the LyX document settings pane.

Next, we need to add a “Style” block that describes the “Section” element of the nih document class.  By default NIH sections are labeled alphabetically: “A Specific Aims”, “B Background”, “C Methods”, etc.  In contrast, the article labels its sections numerically: “1 Specific Aims”, “2 Background”, “3 Methods”, etc.  If we don’t modify the standard labeling, it will be displayed incorrectly on screen

Luckily, it’s an easy fix.  Add the following to article.layout:

Style Section
    LabelType             Counter
    LabelCounter          section
    LabelString           “\Alph{section}”

Before using your new document class, you will need to reconfigure LyX so that it can see them. After you’ve made these changes, resave the file as “nih.layout”.  Then copy the file to either the main LyX directory layouts folder (typically LyXDir/layouts) or to your LyX user directory (typically found at .lyx/layouts/).  For LyX to see and use the new files, you will need to run Tools –> Reconfigure.

Note: A full version of the nih.layout file is available as part of the archive package for this tutorial.

Step 4: Create a LyX template file

With a fully functioning LyX layout (nih.layout), you can now create a template file that has all of the needed elements.  As mentioned above, a LyX template file is nothing more than a regular LyX file.  So, start by creating a new LyX document (File –> New).

After the new document is open, the very first thing that you should do is change the document class.  Go to Document –> Settings –> Document Class.  Then from the drop down menu, select “proposal (NIH)”.

Customize LyX - Document Settings

Next, you need to add the information removed from nih.cls to the LaTeX Preamble.  Go to Document –> Settings –> LaTeX Preamble, and paste the text into the provided space.  While doing this, you may want to modify the name of the PI that will be shown in the document header.  You make this change by adding your name to the line that reads:

\newcommand{\nih@PIname}{Last Name, First Name Middle}

When done, press “Close”.  You now have a fully functional, NIH compliant grant proposal template.

Customize LyX - Document Preamble

But while that’s the end of the essential boilerplate, you may want to include a few additional goodies.  Wouldn’t it be nice, for example, if you had access to clickable hyperlinks?  Or if you were be able to use the bookmarks sidebar to navigate the document?  For these and other desirables, add the following to the preamble:

% Hyperlink Options
\usepackage{ifpdf} % part of the hyperref bundle
\ifpdf % if pdflatex is used

% Use True Type Fonts Instead of Older LaTeX Fonts

\fi % end if pdflatex is used

% for correct jump positions when clicking on a link to a float

This code enables the hyperref package.  Then, go to Document –> Settings –> PDF Properties and enable hyperref support in the options.  While changing the PDF properties, I personally like to customize the colors of the links.  I think that document links and cited references should be black; while urls and files should be blue.  To make this change, add the following to the “additional options” line:

linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue

Customize LyX - PDF Properties

Using the Template

If you’ve followed all of the steps in this tutorial, you will now have a fully functioning NIH grant template.  Now might be a good time to save it in the same location where you keep other templates.  (If you don’t have a templates folder, you might want to create one.)  I’ve saved mine as “NIH Grant Proposal.lyx”.  From here on out, whenever I want to create a new NIH document, I simply choose New from template from the File menu and load the appropriate version.

Now that my template is set up, I’m back to an automated wonderland.  LyX and LaTeX keep track of the references, labels, footnotes, formatting and the other minutiae that make complicated documents so painful.  I’m free to focus on the ideas,  voice, and message; which is exactly how it should be.


3 Responses to “Customizing LyX: Create an NIH Grant Proposal Template”

[…] Unfortunately, creating layout files is a bit of an arcane art; and as a result, many document classes are never adapted to work with LyX. (For more information about how the relationship between LyX and LaTeX –including an example of how to create a custom layout from an existing document class – please see my earlier article, Customizing LyX: Create an NIH Grant Proposal Template.) […]

yves wrote a comment on October 28, 2013

You seem to have a mastery over Lyx and Latex. I also saw you had developed a module for Lyx.

I was wondering how prototyped it and how you are integrating it into Lyx?

I have an idea for a similar “plugin” for helping with various formatting customizations that are not simple to figure out unless you are a Latex/Lyx master.

The idea is to have a GUI to select what kind of formatting you want, and generate some text that can be pasted into the preamble.

For example, specifying how chapters and sections should look (from what options are available from titlesec package). Or formatting options for the TOC (based on options available in tocloft package).

Essentially I want to make a simple tool that would make formatting a bit more straightforward for the common folk like me.

Care to comment?