Document .dtx vs. .cls

[koppor]

This template uses the .dtx procedure to generate the files such as lni.cls. PRs, however, touch the files directly (e.g., #104). In case such a PR is merged, the template distribution process undoes the changes.

Example:

-  \vskip -27pt% Abstand vor dem Titel
+  \vskip -24pt% Abstand vor dem Titel

We should document explain how the whole system works (https://tex.stackexchange.com/q/344530/9075; https://www.texdev.net/tags/#dtx), put make it optional to contributors. After a PR, the maintainers have to adapt the .dtx.

Alternatively, we could remove the generated files from the .dtx. This, however, would make the whole package inconsistent with "typical" .dtx usage.

CC @csware

[sieversMartin]

If we stick to the dtx-approach, this should be the file to be edited. The CONTRIBUTING.md should clearly state this IMHO.
Maybe we could then establish a workflow/check for a pull request, which tests for changes in the dtx file, calls latex lni.ins and then merges the files. Is that even possible @koppor?

[koppor]

Sure, we can do a merge.

And then manually "backporting" to .dtx?

[sieversMartin]

Well, no. I thought of getting contributors to only modify the dtx file :-)

[koppor]

Discussion notes:

Maybe, we should move away from dtx

I0002   Checking package files in directory lni/
E0019   lni/lni-author-template.tex generated by lni/lni.dtx exists
E0019   lni/lni-paper-example-de.tex generated by lni/lni.dtx exists
E0019   lni/lni-paper-example-de.bib generated by lni/lni.dtx exists

We currently just concatenate files in the dtx and do not use some of the "fancy" features of dtx (resuing things across generated files, ...).

I think, it is easier for contributors to modify .cls, .tex directly instead of diving into the dtx file.

[csware]

Another alternative would be to not have the .cls files in the repository but generated them, e.g. in a CI job, and offer those as releases...

What do other tx packages do?

The process should not be over-engineered....

[sieversMartin]

Well, as said before dtx is the classical way of doing it. However, I agree, that it makes things more complicated at some points. Many contributors don't know about using a dtx file. As it remains standard for CTAN as well, I prefer your last suggestions, i.e. having only a .dtx file and and .ins file in the repo and generating everything else for the packaging.

[koppor]

Another alternative would be to not have the .cls files in the repository but generated them, e.g. in a CI job, and offer those as releases...

Yes.

My gut feeling is follows:

• For intermediate TeX users, the concept of .dtx is not obvious.
• The development process is more complicated (code and fix enabled by another compiler step).
• Editors don't support DTX out of the box (https://tex.stackexchange.com/q/31004/9075)
• Syntax of DTX is different from TEX (percent signs at the beginning)
• DTX is used by package authors if they are more into the tex world - "plain" packaging is used by people not seeing beneifts of using dtx

---

If we switch to dtx, we will not have the .tex example files in this repository and more. They will only be on github pages. Making contributions to authors templates (e.g., fixing typos, adding some notes) cumbersome.

Question: Will we loose any contributor if we use DTX? Is there anyone wanting to support but being pushed back by seeing DTX? If I remember my old TeX times, I would have been pushed back. But maybe, I am a unicorn and all others either do no code contribution or are OK by updating DTX.

We just need to decdie. And since martin votes for .dtx, I will change the whole workflow accordingly.