In the LaTeX community templates for documents are a recurring topic of discussion. I have written about it:
Others have written about it:
It all boils down to this: templates often contain bad code or don’t follow good LaTeX practice but on the same time many not so experienced users like to use templates for their documents. This is the source for many, many problems and questions in LaTeX forums and Q&A sites.
More experienced users tend to avoid templates and write their documents from scratch (or write custom document classes). So this is an often heard advice. But of course writing and designing a document from scratch is far from easy for more inexperienced users. It often is time consuming. As a consequence it isn’t really surprising that templates are popular.
So what can be done in order to mimimize the problems with many of the templates? This is the topic of a current discussion between some people in the LaTeX community. This discussion still is at the beginning so there is no conclusion, yet. In this post I like to add some thoughts to the discussion.
Naturally the people who are maintaining popular template sites such as Frits Wenneker from
\howto TeX or Velimir Gayevskiy from
LaTeX Templates and probably also
the Overleaf team need to join the discussion. Otherwise I’m afraid the whole discussion is rather academic than that it will lead to useful results.
Then I think the first thing to do would be to define some standards: which document classes should be the ones recommended or used (I’d opt for KOMA-Script but that’s just my opinion). Which packages are recommended for certain tasks? What is »good LaTeX practice«? The last point is not so easy: many experienced users strongly advice the separation of contents and layout. This for example means that you dont write
[cce_latex]\textbf{this is important}[/cce_latex]
but instead you define a semantic macro for this
in your preamble:
[cce_latex]\newcommand\important[1]{\textbf{#1}}
…
\begin{document}
…
\important{this is important}[/cce_latex]
But there are quite a few number of LaTeX users for whom this is not as important. They prefer the first »easy« solution. This is fine, I guess (although I’d
strongly advice against it). So which solution to define as »standard«?
Once the set of standards is defined and agreed upon existing templates need to be revised having those standards in mind. Maybe the existing templates would need to have maintainers who are responsible for keeping an eye on the templates, fixing bugs, adapting to new standards as the years go by and so on, very much similar to how LaTeX packages are maintained. Of course this would need volunteers…
Finally when all templates have been revised following the previously defined standards those template sites which are participating could »officially« be advertized by TeX user groups, on popular (La)TeX blogs and (La)TeX forums and Q&A sites with the hope that new users then will find those sites first and use the »recommended templates«.
Now I’m really interested in and excited about what you think on this topic!
Picture: © Sabine Schmidt/pixelio 
Many templates are quick and dirty hacks, but very often they don’t need to be polished, because they are just fine for their job. You need a printed CV or invoice, you get it. More complex templates, like thesis or books need more love and maintenance and very often there are good maintainers.
I don’t think that common standard (did you mean a sort of high-level tags library?) is achievable [2], as well as the separation of contents and layout. As John Cook points [1], “LaTeX was designed to put ink on paper”, and there are many cases where you really need to tweak layout in this particular table cell, and you end up adding layout hacks into your content.
All that said, it would be really great to have high-quality templates where code isn’t too clumsy (e.g. like moderncv), bugs get fixed and updates come regularly. Perhaps switching to GitHub and similar hostings instead of distributing tarballs will do the trick; at least skilled template users will be able to propose the changes easily.
— Dmitry Barashev, Papeeria Team
[1] http://www.johndcook.com/blog/2013/02/18/unicode-to-latex/comment-page-1/#comment-712
[2] https://xkcd.com/927/
Interesting: did you really make that experience? Mine is completely the opposite: many if not most times there are no or no good maintainers…
This is perfectly fine as long as you keep your templates to yourself (don’t look at my private stack of documents… :p). As soon as you publish them – let alone advertize them – dirty hack templates are a nuisance for many helpers in many, many LaTeX forums. Worse: they keep inexperienced users from getting better because they’re not able to judge that the code they’re offered may be crap.
Until now templates don’t follow any standard. I didn’t mean a standard for everyone. As you correctly point out with the xkcd comic: that isn’t possible, anyway. What I would like to see is that one or two popular template providers would develop a standard together with the LaTeX community with the minimal goal that templates would no longer contain all those mistakes that currently will hit the users sooner or later. A hacky document is fine for a short (one or two page) document that you use only once. As soon as you plan something larger or want to use a template more often sooner or later the hacks will cause problems. (The same is not only true for LaTeX problems but for any other situation, too…)
I beg to disagree: John Cook maybe right about TeX in general or Plain TeX in particular when he says »It would be nice if it made more semantic distinctions, but it wasn’t designed for that.« but certainly not about LaTeX. One of the main differences if not the main difference between Plain TeX and LaTeX is that the latter propagates separation between content and design!
Actually, no, not in my experience. I don’t know when I had to break the separation rule the last time. Not for years. Of course it can be that you need the one or the other setup done in the middle of the document but those cases are rare in my experience. (Most times they’re necessary due to resctrictions in the functionality of a package but not due to how LaTeX works).
I don’t really agree with Cook’s particular statement, there. In real-world documents, the document setup does matter. Things change and requirements are updated — if your document can’t handle that, that’s a significant amount of work to be done.
I’ll note that I did start a project about a year ago that hoped to be a such a compendium of ‘templates’ (even though I think that very word is damaging to the project — ‘examples’ is better):
https://github.com/vermiculus/texample
The latest commit was over a year ago, but I’m hoping to breathe new life into the project. Keep tuned — I’ll be sure to ping y’all on Twitter when there’s a system in place to suggest new examples.
Just a thought: for people willing to participate I could set up a discussion forum in my forums section so we’d have a place to discuss ideas (most importantly about what the standards would be that we wanted…).
I’ve also set up https://gitter.im/vermiculus/texample, which only requires a GitHub account to participate in. It’s directly linked to the repository of the same name 🙂
How and why was LaTeX Templates created?
Let me give a quick overview of my motivations and reasons for getting into templates. LaTeXTemplates.com started as an idea from me learning LaTeX about 6 years ago now and being surprised/annoyed that there was no single source for good looking templates out there. Instead there was a scattering of templates on 1990’s-era academic websites and a few blogs with templates here and there. When I learn a new programming/markup language I prefer learning by doing, i.e. getting started quickly and learning as I go on an actual project. The LaTeX templates I found online helped me do this as I started with just modifying the content for university assignments and when I ran into problems such as “how do I modify the margins” I would look up the answer and eventually learn how to do it right. After about a year of this, I decided to create a resource of templates beautifully displayed with nice previews so others in a similar situation didn’t have to hunt around on Google. Don’t get me wrong, I’m not saying this is the best way to go about learning something complex – it’s just what works for me. In an ideal world we would have the time and energy to sit down with the LaTeX WikiBook or your favorite guide to LaTeX and go through it from cover to cover faithfully reproducing all the examples, but you and I both know that happens very rarely.
My motivations.
When I started the website, I was myself quite a newbie to LaTeX, and indeed, even now my knowledge is probably nowhere near as good as yours. My thinking was: “LaTeX makes beautiful documents, I want to make this easy for other people to use!” Because of this, my motivation for templates has always been, above all else, usability (usability here means putting content into a template, not modifying the template). What this meant was that I focussed on commenting and rearrangement – I would block off major parts of the template with commenting (e.g. ABSTRACT SECTION), fix formatting errors, rearrange code and add some commenting where I could. As I worked more on the website (it now has ~85 templates), I learned more about LaTeX and gradually started improving the code of templates as I went. I would not only do the usability stuff, but I would also chuck out the bits of code that weren’t doing anything, or were doing something wrong or were conflicting with something else. This meant that processing a new template took more and more time as I was effectively rewriting them and explains why there have been fewer and fewer coming online of late. Another reason is that I am no longer a PhD student 😉
Ultimately, what I strive for is that when you go to LaTeX Templates and find a template you like based on the preview image/PDF, you download it and the way for you to put your own content in to replace the dummy content is very clear and easy to do. This may sound like heresy, but the actual code to create the layout is then secondary to this – I comment it as much as I have time to do so that simple modifications are easy, but there is a certain expectation there that if you’re going to dig around and try to modify the templates in a significant way, you should know what you’re doing – just as you would have to do for creating a document layout from scratch.
What can we do to improve LaTeXTemplates.com?
With regards to current templates, I completely agree with you that many have poor (or outdated) code and in some cases may be a serious hindrance to modification. This poor code can then prompt user questions with the same questions coming up over and over; I have done plenty of support for the templates on my site to know this. I have had a few requests now to put the templates on GitHub so that people could send me push requests, and while I agree this would be great, I simply don’t have the time to go through that volume of requests. You may ask, why don’t I just let anyone make the changes and send me the modified templates for replacement of the old versions? The answer is that I try to have a consistent commenting style throughout the website and I also like to do some quality control on the templates before they are put up – I wouldn’t be happy blindly accepting changes.
Practical suggestions.
So, if you’re asking for my opinion on how LaTeX templates can be standardized in general, here is what I would recommend:
1) Create what are essentially functions for LaTeX consisting of the “correct” way of doing a specific task. E.g. if you want to modify the margins, the geometry package is probably the best way to go. Every future modification of margins in every template can then use this standard snippet.
2) Decide on a consistent formatting and commenting style and stick to it. This includes things like: no hard line wrapping (this really annoys me when I see it and have to manually remove it), separating out logical blocks within the template into delimited commenting blocks as I do in all the templates (e.g. abstract here, introduction here, methods here, etc), comment ALL lines of code specifying structure/layout with the exact same text across templates.
3) Separate content from style. I have been doing this more and more with the new templates by moving any code that specifies how the document looks or works into a file called structure.tex. A complete novice can then just stick to the template file and add their own content in while anyone who is comfortable with tinkering can find everything nicely separated and commented in structure.tex. Note that this also includes custom commands for things like title, authors, date that are specified at the top of the template file but are defined in the structure.tex file.
Problems with these:
1) Package incompatibilities is a major one, I don’t need to tell you why.
2) The more you set things in stone, the harder it is to make (hackey) modifications. This is exactly what you say with: “But there are quite a few number of LaTeX users for whom this is not as important. They prefer the first »easy« solution.”
Your suggestions for agreed standards and the revision of templates to meet them is great, but as you pointed out this requires a lot of volunteers and a maintainer for each template. In my opinion there then needs to be some kind of oversight that the templates are actually adhering to the usability rules I mentioned in point #2. Remember that templates are more about usability than the code from my perspective.
In the mean time, if you want a template changed, download the current version from the website, make the changes (and please adhere to my commenting style to minimize work that I have to do) and email it to me. I can then go through and OK it and upgrade the version on the website. This is what Johannes has done for the Masters/Doctoral Thesis Template and we’ve made some major modifications to it for both code quality and usability. Definitely happy to give anyone who does this credit on the website.
Thanks for this long comment! I’ll have to read this more closely before I can respond. Just a short comment because i stumbled upon this:
I am exactly the opposite! I can’t stand those infinitely long lines in a source file (for several reasons) which is why my editor breaks those for me automatically. This is one point where we would have a hard time working together… 🙂
@Vel Same here by the way. My editor does hard line wrapping because i told it so. Usual terminal width of 80 chars. It is quite common that i have three different tabs open to code, with a hard line wrap, i know exactly where i am.
The way I see it, if you use hard line wrapping you are adding extra information into the file, i.e. extra newline characters. This is forcing the user of whatever you wrote to adhere to your preferred line width rather than their own. Keeping text on one line means the user decides if they want to hard line wrap, soft line wrap (based on the width of their editor) or let the line go off the side of the editor. It’s one of the things I always “fix” in templates that I put up on LT.com 😉
The 80 character limit for line-wrapping has a long history and is seems to be a standard between programmers all around the world. Not surprisingly there are a number of questions about this topic stackoverflow and programmers.sx. This post has the history wrong but gives the reasons that I also have for the hard line wrap: Is the 80 character line limit still relevant?.
First i want to thank you for your detailed explanation. 🙂
You have mentioned the LaTeX Wikibook. Unfortunately, quite a few information in there are outdated or wrong. Some introductions to LaTeX have just the same problem, they are written by the same people providing some of the bad templates. I think this is one of the parts: Spotting and notfying, hoping for collaboration.
I have the impression that this will be a very big task, and even an impossible task to finish.
A user should be able to get into the car and drive off without problems, a bit of learning is still needed though. But you don’t have to know how an internal combustion engine works. You just assume the developers of the car have done solid job.
If we want to make the lifes of others more easy (and less dangerous), we should supply them with stable code.
You mentioned your site gets about 5k hits every day, your site is looking very nice and promises high quality templates. There is a very high interest and i think we can do some good here. But it really takes a bit of time and effort by us all.
I just used the WikiBook as the first thing that came to my head – I often use it as a quick reference for remembering how to do something. I agree it may not always be the best way though!
The effort required is the thing that worries me most because I have very little time to work on templates at the moment. I’m working on a new commercial LaTeX project that I’d rather not talk about yet and suffice it to say, it’s quite ambitious and takes a lot of my free time. I am definitely on board with improving template quality, I would just like for there to be a usability standard that I am happy with and then anyone can be free to modify existing templates to fit it. It would then be a simple matter of me checking over the modified template, making sure it adheres to the standard and replacing the existing one.
On the TUG conference 2015 some people will be trying to collect thoughts and ideas on this matter – I suggest we postpone the real discussion (whatever »real« means) until afterwards! (Until then each of us can think about which discussion form we’d like to have: a forum? gitter chat? Mailing list? Good old email? Other ideas?)
This doesn’t mean you cannot comment on this post if you have something to add! (Especially if you’re afraid to forget about it until after TUG 2015 🙂 )
For reference: http://chat.stackexchange.com/transcript/message/22598571#22598571
I quite like IRC and have a server I’m happy for us to use to chat 🙂
It came to me that this discussion seems to miss one thing: there are templates on CTAN like classicthesis, tufte-book or even my cnltx-doc. Seems like a natural place: a genuine LaTeX template is a document class. In a way every document class is a LaTeX template. Maybe what we are talking about are not so much templates but examples for LaTeX usage…
I think we should talk about the beginning of all those problems and there are two beginnings, I think.
1. When I started writing with LaTeX I used a template for this and a template for that. I didn’t know what is “good” or what is “bad”. I still don’t know it.
There is now guide that tells us what is so called “good practise while LaTeX writing”. Or at least I don’t know such a guide. Of course, there is the “Todsünden Register” but this isn’t helpful when creating a theses template by yourself.
You ask Google and google tells you a solution. First, it works fine and after a while it begins to be strange. Then you ask Google again and you can find that for example your solution XYZ isn’t correct for KOMA.
2. The question of hen and egg. Who says what is “good” and how and where is it defined? This macro thingy is nice but where is the difference between \textbf{} and the macro? Both isn’t “readable” as normal text in an easy way. I, for example, use macros when I know I use the thing behind the macro more than once. In the textbf example I always use the command directly.
Can anybody explain where I can find the defined “good practice in LaTeX”?