Writing Modular TeX Documents

(Mathematical Toolset Series: TeX & LaTeX, Part 3 of 3)

If you write frequently, it is likely that you have certain stock or administrative material that is included in each of your documents. You also likely spend a substantial portion of your overall effort re-writing, editing, or re-arranging material. In this situation, one of the best ways of preserving your time and your sanity is to adopt a modular approach to document development.

In this final article of the three part series on LaTeX / TeX, I will discuss a modular approach to document preparation using TeX. I’ll also provide modular templates that should make your use of TeX more efficient.

This is Part 3 in a series of three articles (Part 1, Part 2) intended to give you all that you’ll need to begin working with LaTeX / TeX on Windows, using free, open-source software.

Why Modular Documents?

A modular approach to document design can be more efficient if you have common elements in your documents, especially when you begin to make changes to these common elements. By using decoupled text modules, you can readily re-arrange or re-order them, creating documents for different purposes, from the same stock of core content, modularly organized.

Thinking Modular in TeX

In TeX, taking a modular approach means partitioning your typical document into more or less independent pieces, many of which you will want to re-use from document to document. Provided that you have kept the re-usable parts of your document separate from the main content, they can be brought into the main document using various \include directives.

The advantages of the modular approach to organizing the components of your document are that it allows you:

• (i) to avoid copy / paste whenever possible,
• (ii) to re-use specific parts of your document wherever possible, and
• (iii) to be able to make corrections in only one place and have these corrections propagate easily into all documents that use the module, without having to make the same change over and over again in each document.

I’ve found it advantageous to compose and maintain, at a minimum, the following as separate modules:

1. a separate Title Page. The key here is not so much the fact that you may wish to change your title or content. The key is that you may, down the road, wish to combine content from various different articles into a coherent larger unit. For example, you may wish to combine multiple short articles into a longer article, or take a collection of articles and organize them as separate chapters of a book. By keeping the titles of your articles separate from their content, you give yourself the flexibility, without changing either title or content, to generate a short article or to incorporate the same content in another vehicle, be it larger article, report, or book.
   

2. separate Author Attributions. This allows you to designate your authors and craft their details once, and include the same composition in all your documents. The savings comes when author information changes — contact information, position, and so on. Instead of having to manually go through each document and make the same changes over and over again, you make the required change in one place, and all documents compiled thence forward will pick up the corrected attribution.
3. separate Document Settings (Preamble section). The settings section of a LaTeX should most definitely be organized for re-use. As you evolve your style, you will begin to collect settings and macros. If these are in one place and pulled into each document, you will find it much easier to produce consistently good documents. The advantage is that when you recompile a document created with an older template, you will automatically get all of the improvements you have added to your separate Document Settings file. The alternative: keeping track of dozens of settings and making sure that changes find their way into all of your documents, is fraught with headaches and mistakes.
4. a separate Bibliography. Establishing a separate repository for all of your bibliographic information is a strongly recommended practice. Doing so means that you are building a reference list that is comprehensive and uniform. The key is that TeX (specifically BibTeX) automatically pulls only those citations that are used in a particular article when creating that article’s list of references. So comprehensiveness without the hassles of having to manually copying and pasting and then maintain specific, often overlapping subsets of references for related articles — this is a big win! You should make the effort and invest in using BibTeK.
5. separate Code Listings. If you include algorithms, program listings, or other similar external material in your papers, you should not copy and paste the content directly into your article. With every copy and paste comes the serious and taxing burden of making a correction in the original source code and forgetting to update the article text. By dynamically including program listings directly from wherever the source code resides (in version control, a separate folder, and so on), you set yourself up for success. Any changes made to the original source code will be reflected automatically in every recompilation of the document — i.e. one button click. The key: keep your code listings OUT of TeX.

   Modular Templates for LaTeX

   To give modular document organization a try, it is helpful to have ready-to-use templates that you can use as boilerplates to experiment with for your own work. So, attached is a collection of modular templates similar to ones that I use in my own LaTeX work. They are available as ZIP archive from the Downloads section or can be downloaded individually by following the links for each template below.

   1. _TeXdefs.tex, containing the preamble definitions, macros, style settings, and other layout details
   2. paper-title.tex, containing the title and optionally the abstract. This is the main vehicle that pulls together the pieces of the document. You will be compiling this to create the paper.
   3. paper-content.tex, consisting of one or many content specific modules, perhaps separate chapters, sections, or other organization of material that is naturally decoupled. A good litmus test here is that it should make sense to be able to interchange the order of your content modules without affecting the logical flow. The specific order in which they appear in the paper will be fixed in the paper_title
   4. authors.tex, containing the simple, crafted attributions of authors with contact information and the obligatory acknowledgements.
   5. bibliog.bib, consisting of a collection of all your references, not just the ones cited in a particular paper. This is a much more efficient way of maintaining comprehensive reference lists and avoiding the duplication that is otherwise required for commonly used citations.

   Instructions:
   To test these templates, put them all into the same folder and point your LaTeX compiler to paper-content.tex. This PDF is what should result.

   Notes

   • Don’t forget! You have to compile a fresh batch of files three times in succession before all warnings are resolved — the first compilation builds pulls references to citations, footnotes, headings, etc., the second fills in these references into the table of contents and other automatically numbered objects, which means the third compilation can produce your final document.
   • If you’re using the platform I’ve described in Part 2, you will be loading paper-content.tex into TeXnicCenter.
   • If the words “compiling” and “building” are a mystery to you, you probably haven’t yet gotten a LaTeX / TeX platform working in Windows. No worries! Just follow the steps in Part 2 to get yourself set up and comfortable. Then come back and test these files.

   Happy TeX-ing!

   This closes the series of three articles intended to get you started working with LaTeX / TeX on Windows, using free, open-source software.

   If you have adopted LaTeX / TeX, I hope you’ll find its practicality freeing and the beauty of its output inspirational. Happy TeX’ing!

   ---

   If you’ve started with this article, please note that Parts One and Two provide the background to “the TeX Way” and help you set up your a LaTeX / TeX platform on Windows. You’ll need a LaTeX / TeX platform to try out the example templates provided above.

   >> Continue reading: Part 1: LaTeX / TeX: Professional Grade Typesetting for Scientific Writing

   >> Continue reading: Part 2: Setting up a TeX / LaTeX Platform on Windows with Open Source Tools