sylvainhalle/papershell

Nice and flexible template environment for papers written in LaTeX

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:

• The up-to-date style and bibliography files of many different publishers (journals and conferences)
• A script that generates the proper preamble (title, list of authors and institution) specific to each style
• A very advanced Makefile (by Chris Monson) taking care of the compilation/cleaning process
• Scripts (for both Windows and Linux) to perform spell checking of the LaTeX source with GNU Aspell. The words added to the dictionary while checking are also versioned with the project.
• A script that can "flatten" your sources into a single compilable .tex file (with all includes and bibliography) and export all resources in a stand-alone folder (ideal for exporting the camera-ready sources to an editor)
• A .gitignore file suitable for a single-document LaTeX project
• A script to clean up a BibTeX file

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:

• aaai for AAAI journals
• acmart for ACM conferences and journals
• easychair for EasyChair EPiC Series and Kalpa Publications series
• elsarticle for Elsevier journals
• eptcs for the Electronic Proceedings in Theoretical Computer Science
• IEEEtran for IEEE conference proceedings and journals
• lipics for the Leibniz International Proceedings in Informatics
• llncs for Springer's Lecture Notes in Computer Science series
• sig-alternate for ACM conference proceedings
• stvrauth and similar for Wiley Journals
• svjour for Springer journals
• usenix2019_v3 for USENIX publications

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

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

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

2. 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.

3. 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.

4. 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.

5. 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.

• The preamble for IEEE journal fixes a problem with a redefinition of the \markboth command that would otherwise prevent the document from compiling
• The postamble for Elsevier fixes the fact that the bibliography does not have a section title
• The EPTCS BibTeX file incorrectly handles doi fields that contain an underscore. PaperShell contains a fixed version.
• The LIPIcs style is incompatible with the subfig package. PaperShell contains a fixed version.
• The Springer Nature journal style has a bug causing Tikz to break compilation. PaperShell contains a fixed version.
• The Springer Nature journal style also redefines the \href command of the hyperref package in a way that the link's text is never shown. PaperShell has a version where this redefinition is commented out.

It also takes care of using fonts properly:

• The original style files load obsolete font packages; PaperShell overrides them with newer ones with much nicer math support (e.g. lmodern and mathptmx instead of cmr and times)
• In all styles, the Helvetica font (used in \textsf) is larger than the text's normal font. PaperShell fixes this issue by scaling down Helvetica.

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.

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:

• When spell checking, you have to run Aspell on a single file. Otherwise, you need to run it on every input file every time, and you cannot use the bundled script.
• Some publishers require you to upload a single stand-alone TeX file when submitting. PaperShell has a script that can do it for you if you use the defaults, but it may not work if your paper has multiple parts in separate files (this has not been tested).
• When searching for a word or an expression in your text editor, you have to search in a single file ---otherwise you have to search in all files.
• If your text editor has a "Compile with LaTeX" button, clicking on it when editing one of the section-x.tex will try to compile only that file and will fail. You have to go back to the main file every time you need to compile.
• If the goal is to make it possible to edit different parts of the same paper in parallel, don't forget you are using Git and that it should take care of this even if you edit the same file.
• If you move parts of text around, the changes are easier to track in Git if they don't jump from one file to another.

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.

papershell's Issues

Use graphicspath

Some submissions systems (such as Editorial Manager) impose that all files (including pictures) reside in a flat directory. The template paper should use \graphicspath{{fig/}} so that the path for figures can be easily changed instead of being hard-coded throughout the paper. See: http://tex.stackexchange.com/questions/139401/how-to-use-graphicspath

Gitignore: remove the -ambles

The pre-, mid- and post-amble includes should be versioned. Otherwise cloning on Overleaf does not work.

Don't put affiliation numbers when only one affiliation

In the LNCS style, we should not show the institution number (i.e. "1") if all authors are from the same institution.

Clash between microtype and newtx

The fonts newtxtext and newtxmath (loaded in the IEEE stylesheet) prevent LaTeX from compiling when used in conjunction with microtype. You must either remove microtype or use mathptmx instead of the newtx packages. Not a bug in PaperShell itself, but a workaround would be appreciated.

Allow an author to have two affiliations

In authors.txt, one could write:

Marty McFly (1,2)
...

1
My Institution A

2
My institution B

llncs has no orcid support

there's a newer version of llncs.cls which has \orcidId{...} which is encouraged by Springer

Associate each style with its files

Currently all auxiliary files required by all styles are in the Source folder, without knowing which one belongs to which style. The set-style.php script should keep track of these associations. Two uses:

1. easier to update the files of a specific style
2. possible to export sources only with they style file they actually use

Put only institutions associated to authors

In authors.txt, if you write institutions that are not associated to authors, they still appear in the list of institutions.

BibTeX does not work in Overleaf

When using a PaperShell (2.0) project in Overleaf, the bibliography is not compiled and you get lots of messages complaining about undefined references.

This is because the \bibliography command is not located in the main paper.tex file, but rather in postamble.inc.tex, which is included by paper.tex. Apparently Overleaf only looks for the bibliography in the main file and does not follow the \includes.

The workaround (a hack, actually) is to manually copy-paste the contents of postamble.inc.tex at the end of paper.tex. Is there a better way?

svjour.cls missing

\usepackage{XXX}

Because the preamble.inc.tex file will be overwritten after make.

If I want to introduce my own additional packages before make, what changes need to be made?

EX:

\usepackage{booktabs}
\usepackage{adjustbox}
\usepackage{threeparttable}

If you open the project in overleaf, please note!

Issue：

*** (job aborted, no legal \end found) error in LaTex

For anyone interested on this problem, the issue seems to be that the main file selected in my overleaf project was wrong: it was Preamble.tex instead of main.tex

I went to the menu in the upper left corner of the page and changed the main file to main.tex. Now it works fine.

make error🙅

After writing the paper.tex, execute the make command to report an error:

NOTE: You may ignore warnings about the following files:

     paper.d

Makefile:2898: paper.d: No such file or directory
= paper.tex --> paper.d paper.pdf.1st.make (0-1) =
sed: 2: "d
": unused label 'needthreemore'
sed: 2: "d
": unused label 'needonemore'
sed: 2: "d
": unused label 'needthreemore'
sed: 2: "d
": unused label 'needtwomore'
make: *** No rule to make target `fig/The\\\', needed by `paper.d'.  Stop.

LabPal plots must be in `fig`

If you use LabPal and put labpal-plots.pdf in the Source folder, the Makefile breaks. Everything works if the file is put in the fig subfolder instead. There should be a way to tell the Makefile not to attempt building something for this file if it is in the Source folder.

running php file

Hi there,

really thankful for your work, but I have an Issue.
I modified the authors.txt file but I cant seem to translate it into the then compiled pdf.
I downloaded and installed php. Folderstructure is:

Main

• PHP
• -php.exe
• PaperShell
• -source folder
• --paper.tex
• --etc.
• -set-style.php
• -authors.txt
• -etc.

It seems im not running the set-style file correctly, i tried for cmd: php set-style.php lncs
but it didnt work out yet. And ideas? Thanks in advance.

Best,
Binel

IEEE forbids pdflatex

...so every image (jpg, png, pdf, whatever) must be converted to eps, and latex (instead of pdflatex) must be used to compile --at least for the camera-ready version you send them. We should provide a script (using pdftops and imagemagick) that takes care of that. Some info here: http://tex.stackexchange.com/questions/20883/how-to-convert-pdf-to-eps

Makefile does not work in Windows

Hi, stumbled across this template in Overleaf and wanted to give it a try. Sadly, I followed the instructions all the way to compiling it. I am on a Windows machine and the error was the following:

PS D:\Papers\PaperShell-2.6.1\PaperShell-2.6.1\Source> make

The system cannot find the path specified.
process_begin: CreateProcess(NULL, which echo, ...) failed.
Makefile:834: pipe: Bad file descriptor
The system cannot find the path specified.
process_begin: CreateProcess(NULL, which tput, ...) failed.
Makefile:1104: pipe: Bad file descriptor
"NOTE: You may ignore warnings about the" "following files:" ; echo ; echo ' paper.d' ; echo ""
'kpsewhich' is not recognized as an internal or external command,
operable program or batch file.
'kpsewhich' is not recognized as an internal or external command,
operable program or batch file.
"= paper.tex --> paper.d paper.pdf.1st.make (0-1) ="
The system cannot find the path specified.
'/'' is not recognized as an internal or external command,
operable program or batch file.
Makefile:2898: paper.d: No such file or directory
make: *** [Makefile:3340: paper.d] Error 255

As far as I could google about it, syntax on the directories might be the issue. So yes, would you be supporting Windows on this?

IEEE forbids hyperref

http://tex.stackexchange.com/questions/133303/how-to-remove-bookmarks-from-you-pdf-latex-file

ACM: text over copyright

In some paper instances, the last line of text in the first column (ACM style) overlaps the copyright notice. Someone should investigate when this happens and try to fix this. (This is probably not a problem with PaperShell, but the template could provide a version that fixes this issue.)