Document Classes ⇒ My first document class, looking for a “review”

[foquare]

Good afternoon all,

While I’m not massively new to LaTeX, I wouldn’t say I was particularly experienced. I’ve been using it on and off for about eight years and nobody has complained about the documents I’ve produced—but then no one has every really seen what dwelled behind them…

Recently I’ve been wanting to learn more and thought that creating a document class would be fun. I picked my CV which had a fairly large (for me) preamble, and used it as an exercise to a) refactor my preamble, and b) learn how to create a document class.
These activities were largely successful, but I then learnt that it is common practise to write a DTX file which generates the CLS file, so I set about doing that. I found documentation rather hard to follow, perhaps a more in-depth knowledge of TeX, or DocStrip, or the LaTeX kernel would have made things easier. Still, I have come out the other side with something that pretty much works in the same way my original CV with preamble does, which is a win in my book.

I have come here to ask if anyone would be willing to do a “code review” and point out anything I may have done incorrectly or against convention. Having found this process challenging, interesting, and ultimately rewarding, I’d like to go and make a few more document classes and perhaps packages. However I don’t want to be spewing rubbish everywhere, especially if someone was to come along and copy it thus proliferating my wrongdoings.

I’ve put what I have on GitHub, and you can find my CV document class here

Many thanks,
Ben

[Stefan Kottwitz]

Hi Ben,

welcome to the forum!

Thank you for sharing your work. I will for sure read through it when I got time again.

Stefan

[Johannes_B]

Hi and welcome to our little commmunity,

i am really glad to see a human being wanting to share knowledge with others, share software, share thoughts. I am even more glad to see, that you want your material reviewed to verify its usefulness and not let it out in the wild unready.


I indeed see a few things that are not so good, or just wrong

You are setting (at least try to set) options for the font size of the base class article. Let's have a closer look. When starting the compilation, LaTeX executes the first few commands, options are declared, commands are set up. When all options are declared, you request LaTeX to process the options that were given by the author.
In your case, all options are processed, but no option is formally declared. Unfortunately, all the information is lost.
Ok, no problem, let's just swap that and process the options after declaring.
What does option 12pt do? It passes the option 12pt to the base class, which is article here. But, and here comes the catch, the class is already loaded, with an empty option set. So, once again, useful information is lost, no matter which option you give, the document will be typeset with a 10 pt font.

SO, to sum it up, we need to declare valid options, take the user specified options and process them. Load the class, if needed, we can pass options to the class, but we have to do it before loading.

Don't worry, once you understand how LaTeX internally works, you won't confuse that anymore.

Unfortunately, if we really do typeset a 12pt document, the first column does not have enough space and prints over the main part.

LaTeX has a structural command, section, which can be numbered or unnumbered in the output. The user can mark that with a star to produce unnumbered sections. Internally, LaTeX uses \ifstar to check and pass the important stuff to two different macros. You redefined section, basically removing this decision process. If a user, for some reason, decides to use unnumbered sections, all they get for a heading will be the star.

Package hyperref is used by many many people, by you as well. It defines a whole lot of internal stuff, by the kernel and some packages. Hyperref is in your class file, the user can still load quite a bunch of packages. It is quite possible, that something will break.

You are defining \littleblankline for a bit of separation between paragraphs. You definition does not introduce any paragraph. Though it looks like two different paragraphs, LaTeX just sees a new line there and treats it like that. Confusing \\ with \par (or simply a blank line) is one of the most confused things and even users for years don't know the difference.

The contactdetails block is hardcoded. There will be someone who wants to change the order of phone and mail, trust me. But there is something else on my mind. As everything is hard coded, what happens if something is missing? For example, i don't have a website, leaving the field empty will still print WWW: and a warning by hyperref is issued. You should somehow catch this case.

As it happens, i was thinking about CVs as well over the past weeks and i set up a little sandbox myself. Feel free to take a look at bausteineBewerbung.

Joseph Wright wrote about CVs on his blog, i think it will be very interesting for you and you should definitely check it out Writing a curriculum vitae in LaTeX


Once again, thanks for sharing your work. I hope you are not intimidated by my (contructive) crtique

[foquare]

Hi Johannes,

Thanks so much for the warm welcome and for the critique. Sorry I've not posted before now, I hadn't received a notification of your post and hadn't had time to check back.

I've not had much of a chance to digest your feedback yet, and may not for a couple of days, but I really appreciate you looking and commenting on what I've done. I think it may take me some time to properly wrap my head around everything

I'll quickly take this opportunity to comment on how pleasantly surprised I am at how friendly people are around here. I've asked similar questions about other technologies in other communities, and have quite often been confronted with blunt and unfriendly criticism, as apposed to your kindly worded, and constructive, critique.

Thank you once again — I'll be back when I've had some time to digest

[foquare]

Hi Johannes,

Thank you once again for your reply. I feared that once I had sat down to really read what you had written that I would find it very difficult to make the changes, however after a few hours and a couple of reference books/websites, I think I have made all of your suggestions except for the note about hyperref, as I'm not really sure what to do about that…

It has been good to have been told about these things. While fixing the problems I learnt more about conditionals in LaTeX, and more broadly some extra git stuff which I hadn't touched on before.

Thank you so much for your review

[Johannes_B]

Package hyperref is a blessing and a curse. Usually, it should be loaded last, usually as there are exceptions, for example package glossaries.

A documentclass is the stuff first read in by LaTeX. If you load hyperref at the end of the class, it is still at the beginning of the preamble and the user could load a package that smashes hyperref.
LaTeX provides hooks and conditionals to deal with stuff like that. You could, for example, delay the loading of the package using a hook like \AtEndPreamble and similar. This will, on the other hand, smash package glossaries, if a user did load it. Package scrlfile of the KOMA bundle provides a few more bells and whistles to deal with that issue, but really keeping track is tedious. Best to let the user decide to load package hyperref on their own.

There is still \hypersetup which we didn't mention yet, that lets the user declare hyperref settings.


By the way, you are loading package ifthen, you might enjoy the capabilities of package etoolbox.