6

I want to create a new LaTeX package to assist myself, and other researchers working in the same field typeset their work. Currently, it is primarily done manually per paper, and while that mostly works, it's clunky, slow and a bit error-prone.

My online searches have turned up various tidbits (along with hats), most notably Overleaf's advice, the LaTeX2e for class and package writers document and documents on LaTeX3's expl3 and xparse packages. It's not clear to me which one of these I should follow. LaTeX2e for class and package writers seems like the obvious place, but it's about 14 years old now. Meanwhile, I know LaTeX3 is coming, and I would prefer the package to be 'future-proof', but I can't tell if it's what I should start with at this point (nor, to be honest, which one of the aforementioned packages is the one I should be looking at).

I could only find a few questions on here that seemed relevant (namely, this, this and this) and all of them more-or-less dive in a bit ahead of where I am at.

So, my question is, where should I start with creating a brand new LaTeX package, in this day-and-age? Have I missed some important guides/advice somewhere? I would prefer it if I could make sure that this package can be used with any of the LaTeX distributions and engines.

Jarak
  • 391
  • 8
    “I know LaTeX3 is coming” The scheduled release is in 3019. – Henri Menke Dec 23 '19 at 04:20
  • 6
    note there is essentially no difference between writing a package and defining commands in the preamble of a document. Start by taking an existing document and place all the preamble commands into a mypackage.sty and then have a preamble that says \usepackage{mypackage} – David Carlisle Dec 23 '19 at 09:06
  • @DavidCarlisle I can do that. Though some of the repeated elements haven't even been codified as defined commands, and instead there's just copy-pasting of stuff. Once I have shifted the common parts into a .sty file, is there a clear next step to take? Thanks :) – Jarak Dec 23 '19 at 09:41
  • 2
    Next steps: Give the package a proper license (for example LPPL), document it using docstrip, put it to CTAN. –  Dec 23 '19 at 11:33
  • 2
    You might also consider whether this will be a package (.sty file) or a document class (.cls file). If a package, you will want to be specific in the documentation about which \documentclasses are compatible -- there are many differences, and results can be "unpredictable" if the "wrong" one is used. Making this a class will lock down the possibilities and probably result in fewer problems; remember, you can start by loading the most appropriate existing class. – barbara beeton Dec 23 '19 at 13:41

1 Answers1

8

Since nobody else ever posted an answer, I thought I should put one up, just in case somebody stumbles across this question. This answer deals only with packages, since that is what I needed. I don't know about writing classes.

Firstly, I would say: Do you really need to create a new package? Is there definitely no pre-existing package you can use? Do you only have a few lines of custom commands, such that it isn't worth the effort?

If you just want to write up a few commands, then checking the Overleaf advice, LaTeX2e for Class and Package Writers and the LaTeX Wikibook's pages on it are probably the best starting place, and perhaps all you will need. Also, if you can access a copy of it, it would be worth taking a look at The LaTeX Companion (2nd ed), specifically Chapter 14 and Appendix A (it's available in O'Reilly's online learning system, if you use that).

On the other hand, if you are wanting to create a full-blown package with supporting documentation, especially if you want to contribute it to CTAN, then your best bet is probably to use the .dtx approach, which is arguably a de facto standard these days. This essentially involves creating a special file which includes both the commands themselves, and also the documentation to support them. The use of dtx files is much too big a topic to describe in this post, so instead, I will include a bunch of links that may be of help:

  • The dtx tutorial.
  • A brief dtx FAQ.
  • A blog post about an example dtx file.
  • The documentation for the doc LaTeX class, the backing class for this system.
  • The documentation for DocStrip, which is the part that pulls your commands out of the dtx file and puts them into a sty file.
  • sty2dtx or makedtx, Perl scripts to extract what you have out of a sty file and make it a proper dtx file.
  • The dtx Gallery, which contains a handful of sample dtx files - though they're all old now.
  • These questions about preparing packages for upload to CTAN (I found them well after I posted this question).

Almost certainly, there are other good resources out there, but these were the ones I found and which helped me with my task.

In the end, I completely abandoned the idea of using LaTeX3 for now, since I couldn't find anything that provided a nice introduction to it, instead of appearing to be reference material for those who are already knowledgeable about it. I imagine there are good resources out there, but I didn't locate them.

EDIT: Months after I wrote this answer, Alan Xiang wrote an introductory tutorial to LaTeX3 and posted it on his blog. I haven't had a chance to go through it properly yet, but it looks like exactly the sort of thing I had been hoping to find when I first posted this question. Thanks, Alan!

I also have just come across these other TeX.SE questions (I have no idea why I didn't manage to find them before), which appear to have directly useful content: see here and here.

Jarak
  • 391