LaTeX Template Generator

Generates latex templates (e.g., for thesis, workshops, conferences, IEEEtran, LNCS, ...) out of "micro-templates"

Talks and papers

• Paper: Oliver Kopp - The LaTeX template generator: How micro-templates reduce template maintenance effort
• Talk: Oliver Kopp - The LaTeX Template Generator - DANTE Herbsttagung 2019 - a talk on the motivation, user experience, and the contribution

Background information

There are many latex templates out there. All of them make use of certain packages such as hyperref, listings, or minted. The packages have to be a) included in the .tex file somehow and b) configured. Moreover, some packages offer interfaces (such as new commands or new environments) to users. Minimal examples help to understand how a package works.

The aim of the repository is to provide for each common latex package

1. Configuration
2. Usage example

and a generation into templates:

1. Support for ACM, IEEE, LNCS, KOMA-Script
2. Support for separate documents which require --shell-escape and not.
3. Support for integrated pdflatex and lualatex documents

Precondition for the generator

One has to install Node.js version 18 (or later) to get this generator running. For simple installation, just head to https://nodejs.org/ and follow the installation instructions.

Using the generator

One can start using the generator directly using the node execution wrapper npx:

npx -p yo -p generator-latex-template -c 'yo latex-template'

Permanent installation (and simpler command line usage)

In case one wants to have the generator installed permanently (or npx does work as expected), one can install generator-latex-template using following command:

npm install -g generator-latex-template

Then, one can invoke the generator as follows:

yo latex-template

How to update the document

⚠️ The template generator overwrites main.tex on each run. This will destroy your work. ⚠️

You can use the magic of git to prevent that:

1. After repository initialization:

   • git commit to save your work
   • git checkout -b template - to create a branch with initial template (required for updating)
   • git checkout main switch back to your thesis

2. Work on the main branch

3. In case an update comes in, update the template branch

   • git checkout template - switch to the template branch
   • yo latex-template - generate new template
   • git commit - save the new template
   • git checkout main - switch to your work
   • git merge template - merge in the template changes
   • resolve conflicts ^^ (Hint: IntelliJ Community Edition has a great conflict resolving tool)

Resources

• IEEE - example: paper-conference-minted.tex
• LNCS - example: paper.tex
• scientific-thesis-template - example: latexhints-english.tex
• alpenwasser/TeX

Development roadmap

• [x] Create directory structure
• [ ] Sort in examples from the scientific-thesis-template
• [ ] Have scientific-thesis-template generated completely.
• [x] Have LNCS generated completely.
• [x] Have uni-stuttgart-dissertation-template generated automatically.

In the long run, the contents of the paper.tex (and similar) files in repositories of the latextemplates organization should be generated automatically.

Development hints

• Templating language: https://ejs.co/
• Conditional questions: https://stackoverflow.com/a/18706640/873282.
• Types of prompts: https://github.com/SBoudrias/Inquirer.js#prompt-types
  • E.g., Question
• Add a new question
  • Also adapt __tests__/app.js
  • Execute tests with npx jest
• Update NPM dependencies
  • npx npm-update-all. See FreeCodeCamp for more details.
  • npx npm-check-updates -u. [Source]
  • See https://github.com/yeoman/generator/releases for changes in the generator.
  • Generate package-lock.json only: npm i --package-lock-only
• When one encounters Cannot find module 'yeoman-generator', please update the npm dependencies. That error occurred when using version 4.13.0 and 5.4.2 was available.
• In case of the error "Error: EACCES, permission denied '/root/.config/configstore/insight-yo.json'", one needs to execute chmod g+rwx /root /root/.config /root/.config/configstore
• Check GitHub actions
  • Use actionlint
  • Use vs.code GitHub actions plugin
  • Use act for checking: act --rm --platform ubuntu-latest=fwilhe2/act-runner:latest -W .github/workflows/check-ieee-conference-a4-pdflatex-bibtex-2023-true.yml
• When adding a new package use DEPP (see above) or execute following steps:
  1. execute npx with --generatereitzig (in a clean directory)
  2. run pdflatex
  3. run {repository-root}/generate-texlivefile.sh
  4. copy Texlivefile to the root of the {repository-root}/generators/app/templates
  5. adapt Texlivefile as required
• When issues with the template occur: npx ejs-lint main.en.tex
• Cancel workflows:
  • gh run list -L 100 --json databaseId -s queued -R latextemplates/generator-latex-template | jq -r '.[] | .databaseId' | awk '{gsub(/\\r\\n/,RS)} 1' | while read -r run_id; do gh run cancel "$run_id" -R latextemplates/generator-latex-template || true; done
  • gh run list -L 100 --json databaseId -s in_progress -R latextemplates/generator-latex-template | jq -r '.[] | .databaseId' | awk '{gsub(/\\r\\n/,RS)} 1' | while read -r run_id; do gh run cancel "$run_id" -R latextemplates/generator-latex-template || true; done
• Update submodule of "derived" templates (LNCS, ...): [ -z "$(git status --porcelain)" ] && cd generator-latex-template/ && git pull && cd .. && git add . && git commit -m"Update LTG" && git pull --rebase && git push

Testing

• All workflows test overleaf=no - and (nearly) all possible combinations.
• All *-refined repositories test with overleaf=true - and only the typical settings for the template.
• refine-ltg is the development branch for the template generator; only a small set of workflows enabled there due to load during testing.
• update-ltg is the development branch at each *-refined template.

Test locally

• Create empty directory ("target directory")
• Change to the target directory
• Run npx yo <path-to-git-repository>/generators/app/index.js. Background: Starting from 5.0.0 on, one needs to specify the full path to index.js.
• Windows: npx yo c:\git-repositories\latextemplates\generator-latex-template\generators\app\index.js

Linux

Parameters can be set using command line

• lncs: npx yo /tmp/repo/generators/app/index.js --documentclass=lncs --papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --texlive=2024 --docker=false --lang=en --font=default --listings=listings --enquotes=csquotes --tweakouterquote=babel --todo=pdfcomment --examples=true --howtotext=true

Windows

Parameters can be set using command line

• IEEE template (with pdflatex and bibtex): npx yo c:\git-repositories\latextemplates\generator-latex-template\generators\app\index.js --overleaf=false --documentclass=ieee --ieeevariant=conference --papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --texlive=2024 --docker=reitzig --lang=en --font=default --listings=listings --enquotes=csquotes --tweakouterquote=babel --todo=pdfcomment --examples=true --howtotext=true
• LNCS template (with pdflatex and bibtex): npx yo c:\git-repositories\latextemplates\generator-latex-template\generators\app\index.js --overleaf=false --documentclass=lncs ---papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --texlive=2024 --docker=false --lang=en --font=default --listings=listings --enquotes=csquotes --tweakouterquote=babel --todo=pdfcomment --examples=true --howtotext=true
• Scientific Thesis template: npx yo c:\git-repositories\latextemplates\generator-latex-template\generators\app\index.js --overleaf=false --documentclass=scientific-thesis --papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --texlive=2024 --lang=en --font=default --listings=listings --enquotes=csquotes --tweakouterquote=babel --todo=pdfcomment --examples=true --howtotext=true
• USTUTT template: npx yo c:\git-repositories\latextemplates\generator-latex-template\generators\app\index.js --overleaf=false --documentclass=ustutt --papersize=a5 --latexcompiler=lualatex --bibtextool=biblatex --texlive=2024 --lang=en --font=default --listings=listings --enquotes=csquotes --tweakouterquote=babel --todo=todonotes --examples=true --howtotext=true -- todonotes is the preferred TODO package here.

• Run latexmk to build the PDF

Using DEPP

To fire up a TeX Live installation and use the Dependency Printer for TeX Live to refine Texlivefile, execute following steps:

docker run -it --rm -v c:\temp\ltg:/ltg registry.gitlab.com/islandoftex/images/texlive:latest

cd /tmp
git clone https://gitlab.com/islandoftex/texmf/depp.git
cd depp
l3build install
cd /ltg
# edit paper.tex and add `\RequirePackage[dependency-file=Texlivefile]{depp}`
lualatex/pdflatex paper

Running reitzig

1. docker build --progress=plain -t reitzig -f Dockerfile .
2. docker run -it --rm -v c:\temp\ltg:/work/src -v c:\temp\ltg-out:/work/out reitzig work latexmk

Useful snippets

<% if (howtotext) { -%>
<% } else { -%>
<% } -%>

<% switch (documentclass) { case "lncs": -%>
<% break; case "ieee": -%>
<% break; default: -%>
<% break; } -%>

Debugging

A launch.json configured for Windows and Visual Studio Code is included. Just press F5 and the generator should run in debug mode.

ejslint.cmd c:\git-repositories\latextemplates\generator-latex-template\generators\app\templates\main.en.tex

Releasing a new version

1. Update CHANGELOG.md (change h2 heading etc.)

2. Update package.json, publish to npmjs, create GitHub release. Use release-it (do not create a release on GitHub) and github-release-from-changelog.

   • npx release-it
   • npx github-release-from-changelog

License

The code is licensed 0BSD, the snippets (both LaTeX and text) 0BSD, too. See benbalter/talks#15, for a reasoning, why CC0 cannot be used.

• generators/app/templates/splncs04nat.bst is taken from tpavlic/splncs04nat and is MIT-licensed.
• generators/app/templates/logos/: This directory contains logos, which have special licenses.