[Tex/LaTex] Class file and style file structure

document-classesdocument-configurationmacros

I'm trying to clean up a documentclass for documents produced in a course I'm teaching. It's evolved over about 15 years of various novices "just adding a little something" until it's a complete mess. I'd like to restructure, but it'd be nice to do it in a way that's at least somewhat latex-like.

I'd like to know what should go in a .cls file, what should go in a .sty file, and what (if anything) should go in a .tex file.

The documentclass, which lives in a latex directory where all latex-stuff is put, separate from the actual course content, is derived from "article"; it does a nice \ProvidesClass{courseclass} and \LoadClass[11pt]{article}, and then
"requires" various packages. Some of these are not part of our department's standard latex implementation, so they too are in that latex directory. I'm pretty sure that up to this point, things are OK.

There are several more things to be done:

  1. Customize stuff. We use the listings package, and defining languages (like Ocaml) for which we want to typeset code has to happen via \lstdeginelanguage.

    1. Define new environments like the "qa" environment for lecture notes, which we use to present questions and answers from lecture.

    2. Do somewhat fancier stuff, like defining a bunch of macros like \hw and \lec that get used in individual homework or lecture documents in the form \hw{02}{Syntax} or \lec{07}{Recursion}. These do things like declare that this document is Homework 2 or Lecture 7, and set the title of the homework or lecture, and look up the presentation date for the lecture or the due-date for the homework; these dates are all specified in one place (within the latex directory), and the lookup uses the first argument of the \hw or lec macro.

My question is whether any of this should be in .tex files, or should it all be in the main .cls file? And if it should all be in the main file, is there a way to "properly" break it up using include or import or something so that we can have a single file that does date-related stuff (which changes year to year) and a different one that does document-appearance stuff, like "styles for program listings", which is pretty constant?

Any recommendations? Any recommendations on someplace I could go read this without learning everything about all of Tex/Latex? 🙂

Best Answer

Firstly the active component of \input, \LoadClass, \RequirePackage etc is just \input so it really doesn't make any difference to TeX. (Note \include is different and should never be used before \begin{document}). The difference is really a matter of taste in how to structure the code and perhaps more importantly how you want to document it to users.

  • So one reasonable option is to put it all in one class file. Note that if you are using a system like doc/docstrip you can still structure the source into multiple files if that is convenient in terms of code organisation. (For example the main latex format source file latex.ltx is built from over 40 separate ".dtx" documented source files.

If you want to have separate files "at run time" there are several possibilities.

  • In the core latex classes and packages we tended to use the extensions .clo for code implementing class options so [12pt] ends up inputting size12.clo, and .def for other package or class related definitions so [dvips] option in graphicx inputs dvips.def, [utf8] option to inputenc causes utf8enc.def to be input etc. font setup were special cased with a .fd extension. Cases where there is a possibility of user-configuration are handled as .cfg/.ltx pairs using \InputIfFileExists so for example at format creation time if there is a fontmath.cfg file that is input, if (as is usually the case) it does not exist then the default fontmath.ltx is input to set up math fonts.

Note that none of these extensions is "built in" in the way .sty and .cls are, unlike packages which can be referred to by name without extension .def files are input as \input{xxx.def} and you could use .def or a package-specific extension.

  • If the extra code is potentially useful outside your class then it makes sense to make it a package that the class loads using \RequirePackage so for example an ocaml listings configuration might be useful generally and you could put that in a ocaml-listings.sty and have \RequirePackage{ocaml-listings} in your class file so that it is automatically loaded in that case. (You see this style in the AMS document classes which require the amsmath and amsfonts packages,
Related Question