Home

Awesome

A Flexible LaTeX Article Environment

This repository provides a boilerplate environment for writing LaTeX articles using the popular templates from Springer, IEEE, ACM, AAAI, Elsevier, etc. It provides:

Using this template, switching a paper from any stylesheet to any other simply amounts to regenerating two files with an included PHP script. You don't need to change a single line of the main, paper.tex document you are working on. What is more, the project's structure can be imported and used within Overleaf.

Why this template?

If you have been writing lots of (Computer Science) papers, you may have been mostly using LaTeX with a couple of different document classes:

First off, this repository provides a well-structured template project where all these classes are included, so you can pick the one you wish when starting to write. Moreover, it comes with a very powerful Makefile that does all sorts of nifty things, such as suppressing useless output from LaTeX and colouring (yes, colouring) its meaningful output (errors in red, etc.).

There do exist products, such as Overleaf, which allow you to instantiate a blank LaTeX paper using many of these templates (PaperShell can interact nicely with Overleaf; see below). However, there might be various reasons for which you might want to switch an existing document from one class to the other. For example, you started writing a paper without deciding where to send it, only to find that the conference you've chosen has a different publisher than the paper's current style. Or, a paper sent to a conference (and perhaps rejected) needs to be sent to another venue with a different publisher. (Note that in the past, it used to be the publisher's job to format your manuscript to their taste. But that's another story.)

Alas, it turns out these stylesheets are not directly interchangeable. Rather than nicely overriding the behaviour of LaTeX's original commands from the article document class, each class decided to invent its own commands to, e.g., define the title, authors and institution of a document --and none of them works the same way. For example, here is how to declare authors and institutions in llncs:

\author{Emmett Brown\inst{1} \and Marty McFly\inst{1} \and Biff Tannen\inst{2}}
\institute{%
Temporal Industries \\
Hill Valley, CA 90193 \\
\and
BiffCo inc. \\
Hill Valley, CA 90193 \\
}

...in IEEEtran:

\author{%
\IEEEauthorblockN{Emmett Brown, Marty McFly}
\IEEEauthorblockA{%
Temporal Industries\\
Hill Valley, CA 90193\\
}
\IEEEauthorblockN{Biff Tannen}
\IEEEauthorblockA{%
BiffCo inc.\\
Hill Valley, CA 90193\\
}
}

...in acmart:

\author{Emmett Brown}
\affiliation{
  \institution{Temporal Industries}
  \streetaddress{Hill Valley}
  \state{CA}
  \postcode{90193}
}
\author{Biff Tannen}
\affiliation{
  \institution{BiffCo inc.}
  \streetaddress{Hill Valley}
  \state{CA}
  \postcode{90193}
}

...and in elsarticle:

\author{Emmett Brown\fnref{label1}}
\author{Marty McFly\fnref{label1}}
\author{Biff Tannen\fnref{label2}}
\fntext{Temporal Industries, Hill Valley, CA 90193}
\fntext{BiffCo inc., Hill Valley, CA 90193}

Four different sets of commands and syntax for the same data ---and all this while article.cls already provides commands doing exactly that, which could have easily been overridden! To make things even worse, the class elsarticle does not even use \maketitle to print the title, which must be enclosed (along with the abstract) within a frontmatter environment after the \begin{document}. Therefore, switching between classes requires some amount of braindead, yet frustrating copy-pasting from existing files you have, which arguably becomes quite mind-numbing when you've been doing that once in a while for the past ten years. And sadly, tools like Overleaf do not allow you to easily switch templates once you've started writing.

In this project, the paper's title, authors and institutions are written in a separate file called authors.txt:

Applications of the Flux Capacitor

Emmett Brown (1)
Marty McFly (1)
Biff Tannen (2)

1
Temporal Industries
Hill Valley, CA 95420

2
BiffCo inc.
Hill Valley, CA 95420

(You can optionally separate first and last names with braces, e.g. {Marty} {McFly}. This is used in the EPTCS style for writing abbreviated author names, e.g. "E. Brown, M. McFly, B. Tannen", etc.)

You then call a script named set-style.php to generate a preamble and postamble with the proper syntax for the document classes you want to use. These files are called preamble.inc.tex and postamble.inc.tex.

To change the authors or title, or to switch between document classes, modify authors.txt and runset-style.php again. You then just need to recompile. Voilà!

Quick Use

  1. Download and unzip the PaperShell empty project in a folder of your choice.

  2. Modify authors.txt with the desired title, authors and institutions. The file is self-documented and tells you how to do it.

  3. Call php set-style.php style to generate the include files, which will be placed in the Source subfolder. (This requires PHP to be installed in your path.) The word style must be replaced by the name of a paper template, which you can select from a long list. Some of the available styles are: lncs, ieee, acmconf, elsevier, springer, aaai, acmjour, eptcs, stvr, lipics, easychair, usenix.

  4. Write your text as usual in Source/paper.tex. Figures should be placed in the fig subfolder. Write your abstract in Source/abstract.tex, and put any other imports and declarations in Source/includes.tex. Write anything that should go after the bibliography (such as appendices) in Source/appendices.tex.

  5. To compile, use make all. To remove temporary files, use make clean. The Makefile has a very comprehensive list of other useful features. To read them, run make help.

  6. To spell check, type ./aspell-check.sh (in Linux) or aspell-check.bat (in Windows) from the project's top folder. Any additions to the personal dictionary will be reflected in changes to files .aspell.en.prepl and .aspell.en.pws, which are versioned with the rest of the project. See the file aspell-check.readme for instructions. (Hint: you may also want to try TeXtidote).

Extras

As an extra, the generated preamble files add a few commands that fix bugs in some document classes.

It also takes care of using fonts properly:

Exporting your sources

If your paper is accepted (yay!), you may need to send the sources to the editor so they can produce the final, "camera-ready version". Just zipping your PaperShell Source folder will confuse a few of them, especially if they have scripts trying to compile it automatically (many of them just try to compile the first .tex file they find, which won't be the right one in most cases).

From the root folder, you can call

php export.php

Creates a stand-alone directory with all the sources. This script reads the original source file (paper.tex using the defaults) and replaces all non-commented \input{...} instructions with the content of the file. It also includes the bibliography (paper.bbl) directly within the file (so no need to call BibTeX). The resulting, stand-alone LaTeX file is copied to a new folder (Export), along with all necessary auxiliary files (basically everything in the Source folder that is not a .tex file).

Normally, what is present in the Export folder is a single compilable .tex file (no \include or \input), plus class files and images. It is suitable for sending as a bundle e.g. to an editor to compile the camera-ready version. You can also bundle the whole thing (except the main .pdf file and auxiliary files) in a single zip file using zip-export.sh.

As an option, the export.php script can also create a "flat" structure with no folders (some publishers ask for this when submitting source files). Use the --flatten command line option when invoking the script.

Overleaf integration

Overleaf is an online collaborative platform for editing LaTeX documents. Provided you have run set-style.php once, you can import the whole project structure into Overleaf and edit it there; don't forget to set Source/paper.tex as the main file.

If you want to change the document to another article class, simply re-run set-style.php on your computer and re-upload preamble.inc.tex, midamble.inc.tex and postamble.inc.tex to Overleaf. This is even easier if you keep Overleaf in sync with a GitHub repository.

Cleaning up a BibTeX file

You can uniformize the presentation of BibTeX entries (indentation, etc.) and remove duplicate entries by passing it into a script. In the root folder of your project, type

php clean-bibtex.php

This will read and parse Source/paper.bib and re-output a cleaned up version at Source/paper-clean.bib. If everything looks good, you can then overwrite the original paper.bib with this new file.

Overriding defaults

Default settings can be overridden by giving values to parameters found in settings.inc.php. All these settings are documented in detail in the file. Make sure to call generate-preamble.php again after you change the file.

In the case of ACM journals, you also have to overwrite acm-ccs.tex and acm-bottom.tex with appropriate content.

Changing the paper's filename

By default, the main paper is called paper.tex. We recommend that you leave it that way: the whole point of using this environment is to use the same commands and structure for all your papers, so customizing it for each paper kind of defeats that. If you must change it to something else:

  1. Make sure the filename does not contain spaces, or the make command will not do anything.
  2. Make sure to change paper.tex by your filename in Source/Variables.ini.

Good practices

Use a single tex file

Try to keep your paper in a single file (paper.tex if you use the project defaults) ---that is, do not split the paper into section-1.tex, section-2.tex, etc. that you \input inside paper.tex. A few reasons for doing so:

In all honesty, we don't see much benefit in splitting a 10-page paper into multiple parts in separate files.

About the Author

This project is maintained by Sylvain Hallé, Full Professor at Université du Québec à Chicoutimi, Canada.

<!-- :wrap=soft:maxLineLen=80: -->