# Reusing LaTeX code to achieve a consistent layout

What is the best approach to reusing the same layout for numerous tables, paragraphs etc. which share the same structure but different content? Is the best method to use custom commands/macros?

-
Write a (maybe private, maybe simple) package in which you define the macros. –  Leo Liu Aug 12 '12 at 6:30

As David Carlisle and Leo Liu have already pointed out, if you anticipate spending significant amounts of time in the future writing papers using LaTeX, it's definitely an excellent idea to create customized macros, say to standardize the layout and other formatting-related issues of your papers. Indeed, TeX and LaTeX are very much designed to make this possible.

Naturally, there's no single "best" approach to creating such a collection of macros. The macros are there to serve your needs, and what works for you needn't work for others (and vice versa). Some general guidelines do apply though, I think:

• Assuming you use LaTeX, you'll probably want to collect the macros in a "style file" and store this file somewhere in the TeX directory tree where it can be found when you invoke it with a \usepackage command.
• As with any computer program, use lots of comments to leave signposts regarding your thinking when you write and/or modify macros. You may understand perfectly right now what you're doing today, but when you get back to the code after some weeks or months have passed, you'll be most grateful to yourself for having provided copious comments. Providing comments also greatly simplifies the task of tracking down and fixing any bugs in your code.
• Identify which LaTeX packages you always (or almost always) tend to load for your documents. Some candidate packages might be amsmath, eurosym, and calc. If there are such packages, you should probably load them in your style file.
• Structure the package like a little document in its own right. Have an introduction (likely consisting of comments only), followed by sections related to matters such as page layout (possibly using the geometry package), the format of the table of contents (possibly using the tocloft package), the format of the references and citations (e.g., do you use a citation management package such as natbib?), graphics support (graphicx), formatting of numbers and scientific units (e.g., with the siunitx package), hyperlinking and cross-referencing (hyperref and cleveref), etc.
• Formatting figures and tables consistently is a challenge, and practice makes perfect (or, at the very least, very good). For these two groups of objects, the main pieces of advice I would give is (i) to familiarize yourself thoroughly with the properties of the various tabular-like environments (to name but a few: tabular, tabular*, tabularx, tabulary, longtable, and a host of others) and (ii) to develop a consistent style regarding the layout of tables (and figures) and to stick with it. E.g., should the caption always be at the top or the bottom of the respective float? Either approach can work, but it's up to you to make the choice. There are packages such as ctable that can help structure the creation of tables in consistent way. Be sure to figure out whether these packages' built-in formatting standards are to your liking and/or whether you can modify parts of these packages to suit your needs.

Separately, be prepared to provide some ex ante flexibility regarding the LaTeX packages that should be loaded and any custom code that should be executed by your package. Not all LaTeX packages should be loaded always (see below for an example). With some planning ahead, it's straightforward to disable parts of your package by setting a single option; that's much easier, and substantially less error-prone, than having to comment out various instructions on a case-by-case basis (which might be called a form of "ex post" flexibility, I suppose).

• Assume, for instance, that you write working papers that need to be formatted differently depending on whether they are to be circulated as (i) one-off submissions to colleagues, co-authors, and others -- in which case you can fully implement your personal style preferences; (ii) working papers in your university department's working paper series; and (iii) articles in a scholarly journal. Your department and the journals you submit papers to almost certainly have "house styles" for formatting-related matters. (Hopefully, these styles have written up as LaTeX style files for you to download and include.) Naturally, you don't want your package to conflict with the additional style files you may need to load in order to adhere to your department's or journal's formatting requirements.

• To deal with this rather common contingency, it's helpful to group the package's contents into two separate parts:

• One part should contain all directives related to broadly defined formatting issues, such as page size (e.g., "A4" or "US letter" size), margin widths, line spacing, font sizes, fonts, spacing above and below floats, styles for various sectioning headers, etc.

• The other part should include all macros and directives not linked to formatting issues. Among these could be specialized math macros you've set up, hyphenation exception patterns for words that tend to occur in your documents (e.g., if you cite an author named Gottlieb, you may want to add the command \hyphenation{Gott-lieb} so as to avoid seeing the name be hyphenated as Got-tlieb!), as well as instructions for loading packages related to graphics support, color, hyper-linking of cross-references and citations, and cross-referencing itself. Usually, the formatting requirements of journals and academic departments don't specify anything special for the latter types of packages.

• Once you've (re)organized your package in this manner, you can define (i) a Boolean "variable" that controls whether the formatting-related section of the package should be executed or not (its default value should be "true"), and (ii) a package option named, say, noformattingcode, which changes the value of the Boolean variable to "false." This could be done along the following lines:

\newif\if@formattingcode\@formattingcodetrue
\DeclareOption{noformattingcode}{\@formattingcodefalse}
... % various other option declarations, etc.
\ProcessOptions\relax

\if@formattingcode % if true, execute the following instructions until \fi
% all stuff broadly related to formatting of document
\fi
...


If you set the option noformattingcode when you load your package, you're telling LaTeX to skip over the part that's in the scope of the \if@formattingcode conditional.

Happy TeXing!

-
Thanks, very thorough. Much appreciated. –  Aram Kocharyan Aug 13 '12 at 13:30

As a general rule it is a good idea to put macros and settings in a package so they can be reused. That is essentially the main point of TeX being a macro language.

One thing to consider though is any other non TeX systems whith which the document sources are going to be used. TeX itself (and extensions such as e-tex, xetex, luatex) are very consistently implemented and any TeX macros will work the way on any system. However increasingly people convert TeX sources to other formats. Conversion to HTML and e-books for example, or MathJax dynamically interpreting TeX-like markup in a web page. Most of these systems do not understand the full TeX language, and so the more you use interesting features in your definitions, the harder it is to use the sources in non-TeX systems.

An extreme example is the plain TeX file http://mirrors.ctan.org/macros/plain/contrib/misc/xii.tex Many TeX-to-something translators fail to understand that file at all. (Some do, tex4ht and latexml for example.)

-
Thanks, packages it is. –  Aram Kocharyan Aug 13 '12 at 13:29

I wasn't sure how to provide this information, but using Mico's answer I set up a couple \if@s in my local package file that conditionally call packages, but was getting a compile error LaTeX Error: \RequirePackage or \LoadClass in Options Section. The exact TeX was like this, compiled with pdfLaTeX:

\ProvidesPackage{tablemwe}

\newif\if@formattingcode\@formattingcodetrue
\DeclareOption{noformattingcode}{\@formattingcodefalse}

\if@formattingcode % if true, execute the following instructions until \fi
\usepackage{tikz}
\fi


This may be obvious to more experienced users, but after declaring options in a package, you have to add a \ProcessOptions command. Additionally, you can separate the \newif and \DeclareOption from the actual \if statement. The same example as above is corrected to look like this:

\ProvidesPackage{tablemwe}

\newif\if@formattingcode\@formattingcodetrue
\DeclareOption{noformattingcode}{\@formattingcodefalse}
\ProcessOptions
% Other code can come here, calling packages, renew commands, etc.
\if@formattingcode % if true, execute the following instructions until \fi
\usepackage{tikz}
\fi

-
Thanks for pointing out the need to mention that if one has various \DeclareOption statements in one's package, one also needs to provide a \ProcessOptions instruction. I've added this piece into the pseodo-code in my answer. –  Mico Aug 16 '12 at 10:54