Reference guide to begin writing a class and/or a package

Question

Once a LaTeX user gets more and more skilled, and writes his/her own code, the question "Should I make a package (or a class) out of it?" will probably arise.

My question is (you catch me: I'm one of those users!): is there a reference guide other than LaTEX 2ε for class and package writers?

I mean, to me it seems that the ability to write a class or a package is something gained only by experience. Every LaTeX package is always well documented. Is there a document on how to write packages assuming very little knowledge of LaTeX?

You know, there's always a "Hello world" example for every programming language and, starting from that example, the language is explained in all of its functions. But I've not yet found something similar for writing LaTeX packages.

Answer 1

I wrote my first LaTeX package (idxlayout) about half a year ago (January 2010). I didn't know a comprehensive class/package writing guide then (and do not now), but I can offer a few hopefully useful hints:

• You may not need advanced TeX programming skills, but you should be familiar with the existing solutions (and their shortcomings) in the subject area you're interested in. Delve in the respective code of the LaTeX kernel, study the packages that may already exist.
• Try to straighten out the desired features of your package and their interdependencies before you write lots of code. Come up with intuitive names for options and user commands.
• Consider a key-value-interface for the options you're going to offer. There are quite a few support packages for key-value-syntax; I've used kvoptions.
• You've already mentioned the importance of documentation. I'll add that writing a comprehensible user manual is necessary, but that your top priority should be documenting the intricacies of your source code - neglecting this will come to haunt you later.
• For distributing your package you may use the dtx-format which packs source code and documentation in one file. A good tutorial is Scott Pakins article.

EDIT: One year later and with version 0.1 of my second package (quoting) published, I want to stress some other points. Note that I'm only a LaTeX "power user" and that my recommendations probably are self-evident for programmers.

• As you develop your class/package, write an accompanying test document that allows for a quick overview if the (major) features (still) work as expected or if you broke something with your latest build. Whenever you stumble upon a new edge use case, amend your test document to include it.

• Consider to use a version control system. I have kept copies of "major" development versions of my packages, but not used a full-fledged system like subversion, and do somehat regret it now. (I had programmed a small feature for quoting, then dismissed it within the same "major" package version, and would now very much like to reuse the code.)

Answer 2

I might be wrong, but your question seems to be asking how to go about authoring LaTeX packages rather than programming in LaTeX. Right? In this case, you might be interested in the dtxtut guide and the dtxgallery collection of examples.

Answer 3

I don't think there are many interesting LaTeX packages that could be written with only a little knowledge of LaTeX. Most (but not all) require a fairly deep understanding of TeX. I highly recommend reading the TeXbook to learn about TeX.

One could probably write a class that essentially loaded another class (like article), used some packages (like geometry) and supplied the necessary arguments to them without a whole lot of LaTeX knowledge. Dealing with docstrip for documentation is a whole other issue.

Answer 4

An introduction to writing classes is here.