About(none)
Shop(none)
LaTeX(none)
Software(none)
Books(none)
Gallery(none)
News(none)
Contact(none)
Blog(none)
Settings(none)
Latest news 2019-09-20: new blog post "Clouds, Cookies and Migration Part 3: Cookies."


1.1 Packages and Document Classes

If you already have some basic knowledge of LaTeX, you'll know that a class is loaded using

\documentclass[options]{name}

and packages are loaded using

\usepackage[options]{name}

If you are using an operating system with case-sensitive filenames (for example, Unix-like systems), the ⟨name⟩ part must use the same case as the corresponding filename ⟨name.cls or ⟨name.sty. If the case doesn't match, the file won't be found. In the instance of operating systems with case-insensitive filenames (such as Windows) the file will be found but there will most likely be a warning that ⟨name⟩ doesn't match the declared class or package name. To assist you, this book will always match the filename case when referring to a class or package, rather than the format used in the class or package's manual. (For example, pgf/tikz rather than PGF/TikZ or pstricks rather than PSTricks.) If I use any upper case characters (for example, Alegreya or DejaVuSerif) then that means the filename actually contains those upper case characters.

Recall from Volume 1 that package and class documentation can be accessed via the texdoc application. For example:

texdoc datatool

In the past couple of years that I've been writing this book, I've submitted more bug reports than I have over the previous twenty or more years of using LaTeX. If it's of any consolation to my fellow coders, I found more bugs in my own code than anyone else's. However this leads me onto a topic I haven't really covered in the previous two volumes (except, perhaps, briefly in Volume 1) and that's the difference between commercial software and open source software (aside from the obvious one of price).

When a company decides to produce a new piece of software, they usually hire someone to do some market research to find out what potential customers might need, then they hire a programmer (or group of programmers) to write the code and then the software gets tested by a group of product testers. After the buyer has purchased the software, they usually have access to a support desk, customer helpline or chat. The person on the support desk may just have a crib sheet of stock solutions for common issues and if the issue isn't on that list, the customer will probably be referred to a more technical support person. In a few years' time, the company may decide it's no longer financially viable to continue to provide or support that product. If the customer upgrades their operating system (or buys a new computer with a newer operating system) the software may no longer be able to run (or even install), and customers may find themselves in a position where they can no longer access their data that's stored in a proprietary format.

Open source software, on the other hand, usually starts life when someone has a need for an application or piece of code that doesn't exist or exists but is beyond their budget or exists but doesn't run on their operating system. If that person happens to be able to write code (or, perhaps, decides to take this opportunity to learn) then they may be able to write something that fixes their problem. If it achieves what they wanted to do, there's a chance it might be useful to someone else with a similar requirement, so they make it publicly available with an open source licence and an “as is” caveat. There are two most likely possibilities: firstly, once the task has been completed, the developer loses interest in the code they wrote or, secondly, the developer makes repeated long-term use of the code they wrote.

Consider the first case. There's no support desk or customer helpline for this code. The developer has other tasks to do and possibly a full-time job to keep them busy. There are few employers who will pay employees to work full-time on something that doesn't generate an income or improve productivity. If your problem isn't quite identical to the developer's, that code might not work. It may need a few patches or adjustments. Since it's open source, if you understand the code you may be able to modify it yourself. If you don't understand it, you might be able to find someone else who can. This kind of tweaking and patching isn't possible with commercial software. However, it may be that you can't fix it yourself and you can't find anyone willing to help you. At which point you may have to look around for another alternative, which can be time-consuming.

Now consider the second case. Again, there's no support desk or customer helpline, but if the developer is regularly using this code in their work then they have more interest in maintaining and enhancing it. While the code doesn't actually generate any income, it may improve productivity in which case an employer may be more amenable to the developer spending time on updating it. In this case you're in a better position if you use the code and find it doesn't quite work for you.

Although I said that in both cases there's no support desk or customer helpline, there's generally something better: a collection of enthusiastic users who are keen to help others in their spare time. These aren't people just reading stock answers from a crib sheet, they are people who regularly use the code and understand it (the user commands, at least, if not the underlying internals). In the TeX world, you can find them at places like TeX on StackExchange, The LaTeX Community or similar forums or on a newsgroup such as comp.text.tex [16] or a mailing list (such as the TeX User Group (TUG) lists at http://tug.org/mailman/listinfo). These people are usually friendly, as long as you remember that they are volunteers not employees and that repeating the same old answers is tiresome.

Some of the topics covered in this book suggest a number of alternative classes or packages that you could use. When presented with a selection like this, how do you decide which of them fall under the first case and which the second case? The second case is clearly preferable as any issues are more likely to be fixed. You don't really want to invest time on learning how to use a package only to discover there are ancient unresolved bugs in it.

The first thing to do is check the version number and release date. This information is listed on the Comprehensive TeX Archive Network (CTAN). For example, if you go to http://ctan.org/pkg/datatool you'll see the version number listed in the summary. The release date is in both the README file and at the start of the user guide. If the version number is low, such as 1.0, and the release date is some years ago then the package hasn't had much activity. This may not necessarily be a sign that the package falls under the first case as it may be small enough for bugs to be easily detected with a simple test file, but it may well be an indication that the author created it for a particular document, made it publicly available, but hasn't required it for any new documents. The other thing to look for is a “changes” or “history” file. A long revision list is usually an indication of the second case. (Don't mistake a long list of bug fixes as a bad thing. A package that has ten boolean options requires 210 = 1024 test files to check that all combinations work correctly, and that doesn't include the possibility of conflicts with other packages.)

The next thing to do is a quick search for the package on one of the sites mentioned above. For example, enter the package name in the search box for TeX on StackExchange or the LaTeX Community Forum. Are there many results? If there aren't, that could mean there's not much interest in the package. (Unless, again, it's a very small package that's too trivial to cause any issues.) If, on the other hand, the result list is long and most of the answers involve hacks using internal commands, then the package most likely falls under the first case. If the result list is long and most of the answers don't use internal commands or indicate that there was a bug that has now been fixed or a new feature has been added that solves the problem, then the package most likely falls under the second case. A little time spent on this type of investigation could save you a lot of grief later on.

Occasionally a package or class that has been under the second case for some years suddenly loses maintenance. This is most likely due to a change of circumstances for the developer. (None of us are immortal or immune to adversity or the ageing process!) Fortunately, in the case of some popular classes or packages other volunteers have agreed to take over maintenance. The open source nature of the code makes this more likely than it would with proprietary code.


This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).

© 2015 Dickimaw Books. "Dickimaw", "Dickimaw Books" and the Dickimaw parrot logo are trademarks. The Dickimaw parrot was painted by Magdalene Pritchett.

Terms of Use Privacy Policy Cookies Site Map FAQs