generator-latex-template 0.1.1 → 0.4.0

package/LICENSE

@@ -1,21 +1,14 @@
-MIT License
+BSD Zero Clause License
 
-Copyright (c) 2018-2019 Oliver Kopp <kopp.dev@gmail.com> (http://orcid.org/0000-0001-6962-4290)
+Copyright (c) 2018-2021 Oliver Kopp <kopp.dev@gmail.com> (http://orcid.org/0000-0001-6962-4290)
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 > Generates latextemplates (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.
+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.
 
 ## Background information
 
@@ -19,27 +19,36 @@ The aim of the repository is to provide for each common latex package
 
 and a generation into templates:
 
-1. Support for LNCS, IEEE, KOMA-Script
+1. Support for [ACM](https://ctan.org/pkg/acmart), [IEEE](https://ctan.org/pkg/ieeetran), LNCS, [KOMA-Script](https://ctan.org/pkg/koma-script)
 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
+- [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
 
 ## Usage
 
+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.
+
+On Linux, 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`
 
-You can install `generator-latex-template` using following command:
+In case one wants to have the generator installed permanently or `npx` does work as exepcted, one can install `generator-latex-template` using following command:
 
 ```bash
-npm install -g yo generator-latex-template
+npm install -g generator-latex-template
 ```
 
 ### Using the generator
 
-You can run the generator by invoking this command on a command prompt:
+One can run the generator by invoking this command on a command prompt:
 
 ```bash
 yo latex-template
@@ -47,46 +56,40 @@ yo latex-template
 
 ## How to update the document
 
-!! The template generator overwrites `main.tex` on each run and will destroy your work.
+⚠️ 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 master` switch back to your thesis
+   - `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 `master` branch
+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 master` - switch to your work
-  - `git merge template` - merge in the template changes
-  - resolve conflicts ^^ (Hint: IntelliJ Community Edition has a [great conflict resolving tool](https://www.jetbrains.com/help/idea/resolving-conflicts.html#))
-
-<!--
-#### Generator Output
-
-Use this section for documenting what your generator actually will generate.
--->
+   - `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](https://www.jetbrains.com/help/idea/resolving-conflicts.html#))
 
 ## Resources
 
-- [IEEE](https://latextemplates.github.io/IEEE/) - example: [paper-conference-minted.tex](https://github.com/latextemplates/IEEE/blob/master/paper-conference-minted.tex)
-- [LNCS](https://latextemplates.github.io/LNCS/) - example: [paper.tex](https://github.com/latextemplates/LNCS/blob/master/paper.tex)
-- [scientific-thesis-template](https://latextemplates.github.io/scientific-thesis-template/) - example: [latexhints-english.tex](https://github.com/latextemplates/scientific-thesis-template/blob/master/latexhints-english.tex)
+- [IEEE](https://latextemplates.github.io/IEEE/) - example: [paper-conference-minted.tex](https://github.com/latextemplates/IEEE/blob/main/paper-conference-minted.tex)
+- [LNCS](https://latextemplates.github.io/LNCS/) - example: [paper.tex](https://github.com/latextemplates/LNCS/blob/main/paper.tex)
+- [scientific-thesis-template](https://latextemplates.github.io/scientific-thesis-template/) - example: [latexhints-english.tex](https://github.com/latextemplates/scientific-thesis-template/blob/main/latexhints-english.tex)
 - [alpenwasser/TeX](https://github.com/alpenwasser/TeX)
 
 ## Development roadmap
 
-1. Create directory structure
-2. Sort in examples from the [scientific-thesis-template](http://latextemplates.github.io/scientific-thesis-template/)
-3. Have scientific-thesis-template generated completely.
-4. Have LNCS generated completely.
-5. Have [uni-stuttgart-dissertation-template](https://github.com/latextemplates/uni-stuttgart-dissertation-template) generated automatically.
+- [x] Create directory structure
+- [ ] Sort in examples from the [scientific-thesis-template](http://latextemplates.github.io/scientific-thesis-template/)
+- [ ] Have scientific-thesis-template generated completely.
+- [x] Have LNCS generated completely.
+- [ ] Have [uni-stuttgart-dissertation-template](https://github.com/latextemplates/uni-stuttgart-dissertation-template) generated automatically.
 
 In the long run, the contents of the `paper.tex` (and similar) files in repositories of the [latextemplates](https://latextemplates.github.io/) organization should be generated automatically.
 
@@ -94,7 +97,65 @@ 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 questions: <https://github.com/SBoudrias/Inquirer.js#prompt-types>
+- Types of prompts: <https://github.com/SBoudrias/Inquirer.js#prompt-types>
+  - 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 --texlive=2021 --latexcompiler=pdflatex --bibtextool=bibtex --docker=false --language=en --font=default --listings=listings --cleveref=true --enquotes=csquotes --tweak_outerquote=babel --todo=pdfcomment --howtotext=true --examples=true`
+    - Windows: `npx yo c:\git-repositories\latextemplates\generator-latex-template --documentclass=scientific-thesis --texlive=2021 --latexcompiler=pdflatex --bibtextool=bibtex --docker=false --language=en --font=default --listings=listings --cleveref=true --enquotes=csquotes --tweak_outerquote=babel --todo=pdfcomment  --howtotext=true --examples=true`
+    - Windows automatic generation of a LNCS template (with pdflatex and bibtex): `npx yo c:\git-repositories\latextemplates\generator-latex-template --documentclass=lncs --texlive=2021 --latexcompiler=pdflatex --bibtextool=bibtex --docker=false --language=en --font=default --listings=listings --cleveref=true --enquotes=csquotes --tweak_outerquote=babel --todo=pdfcomment --howtotext=true --examples=true`
+  - Run `latexmk` to build the PDF
+- 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.
+- When one encounters `Cannot find module 'yeoman-generator'`, please update the npm dependencies.
+  That error ocurred 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`
+  2. run `pdflatex`
+  3. run `.../generate-texlivefile.sh`
+  4. copy `Texlivefile` to the root of the source repository
+  5. adapt `Texlivefile` as required
+
+### Useful snippets
+
+```ejs
+<% if (howtotext) { -%>
+<% } else { -%>
+<% } -%>
+```
+
+```ejs
+<% switch (documentclass) { case "lncs": -%>
+<% break; case "ieee": -%>
+<% break; default: -%>
+<% break; } -%>
+```
+
+```ejs
+<% if (cleveref) { %>\cref<% } else if (documentclass == 'lncs') { %>Sect.~<% } else { %>Section~<% } %>{sec:relatedwork}
+```
+
+### Debugging
+
+A `launch.json` configured for Windows and Visual Studio Code is included.
+Just press <kbd>F5</kbd> and the generator should run in debug mode.
+
+```terminal
+ejslint.cmd c:\git-repositories\latextemplates\generator-latex-template\generators\app\templates\main.en.tex
+```
 
 ### Releasing a new version
 
@@ -102,10 +163,16 @@ In the long run, the contents of the `paper.tex` (and similar) files in reposito
 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).
 
+   - `npx release-it`
+   - `npx github-release-from-changelog`
+
 ## License
 
-The code is licenced MIT, the snippets (both LaTeX and text) [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).
+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.
+
+[hyperref]: https://ctan.org/pkg/hyperref
+[listings]: https://ctan.org/pkg/listings
+[minted]: https://ctan.org/pkg/minted
 
-  [hyperref]: https://ctan.org/pkg/hyperref
-  [listings]: https://ctan.org/pkg/listings
-  [minted]: https://ctan.org/pkg/minted
+<!-- markdownlint-disable-file MD013 MD033 -->