59

This question is intended to be something reference-like to point users of complex templates they do not fully understand to.

After having read What is a template? it should be clear what a template is. Many questions here deal with rather complex templates (e.g. for thesis writing) and users ask how to modify a specific template. Often they are suggested not to use the template at all, but write up a document from scratch.

Why should users avoid using those complex templates or, if you see it the other way around, when should templates be used?

  • @CarLaTeX Thanks. Do you have any other suggestions why not to use those templates? – TeXnician Sep 10 '17 at 8:03
  • 10
    Templates are evil Period! They are often a merge of hacks from many people that have no idea of typography and TeX/LaTeX at all. – user31729 Sep 10 '17 at 10:14
30

I'm a user. I have no idea of TeX, plus neither of Lua nor of »expl3«.

I'm a user. I made an installation of texlive or MikTeX on my computer. I read an introduction to LaTeX and learned about some basic packages as well as about what an editor is, why encoding is necessary and about babel / polyglossia. I'm skimming through the manual of every package I'm loading (texdoc packagename on the command line produces the manual). If I encounter an issue, I'm able to produce a minimal working example and get help.

If I were a template user, I'd have missed much of that. No idea how to discern flagship packages from unmaintained stuff. No way to produce a minimal working example and get help.

Starting with LaTeX with a complex template is like downhill racing on a mountain bike without having ever learned how to cycle on a bike: Hell.

  • 4
    Au contraire. Do you have to know C++ to use Chrome? This is actually the basic problem about LaTeX2(e) that the LaTeX3 team is trying to address: a clear distinction of the several layers involved when producing documents via LaTeX. In LaTeX2e those layers highly interfer by design. Nevertheless it must be possible to write a working template in which the user can simply input his content and customise a few things easily if needed. – Ruben Sep 11 '17 at 14:31
  • 2
    I accepted your answer, because it's a great non-TeXnical view on this matter with some tips how to learn to avoid templates. – TeXnician Sep 12 '17 at 10:00
  • 3
    @Ruben - "it must be possible to write a working template in which the user can simply input his [her??] content and customise a few things" -- It already exists: it's the set of basic document classes: article, report, and book. :-) – Mico Sep 13 '17 at 5:51
  • 1
    @Mico - hahaha. ok, darn. you got me. I have to reconsider everything I wrote so far ;) – Ruben Sep 13 '17 at 6:52
  • Are you implying that downhill billies know how to cycle? Having said that, I always ask my students to use standard templates and usually try to remove their bad (la)tex habits in iterations. – Oskar Limka Nov 14 '18 at 15:36
52

To start with a quote (from Wikibook):

If a friend of yours wants to give you his/her template, it is a very nice gesture. Say Thanks, but no, Thanks. You won't believe how many strange stuff is in there without him/her even noticing it. All those are little tripwires that you don't want in your document. Unfortunately, the same is true for many templates you can find online.

The following text summarizes some common points. (In the following text the term "template" is meant for every piece of code you'll find out there providing a full-featured TeX document which just misses the content and, of course, those custom document classes you'll find everywhere.)

Deprecated commands

Many templates you'll find are built on the command set of LaTeX 2.09. That includes commands like \bf etc. which should not be used in recent documents. Those old commands may cause some harm especially working with some document classes (see, e.g., KOMA) you may want to use.

Bugs

Many templates have crashingly bad code, often from using packages and classes that are incompatible with one another. (classicthesis is a prime example.)
above sentence taken from a comment by Alan Munn

In addition some problems with maintenance may occur as there are templates that were published once, but are not maintained anymore. If you encounter bugs (bugs are not not modification requests) in such a template, you may have to solve them on your own.

Single-purpose templates

Another problem with templates is that you will find many templates made on purpose. So a thesis template for university X probably meets the style requirements of university X, but not Y. You should not even try to use it at Y, because most templates do not want you to modify them.

Overload of packages

Many templates also tend to load a whole bunch of packages. Some of them aren't even needed and some of them may clash with packages you need to use. You could try to rewrite or delete parts of the template, but that's cumbersome.

Predefined structure and dependencies

Some templates (especially for bigger projects) also force you to use a specific file and folder layout, because they link to an image file or a file in another directory. Sometimes templates even include a reference to a package which is not distributed with all distributions, but only some (or has to be downloaded).

It's getting even worse if the name of the template clashes with other packages (or if it's too general like thesis.cls).

Problems in typography

As in every other subject you should understand what you're doing. Some templates change typographic conventions and want to force you to some specific style. That's especially problematic as typography differs around the world. American style is not always applicable in Germany, for example.

Mostly it's better if you learn how to present your data (which is also important) in the traditions of your country's typography (look, e.g., at booktabs etc.).

Suggestion

Do not use a (complex) template if you do not have to. If you're studying at a university forcing you to use a specific template, you should use it, but if you're free to choose your style, just start off with a very basic document and spend some time learning LaTeX to get the style you want without using a complex template which does not suit exactly your needs.

  • 4
    +1 This is a great answer, especially points 1 and 3 which probably account for most of the problems we see in templates. Although you forgot one other thing: bugs. Many templates have crashingly bad code, often from using packages and classes that are incompatible with one another. (classicthesis is a prime example.) – Alan Munn Sep 11 '17 at 20:34
42

I'm a template user ...

I'm using them constantly: When I write a letter, I use an older one as template. At every project my first step is to look if I have or know about some older code that I could use as a starting template. Quite often the templates I use are not good – they are old, sometimes buggy, or they don't really fit. Many of my templates are rather complex. They nevertheless save me time: I don't have to retype everything, I don't have to wade through documentations to find out command names and syntax, I can reuse ideas.

So I don't find it very convincing to tell people not to use templates at all.

... but I have the knowledge to handle the templates

And this is imho the main point: Many users use templates to avoid having to learn LaTeX and read some documentation. This almost never works.

So if you want to use a (rather complex) template or a local custom class:

Imagine that you get a fatal error and nothing compiles, or that someone tells you to change the header or the bibliography style, or that you realize in the middle of your work that something in the template doesn't fit your needs. Consider if and how you can handle such a problem.

If the answer is one of these

  • I know enough about LaTeX to debug or adapt the template.
  • I have a friend with enough knowledge who will help me.
  • I have access to some professional support that will help me.
  • I understand enough of the template and of LaTeX to be able to build a minimal example and ask on tex.SX or some other help site.

Then go along and use the template if you like it. If you are relying on external support for problems perhaps ask them first if they recommend the template.

If the answer is

  • in case of problems I will put everything in a zip file on the net and then hope to find some stranger who spends a few hours to disentangle everything for free.

Then you had better reconsider the use of the template. Even if you find help you seldom find it fast as there are far less people around who are willing to spend that much time on a problem and often you get the help only after a lot of begging and disagreeable discussions about why you use a template that you can't handle.

If the answer is

  • I won't get problems – the template is perfect.

Good luck.

  • 9
    This is probably the most useful and truthful answer so far. – Johannes_B Sep 12 '17 at 13:28
  • Very good answer, gets exactly to the truth of the matter. – A Feldman Sep 18 '17 at 12:11
17
Disclaimer: This is the Advocatus Diaboli writing.

Personally, I also fully agree with the point of @TeXnician. There is so much value in building up a document from scratch. Fitting it to it exact needs. And learning new things in that process.

But, I think this misses a few things as it describes a very specific kind of LaTeX user. There are for sure people who want to use the system without learning very much about it - I think the whole spectrum is present. And this should be OK! Hence why LaTeX templates should not be avoided by users.

To be fair: the current state of template use is quite a disaster. There are so much undocumented, unmantained and fully overloaded templates containing bad hacks. And on the other hand there are users who pick them. And since I am firmly convinced that this question won't be able to stop template use here is a set of advice to users who are inclined to use templates: 1) Check if there is documentation for the template or at least some comments in the code. 2) Check if someone is taking care of keeping the template up to date and avoid using templates by John Doe, version 'I simply uploaded this to the internet, good luck...' 3) Check for unnedded packages. This might be hard to judge in the beginning and will most likely require a few minutes of reading. A (really rough) rule of thumb is: If there are more than 20 packages loaded by default beneath each other there might be stuff you won't need at all. 4) Check for bad hackery. Probabilly the most hard to assess. Maybe consult your local TeXnician for that :)

Apart from that it could be beneficial to declare guidelines for template authors and to have some kind of certificate for authorised LaTeX-template-writers. The guidelines are quite obvious, I think:

  • The format: .sty or .cls (IMO this should be limited even to packages only) with an according .tex file setting it up.
  • A Meaningful name to make it easy distinguishable for users (as for the comment of @samcarter)
  • Healthy balance of generalisation and specific features
  • Maintained version on CTAN
  • Presence of a documentation

Ideally, new users would then be pointed to those templates in the LaTeX starter guide and briefed that other templates should not be used - but this is really more about TeX politics, which I honestly do not know much about...

  • @TeXnician, we all should go and see him from time to time... :) Thanks! – Ruben Sep 11 '17 at 10:29
  • 8
    May I suggest one addition to your guidelines? One key point of a good template for me is a unique name - while this does not say anything about the quality this will help the user to efficiently search for help. Example of a good name: cleanthesis, example of a bad name: "thesis" – user36296 Sep 11 '17 at 10:41
  • Very good @samcarter! Thanks. I will add this one. – Ruben Sep 11 '17 at 12:46
  • 2
    One good source of templates are top computer science conferences, like NIPS. They update them every year, so they are usually fairly well written, and with arbitrary users in mind. Journals on the other hand... keep away unless you need to submit. – Davidmh Sep 12 '17 at 10:22
  • 1
    @David i have seen conference templates that put a new date on the template and you can find the very same strange things that have been in there for years. – Johannes_B Sep 14 '17 at 7:13
16

I agree 100% with TeXnician answer (+1), so I'm just going to emphasize some aspects:

  1. Templates are very attractive for novices since supposedly the template will do magically the most of the hard work for you: learn LaTeX "will be nearly irrelevant", but the premise is miserably false, even with the best template. You will face to your own ignorance before the cock crows twice.

  2. The more miracles you wait, the more mistakes you'll find. Heavily tuned classes and endless preambles are created mostly for awesome visual effects but even working fine, in the hands of others than the author, could be used unexpectedly. The result is often only cryptic errors, novices' nightmares. Example:

    LaTeX Error: Float (s) lost.

    English translation: they float, Georgie, and when you’re down here with me, you’ll float, too.

  3. Templates, custom classes, and macros often have not a decent documentation, not even a simple comment in the source code. Therefore, not only is a pain debugging error. Also, discover the template features and how to use them could be annoying.

  4. In case of custom classes or packages that are not in your distribution, you should maintain these files in your working directory or your some other available path. Over time, in both cases there a risk of being outdated or lost (you save the document, but not the required files, for instance). This will not happen using your distribution standard classes.

  5. We all have the obsession to do things in our own way. Even with articles to submit to scientific journals. Even when this obviously will not make happy to the editor (that provided a template just to avoid your author "creativity"). If we will end up customizing a tangled custom templates... why not start with a clearer one, as \documentclass{article} \begin{document} text here \end{document}?

16

The question is not about avoiding templates. It is about avoiding templates that you don't understand.

beamer is basically a template with ridiculously complex (and often annoying) code. But because it works and consistent, people use it and spend extra time and effort on it to learn it. Because it is learnable (well almost). memoir is also amazing and you customize it to the nuts and bolts (so is KOMA). But the catch is that these all have great manuals. A random template doesn't. So that is the atom of evil.

If you pick up a random template and don't understand any part of it then you can't modify it. Because you don't understand what it is doing you start searching online and things get out of hand.

But all this mess is because of google not sorting the search results chronologically. You can see an archaic plain TeX and last-year's-package trick in the same document. This is not user's fault. Because TeX is also archaic and a horrible language to learn without any proper version information or other indicator, you pick up a trick from a page where it still has these animations

enter image description here

Then you pick another piece of code from here asked last month. Somehow they don't work you wonder. Also TeX is super esoteric, so are its users. So you don't get a clean answer to very simple problems. Most of the arguments if lasted more than 5 minutes leads to Turing completeness.

Everything might or might not be a good code. So things get convoluted really fast. And you give up and say screw this, is there a readily made thing which I can use?. At that moment, you can make a very simple choice:

If you would handle the code or at least you know roughly which part is responsible for the header and other part is the title page, you can use it. Otherwise do it your own. Because the time you spend debugging the foreign template will be longer than your own design problems solved here when you ask properly.

Can't resist...

enter image description here

  • 2
    +1 Very good answer with yet another point of focus. Although I do not agree with the IE... – TeXnician Sep 12 '17 at 4:15
  • 2
    I’m missing a non-loaded image with the little red cross in the corner … ;) – Jan Sep 13 '17 at 11:37
  • Love this answer, bravo. – A Feldman Sep 18 '17 at 12:15
  • Nice, percusse : ) +1 – Ruben Sep 18 '17 at 15:00
13

Proclaimer: within the Church of LaTeX, deviation is not a sin.

Templates provide examples. People learn from examples very fast, compared to other types of documentation. Besides speed, also a lot of detail is conveyed by seeing a command or environment in action. People teaching programming courses will agree with this, and LaTeX is no different.

A template usually provides a complete, working document, that shows many features of the class and packages involved, including ways to modify the default behavior. This can be very helpful for users, both beginners and experienced ones. It gives you a head start, and saves the trouble of collecting the large amount of scattered knowledge needed to use advanced features (i.e., the user doesn't have to reinvent the wheel).

Without templates, many users would not be able to create complex documents. With templates, they can. Fast. Personally, I was very happy with my PhD thesis template, which allowed me to write a nice document, and I also learned a lot about LaTeX in the process.

It's not surprising that many packages on CTAN include, besides the regular documentation, a template with the most important use cases. They are there because it is useful.

So far for the good news. The bad news is: many templates available online are poorly written, they have all kinds of problems and trying to tweak them to your own needs may take more time then writing a new document from scratch, even including the time needed to find out how to write things from scratch. See @TeXnician's answer (and others). But this is also part of the learning process. With some experience with different templates, users will learn to distinguish a good template from a bad one. Use what is useful, forget the rest. LaTeX is hard and frustrating, don't make it more difficult than it already is.

  • 5
    +1 Learning from examples is indeed important. But (regarding your last paragraph) I would doubt that simply looking at different templates will teach you what is good and bad practice. In fact I had a few bad habits "trained" from bad templates that I layed down only when I read approved sources (e.g. the LaTeX kernel docs) and of course questions on TeX.SX ;) – Ruben Sep 11 '17 at 10:36
  • 2
    Learn with examples is also my prefered way to learn, but I doubt that a thesis template could middly as clear didactically as a MWE in this site, or a package vignette, or a good structured LaTeX introduction (often they have also some examples...). One usual symptom of how unclear are sometimes these examples for the novices is that often they copy and paste such "examples" in another document, but then nothing work anymore. – Fran Sep 11 '17 at 12:29
  • @Fran by which they would learn that (a) commands are defined somewhere, so you need to copy the definition or the relevant usepackage, (b) templates are intended to be used as, well, templates, and not as source for arbitrary code snippets, however (c) they can be used as such if done properly (see (a)). Point is that without the template it is more difficult to put together a full-featured document. That said, I fully agree with you that MWEs and introductory texts are important and sometimes essential for understanding. – Marijn Sep 11 '17 at 13:13
9

I once attempted to produce a resume, with classicthesis template, I even asked a question here in my attempt to get it to work and found myself going down one rabbit hole after another. It just got more and more frustrating, and complex, as I attempted to force the foreign template to do my bidding. It somehow took on a life of its own; the more I tried to make it do what I wanted, the more weird stuff happened as a result.

The template example looked really good, and so I thought, hey why not use the template?

Finally sanity set in, and I took the design elements from the template that I liked, and made my own template. Making my own took vastly less time.

So, my take on it is how do you want to spend your time? Trying to figure out somebody else's wabbit hole, versus creating your own. At least I somewhat understand my own perhaps quirky coding.

But, it was a very educational experience...

  • 3
    +1! You describe perfectly how the decision process of users picking templates is biased ;) – Ruben Sep 18 '17 at 15:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.