Since TeX was Donald Knuth’s fix to the ugly digital typesetting of his books, The Art of Computer Programming, it seems relevant that we take a bit of a pause from the intricacies of TeX to look at readability of the text we are producing with this system. The last task in Knuth’s The TeXbook simply states, ‘Go forth now and create masterpieces of the publishing art!’, but like Stefan A. Revets remarks in the Octavo package manual, then Knuth probably did not intend that everything published with TeX was supposed to ‘shriek “TeX” from every page’. So why is it that almost every TeX-based publication is so easy to identify and for many, so easy to dislike. Apart from the standard document layout that we have already covered how to customise with memoir in earlier posts, this what we will try to take a look at today.

Typefaces come in all sorts of varieties, light, heavy, condensed, wide, and in as many standard configurations that there are typefaces. The norm for legible typefaces used to be that the width of the English lower-case letters, a to z, would take up approximately 13 em. Narrower than this can be good for shorter lines and for saving on paper, wider than this gives more whiteness on the page, which can be used to provide a greater sense of space. Like we saw in the post on microtypography, then a uniform ‘grayness’ of the page can help to improve the aesthetics of your text. With too narrow fonts the blackness of the page will usually take an overhand, and too wide fonts, the whiteness will be too much. So we would like to find the ‘just right’ balance, which is typefaces where the lower-case alphabet takes up about 13 em of space when set. Of course, this being an art-related topic, we should note that the rules are here to be broken, so if something works better for you or for something you are producing, by all means, go ahead.

So, for these purposes, let us take a look at a number of standard available LaTeX fonts, and a couple free, but non-standard fonts, and how they measure up against this 13 em measurement.

‘Nimbus Roman No9’ is an adaption of the world famous ‘Times New Roman’, although this version is a bit wider than the original. You can use this typeface by issuing the command \usepackage{times}. In order to understand the use of ‘Times New Roman’, it is necessary to understand its origin. In 1931, ‘The Times’ commissioned a new typeface that should be legible and economise space, because the less space articles can be printed in while remaining legible, the less will ‘The Times’ have to pay in publishing costs (since you could run fewer pages or more advertisements). ‘The Times’ has since then had several other typefaces created to succeed ‘Times New Roman’. ‘Times New Roman’ has also served much popular use since Microsoft has been including it as the default serif typeface in all versions of Windows since Windows 3.1. It should be remembered, though, that the typeface is created to save money while maintaining legibility, not for optimal legibility, which we may also see in the figure above as it is the narrowest of the ‘normal’ serif typefaces in use in the LaTeX world.

‘Computer Modern’ is the typeface that Donald Knuth created together with TeX. The version depicted in the figure above is from the cm-super package that contains Type1 outlines of the ‘Computer Modern’ font family, rather than the original METAFONT definitions from Knuth. ‘Computer Modern’ is the standard typeface in use in any TeX or LaTeX document, it is the hallmark of the thing that shrieks ‘TeX’. The glyphs are thin and the contrast of the font is rather low for a serif typeface, in effect causing the typeface to feel ‘too light’. There are, thus, other factors than merely the ‘13 em width’ we are currently looking at, that influences the quality of a typeface. For the mere purpose of not shrieking TeX, we will recommend the use of another typeface for texts.

‘Gentium’ is a relative new-comer to the typeface scene of freely available typefaces, and is designed by the award-winning type designer Victor Gaultney. It has been designed for good legibility, to be reasonably compact, attractive, and freely available. It is also intended to embrace the Latin alphabet world with all its plethora of diacritics and provide a common OpenType font that can be used in all these countries. It is not trivial to get this font to work with LaTeX, but it is a reasonably nice alternative to the free fonts that are available in the LaTeX distributions and the non-free ones that come with a bunch of strings attached (like ‘URW Garamond No8’ below). Its compactness is almost neglible and does not cause legibility to suffer, it is only a few points short of the 13 em width.

‘URW Garamond No8’ is an adaption of 16th century type cutter Claude Garamond’s typeface. The ‘Garamond’ is one of the most often-used type families when it comes to professional works, owing in particular to Slimbach’s beautiful digitalisation in Adobe’s Garamond Pro typeface. URW’s adaption of ‘Garamond’ fits exactly within the 13 em measure, but the different adaptions vary somewhat to both sides. Unlike the previous three fonts we have looked at, ‘URW Garamond No8’ is not free and does not come with LaTeX distributions by default. It can, however, be downloaded from CTAN under the non-free fonts. Be sure to investigate the license that accompanies it for whether your use is applicable. In order to use this font in LaTeX, after it has been installed, you can add the following code to your preamble: \renewcommand{\rmdefault}{ugm}.

The last typeface we will look at is, ‘URW Palladio L Roman’, which is an adaption of Hermann Zapf’s Palatino. It is a somewhat wider typeface than the rest that we have looked at, which in some opinions may improve legibility. Like ‘Garamond’ and ‘Times New Roman’, ‘Palatino’ is one of the most often used typefaces, probably also owing to the fact that Microsoft also provides it since Windows 2000. LaTeX provides this together with a correspondingly designed maths typeface in the package mathpazo. There are several versions of Palladio available in LaTeX, including versions with smallcaps and old-style figures (both absent from ‘URW Garamond No8’, and the latter unavailable in ‘Gentium’).

So if we want to save a lot of space while maintaining legibility, we should probably be using ‘Nimbus Roman No9’ (or if you have professional typefaces one of the ‘Times New Roman’ successors like ‘Times Modern’), if we want good general-purpose text with a classical feel to it, we should probably be using ‘Gentium’ or ‘Garamond’ (or ‘Plantin’, or… there are really many great serif typefaces in this category, but most of them are fairly expensive, unfortunately), and if we want a lighter feel to our text while consuming more space, there is ‘Palladio’ (or many other more recent typefaces).

As I hinted to in the discussion of ‘Computer Modern’ there are several more measures for the fitness of a typeface for a particular purpose, but being an artform in itself, there are so many varying and opposing opinions that only very vague guidelines exist. So instead of trying to uncover all of these, let us do like the rest of the crowd seems to do and let us rely on our subjectivity and take a look at a bit of text typeset with each of these typefaces.

Here we see that the wider ‘Computer Modern Roman’ takes up a line more for the paragraph excerpt; this will run up in cost when you publish, but the cost of the narrower font is of course it is not as pleasant to read most of the time. However, we can also see that ‘Computer Modern Roman’ feels a lot more light than ‘Nimbus Roman No9’, not making it particularly ideal either for typesetting a paper, let alone a book. So let us continue and take a look at some of the more traditional book typefaces.

Here, ‘URW Garamond No8’, at least, has proven its worth by surviving from the 16th century until now, in widespread use. However, both typefaces present strongly and have each their distinctive style while maintaining familiar, pleasant and good readability. When you want to choose a typeface for publishing an article, book, or the like, then picking a typeface that falls in line with either of these two will most likely be a good bet.

There is a rather stark contrast between the narrow ‘Nimbus Roman No9’ and the wide ‘URW Palladio L Roman’. To some, the wider ‘Palatino’ may be too wide, but if you need to provide your pages with a lighter feel (without increasing the line spacing), then it and other wider typefaces may prove very useful. In the end, though, the typeface you choose will be a matter of personal preferences and what you think look good. But do not use ‘Comic Sans’ for anything serious, ever.

Now, with that out of the way, I will not go long into a discussion on the merits of using sans-serif typefaces for the main text. Several psychologists (a bunch of them working for Microsoft) has done various studies that indicate that there is no discernible difference in reading speeds or preferences between the two. However, for the sake of tradition and the beauty of the serifs, I suggest we keep using serif typefaces for main text. There is, however, another thing that is relevant to look at, namely the length of lines. One of the LaTeX packages that sees widespread use in a lot of Europe is the a4wide package. For those who are uninitiated into this monstrosity, it makes the margins a lot smaller than the LaTeX default. Let us look at the difference between standard and wide margins:

So what is the difference here, other than saving paper by printing more. It is the distance that our eyes have to travel when we reach the end of one line and skip to the beginning of the next line. The longer the lines are, the easier it is for the eye to get lost and you have to backtrack and pick up at the right spot again, either because you reread the same line again or because you skip a line too far ahead. So unless there is a really good reason for the much smaller margins, do not do that.

This is about as far as we will go into the intricacies of typefaces and layout today, there is much, much more to expound on the topic, though, so I might return to it some day.

To most people, this situation is, of course, untenable, and since there usually are rules from each publisher that describe how references should be written down, it is almost apparent that you should be able to use some kind of software that automates this process for you. In fact, there are many software packages doing exactly this, with EndNote and RefWorks being some of the more well-known commercial packages if you are a Microsoft Word user. Fortunately, we are not! So for us the main contender to do bibliographies with LaTeX is BibTeX (there are several other tools, but BibTeX is the most often-used tool for this purpose, so we will focus on that).

Before we take a look at BibTeX, let us, for good measure and for those not too corrupted by academia yet, do a quickly summarise some of the different ways to create a bibliography and the corresponding ways to cite this work inside the text. Our example work will be the book Design Patterns: Elements of Reusable Object-Oriented Software by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides, published by Addison-Wesley in 1995 with an ISBN 0-201-63361-2. Each pair of lines in the image below will show how it is (or can be) referenced inside the text, and the other line will show how it is listed in the bibliography—the list at the end of your work that gives a thorough list of the works you have cited in your text.

And there are many, many, many more variants than these to choose from, but it gets a bit tiresome to write them all out. To the first of these (the Chicago Manual of Style styled citation) there is of course also an alternative contextual representation that goes like this: ‘Gamma, Helm, Johnson, and Vlissides (1995)’ so that you can use it as part of a normal sentence. And there are more rules governing these things when you add more information to the citation, like a page number/range or a chapter. Verily it is much better to let a program take care of all these technicalities than have to remember them yourself.

Before we move on to BibTeX and how it works, it might be prudent to take a quick look at how we can create bibliographies manually in LaTeX, as BibTeX actually just automates creating bibliographies for us.

The environment for a bibliography in LaTeX is simply called thebibliography. It works very much like an enumerate environment, but with a few more bells and whistles and some slightly different command names. To see how it works, let us just look at a full example up-front:

\begin{thebibliography}{1}

\bibitem{DP} Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides.
  \textit{Design Patterns: Elements of Reusable Object-Oriented Software}.
  Addison-Wesley, 1995.
\end{thebibliography}

So let us cover this one step at a time. The {1} after the thebibliography is the visual key of the widest element in the bibliography list. Since we only have a single entry and we’re creating a bibliography after the plain LaTeX style above, this is 1. If we were using the alpha style, it would have been {GHJV95} instead. Instead of \item we have \bibitem and it takes a key that you will be using to refer to that work when you cite something. Citing is done with the \cite command, so to cite the Design Patterns book, you would write \cite{DP}. The rest of the text is merely a standard list text and nothing fancy happens to that. We will cover the \cite command in more detail later on.

With this in mind, it is time to move on to BibTeX. BibTeX uses a bibliography file that is provided by the user with a .bib suffix, a style file that ends in a .bst suffix, this file is typically chosen from the large set of existing style files, and finally the actual BibTeX program that understands the .bib file format and the .bst file format and processes them together to create a .bbl file. On a subsequent run, LaTeX reads in the .bbl file, which contains a finished thebibliography environment. This may seem convoluted, but remember that TeX is an old program from long before we measured system resources in gigabytes, so this was the only really tenable solution for integrating new tools back then.

Let us start at the .bib file format and take a look at how this is organised.

@worktype{reference-key,
  key_1 = value_1,
  key_2 = value_2,
  ...
  key_n = value_n
}

...

Here the worktype specifies the type of work, for example article, phdthesis, inproceedings, and many other types. It is the .bst file that defines what worktypes are supported. Likewise the keys are dependent on the worktype and are also defined by the .bst file. Normally a lot of these worktypes and keys will be the same across different .bst files, so it is quite normal that all of them has support for an article and support for keys such as author, title, publisher, year, month, isbn, etc. The values are, on the other hand, are a lot less well-defined and there are several ways to write them. For our initial purposes, though, it will most likely be sufficient to write values like this: {value test}. So to get a feeling of how this all will work out for our book reference above, let us write it up in BibTeX:

@book{DP,
  author = {Erich Gamma and Richard Helm and Ralph Johnson and John Vlissides},
  title = {Design Patterns: Elements of Reusable Object-Oriented Software},
  publisher = {Addison-Wesley},
  year = {1995},
  isbn = {0-201-63361-2}
}

Authors here are merely delimited with the keyword and, which allows BibTeX to automatically figure out the things it needs about the authors. Do note that BibTeX has some weaknesses in guessing where to break some names, like Domonique Galouzeau de Villepin, whose first name is Dominique and last name is Galouzeau de Villepin. If entered as ‘Dominique Galouzeau de Villepin’ in BibTeX as-is, it would see ‘Dominique Galouzeau’ as first name, ‘de’ as a delimiter for the last name and ‘Villepin’ as the last name. To disambiguate this you can also enter names in BibTeX like this: ‘Galouzeau de Villepin, Dominique’. For many more details on the finer trickeries of BibTeX you may want to refer to Xavier Décoret’s excellent summary.

For now, let us return to the problem at hand: using this .bib file with our text in LaTeX. As before, DP is the key of the work, so inside our LaTeX text we can just refer to the work using the command \cite{DP}. So what do we use to hook us up to the .bib and .bst files? This is, in fact, very easy, it just requires two commands:

\bibliographystyle{plain}
\bibliography{myfile}

So the argument for \bibliographystyle is the .bst file without the .bst suffix, and the argument for \bibliography is the name of your .bib file, likewise without the .bib suffix. If we presume that you use pdflatex to compile your LaTeX documents to PDF, this is a typical run of what you would do when you use BibTeX:

1. pdflatex mytexfile.tex

   This generates mytexfile.aux with special bibliography commands that BibTeX will process.

2. bibtex mytexfile

   This is done without any suffix to mytexfile. What it does is that it reads the generated .aux file for bibliography commands in order to figure out what .bst and .bib files to use. Once it finds these, it generates a .bbl file with a finished thebibliography environment.

3. pdflatex mytexfile.tex

   This includes the contents of the .bbl file at the location where you have the \bibliography command and writes citation location information to the .aux file.

4. pdflatex mytexfile.tex

   Like the previous step, except now the citation location informations are available in the .aux file, so the \cite commands can be translated to an actual reference with the relevant text.

In some rarer cases you may need another run of pdflatex to sort out some kinds of references, but the TeX engine will generally let you know if it needs to be run again to resolve references. There is, of course, no real need to understand all these technicalities. In practice you will just run pdflatex once, then bibtex and then pdflatex a number of times until LaTeX stops complaining about references. The important thing is that you can now just replace \bibliographystyle{plain} with \bibliographystyle{alpha} if that is what suits your fancy, and run pdflatex and bibtex again as above. Do note that in some cases you may need to delete the .aux and .bbl files in order to be able to compile again after you have changed to a new bibliography style, as some bibliography styles use special-purpose commands that may be removed by your changes. This will, however, usually not be a problem in practice unless you vacillate endlessly between bibliography styles, but who does that, really? (The author looks around suspiciously).

Citing works is fairly easy by just doing \cite{work}, but what if we want to indicate that we are only really referencing a single page or chapter in the work. We could of course write something like: ‘See chapter 1 in \cite{work}’, but unfortunately for us, there are also guidelines governing how to write these things in relations to citations by the different publishers, so we will need to come up with another approach. Fortunately, \cite takes an optional argument that tells us exactly this: \cite[info]{work}. So, for instance, referring to page 120 of Design Patterns would be written like this: \cite[p.~120]{DP}. Note the non-breaking space, ~, which makes sure that there isn’t a line break between the ‘p.’ and the ‘120’, which would look fairly ugly in most cases and disrupt the general flow of reading. It is also customary to place a non-breaking space before the \cite command if it isn’t the first thing in a sentence, e.g.: ‘… as described in~\cite[p.~120]{DP}’.

In order to get really going with using BibTeX now, you only really need to know the standard worktypes and keys. Fortunately, Wikipedia provides a nice, if short, overview of them here.

That’s basically what there is to using BibTeX for most purposes. Hopefully I will find the time to write something on creating custom .bst files later on, as those are fairly interesting as well.

While most people I know who read this blog use LaTeX predominantly, most of us make acquaintance with the mainstream text tools, OpenOffice and Word. They create equally shoddy text (I guess it is their prerogative given that they are text processors rather than type setting programs, but it is still depressing). Still, looking at the output from one of these programs may serve as an (extremely good) motivating factor for considering LaTeX. The image below illustrates a standard text in OpenOffice, without hyphenation (with hyphenation did not change the result radically).

Looking at the interword spaces on line three, we see that they’re radically different from the spaces in the last line, for instance. This gives a very uneven reading and is not particularly nice looking at any rate. If we furthermore look down along the right margin, we see that, even though we have selected a justified text formatting, that the visual appearance of the text against the margin is not even. For instance, the ‘y’ and comma seem to be futher to the left than the ‘d’ and ‘r’. Furthermore, the fourth last line seem to be shorter than the others when you glance down along the right margin. This detracts from the aesthetic qualities of the text as well.

We are not going to be able to crank anything much more useful out of OpenOffice, so let us switch to our favourite typesetting language, LaTeX, and see how it looks there. This gives us what we can see in the following figure (margins adjusted to fit better with the OpenOffice defaults – normally margins are larger in LaTeX for better aesthetic value).

This still gives us a somewhat jagged appearance in the right margin. What we want to do is to let some characters, in particularly punctuation, fall into the margin, causing more uniform lines to appear (visually, not mathematically). This is called character protrusion, or margin kerning.

Pdftex 1.40 and newer supports two levels of character protrusion: level 1 that does not take line breaking into account, and level 2 that does. The details of this is easier to see if we are writing a two-column page. Below we see level 1 in the left column and level 2 in the right column. The interword spacing is clearly superior at level 2. In particular, this is illustrated in line 4 where there’s a much larger space in the left column after the full stop.

Looking at line 15 in the right column, we do, however, see that spacing is not entirely even, as there is a larger space after the full stop, at the text starting ‘At first I could not believe my’. These ‘artifacts’ happen when a proper line breaking cannot be made (breaking ‘eyes’ would be unnatural), and thus the line is padded with a bit of extra space, here after a full stop since we are more forgiving about extra spaces here as there is already some form of pause.

Some of the lines are spaced too tightly in my opinion in the right column above, example the line reading ‘my very feelings changed to repulsion and ter-’ is pushed too tightly together, particular the change from ‘feelings’ to ‘changed’ seem too close. As a way to improve the spacing we can turn on font expansion. What this feature does is to use a more narrow version of a font when there is little space, and a wider version of a font when there is ‘too much’ space. Since this change is, for the most part, automatically generated from the original font, great caution should be applied as it may distort the original font shapes, however, with the defaults, all this happens to a maximum of a three per cent change from the original shape, making it almost invisible to the naked eye. The results below are, however, fairly compelling. The left column is the same as the right column above, and the right column is with font expansion turned on at full level.

This is miles from the look of OpenOffice that we saw at the beginning of this post. Indeed, returning to default margin size in full width, we can see the text typeset below with full character protrusion and font expansion.

These things are, of course, just one among many of microtypographic finnesses that can be controlled in later versions of pdftex. What we have not looked at here is, of course, how you can use these things. Fortunately there is a nice package that wraps up a lot of these issues: microtype. Using it is exceptionally easy:

\usepackage{microtype}

This will enable both character protrusion and font expansion. For more advanced manipulative changes, you can refer to microtype’s documentation. (There is even a way to make it look like it was created in Word or OpenOffice!)

Thanks for reading.

So, if you have some form of functionality that you use repeatedly in different projects and would like to abstract it away in a separate package that you can easily use in your other projects, a package is what you are looking for. The basis of creating a package is to pick a filename, say, mypackage.sty (on some systems you may have to keep to the 8.3 filename standard, so it may be prudent to name your packages to fit inside that, but it is not a requirement).

Every package starts with either the first or both of the following lines:

\ProvidesPackage{mypackage}[2006/05/01 version 1.0 by Someone]
\NeedsTeXFormat{LaTeX2e}

\ProvidesPackage‘s name is required to be the same as the file of the package, and \NeedsTeXFormat specifies what document format is required in order to use the package (if it is using functionality specific to a certain format). Here, LaTeX2e is what most of us use when we write documents, but plenty of others exist as well.

Packages can, of course, also depend on other packages, but unlike in the main document, we do not use \usepackage to include these, rather, a separate command, \RequirePackage exist instead that otherwise does the same thing (more or less). So if we were to require some higher level constructs for directing command flow using the ifthen package, we could use the following line of code inside our package:

\RequirePackage{ifthen}

With some packages it is also possible to pass them options, for instance for the babel package that takes care of renaming various commands to a specific language:

\usepackage[british,french]{babel}

These options dictate that we should load both the british and french modules and that we want to pre-select french (as that is the last option) for the language to write in. Likewise it might be relevant for your package to provide a number of options that can be used to control overall functionality of the package or pre-define certain environments or commands. Declaring a package option is done using the \DeclareOption command. So if we were to declare a theorem option, it might look like this:

\DeclareOption{theorem}{%
  % code goes here
}

And when we subsequently use the package in a document we can write:

\usepackage[theorem]{mypackage}

All the options aren’t executed at the point of declaration though, it requires a separate command, \ProcessOptions that can occur anywhere in the package code (though naturally after the \DeclareOption and before the end of the package). A reason to place it later in the document than immediately after your declared options could be that some options redefine commands that are introduced later on in the package, for instance.

Most of the remaining code in a package is just a collection of introducing new commands and environments. There is one thing that is worthy of notice, though, namely that command names that are internal to packages are typically given a @-sign inside them, as these are not directly available in normal documents, as we have seen before. Inside a package the @-sign behaves as a letter and you do not need to surround all such uses with \makeatletter and \makeatother. Also, remember that commands must be unique, there are no overloading, so try to pick names that don’t conflict with other packages. Of course, given the sheer number of packages in existence, this may prove rather difficult.

This is basically all there is to creating packages. The rest is pretty much up to what you need to abstract for kinds of behaviour. Looking back at the code we have seen in this blog, we might, for instance, pick out the layout of a book to package. That way we can reuse this layout at a later time, merely by including a package. And that is, in short, the basic idea of packages.

We can, for instance, imagine that we are writing a document where all figures are centered before they are drawn. In many cases this is accomplished by people using roughly the following code:

\begin{figure}
  \begin{center}
    % figure code goes here
  \end{center}
  \caption{...}
  \label{...}

\end{figure}

But with this, we have mixed together structure and layout, so let us drag the author out back and shoot him before it is too late. Rather, what we would want to do is somehow create a new environment, say myfigure, that takes care of centering the contents. In order to introduce a new environment, we may use the \newenvironment command, which functions very much like \newcommand except that it takes two arguments: what happens before the content, and what happens after the content. So using this knowledge, we can wrap up the centering code:

\newenvironment{myfigure}{
  \begin{figure}\begin{center}
}{
  \end{center}\end{figure}
}

Do note that the order of appearance of the figure and center environments matter. If you try to end a figure environment with a center environment, LaTeX will throw errors your way. With our brand new environment, we can now write our figure using our own environment:

\begin{myfigure}
  % figure code goes here
  \caption{...}
  \label{...}
\end{myfigure}

Thus, we nicely separate our layout and our structure. Normally it would seem prudent to find a better name than myfigure, one that better describes the purpose of the structural component, but sometimes no nifty names come to mind.

Like with commands, environments can also be given a number of parameters. These parameters are, however, only available in the ‘before content’ code. If we often customise our itemize environments to use different kinds or itemisation symbols, we could create an environment that lets us specify these easily:

\makeatletter
\newenvironment{myitemize}[1]{
  \begin{itemize}
    \expandafter\renewcommand\expandafter{
      \csname labelitem\romannumeral\the\@itemdepth\endcsname}{#1}
}{
  \end{itemize}
}

\makeatother

Now we can use this to change the item symbol like this:

\begin{myitemize}{$\star$}
  \item Test
\end{myitemize}

And there would be a nice little star to the left of ‘Test’.

This is basically what there is to environments at the surface. This leaves the technical details of how they are actually implemented (as they are not a part of plain TeX). In fact, \newenvironment is just a cover around creating two different commands: \environmentname and \endenvironmentname. Here the parameters are passed to the \environmentname exclusively, as that is typically where they are needed. Now, invoking \begin{environmentname} is not entirely the same as invoking \environmentname as \begin also sets up some other variables and starts a new group (scope in regular programming).

The primary goal of using environments, though, is to separate the content from the layout. If you keep this in mind when creating documents it will be extremely easy to tweak the layout without having to go through the entire document every time you wish to change all your figures to be centered, for instance.

While many premade solutions exist, there will invariably be times where you need something custom made. Today we will look at the basics of creating new commands in LaTeX. Previous familiarity with programming will be a benefit, but, I hope, not an absolute requirement.

A command in LaTeX can accomplish pretty much anything (for the really interested, LaTeX is Turing complete), but for our purposes it is mostly used to abstract away formatting or change the values of counters or lengths. As such, familiar things in LaTeX such as \section, \usepackage and the like are all commands that abstract some behaviour. To familiarise ourselves with how to introduce commands, we will look at a fictional problem: We are writing a larger document containing a lot of acronyms, and we’d like to be able to standardise on the typography for printing acronyms, and ensure that the first time an acronym is used its full definition is written out.

Introducting a command in LaTeX is done using the \newcommand command. Its full definition is on the following form:

\newcommand{command-name}[number-of-arguments]{body}

Inside the body, the arguments can be referenced by typing #n where n is the n’th argument to the command. With this in mind, let us create an \ac command for typesetting acronyms.

\newcommand{\ac}[1]{\textbf{#1}}

What this does it create a command, \ac that takes one argument, and it expands to boldfacing the argument in the text. If you find using bold type for typesetting acronyms bad style, there is, fortunately, a single place to correct the formatting with this command, rather than having to go through the entire document and correct every single acronym.

While this lays the foundation for the command, what we would really like is to be able to define a number of acronyms, i.e. both their short forms and their expanded forms, and have LaTeX make sure that we have always presented the long form of an acronym the first time we use it. This is a good deal tricker, as we will have to introduce commands that are constructed dynamically. Basically we would like to be able to define an acronym like: \acronym{ETA}{Expected Time of Arrival}, and when we use it the first time have it print something like: ETA (Expected Time of Arrival) and just ETA at subsequent occurrances in the text.

So at the core we have something like:

\newcommand{\acronym}[2]{
}

And we need to fill something into the body. If we just do something like this:

\newcommand{\acronym}[2]{
  \newcommand{\acronym#1}{#2}
}

Then we’re told that the command \acronym already exists. So we need some way of splicing acronym and our command together to form a whole command. This can be done with the \csname and \endcsname constructs, like this:

\newcommand{\acronym}[2]{
  \newcommand{\csname acronym#1\endcsname}{#2}
}

However, now this tells us that the \csname command is already defined. So we need some way to indicate to LaTeX that it should resolve and concatenate acronym#1 first, then invoke \csname and finally call \newcommand. We can accomplish this using the fairly low-level command \expandafter. This command does, when placed in front of a command indicate that what comes after it should be expanded before we call the command. So we have to jump over \newcommand and \csname, so we will need two uses of \expandafter, like this:

\newcommand{\acronym}[2]{
  \expandafter\newcommand\expandafter{\csname acronym#1\endcsname}{#2}
}

Using this with our call to \acronym{ETA}{Expected Time of Arrival} creates a new command, \acronymETA, which we can call normally, and this command will print ‘Expected Time of Arrival’.

The next thing we need to accomplish is to only print this expanded text the first time we use the acronym. To aid us slightly, we use the ifthen package’s commands \newboolean and \setboolean as follows:

\newcommand{\acronym}[2]{
  \newboolean{acronym#1}
  \setboolean{acronym#1}{true}
  \expandafter\newcommand\expandafter{\csname acronym#1\endcsname}{#2}
}

Here the \newboolean figures out that the name of the boolean should be expanded before the creation of a new boolean on its own, so we don’t have to place manual \expandafter commands throughout the code.

This means that we have everything in place to create a new command that prints the actual acronym:

\newcommand{\ac}[1]{
  \ifthenelse{\boolean{acronym#1}}
  {#1 (\csname acronym#1\endcsname)
    \setboolean{acronym#1}{false}}
  {#1}
}

Using this as follows:

The \ac{ETA} is now 5 minutes. The \ac{ETA} is now 4 minutes.

Would result in the following: ‘The ETA (Expected Time of Arrival) is now 5 minutes. The ETA is now 4 minutes.’ This is, of course, all great and well, but recreating all of \ac can be a bit taxing, if we want to change the formatting of parts of the word. So let us create two more commands to typeset the acronym with and without the expanded text:

\newcommand{\printlongacronym}[2]{#1 (#2)}
\newcommand{\printshortacronym}[1]{#1}

And we change the definition of \ac to use these as follows:

\newcommand{\ac}[1]{
  \ifthenelse{\boolean{acronym#1}}
  {\printlongacronym{#1}{\csname acronym#1\endcsname}
    \setboolean{acronym#1}{false}}
  {\printshortacronym{#1}}
}

This now lets us change the formatting of acronyms merely by changing the definition of \printlongacronym and \printshortacronym, thus abstracting away all the technical issues of changing boolean values and whatnot from the end user. The user just needs to focus on how to adapt these two commands for his formatting needs. And, if these things are wrapped away in a package, the user can use \renewcommand to change the meaning of the commands.

This is basically all there is to commands: give it a name, some arguments and do something in the body. Even a simple command such as typesetting some code inline in the text might be a boon if you have to go over the document at a later time to fix up the layout.

Advanced commands and TeXing

Now that we have our fancy \ac function, it is time to consider what happens if we write something like: ‘Some of the \ac{CIA}'s archives have recently been opened up.’ The outcome could be one of two things, depending on whether this is the first use of the CIA acronym or not, namely:

Some of the CIA’s archives have recently been opened up.

or

Some of the CIA (Central Intelligence Agency)’s archives have recently been opened up.

In the latter case, the possessive should still have been attached to CIA rather than the parenthesis. One way to cope with this is to use TeX’s mechanism for defining functions and in particular functions with optional parameters. This is done using the TeX function \def. If we were to code a command with optional parameters (keeping in mind that optional parameters are typically given in []‘s as the first part of a command, in TeX), it would look something like this:

\def\acopt[#1]#2{
 \ifthenelse{\boolean{acronym#1}}
  {\printlongacronym{#2#1}{\csname acronym#2\endcsname}
    \setboolean{acronym#2}{false}}
  {\printshortacronym{#2#1}}
}

This basically means we can call it like this: \acopt['s]{CIA} and we’d get:

CIA’s (Central Intelligence Agency)

if this was the first use of the acronym. Now, we could just call \acopt whenever we need to add some fancy possessive or what have you to an acronym. However, we’d like to be able to extend \ac so that we only have to type one command, and that’ll figure out whether to call \acopt sensibly. In order to do this, we must use a built-in command \@ifnextchar. This command is primarily meant to be used from inside a package, but we can use it in normal document code by surrounding it by the two commands \makeatletter and \makeatother. These two commands are necessary, as @ isn’t treated as a normal letter in LaTeX commands and thus we’re required to change @’s code group (if you’re getting confused now, don’t worry, you can just use the two commands around the location where you need to use a command with an @ in it and worry about the details at some later time). With this we can define \ac like this:

\makeatletter
\def\ac{\@ifnextchar[\acopt\acnoopt}
\makeatother

What this does it it queries the token stream (the next bunch of characters in the document, for a very loosely hand-waved definition) and if the next character is a left-bracket we call \acopt, or otherwise we call \acnoopt, the latter of which we can define very easily:

\def\acnoopt#1{\acopt[]{#1}}

With this we can now both write \ac['s]{CIA} and \ac{CIA} and everything will sort itself out nicely.

On the horison

Apart from these few commands we’ve seen, it is also possible to define commands globally using \gdef (commands are otherwise local to the environment they’re declared in), redefine LaTeX commands using \renewcommand, create commands that cannot include paragraph changes using \newcommand* and many, many others. However, the command construction you’ve seen above goes for pretty much all the other commands as well, so presuming you’ve gleaned some meaning from my ramblings, you should be able to get somewhere fast no matter the situation.

Much like with the last four blog posts, we will take a look at styling the book in the same order, namely: chapter, table of contents, sections, and footers/headers. Remembering the plain chapter style, we have something like this, for our book:

As I’ve written before: while this is certainly acceptable, it’s not really too unique of fascinating, so let us think up a way to get it to feel more 1920′s and horror-ish. The last part is of course hard to quantify unless you pick some cheesy font that’s impossible to read, so let’s just stick to making it look a bit like a book on good literature. We will try to accomplish this by just writing the chapter number as a word (one, two, three, etc.), and omit the ‘Chapter’ prefix, centered, and put the chapter title in italics, also centered. We can do that with the following code:

\makechapterstyle{bookstyle}{ % Yes it's a very imaginative name
  \setlength{\beforechapskip}{0em}
  \setlength{\midchapskip}{1em}
  \renewcommand{\chapnumfont}{\normalfont\large\bfseries\fscshape}
  \renewcommand{\chaptitlefont}{\normalfont\huge\bfseries\itshape}
  \renewcommand{\printchaptername}{}
  \renewcommand{\printchapternum}{%

    \centering\chapnumfont\numtoname{\thechapter}
  }
  \renewcommand{\printchaptertitle}[1]{\centering\chaptitlefont ##1}
}
\chapterstyle{bookstyle}

This verily will take a bit further description. The \fscshape command introduces fake small-caps, and its existence depends on what font package you may or may not be using. If you have a commercial grade font, or one of the built-in fonts, then you will want to use \scshape instead. The \fscshape I am using here is provided by the mathdesign package together with the URW Garamond typeface. The only other surprise here should be the \numtoname command that is provided by memoir, and this command converts a number into a corresponding name, for instance \numtoname{13} will be turned into ‘thirteen’.

With this modest change in place, our chapter page suddenly looks like this:

This seems a tad more classic literature-ish to me, at least. So we will chalk one up for success on the chapter style. We could, of course, add something to the fancy and automatically insert an image for each chapter to complement the story, but since my freehand drawing skills aren’t what I’d like them to be, we shall skip this step for now.

With this out of the world, let us take a look at the existing table of contents:

From this we see that our book is divided in two parts: one for some of Lovecraft’s essays, and another for a very few of his poems. Since most of his essays aren’t subdivided, we probably have no need to indicate any of these, so let us turn them off and simplify the table of contents a bit. This may be done using:

\settocdepth{chapter}

Now, as long as you only want to tweak the distance between table of content entries, perhaps remove the dots on the line to the page numbers and move the page numbers a bit back and forth on the page, then everything is easy to do with memoir, but as soon as you move beyond that, things start to get really complicated, unfortunately. Not one to shy away from hard things, let us look at what it takes to center the part and draw lines around it and to typeset all the chapters in italics.

The first part is, unfortunately, rather hard. It requires us to override two different commands: \l@part and \partnumberline. The reason for this is two-fold. When we issue a \part command, the following is written to the .aux-file: \@writefile{toc}{\contentsline{part}{\partnumberline {I}Essays}{1}}, for instance, for part 1 called Essays. When this is going to be typeset then \l@part is called with the last two {}‘s above as arguments.

Using the tikz package that we have covered earlier to draw the lines about the part title, we will give the entire definition of the two commands here and then proceed with an explanation of the key points. The overall structure has been ‘borrowed’ from memoir.cls:

\newlength\sb@partheight

\renewcommand*{\l@part}[2]{%

        \ifnum \c@tocdepth > -2\relax
        \addpenalty{-\@highpenalty}%
        \addvspace{\cftbeforepartskip}%

        \begingroup{
        \centering
        \settoheight{\sb@partheight}{\Large\bfseries\MakeUppercase{#1}}
        \setlength{\sb@partheight}{.5\sb@partheight}
        \addtolength{\sb@partheight}{5pt}
        \begin{tikzpicture}
                \draw (0,0) node { \Large\bfseries\MakeUppercase{#1} };
                \draw (-.25\textwidth,\sb@partheight) -- (.25\textwidth,\sb@partheight);
                \draw (-.25\textwidth,-\sb@partheight) -- (.25\textwidth,-\sb@partheight);
        \end{tikzpicture}
        \par

        }\endgroup
        \fi
}

\renewcommand{\partnumberline}[1]{}

So, I guess this requires some explanation. The test on \c@tocdepth tests for whether the part should actually be displayed in the table of contents, and -2 is the code for the part in this instance. The \addpenalty command here makes TeX prefer to create a page break \emph{before} the part rather than after, so we don’t have a part title dangling alone at the bottom of a page, since that doesn’t look particularly nice. Then we use \begingroup to localise our changes so they don’t seep into the remaining document, and inside this group, we do a bit of slight trickery to compute how heigh the part title is, using the \settoheight. Then we calculate the half height and add some space, and this we use as a measurement in the following tikzpicture. The tikzpicture code should be familiar, as we have already seen it here. The redefinition of \partnumberline merely discards the part number as we aren’t really interested in that.

Our changes to the actual chapters are a lot easier to accomplish. Indeed, it only requires the following two lines:

\setlength{\cftbeforechapterskip}{.2em}
\renewcommand{\cftchapterfont}{\normalfont\small\itshape}

Taking all this together and using it with our book, we get the following table of contents for it:

This looks a good deal more like some of the older fictional works. So far so good. The next thing to turn pretty is the section titles. For the most part Lovecraft’s essays don’t have actual sections, but a few of them have sections named I, II, III, etc., and even fewer have actual section titles. One of the essays that do, is ‘Herbert West: Reanimator’.

First off, the numbering of the section doesn’t really make any sense in a fictional work as the title is usually sufficient in and of itself, so let’s do away with that. Apart from that, the standard section title layout looks quite decent. This is an extremely easy change then:

\maxsecnumdepth{chapter}
\setsecnumdepth{chapter}

And we get the following:

This leaves us with just the page headers and footers. As we can see below, and as I have written previously, the standard page headers are just ugly.

So, to rectify this, we will place the part title on the left page and the chapter title on the right page, both centered in the header, and we’ll place the page number on the page edge in the footer. And this is easily accomplished with the following code:

\makepagestyle{mybookstyle}
\makeoddhead{mybookstyle}{}{\itshape\rightmark}{}

\makeevenhead{mybookstyle}{}{\itshape\leftmark}{}
\makeoddfoot{mybookstyle}{}{}{\thepage}
\makeevenfoot{mybookstyle}{\thepage}{}{}
\makepsmarks{mybookstyle}{%

  \def\partmark##1{\markboth{##1}{}}
  \def\chaptermark##1{\markright{##1}}
  \def\sectionmark##1{}
}

\pagestyle{mybookstyle}

And presto, we get a much nicer output:

Throughout all these examples, we have used the @-sign repeatedly in commands. This is ok if you’re implementing this in a package file, but if you’re pasting them into your document’s preamble, the @ will not be interpreted as a character and a lot of errors will follow. To rectify this, surround the code in the preamble with the commands \makeatletter and \makeatother. This will make everything right. In a future post, I will try to talk about implementing packages to better hide this functionality away in a reusable component.

This concludes the styling example for today. If you’re in a need for a lot of sensible material to try out different stylings on, then I suggest that you head over to WikiSource or Project Gutenberg and grab some works that have entered the public domain and try to make your own compilation of them. And for your viewing pleasure, here is the book typeset with the style above.

For those of you with bad eye-sight, the chapter name and title is printed in all-caps. Absolutely ghastly. I mean, what is this, a tribute to AOL users?! We are definitely going to have to change something here indeed.

This is probably as good a time as any to bring this up. When we are typesetting a book it contains pages that will be to the left (verso pages) and on the right (recto pages). These two pages have different margins (try to open one of your books on your bookshelf and check for yourself), and furthermore books tend to have different things in the verso and recto headers and footers. Typically this means that the chapter number and title will be displayed on the verso page and the section number and title on the recto page (or part and chapter in other books, or something entirely different in yet other books).

These items (chapter number and title and section number and title) isn’t grabbed out of thin air in LaTeX, but is written into internal commands that can be read using the \leftmark and \rightmark commands (named for their use on left and right pages, obviously). Thus, the all-caps chapter title on the default page header has been written into the left mark here, so we will need to modify how the marks are stored.

The first step to creating a new page header and footer is to create a new page style using the \makepagestyle{name} command. So if we want to create a new page style where the header contains the page number and the chapter/section number (if any) and title, we would start out with the following:

\makepagestyle{mypagestyle}

To create a nice separation between the page number and the title—rather than typesetting them at opposite ends of the header—we will separate them with a vertical rule. Now the commands to modify the headers and footers of a page style are: \makeevenhead{style}{left}{center}{right}, \makeoddhead, \makeevenfoot, and \makeoddfoot. All with the same number of arguments. So, this means we can extend our page style as follows:

\makeevenhead{mypagestyle}{\thepage\hskip.5cm\vrule\hskip.5cm\leftmark}{}{}
\makeoddhead{mypagestyle}{}{}{\rightmark\hskip.5cm\vrule\hskip.5cm\thepage}

If we tack on a \pagestyle{mypagestyle} now, we will get some output like this:

Better than the standard, but it still feels partly like an AOL user tribute, what with all the caps and stuff. Before we fix this, it is time to discuss marks in a bit more detail.

Storing information to be read by \leftmark and \rightmark is accomplished using \markboth and \markright (no, there is no separate \markleft). And these two commands are meant to be invoked inside some specific commands that are in turn invoked from \chapter, \tableofcontents, etc. These commands include: \tocmark, \partmark, \chaptermark, and \sectionmark. There are, of course, more marks and you can generate more by creating new lists, so if you’re overriding marks you need to make sure to catch all of them appropriately.

Getting to the actual code now would be too easy. When we need to print the chapter number we have to remember that a book is divided into several ‘sections,’ namely the front matter (table of contents, lists, foreword, etc.), main matter (the actual book chapters), and back matter (bibliography, indices, etc.). Of these it is only customary to give the chapters in the main matter numbers in the heading.

Before we venture on, we also need to look at one of the ‘reserved’ symbols in LaTeX: @. This section is vague on purpose in order not to spend too much time on this detail. The @ is used for ‘reserved’ commands inside class-files and packages and its default ‘code’ to something that cannot be used. If, however, you’re in the need to using commands with @ in them you can use the command \makeatletter and then once you’re done return it to its original state with \makeatother. I will try to remember to visit this topic in more detail at some later time.

The use of @ becomes relevant when we need to test whether we’re in the main matter, because this is done (with memoir, remember @ means we’re overriding the internals of some package) using the \if@mainmatter where @mainmatter is a boolean value.

Now we’re finally ready to create our own marks! To recoup, we want to write the chapter mark on the verso page and the section mark on the recto page. This is done like this:

\makeatletter

\makepsmarks{mypagestyle}{
  \def\chaptermark##1{\markboth{%
    \ifnum \value{secnumdepth} < -1
      \if@mainmatter
        \chaptername\ \thechapter\ --- %
      \fi
    \fi
    ##1}{}}

  \def\sectionmark##1{\markright{%
    \ifnum \value{secnumdepth} < 0
      \thesection. \ %
    \fi
    ##1}}
}

\makeatother

The secnumdepth is a counter that contains information about what depth of sections should be numbered. Chapters is equal to secnumdepth 0 and sections to 1, hence the comparisons. Using this in our document we get the following output:

And for those with bad eye-sight, a courtesy close-up of the verso page:

Rather much of an improvement to the earlier AOL user tribute. There are, of course, plenty of other things we could want to do: add a ruler below the header, place the page number in the margin to make it easier to find a page when flipping through a book, or whatever else we might imagine. Even though I’ve carried this post on for quite a while, let us take a brief look at accomplishing this. First we create a page style very much like above:

\makepagestyle{myruledpagestyle}
\makeevenhead{myruledpagestyle}{\thepage}{}{\leftmark}
\makeoddhead{myruledpagestyle}{\rightmark}{}{\thepage}
\makeatletter
\makepsmarks{myruledpagestyle}{
  \def\chaptermark##1{\markboth{%
        \ifnum \value{secnumdepth} > -1
          \if@mainmatter
            \chaptername\ \thechapter\ --- %
          \fi
        \fi
        ##1}{}}
  \def\sectionmark##1{\markright{%
        \ifnum \value{secnumdepth} > 0
          \thesection. \ %
        \fi
        ##1}}
}
\makeatother

This is almost exactly the same as mypagestyle above, with the only change that we now place the page number and the mark on opposite sides of the header. This leaves us with the task of moving the page number into the margin and adding a ruler below the header. This is fairly easily accomplished:

\makerunningwidth{myruledpagestyle}{1.1\textwidth}
\makeheadposition{myruledpagestyle}{flushright}{flushleft}{flushright}{flushleft}
\makeheadrule{myruledpagestyle}{1.1\textwidth}{\normalrulethickness}

Here \makerunningwidth changes the width of the headers and footers of the specified style. As standard it’s \textwidth long, here we make it 1.1 times longer. \makeheadposition changes the placement of the header and footer. It has the form \makeheadposition{even-head-position}{odd-head-position}{even-foot-position}{odd-foot-position} where the different positions can be chosen between flushleft, center or flushright. This command is only useful, if the width of the page header is different from \textwidth. Finally we apply the actual rule, stating that it should be the width of the header and to use the normal rule thickness. This is, unless you have changed something, typically 0.4pt in LaTeX.

With all this trickery, this is what we get as output:

As an incidental note, the last style presented here is almost equivalent to the Ruled page style that comes with the memoir package (remember casing matters, there is both a ruled and Ruled page style). So if you want exactly this style, use that instead of defining all this yourself.

This fairly much concludes the styling the document series, but I am sure that I will, sooner or later, revisit how to style other parts of the document, or show even more involved styling solutions. But until then, let your imagination run free and bring some personal style to your documents.

While memoir is indeed very configurable, it doesn’t contain quite as an elaborate amount of commands to configure the sections, subsections and so forth. The primary command to customise with here is the \setXheadstyle where X can be sec, subsec, or subsubsec (and possibly more). So writing up the section style mentioned above would look like this:

\newcommand{\ruledsection}[1]{%
  \noindent%
  \parbox[t]{\textwidth}{%
    \hrule\vskip1em
    \sffamily\Large\bfseries #1\vskip1em%
    \hrule%
  }
}

\setsecheadstyle{\ruledsection}

Here we set the style to our custom command that will be called with the section number and title as an argument. This gives us the following output when compiled:

Since styling in this way is fairly simple, I will not go into painstriking detail of how to create more section styles. It is, though, useful to note that there are three more useful commands to know of: \setbeforeXskip, \setafterXskip, and \setXindent. The two first commands take lengths such as ‘-3.5ex plus -1ex minus -.2ex’ as arguments, and the last command just takes a regular length as an argument.

To see how these lengths can be used in practice, please refer to the memoir manual.