Template for LaTeX papers

The template itself is in the {{cookiecutter.paper_id}}-paper.

In order to generate a project from the template:

• install cookiecutter
• find a paper-cutter tag applicable (usually the latest tag listed at https://git.wmi.amu.edu.pl/filipg/paper-cutter/releases), say 4.8.0
• run: cookiecutter https://git.wmi.amu.edu.pl/filipg/paper-cutter.git --checkout 4.8.0

You will be asked to choose a LaTeX template, at the moment the following templates are handled:

• “Vanilla” — just a standard LaTeX article template (vanilla),
• TACL (tacl),
• ACL (acl),
• Natural Language Engineering journal (nle),
• ACM SIGCONF template (sigconf), e.g. for the SIGIR conference,
• MSc thesis at Warsaw University of Technology (pw-thesis)
• COLING (coling)
• LLNCS (llncs)
• EMNLP (emnlp)
• NeurIPS (neurips)
• IEEE Access (ieee-access)
• PolEval (poleval)
• Msc thesis at Adam Mickiewicz University, Faculty of Mathematics and Computer Science (amu), template prepared by Bartłomiej Przybylski (https://github.com/bprzybylski/amuthesis)

If you are to use another template, prepare an MR to this repo first! Do not add directly to your specific paper.

Interoperatibility with Overleaf

Overleaf handles git but in an imperfect way (to put it mildly). It's better to upload a package to Overleaf first.

You can do this by running helpers/set-up-overleaf.sh after creating a project or carrying out the following steps manually:

1. Create a project locally.
2. Run make
3. Run make source-pack
4. Upload the zip file to Overleaf.
5. Copy project to some other place.
6. Clone the repo from Overleaf: git clone https://git.overleaf.com/FUNNY-OVERLEAF-CODE PAPERID-paper
7. Set remotes:

git remote add overleaf https://git.overleaf.com/FUNNY-OVERLEAF-CODE
git remote set-url origin YOUR-GIT-REPO

7. Set credential helper so that Overleaf won't ask about password: git config credential.helper "cache --timeout=10000000"
8. Unfortunately, Overleaf will discard hidden files (.*) when a zip is uploaded, also file permissions will be somewhat broken
9. … so you need to copy .cookiecutter.yml file and re-apply the template (cookiecutter https://git.wmi.amu.edu.pl/filipg/paper-cutter.git --checkout 4.8.0 --output-dir .. --config-file .cookiecutter.yml --no-input --overwrite-if-exists)
10. Re-commit the files (including recovered .* files).
11. Push the repo to Overleaf (fortunately, the .* will be treated correctly when this is done by git): git push overleaf master
12. Push the repo to GitLab. git push origin master
13. Set the Overleaf git remote in helpers/vars
14. Now you can synchronize between GitLab repo and Overleaf manually or using helpers/synchro.sh script

Updating package with updated template

To keep your codebase in sync with template you need to occasionally reapply the template. Here's how:

• find a paper-cutter tag applicable, say 4.8.0
• (do not refer to master in your projects!)
• go to project root
• run: cookiecutter https://git.wmi.amu.edu.pl/filipg/paper-cutter.git --checkout 4.8.0 --output-dir .. --config-file .cookiecutter.yml --no-input --overwrite-if-exists
• check changes with git

Editing the files

Please do not modify the file PAPER_ID.tex (this file is supplied by this template — and will be switched when you switch to another journal/conference template, see below) . Modify metadata.tex and main.text files.

If you really need to change PAPER_ID.tex, please prepare a merge request to this template repo.

Switching to another conference/journal template

Switching to another conference or journal template is easy.

1. Check whether the template is already handled. (See above for the list of LaTeX templates handled.) If not, get in touch with Filip Graliński.
2. Commit or stash any uncommitted changes.
3. Change the latex_template value accordingly in the .cookiecutter.yml file. Commit the changes.
4. Re-run the template (as if updating, see above: cookiecutter https://git.wmi.amu.edu.pl/filipg/paper-cutter.git --checkout 4.8.0 --output-dir .. --config-file .cookiecutter.yml --no-input --overwrite-if-exists).
5. Compare metadata.tex against the right metadata template file (*/*-template-meta.tex in _latex-templates/) and make any fixes needed. This is the only thing that needs to be done manually (unfortunately, LaTeX templates differ in commands for authors, their affiliations, etc.).
6. Run make to generate PDF.
7. If you have an appendix, make sure it is rendered correctly.

Adding new conference/journal template

You should prepare a merge request similar to https://git.wmi.amu.edu.pl/filipg/paper-cutter/commit/970e10ca52bed1bf293f99809d89aacd5c7ca44a.

Some notes:

• the style files should be just downloaded from an external resources (see e.g. https://git.wmi.amu.edu.pl/filipg/paper-cutter/src/branch/example/hooks/post_gen_project.sh#L87)
• you should take an example document (usually provided by the creators of a conference/journal template) and turn it into a template, like e.g. https://git.wmi.amu.edu.pl/filipg/paper-cutter/src/branch/example/%7b%7bcookiecutter.paper_repo_name%7d%7d/_latex-templates/neurips-template.tex
• metadata header (title, authors, etc.) should be given as a separate template file, see https://git.wmi.amu.edu.pl/filipg/paper-cutter/src/branch/example/%7b%7bcookiecutter.paper_repo_name%7d%7d/_latex-templates/neurips-template-meta.tex
• remember that Jinja2 is used as the template engine
• sometimes you will need to add Jinja {% raw %} and {% endraw %} directives to escape LaTeX mark-up conflicting with Jinja directives (usually the whole or parts of ...-template.tex and ...-template-meta.tex files.

Versioning the template

Always use a specific tag in the .gitlab-ci.yml file for your project when including main.yml from this repository.

This template is versioned with a Semantic-Versioning-like scheme, i.e. a version is expected to be of the form M.N.P, where:

• M is changed in case of breaking changes for which manual actions other then update with the cookiecutter command is required
• N is changed when a new feature is added or a significant bugfix happened, it means that the files need to be updated in a project with the cookiecutter command
• P is changed in case of minor changes or bugfixes, it should be OK even if changes are not update with the cookiecutter command

Releasing a new version of the template

• change the version in the {{cookiecutter.paper_id}}-paper/.gitlab-ci.yml template file
• add an item to CHANGELOG.md
• in case of breaking changes (M is incremented) describe clearly what actions are to be taken in CHANGELOG.md
• tag master with the version (the same as in {{cookiecutter.paper_id}}-paper/.gitlab-ci.yml)

Variables to be set in GitLab UI

• SLACK_RELEASE_BOT_SECRET - secret to a Slack bot to inform about new releases (go to https://YOUR_ORGANIZATION_NAME.slack.com/apps/manage/custom-integrations, click "Incoming WebHooks" / "Add", then configure the hook and and set the string such as "ABCDEFGHI12/ABCDEFGHI12/aaaaaaaaaaaaaaaaaaaaaaaa" as SLACK_RELEASE_BOT_SECRET)

Authors

Prepared by Filip Graliński (Applica.ai).

Contributors

• Łukasz Garncarek
• Piotr Halama (including the project name)
• Tomasz Stanisławek
• Paweł Mleczko