Many first-time users of LaTeX often mistakenly look at the language as a a type of glorified word processing software – albeit a particularly complicated one.  While such an analogy may be apt in helping new users become acclimatized to the language, it suffers from a rather nasty problem: LaTeX isn’t a word processor.

If anything, LaTeX shares more in common with a programming languages than any type of application.  In fact, the document processing system is really nothing more than a bunch of re-usable pieces of programming called macros.  Everything is a macro.  That includes the commands that every user is familiar with: \title{}, \section{}, \subsection{}; in addition to the internal formatting commands that allows LaTeX to function.  (Most of the macros were originally created or packaged by Leslie Lamport as a way of making TeX – the typesetting system created by Donald Knuth – easier to work with.)

This has some rather practical consequence; because everything in LaTeX is a macro, it is far more extensible than a word processor could ever hope to be.  If you require a feature that doesn’t yet exist, it typically isn’t all that difficult to add it.  And when your extension is packaged inside a style or class, you can use those customizations in anything that you want to write.

But though creating macros isn’t particularly complicated, it is a different beast than just using the stock macros for writing.  This is not surprising, the craft of design is inherently different than the craft of writing.  There are different conventions to follow and different topics to obsess about.  In the first article of this series, I introduced the xetexCV document class, which is one example of where I decided to don the designer hat.

But before you get too far down the road of customizing and extending, there are a some important things that you need to know.  These include the general conventions used when working with document classes, their internal anatomy, an understanding of how macros are created, and how to handle formatting and layout challenges.  In this article, I will look at these issues more in detail, particularly as they pertain to xetexCV.  In the process of reviewing these topics, I will also explain some of my design choices.

Understanding Conventions

When trying to customize or extend a document class, perhaps the very first thing to understand is that there are certain conventions.  The document “LateX 2E for class and package designers” describes them this way:

LaTeX has three types of commands.

There are the author commands, such as \section, \emph and \times: most of these have short names, all in lower case.

There are also the class and package writer commands.  Most of these have long mixed-case names such as the following:

\InputIfFileExists    \RequirePackage    \PassOptionsToClass

Finally, there are the internal commands used in the LaTeX implementation, such as \@tempcnta, \@ifnextchar and \@eha: most of these commands contain @ in their names, which means they should not be used in documents, only in class and package files.

These conventions help to better separate  procedural formatting from the descriptive tags used in writing a document.  But it also makes it easier to identify what different sections of the code do.  Sections that are responsible for importing and configuring packages will typically use mixed case names, while variables will contain the @ symbol, and user facing macros will be in lower case.

The Internal Anatomy of a Document Class

The next important thing to understand is that all document classes have a few well defined components.  That is to say, they have an internal anatomy which contributes to their function and physiology.  The internal bits include the class description and required statements, a block that imports and configures packages which new features will depend on, and a section where new macro commands are created or existing commands are redefined.

Class Description and Required Statements

\ProvidesClass

The very first such section gives the package name and description.  Also included is a definition of the most recent version of LaTeX that the document class will work with.  The relevant code from xetexCV is shown below:

\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{xetexCV}[2009/11/30 – Modern looking résumé which uses
the xetex typesetting system]
…

Here, the \NeedsTeXFormat{LaTeX2e} command is the earliest version of LaTeX that the document class will work with.  \ProvidesClass{xetexCV} identifies the class name (xeteCV) and everything in square brackets is the document description.

\LoadClassWithOptions

Generally speaking, there are two major types of LaTeX document classes: those that are free standing, and those that are variations of other document classes.  The standard classes (article.cls, report.cls, and book.cls) are examples of the former.  They contain all of the code needed to compile and work without additional extensions.  xetexCV, is an example of the second type.

To load an existing class as the foundation, you can use the \LoadClassWithOptions macro:

…
\LoadClassWithOptions{article}
…

xetexCV uses “article” for its foundation.  For that reason it is likely that other packages and styles will work without conflict.

Building on the Foundation

\RequirePackage

After the base class has been loaded, the new package is fully functional, if identical to the foundation class.  The next step in the customization process, then, is to begin adding new features and modifying old ones.  In the case of xetexCV, there were several changes which I wanted to make.  First,  I wanted to use an 8 1/2 inch by 11 inch paper (US letter) by default.  I also wanted to set a 1 inch margin.  Next, I wanted to use the XeTeX typesetting system and a pair of advanced OpenType fonts.

These changes are made through the use of other LaTeX packages.  In a document class, add-on modules are loaded through the \RequirePackage command.  Below is the related code from xetexCV:

…
\RequirePackage{fontspec}
\RequirePackage{xunicode}
\RequirePackage{xlxtra}

\RequirePackage{graphicx}
\RequirePackage[colorlinks]{hyperref}

\RequirePackage{ifthen}
…

The first three packages (fontspec, xunicode, and xlxtra) are used by XeTeX to set fonts and provide unicode support.  fontspec, in particular, is very important.  It provides convenience macros that make it easy to change the the various font families: \setmainfont{fontname}, \setromanfont, \setsansfont, and \setmonofont.  It also provides a way to manipulate font mappings, color, scaling, and inter-word spacing.  graphicx is used to add images to the document and manipulate their size.

hyperref makes it possible to add clickable hyperlinks and bookmarks.  The [colorlinks] option specifies that these special links should be rendered in a different color than other text.  The hyperref package is then configured using the \hypersetup{} macro.  By default, I’ve configured xetexCV to use blue for urls and webpages and black for filenames:

\hypersetup{linkcolor=blue,citecolor=blue,filecolor=black,urlcolor=blue}

The ifthen package provides several macros that make it easier to apply conditional formatting.  These will be discussed in more detail below.

Creating New Features and Modifying Old Ones

The last major section of a document class is where new macros are defined and old ones are modified.  As might be expected, this section typically accounts for the majority of the code.

\def and \newcommand

There are two major commands used to define macros and variables: \def and \newcommand.  \def is a TeX primitive while \newcommand is a LaTeX macro that checks for name clashes or other problems.  In many cases, they may be used interchangeably or in concert.  Consider the code block below which defines the \cvname macro:

…
\def\@cvname{\relax}
\newcommand{\cvname}[1]{\gdef\@cvname{#1}}
…

\@cvname (according to the LaTeX conventions) is a variable/macro which should only be used from inside the LaTeX document class.  Consequently, it needs a user-facing macro that can be used to assign it a value.  This is what \cvname does.  In this example, the first line of code creates the variable and assigns it the LaTeX equivalent of a null value (\relax).  The second line is a little more interesting.  It defines a macro called \cvname with one argument [1].  Then, it takes the \cname argument and assigns it to \@cvname.

A second, related example can be seen in the definitions of \@cvimage and \cvimage:

…
\def\@cvimage{\relax}
\newcommand{\cvimage}[1]{\gdef\@cvimage{#1}}
…

Again, the first line of code creates a variable (\@cvimage) with a null value, and the second line creates the user facing macro (\cvimage).  In later commands, the internal variables are used for layout and formatting (see below).

\renewcommand

If I need to modify a particular piece of code, those changes can be made using the \renewcommand macro.  This is similar to over-riding a method in an object-oriented programming language like C++ or Python.  Everything that hasn’t been changed continues to work as before.  In xetexCV, I wanted to modify the \section and \subsection macros.  To do so requires \@startsection and six arguments:

\@startsection {NAME}{LEVEL}{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE}

Generic command to start a section.

NAME : e.g., “subsection”
LEVEL : a number, denoting the depth of the section in the table of contents
INDENT : Indentation of the heading from the left margin
BEFORESKIP : Space to leave above the heading
AFTERSKIP : Space to leave after the heading
STYLE : Commands to set the font and style of the heading

I, therefore, copied over the definitions from article.cls and modified the spacing and fonts:

\renewcommand\section{\@startsection
{section}{1}{\z@}%
{-3.5ex \@plus –1ex
\@minus -.2ex \vspace{1mm}}%
{0.5mm}%
{\sffamily\large\bfseries}}

\renewcommand\subsection{\@startsection
{subsection}{1}{\z@}%
{-3.5ex \@plus -1ex \@minus -.2ex}%
{3.0mm}%
{\sffamily\mdseries}}

But while I chose to completely rewrite my section definitions, much the same thing could have been accomplished through the sectsty package.  Despite the ease of sectsty, I felt that it would be better to define my styles from scratch.  sectsty often throws errors when used with other document classes, like scrbook.

Rules for Creating New Macros

The third important thing to understand when writing a document class is when you should add new macros rather than modifying the behavior of old ones.  In trying to make this decision, it is good to think about how changing a macro’s behavior will influence other document features.  In cases where a change might cause other features to break, it is better to add a new macro.

Managing Complex Formatting – \cvsection and \cvsubsection

While I was redefining the \section and \subsection macros, I ran into one such difficulty.  I wanted to set one indentation level for the header and another for the body text.  Further, I wanted to include a decorative line following the header.  Yet, no matter how I chose to define the STYLE or AFTERSKIP arguments, I couldn’t quite achieve the formatting I wished (shown below).

I finally decided that the formatting was too complex and required a new macro that could be used instead of \section and \subsection.  These new additions became \cvsection and \cvsubsection:

\newcommand{\cvsection}[1]{\leftskip 0cm
\section*{#1}\decorativeline\marginpar{\vspace{0.3ex}}
\leftskip 116pt}

As in the previous examples, \newcommand was used to define a code block with a single argument – the text to be formatted).  Then, I specified the procedure that I wanted to apply to the text

• The left text margin is moved so that it is flush with the page margin (\leftskip 0cm)
• A non-numbered section header is added (\section*{#1})
• The  decorative line is included (\decorativeline)
• The text indentation is returned to the previous value (\leftskip 116pt).

The definition of \cvsubsection is similar, with two exceptions.  First, the \cvsubsection style does not include a decorative life.  The second major difference is more substantial.  I found the vertical spacing preceding the \subsection definition to be too large, I therefore moved the entire text block up by 0.2 cm (\vspace{-0.2cm}).  This was ultimately easier than trying to find a better value for the BEFORESKIP argument:

\newcommand{\cvsubsection}[1]{\leftskip 0cm \vspace{-0.2cm}
\subsection*{#1}\vspace{1.0mm} \leftskip 116pt}

Note: When given a negative value, \vspace moves up the block of text by the specified amount.

Layout and Formatting

One of the very best features of TeX is the automatic layout algorithm that it uses to position content.  In nearly all cases, allowing for LaTeX to manage spacing and layout will result in a better looking document than if you try and do so yourself.  There will be circumstances, however, where it is necessary to manually specify the position of photos or text in a more precise manner.

In xetexCV, there are two such cases.  In the first, special handling is required so that the CV contact information is correctly labeled and typeset.  Additional formatting commands are required so that the images and text of the title section have a “balanced” feel to them.  All of this processing occurs in the \makecvtitle macro.

Conditional Formatting – \ifthenelse

While it may appear simple, the formatting of the xetexCV contact section (which includes the institution, address, phone, fax, email and website information) is rather involved.  First, in order to simplify the use of the document class, I chose to add this information through the use of special macros (\email, \website\, \cvname, etc.).  Because the information is added through tags, this means that logical rules must be set up to handle to handle the layout.  What should happen, for example, if a fax number or website isn’t supplied?

The obvious answer is that the information should be left out of the contact details.  That also means that the label (“Fax:”, “Phone:”, “Email:”) should be omitted.  To accomplish this goal requires conditional formatting, better known to programmers as the “if, then, else” loop.  “If” a condition exists, “then” do one thing, “else” do another.

In LaTeX, conditional formatting is performed by the “ifthen” package and uses the \ifthenelse macro.

\ifthenelse takes three arguments:

\ifthenelse{CONDITION}{IF TRUE}{ELSE}

CONDITION : The test condition, often expressed as \equals{VARIABLE}{VALUE}
IF TRUE : The code that should be executed if the condition is satisfied
ELSE : What to do if the condition is false

At several instances in xetexCV, \ifthenelse is used to test if there is a null (or empty) value for a particular tag.  In the cases where it finds a null value, then no formatting commands are executed.  If, however, there is a value, then text is added.  A few of the simpler examples are shown below:

\ifthenelse{\equal{\@phonenumber}{\relax}}
{}{Phone: \texttt{\@phonenumber}\\}
\ifthenelse{\equal{\@faxnumber}{\relax}}
{}{Fax: \texttt{\@faxnumber}\\[0.2cm]}
\ifthenelse{\equal{\@email}{\relax}}
{}{Email: \href{mailto:\@email}{\@email}\\}
\ifthenelse{\equal{\@website}{\relax}}
{}{Website: \href{\@website}{\@website}\\}

In each of these cases, the \equal macro is used to check if the pertinent variable (specified by the \@ symbol) still has a value of \relax (\equal{\@variablename}{relax}).

Note: \relax can be thought of as an equivalent to null in other language.

If the value is still set to \relax, then nothing is done (denoted by the empty diamond brackets).  If there is a non-null value, however, then the appropriate label and formatted text is added to the document.

While these examples are relatively simple, the same principle can be used to for very complicated formatting.  \makecvtitle, for example, uses a similar conditional statement to see if the user has specified an image.  If not, then it will use one formatting style for the entire title section.  If so, then it uses the layout shown in the examples.

Balancing Images and Text – \makecvtitle

In addition to the conditional formatting issues, \makecvtitle must also wrestle with the best way of creating a single, unified title block.  The CV name, contact information and photo should all be included.  Moreover, subsequent sections should be added after the end of the photo, rather than wrapping around it.  One of the easiest ways to create such a unified block of content is to use the minipage environment.

The minipage is extremely flexible.  It can have text, formatting and image within a self-enclosed space.  Furthermore, they can be embedded within one another.  By creating a series of embedded minipages (as shown below), you can group related content.  You can additionally specify how wide you want each minipage environment to be, or you can let the LaTeX engine make those determinations.

Note: An additional advantage of minipage is that any footnotes added to text within the minipage are  part of that environment instead of the main document.  This is useful for adding footnotes to figures or text.  Accomplishing the same thing in Microsoft Word without tedious manual formatting is impossible.

I’ve used this strategy to ensure that text containing the contact details is properly aligned against the cv photo.  The minipage environment from xetexCV is shown below:

\begin{minipage}{6in}
\begin{minipage}{114pt}
\resizebox*{100pt}{!}
{\includegraphics{\@cvimage}}
\end{minipage}
\begin{minipage}{4in}
\ifthenelse{\equal{\@institution}{\relax}}
{}{\bfseries\@institution\\}
\mdseries\@contactaddress\\[0.2cm]
\ifthenelse{\equal{\@phonenumber}{\relax}}
{}{Phone: \texttt{\@phonenumber}\\}
\ifthenelse{\equal{\@faxnumber}{\relax}}
{}{Fax: \texttt{\@faxnumber}\\[0.2cm]}
\ifthenelse{\equal{\@email}{\relax}}
{}{Email: \href{mailto:\@email}{\@email}\\}
\ifthenelse{\equal{\@website}{\relax}}
{}{Website: \href{\@website}{\@website}\\}
\end{minipage}
\end{minipage}

As you may notice, there are three embedded minipages here (the main minipage and two sub pages).  The main minipage is set to span the entire width of the text.  However, the first embedded minipage is only 114 pt in width (about 1.6 inches).  Within this first box, I place the cvphoto, resized to a width of 100 pt:

\resizebox*{100pt}{!}
{\includegraphics{\@cvimage}}

Note: The {!} argument in \resizebox allows the image to stretch proportionally in the vertical direction.

The second minipage is allowed to take up the rest of the paper width and includes the conditional formatting for the contact details.

Conclusion

Through the use of custom formatting, packages and macros, I’ve created a document that is substantially different from the foundation class (article.cls).  Despite those differences, nearly every major customization was made using simple LaTeX macros which many users will be familiar with.  Further, because it is built on a solid foundation, the ability to use other add-on packages is retained.

Extending an existing document class does not need to be difficult.  It is possible to use many of the commands used for writing a document.  Additionally, the modifications could be packaged as a style (.sty) and used to enhance any content that I might write in the future.

This flexibility is one of the reasons why LaTeX is such a good candidate for the typesetting of scientific and technical material.  It’s also why LaTeX is a good candidate for creating design heavy documents, such as a curiculum vitae.

______________________________________________________

Acknowledgements and Further Reading

Additional information on the structure of document classes can be found in the article “Rolling your own Document Class: Using LaTeX to keep away from the Dark Side” by Peter Flynn of Silmaril Consultants.

A second article called “How to develop your own document class – our experience” describes additional techniques for documents that might have non-standard formatting.  It outlines several common mistakes and ways to get avoid them.

This article is part 2 of a four part series.  Part 1 introduces the xetexCV document class and describes its use.  Part 3 shows how to generate a publications list through the use of a .bib database and custom BibTeX style.  Part 4 describes how to use the document class and a corresponding layout file with LyX.

Similar Posts:

• Typeset Your Curriculum Vitae – Part 1: The xetexCV Document Class
• Customizing LyX: Character Styles and the LyX Local Layout
• Typeset Your Curriculum Vitae – Part 3: Automatically Generate a List of Publications
• Learning IronPython – Part 3 – A Beautiful Start
• Creating the Perfect Writing Tool: A Proposal

Tags: Curiculum Vitae,LaTeX,Typesetting
Categories: Computer, Writing and Literature, rapidBOOKS
2 Comments »