2

I've written a really nice, pretty comprehensive class for my particular department's particular way of doing things. I've also got biblatex citation and bibliography styles. Once I have them a bit tidied up (so they're easier to maintain), I intend to send them to my department so they can be shared the other students who use LaTeX (both of them, I'm sure!).

What are the best practices here? I'm looking for established/common practices or tools for:

  • writing (some, minor) documentation (ideally including that trick where the documentation automatically includes the source code)
  • using the class and styles once they're hosted elsewhere -- there has to be something better than just checking and redownloading if anyone else updates it, but it seems much too niche to be worth putting out publically on something like CTAN.
  • somehow packaging the class and style together. Is this possible? It would seem sensible if it is.

Not really sure where to look for this sort of thing, so I'm looking here... TIA!

1
  • 2
    Thank you for the common sense of not publishing this to CTAN. While this increases the effort of distribution a bit, I really don't like the number of niche classes included in a full TeX Live installation... That being said, this Q&A format is probably better suited for questions with a narrower scope (read: single questions, not multiple disguised as one). However I'll try to give some pointers.
    – Skillmon
    Dec 8, 2021 at 8:13

1 Answer 1

2

The traditional way to write documentation with the implementation in the document is to create a .dtx with the correct setup (of course you could also just use something like \lstinput in a separate document, but the .dtx file allows to have explanations neatly typeset in between the blocks of code, and everything unnecessary is stripped for the production release via docstrip).

Some information about .dtx can be found on Joseph's blog in a posting from 2009 (there are multiple posts about them there). You could also take a look at other packages and how they do things. And it is possible to create both your class and bibliography style from a single .dtx file if you want (though I'm certainly not the best package writer out there, you could for example take a look at the source of my expkv, which creates multiple files from a single .dtx: https://github.com/Skillmon/tex_expkv).

I'd also suggest using the l3build system created by the LaTeX Project team. It allows to write unit tests for your code, and an easy way to install the necessary files locally (just a single call of l3build install will put the files at the right spot for you, provided you set installfiles correctly inside the build.lua configuration). My expkv is using l3build as well, so you can also take a look there.

And I'd suggest putting it on some git server (either something hosted by your institute, one you host yourself, or if that's fine for you something like GitHub or GitLab). This doesn't solve the problem you formulated as

there has to be something better than just checking and redownloading if anyone else updates it

but at least you'll get something one can easily script to get updates (if you put it on CTAN it is only updated if the users update their LaTeX distribution, so while this bundles things on a single spot it still is no automatic solution of its own). One could for example just write a small shell/batch script that fetches the latest changes from the git, runs l3build check (if you set up unit tests), and if that's successful also runs l3build install. Simple minded bash script:

cd "/path/to/local/repository"
git fetch
git pull
l3build check && l3build install

You must log in to answer this question.

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