Today at 14:45, I would have given a talk at the 2020 DANTE spring conference in Lübeck which had to be cancelled due to corona. In honour of this event, I decided to publish a blog post instead (but with different content and for a different audience since I’m still hoping to give that talk some day). So due to a request by our friend the LaTeX Noob, I will explain how to approach your first time modifying (and reading) a .cls file.

At some point, I will follow up with the same things for .sty file and a more general post on how to approach other people’s (not only LaTeX) code when you’re a newbie wanting to start tweaking other people’s stuff to get started on the path to “Advanced LaTeX” skills. I also still owe you a post on that topic, I haven’t forgotten. Maybe corona will help give me time to write all those posts I’ve promised, drafted yet never finished 😉

But first things first.

What is a .cls file and why do we need it?

I have cited a bunch of resources which you can check out in the Resources section for additional information but for here, I think this text by Will Robertson sums it up really nicely and says it all:

 In general, .cls and .sty files are supplementary files that increase the functionality of LaTeX. They are the files loaded with the \documentclass{...} and \usepackage{...} commands, respectively. We generally call .cls files ‘classes’, and .sty files ‘style files’, or often just ‘packages’.

They both may contain arbitrary TeX and LaTeX code, but they are used in separate ways. Loading a class via \documentclass is mandatory, and may only appear once in a LaTeX document; usually, it is the very first command. On the other hand, packages are optional and as many of them may be loaded as one could wish (prior to the beginning of the document itself).

In the ideal case, a class file will completely define the structure of the document. The familiar article class is a good example: it provides commands for typesetting articles, such as \section, \tableofcontents, \author and so on.

Packages, or style files, are then used to provide anything else that the class doesn’t accommodate. These fall into two broad categories: amendments to the class file, or additional functionality.

For example, the graphicx package provides methods to include images and apply all manner of graphical effects to elements in a document. This package will work with essentially any class file.

On the other hand, the sectsty package provides methods to customise the section headers in the default LaTeX classes (article, report, or book). So, trying to use it with the memoir class, say, will result in it overwriting memoir’s method of creating section headers, and calamity will ensue.

To summarise, .cls and .sty files are loaded by LaTeX to provide and improve methods that are used to create documents. Generally speaking, class files implement the specific structure of the document, whereas packages are used to provide either generic functionality to any document, or to ‘style’ the methods provided by a specific class. (Robertson 2005)

In the .cls, you can define possible class options (this is what we’ll explore here). But you can also use it for things like error handling or defining which packages are required for your class via \RequirePackage{}. Read more on those aspects in the links in the references section.

As writing up a whole document structure would be overkill for this post in my opinion, we’ll use the .cls to extend a class by providing it with a colour theme. The class will then be named something other than article but it will essentially just be a slightly modified version of it. So do you really need to create a class for this? Probably not depending on how much change you really want. But it can be quite practical in the given case of making different colour themes which will be explained on the example of one of my CV templates, Pastel CV / Resumé.

Setting up the main document for colour changes: Colour name variables

An important thing to consider is that when you want to change a colour theme, you need to use ‘variable names’ in your main document or commands when requesting a colour. Then you can change what that colour will be defined as, depending on the class option, in the .cls file. So for example, you might decide you have three different colours in your document or even just one. After all, it is considered typograpically good style to not overload your creations with too many different colours, fonts or font weights. (I’ve been wanting to make a post on basic typography tips too, as I now remember.)

So for example, you might call your colour ‘colour’, maybe it would be even better to say ‘maincolour’ or something. (using the British spelling with ‘ou’ instead of American ‘color’. Which might be a good idea here to make it easier to remember when you are using a self-defined colour rather than a LaTeX command \color{}, especially if you’re not so used to this yet) Don’t use an actual colour name in this because you want it to change with the use of a different option. So, for example, should you want tot define a special highlight colour, call it ‘highlightcolour’ rather than ‘blue’ or just ‘highlight’. If you write just highlight, a re-user of your code who isn’t so familiar with the set of your self-written commands or the packages you used might be confused as to what ‘hightlight’ refers to. ‘highlightcolour’ might seem long and bulky but it dramatically improves code-readability, thus maintainability and adaptability and reduces ambiguity, resulting in good style. Replace all the instances of old colour names (if you have them) which don’t fit into your current naming schema with the new names.

Also, I’d recommend not using ‘practical’ shortcuts so you have less to type. This is considered bad style and will come to bite you at some point. Or at least it will come back to bite those who use your template. What seems ‘the obvious naming’ for you might not at all be understandable to others, so keep that in mind when selecting a name. In one of the templates which have been most inspirational to me, the author kept calling the colour names ‘col’ which I still get confused about at times because ‘col’ is such a common shorthand for ‘column’ and since LaTeX also has tables where you could actually mean column, this creates ambiguity. So rather stick with that a little bit longer but more understandable and less ambiguous colour name. This goes for variables in general.

Once you’ve replaced all your colour names by these ‘stand-ins’ (or ‘variable names’ instead of ‘real’ colour names – they are actually variable names too but don’t worry about that now), you’re good to go. You can now write up a minimal example document where you can switch out the colours.

A minimal working example of a colour-changing class

I have generated an Overleaf template with a simplified ready-to-test version of the following. Also, here’s the github to go with it.

% in main.tex
\documentclass[blue]{pastelcv}

You need to change this class name in multiple places (in all where it comes up) when changing the name of your class! It’s in the file name of the class file, here in the \documentclass command and in the first lines of the class itself (\ProvidesClass{classname} as well as it’s written explanation: \ProvidesClass{classname}[2020/03/25 A Template Named classname]). Make sure to not forget to get rid of the old naming if manipulating an existing document. At best, this will produce inconsistency. At worst, there will be trouble with your code not working properly.
I define a few colours, using either rgb or HTML values. These are ‘default colours’ I want to have available but which are not actually changed in my options. You could have probably done the definitions in the top section already and the only use \colorlet{name}{colour} inside the options as well.
% in pastelcv.cls
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{pastelcv}[2019/12/08 A Pastel CV Template with some infographics]
\LoadClass[]{article}
\RequirePackage{xcolor}
\definecolor{headercolour}{rgb}{0.25,0.25,0.25}
%-------------------------------------------------------
\definecolor{materialpurple}{HTML}{9C27B0}
\definecolor{materialindigo}{HTML}{3F51B5}

At first, I identify the class with its name (\ProvidesClass{}[]), then I load the article class, meaning I don’t actually write up a class structure myself. Then I require a package (xcolor) because more is not needed for this example.
Then, I define my colours needed in the options and assign them to my ‘variables’ cvcolour and cvaltcolour (meaning the main and the ‘alternative’ colour, whatever that means) with \colorlet. You could also use things like black!30, meaning black, = one of the predefined colour names, in 30% opacity. This can also be practical if you don’t want to be looking up HTML colour codes all the time. 
% ---------------------------------------------------------------------------
\DeclareOption{blue}{
\definecolor{cvblue}{HTML}{5499C7}
\definecolor{cvgrey}{HTML}{CFCFCF}
\colorlet{cvcolour}{cvblue}
\colorlet{cvaltcolour}{cvgrey}
}
% ---------------------------------------------------------------------------
\DeclareOption{red}{
\definecolor{cvred}{HTML}{DD5E53}
\definecolor{cvgrey}{HTML}{CFCFCF}
\colorlet{cvcolour}{cvred}
\colorlet{cvaltcolour}{cvgrey}
}

I then end this short class by saying:
% ---------------------------------------------------------------------------
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
\ProcessOptions\relax
\newcommand{\paracolbackgroundoptions}{%
% intentionally left blank
}
\usepackage{pastelcv}

Thereby calling the package pastelcv.sty (learn more about that in a follow-up post on commands and .sty files / packages). The way this is done is not 100% best practice. It’s not a fully-fledged package or class, it’s really just meant to be a template that does its job. Maybe some of the TeX Gurus reading this want to contribute improvements for style and best practices because, after all, I’m not really an expert myself either.
So one ‘real’ example you have now seen would be my Pastel CV template. or any other template where you can change colour options. But, of course, colour-changing isn’t the only use for .cls files. I just thought that this is easy to understand and maybe a good place to start on your way to becoming a class-file-tweaking advanced LaTeX user. I’ll try to follow up soon with how to approach reading other people’s code and making your own commands, the other basics skill you need to start out on your way to advanced LaTeX.
Hoping this was useful to you,
wishing you all the best in times of corona!
the Ninja
References

On the difference between .sty files and .cls files, see Robertson 2005: Will Robertson, What are .cls and .sty files? How are they different? TUG, July 15, 2005.
Creating your own class section of the LaTeX wikibook
LaTeX for authors user guide
LaTeX for class and package writers
Overleaf, Understanding packages and class files tutorial
Overleaf, Writing your own class tutorial



	

		
		

			
Buy me coffee!
			
If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!
			
€3.00
			

				

					
				
				

		
	


			

			
			
Share this:
Twitter
Facebook
Print
Telegram
WhatsApp
Email
Like this:
Like Loading...


	
Related