PDF Examples to check for compilation errors

[fprott]

May I propose to add an folder of compiled pdf examples to the repo? Just plain examples like already available here. That way the user can check if the compiled document looks actually as intended.

An example, I currently have a few bugs with the latex compiler. Nothing serious, just a broken bibliography and odd spaces. However now I have the problem that I have to assume that the archived version is still the same then the current version. Also I have to find that archived version.

If these examples would be maintained directly in the repo people could easier compare and find the examples.

[TeXhackse]

I can't follow the link because I am an external.

The PDF examples exist, just not in the repo. because It's never a good idea to add compiled material to a git repo.

I don't get the point of using PDFs to find compiler issues, because usually that's the task of the logfile, but if this helps,you can find the PDFs for the release in the CTAN bundle (https://github.com/tudace/tuda_latex_templates/releases/latest/) Or single files directly on CTAN: https://ctan.org/pkg/tuda-ci

I hope this helps.

[StefanFabian]

The PDF examples exist, just not in the repo. because It's never a good idea to add compiled material to a git repo.

That's not true. It's usually a bad idea to add compilation products to a git repo as they frequently change but manually adding a small compiled example is absolutely not a bad practice. Also, if those examples are not linked in the readme, they might as well not exist. Maybe the CTAN page should be linked in the readme as a suggestion where to find compiled pdfs that can be used to check whether the local installation works correctly (Though I haven't had the experience that they would compile but render incorrectly as could happen with an installation of the old template).

[schoeps]

@TeXhackse I guess we could set up a free runner (I use circleci for this) and push the PDFs to a doc branch? The infrastructure is already in place (docker image and your release scripts). This makes sense since the repo is typically one release ahead of CTAN. But I'd agree that this does not have very high priority.

[TeXhackse]

That's not true. It's usually a bad idea to add compilation products to a git repo as they frequently change but manually adding a small compiled example is absolutely not a bad practice.

They would change, because dependencies might change. This is why I'd prefer to add them with the release. I can of course add a link to the files directly. Still I don't get the requirement, as they are installed by TeX Live/MikTeX to the doc tree of your TeX distribution.

But I will add an additional link to the GitHub version of the README for the CTAN reference.

@schoeps The problem with a CI setup will be, that we create a bunch of copies which are not necessary. I'd rather prefer to directly add the PDFs to the release tag. Which I think can be okay, but I still don't really see a requirement, because the log files should give information on that.

[schoeps]

I agree that there is no need to add the PDFs for the releases because they will be at CTAN. Maybe it's also sufficient to just add the CTAN link to each example as a comment? Either way, I agree that the files should not be in the main branch.

[StefanFabian]

Still I don't get the requirement, as they are installed by TeX Live/MikTeX to the doc tree of your TeX distribution.

You should not forget that most people using this template are not very knowledgeable in LaTeX and I doubt they would know where to look for the docs if they even knew they existed. Same goes for the CTAN entry. I did not think of checking that and while I'm certainly not proficient, I do have a few years of experience with LaTeX. The first place they will go looking for example pdfs is this repository. A link to the CTAN in the readme and perhaps as @schoeps suggests in the corresponding example tex file would probably help a lot.

[fprott]

Still I don't get the requirement, as they are installed by TeX Live/MikTeX to the doc tree of your TeX distribution.

You should not forget that most people using this template are not very knowledgeable in LaTeX and I doubt they would know where to look for the docs if they even knew they existed. Same goes for the CTAN entry. I did not think of checking that and while I'm certainly not proficient, I do have a few years of experience with LaTeX. The first place they will go looking for example pdfs is this repository. A link to the CTAN in the readme and perhaps as @schoeps suggests in the corresponding example tex file would probably help a lot.

That is exactly what I mean. The average student starts using latex when he is writing his bachelor thesis. He has no idea about the log files, he has no idea about the distribution and most importantly he has no idea how to deal with errors. He downloads / installs the package and then clicks on build.

Most latex projects I worked on had one or two errors. In fact this one has two errors out of the box (Misplaced alignment tab character &. \end and Underfull \hbox (badness 10000) in paragraph, both on an empty example). The most common approach, especially close to the deadline, is to just check if something breaks the layout. Why? Because Latex bug-hunting is very time consuming. Also next to impossible for students who are not that skilled with computers. Given the many none technical faculties at the TU, my bleak look on humanity and the fact that I don't understand Latex myself I would say that most students do not know how to deal with that problem or what the CTAN is. I am not saying this is good behavior or should be supported. I am saying that this is just the reality and there is nothing one can do to prevent this behavior next to making latex training mandatory, which I would fully support.

But the problem is even worse if nothing is wrong. The professor might remember an older version of the document. If you present him with the current version he might ask if the spacing is broken or if the design is the wrong style. How can you verify that? How can you answer him? Just because you can't see the problem doesn't mean that there is no problem.

Therefore I believe that a simple pdf that shows how the layout should look like would improve the project. It allows students who don't understand latex to check if they even need assistance.

However I can see the need for not cluttering the main branch. I do not fully support it, after all I believe documentation and tests like the README.md belong to the code (what else is such an example file but visual documentation or a visual test to confirm that everything works). But at least links to such pdfs would be nice.

[TeXhackse]

Okay, I get that point. And as I already said, I'll add links for the PDFs.

Why? Because Latex bug-hunting is very time consuming. Also next to impossible for students who are not skilled with computers.

I thought students might receive at least a simple introduction to the TeX & Friends Ecosystem. Because the template for me was not meant to describe the basic usage of LaTeX. The universities I visited/taught at always had workshops on this to get the basics. Especially with a focus on debugging LaTeX.

I usually achieve a lot with a 20 Minute workshop on this and explaining how TeX output should be read. But sure … sadly not everyone sees the requirement of handling it.

My problem with this usually is, that I think it's dangerous to support users too much in doing a “visual” debugging. Because this will not make them start reading their logs. On the long term it's much easier to work with the log files. Especially because you train yourself to stick to the markup.

editet: sorry for the lots of typos

[schoeps]

Especially with a focus on debugging LaTeX.

We seem to know very different universities. I know the latex courses of at least three different universities and nobody talked ever sufficiently about debugging or log files (by the way: also all my programming lectures that I ever attended disregarded this topic). I am not saying that this is good though...

[fprott]

Okay, I get that point. And as I already said, I'll add links for the PDFs.

Why? Because Latex bug-hunting is very time consuming. Also next to impossible for students who are not skilled with computers.

I thought students might receive at least a simple introduction to the TeX & Friends Ecosystem. Because the template for me was not meant to describe the basic usage of LaTeX. The universities I visited/taught at always had workshops on this to get the basics. Especially with a focus on debugging LaTeX.

I usually archieve a log with a 20 Minute workshop on this and explaining how TeX output should be read. But sure … sadly not everyone sees the requirement of handling it.

My problem with this usually is, that I think it's dangerous to support users too much in doing a “visual” debugging. Because this will not make them start reading their logs. On the long term it's much easier to work with the log files. Especially because you train yourself to stick to the markup.

I can only speak knowing a small part of the engineering department but there simply is no mandatory (or even with CP rewarded) latex course that I know of. There are workshops but most people do not know about those. Also the need to use latex arises during a time where you have a lot on your plate (thesis deadline) so everything that requires time is of the table.

I know that this is in no way optimal, it just is that way for many students that I know of.

[TeXhackse]

I just wanted to do this, but when typing the text for the README I was wondering, how people get this Information. Because if people install the bundle using tlmgr or MikTeX they will not even see this.

I now added it to the README and to the License information of the DEMO files. Would be glad, if one of you could take a look.

And to get back to the OffTopic of LaTeX-Courses: Debugging is the easiest to teach. This is why I am always confused, people don't include this in their courses. If you know people offering those intros I can always try to help with preparation of a small debugging session. Easiest way to save time.

[fprott]

I just wanted to do this, but when typing the text for the README I was wondering, how people get this Information. Because if people install the bundle using tlmgr or MikTeX they will not even see this.

I now added it to the README and to the License information of the DEMO files. Would be glad, if one of you could take a look.

And to get back to the OffTopic of LaTeX-Courses: Debugging is the easiest to teach. This is why I am always confused, people don't include this in their courses. If you know people offering those intros I can always try to help with preparation of a small debugging session. Easiest way to save time.

Usually people find the information via the TU website. I strongly advice to put the link there. Most people do not know about MikTeX or even latex before visiting the site. Please be advised, there are several sides about Latex. I can not tell which is the "official" or "current" one.

Latex is something that is usually not taught at all. The first time most students are confronted with it is during their thesis.

[TeXhackse]

@fprott okay then. That's not my job.

@marklaz: It's your turn I guess. But I can also write an email to the shown contact address. Just guess it will be easier if an intern does ;-)

[schoeps]

I now added it to the README and to the License information of the DEMO files. Would be glad, if one of you could take a look.

I guess people find the tex examples files mostly using google (not on their harddisk disk) so I would have recommended to put a direct link in ea h tex-file to ctan? You don't like it? What do you think?

[TeXhackse]

That's what the license Info of the demo files does. So i did this already. But during an online search people will find the pdf before the code anyway.

[TeXhackse]

I remove the milestone, because the release has been done, and I am waiting for @marklaz to close this when the information is added on the webpage.