# The manual of the LaTeX “memoir” package

After a brief encounter with ConTeXt, and lots of fun preparing a typesetting style which a colleague at Bytemobile liked a lot (so much, in fact, that he actually used it to write a mini-guide sitting on my desk), I have now started reading about the memoir package of LaTeX.

I was pointed at the “memoir” package by Dimitris Hanos, another much esteemed colleague, who also happens to be the first real programming teacher I ever had, while he was teaching C Programming :-)

The manual of the memoir package is a mid-sized book itself, containing more than 260 pages of beautifully typeset information about document preparation with memoir, page and document layout, and a surprisingly great deal of amount about typography and its history. I’ve already managed to skim through the first 50 or so pages earlier tonight, and I can’t wait until I have more time to read all of it :-)

## 6 thoughts on “The manual of the LaTeX “memoir” package”

1. Michael Iatrou

So any thoughts on ConTeXt vs. memoir? Features you liked, recommended use cases?

2. keramida Post author

Both ConTeXt and the memoir package were written by people who have studied the history of typography a fair bit. This is obvious when one reads the documentation of ConTeXt and memoir.

Memoir’s manual includes a very interesting introduction to the history of page layout and beautifully arranged miniatures of different page layouts, ranging from the 15th century to modern packages like LaTeX’s article page layout. The manual also includes, among other things: technical details about typesetting in the Middle Ages, information about the way typesetters and typographers work, and the valid reasons why one may prefer to stick with a “standard“ page layout, but also the reasons why sometimes a custom page layout is necessary for producing results which are æsthetically pleasing.

The developers of ConTeXt have also written a lot of beautiful and nicely typeset documentation, and many of their documents are available in PDF format for anyone to download. The Typographic Programming manual is one of the manuals distributed online by “PRAGMA A.D.E”, the company which drives most of ConTeXt’s development. It was a great fun to read, even though it’s not finished yet, and it includes a lot of typographic information similar to the memoir manual. The “Documentation overview” pages at http://www.pragma-ade.com include a wealth of information for using ConTeXt and its features too.

I tried using ConTeXt for writing documentation at Bytemobile, and some of the results are encouraging. It doesn’t take a long time for a technically minded person to get used to the macros of ConTeXt, and with a nice “environment” (what LaTeX calls a “style”) anyone can be up and running with ConTeXt in minutes.

The main differences between ConTeXt and LaTeX are:

ConTeXt tries to embed and integrate a lot of the functionality that is commonly provided by LaTeXp packages.

At the same time, ConTeXt tries to make any new functionality optional, tunable, and customizable through feature options, so that it is possible to extend and configure each integrated feature

LaTeX includes a predefined, basic set of styles (the “article”, “book”, “report” and “letter” styles). ConTeXt also includes a set of predefined styles, but the collection is much much smaller than LaTeX.

As far as use cases are concerned, there is one major area where LaTeX seems to be the unquestionable leader: journal publications. Many journals accept submissions in LaTeX format; some of them even have special stylesheets which authors can use to write in a uniform, consistently beautiful style. Some of these journals have started giving away ConTeXt styles too, but the number of the ones which do that is much smaller than the LaTeX-friendly journals today.

ConTeXt is, on the other hand, very interesting if you are willing to experiment with fonts and typefaces, color-separation for CMYK printing, page layout and entirely custom page-design, color support, XML input, multi-language and UTF-8 input, and a few other things which are already part of ConTeXt but are also actively being developed.

3. Michael Iatrou

Thanks a lot for the insightful comments. Please, allow me to squeeze it a little bit more: three cases from the top of my head:

1. Technical documentation for Bytemobile (index, figures, tables, side-notes, footnotes, references), other colleagues may have to expand it and maintain it.

2. Technical article for FreeBSD [random topic] (code, figures, tables, footnotes, references), on time thing, no need to expand/modify it.

3. Mid-sized book “Tales from the crypt: peaking on the FreeBSD core team” [random title] (index, footnotes), for dead trees publishing, no need to expand/modify it.

What would you choose for each one of them? (single word answers will make me happy, although I would be thrilled if you share with us any relative field experience)

P.S. Thumbs up for the theme change :-)

4. keramida Post author

Minor diversion: WordPress doesn’t fancy anyone’s “set tw=NUM” setting. I use the “mozex” Firefox plugin and the “longlines” mode in Emacs, configured to wrap at the active window boundary to edit WordPress posts and comments and/or Bugzilla bug reports, bug comments, and so on. Anything that required editing in a tiny browser window gives me the creeps and I delegate all editing to Emacs!

I’ve edited your comment to remove the hard newlines, and it looks much better now :-)

Let’s see the three use cases you described now.

1. Technical documentation for Bytemobile (index, figures, tables, side-notes, footnotes, references), other colleagues may have to expand it and maintain it.

I’d probably use ConTeXt for Bytemobile.

ConTeXt uses the texexec utility to “run” documents through the formatting engine. This is a very handy tool to have around, because it takes care of running the document multiple times through ConTeXt, until all cross-references are resolved, the table of contents, table of figures, and index are populated, and so on. It automates a great deal of stuff, so all you basically have to to do generate a list of tables in a ConTeXt document is to write at the document location where you want to place the list of tables to appear:

\completelistoftables

All the details of inserting an unnumbered section with a title of “List of tables”, adding a table of contents entry, and enumerating all the tables of the current document, are taken care of automatically. This is a fairly painless way of typing ConTeXt documents with lots of tables, and having the \completelistoftables macro around, coupled with the smart texexec script which takes care of running ConTeXt as many times as necessary to generate the proper list-of-tables contents is definitely a nice point.

LaTeX includes similar macros, which I’m assuming you are already familiar with, but it may take a few manual steps to produce the correct l-o-t contents, i.e. rerunning pdflatex at least twice.

Footnotes and side-notes are pretty easy in ConTeXt too. There are even features to create custom “lists of XX”, i.e. a list of all side-nodes, and typeset that after the list of tables. The texexec utility will also take care of rerunning ConTeXt as many times as necessary to populate the new list. Formatting customizations for the look and placement of footnotes are available. Formatting and placement of side-nodes can be configured either individually, for each side-note, or globally for the entire document.

Cross-references are pretty easy in ConTeXt. You just write something like:

The greatest foobars of all time are listed in \in{foo-complete},
at \at[page]{foo-complete}. If you don’t have time to read
through a big list, it may be more interesting to simply skim
through the latest foobars, namely those of the last century.
These are listed in \in{foo-century}, at \at[page]{foo-century}.

\section[foo-century]{Great foobars of the last century}

\section[foo-complete]{Great foobars of all time}

You are done. You don’t need to do anything special for texexec to notice that there are internal cross-references, and produce hyperlinks.

I’ve also used the features of LaTeX, but ConTeXt’s great advantage here is that you don’t need to \usepackage anything to have all these features; they are part of the standard ConTeXt distribution :-)

Note: I’ve already used ConTeXt to produce some of the documents of Bytemobile, but I don’t know how easy it would be to convince others at work to start using a predefined ConTeXt style to produce consistently looking documentation. I’ve shown the output to a few colleagues, and at least two of them liked the generated output. The catch-22 is that the two colleagues who liked the output are already “sold” on typesetting with TeX-based systems, so the fact that they liked ConTeXt is not in any way related to what other, Word-addicted colleagues may feel :-)

The tricky part of writing with ConTeXt is that it needs a lot more upfront work to create a proper style, precisely because it doesn’t have any style which is considered to be “The One True Article Style” or “The One True Book Style”. Once a style is prepared, and an easy set of macros is defined, both ConTeXt and LaTeX are quite capable of handling the documentation needs of a technically-oriented company. The main reason why ConTeXt or LaTeX is not going to be accepted in some companies are not technical, but social :-)

2. Technical article for FreeBSD [random topic] (code, figures, tables, footnotes, references), on time thing, no need to expand/modify it.

I’d probably use LaTeX for this.

The main reason is that I think people from FreeBSD would want to be able to easily copy, modify, edit, reviewand even include this sort of writing in journals, conference reports, and so on.

Quoting source code is an ever-resurfacing problem with technical documentation. The problems of picking the right font style, font size and text width can be handled equally well by LaTeX and ConTeXt. Both these macro packages include support for defining, using and customizing “verbatim-style” environments; there is no reason to prefer one or the other, in terms of technical features for writing developer-oriented documentation :)

3. Mid-sized book “Tales from the crypt: peaking on the FreeBSD core team” [random title] (index, footnotes), for dead trees publishing, no need to expand/modify it.

I’d use LaTeX for this.

LaTeX has literally hundreds of macro packages, for anything that exists under the Sun, and then some more bits too.

When writing anything that is larger than small-sized articles and/or one-shot things, I am not really sure it is worth spending all the time it takes to prepare a seriously looking, beautiful ConTeXt style. It’s probably a wiser choice to reuse the existing LaTeX macro packages, and stick with one of the standard styles, like “report” for technical reports and “book” or “memoir” for other book-sized publications.