generator-latex-template 0.7.0 → 2025.1.14

package/README.md

@@ -2,7 +2,10 @@
 
 > Generates latex templates (e.g., for thesis, workshops, conferences, IEEEtran, LNCS, ...) out of "micro-templates"
 
-See the **[talk about the generator](https://github.com/dante-ev/Vortraege_Tagungen/blob/master/2019-Herbst/Oliver%20Kopp%20-%20The%20LaTeX%20Template%20Generator%20-%20dante2019-herbst.pdf)** for an overview on the aims and the general concept.
+## Talks and papers
+
+- Paper: [Oliver Kopp - The LaTeX template generator: How micro-templates reduce template maintenance effort](https://tug.org/TUGboat/tb44-2/tb137kopp-microtemplates.html)
+- Talk: [Oliver Kopp - The LaTeX Template Generator - DANTE Herbsttagung 2019](https://github.com/dante-ev/Vortraege_Tagungen/blob/master/2019-Herbst/Oliver%20Kopp%20-%20The%20LaTeX%20Template%20Generator%20-%20dante2019-herbst.pdf) - a talk on the motivation, user experience, and the contribution
 
 ## Background information
 
@@ -23,32 +26,28 @@ and a generation into templates:
 2. Support for separate documents which require `--shell-escape` and not.
 3. Support for integrated pdflatex and lualatex documents
 
-## Talks
-
-- [Oliver Kopp - The LaTeX Template Generator](https://github.com/dante-ev/Vortraege_Tagungen/blob/master/2019-Herbst/Oliver%20Kopp%20-%20The%20LaTeX%20Template%20Generator%20-%20dante2019-herbst.pdf) - a talk on the motivation, user experience, and the contribution
+### Precondition for the generator
 
-## Usage
+One has to install [Node.js](https://nodejs.org/en/) version 18 (or later) to get this generator running.
+For simple installation, just head to <https://nodejs.org/> and follow the installation instructions.
 
-One has to install [Node.js](https://nodejs.org/en/) version 14 to get this generator running.
-On Windows, one can just run `choco install nodejs-lts` to get the right version of Node.js.
+### Using the generator
 
-On Linux, one can start using the generator directly using the node execution wrapper [npx](https://www.npmjs.com/package/npx):
+One can start using the generator directly using the node execution wrapper [npx](https://www.npmjs.com/package/npx):
 
 ```bash
 npx -p yo -p generator-latex-template -c 'yo latex-template'
 ```
 
-### Installing `generator-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:
+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:
 
 ```bash
 npm install -g generator-latex-template
 ```
 
-### Using the generator
-
-One can run the generator by invoking this command on a command prompt:
+Then, one can invoke the generator as follows:
 
 ```bash
 yo latex-template
@@ -98,36 +97,81 @@ In the long run, the contents of the `paper.tex` (and similar) files in reposito
 - 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](https://github.com/SBoudrias/Inquirer.js#question)
+  - E.g., [Question](https://github.com/SBoudrias/Inquirer.js#question)
 - Add a new question
   - Also adapt `__tests__/app.js`
   - Execute tests with `npx jest`
-- Test locally
-  - Create empty directory ("target directory")
-  - Change to the target directory
-  - Run `npx yo <path-to-git-repository>`
-    - Windows: `npx yo c:\git-repositories\latextemplates\generator-latex-template`
-  - Parameters can be set using command line
-    - Linux: `npx yo /tmp/repo --documentclass=lncs --papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --overleaf=false --texlive=2022 --docker=false --language=en --font=default --listings=listings --enquotes=csquotes --tweak_outerquote=babel --todo=pdfcomment --examples=true --howtotext=true`
-    - Windows: `npx yo c:\git-repositories\latextemplates\generator-latex-template --documentclass=scientific-thesis --papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --overleaf=false --texlive=2022 --language=en --font=default --listings=listings --enquotes=csquotes --tweak_outerquote=babel --todo=pdfcomment --examples=true --howtotext=true`
-    - Windows automatic generation of a LNCS template (with pdflatex and bibtex): `npx yo c:\git-repositories\latextemplates\generator-latex-template --documentclass=lncs ---papersize=a4 --latexcompiler=pdflatex --bibtextool=bibtex --overleaf=false --texlive=2022 --docker=false --language=en --font=default --listings=listings --enquotes=csquotes --tweak_outerquote=babel --todo=pdfcomment --examples=true --howtotext=true`
-  - Run `latexmk` to build the PDF
-- Update npm dependencies
+- Update NPM dependencies
   - `npx npm-update-all`. See [FreeCodeCamp](https://www.freecodecamp.org/news/10-npm-tricks-that-will-make-you-a-pro-a945982afb25/) for more details.
   - `npx npm-check-updates -u`. [[Source](https://www.carlrippon.com/upgrading-npm-dependencies/)]
   - 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](https://github.com/rhysd/actionlint#readme)
   - Use [vs.code GitHub actions plugin](https://marketplace.visualstudio.com/items?itemName=cschleiden.vscode-github-actions)
-- When adding a new package:
-  1. execute `npx` with `--generatereitzig`
+  - Use [act](https://github.com/nektos/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 `.../generate-texlivefile.sh`
-  4. copy `Texlivefile` to the root of the source repository
+  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" || 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" || 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`
+
+### 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](https://github.com/yeoman/yo/issues/797#issuecomment-2541794625).
+- 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.
+
+<!-- markdownlint-disable-next-line MD004 -->
+* Run `latexmk` to build the PDF
+
+##### Using DEPP
+
+To fire up a TeX Live installation and use the [Dependency Printer for TeX Live](https://gitlab.com/islandoftex/texmf/depp) to refine `Texlivefile`, execute following steps:
+
+```cmd
+docker run -it --rm -v c:\temp\ltg:/ltg registry.gitlab.com/islandoftex/images/texlive:latest
+```
+
+```bash
+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
 
@@ -155,7 +199,7 @@ ejslint.cmd c:\git-repositories\latextemplates\generator-latex-template\generato
 
 ### Releasing a new version
 
-1. Update `CHANGELOG.md`
+1. Update `CHANGELOG.md` (change `h2` heading etc.)
 2. Update `package.json`, publish to [npmjs](https://www.npmjs.com/package/generator-latex-template), create GitHub release.
    Use [release-it](https://www.npmjs.com/package/release-it) (do not create a release on GitHub) and [github-release-from-changelog](https://www.npmjs.com/package/github-release-from-changelog).
 
@@ -167,7 +211,8 @@ ejslint.cmd c:\git-repositories\latextemplates\generator-latex-template\generato
 The code is licensed [0BSD](https://choosealicense.com/licenses/0bsd/#), the snippets (both LaTeX and text) 0BSD, too.
 See [benbalter/talks#15](https://github.com/benbalter/talks/issues/15#issuecomment-599704662), for a reasoning, why [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) cannot be used.
 
-`generators/app/templates/splncs04nat.bst` is taken from [tpavlic/splncs04nat](https://github.com/tpavlic/splncs04nat) and is MIT-licensed.
+- `generators/app/templates/splncs04nat.bst` is taken from [tpavlic/splncs04nat](https://github.com/tpavlic/splncs04nat) and is MIT-licensed.
+- `generators/app/templates/logos/`: This directory contains logos, which have special licenses.
 
 [hyperref]: https://ctan.org/pkg/hyperref
 [listings]: https://ctan.org/pkg/listings