Additional Packages

[didi1357]

Hi,

I'd like to suggest some packages here which I'm using heavily:

• siunitx instead of units
• fancyref
• listings
• glossaries

I understand that you would like to keep this template as simple as possible, or that siunitx instead of units might be a matter of taste. However, if you would like me to add one of them, I'll create a pull request.

[novoid]

Oh, I feel your pain ;-)

On the one hand side, I'm not familiar any more with all this "don't use this old package any more because there's a better approach meanwhile" since I'm not actively using LaTeX myself for too many years. (Unfortunately.)

On the other hand side, I really want to stick to the basics where the chance is very high that anybody is using this package for a decent thesis. I guess my approach was that units are that general, that anybody would like to have them in his/her document. The other packages are really a great things to have especially for tech-based documents. As far as I remember, using the glossaries package was far from trivial and required to actually read its (great) manual. Therefore, I still hesitate to add this level of additional complexity to the template.

Please do reply if you do think that I should take into account more arguments from your side.

[didi1357]

Oh, I feel your pain ;-)

Mhm. I saw you moving people from bibtex to biber ;)

On the one hand side, I'm not familiar any more with all this "don't use this old package any more because there's a better approach meanwhile" since I'm not actively using LaTeX myself for too many years. (Unfortunately.)

But your reply to me on saturday night means you're at least still maintaining your template. 👍
At TU Graz some Professors/Institues suggest or even force people to use it. So yes. I think we should at least keep on talking about keeping your template up to date.

Regarding siunitx:
I expected that to be honest. Maybe units is even easier to learn and use than siunitx, as it leaves more responsibility to the user. For example, siunitx needs to know the document language and will take care about differences in english and german notation of numbers, ranges and so on.

Regarding fancyref:
It is the reason why prefixes like ch, fig are usually used for labels.
I guess a usage example producing the same output would be most helpful:
See figure~\ref{fig:test} on page~\pageref{fig:test}.
With fancyref:
See \fref{fig:test}.
Please keep in mind that people, especially beginners, tend to e.g. forget the ~ before \ref. So using fref would definitely increase the quality of texts written with your template.
Also: This is not just a simple newcommand macro. It e.g. knows if the reference is on the same page and will omit the "on page.." term.
Unfortunately this package also needs to know the language. Another reason for my request for a global language switch.

Regarding listings:
Yes, your're right.. It's just useful for tech documents. I understand if you would like to leave it out. On the other hand it won't hurt non-tech documents if it's included.

Regarding glossaries:
I'm using it with only two commands. In my opinion that's not really complex. This is what I put in the acronyms.tex:
\newacronym[shortplural=PCBs, longplural=printed circuit boards]{pcb}{PCB}{printed circuit board}
You could add it as an example in the template just like for biblatex. Then it's just a matter of copy and pasting and inserting the right terms for a user. TBH: I just copied that because I'm also not able to write that down without looking it up.

Within the text I'm using \gls{label} or \glspl{label} for the plural version. These are the only two commands I need to remember. Sure, the concept of labels must already be known to the user, but this needs to be known for cross references too.

The benefit is clear: The first occurence is describing, the others are just the short form with a link to the glossary. Just as you would have done by hand in any good paper.

[novoid]

Oh, I feel your pain ;-)

Mhm. I saw you moving people from bibtex to biber ;)

From my point of view, there was no option for bibtex to be part of a template that should last a couple of years. The pain with using bibtex for German references (Umlauts, ...) was bigger than the one-time pain for biblatex to be set up. From the perspective of a user within the LaTeX document, there was hardly any difference. So my choice was not that hard to make.

On the one hand side, I'm not familiar any more with all this "don't use this old package any more because there's a better approach meanwhile" since I'm not actively using LaTeX myself for too many years. (Unfortunately.)

But your reply to me on saturday night means you're at least still maintaining your template. +1

Sure.

At TU Graz some Professors/Institues suggest or even force people to use it. So yes. I think we should at least keep on talking about keeping your template up to date.

I was not aware of any significant number of people using my template until I began to work in a company in 2017. Most (younger) colleagues recognized my name from their master thesis template. And I was absolutely astonished. I thought my template was more or less forgotten. Almost no feedback. After that, I introduced the hall of fame so that people might add their document to it. Almost no feedback on this one as well so far.

Regarding siunitx:
I expected that to be honest. Maybe units is even easier to learn and use than siunitx, as it leaves more responsibility to the user. For example, siunitx needs to know the document language and will take care about differences in english and german notation of numbers, ranges and so on.

I have to take a look at siunitx as I've never heard of it before. Currently, I would hesitate to use something different. For units, it was a very close call that I included it to my template as it seems to be an edge-case when it comes to "helpful for the average document".

Regarding fancyref:
It is the reason why prefixes like ch, fig are usually used for labels.
I guess a usage example producing the same output would be most helpful:
See figure~\ref{fig:test} on page~\pageref{fig:test}.
With fancyref:
See \fref{fig:test}.
Please keep in mind that people, especially beginners, tend to e.g. forget the ~ before \ref. So using fref would definitely increase the quality of texts written with your template.
Also: This is not just a simple newcommand macro. It e.g. knows if the reference is on the same page and will omit the "on page.." term.
Unfortunately this package also needs to know the language. Another reason for my request for a global language switch.

Okay. I see the benefit. However, another issue with those fancy packages is that you hardly get help online as long as it is a cool but rarely known package. Another aspect of "sticking to the common standard" to keep in mind. :-(

Regarding listings:
Yes, your're right.. It's just useful for tech documents. I understand if you would like to leave it out. On the other hand it won't hurt non-tech documents if it's included.

True.

But at the same time I may use the argument "if only tech-savvy people use listings, why not assume they add it themselves?"

Regarding glossaries:
I'm using it with only two commands. In my opinion that's not really complex. This is what I put in the acronyms.tex:
\newacronym[shortplural=PCBs, longplural=printed circuit boards]{pcb}{PCB}{printed circuit board}
You could add it as an example in the template just like for biblatex. Then it's just a matter of copy and pasting and inserting the right terms for a user. TBH: I just copied that because I'm also not able to write that down without looking it up.

Within the text I'm using \gls{label} or \glspl{label} for the plural version. These are the only two commands I need to remember. Sure, the concept of labels must already be known to the user, but this needs to be known for cross references too.

The benefit is clear: The first occurence is describing, the others are just the short form with a link to the glossary. Just as you would have done by hand in any good paper.

I, too, used glossaries in my thesis. However, it requires the user to read the manual before she is able to use it properly. And this is where problems start for the average user.

How about that? Adding a chapter to the template documentation that describes how to add a selection of helpful packages like you describe? This way, the average user does not get confused too much and the advanced user gets ideas and directions on how to add nice packages or switch from a basic package to its fancy version.

This approach would not help you, I guess, since your aim seems to be to use my template as it is. However, as you might have noticed, my focus is the average LaTeX user which is not necessarily a tech person. I've held many LaTeX-workshops and taught over a hundred people how to start with LaTeX: secretaries, teachers, tech-documentation people, ...
Tech-savvy people are able to modify the template anyway. At least this was my mind-set so far.

A radical other approach would be that you'd fork my template and try to establish your advanced template as the new template in your environment. This would not hurt me much since you would still need to attribute my original version according to the license. I would gladly link to your template in my README file.

[didi1357]

From the perspective of a user within the LaTeX document, there was hardly any difference. So my choice was not that hard to make.

Setting the environment up with biber was harder some years ago, as not all distributions did ship with it by default. So in my opinion it was a "movement".

Almost no feedback. After that, I introduced the hall of fame so that people might add their document to it. Almost no feedback on this one as well so far.

This is because most people are too lazy or have too little time/free time for participating in open source movement. I think your template hit 3-digit user numbers a long time ago. I guess it's already reaching out for 4-digits. Just take a look at the stars/forks. I guess a lot of the people don't even have a github account. They just hit the download button and use it as is.

I, too, used glossaries in my thesis. However, it requires the user to read the manual before she is able to use it properly. And this is where problems start for the average user.

In my opinion it's not more manual dependent for a user than the citation system. It's probably less often used/needed. Maybe you could elaborate a bit more on the manual dependence you see?
Nevertheless, I'd still suggest to add it. Maybe with a boolean in Main.tex to enable/disable it's output. Users who are looking for a more slim document could just disable this output using that switch. The rest is provided with an acronyms.tex file including an example acronym without having to create that and look up the included command on their own.

How about that? Adding a chapter to the template documentation that describes how to add a selection of helpful packages like you describe? This way, the average user does not get confused too much and the advanced user gets ideas and directions on how to add nice packages or switch from a basic package to its fancy version.

Most likely the way to go for siunitx and listings. I can understand your decisions there. Maybe this is also the way to go for fancyref, because of missing popularity.

This approach would not help you, I guess, since your aim seems to be to use my template as it is.

Not exactly. I use your template merged with my additions now, but that's a completely different story and not the reason for me trying to introduce changes here.

However, as you might have noticed, my focus is the average LaTeX user which is not necessarily a tech person.

This would actually be a vote for fancyref I think :D Unfortunately only partly. On one hand it get's easier for users because they don't need to know/use the ~ and ref/pageref. On the other hand they need to be aware that fancyref needs e.g. the sec: prefix in the label. This is definitely something for the documentation.

A radical other approach would be that you'd fork my template and try to establish your advanced template as the new template in your environment. This would not hurt me much since you would still need to attribute my original version according to the license. I would gladly link to your template in my README file.

I have no environment to establish my template in :D I also don't really care for publicity or something like that. I care for having to tell less people, that MS Word is a bad idea for a thesis :D

[novoid]

I'll digest your input. Meanwhile I've put it on my project's list. I can not guarantee to work on that this year since I'm very busy with other tasks. I might as well start this conversation with you again, when I learned about those packages and decided which ones to add and which ones to add as documentation only. As you're being much into details here, I'm probably asking for your help or at least for your comments on anything that is resulting from this.

So far: thanks for your high-value contribution and let's continue to move people to LaTeX as smooth as possible. 👍

[didi1357]

I'd also be willed to contribute parts in form of a pull request, once you digged into the packages and are okay with them. Or a part of them or something like that. Just let me know here.

[novoid]

I'd also be willed to contribute parts in form of a pull request, once you digged into the packages and are okay with them. Or a part of them or something like that. Just let me know here.

That would be really cool.
How about separate pull requests for siunitx and listings for the start? I do think that those two are the most promising candidates to find their way into the template.

[didi1357]

Okay.. I'll start with siunitx, which brings me to the question:
What about the also suggested global language switch? I'd strongly recommend it as siunitx also needs to know the document language.. This would add a third to your two separate language switches..

Or would you like me to just add the package to the documentation only?

What if I just start with a pull request for the language switch first to show you how I'd implement it?

[novoid]

Sorry, this somehow slipped my mind and I forgot to answer.

Language switch: I just closed the issue and added my reasoning. For the current suggestion, I'd propose one area where language strings needs to be set like "lang-for-package-X", "lang-for-package-Y", and so forth. This seems to be not elegant IMHO. Maybe you do have another idea?

Documentation-only is a reasonable workaround here, yes.

[didi1357]

If a global language switch is not our desired way to go, the area approach with many variables is probably a good option, as it moves configuration into one block, while still allowing a huge amount of configurability... Certainly more than the single global language switch. There is just one downside which makes me a bit unhappy:

Suppose, I'm a user new to Latex. I don't know yet, that I'm setting template variables which will be supplied to corresponding packages as parameters. So to understand all that I need to understand the package parameters first and then understand that there is another level of indirection introduced by the template.

If there was a global language switch with reasonable defaults, that would probably be already enough for many users. They might never need to learn the package parameters used in the template, which would in turn lower the bar for newcomers. People who need a detailed setting will need to dig into the template and package options anyways. So they could also just configure these details somewhere in the template.

Regarding another idea: A completely different approach would be to force people to read up package parameters by not providing any kind of language-variables and just placing the \includepackage at a very eye-catching/demonstrative position. Advantage: New users would just need to read up the package documentation without having to dig into variable usages also.
Downside: They actually need to read up all that. This might be an overwhelming amount at the beginning. Also, include orders could clutter the otherwise "configuration-only-preamble-block".

To sum it up: We currently have a mix of using variables/indirection to ease and beautify configuration vs. not using these features to force people to read the documentation. From this point we can go into both above mentioned directions. The "right direction" is probably also a matter of taste and targeted audience of the template.