[Tex/LaTex] Reusing LaTeX code to achieve a consistent layout

best practicesformattingmacrostables

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?

Best Answer

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!

Related Question