0

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? :)

Improve this question
2
  • I assume that the lecture or the homework numbers and titles change anyway in the document that use the class, so they should not be set inside the class at all. You can use an approach like is done for \author or \title, see the latex.ltx and article.cls code, for example!
    – user31729
    Commented Sep 5, 2016 at 12:02
  • Thanks, @Christian. I wasn't as clear as I should have been. See my expanded item 3. It's the definition of "hw" and "lec" that live in (or near) the class file. The actual use of these macros is in the lecture or homework documents. The dates that they refer to are all in one file to reflect the structure of the course, if not the individual documents. When the whole course starts two days earlier because of the academic calendar's shift, it's nice to make changes in just one place. This probably doesn't belong in the "latex" directory, but I don't see an easy workaround.
    – John
    Commented Sep 5, 2016 at 12:13

1 Answer 1

Reset to default
2

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,
Improve this answer
3
  • Thanks. So for an organization that would make sense to a Latex-savvy person: In the "put it all in one class file," version, if I want to break this file into pieces (like 'useful math macros' and 'document appearance' and 'code formatting'), I should then use \include{macros.def} and \include{appearance.def}, etc? Or would doing that suggest I was writing 'core stuff'? I'm really hoping for a recommendation about good practice (if not "best practices"), not a "gosh, it's a programming language, so you can do things a million ways" kind of thing. I already know how to do it badly. :(
    – John
    Commented Sep 5, 2016 at 12:50
  • @John no! not \include that is the one rule that you have to follow:-) Use \input for .def files. But also remember that any files you input are in the input path for all documents world wide so if you use \input{macros.def} in a class file you put on ctan, then no one else anywhere can use that name, so it's better (and quicker) to put it all in one file unless it's really getting too large to manage, but if you do split it up try to make the filenames unique to your class somehow (either using fooclass-macros.def or macros.foo or some such for files linked to a class foo.cls)
    – David Carlisle
    Commented Sep 5, 2016 at 12:56
  • Thanks...I intended to write "input" but mistyped. :( None of this will ever see CTAN, but I see your point about naming conventions; I'll try to do something reasonable there, esp. since if I happened to use a name like "ifthen", when I needed to download the ifthen package, I could end up getting messed up. There's no me-to-CTAN danger, but the other direction is fraught with peril. Thanks again!
    – John
    Commented Sep 5, 2016 at 13:13

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .